adolf/docs/cli/system.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw system` (system events, heartbeat, presence)	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	System

openclaw system

System-level helpers for the Gateway: enqueue system events, control heartbeats, and view presence.

All system subcommands use Gateway RPC and accept 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

Enqueue a system event on the main session by default. The next heartbeat injects it as a System: line in the prompt. Use --mode now to trigger the heartbeat immediately; next-heartbeat (default) waits for the next scheduled tick.

Pass --session-key to target a specific session, for example to relay an async-task completion back to the channel that started it.

**Timing exception with `--session-key`:** when `--session-key` is supplied, `--mode next-heartbeat` collapses to an immediate targeted wake instead of waiting for the next scheduled tick. Targeted wakes use heartbeat intent `immediate` so they bypass the runner's not-due gate that would otherwise defer (and effectively drop) an `event`-intent wake. If you want delayed delivery, omit `--session-key` so the event lands on the main session and rides the next regular heartbeat.

Flags:

• --text <text>: required system event text.
• --mode <mode>: now or next-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 last heartbeat event.
• enable: turn heartbeats back on (use this if they were disabled).
• disable: pause heartbeats.

system presence

List the current system presence entries the Gateway knows about (nodes, instances, and similar status lines).

Notes

• Requires a running Gateway reachable by your current config (local or remote).
• System events are ephemeral and not persisted across restarts.

Related

• CLI reference