OpenClaw Doctor 指令：完整參考與修復指南

openclaw doctor 指令是出問題時的第一道防線。它會診斷問題、解釋哪裡壞了，並且能自動修復大多數問題。

基本用法

# 診斷問題（唯讀）
openclaw doctor

# 診斷並自動修復
openclaw doctor --fix

Doctor 會執行一系列健康檢查，並以 OK、WARN 或 FAIL 報告結果。

Doctor 檢查項目

1. Gateway 設定

檢查 gateway.mode 是否已設定且有效。

FAIL  gateway.mode is unset — gateway start will be blocked
FIX:  openclaw config set gateway.mode local

使用 --fix 自動修復： 將 gateway.mode 設為 local。

2. 裝置 Token 不一致

檢查裝置 token 是否與 gateway 預期的 token 一致。

FAIL  device token mismatch — stored token doesn't match gateway
FIX:  regenerating device token

使用 --fix 自動修復： 重新產生匹配的 token 並重新配對裝置。

3. 未知設定鍵

檢查 openclaw.json 中是否有無法識別的鍵名。

WARN  unknown config key: "model" (did you mean "ai.model"?)
WARN  unknown config key: "telegramToken" (did you mean "telegram.token"?)

使用 --fix 自動修復： 移除或遷移無法識別的鍵名至正確名稱。

4. 設定驗證

檢查是否有無效的值、缺少的必填欄位和格式錯誤的 JSON。

FAIL  config validation failed: "gateway.port" must be a number

使用 --fix 自動修復： 修正類型不匹配，並為缺少的欄位設定預設值。

5. 配對狀態

檢查 Telegram 和其他整合是否已正確配對。

WARN  pairing required — Telegram bot is configured but not paired
FIX:  openclaw pairing approve telegram CODE

使用 --fix 自動修復： 啟動配對流程並提供核准指令。

6. 目錄權限

檢查 OpenClaw 的資料目錄是否存在且可寫入。

FAIL  data directory not writable: /app/data
FIX:  fixing permissions

7. 連接埠可用性

檢查配置的 gateway 連接埠是否可用。

FAIL  port 3001 is already in use by process 12345
FIX:  kill the process or change gateway.port

8. Node.js 版本

檢查你的 Node.js 版本是否符合最低要求（22+）。

FAIL  Node.js 18.x detected — OpenClaw requires Node.js 22+

實用旗標

--fix

自動修復所有偵測到的問題：

openclaw doctor --fix

可以安全地重複執行。已經正確的項目不會被改動。

--generate-gateway-token

產生新的 gateway token（在 device token mismatch 後很有用）：

openclaw doctor --generate-gateway-token

--verbose

顯示詳細的診斷輸出：

openclaw doctor --verbose

--json

以 JSON 格式輸出結果（適合用於腳本）：

openclaw doctor --json

常見情境

全新安裝後

openclaw doctor --fix

這會配置 gateway 模式、設定目錄，並驗證初始設定。

升級後

openclaw doctor --fix

遷移已棄用的設定鍵名，並修復升級帶來的任何破壞性變更。

容器重建後

docker exec -it CONTAINER_ID openclaw doctor --fix

重新產生 token 並重新配對在重建過程中遺失的裝置。

其他方法都無效時

openclaw doctor --fix --verbose

Verbose 旗標會顯示正在檢查和修復的確切內容，幫助你找出 doctor 無法自動修復的問題。

Doctor 無法修復的問題

有些問題需要手動處理：

• 錯誤的 API 金鑰：Doctor 無法驗證你的 AI 供應商憑證
• 網路問題：防火牆規則、DNS 或 ISP 封鎖
• 反向代理設定錯誤：Caddy/Nginx 的設定不在 OpenClaw 的管轄範圍
• Telegram bot 衝突：另一個程序正在輪詢相同的 bot token

遇到這些問題時，請檢查 openclaw logs --follow 以取得具體的錯誤訊息。

定期執行 Doctor

將 openclaw doctor 加入你的維護例行工作中——特別是在更新後。它能在設定飄移造成問題之前就偵測到。

預先配置，無需 Doctor

ClawTank 自動管理你的 OpenClaw 設定。不需要執行 doctor——平台會幫你處理 gateway token、設定驗證和配對。