> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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)