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...

Security Scan

The skill's code and instructions match its stated purpose (waking an agent via the gateway) but the registry metadata omits the clearly required gateway credential and there are small mismatches in how the token is located—this inconsistency should be resolved before use.

Purpose & Capability

The SKILL.md and the included script require a gateway auth token (GATEWAY_TOKEN or OPENCLAW_GATEWAY_TOKEN read from ~/.openclaw/gateway.cmd), but the registry metadata lists no required environment variables or credentials. That mismatch is incoherent: a wake tool legitimately needs the gateway token, and the metadata should declare it. Other than that, the requested actions (POST to /tools/invoke on the gateway) align with the stated purpose.

Instruction Scope

The runtime instructions and script are narrowly scoped: they load a local .env (script directory only), optionally read gateway.cmd from ~/.openclaw, and POST a wake event to the local gateway /tools/invoke endpoint. The README instructs enabling the cron tool over HTTP and setting the gateway token. The skill does not instruct reading unrelated system files or transmitting data to third-party endpoints.

Install Mechanism

No install spec; this is an instruction-only skill with a small Python script. Nothing is downloaded or written to disk by an installer. Risk from installation is low.

Credentials

The functionality reasonably requires a gateway auth token, and the SKILL.md declares GATEWAY_TOKEN as required, but the registry metadata omitted it. The script also reads OPENCLAW_GATEWAY_TOKEN from gateway.cmd—this is relevant to the purpose but the lack of declared credentials in the registry is a red flag for packaging/metadata correctness and could lead to accidental misconfiguration or unintended exposure.

Persistence & Privilege

The skill does not request permanent presence, does not set always:true, and does not modify other skills or system-wide settings. It merely invokes the gateway API when executed.

What to consider before installing

The included Python script appears to do exactly what the description says: post a wake event to the local OpenClaw gateway using a gateway auth token. However, the registry metadata incorrectly lists no required credentials while the SKILL.md and script require a GATEWAY_TOKEN (or read OPENCLAW_GATEWAY_TOKEN from ~/.openclaw/gateway.cmd). Before installing or running this: 1) confirm where you should store the gateway token and that the registry metadata is updated; 2) ensure the gateway URL is a trusted, local endpoint (default is http://localhost:18789) and that enabling the cron tool over HTTP is acceptable for your environment; 3) protect the gateway token (do not commit a .env with the token into version control); and 4) if you plan to run this from external or networked environments, consider network-level protections so the gateway cannot be invoked by untrusted actors. If you want to proceed, update the skill/metadata to explicitly declare GATEWAY_TOKEN as a required credential so its needs are clear.

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

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:

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

From any Python script

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

Standalone (wake main session)

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:

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.