agent-wake

Wake an OpenClaw agent session from an external script or process. Use when a background task (Claude Code CLI, cron job, webhook, price alert, or any script) finishes and you want the agent to automatically receive a notification and respond in the correct Discord channel without manual prompting. Solves the problem of agents not knowing when async work completes.

Wake your OpenClaw agent from any external process using the gateway HTTP API.

How it works

scripts/agent-wake.py calls POST /tools/invoke with the cron tool, firing a wake event into the agent's session. The agent receives the event text as a system message and responds immediately in the correct channel.

Quick start

bash

python agent-wake.py "Task finished -- brief summary" "YOUR_DISCORD_CHANNEL_ID"

Setup (one-time)

See references/setup.md for:

• Enabling the cron tool over HTTP (required -- blocked by default)
• Setting GATEWAY_TOKEN
• Finding your Discord channel ID

Usage patterns

End of a Claude Code CLI task

Add to the task prompt:

text

When done, run: python "/path/to/agent-wake.py" "Task done -- summary here" "CHANNEL_ID"

From any Python script

python

import subprocess
subprocess.run([
    "python", "/path/to/agent-wake.py",
    "Price alert triggered -- AAPL crossed $200",
    "1475232925724315740"
])

Standalone (wake main session)

bash

python agent-wake.py "Backup completed successfully"

Omit channel ID to wake the main session (response goes to default channel).

What the agent receives

The event text is injected as a system message. Be specific -- the agent acts on what you write:

text

Build finished -- 3 errors fixed, tests passing. Send your response to Discord channel 1475232925724315740...

Script location

scripts/agent-wake.py -- copy this wherever your tasks run. No dependencies beyond Python stdlib.