openclaw/docs/cli/status.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "CLI reference for `openclaw status` (diagnostics, checks, usage snapshots)"
read_when:
  - You want a quick diagnosis of channel health + recent session recipients
  - You want a pasteable "all" status for debugging
title: "openclaw status"
---

Diagnostics for channels + sessions.

Task counts and audit totals use a read-only metadata summary. Retained task
payloads and delivery history are not loaded for each status request, and
overlapping requests share the pending summary read. Database work runs on the
shared SQLite worker; live task ownership is still checked by the Gateway.
These summaries are not a full physical database-integrity check. Full registry
restoration and Doctor retain their integrity verification.

```bash
openclaw status
openclaw status --all
openclaw status --deep
openclaw status --usage
openclaw status --all --usage
openclaw status --usage --agent work
```

| Flag                    | Description                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--all`                 | Full diagnosis (read-only, pasteable). Includes security audit, plugin compatibility, and memory-vector checks. |
| `--deep`                | Requests channel health (live checks where supported). Also enables the security audit.                         |
| `--usage`               | Prints normalized provider usage windows as `X% left`.                                                          |
| `--agent <id>`          | Selects the agent auth/profile scope for `--usage`. Required when an explicit multi-agent fleet has no default. |
| `--json`                | Machine-readable output.                                                                                        |
| `--timeout <ms>`        | Check timeout in milliseconds (default: `60000`).                                                               |
| `--verbose` / `--debug` | Also print the raw Gateway target resolution before the report.                                                 |

Status starts one monotonic check deadline when the command begins. Local readiness, Gateway status, provider usage, and deep health consume the remaining allowance. Remote targets and explicit Gateway URLs skip local readiness but keep the same deadline. Local checks report the observed startup phase while waiting. If the Gateway is still starting when the budget expires, status reports “still starting” instead of unreachable and skips deep channel checks. JSON keeps the status report and adds `gateway.readiness: "still-starting"` and `gateway.startupPhase`. An explicit `--timeout` limits that shared allowance.

When no matching Gateway service or live foreground owner exists and its port is
free, status checks directly instead of waiting for a Gateway startup. Local-only
agent environments therefore report an unavailable Gateway promptly. Observed startup
migrations retain startup grace across the handoff to Gateway ownership; unverifiable
ownership also retains that grace. Lock and native process inspection consume the
same remaining check allowance.

Channels without a check, such as WhatsApp, report lifecycle health instead.
In the Health table, `healthy` is `OK`; degraded lifecycle states and failed
checks remain `WARN`. A lifecycle `OK` does not mean a live check ran.

The Update run row preserves the last recorded update outcome. When the local
Gateway passes the current readiness and connection checks and its serving
version matches the recorded update target, a previous failure is labeled as
historical: `Last update run failed (post-update-failed) — Gateway is serving
2026.9.7; run openclaw update to clear the record.` Build IDs must also match when
both the target and the live check expose them. A healthy old version, a different
build, or unknown identity keeps the warning and its recorded failure details,
with the serving and target versions when known. Rollback and recovery observations
cannot by themselves establish the intended candidate identity. A
same-version rollback stays warned when the intended candidate build cannot be
verified. A failed run that never selected a target, such as a preflight refusal
that recorded no target version, SHA, tag, or post-update identity, is also
labeled as historical once the Gateway serves a different version or build than
the running Gateway observation saved with that failure: `Last update run failed
(preflight-no-good-commit) — Gateway is now serving 2026.10.1; recorded serving
identity was 2026.9.4.` The installed package identity alone cannot establish this
change: it may already have been ahead of the running Gateway when the update
failed. A recovery check matching the old installed package does not establish
an update target. Without a saved serving identity, the warning remains. A run with an
explicit target keeps the rules above.
Status does not rewrite the failed run or claim the update succeeded.
Starting, unreachable, degraded, and
remote Gateways do not qualify for this note. Use
`openclaw update status` to inspect the saved verification failure.

`--deep` also asks the running Gateway whether the Node executable it still holds can be started. A Homebrew upgrade can delete that Cellar path while the LaunchAgent plist still points at a valid symlink and the Gateway port stays reachable. Status then warns:

```text
Gateway runtime is stale after Node upgrade: child workers are using <path>, which no longer exists. Restart the Gateway.
```

The check does not restart the Gateway. Run `openclaw gateway restart` after the warning.
Exec and stdio MCP command relays can use the stable Homebrew Node path when the
old executable is gone. Workers that require the Gateway's exact runtime still
need a restart; a failed supervisor or broker launch reports the same warning.

`--deep` and `--all` also show delivery queue warnings for dead-lettered messages
and pressured inbound lanes. These warnings include pending, claimed, and blocked
message counts even when a channel connection is healthy. See
[Queue warnings](/gateway/health#queue-warnings).

Plain `openclaw status` stays on the fast read-only path and marks memory as
`not checked` instead of unavailable when it skips memory inspection. Heavy
security audit, plugin compatibility, and memory-vector checks are left to
`openclaw status --all`, `openclaw status --deep`, `openclaw security audit`,
and `openclaw memory status --deep`.

Local agent ownership checks read schema and owner metadata from one consistent
SQLite snapshot, including committed WAL changes. They do not copy the entire
agent database unless its journal state requires private recovery. Startup and
migration readiness checks retain their full validation.

The CLI runs in a separate process and contacts the Gateway over WebSocket, even
for a local loopback target. `--timeout` bounds checks, not the entire status
command. Cold device-token worker initialization happens during request preparation,
before the RPC timeout starts; connection token reads remain fresh. Compare
`openclaw gateway call status --json` with `openclaw status --json`
to separate the Gateway response from local report collection. Gateway
[Prometheus RPC timings](/gateway/prometheus) exclude CLI startup and connection
setup; a slow CLI can finish without a slow Gateway handler.

When the Gateway is reachable and authorized, `status --json` uses its status
projection instead of scanning every agent's plugin metadata and database
ownership locally. The Gateway supplies session counts, heartbeat and task
state, runtime vitals, and agent roster facts. The request keeps `operator.read`
scope, including its redaction of session paths, recent sessions, model defaults,
and detailed admission refusals. After the Gateway hydrates a physical session
store, clean repeated status reads reuse its resident materialized session rows;
only topology changes and dirty or missing exact identities return to the
existing read-only SQLite path.

JSON `collection.notCollected` names fields that were not inspected and explains
why. Online status leaves workspace and bootstrap checks unknown, including
`agents.bootstrapPendingCount: null`. It returns `channelSummary: []` without
loading channel plugins and records `channelSummary` in `collection.notCollected`.
An empty list there means the field was not collected, not that no channels are
configured. Use `openclaw channels status` for the configured inventory, or
`openclaw channels status --probe` for live account checks. Online status skips
local config validation, channel and memory credential inspection, and the local
plugin inspections normally requested by `--all` or `--deep`. Requested security
audit and plugin compatibility sections report `collected: false`; memory remains
`null`. Use
`openclaw security audit`, `openclaw plugins inspect --all`, or
`openclaw memory status --deep` for those local inspections. `--deep` still requests
Gateway health, and `--usage --agent <id>` retains its credential scope.
When the Gateway is unavailable, JSON status retains local diagnostics.

For Git installs, plain status compares cached remote-tracking refs without a
network fetch. If the latest recorded update fetch failed and no later update
run records a completed fetch, the Update row shows
`update check stale: last update fetch failed 5m ago (network error)` instead of
`up to date`, with ahead/behind counts labeled `cached`. JSON exposes this under
`update.git.stale` (`reason`, `failedAtMs`, `detail`, and `runId`) and sets
`update.git.countsCached` to `true`. Without a recorded fetch failure, the usual
cached comparison is unchanged. The history belongs to the current state
directory. A later run that completes its fetch clears the warning even if the
rest of that update is skipped, fails, or rolls back. A manual `git fetch` does
not clear the recorded warning. Use `openclaw update status` for a fresh check
and the last update run, or run `openclaw update` again. `openclaw status --deep`
also fetches for that check; it does not change the ledger. See
[Release channels](/install/development-channels#checking-current-status).

## Status timing

Use the existing diagnostic timeline to locate time spent outside Gateway RPCs:

```bash
OPENCLAW_DIAGNOSTICS=timeline \
OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-status-timeline.jsonl \
  openclaw status --json
```

The timeline includes configuration and secret resolution, agent admission,
local session reads, Gateway checks, and summary collection. Durations include
waiting; parallel stages overlap and should not be added together.

## Skills diagnosis

`status --all` reports eligible skills and skills with missing prerequisites for
the workspace shown in the Skills row. Missing prerequisites use the same category as
`openclaw skills check`: intentionally disabled skills and skills blocked by the
bundled allowlist are excluded; agent allowlist exclusions remain independent.
Unmet OS requirements are included in this count, although Doctor does not disable
skills for OS incompatibility.
Use `openclaw skills check --agent <id>` to inspect the missing requirements.

## Session and model resolution

- Session status output separates `Execution:` from `Runtime:`. `Execution`
  is the sandbox path (`direct`, `docker/*`), while `Runtime` tells you
  whether the session is using `OpenClaw Default`, `OpenAI Codex`, a CLI
  backend, or an ACP backend such as `codex (acp/acpx)`. See
  [Agent runtimes](/concepts/agent-runtimes) for the provider/model/runtime
  distinction.
- The `/status` chat command shows `Endpoint`: the upstream base URL
  from the same prepared model/auth decision used to select the route. It
  describes the current selection, not a previous request or billing attribution.
  The URL is the API base; the transport adds operation paths such as
  `/responses` when sending requests.
  Routes without a resolved endpoint display `unknown`. Displayed URLs omit
  user information, query parameters, and fragments; custom paths are hidden.
- When the current session snapshot is sparse, the `/status` chat command (see
  [Slash commands](/tools/slash-commands)) can backfill token and cache counters
  from the most recent transcript usage log. Existing nonzero live values still
  win over transcript fallback values.
- Transcript fallback can also recover the active runtime model label when
  the live session entry is missing it. If that transcript model differs
  from the selected model, status resolves the context window against the
  recovered runtime model instead of the selected one.
- For prompt-size accounting, transcript fallback prefers the larger
  prompt-oriented total when session metadata is missing or smaller, so
  custom-provider sessions do not collapse to `0` token displays.
- When a session is pinned to a model that differs from the configured
  primary, status prints both values, the reason (`session override`), and
  the hint `/model default`. The configured primary applies to new or
  unpinned sessions; existing pinned sessions keep their session selection
  until cleared.
- Output includes per-agent session stores when multiple agents are
  configured.
- Fleet status works without a System Agent owner. Pending events include each
  agent's main queue; a shared global queue is counted once. `--agent` selects
  credentials only for `--usage`.

## Usage and quota

- `--usage` prints normalized provider usage windows as `X% left`.
  It also adds usage snapshots to `--all`; `--agent` keeps the same usage-only scope.
  Usage checks receive the remaining shared check budget, capped by `--timeout` when set;
  providers that exceed that bound report `Timeout` in the usage output.
  An exhausted budget reports `Timeout` without starting provider auth or usage
  requests. Expiry cancels active usage requests and prevents late auth results
  from starting another request; completed provider snapshots remain available.
- In an explicit multi-agent setup, `--usage` reads the auth profiles owned by
  `agents.defaults.systemAgent.agentId` by default. Pass `--agent <id>` to
  inspect another agent; without either owner, OpenClaw does not guess one
  agent's credentials from an ambiguous roster.
- MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota,
  so OpenClaw inverts them before display; count-based fields win when
  present. `model_remains` responses prefer the chat-model entry, derive the
  window label from timestamps when needed, and include the model name in
  the plan label.
- Model pricing refresh failures are shown as optional pricing warnings.
  They do not mean the Gateway or channels are unhealthy.

## Overview and update status

The Gateway service row compares its installed package with the active CLI.
If they resolve to different installations, status names both package paths and
versions. It recommends `openclaw doctor --fix` or `openclaw gateway install --force`
when service installation is allowed, or reports the installation owner's refusal.
This local diagnostic remains available when the Gateway connection fails,
including a protocol mismatch. JSON exposes the comparison as
`gatewayService.installationDrift`.
If local session state requires Doctor, status prints any installation drift to stderr alongside the original error and preserves the failure exit status.

- The **Sessions** overview counts stored conversation rows, including archived
  rows. Running turns and recent activity are separate from this inventory.
- Overview includes Gateway + node host service install/runtime status when
  available, plus compact Gateway process uptime and host system uptime.
- `status --all` shows returned host, IP, version, and platform in **Gateway self**.
  It uses `unknown` only when those fields are unavailable.
- On Linux, a readable installed node service remains listed when the service
  manager is unavailable; its runtime status stays unknown.
- Overview includes update channel + git SHA (for source checkouts).
- Update info surfaces in the Overview; if an update is available, status
  prints a hint to run `openclaw update` (see [Updating](/install/updating)).
- `status` and `status --all` keep current availability in **Update** and show
  active or recent update history separately in **Update run**. A distinct
  **Update restart** report remains visible unless it names that same run ID.
- `status --all` includes a **Telemetry exporters** diagnosis with the latest
  trusted per-signal exporter state and transport. Endpoint values, headers,
  certificates, payloads, and raw errors are not shown.

## Secrets

- When the running Gateway has any isolated SecretRef owner from startup, reload, or a config write, status includes `degradedSecretOwners` in JSON and a **Degraded secrets** overview row in human output. Each entry names the owner, degradation state (`cold` or `stale`), config paths, and redacted reason. Cold owners are unavailable; stale owners continue with last-known-good values.
- Read-only status surfaces (`status`, `status --json`, `status --all`)
  resolve supported SecretRefs for their targeted config paths when
  possible.
- If a supported channel SecretRef is configured but unavailable in the
  current command path, status stays read-only and reports degraded output
  instead of crashing. Human output shows warnings such as "configured token
  unavailable in this command path", and JSON output includes
  `secretDiagnostics`.
- When command-local SecretRef resolution succeeds, status prefers the
  resolved snapshot and clears transient "secret unavailable" channel
  markers from the final output.
- `status --all` includes a Secrets overview row and a diagnosis section
  that summarizes secret diagnostics (truncated for readability) without
  stopping report generation.

## Memory

`status --json --all` reports memory details from the active memory plugin
runtime selected by `plugins.slots.memory`. Custom memory plugins can leave
built-in `memory.search.enabled` disabled and still report
their own files, chunks, vector, and FTS state.

## Related

- [CLI reference](/cli)
- [Doctor](/gateway/doctor)
- [`openclaw health`](/cli/health) — Gateway health snapshot over RPC