---
read_when:
- 新增或修改 doctor 遷移作業
- 引入不相容的設定變更
sidebarTitle: Doctor
summary: Doctor 命令：健康檢查、設定遷移與修復步驟
title: 診斷工具
x-i18n:
generated_at: "2026-07-14T13:40:03Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 25
provider: openai
source_hash: e5c37c31332a9128767ebf6a853aa618511b9eda7f5840a4f863ec705c58421a
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` 是 OpenClaw 的修復與遷移工具。它會修正過時的設定／狀態、檢查健康狀況，並提供可採取行動的修復步驟。
## 快速開始
```bash
openclaw doctor
```
### 無介面與自動化模式
```bash
openclaw doctor --yes
```
不顯示提示並接受預設值（適用時包括重新啟動／服務／沙箱修復步驟）。
```bash
openclaw doctor --fix
```
不顯示提示並套用建議的修復（`--repair` 是別名）。
```bash
openclaw doctor --lint
openclaw doctor --lint --json
```
執行適用於 CI 或預檢自動化的結構化健康檢查。唯讀：不會顯示
提示、進行修復或遷移、重新啟動，亦不會寫入狀態。
```bash
openclaw doctor --fix --force
```
同時套用積極的修復（會覆寫自訂的監督程式設定）。
```bash
openclaw doctor --non-interactive
```
不顯示提示，且僅套用安全遷移（設定正規化 +
磁碟上的狀態移動）。略過需要人工
確認的重新啟動／服務／沙箱動作。偵測到舊版狀態遷移時仍會自動執行。
```bash
openclaw doctor --deep
```
掃描系統服務中的額外閘道安裝項目（launchd/systemd/schtasks）。
若要在寫入前檢閱變更，請先開啟設定檔：
```bash
cat ~/.openclaw/openclaw.json
```
## 唯讀 lint 模式
`openclaw doctor --lint` 是 `openclaw doctor --fix` 適合自動化使用的同系工具。兩者共用相同的 Doctor 規則登錄表，但
選取或處理規則的方式並不相同：
| 模式 | 提示 | 寫入設定／狀態 | 輸出 | 用途 |
| ------------------------ | --------- | ----------------------- | ---------------------- | ------------------------------- |
| `openclaw doctor` | 是 | 否 | 易讀的健康報告 | 人工檢查狀態 |
| `openclaw doctor --fix` | 有時 | 是，依照修復政策 | 易讀的修復記錄 | 套用已核准的修復 |
| `openclaw doctor --lint` | 否 | 否 | 結構化發現項目 | CI、預檢及檢閱閘門 |
預設的 `doctor --lint` 會執行廣泛且安全的自動化設定檔：執行靜態、本機，
且對 CI 或預檢輸出有用的檢查。它會略過選擇加入且屬於建議性、
對環境敏感、依賴即時服務、帳號／工作區
清查或歷史清理的檢查。若要執行完整的已登錄 lint 稽核（包括這些選擇加入的檢查），請使用 `doctor --lint --all`；若要執行
特定檢查，則使用 `--only `。
`doctor --fix` 不使用 lint 預設設定檔，也不接受
`--all`。它會執行 Doctor 的依序修復路徑：現代化健康檢查可提供
選用的 `repair()` 實作，較舊的區域則仍使用其舊版
Doctor 修復流程。部分 lint 發現項目刻意僅供診斷，因此
即使某項檢查出現在 `--lint --all` 中，也不代表 `--fix` 會修改該區域。
此合約將 `detect()`（回報發現項目）與 `repair()`（回報
變更／差異／副作用）分開，為未來的
`doctor --fix --dry-run` 保留發展路徑，而無須將 lint 檢查轉變為修改規劃器。
部分內建檢查在內部預設為停用，以便讓
`--all`、`--only` 和 Doctor 修復流程使用，同時不成為預設
`doctor --lint` 自動化設定檔的一部分。每個發現項目仍會輸出其嚴重性
（`info`、`warning` 或 `error`）；預設選取並非嚴重性
層級。
```bash
openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --only core/doctor/gateway-config --json
```
JSON 輸出欄位：
- `ok`：是否有任何發現項目達到所選的嚴重性門檻
- `checksRun` / `checksSkipped`：計數（因設定檔、`--only` 或 `--skip` 而略過）
- `findings`：包含 `checkId`、`severity`、`message`，以及選用的 `path`、`line`、`column`、`ocPath`、`source`、`target`、`requirement`、`fixHint` 的結構化診斷資訊
結束代碼：
| 代碼 | 意義 |
| ---- | -------------------------------------------------------- |
| `0` | 沒有任何發現項目達到或超過所選門檻 |
| `1` | 一個或多個發現項目達到所選門檻 |
| `2` | 在能夠輸出發現項目前發生命令／執行階段失敗 |
旗標：
- `--severity-min info|warning|error`（預設為 `warning`）：同時控制輸出的內容，以及導致非零結束代碼的條件。
- `--all`：執行所有已登錄的 lint 檢查，包括預設自動化集合排除的選擇加入檢查。
- `--only `（可重複使用）：僅執行指定 ID 的檢查；未知 ID 會回報為錯誤發現項目。
- `--skip `（可重複使用）：排除某項檢查，同時保持其餘檢查繼續執行。
- `--json`、`--severity-min`、`--all`、`--only` 和 `--skip` 需要 `--lint`；單純執行 `openclaw doctor` 和 `--fix` 時會拒絕這些旗標。
## 功能摘要
- Git 安裝項目的選用預檢更新（僅限互動模式）。
- UI 通訊協定新鮮度檢查（當通訊協定結構描述較新時，重新建置 Control UI）。
- 健康檢查 + 重新啟動提示。
- 僅顯示有問題的 Skill 和外掛備註；健康的清查結果仍位於 `openclaw skills check` 和 `openclaw plugins list`。
- 舊版值形狀的設定正規化。
- 將舊版扁平 `talk.*` 欄位的 Talk 設定遷移至 `talk.provider` + `talk.providers.`。
- 舊版 Chrome 擴充功能設定和 Chrome MCP 就緒狀態的瀏覽器遷移檢查。
- OpenCode 提供者覆寫警告（`models.providers.opencode` / `opencode-zen` / `opencode-go`）。
- 舊版 OpenAI Codex 提供者／設定檔遷移（`openai-codex` → `openai`），以及過時 `models.providers.openai-codex` 的遮蔽警告。
- OpenAI Codex OAuth 設定檔的 OAuth TLS 先決條件檢查。
- 當 `plugins.allow` 採用限制性設定，但工具政策仍要求萬用字元或外掛所擁有的工具時，顯示外掛／工具允許清單警告。
- 舊版磁碟狀態遷移（工作階段／代理程式目錄／WhatsApp 驗證）。
- 舊版外掛資訊清單合約鍵遷移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
- 舊版排程儲存區遷移（`jobId`、`schedule.cron`、頂層傳遞／承載資料欄位、承載資料 `provider`、`notify: true` 網路鉤子後援工作）。
- 在 `agents.defaults`、`agents.list[]` 和 `models.providers.*`（包括各模型項目）中修復 Codex 命令列介面執行階段固定項目（`agentRuntime.id: "codex-cli"` → `"codex"`）。
- 啟用外掛時清理過時的外掛設定；當 `plugins.enabled=false` 時，過時的外掛參照會保留為非作用中的隔離設定。
- 檢查工作階段鎖定檔案並清理過時的鎖定。
- 修復受影響的 2026.4.24 組建所建立、含重複提示重寫分支的工作階段文字記錄。
- 偵測卡住子代理程式的重新啟動復原墓碑，並支援以 `--fix` 清除過時且已中止的復原旗標，避免啟動流程持續將子項目視為重新啟動已中止。
- 狀態完整性與權限檢查（工作階段、文字記錄、狀態目錄）。
- 在本機執行時檢查設定檔權限（chmod 600）。
- 模型驗證健康狀況：檢查 OAuth 到期情況、可重新整理即將到期的權杖，並回報驗證設定檔的冷卻／停用狀態。
- 啟用沙箱時修復沙箱映像檔。
- 舊版服務遷移及額外閘道偵測。
- Matrix 頻道舊版狀態遷移（在 `--fix` / `--repair` 模式中）。
- 閘道執行階段檢查（服務已安裝但未執行；快取的 launchd 標籤）。
- 頻道狀態警告（從執行中的閘道探測）。
- 頻道特定的權限檢查位於 `openclaw channels capabilities` 下；例如，使用 `openclaw channels capabilities --channel discord --target channel:` 稽核 Discord 語音頻道權限。
- 當本機終端介面用戶端仍在執行時，檢查閘道事件迴圈健康狀況降級所造成的 WhatsApp 回應問題；`--fix` 僅會停止已驗證的本機終端介面用戶端。
- 修復主要模型、後援、影像／影片產生模型、心跳偵測／子代理程式／壓縮覆寫、掛鉤、頻道模型覆寫及工作階段路由固定項目中的舊版 `openai-codex/*` 模型參照；`--fix` 會將其重寫為 `openai/*`，將 `openai-codex:*` 驗證設定檔／順序遷移至 `openai:*`，移除過時的工作階段／整個代理程式執行階段固定項目，並讓修復後的有效路由決定 Codex 是否相容。
- 監督程式設定稽核（launchd/systemd/schtasks），並可選擇進行修復。
- 清理閘道服務在安裝或更新期間擷取的 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值所形成的內嵌 Proxy 環境。
- 閘道執行階段檢查（不受支援的舊版 Bun 服務、版本管理器路徑）。
- 閘道連接埠衝突診斷（預設 `18789`）。
- 開放式私訊政策的安全性警告。
- 本機權杖模式的閘道驗證檢查（沒有權杖來源時會提議產生權杖；不會覆寫權杖 SecretRef 設定）。
- 裝置配對問題偵測（待處理的首次配對要求、待處理的角色／範圍升級、過時的本機裝置權杖快取偏移，以及已配對記錄的驗證偏移）。
- Linux 上的 systemd linger 檢查。
- 工作區啟動程序檔案大小檢查（內容檔案的截斷／接近限制警告）。
- 預設代理程式的 Skills 就緒狀態檢查；回報缺少二進位檔、環境、設定或作業系統需求的已允許 Skills，而 `--fix` 可停用 `skills.entries` 中無法使用的 Skills。
- Shell 自動完成狀態檢查及自動安裝／升級。
- 記憶搜尋嵌入提供者就緒狀態檢查（本機模型、遠端 API 金鑰或 QMD 二進位檔）。
- 原始碼安裝檢查（pnpm 工作區不相符、缺少 UI 資產、缺少 tsx 二進位檔）。
- 寫入更新後的設定 + 精靈中繼資料。
## 夢境 UI 回填與重設
Control UI 的夢境整理場景包含適用於有根據夢境整理工作流程的**回填**、**重設**和**清除有根據項目**動作。這些動作使用閘道的 doctor 風格 RPC 方法，但**不**屬於 `openclaw doctor` 命令列介面的修復／遷移功能。
| 動作 | 功能 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 回填 | 掃描作用中工作區內的歷史 `memory/YYYY-MM-DD.md` 檔案、執行有根據的 REM 日記處理，並將可還原的回填項目寫入 `DREAMS.md`。 |
| 重設 | 僅從 `DREAMS.md` 移除已標記的回填日記項目。 |
| 清除有根據項目 | 僅移除歷史重播中尚未累積即時回憶或每日支援的暫存有根據專用短期項目。 |
這些動作都不會自行編輯 `MEMORY.md`、執行完整的 doctor 遷移，或將有根據候選項目暫存至即時短期提升儲存區。若要將有根據的歷史重播送入一般的深度提升流程，請改用命令列介面流程：
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
這會將有根據的持久候選項目暫存至短期夢境整理儲存區，而 `DREAMS.md` 仍作為檢閱介面。
## 詳細行為與理由
如果這是 git checkout，且 doctor 以互動模式執行，它會在執行 doctor 前詢問是否要更新（fetch／rebase／build）。
Doctor 會將舊版值格式正規化為目前的結構描述。目前的 Talk 語音設定為 `talk.provider` + `talk.providers.`，即時語音設定則位於 `talk.realtime.*` 下。Doctor 會將舊版 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 格式重寫至提供者對應表，並將舊版頂層即時選擇器（`talk.mode`、`talk.transport`、`talk.brain`、`talk.model`、`talk.voice`）重寫至 `talk.realtime`。
當 `plugins.allow` 非空白，且工具原則使用萬用字元或外掛擁有的工具項目時，Doctor 也會發出警告。`tools.allow: ["*"]` 僅比對實際載入之外掛所提供的工具；它不會繞過外掛專用允許清單。
當設定包含已有作用中遷移的已淘汰鍵時，其他命令會拒絕執行，並要求你執行 `openclaw doctor`。Doctor 會說明找到哪些舊版鍵、顯示所套用的遷移，並以更新後的結構描述重寫 `~/.openclaw/openclaw.json`。閘道啟動時會拒絕舊版設定格式，並要求你執行 `openclaw doctor --fix`；它不會在啟動時重寫 `openclaw.json`。排程工作儲存區遷移也由 `openclaw doctor --fix` 處理。
Doctor 僅會在設定鍵淘汰後約兩個月內保留自動遷移。
更舊的舊版鍵（例如最初的
`routing.queue`、`routing.bindings`、`routing.agents`/`defaultAgentId`、
`routing.transcribeAudio`、頂層 `agent.*`，或多代理程式設定格式之前的頂層 `identity`）
已不再有遷移路徑；使用這些鍵的設定現在會驗證失敗，而不會遭到重寫。
請依照目前的設定參考資料手動修正這些鍵，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` |
| `channels.telegram.requireMention` | `channels.telegram.groups."*".requireMention` |
| `channels.webchat`、`gateway.webchat` | 已移除（WebChat 已淘汰） |
| `channels.feishu.accounts..botName` | `channels.feishu.accounts..name` |
| `session.threadBindings.ttlHours`、`channels..threadBindings.ttlHours`（及各帳號設定） | `...threadBindings.idleHours` |
| 舊版 `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` | `talk.provider` + `talk.providers.` |
| 舊版頂層即時 Talk 選擇器（`talk.mode`/`talk.transport`/`talk.brain`/`talk.model`/`talk.voice`） | `talk.realtime` |
| `messages.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`） | `messages.tts.providers.` |
| `messages.tts.provider: "edge"` / `messages.tts.providers.edge` | `messages.tts.provider: "microsoft"` / `messages.tts.providers.microsoft` |
| TTS 說話者欄位 `voice`/`voiceName`/`voiceId` | `speakerVoice`/`speakerVoiceId` |
| `channels..tts.` / `channels..accounts..tts.`（Discord 以外的所有頻道） | `...tts.providers.` |
| `channels..voice.tts.` / `channels..accounts..voice.tts.`（包括 Discord 在內的所有頻道） | `...voice.tts.providers.` |
| `plugins.entries.voice-call.config.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`） | `plugins.entries.voice-call.config.tts.providers.` |
| `plugins.entries.voice-call.config.tts.provider: "edge"` / `...tts.providers.edge` | `provider: "microsoft"` / `...tts.providers.microsoft` |
| `plugins.entries.voice-call.config.provider: "log"` | `"mock"` |
| `plugins.entries.voice-call.config.twilio.from` | `plugins.entries.voice-call.config.fromNumber` |
| `plugins.entries.voice-call.config.streaming.sttProvider` | `plugins.entries.voice-call.config.streaming.provider` |
| `plugins.entries.voice-call.config.streaming.openaiApiKey`/`sttModel`/`silenceDurationMs`/`vadThreshold` | `plugins.entries.voice-call.config.streaming.providers.openai.*` |
| `models.providers.*.api: "openai"` | `"openai-completions"`（閘道啟動時也會略過其 `api` 為未來／未知列舉值的提供者，而不會採取失敗關閉） |
| `browser.ssrfPolicy.allowPrivateNetwork` | `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` |
| `browser.profiles.*.driver: "extension"` | `"existing-session"` |
| `browser.relayBindHost` | 已移除（舊版 Chrome 擴充功能轉送設定） |
| `mcp.servers.*.type`（命令列介面原生別名） | `mcp.servers.*.transport` |
| `plugins.entries.codex.config.codexDynamicToolsProfile` | 已移除（Codex app-server 一律讓 Codex 原生工作區工具維持原生） |
| `commands.modelsWrite` | 已移除（`/models add` 已淘汰） |
| `agents.defaults/list[].silentReplyRewrite`、`surfaces.*.silentReplyRewrite` | 已移除（完全相符的 `NO_REPLY` 不再重寫為可見的備援文字） |
| `agents.defaults/list[].systemPromptOverride` | 已移除（OpenClaw 擁有產生的系統提示） |
| `agents.defaults/list[].embeddedPi` | `embeddedAgent` |
| `agents.defaults/list[].sandbox.perSession` | `sandbox.scope` |
| `agents.defaults.llm` | 已移除（針對較慢的模型／提供者逾時，請使用 `models.providers..timeoutSeconds`，並將其保持在代理程式／執行逾時上限以下） |
| 頂層 `memorySearch` | `agents.defaults.memorySearch` |
| `memorySearch.provider: "auto"` | `"openai"` |
| `memorySearch.store.path`（任何層級） | 已移除（記憶索引位於各代理程式資料庫中） |
| 頂層 `heartbeat` | `agents.defaults.heartbeat` / `channels.defaults.heartbeat` |
| `plugins.openai-codex` 原則 ID | `plugins.openai` |
| `tools.web.x_search.apiKey` | `plugins.entries.xai.config.webSearch.apiKey` |
| `session.maintenance.rotateBytes`、`session.parentForkMaxTokens` | 已移除（已淘汰） |
| `diagnostics.memoryPressureBundle` | `diagnostics.memoryPressureSnapshot` |
上述 `plugins.entries.voice-call.config.*` 資料列會在每次載入設定時由
Voice Call 外掛本身正規化，而不是由 `openclaw
doctor` 處理。該外掛也會記錄啟動警告並指向 `openclaw
doctor --fix`，但 doctor 目前不會針對這些鍵重寫
`openclaw.json`；執行階段實際套用變更的是外掛自身的正規化。
多帳號頻道的帳號預設值指引：
- 如果設定了兩個以上的 `channels..accounts` 項目，卻未設定 `channels..defaultAccount` 或 `accounts.default`，doctor 會警告備援路由可能選取非預期的帳號。
- 如果 `channels..defaultAccount` 設為未知的帳號 ID，doctor 會發出警告並列出已設定的帳號 ID。
如果你手動新增了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它會覆寫來自 `openclaw/plugin-sdk/llm` 的內建 OpenCode 目錄。這可能會強制模型使用錯誤的 API，或將成本歸零。Doctor 會發出警告，讓你移除覆寫並還原各模型的 API 路由與成本。
如果你的瀏覽器設定仍指向已移除的 Chrome 擴充功能路徑，Doctor 會將其正規化為目前主機本機的 Chrome MCP 附加模型（`browser.profiles.*.driver: "extension"` → `"existing-session"`；`browser.relayBindHost` 已移除）。
使用 `defaultProfile: "user"` 或已設定的 `existing-session` 設定檔時，Doctor 也會稽核主機本機的 Chrome MCP 路徑：
- 檢查預設自動連線設定檔所使用的同一台主機上是否已安裝 Google Chrome
- 檢查偵測到的 Chrome 版本，並在低於 Chrome 144 時發出警告
- 提醒你在瀏覽器檢查頁面中啟用遠端偵錯（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
Doctor 無法替你啟用 Chrome 端的設定。主機本機的 Chrome MCP 仍需要在閘道／節點主機上本機執行 Chromium 核心瀏覽器 144+、啟用遠端偵錯，並在瀏覽器中核准首次附加的同意提示。
此處的就緒狀態僅涵蓋本機附加的必要條件。現有工作階段會維持目前的 Chrome MCP 路由限制；`responsebody`、PDF 匯出、下載攔截及批次動作等進階路由仍需要受管理的瀏覽器或原始 CDP 設定檔。此檢查不適用於 Docker、沙箱、遠端瀏覽器或其他無頭流程，這些流程會繼續使用原始 CDP。
設定 OpenAI Codex OAuth 設定檔後，Doctor 會探測 OpenAI 授權端點，以驗證本機 Node/OpenSSL TLS 堆疊能否驗證憑證鏈。如果探測因憑證錯誤而失敗（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、憑證過期或自簽憑證），Doctor 會顯示平台專用的修正指引。在 macOS 上使用 Homebrew Node 時，修正方式通常是 `brew postinstall ca-certificates`。使用 `--deep` 時，即使閘道運作正常也會執行探測。
如果你先前在 `models.providers.openai-codex` 下新增了舊版 OpenAI 傳輸設定，它們可能會遮蔽內建的 Codex OAuth 提供者路徑。Doctor 在 Codex OAuth 旁看到這些舊傳輸設定時會發出警告，讓你移除或重寫過時的傳輸覆寫，並還原目前的路由行為。自訂 Proxy 與僅標頭覆寫仍受支援且不會觸發此警告，但這些自行定義的請求路由不符合隱含 Codex 選擇的資格。
Doctor 會檢查舊版 `openai-codex/*` 模型參照。原生 Codex 執行框架路由使用標準的 `openai/*` 模型參照，但僅有前綴絕不會選取 Codex。當執行階段原則未設定或為 `auto` 時，只有完全相符、未自行定義請求覆寫的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由符合資格。請參閱 [OpenAI 隱含代理程式執行階段](/zh-TW/providers/openai#implicit-agent-runtime)。
在 `--fix`／`--repair` 模式下，Doctor 會重寫受影響的預設代理程式與個別代理程式參照，包括主要模型、備援模型、圖片／影片生成模型、心跳偵測／子代理程式／壓縮覆寫、鉤子、頻道模型覆寫，以及過時的持久化工作階段路由狀態：
- `openai-codex/gpt-*` 會變成 `openai/gpt-*`。
- 對修復後的代理程式模型參照，Codex 意圖會移至提供者／模型範圍的 `agentRuntime.id: "codex"` 項目。
- 過時的整體代理程式執行階段設定與持久化工作階段執行階段固定項目會被移除，因為執行階段選擇是以提供者／模型為範圍。
- 除非修復後的舊版模型參照需要 Codex 路由才能保留舊的驗證路徑，否則會保留現有的提供者／模型執行階段原則。
- 會保留現有的模型備援清單並重寫其中的舊版項目；複製的個別模型設定會從舊版鍵移至標準的 `openai/*` 鍵。
- 會在所有探索到的代理程式工作階段儲存區中修復持久化工作階段的 `modelProvider`/`providerOverride`、`model`/`modelOverride`、備援通知及驗證設定檔固定項目。
- Doctor 會另行將過時的 `agentRuntime.id: "codex-cli"` 固定項目（不同的舊版執行階段 ID）修復為 `"codex"`，涵蓋 `agents.defaults`、`agents.list[]` 及 `models.providers.*` 模型項目。
- `/codex ...` 表示「從聊天中控制或繫結原生 Codex 對話」。
- `/acp ...` 或 `runtime: "acp"` 表示「使用外部 ACP/acpx 轉接器」。
將設定的模型或執行階段從 Codex 等外掛擁有的路由移開後，Doctor 也會掃描探索到的代理程式工作階段儲存區，尋找過時且自動建立的路由狀態。
`openclaw doctor --fix` 可以清除自動建立的過時狀態，例如 `modelOverrideSource: "auto"` 模型固定項目、執行階段模型中繼資料、固定的執行框架 ID、命令列介面工作階段繫結，以及其所屬路由已不再設定時的自動驗證設定檔覆寫。明確的使用者或舊版工作階段模型選擇會回報供手動檢閱，且保持不變；當不再需要該路由時，請使用 `/model ...`、`/new` 切換，或重設工作階段。
Doctor 可以將較舊的磁碟配置遷移至目前的結構：
- 工作階段儲存區與逐字稿：從 `~/.openclaw/sessions/` 遷移至 `~/.openclaw/agents//sessions/`
- 代理程式目錄：從 `~/.openclaw/agent/` 遷移至 `~/.openclaw/agents//agent/`
- WhatsApp 驗證狀態（Baileys）：從舊版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）遷移至 `~/.openclaw/credentials/whatsapp//...`（預設帳號 ID：`default`）
這些遷移會盡力執行且具冪等性；Doctor 將任何舊版資料夾留作備份時會發出警告。閘道／命令列介面也會在啟動時自動遷移舊版工作階段與代理程式目錄，讓歷程記錄／驗證／模型進入各代理程式的路徑，而無須手動執行 Doctor。WhatsApp 驗證刻意僅透過 `openclaw doctor` 遷移。Talk 提供者／提供者對應表的正規化會依結構相等性進行比較，因此只有鍵順序不同的差異不再觸發重複且無實際變更的 `doctor --fix` 變更。
Doctor 會掃描所有已安裝外掛的資訊清單，尋找已棄用的頂層功能鍵（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到時，它會提議將這些鍵移入 `contracts` 物件，並就地重寫資訊清單檔案。此遷移具冪等性；如果 `contracts` 已有相同的值，則會移除舊版鍵而不重複資料。
Doctor 也會檢查排程工作儲存區（預設為 `~/.openclaw/cron/jobs.json`，覆寫時為 `cron.store`），尋找排程器為了相容性仍可接受的舊工作結構。
目前的排程清理包括：
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- 頂層承載資料欄位（`message`、`model`、`thinking`、……）→ `payload`
- 頂層傳遞欄位（`deliver`、`channel`、`to`、`provider`、……）→ `delivery`
- 承載資料 `provider` 傳遞別名 → 明確的 `delivery.channel`
- 舊版 `notify: true` 網路鉤子備援工作 → 設定 `cron.webhook` 時，改為明確的網路鉤子傳遞；公告工作會保留其聊天傳遞並取得 `delivery.completionDestination`。未設定 `cron.webhook` 時，對於沒有目標的工作，會移除無作用的頂層 `notify` 標記（包括公告在內的現有傳遞會保留），因為執行階段傳遞絕不會讀取它。
閘道也會在載入時清理格式錯誤的排程資料列，讓有效工作繼續執行。原始格式錯誤的資料列會先複製到有效儲存區旁的 `jobs-quarantine.json`，再從 `jobs.json` 移除；Doctor 會回報已隔離的資料列，讓你手動檢閱或修復。
閘道啟動時會正規化執行階段投影並忽略頂層 `notify` 標記，但會保留持久化排程設定供 Doctor 修復。未設定 `cron.webhook` 時，Doctor 會針對沒有遷移目標的工作移除無作用的標記（`delivery.mode` 為 none／不存在、無法使用的網路鉤子目標，或現有的公告／聊天傳遞），且不變更現有傳遞，因此重複執行 `doctor --fix` 時，不再針對同一工作重複發出警告。如果已設定 `cron.webhook`，但它不是有效的 HTTP(S) URL，Doctor 仍會發出警告並保留標記，讓你修正 URL。
在 Linux 上，如果使用者的 crontab 仍呼叫舊版 `~/.openclaw/bin/ensure-whatsapp.sh`，Doctor 也會發出警告。現行 OpenClaw 不維護該主機本機指令碼，而且當排程無法連線至 systemd 使用者匯流排時，它可能會將錯誤的 `Gateway inactive` 訊息寫入 `~/.openclaw/logs/whatsapp-health.log`。請使用 `crontab -e` 移除過時的 crontab 項目；目前的健康狀態檢查請使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。
Doctor 會掃描每個代理程式工作階段目錄，尋找工作階段異常結束時留下的過時寫入鎖定檔案。它會針對找到的每個鎖定檔案回報：路徑、PID、PID 是否仍存活、鎖定存在時間，以及是否視為過時（PID 已終止、擁有者中繼資料格式錯誤、早於 30 分鐘，或可證實存活的 PID 屬於非 OpenClaw 處理程序）。在 `--fix`／`--repair` 模式下，它會自動移除擁有者已終止、孤立、被重複使用、中繼資料格式錯誤且過舊，或非 OpenClaw 的鎖定。仍由存活 OpenClaw 處理程序擁有的舊鎖定會予以回報但保留原位，避免 Doctor 中斷正在寫入逐字稿的處理程序。
Doctor 會掃描代理程式工作階段 JSONL 檔案，尋找由 2026.4.24 提示詞逐字稿重寫錯誤所建立的重複分支結構：一個含有 OpenClaw 內部執行階段上下文且已放棄的使用者輪次，以及一個包含相同可見使用者提示詞的作用中同層分支。在 `--fix`／`--repair` 模式下，Doctor 會在每個受影響檔案的原始檔案旁建立備份，並將逐字稿重寫至作用中分支，使閘道歷程記錄與記憶讀取器不再看到重複輪次。
狀態目錄是維持運作的腦幹。如果它消失，除非你在其他位置有備份，否則將失去工作階段、認證資訊、記錄和設定。
Doctor 會檢查：
- **狀態目錄遺失**：警告可能發生災難性的狀態資料遺失、提示重新建立目錄，並提醒你無法復原遺失的資料。
- **狀態目錄權限**：確認是否可寫入；提供修復權限的選項（偵測到擁有者／群組不符時，會發出 `chown` 提示）。
- **macOS 雲端同步狀態目錄**：當狀態解析至 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下方時發出警告，因為同步支援的路徑可能導致較慢的 I/O，以及鎖定／同步競爭。
- **Linux SD 或 eMMC 狀態目錄**：當狀態解析至 `mmcblk*` 掛載來源時發出警告，因為以 SD/eMMC 為基礎的隨機 I/O 可能較慢，且在寫入工作階段和認證資訊時耗損較快。
- **Linux 揮發性狀態目錄**：當狀態解析至 `tmpfs` 或 `ramfs` 時發出警告，因為工作階段、認證資訊、設定和 SQLite 狀態（包含 WAL／日誌附屬檔案）會在重新啟動時消失。Docker `overlay` 掛載刻意不會被標記，因為只要容器仍存在，其可寫入層便會在主機重新啟動後持續保留。
- **工作階段目錄遺失**：必須有 `sessions/` 和工作階段儲存目錄，才能保留歷史記錄並避免 `ENOENT` 當機。
- **逐字記錄不符**：當最近的工作階段項目缺少逐字記錄檔案時發出警告。
- **主要工作階段「單行 JSONL」**：當主要逐字記錄只有一行時加以標記（歷史記錄未持續累積）。
- **多個狀態目錄**：當多個主目錄中存在多個 `~/.openclaw` 資料夾，或 `OPENCLAW_STATE_DIR` 指向其他位置時發出警告（歷史記錄可能分散於不同安裝之間）。
- **遠端模式提醒**：若 `gateway.mode=remote`，doctor 會提醒你在遠端主機上執行（狀態位於該處）。
- **設定檔權限**：若群組／所有人可讀取 `~/.openclaw/openclaw.json`，則發出警告並提供將權限收緊為 `600` 的選項。
Doctor 會檢查驗證儲存區中的 OAuth 設定檔，在權杖即將到期／已到期時發出警告，並可在安全的情況下重新整理權杖。如果 Anthropic OAuth／權杖設定檔已過期，則會建議使用 Anthropic API 金鑰或 Anthropic 設定權杖路徑。重新整理提示只會在互動式執行（TTY）時出現；`--non-interactive` 會略過重新整理嘗試。
當 OAuth 重新整理永久失敗時（例如 `refresh_token_reused`、`invalid_grant`，或提供者要求你重新登入），doctor 會回報需要重新驗證，並印出要執行的確切 `openclaw models auth login --provider ...` 命令。
Doctor 也會回報因短期冷卻（速率限制／逾時／驗證失敗）或較長時間停用（帳務／點數失敗）而暫時無法使用的驗證設定檔。
權杖存放在 macOS Keychain 中的舊版 Codex OAuth 設定檔（採用檔案式附屬配置之前的舊版初始設定）只能由 doctor 修復。從互動式終端機執行一次 `openclaw doctor --fix`，將 Keychain 支援的舊版權杖就地移轉至 `auth-profiles.json`；之後，內嵌回合（Telegram、排程、子代理分派）會將其解析為標準 OpenAI OAuth 設定檔。
若已設定 `hooks.gmail.model`，doctor 會依目錄和允許清單驗證模型參照，並在其無法解析或不被允許時發出警告。
啟用沙箱時，doctor 會檢查 Docker 映像，並在目前映像遺失時提供建置或切換至舊版名稱的選項。
Doctor 會在 `openclaw doctor --fix`／`openclaw doctor --repair` 模式中移除由 OpenClaw 產生的舊版外掛相依套件暫存狀態：過時的產生式相依套件根目錄、舊安裝暫存目錄、早期內建外掛相依套件修復程式碼留下的套件區域殘留物，以及可能遮蔽目前內建資訊清單的孤立或已復原之受管理 npm 內建 `@openclaw/*` 外掛副本。Doctor 也會將主機的 `openclaw` 套件重新連結至宣告 `peerDependencies.openclaw` 的受管理 npm 外掛，使 `openclaw/plugin-sdk/*` 等套件區域執行階段匯入在更新或 npm 修復後仍能解析。
當設定參照可下載的外掛，但本機外掛登錄找不到它們時，doctor 也能重新安裝遺失的外掛（實質 `plugins.entries`、已設定的頻道／提供者／搜尋設定、已設定的代理執行階段）。套件更新期間，核心套件正在替換時，doctor 會避免重新安裝外掛套件；若更新後已設定的外掛仍需復原，請再次執行 `openclaw doctor --fix`。除下述容器映像啟動例外之外，閘道啟動和設定重新載入不會執行套件修復；外掛安裝仍是明確的 doctor／安裝／更新工作。
容器化閘道啟動有一個範圍有限的升級例外：當 `openclaw gateway run` 在新的 OpenClaw 版本上啟動時，會在就緒前執行安全的狀態移轉和既有的核心更新後外掛收斂，然後記錄每個版本的檢查點。此啟動流程可以清理過時的內建外掛記錄、修復本機外掛連結、在收斂路徑需要時重新安裝已設定的外掛套件，並檢查作用中的外掛承載內容。如果啟動無法安全修復，請先針對相同的已掛載狀態／設定，使用 `openclaw doctor --fix` 執行相同映像一次，再正常重新啟動容器。
Doctor 會偵測舊版閘道服務（launchd/systemd/schtasks），並提供移除它們及使用目前閘道連接埠安裝 OpenClaw 服務的選項。它也可以掃描其他類似閘道的服務，並印出清理提示。以設定檔命名的 OpenClaw 閘道服務視為第一級服務，不會標記為「額外」。
在 Linux 上，如果使用者層級的閘道服務遺失，但存在系統層級的 OpenClaw 閘道服務，doctor 不會自動安裝第二個使用者層級服務。請使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 檢查，然後移除重複項目；若閘道生命週期由系統監督程式管理，則設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
當 Matrix 頻道帳號有待處理或可採取動作的舊版狀態移轉時，doctor（在 `--fix`／`--repair` 模式中）會建立移轉前快照，然後執行盡力而為的移轉步驟：舊版 Matrix 狀態移轉和舊版加密狀態準備。這兩個步驟皆非致命；錯誤會記錄至日誌，啟動則繼續進行。在唯讀模式（`openclaw doctor` 且未使用 `--fix`）中，會完全略過此檢查。
Doctor 會在一般健康檢查流程中檢查裝置配對狀態，並回報：
- 待處理的首次配對要求
- 已配對裝置待處理的角色或範圍升級
- 裝置 ID 仍相符，但裝置身分已不再符合核准記錄時的公開金鑰不符修復
- 已配對記錄缺少核准角色的有效權杖
- 範圍偏離已核准配對基準的配對權杖
- 目前機器上的本機快取裝置權杖項目，其早於閘道端權杖輪替，或帶有過時的範圍中繼資料
Doctor 不會自動核准配對要求，也不會自動輪替裝置權杖。它會印出確切的後續步驟：
- 使用 `openclaw devices list` 檢查待處理要求
- 使用 `openclaw devices approve ` 核准確切的要求
- 使用 `openclaw devices rotate --device --role ` 輪替新的權杖
- 使用 `openclaw devices remove ` 移除並重新核准過時記錄
這可區分首次配對、待處理的角色／範圍升級，以及過時的權杖／裝置身分漂移，填補常見的「已配對但仍收到需要配對」漏洞。
Doctor 只會在發現警告時發出安全性注意事項，例如提供者在沒有允許清單的情況下對私訊開放，或原則設定具有危險性。使用 `openclaw security audit` 查看完整的安全性清單。
若以 systemd 使用者服務執行，doctor 會確保已啟用 linger，使閘道在登出後仍持續運作。
Doctor 會針對預設代理印出問題和動作，而非健康狀態清單：
- **Skills**：列出已允許但無法使用的 skill 名稱；使用 `openclaw skills check` 查看需求詳細資料和完整計數。
- **外掛**：只回報發生錯誤的外掛 ID；使用 `openclaw plugins list` 查看已載入、已匯入、已停用和套裝外掛清單。
- **外掛相容性警告**：標記與目前執行階段有相容性問題的外掛。
- **外掛診斷**：顯示外掛登錄在載入時發出的任何警告或錯誤。
- **TaskFlow 復原**：顯示需要手動檢查或取消的可疑受管理 TaskFlow。
- **Claude 命令列介面**：只回報二進位檔、驗證、設定檔、工作區或專案目錄問題；省略健康探測詳細資料。
Doctor 會檢查工作區啟動檔案（例如 `AGENTS.md`、`CLAUDE.md` 或其他插入的情境檔案）是否接近或超過設定的字元預算。它會回報每個檔案的原始字元數與插入後字元數、截斷百分比、截斷原因（`max/file` 或 `max/total`），以及插入的字元總數占總預算的比例。當檔案遭截斷或接近限制時，doctor 會印出調整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
Doctor 會檢查目前的 shell（zsh、bash、fish 或 PowerShell）是否已安裝 Tab 自動完成：
- 如果 shell 設定檔使用緩慢的動態自動完成模式（`source <(openclaw completion ...)`），doctor 會將其升級為較快的快取檔案版本。
- 如果設定檔中已設定自動完成，但快取檔案遺失，doctor 會自動重新產生快取。
- 如果完全未設定自動完成，doctor 會提示安裝（僅限互動模式；使用 `--non-interactive` 時略過）。
執行 `openclaw completion --write-state` 可手動重新產生快取。
當 `openclaw doctor --fix` 移除遺失的頻道外掛時，也會移除參照該外掛且懸空的頻道範圍設定：`channels.` 項目、指定該頻道的心跳偵測目標，以及 `agents.*.models["/*"]` 覆寫。這可防止頻道執行階段已消失，但設定仍要求閘道繫結至該頻道所造成的閘道啟動迴圈。
Doctor 會檢查本機閘道權杖驗證是否就緒。
- 如果權杖模式需要權杖，但不存在權杖來源，doctor 會提供產生權杖的選項。
- 如果 `gateway.auth.token` 由 SecretRef 管理但無法使用，doctor 會發出警告，且不會以純文字覆寫。
- `openclaw doctor --generate-gateway-token` 只會在未設定權杖 SecretRef 時強制產生。
某些修復流程需要檢查已設定的認證資訊，同時不削弱執行階段快速失敗的行為。
- `openclaw doctor --fix` 使用與狀態類命令相同的唯讀 SecretRef 摘要模型，以進行針對性的設定修復。
- 範例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修復會嘗試使用已設定且可用的機器人認證資訊。
- 如果 Telegram 機器人權杖透過 SecretRef 設定，但在目前的命令路徑中無法使用，doctor 會回報該認證資訊已設定但無法使用，並略過自動解析，而不會當機或誤報權杖缺失。
Doctor 會執行健康狀態檢查，並在閘道看似不健康時提議重新啟動。
Doctor 會檢查為預設代理程式設定的記憶搜尋嵌入提供者是否就緒。其行為取決於設定的後端與提供者：
- **QMD 後端**：探測 `qmd` 二進位檔是否可用且可啟動。若不可用，會輸出修復指引，包括 `npm install -g @tobilu/qmd`（或對應的 Bun 命令）以及手動指定二進位檔路徑的選項。
- **明確指定的本機提供者**：檢查是否有本機模型檔案或可辨識的遠端／可下載模型 URL。若缺少，會建議切換至遠端提供者。
- **明確指定的遠端提供者**（`openai`、`voyage` 等）：驗證環境或驗證儲存區中是否有 API 金鑰。若缺少，會輸出可採取行動的修復提示。
- **舊版自動提供者**：將 `memorySearch.provider: "auto"` 視為 OpenAI、檢查 OpenAI 的就緒狀態，並由 `doctor --fix` 將其改寫為 `provider: "openai"`。
如果有快取的閘道探測結果可用（檢查當時閘道狀態健康），doctor 會將其結果與命令列介面可見的設定交叉比對，並註記任何差異。Doctor 不會在預設路徑上發起新的嵌入連線測試；若要即時檢查提供者，請使用深度記憶狀態命令。
使用 `openclaw memory status --deep` 驗證執行階段的嵌入就緒狀態。
如果閘道狀態健康，doctor 會執行頻道狀態探測，並回報警告及建議的修復方式。
Doctor 會檢查已安裝的監督程式設定（launchd/systemd/schtasks）是否缺少預設值或使用過時的預設值（例如 systemd 的 network-online 相依性和重新啟動延遲）。發現不符時，會建議更新，並可將服務檔案／工作改寫為目前的預設值。
注意事項：
- `openclaw doctor` 會在改寫監督程式設定前提示確認。
- `openclaw doctor --yes` 會接受預設的修復提示。
- `openclaw doctor --fix` 會直接套用建議的修復而不提示（`--repair` 是其別名）。
- `openclaw doctor --fix --force` 會覆寫自訂的監督程式設定。
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 會讓 doctor 對閘道服務生命週期維持唯讀。它仍會回報服務健康狀態並執行非服務修復，但會略過服務安裝／啟動／重新啟動／引導啟動、監督程式設定改寫和舊版服務清理，因為該生命週期由外部監督程式負責。
- 在 Linux 上，當相符的 systemd 閘道單元處於作用中時，doctor 不會改寫命令／進入點中繼資料。它也會在重複服務掃描期間忽略非作用中、非舊版的額外類閘道單元，避免輔助服務檔案產生清理雜訊。
- 如果權杖驗證需要權杖，且 `gateway.auth.token` 由 SecretRef 管理，doctor 的服務安裝／修復會驗證 SecretRef，但不會將解析出的明文權杖值保存到監督程式服務的環境中繼資料中。
- Doctor 會偵測舊版 LaunchAgent、systemd 或 Windows 排程工作安裝中以內嵌方式儲存的受管理 `.env`／SecretRef 支援的服務環境值，並改寫服務中繼資料，使這些值改由執行階段來源載入，而不是來自監督程式定義。
- Doctor 會偵測服務命令是否在 `gateway.port` 變更後仍固定使用舊的 `--port`，並將服務中繼資料改寫為目前的連接埠。
- 如果權杖驗證需要權杖，且設定的權杖 SecretRef 無法解析，doctor 會阻止安裝／修復路徑，並提供可採取行動的指引。
- 如果 `gateway.auth.token` 和 `gateway.auth.password` 皆已設定，但 `gateway.auth.mode` 尚未設定，doctor 會阻止安裝／修復，直到明確設定模式為止。
- 對於 Linux 使用者 systemd 單元，doctor 在比較服務驗證中繼資料時，會同時納入 `Environment=` 和 `EnvironmentFile=` 來源來檢查權杖差異。
- 如果設定最後是由較新版本寫入，Doctor 服務修復會拒絕使用較舊的 OpenClaw 二進位檔改寫、停止或重新啟動閘道服務。請參閱[閘道疑難排解](/zh-TW/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
- 你隨時可以透過 `openclaw gateway install --force` 強制完整改寫。
Doctor 會檢查服務執行階段（PID、上次結束狀態），並在服務已安裝但實際上未執行時發出警告。它也會檢查閘道連接埠（預設為 `18789`）是否發生連接埠衝突，並回報可能原因（閘道已在執行、SSH 通道）。
當閘道服務在 Bun 或版本管理工具所管理的 Node 路徑（`nvm`、`fnm`、`volta`、`asdf` 等）上執行時，Doctor 會發出警告。Bun 無法開啟 OpenClaw 的 `node:sqlite` 狀態儲存區，因此修復程序會將舊版 Bun 服務遷移至 Node。版本管理工具路徑可能在升級後失效，因為服務不會載入你的 shell 初始化設定。當系統 Node 安裝可用時（Homebrew/apt/choco），Doctor 會提議遷移至該安裝。
新安裝或修復的 macOS LaunchAgent 會使用標準的系統 PATH（`/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是複製互動式 shell 的 PATH，因此由 Homebrew 管理的系統二進位檔仍可使用，同時 Volta、asdf、fnm、pnpm 和其他版本管理工具目錄不會改變 Node 子程序所解析到的版本。Linux 服務仍會保留明確的環境根目錄（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和穩定的使用者二進位檔目錄，但推測出的版本管理工具備援目錄只有在磁碟上確實存在時，才會寫入服務的 PATH。
Doctor 會保存所有設定變更，並標記精靈中繼資料以記錄此次 doctor 執行。
當工作區缺少記憶系統時，Doctor 會提出建議；如果工作區尚未納入 git 管理，則會輸出備份提示。
如需工作區結構和 git 備份的完整指南，請參閱 [/concepts/agent-workspace](/zh-TW/concepts/agent-workspace)（建議使用私有 GitHub 或 GitLab）。
## 相關內容
- [閘道操作手冊](/zh-TW/gateway)
- [閘道疑難排解](/zh-TW/gateway/troubleshooting)