mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-08 22:13:59 +00:00
f7d7148cf0
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
83 lines
4.2 KiB
Markdown
83 lines
4.2 KiB
Markdown
---
|
|
summary: "CLI reference for `openclaw system` (system events, heartbeat, presence)"
|
|
read_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
|
|
title: "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
|
|
|
|
```bash
|
|
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.
|
|
|
|
<Note>
|
|
**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.
|
|
</Note>
|
|
|
|
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](/cli)
|