docs: refresh gateway health snapshot refs

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.

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 <ms>`
 - `--verbose`
@@ -1241,9 +1241,14 @@ Options:
 
 - `--json`
 - `--timeout <ms>`
-- `--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.

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 <ms>`: 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.

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`).