vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-11-06 16:26:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 23
openclaw/docs/cli/system.md
Alix-007 241614b59c
fix(cli): pending system and skill reads outlive interruption (#187504) 
fix(cli): stop accepted CLI reads on Ctrl-C and SIGTERM

Four CLI commands that read from the Gateway over RPC or HTTP after the request was accepted didn't pass the command's interrupt signal to their read adapters. After SIGINT or SIGTERM they stayed pending and printed late results. The RPC and HTTP read adapters now take the existing invocation signal, so the reads stop and the command exits with 130 or 143 and nothing late. Mutations that were already accepted keep their existing lifetime and settlement. This includes the fix from #187512.

Evidence: built CLI against synthetic peers, 19 cases per ref. On main, all four reads stayed pending after SIGINT or SIGTERM and printed late results (twice); with this change they exited 130 or 143 before release with empty stdout (twice). Normal results and errors, and accepted event and heartbeat receipts, behave the same on both refs. Details: https://github.com/openclaw/openclaw/pull/187504#issuecomment-6493534056.

Thanks @Alix-007.

Co-authored-by: Ayaan Zaidi <hi@obviy.us>
2026-10-29 15:49:31 +05:30

5.9 KiB
Raw Permalink Blame History

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 the compatibility controls for migrated heartbeat jobs
You want to inspect system presence entries
System

openclaw system

System-level helpers for the Gateway: enqueue system events, control migrated monitor jobs through legacy interfaces, 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.
--port <port> none Local Gateway port.
--token <token> none Gateway token (if required).
--password <password> none Gateway password (if required).
--timeout <ms> 30000 RPC timeout in milliseconds.
--expect-final off Accepted as a shared client flag, but has no effect on system commands.
--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

Use --mode now to submit a system event to ordinary session execution. It targets the main session by default and waits behind existing work. The legacy default mode, next-heartbeat, attaches the event to a suitable scheduled automation for that session; it reports an error if no eligible job exists. Use an explicit automation schedule when you need delayed work.

The command returns when the Gateway accepts the event, not when execution or delivery finishes. --expect-final does not wait for an agent response.

Pass --session-key to target a specific session, for example to relay an async-task completion back to the channel that started it. Prefer an agent-qualified key. For example, if the ops agent is configured:

openclaw system event --text "Deploy finished" --session-key agent:ops:main --mode now

A targeted event stays with the selected session. Events assigned to another session or a scheduled job stay with their own execution owner.

**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. Prefer `--mode now` to state that intent explicitly. Create an automation when you want delayed delivery.

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. The Gateway rejects malformed agent-qualified keys, keys for unknown agents, targets that conflict with the caller's agent scope, and subagent sessions. Rejected targets do not fall back to the main session.

system heartbeat last|enable|disable

  • last: show the last compatibility heartbeat event.
  • enable: enable the migrated/default proactive jobs recorded by setup or Doctor.
  • disable: disable those jobs.

These compatibility controls do not affect unrelated automations and do not recreate deleted jobs. If no converted/default job remains, use ordinary openclaw automations commands or run Doctor to finish a pending migration.

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.
  • Ctrl-C or SIGTERM cancels a pending system presence or system heartbeat last query without printing a late response. The CLI exits with status 130 or 143. System events and heartbeat changes already sent to the Gateway keep waiting for their acceptance receipt during cleanup.

Related