openclaw system CLI Reference: Events, Heartbeat, Presence
This page covers the openclaw system CLI commands for enqueuing system events, controlling heartbeats, and inspecting presence via Gateway RPC. It is intended for developers managing gateway communication.
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
Gateway system helpers let you enqueue system events, control heartbeats, and inspect presence.
All system subcommands communicate through Gateway RPC and support the shared 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, a system event is enqueued on the main session. The next heartbeat inserts it as a System: line into the prompt. Use --mode now to force an immediate heartbeat; next-heartbeat (default) waits for the next regularly scheduled tick.
Pass --session-key to send the event to a particular session, for instance to notify the originating channel that an async task has completed.
Note
Timing exception with
--session-key: when--session-keyis provided,--mode next-heartbeatbecomes an immediate targeted wake rather than deferring to the next scheduled tick. Targeted wakes use heartbeat intentimmediateand therefore bypass the runner's not-due gate, which would otherwise postpone (and effectively lose) a wake witheventintent. To delay delivery, leave out--session-keyso the event goes to the main session and travels with the next regular heartbeat.
Flags:
--text <text>: system event text (required).--mode <mode>:nowornext-heartbeat(default).--session-key <sessionKey>: optional; targets 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: display the most recent heartbeat event.enable: resume heartbeats after they were stopped.disable: halt heartbeats.
system presence
Show all current system presence entries the Gateway tracks (nodes, instances, and similar status lines).
Notes
- A running Gateway must be accessible through your current configuration (local or remote).
- System events are transient and do not survive restarts.