Health checks

Short guide to verify channel connectivity without guessing.

Quick checks

• text

  Copy

  openclaw status
  — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
• text

  Copy

  openclaw status --all
  — full local diagnosis (read-only, color, safe to paste for debugging).
• text

  Copy

  openclaw status --deep
  — asks the running gateway for a live health probe (
  text

  Copy

  health
  with
  text

  Copy

  probe:true
  ), including per-account channel probes when supported.
• text

  Copy

  openclaw health
  — asks the running gateway for its health snapshot (WS-only; no direct channel sockets from the CLI).
• text

  Copy

  openclaw health --verbose
  — forces a live health probe and prints gateway connection details.
• text

  Copy

  openclaw health --json
  — machine-readable health snapshot output.
• Send
  text

  Copy

  /status
  as a standalone message in WhatsApp/WebChat to get a status reply without invoking the agent.
• Logs: tail
  text

  Copy

  /tmp/openclaw/openclaw-*.log
  and filter for
  text

  Copy

  web-heartbeat
  ,
  text

  Copy

  web-reconnect
  ,
  text

  Copy

  web-auto-reply
  ,
  text

  Copy

  web-inbound
  .

Deep diagnostics

• Creds on disk:
  text

  Copy

  ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  (mtime should be recent).
• Session store:
  text

  Copy

  ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json
  (path can be overridden in config). Count and recent recipients are surfaced via
  text

  Copy

  status
  .
• Relink flow:
  text

  Copy

  openclaw channels logout && openclaw channels login --verbose
  when status codes 409–515 or
  text

  Copy

  loggedOut
  appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
• Diagnostics are enabled by default. The gateway records operational facts unless
  text

  Copy

  diagnostics.enabled: false
  is set. Memory events record RSS/heap byte counts, threshold pressure, and growth pressure. Liveness warnings record event-loop delay, event-loop utilization, CPU-core ratio, and active/waiting/queued session counts when the process is running but saturated. Oversized-payload events record what was rejected, truncated, or chunked, plus sizes and limits when available. They do not record the message text, attachment contents, webhook body, raw request or response body, tokens, cookies, or secret values. The same heartbeat starts the bounded stability recorder, which is available through
  text

  Copy

  openclaw gateway stability
  or the
  text

  Copy

  diagnostics.stability
  Gateway RPC. Fatal Gateway exits, shutdown timeouts, and restart startup failures persist the latest recorder snapshot under
  text

  Copy

  ~/.openclaw/logs/stability/
  when events exist; inspect the newest saved bundle with
  text

  Copy

  openclaw gateway stability --bundle latest
  .
• For bug reports, run
  text

  Copy

  openclaw gateway diagnostics export
  and attach the generated zip. The export combines a Markdown summary, the newest stability bundle, sanitized log metadata, sanitized Gateway status/health snapshots, and config shape. It is meant to be shared: chat text, webhook bodies, tool outputs, credentials, cookies, account/message identifiers, and secret values are omitted or redacted. See Diagnostics Export.

Health monitor config

• text

  Copy

  gateway.channelHealthCheckMinutes
  : how often the gateway checks channel health. Default:
  text

  Copy

  5
  . Set
  text

  Copy

  0
  to disable health-monitor restarts globally.
• text

  Copy

  gateway.channelStaleEventThresholdMinutes
  : how long a connected channel can stay idle before the health monitor treats it as stale and restarts it. Default:
  text

  Copy

  30
  . Keep this greater than or equal to
  text

  Copy

  gateway.channelHealthCheckMinutes
  .
• text

  Copy

  gateway.channelMaxRestartsPerHour
  : rolling one-hour cap for health-monitor restarts per channel/account. Default:
  text

  Copy

  10
  .
• text

  Copy

  channels.<provider>.healthMonitor.enabled
  : disable health-monitor restarts for a specific channel while leaving global monitoring enabled.
• text

  Copy

  channels.<provider>.accounts.<accountId>.healthMonitor.enabled
  : multi-account override that wins over the channel-level setting.
• These per-channel overrides apply to the built-in channel monitors that expose them today: Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, and WhatsApp.

When something fails

• text

  Copy

  logged out
  or status 409–515 → relink with
  text

  Copy

  openclaw channels logout
  then
  text

  Copy

  openclaw channels login
  .
• Gateway unreachable → start it:
  text

  Copy

  openclaw gateway --port 18789
  (use
  text

  Copy

  --force
  if the port is busy).
• No inbound messages → confirm linked phone is online and the sender is allowed (
  text

  Copy

  channels.whatsapp.allowFrom
  ); for group chats, ensure allowlist + mention rules match (
  text

  Copy

  channels.whatsapp.groups
  ,
  text

  Copy

  agents.list[].groupChat.mentionPatterns
  ).

Dedicated "health" command

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

• text

  Copy

  --json
  : machine-readable JSON output
• text

  Copy

  --timeout <ms>
  : override the default 10s probe timeout
• text

  Copy

  --verbose
  : force a live probe and print gateway connection details
• text

  Copy

  --debug
  : alias for
  text

  Copy

  --verbose

The health snapshot includes:

(boolean), (timestamp), (probe time), per-channel status, agent availability, and session-store summary.

Related

• Gateway runbook
• Diagnostics export
• Gateway troubleshooting