Doctor

openclaw doctor 是 OpenClaw 的修復 + 遷移工具。它能修正過期的設定和狀態、檢查健康狀態，並提供可操作的修復建議。

快速開始

openclaw doctor

無人值守/自動化

openclaw doctor --yes

接受所有預設選項，不需互動確認（包括重啟、服務、沙箱修復等步驟）。

openclaw doctor --repair

自動套用建議的修復，不需互動確認（修復 + 安全範圍內的重啟）。

openclaw doctor --repair --force

同時套用積極的修復（會覆蓋自訂的 supervisor 設定）。

openclaw doctor --non-interactive

不需互動確認執行，只套用安全的遷移（設定正規化 + 磁碟狀態搬移）。跳過需要人工確認的重啟、服務和沙箱操作。 偵測到舊版狀態遷移時會自動執行。

openclaw doctor --deep

掃描系統服務，找出額外的 gateway 安裝（launchd/systemd/schtasks）。

如果你想在寫入前先檢查變更，先看一下設定檔：

cat ~/.openclaw/openclaw.json

它做了什麼（摘要）

  • 可選的 git 安裝前置更新（僅互動模式）。
  • UI 協定新鮮度檢查（協定 schema 較新時重建 Control UI）。
  • 健康檢查 + 重啟提示。
  • Skills 狀態摘要（合格/缺失/被封鎖）。
  • 舊版設定值正規化。
  • OpenCode provider 覆寫警告（models.providers.opencode / models.providers.opencode-go）。
  • 舊版磁碟狀態遷移（sessions/agent 目錄/WhatsApp 驗證）。
  • 舊版 cron 儲存遷移（jobId、schedule.cron、頂層 delivery/payload 欄位、payload provider、簡易 notify: true webhook 備援工作）。
  • 狀態完整性和權限檢查（sessions、transcripts、state 目錄）。
  • 設定檔權限檢查（本地執行時 chmod 600）。
  • 模型驗證健康：檢查 OAuth 過期、可刷新即將過期的 token、回報 auth-profile 冷卻/停用狀態。
  • 多餘的 workspace 目錄偵測（~/openclaw）。
  • 啟用沙箱時的映像檔修復。
  • 舊版服務遷移和額外 gateway 偵測。
  • Gateway 執行期檢查（服務已安裝但未運行、快取的 launchd 標籤）。
  • 頻道狀態警告（從運行中的 gateway 探測）。
  • Supervisor 設定稽核（launchd/systemd/schtasks）與可選修復。
  • Gateway 執行期最佳實踐檢查（Node vs Bun、版本管理器路徑）。
  • Gateway 埠衝突診斷（預設 18789）。
  • 開放 DM 策略的安全警告。
  • Gateway 驗證檢查——本地 token 模式（沒有 token 來源時提供生成選項；不覆寫 token SecretRef 設定）。
  • Linux 上的 systemd linger 檢查。
  • 原始碼安裝檢查（pnpm workspace 不匹配、缺少 UI 資源、缺少 tsx 二進位檔）。
  • 寫入更新後的設定 + wizard 中繼資料。

詳細行為與設計考量

0) 可選更新（git 安裝）

如果是 git checkout 且 doctor 在互動模式下執行，會詢問是否在執行 doctor 前先更新（fetch/rebase/build）。

1) 設定正規化

如果設定檔包含舊版的值結構（例如 messages.ackReaction 沒有頻道層級覆寫），doctor 會將其正規化為目前的 schema。

2) 舊版設定鍵遷移

當設定檔包含已棄用的鍵時，其他指令會拒絕執行並要求你執行 openclaw doctor。

Doctor 會：

  • 說明找到了哪些舊版鍵。
  • 顯示套用了什麼遷移。
  • 用更新後的 schema 重寫 ~/.openclaw/openclaw.json。

Gateway 在啟動時偵測到舊版設定格式也會自動執行 doctor 遷移，讓過期的設定不需要手動介入就能修復。

目前的遷移：

  • routing.allowFrom → channels.whatsapp.allowFrom
  • routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
  • routing.groupChat.historyLimit → messages.groupChat.historyLimit
  • routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
  • routing.queue → messages.queue
  • routing.bindings → 頂層 bindings
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • bindings[].match.accountID → bindings[].match.accountId
  • 有命名 accounts 但缺少 accounts.default 的頻道，將頂層的單帳號設定值搬入 channels.<channel>.accounts.default
  • identity → agents.list[].identity
  • agent.* → agents.defaults + tools.*（tools/elevated/exec/sandbox/subagents）
  • agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks
  • browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork

Doctor 也會針對多帳號頻道提供帳號預設值指引：

  • 如果某頻道有兩個以上的 channels.<channel>.accounts 設定但沒有 channels.<channel>.defaultAccount 或 accounts.default，doctor 會警告備援路由可能選到非預期的帳號。
  • 如果 channels.<channel>.defaultAccount 指向不存在的帳號 ID，doctor 會警告並列出已設定的帳號 ID。

2b) OpenCode provider 覆寫

如果你手動新增了 models.providers.opencode、opencode-zen 或 opencode-go，它會覆寫 @mariozechner/pi-ai 的內建 OpenCode 目錄。這可能導致模型用錯 API 或費用歸零。Doctor 會提出警告，讓你移除覆寫以恢復每模型的 API 路由和費用計算。

3) 舊版狀態遷移（磁碟配置）

Doctor 可以把較舊的磁碟配置遷移到目前的結構：

  • Sessions 儲存 + transcripts：
    • 從 ~/.openclaw/sessions/ 到 ~/.openclaw/agents/<agentId>/sessions/
  • Agent 目錄：
    • 從 ~/.openclaw/agent/ 到 ~/.openclaw/agents/<agentId>/agent/
  • WhatsApp 驗證狀態（Baileys）：
    • 從舊版 ~/.openclaw/credentials/*.json（oauth.json 除外）
    • 到 ~/.openclaw/credentials/whatsapp/<accountId>/...（預設帳號 id：default）

這些遷移是盡力而為且冪等的；doctor 會在留下舊版資料夾作為備份時發出警告。Gateway/CLI 在啟動時也會自動遷移舊版 sessions + agent 目錄，確保紀錄、驗證和模型設定進入 per-agent 路徑，無需手動執行 doctor。WhatsApp 驗證則刻意只透過 openclaw doctor 遷移。

3b) 舊版 cron 儲存遷移

Doctor 也會檢查 cron 工作儲存（預設 ~/.openclaw/cron/jobs.json，或 cron.store 覆寫時使用覆寫路徑），找出排程器為了向下相容而仍接受的舊版工作格式。

目前的 cron 清理包括：

  • jobId → id
  • schedule.cron → schedule.expr
  • 頂層 payload 欄位（message、model、thinking 等）→ payload
  • 頂層 delivery 欄位（deliver、channel、to、provider 等）→ delivery
  • payload provider delivery 別名 → 明確的 delivery.channel
  • 簡易舊版 notify: true webhook 備援工作 → 明確的 delivery.mode="webhook" 加上 delivery.to=cron.webhook

Doctor 只在不改變行為的前提下自動遷移 notify: true 的工作。如果某工作同時有舊版 notify 備援和既有的非 webhook delivery 模式，doctor 會發出警告並留給你手動處理。

4) 狀態完整性檢查（session 持久化、路由與安全）

State 目錄是營運核心。如果它消失了，你就會失去 sessions、憑證、日誌和設定（除非你有其他地方的備份）。

Doctor 會檢查：

  • State 目錄遺失：警告災難性的狀態遺失，提示重建目錄，並提醒它無法恢復遺失的資料。
  • State 目錄權限：驗證是否可寫入；提供權限修復選項（偵測到 owner/group 不匹配時會給出 chown 提示）。
  • macOS 雲端同步的 state 目錄：當 state 解析到 iCloud Drive（~/Library/Mobile Documents/com~apple~CloudDocs/...）或 ~/Library/CloudStorage/... 下時發出警告，因為同步路徑可能導致較慢的 I/O 和鎖定/同步競爭。
  • Linux SD 或 eMMC 的 state 目錄：當 state 解析到 mmcblk* 掛載來源時發出警告，因為 SD 或 eMMC 的隨機 I/O 較慢且在 session 和憑證寫入下磨損較快。
  • Session 目錄遺失：sessions/ 和 session 儲存目錄是保存紀錄和避免 ENOENT 崩潰的必要條件。
  • Transcript 不匹配：當近期的 session 條目有缺失的 transcript 檔案時發出警告。
  • 主 session「單行 JSONL」：主 transcript 只有一行（紀錄沒有在累積）時標記。
  • 多個 state 目錄：當不同 home 目錄下存在多個 ~/.openclaw 資料夾，或 OPENCLAW_STATE_DIR 指向其他位置時發出警告（紀錄可能分散在不同安裝之間）。
  • Remote 模式提醒：如果 gateway.mode=remote，doctor 會提醒你到遠端主機上執行（state 在那邊）。
  • 設定檔權限：~/.openclaw/openclaw.json 如果有 group/world 可讀，會發出警告並提供收緊到 600 的選項。

5) 模型驗證健康（OAuth 過期）

Doctor 會檢查驗證儲存中的 OAuth profile，在 token 即將過期或已過期時發出警告，並在安全時刷新。如果 Anthropic Claude Code profile 已過期，會建議執行 claude setup-token（或貼上 setup-token）。 刷新提示只在互動模式（TTY）時出現；--non-interactive 會跳過刷新嘗試。

Doctor 也會回報暫時無法使用的 auth profile：

  • 短期冷卻（限速/逾時/驗證失敗）
  • 較長期的停用（帳單/額度問題）

6) Hooks 模型驗證

如果有設定 hooks.gmail.model，doctor 會對照目錄和白名單驗證模型參照，在無法解析或被封鎖時發出警告。

7) 沙箱映像檔修復

啟用沙箱時，doctor 會檢查 Docker 映像檔，並在目前映像檔不存在時提供建置或切換到舊版名稱的選項。

8) Gateway 服務遷移與清理提示

Doctor 會偵測舊版的 gateway 服務（launchd/systemd/schtasks），並提供移除舊服務、使用目前 gateway 埠安裝 OpenClaw 服務的選項。它也能掃描額外的 gateway 類服務並印出清理提示。 以 profile 命名的 OpenClaw gateway 服務被視為正式服務，不會被標記為「多餘」。

9) 安全警告

當某個提供者對 DM 開放但沒有白名單，或策略被設定成危險的方式時，doctor 會發出警告。

10) systemd linger（Linux）

如果以 systemd user service 運行，doctor 會確認 linger 已啟用，以便在登出後 gateway 仍能持續運行。

11) Skills 狀態

Doctor 會為目前 workspace 印出合格/缺失/被封鎖的 skills 快速摘要。

12) Gateway 驗證檢查（本地 token）

Doctor 會檢查本地 gateway token 驗證是否就緒。

  • 如果 token 模式需要 token 但沒有 token 來源，doctor 會提供生成選項。
  • 如果 gateway.auth.token 是由 SecretRef 管理但無法取得，doctor 會發出警告但不會用明文覆寫。
  • openclaw doctor --generate-gateway-token 只在沒有設定 token SecretRef 時才強制生成。

12b) 唯讀 SecretRef 感知修復

部分修復流程需要檢視已設定的憑證，同時不削弱執行期的 fail-fast 行為。

  • openclaw doctor --fix 現在使用與 status 系列指令相同的唯讀 SecretRef 摘要模型來做針對性的設定修復。
  • 範例：Telegram allowFrom / groupAllowFrom 的 @username 修復，會嘗試在可用時使用已設定的 bot 憑證。
  • 如果 Telegram bot token 是透過 SecretRef 設定但在目前指令路徑中無法取得，doctor 會回報憑證「已設定但不可用」，並跳過自動解析，而不是崩潰或誤報 token 遺失。

13) Gateway 健康檢查 + 重啟

Doctor 會執行健康檢查，並在 gateway 看起來不健康時提供重啟選項。

14) 頻道狀態警告

如果 gateway 健康，doctor 會執行頻道狀態探測並回報警告及建議的修復方式。

15) Supervisor 設定稽核 + 修復

Doctor 會檢查已安裝的 supervisor 設定（launchd/systemd/schtasks）是否有缺失或過時的預設值（例如 systemd network-online 依賴和重啟延遲）。發現不匹配時，會建議更新並可重寫服務檔/任務為目前的預設值。

注意事項：

  • openclaw doctor 在重寫 supervisor 設定前會先詢問。
  • openclaw doctor --yes 接受預設的修復提示。
  • openclaw doctor --repair 不需提示直接套用建議的修復。
  • openclaw doctor --repair --force 覆寫自訂的 supervisor 設定。
  • 如果 token 驗證需要 token 且 gateway.auth.token 是 SecretRef 管理的，doctor 的服務安裝/修復會驗證 SecretRef 但不會將解析後的明文 token 值寫入 supervisor 服務環境中繼資料。
  • 如果 token 驗證需要 token 但設定的 token SecretRef 無法解析，doctor 會封鎖安裝/修復路徑並給出可操作的指引。
  • 如果 gateway.auth.token 和 gateway.auth.password 都有設定但 gateway.auth.mode 未指定，doctor 會封鎖安裝/修復直到 mode 被明確設定。
  • Linux user-systemd 單元的 token 差異檢查現在同時包含 Environment= 和 EnvironmentFile= 來源的比對。
  • 你隨時可以用 openclaw gateway install --force 強制完整重寫。

16) Gateway 執行期 + 埠診斷

Doctor 會檢視服務執行期（PID、上次退出狀態），並在服務已安裝但實際未運行時發出警告。也會檢查 gateway 埠（預設 18789）的衝突，並回報可能的原因（gateway 已在運行、SSH 通道）。

17) Gateway 執行期最佳實踐

Doctor 會在 gateway 服務跑在 Bun 或版本管理器路徑下（nvm、fnm、volta、asdf 等）時發出警告。WhatsApp + Telegram 頻道需要 Node，而版本管理器路徑在升級後可能失效，因為服務不會載入你的 shell init。Doctor 會在有系統級 Node 安裝可用時（Homebrew/apt/choco）提供遷移選項。

18) 設定寫入 + wizard 中繼資料

Doctor 會持久化設定變更，並寫入 wizard 中繼資料來記錄 doctor 執行紀錄。

19) Workspace 建議（備份 + 記憶系統）

Doctor 會在缺少 workspace 記憶系統時建議建立，並在 workspace 尚未用 git 管理時印出備份提示。

參閱 /concepts/agent-workspace 了解完整的 workspace 結構和 git 備份指南（建議使用私有 GitHub 或 GitLab）。

arrow_back
上一頁
Heartbeat
下一頁
Logging
arrow_forward