Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Docs: Wakeup Script Best Practices — Avoid Silent Agent Wake Failures [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#48869•Fetched 2026-04-08 00:51:41
View on GitHub
Comments
1
Participants
2
Timeline
3
Reactions
0
Author
hhdnxxhhdnxx
Participants
hhdnxxhhdnxxRyceRyce
Timeline (top)
commented ×1cross-referenced ×1referenced ×1

This issue proposes adding documentation for wakeup script patterns to prevent silent agent wake failures. The common pitfall: scripts create inbox files but don't trigger the agent session, leading to unprocessed tasks.

Root Cause

The agent doesn't automatically poll the inbox directory. It needs an explicit trigger to wake up and process new files.

Fix Action

Fixed

PR fix notes

PR #48901: docs: add wakeup script best practices guide

Description (problem / solution / changelog)

Summary

Adds a new documentation page at docs/automation/wakeup-scripts.md covering best practices for wakeup scripts — specifically how to avoid the common pitfall of creating task files without triggering the agent.

What's Included

  • The Problem: Why dropping files in an inbox directory doesn't wake the agent
  • Four Solution Patterns:
    1. openclaw wake — immediate wake signal (recommended for urgent tasks)
    2. Cron job — scheduled inbox checks in isolated sessions
    3. System event — programmatic one-shot triggers
    4. Heartbeat integration — low-latency polling via HEARTBEAT.md
  • Comparison Table: Latency, complexity, and best-use for each approach
  • Verification Steps: How to confirm the agent actually processed the task
  • Common Mistakes: Troubleshooting table for frequent issues
  • Full Working Example: A daily report script with proper wake integration

Motivation

As described in #48869, many users write wakeup scripts that create inbox files but forget to trigger the agent session. This leads to silent failures where scripts appear to work but tasks are never processed.

This page fills a gap in the existing automation docs (which cover cron, heartbeat, hooks, and webhooks but not the file-creation + wake pattern).

Related

First-time contributor — happy to address any feedback! 🐾

Changed files

  • docs/automation/wakeup-scripts.md (added, +221/-0)

Code Example

#!/bin/bash
# ❌ Problem: Only creates file, doesn't wake agent

REMINDER_FILE="$INBOX_DIR/task-reminder-$(date +%Y%m%d-%H%M).md"

cat > "$REMINDER_FILE" << EOF
# Task Reminder
...task details...
EOF

echo "Wake complete" >> "$LOG_FILE"
# Missing: No agent trigger!

---

#!/bin/bash
# ✅ Fixed: Create file + trigger agent

REMINDER_FILE="$INBOX_DIR/task-reminder-$(date +%Y%m%d-%H%M).md"

# Step 1: Create reminder file
cat > "$REMINDER_FILE" << EOF
# Task Reminder
...task details...
EOF

# Step 2: Trigger agent session to process inbox
openclaw agent --agent <agent_id> --message "Check inbox and process tasks" >> "$LOG_FILE" 2>&1

echo "Wake complete (agent triggered)" >> "$LOG_FILE"

---

{
  "agentId": "<agent_id>",
  "schedule": {"kind": "cron", "expr": "*/30 * * * *"},
  "payload": {"message": "Check inbox and D+A"}
}

---

openclaw system event --mode now --text "Check inbox"
RAW_BUFFERClick to expand / collapse

Summary

This issue proposes adding documentation for wakeup script patterns to prevent silent agent wake failures. The common pitfall: scripts create inbox files but don't trigger the agent session, leading to unprocessed tasks.

Problem Pattern

Many users create wakeup scripts like this:

#!/bin/bash
# ❌ Problem: Only creates file, doesn't wake agent

REMINDER_FILE="$INBOX_DIR/task-reminder-$(date +%Y%m%d-%H%M).md"

cat > "$REMINDER_FILE" << EOF
# Task Reminder
...task details...
EOF

echo "Wake complete" >> "$LOG_FILE"
# Missing: No agent trigger!

Result: The script runs successfully, but the agent never checks the inbox. Files accumulate unprocessed.

Root Cause

The agent doesn't automatically poll the inbox directory. It needs an explicit trigger to wake up and process new files.

Solution Pattern

#!/bin/bash
# ✅ Fixed: Create file + trigger agent

REMINDER_FILE="$INBOX_DIR/task-reminder-$(date +%Y%m%d-%H%M).md"

# Step 1: Create reminder file
cat > "$REMINDER_FILE" << EOF
# Task Reminder
...task details...
EOF

# Step 2: Trigger agent session to process inbox
openclaw agent --agent <agent_id> --message "Check inbox and process tasks" >> "$LOG_FILE" 2>&1

echo "Wake complete (agent triggered)" >> "$LOG_FILE"

Alternative Approaches

Option A: Cron-based HEARTBEAT

Configure agent HEARTBEAT with Cron to poll inbox periodically:

{
  "agentId": "<agent_id>",
  "schedule": {"kind": "cron", "expr": "*/30 * * * *"},
  "payload": {"message": "Check inbox and D+A"}
}

Option B: System Event

Use openclaw system event for programmatic wake:

openclaw system event --mode now --text "Check inbox"

Proposed Documentation

Add a new page: docs/automation/wakeup-scripts.md

Sections:

  1. Common pitfall (file created, agent not triggered)
  2. Correct pattern (create + trigger)
  3. Alternative approaches (Cron, system event)
  4. Verification (check logs for agent response)
  5. Examples (3-5 common wakeup script templates)

Impact

This documentation would help users avoid:

  • Silent task failures
  • Accumulated unprocessed inbox files
  • Confusion about why scripts "work" but tasks don't get done

Related Issues

  • #39365 - Document openclaw system event as programmatic agent wake
  • #29523 - session:idle hook for automatic memory flush
  • #39885 - Native session memory/persistence

Happy to contribute a draft PR if this is helpful! 🙏

extent analysis

Fix Plan

To fix the issue of silent agent wake failures, follow these steps:

  • Modify existing wakeup scripts to include an explicit agent trigger.
  • Use one of the alternative approaches: Cron-based HEARTBEAT or system event.

Code Changes

Modify your wakeup script to include the agent trigger:

#!/bin/bash
REMINDER_FILE="$INBOX_DIR/task-reminder-$(date +%Y%m%d-%H%M).md"

# Create reminder file
cat > "$REMINDER_FILE" << EOF
# Task Reminder
...task details...
EOF

# Trigger agent session to process inbox
openclaw agent --agent <agent_id> --message "Check inbox and process tasks" >> "$LOG_FILE" 2>&1

echo "Wake complete (agent triggered)" >> "$LOG_FILE"

Alternatively, use Cron-based HEARTBEAT:

{
  "agentId": "<agent_id>",
  "schedule": {"kind": "cron", "expr": "*/30 * * * *"},
  "payload": {"message": "Check inbox and D+A"}
}

Or use openclaw system event for programmatic wake:

openclaw system event --mode now --text "Check inbox"

Verification

Check the logs for the agent response to verify that the fix worked. Look for the "Wake complete (agent triggered)" message in the log file.

Extra Tips

  • Make sure to replace <agent_id> with the actual ID of your agent.
  • Test your modified wakeup script to ensure it works as expected.
  • Consider adding error handling to your script to handle cases where the agent trigger fails.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error#cache issue#memory leak#API versioning#request timeout

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix Docs: Wakeup Script Best Practices — Avoid Silent Agent Wake Failures [1 pull requests, 1 comments, 2 participants]