OpenClaw 狀態檢查：CLI 指令與故障排除指南

健康檢查 (CLI)

開發 Bot 最煩人的事情之一，就是當它沒反應時，你得通靈去猜到底是哪裡出錯。是網路斷了、憑證過期，還是 Gateway 根本沒跑起來？這份簡短指南會教你如何直接驗證 Channel 的連線狀況，不用再靠直覺除錯。

快速檢查

• openclaw status — 本地摘要：Gateway 可達性與模式、更新提示、已連結 Channel 的認證時間、Sessions 以及近期的活動紀錄。
• openclaw status --all — 完整的本地診斷（唯讀、有顏色標記，適合直接貼給別人幫忙除錯）。
• openclaw status --deep — 除了基本檢查，還會探測運行中的 Gateway（在支援的情況下會進行各別 Channel 的探測）。
• openclaw health --json — 向運行中的 Gateway 請求完整的健康快照（僅限 WS；不會直接觸及 Baileys socket）。
• 在 WhatsApp 或 WebChat 中發送 /status 獨立訊息，可以直接獲取狀態回覆，而不會觸發 Agent。
• 日誌檢查：使用 tail /tmp/openclaw/openclaw-*.log 並過濾 web-heartbeat、web-reconnect、web-auto-reply 或 web-inbound 等關鍵字。

深度診斷

• 磁碟上的憑證：ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json（修改時間 mtime 應該要是最近的時間）。
• Session 儲存：ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json（路徑可以在設定中覆蓋）。Session 數量和最近的收件者可以透過 status 指令查看。
• 重新連結流程：當日誌中出現狀態碼 409–515 或 loggedOut 時，請執行 openclaw channels logout && openclaw channels login --verbose。（注意：QR code 登入流程在配對後若遇到狀態碼 515，會自動重啟一次。）

健康監測配置

• gateway.channelHealthCheckMinutes: Gateway 檢查 Channel 健康狀況的頻率。預設值：5。設定為 0 可全域停用健康監測重啟功能。
• gateway.channelStaleEventThresholdMinutes: 一個已連線的 Channel 在被健康監測視為過期並重啟前，可以保持閒置的最長時間。預設值：30。請確保此數值大於或等於 gateway.channelHealthCheckMinutes。
• gateway.channelMaxRestartsPerHour: 每個 Channel 或帳號在一小時內由健康監測觸發重啟的次數上限。預設值：10。
• channels.<provider>.healthMonitor.enabled: 針對特定 Channel 停用健康監測重啟，同時保持全域監測開啟。
• channels.<provider>.accounts.<accountId>.healthMonitor.enabled: 多帳號覆蓋設定，優先權高於 Channel 層級的設定。
• 這些針對每個 Channel 的覆蓋設定適用於目前已提供此功能的監測器：Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, 以及 WhatsApp。

當發生故障時

• 出現 logged out 或狀態碼 409–515 → 先執行 openclaw channels logout 再執行 openclaw channels login 重新連結。
• Gateway 無法連線 → 啟動它：openclaw gateway --port 18789（如果連接埠被佔用，請加上 --force）。
• 收不到傳入訊息 → 確認連結的手機已連網，且發送者在允許名單內（channels.whatsapp.allowFrom）；如果是群組對話，請確保允許名單與提及規則匹配（channels.whatsapp.groups, agents.list[].groupChat.mentionPatterns）。

專用的 “health” 指令

openclaw health --json 會向運行中的 Gateway 請求健康快照（CLI 不會直接從本地開啟 Channel socket）。它會回報已連結的憑證與認證時間、各 Channel 的探測摘要、Session 儲存摘要以及探測耗時。如果 Gateway 無法連線、探測失敗或逾時，該指令會以非零狀態碼退出。

選項：

• --json: 輸出機器可讀的 JSON 格式。
• --timeout <ms>: 覆蓋預設的 10 秒探測逾時設定。
• --probe: 強制對所有 Channel 進行即時探測，而不是回傳快取的健康快照。

健康快照包含：ok (布林值)、ts (時間戳記)、durationMs (探測耗時)、各 Channel 狀態、Agent 可用性以及 Session 儲存摘要。

AI Setup Assistant

下一步

• 了解 Gateway 配置
• WhatsApp 整合指南