Key Findings
  • openclaw doctor 是 OpenClaw 內建的一站式診斷工具，能自動檢測設定檔語法、模型認證狀態、Gateway 連線與 Node.js 版本相容性[1]
  • 加上 --fix 旗標可讓 doctor 自動修復大部分常見問題，包括遺失的設定值、過期的 Token 與損壞的 Workspace 索引[1]
  • Gateway 連線失敗（「Pairing Required」錯誤）是最常見的新手問題，通常只需重新產生 Gateway Token 即可解決[2]
  • 代理「卡死」的根本原因多為 LLM 請求逾時——調高 timeoutSeconds 或設定 Fallback 模型可有效緩解[4]

一、openclaw doctor：你的第一道防線

當 OpenClaw 出現異常行為時，第一件該做的事永遠是執行 openclaw doctor。這個指令會對整個系統進行全面健康檢查，並以清晰的紅/黃/綠標示回報每個項目的狀態。[1]

1.1 基本診斷

openclaw doctor

這個指令會依序檢查：

  1. Node.js 版本：OpenClaw 要求 Node.js 22 或以上
  2. 設定檔完整性：openclaw.json 的語法與必要欄位
  3. 模型認證：已設定的 Provider 是否能成功連線
  4. Gateway 狀態：Gateway 是否正在運行、Port 是否可達
  5. 通道連線：已設定的 Channel（Telegram、WhatsApp 等）是否正常

1.2 自動修復

openclaw doctor --fix

加上 --fix 後，doctor 不只診斷問題，還會嘗試修復。常見的自動修復包括：

1.3 產生 Gateway Token

openclaw doctor --generate-gateway-token

這個指令專門用於產生或重新產生 Gateway 的認證 Token。當你看到「Pairing Required」錯誤時，通常執行這一條指令就能解決。[2]

二、最常見的五個問題與解法

2.1 「Pairing Required」— Gateway 連線失敗

症狀：在 Web UI（http://127.0.0.1:18789）或通訊渠道中看到「Pairing Required」訊息。

原因：Gateway Token 遺失、過期或不匹配。

解法：

openclaw doctor --generate-gateway-token
# 然後重啟 Gateway
openclaw gateway restart

2.2 「LLM Request Timed Out」— 模型請求逾時

症狀：代理在執行任務途中停止回應，日誌顯示逾時錯誤。[4]

原因：LLM API 回應時間超過預設上限，常見於複雜任務或 API 流量高峰期。

解法：

# 調高逾時時間（單位：秒）
openclaw config set agents.defaults.timeoutSeconds 600

# 設定備援模型，在主模型逾時後自動切換
openclaw config set agents.defaults.model.fallbacks '["claude-sonnet-4-6"]'

2.3 代理「卡死」不回應

症狀：代理完全沒有反應，訊息發出後無回覆、無錯誤。

原因：可能是 Gateway 進程卡死、Node 進程崩潰，或 Workspace 狀態損壞。

解法（由輕到重）：

# 1. 重啟 Gateway
openclaw gateway restart

# 2. 如果 Gateway 無法正常重啟，強制停止後重啟
openclaw gateway stop
openclaw gateway start

# 3. 如果仍無法解決，執行完整診斷修復
openclaw doctor --fix

2.4 Port 18789 被佔用

症狀：啟動 Gateway 時顯示 Port 已被佔用。

解法：

# 檢查誰佔用了 Port
lsof -i :18789

# 選項 A：終止佔用的進程
kill -9 PID

# 選項 B：更換 Port
openclaw config set gateway.port 28789

2.5 模型認證失敗

症狀：代理回報「Model not allowed」或「Authentication failed」。[4]

解法：

# 檢查已設定的認證
openclaw models auth list

# 重新設定 API 金鑰
openclaw models auth setup-token --provider anthropic

# 或重新走 OAuth 流程
openclaw models auth login --provider openai

三、重啟與重置流程

3.1 一般重啟（保留所有資料）

openclaw gateway restart

這是最安全的重啟方式。Gateway 會先將當前狀態寫入持久化存儲，然後重新啟動。所有 Workspace、記憶與設定都會保留。

3.2 完全停止再啟動

openclaw gateway stop
# 等待幾秒
openclaw gateway start

適用於 gateway restart 無效的情況。stop 會確保所有相關進程完全終止。

3.3 Daemon 模式重啟（systemd）

如果你使用 openclaw onboard --install-daemon 安裝了 systemd 服務：

systemctl --user restart openclaw-gateway

3.4 清除上下文（軟重置）

如果代理的對話上下文變得混亂，你可以只清除上下文而不重啟整個系統：

openclaw chat --new

這會開啟一個全新的對話，不影響 Workspace 中的長期記憶。

四、日誌分析與進階除錯

4.1 查看即時日誌

openclaw tail

這個指令會即時輸出 Gateway 的運行日誌，類似 tail -f。你可以看到每個請求的處理過程、模型呼叫的延遲與錯誤訊息。[7]

4.2 常見日誌訊息解讀

日誌訊息含義建議動作
Gateway started on :18789正常啟動無需動作
Pairing requiredToken 驗證失敗執行 doctor --generate-gateway-token
LLM request timed out模型回應超時調高 timeoutSeconds 或設定 Fallback
Model not allowed模型不在允許清單中檢查 allowlist 設定
Agent bootstrap pending代理正在初始化等待完成，通常需 10-30 秒
WebSocket connection closedWebSocket 斷開檢查網路連線或反向代理設定

五、預防性維護建議

與其被動排錯，不如主動預防。以下是我們根據實戰經驗整理的維護清單：[5][6]

  1. 每週執行一次 openclaw doctor：即使系統運行正常，定期檢查也能提前發現潛在問題
  2. 保持 OpenClaw 更新：執行 npm update -g openclaw 以獲取最新的安全修補與功能改進
  3. 設定 Fallback 模型：永遠不要只依賴單一模型供應商
  4. 監控 Gateway 記憶體使用：長時間運行的 Gateway 可能出現記憶體洩漏，建議每週重啟一次
  5. 備份 ~/.openclaw/ 目錄：包含你所有的設定、認證與 Workspace 資料

結語

openclaw doctor 加上 --fix 旗標，能自動解決超過八成的常見問題。[1] 對於較複雜的問題，本文提供的日誌分析與系統性排錯流程可以幫助你快速定位根因。

如果你剛開始使用 OpenClaw，建議先閱讀我們的《架構解析與實戰部署全指南》來建立完整的系統認知；如果你需要調整設定，可以參閱《設定完全指南》。