From 9d45f4b4e93df523666999d65201c0aa4333b4e4 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 18:54:04 +0100 Subject: [PATCH] docs: refresh gateway health snapshot refs --- docs/cli/health.md | 8 ++++++-- docs/cli/index.md | 9 +++++++-- docs/gateway/health.md | 16 ++++++++++++---- docs/start/openclaw.md | 4 ++-- 4 files changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/cli/health.md b/docs/cli/health.md index 6761c2d6a4a..60085018178 100644 --- a/docs/cli/health.md +++ b/docs/cli/health.md @@ -1,5 +1,5 @@ --- -summary: "CLI reference for `openclaw health` (gateway health endpoint via RPC)" +summary: "CLI reference for `openclaw health` (gateway health snapshot via RPC)" read_when: - You want to quickly check the running Gateway’s health title: "health" @@ -28,5 +28,9 @@ openclaw health --debug Notes: -- `--verbose` runs live probes and prints per-account timings when multiple accounts are configured. +- Default `openclaw health` asks the running gateway for its health snapshot. When the + gateway already has a fresh cached snapshot, it can return that cached payload and + refresh in the background. +- `--verbose` forces a live probe, prints gateway connection details, and expands the + human-readable output across all configured accounts and agents. - Output includes per-agent session stores when multiple agents are configured. diff --git a/docs/cli/index.md b/docs/cli/index.md index 85bddcf8824..7ccd2cd12f8 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1203,7 +1203,7 @@ Options: - `--json` - `--all` (full diagnosis; read-only, pasteable) -- `--deep` (probe channels) +- `--deep` (ask the gateway for a live health probe, including channel probes when supported) - `--usage` (show model provider usage/quota) - `--timeout ` - `--verbose` @@ -1241,9 +1241,14 @@ Options: - `--json` - `--timeout ` -- `--verbose` +- `--verbose` (force a live probe and print gateway connection details) - `--debug` (alias for `--verbose`) +Notes: + +- Default `health` can return a fresh cached gateway snapshot. +- `health --verbose` forces a live probe and expands human-readable output across all configured accounts and agents. + ### `sessions` List stored conversation sessions. diff --git a/docs/gateway/health.md b/docs/gateway/health.md index a25b2a8144d..bd8785c88d8 100644 --- a/docs/gateway/health.md +++ b/docs/gateway/health.md @@ -14,8 +14,10 @@ Short guide to verify channel connectivity without guessing. - `openclaw status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity. - `openclaw status --all` — full local diagnosis (read-only, color, safe to paste for debugging). -- `openclaw status --deep` — also probes the running Gateway (per-channel probes when supported). -- `openclaw health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket). +- `openclaw status --deep` — asks the running gateway for a live health probe (`health` with `probe:true`), including per-account channel probes when supported. +- `openclaw health` — asks the running gateway for its health snapshot (WS-only; no direct channel sockets from the CLI). +- `openclaw health --verbose` — forces a live health probe and prints gateway connection details. +- `openclaw health --json` — machine-readable health snapshot output. - Send `/status` as a standalone message in WhatsApp/WebChat to get a status reply without invoking the agent. - Logs: tail `/tmp/openclaw/openclaw-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`. @@ -42,12 +44,18 @@ Short guide to verify channel connectivity without guessing. ## Dedicated "health" command -`openclaw health --json` asks the running Gateway for its health snapshot (no direct channel sockets from the CLI). It reports linked creds/auth age when available, per-channel probe summaries, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. +`openclaw health` asks the running gateway for its health snapshot (no direct channel +sockets from the CLI). By default it can return a fresh cached gateway snapshot; the +gateway then refreshes that cache in the background. `openclaw health --verbose` forces +a live probe instead. The command reports linked creds/auth age when available, +per-channel probe summaries, session-store summary, and a probe duration. It exits +non-zero if the gateway is unreachable or the probe fails/timeouts. Options: - `--json`: machine-readable JSON output - `--timeout `: override the default 10s probe timeout -- `--probe`: force a live probe of all channels instead of returning the cached health snapshot +- `--verbose`: force a live probe and print gateway connection details +- `--debug`: alias for `--verbose` The health snapshot includes: `ok` (boolean), `ts` (timestamp), `durationMs` (probe time), per-channel status, agent availability, and session-store summary. diff --git a/docs/start/openclaw.md b/docs/start/openclaw.md index 5d0b3fc753e..5bb40c488b4 100644 --- a/docs/start/openclaw.md +++ b/docs/start/openclaw.md @@ -206,8 +206,8 @@ That means generated images/files outside the workspace can now send when your f ```bash openclaw status # local status (creds, sessions, queued events) openclaw status --all # full diagnosis (read-only, pasteable) -openclaw status --deep # adds gateway health probes (WhatsApp Web + Telegram + Discord + Slack + Signal) -openclaw health --json # gateway health snapshot (WS) +openclaw status --deep # asks the gateway for a live health probe with channel probes when supported +openclaw health --json # gateway health snapshot (WS; default can return a fresh cached snapshot) ``` Logs live under `/tmp/openclaw/` (default: `openclaw-YYYY-MM-DD.log`).