OpenClaw 故障排除指南

寫程式最煩的就是東西突然不動了，但你完全不知道問題出在哪。看著沒反應的視窗或空白的 Log，這種挫敗感真的很討厭。這篇文就是要幫你快速定位 OpenClaw 的問題，不用在那邊瞎猜。

如果你只有兩分鐘，直接把這頁當成你的診斷入口。

需要準備的東西

已安裝 OpenClaw CLI
正在運行的 Gateway 或服務

Quick Start: 最初的 60 秒

按順序執行這串指令，檢查你的系統狀態：

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

正常的輸出應該長這樣：

openclaw status → 顯示已設定的 channels，且沒有明顯的 auth 錯誤。
openclaw status --all → 產出完整的報告供參考。
openclaw gateway probe → 預期的 gateway 目標是可以連上的。
openclaw gateway status → 顯示 Runtime: running 且 RPC probe: ok。
openclaw doctor → 沒有阻斷性的設定或服務錯誤。
openclaw channels status --probe → channels 顯示 connected 或 ready。
openclaw logs --follow → 持續有活動，沒有重複的 fatal 錯誤。

疑難排解

根據你遇到的問題類型，參考下方的決策樹：

flowchart TD
  A[OpenClaw 無法運作] --> B{哪部分先壞掉？}
  B --> C[沒有回應]
  B --> D[Dashboard 或 Control UI 無法連線]
  B --> E[Gateway 無法啟動或服務未執行]
  B --> F[Channel 已連線但訊息沒反應]
  B --> G[Cron 或 heartbeat 未觸發或未送達]
  B --> H[Node 已配對但執行 camera canvas 失敗]
  B --> I[Browser 工具失效]

  C --> C1[/沒有回應部分/]
  D --> D1[/Control UI 部分/]
  E --> E1[/Gateway 部分/]
  F --> F1[/Channel 流程部分/]
  G --> G1[/自動化部分/]
  H --> H1[/Node 工具部分/]
  I --> I1[/Browser 部分/]

常見問題分類

沒有回應 (No replies)

執行這些指令：

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw logs --follow

正常狀態：

Runtime: running
RPC probe: ok
Channel 在 channels status --probe 中顯示 connected/ready。
發送者已獲核准（或 DM 政策為 open/allowlist）。

常見 Log 特徵：

drop guild message (mention required → Discord 中因缺少標註而被阻斷。
pairing request → 發送者未獲核准，等待 DM 配對核准中。
Log 中出現 blocked 或 allowlist → 發送者、房間或群組被過濾。

深入了解：

Dashboard 或 Control UI 無法連線

執行這些指令：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常狀態：

openclaw gateway status 顯示 Dashboard: http://...。
RPC probe: ok
Log 中沒有 auth 無限迴圈。

常見 Log 特徵：

device identity required → HTTP 或非安全環境無法完成裝置認證。
unauthorized 或重新連線迴圈 → token/password 錯誤或 auth 模式不匹配。
gateway connect failed: → UI 指向錯誤的 URL/port 或 gateway 無法連線。

深入了解：

Gateway 無法啟動或服務未執行

執行這些指令：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

正常狀態：

Service: ... (loaded)
Runtime: running
RPC probe: ok

常見 Log 特徵：

Gateway start blocked: set gateway.mode=local → gateway 模式未設定或為 remote。
refusing to bind gateway ... without auth → 非 loopback 綁定但未設定 token/password。
another gateway instance is already listening 或 EADDRINUSE → port 已被佔用。

深入了解：

Channel 已連線但訊息沒反應

執行這些指令：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw channels status --probe

正常狀態：

Channel transport 已連線。
Pairing/allowlist 檢查通過。
在需要標註的地方有偵測到 mentions。

常見 Log 特徵：

mention required → 群組標註限制阻斷了處理。
pairing 或 pending → DM 發送者尚未獲准。
not_in_channel, missing_scope, Forbidden, 401/403 → Channel 權限或 token 問題。

深入了解：

Cron 或 heartbeat 未觸發或未送達

執行這些指令：

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow

正常狀態：

cron.status 顯示啟用並有下次喚醒時間。
cron runs 顯示最近有 ok 記錄。
Heartbeat 已啟用且不在靜音時段內。

常見 Log 特徵：

cron: scheduler disabled; jobs will not run automatically → cron 已停用。
heartbeat skipped 帶有 reason=quiet-hours → 處於設定的靜音時段。
requests-in-flight → 主通道繁忙，heartbeat 喚醒被推遲。
unknown accountId → heartbeat 傳送目標帳號不存在。

深入了解：

Node 已配對但執行工具失敗

執行這些指令：

openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow

正常狀態：

Node 狀態為已連線，且配對角色為 node。
你呼叫的指令具備相應的 Capability。
該工具的權限狀態為已授權。

常見 Log 特徵：

NODE_BACKGROUND_UNAVAILABLE → 需要將 Node App 切換至前台。
*_PERMISSION_REQUIRED → OS 權限被拒絕或缺失。
SYSTEM_RUN_DENIED: approval required → 執行審核待處理中。
SYSTEM_RUN_DENIED: allowlist miss → 指令不在執行白名單中。

深入了解：

Browser 工具失效

執行這些指令：

openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor

正常狀態：

Browser 狀態顯示 running: true 且有選定的 browser/profile。
openclaw profile 已啟動，或 chrome relay 已附加分頁。

常見 Log 特徵：

Failed to start Chrome CDP on port → 本地瀏覽器啟動失敗。
browser.executablePath not found → 設定的執行檔路徑錯誤。
Chrome extension relay is running, but no tab is connected → 擴充功能未附加。
Browser attachOnly is enabled ... not reachable → attach-only 模式找不到運行的 CDP 目標。

深入了解：

如果是更複雜的問題，建議直接詢問 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。