openclaw system CLI Reference: System Events, Heartbeat, Presence
Reference for the openclaw system CLI command. Covers queueing system events, managing heartbeats, and inspecting presence via Gateway RPC for developers and operators.
Read this when
- You want to enqueue a system event without creating a cron job
- You need to enable or disable heartbeats
- You want to inspect system presence entries
openclaw system
System level helpers for the Gateway: queue system events, manage heartbeats, and inspect presence.
All system subcommands communicate through Gateway RPC and share these client flags:
| Flag | Default | Description |
|---|---|---|
--url <url> | gateway.remote.url when configured | Gateway WebSocket URL. |
--token <token> | none | Gateway token (if required). |
--timeout <ms> | 30000 | RPC timeout in milliseconds. |
--expect-final | off | Wait for final response (agent). |
--json | off | Output JSON. heartbeat last/enable/disable and system presence always print the raw RPC JSON payload regardless of this flag; system event uses it to switch between JSON and a plain ok line. |
Common commands
openclaw system event --text "Check for urgent follow-ups" --mode now
openclaw system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
openclaw system heartbeat enable
openclaw system heartbeat last
openclaw system presence
system event
By default, enqueue a system event on the main session. The next heartbeat inserts it as a System: line in the prompt. Use --mode now to fire the heartbeat right away; next-heartbeat (default) holds off until the next scheduled tick.
Pass --session-key to address a specific session, for example to send an async task result back to the channel that started it.
Note
Timing exception with
--session-key: when--session-keyis given,--mode next-heartbeatbecomes an immediate targeted wake instead of waiting for the next scheduled tick. Targeted wakes use heartbeat intentimmediateso they skip the runner's not-due gate that would otherwise delay (and effectively discard) anevent-intent wake. For delayed delivery, leave out--session-keyso the event goes to the main session and arrives with the next regular heartbeat.
Flags:
--text <text>: required system event text.--mode <mode>:nowornext-heartbeat(default).--session-key <sessionKey>: optional; target a specific agent session instead of the agent's main session. Keys that do not belong to the resolved agent fall back to the agent's main session.
system heartbeat last|enable|disable
last: show the most recent heartbeat event.enable: re enable heartbeats (use this if they were stopped).disable: suspend heartbeats.
system presence
Display the current system presence entries known to the Gateway (nodes, instances, and similar status lines).
Notes
- Requires a running Gateway that your current config (local or remote) can reach.
- System events are ephemeral and do not survive restarts.