使用 OpenClaw Doctor 修復系統配置與狀態錯誤

概覽

OpenClaw 的 doctor 指令是你維護系統穩定性與處理遷移問題的核心工具。它能自動偵測並修復過時的配置或狀態，確保你的 OpenClaw 執行環境始終保持在最佳狀態。

執行診斷檢查

當你遇到系統行為異常或配置錯誤時，可以透過此指令進行全面檢查。它會掃描你的 Node.js 環境與 Gateway 設定，並提供具體的修復建議。

開啟你的終端機並輸入以下指令來啟動診斷程序：

openclaw doctor

系統會自動分析目前的 JSON 設定檔與 webhook 狀態，並在終端機中顯示檢查結果。

自動修復配置

若診斷工具發現了損壞的設定，你可以直接使用修復模式來修正問題。這能省去手動編輯檔案的麻煩，並確保所有 API 參數符合最新規範。

若要自動套用修復建議，請在指令後方加上 --fix 旗標：

openclaw doctor --yes

程式會逐一詢問你是否要覆寫舊有的設定，確認後即可完成修復。

檢查系統健康狀態

除了修復功能外，你也可以利用此工具確認 Docker 容器與相關服務的連線狀況。這對於排除網路連線或權限問題非常有幫助。

使用以下指令來執行健康檢查，確保所有服務皆正常運作：

openclaw doctor --check-health

檢查完成後，若看到所有項目顯示為綠色的狀態，代表你的 OpenClaw 部署已準備就緒。

快速開始

想要檢查你的 OpenClaw 環境狀態，最簡單的方式就是執行診斷指令。這能確保你的 OpenClaw 安裝與 Gateway 設定都處於正常運作狀態。

執行以下指令來啟動診斷：

openclaw doctor

自動化與無頭模式

如果你正在編寫自動化腳本或是需要在伺服器上執行，可以使用這些參數來跳過互動式確認。這些指令能讓 OpenClaw 在無人值守的情況下自動處理常見問題。

若要接受所有預設選項，請執行：

openclaw doctor --yes

若要自動套用建議的修復方案，請執行：

openclaw doctor --repair

若要執行強制修復（這會覆蓋你自訂的 supervisor 設定），請執行：

openclaw doctor --repair --force

若要執行非互動式修復，僅套用安全的遷移（如設定正規化與磁碟狀態移動），請執行：

openclaw doctor --non-interactive

若要掃描系統服務中是否存在額外的 Gateway 安裝（例如 launchd、systemd 或 schtasks），請執行：

openclaw doctor --deep

如果你想在寫入任何變更之前先檢查目前的設定檔，可以查看 JSON 格式的設定內容：

cat ~/.openclaw/openclaw.json

AI Setup Assistant

OpenClaw 功能總覽

OpenClaw 透過一系列自動化檢查與修復機制，確保你的開發環境保持在最佳狀態。這些功能涵蓋了從環境配置、依賴管理到 Gateway 運作狀態的全面監控，幫助你快速排除潛在的技術障礙。

預檢與環境更新

在執行 git 安裝時，系統會提供選擇性的預檢更新功能，僅適用於互動式操作。它會檢查 UI 協議的新鮮度，若發現協議架構有更新，將自動重新建置 Control UI。此外，系統會執行健康檢查，並在發現問題時提示你是否需要重啟。

技能與插件狀態管理

系統會自動彙整技能狀態，明確標示出符合資格、缺失或被封鎖的項目，同時也會列出當前插件的運作狀態。

配置正規化與遷移

針對舊版的配置值，系統會進行正規化處理。這包括將舊有的 talk.* 欄位遷移至 talk.provider 與 talk.providers.<provider> 結構中。同時，系統會檢查瀏覽器配置，確認舊版 Chrome 擴充功能配置與 Chrome MCP 的就緒狀態。

提供者與 OAuth 警告

系統會針對 OpenCode 提供者覆寫發出警告（檢查 models.providers.opencode 與 models.providers.opencode-go），並針對 OpenAI Codex OAuth 設定檔發出 OAuth 遮蔽警告。此外，系統會檢查 OpenAI Codex OAuth 設定檔所需的 OAuth TLS 先決條件。

磁碟狀態與合約遷移

系統會處理舊版磁碟狀態的遷移，包含 sessions、agent 目錄以及 WhatsApp 驗證資訊。同時，它會執行舊版插件清單合約鍵值的遷移，將 speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders 與 webSearchProviders 統一遷移至 contracts。

Cron 任務與鎖定檔案處理

針對舊版 cron 儲存庫進行遷移，處理 jobId、schedule.cron、頂層 delivery/payload 欄位、payload provider 以及簡單的 notify: true webhook 回退任務。系統也會檢查 session 鎖定檔案，並清理過期的鎖定狀態。

狀態完整性與權限檢查

系統會驗證 sessions、transcripts 與狀態目錄的完整性及權限。若在本地執行，系統會自動檢查配置檔案的權限，確保其設定為 chmod 600。

模型驗證與工作區檢查

系統會檢查模型驗證的健康狀況，包括 OAuth 過期檢查、自動更新過期 token，並回報驗證設定檔的冷卻或停用狀態。同時，系統會偵測額外的工作區目錄（如 ~/openclaw）。

沙盒與服務遷移

當啟用沙盒功能時，系統會自動修復沙盒映像檔。此外，系統會執行舊版服務遷移，並偵測額外的 Gateway 實例。

Matrix 頻道與 Gateway 執行檢查

在 --fix 或 --repair 模式下，系統會處理 Matrix 頻道舊版狀態的遷移。同時，系統會進行 Gateway 執行檢查，例如偵測服務已安裝但未啟動，或是檢查快取的 launchd 標籤。

頻道狀態與 Supervisor 稽核

系統會從執行中的 Gateway 探測頻道狀態並發出警告。同時，它會稽核 Supervisor 配置（包含 launchd、systemd 或 schtasks），並提供選擇性的修復功能。

Gateway 最佳實踐與連接埠診斷

系統會檢查 Gateway 運作的最佳實踐，例如 Node.js 與 Bun 的比較，以及版本管理工具的路徑。同時，它會診斷 Gateway 的連接埠衝突問題（預設連接埠為 18789）。

安全性與 Gateway 驗證

系統會針對公開的 DM 政策發出安全性警告。針對本地 token 模式，系統會檢查 Gateway 驗證，若無 token 來源，將提供 token 生成選項，且不會覆寫現有的 token SecretRef 配置。

裝置配對與系統整合

系統會偵測裝置配對問題，包括待處理的首次配對請求、待處理的角色/範圍升級、過期的本地裝置 token 快取偏移，以及配對記錄的驗證偏移。在 Linux 系統上，系統會檢查 systemd linger 狀態。

效能監控與安裝檢查

系統會檢查工作區引導檔案的大小，並針對接近限制的內容檔案發出截斷警告。同時，系統會檢查 Shell 自動完成狀態並執行自動安裝或升級。此外，系統會驗證記憶體搜尋嵌入提供者的就緒狀態（檢查本地模型、遠端 API key 或 QMD 二進位檔）。

原始碼安裝檢查與配置寫入

系統會執行原始碼安裝檢查，包括 pnpm 工作區不匹配、缺失 UI 資產或缺失 tsx 二進位檔等問題。最後，系統會寫入更新後的配置檔案與 wizard 中繼資料。

AI Setup Assistant

Dreams UI 的 Backfill 與 Reset 功能

Control UI 的 Dreams 場景包含了針對 grounded dreaming 工作流程的 Backfill、Reset 與 Clear Grounded 操作。這些操作雖然使用了類似 Gateway doctor 的 RPC 方法，但它們並非 openclaw doctor CLI 修復或遷移流程的一部分。

這些功能的作用如下：

Backfill 會掃描當前工作區中歷史的 memory/YYYY-MM-DD.md 檔案，執行 grounded REM 日記處理，並將可逆的 backfill 條目寫入 DREAMS.md。
Reset 僅會從 DREAMS.md 中移除那些被標記為 backfill 的日記條目。
Clear Grounded 僅會移除那些來自歷史重播、且尚未累積即時回憶或日常支援的暫存 grounded 短期條目。

這些功能本身不會執行以下操作：

它們不會編輯 MEMORY.md。
它們不會執行完整的 doctor 遷移。
除非你明確先執行了暫存的 CLI 路徑，否則它們不會自動將 grounded 候選項目推送到即時短期提升儲存區。

如果你希望 grounded 的歷史重播能影響正常的深度提升通道，請改用 CLI 流程：

openclaw memory rem-backfill --path ./memory --stage-short-term

這會將 grounded 的持久候選項目暫存到短期 dreaming 儲存區，同時保留 DREAMS.md 作為審查介面。

詳細行為與原理

0) 選擇性更新 (git 安裝)

如果這是透過 git 下載的安裝，且 doctor 正在互動模式下執行，它會詢問是否要在執行 doctor 之前進行更新（執行 fetch/rebase/build）。

1) 設定正規化

如果設定檔包含舊版的數值格式（例如 messages.ackReaction 沒有針對特定頻道進行覆寫），doctor 會將其正規化為目前的 schema。

這包含舊版的 Talk 平面欄位。目前的公開 Talk 設定為 talk.provider + talk.providers.<provider>。Doctor 會將舊版的 talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey 格式重寫為 provider 對應表。

2) 舊版設定鍵遷移

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

Doctor 將會：

解釋發現了哪些舊版鍵值。
顯示它所執行的遷移操作。
使用更新後的 schema 重寫 ~/.openclaw/openclaw.json。

當 Gateway 在啟動時偵測到舊版設定格式時，也會自動執行 doctor 遷移，因此過時的設定無需手動介入即可修復。Cron job 儲存庫的遷移則由 openclaw doctor --fix 處理。

目前的遷移項目：

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
舊版 talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + talk.providers.<provider>
routing.agentToAgent → tools.agentToAgent
routing.transcribeAudio → tools.media.audio.models
messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
channels.discord.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.<provider>
channels.discord.accounts.<id>.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.accounts.<id>.voice.tts.providers.<provider>
plugins.entries.voice-call.config.tts.<provider> (openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.<provider>
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.*
bindings[].match.accountID → bindings[].match.accountId
對於具有命名 accounts 但仍保留單一帳號頂層頻道值的頻道，將這些帳號範圍的值移動到為該頻道選擇的提升帳號中（大多數頻道為 accounts.default；Matrix 可以保留現有的匹配命名/預設目標）
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
browser.profiles.*.driver: "extension" → "existing-session"
移除 browser.relayBindHost (舊版 extension relay 設定)

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 路由與成本計算。

2c) 瀏覽器遷移與 Chrome MCP 就緒狀態

如果你的瀏覽器設定仍指向已移除的 Chrome extension 路徑，doctor 會將其正規化為目前的 host-local Chrome MCP attach 模型：

browser.profiles.*.driver: "extension" 變為 "existing-session"
browser.relayBindHost 被移除

當你使用 defaultProfile: "user" 或已設定的 existing-session profile 時，doctor 也會審核 host-local Chrome MCP 路徑：

檢查預設自動連線的 profile 是否在同一主機上安裝了 Google Chrome
檢查偵測到的 Chrome 版本，並在低於 Chrome 144 時發出警告
提醒你在瀏覽器檢查頁面啟用遠端偵錯（例如 chrome://inspect/#remote-debugging、brave://inspect/#remote-debugging 或 edge://inspect/#remote-debugging）

Doctor 無法為你啟用瀏覽器端的設定。Host-local Chrome MCP 仍然需要：

在 gateway/node 主機上有 Chromium-based 瀏覽器 144+
瀏覽器在本地執行
在該瀏覽器中啟用遠端偵錯
在瀏覽器中核准第一次 attach 的同意提示

此處的就緒狀態僅關於本地 attach 的先決條件。Existing-session 保留目前的 Chrome MCP 路由限制；進階路由如 responsebody、PDF 匯出、下載攔截和批次操作仍需要託管瀏覽器或原始 CDP profile。

此檢查不適用於 Docker、sandbox、remote-browser 或其他 headless 流程。這些流程繼續使用原始 CDP。

2d) OAuth TLS 先決條件

當設定了 OpenAI Codex OAuth profile 時，doctor 會探測 OpenAI 授權端點，以驗證本地 Node/OpenSSL TLS stack 是否能驗證憑證鏈。如果探測因憑證錯誤（例如 UNABLE_TO_GET_ISSUER_CERT_LOCALLY、憑證過期或自簽憑證）而失敗，doctor 會列印平台特定的修復指引。在 macOS 上使用 Homebrew Node 時，修復方式通常是 brew postinstall ca-certificates。使用 --deep 時，即使 gateway 健康，探測也會執行。

2c) Codex OAuth provider 覆寫

如果你之前在 models.providers.openai-codex 下添加了舊版 OpenAI 傳輸設定，它們可能會遮蔽較新版本自動使用的內建 Codex OAuth provider 路徑。當 doctor 在 Codex OAuth 旁邊看到這些舊的傳輸設定時會發出警告，讓你移除或重寫過時的傳輸覆寫，以取回內建的路由/後備行為。自訂代理和僅標頭的覆寫仍受支援，且不會觸發此警告。

3) 舊版狀態遷移 (磁碟佈局)

Doctor 可以將舊的磁碟佈局遷移到目前的結構中：

Sessions 儲存庫 + 轉錄檔：
- 從 ~/.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 目錄，因此歷史記錄/驗證/模型會落在每個 agent 的路徑中，無需手動執行 doctor。WhatsApp 驗證刻意僅透過 openclaw doctor 遷移。Talk provider/provider-map 正規化現在透過結構相等性進行比較，因此僅鍵順序不同的差異不再觸發重複的無效 doctor --fix 變更。

3a) 舊版外掛清單遷移

Doctor 掃描所有已安裝的外掛清單，尋找已棄用的頂層能力鍵 (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders)。當發現時，它會提議將它們移動到 contracts 物件中，並就地重寫清單檔案。此遷移是冪等的；如果 contracts 鍵已經具有相同的值，則會移除舊版鍵，而不會複製資料。

3b) 舊版 cron 儲存庫遷移

Doctor 也會檢查 cron job 儲存庫（預設為 ~/.openclaw/cron/jobs.json，或覆寫後的 cron.store），尋找排程器為了相容性仍接受的舊版工作格式。

目前的 cron 清理包含：

jobId → id
schedule.cron → schedule.expr
頂層 payload 欄位 (message, model, thinking, …) → payload
頂層傳遞欄位 (deliver, channel, to, provider, …) → delivery
payload provider 傳遞別名 → 明確的 delivery.channel
簡單的舊版 notify: true webhook 後備工作 → 明確的 delivery.mode="webhook" 搭配 delivery.to=cron.webhook

Doctor 僅在不改變行為的情況下自動遷移 notify: true 工作。如果工作結合了舊版通知後備與現有的非 webhook 傳遞模式，doctor 會發出警告並將該工作留給手動審查。

3c) Session 鎖定清理

Doctor 掃描每個 agent session 目錄以尋找過時的寫入鎖定檔案 — 即 session 異常退出後留下的檔案。對於找到的每個鎖定檔案，它會報告：路徑、PID、PID 是否仍存活、鎖定時間，以及它是否被視為過時（PID 已死或超過 30 分鐘）。在 --fix / --repair 模式下，它會自動移除過時的鎖定檔案；否則會列印註記並指示你使用 --fix 重新執行。

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

狀態目錄是運作的核心。如果它消失了，你將失去 sessions、憑證、記錄檔和設定（除非你在其他地方有備份）。

Doctor 檢查：

狀態目錄遺失：警告狀態遺失的災難性後果，提示重新建立目錄，並提醒它無法復原遺失的資料。
狀態目錄權限：驗證可寫入性；提議修復權限（並在偵測到擁有者/群組不匹配時發出 chown 提示）。
macOS 雲端同步狀態目錄：當狀態解析在 iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) 或 ~/Library/CloudStorage/... 下時發出警告，因為同步備份的路徑可能導致較慢的 I/O 和鎖定/同步競爭。
Linux SD 或 eMMC 狀態目錄：當狀態解析到 mmcblk* 掛載來源時發出警告，因為 SD 或 eMMC 支援的隨機 I/O 在 session 和憑證寫入下可能較慢且磨損較快。
Session 目錄遺失：sessions/ 和 session 儲存目錄是持久化歷史記錄並避免 ENOENT 當機所必需的。
轉錄檔不匹配：當最近的 session 項目缺少轉錄檔時發出警告。
主要 session “1-line JSONL”：當主要轉錄檔只有一行時標記（歷史記錄未累積）。
多個狀態目錄：當多個 ~/.openclaw 資料夾跨越家目錄存在，或當 OPENCLAW_STATE_DIR 指向其他地方時發出警告（歷史記錄可能在不同安裝之間分裂）。
遠端模式提醒：如果 gateway.mode=remote，doctor 提醒你在遠端主機上執行它（狀態存在那裡）。
設定檔權限：如果 ~/.openclaw/openclaw.json 是群組/全域可讀的，則發出警告並提議收緊為 600。

5) 模型驗證健康狀況 (OAuth 過期)

Doctor 檢查驗證儲存庫中的 OAuth profile，在權杖即將過期/已過期時發出警告，並可在安全時重新整理它們。如果 Anthropic OAuth/權杖 profile 過時，它會建議使用 Anthropic API key 或 Anthropic setup-token 路徑。重新整理提示僅在互動模式 (TTY) 下執行時出現；--non-interactive 會跳過重新整理嘗試。

當 OAuth 重新整理永久失敗時（例如 refresh_token_reused、invalid_grant 或 provider 要求你重新登入），doctor 會報告需要重新驗證，並列印出確切的 openclaw models auth login --provider ... 指令供你執行。

Doctor 也會報告因以下原因暫時無法使用的驗證 profile：

短期冷卻（速率限制/逾時/驗證失敗）
長期停用（帳單/信用失敗）

6) Hooks 模型驗證

如果設定了 hooks.gmail.model，doctor 會根據目錄和允許清單驗證模型參考，並在無法解析或不被允許時發出警告。

7) Sandbox 圖像修復

當啟用沙盒時，doctor 會檢查 Docker 圖像，如果目前的圖像遺失，則提議建置或切換到舊版名稱。

7b) 綁定外掛執行時期相依性

Doctor 僅針對目前設定中啟用或由其綁定清單預設啟用的綁定外掛驗證執行時期相依性，例如 plugins.entries.discord.enabled: true、舊版 channels.discord.enabled: true 或預設啟用的綁定 provider。如果遺失任何項目，doctor 會在 openclaw doctor --fix / openclaw doctor --repair 模式下報告這些套件並安裝它們。外部外掛仍使用 openclaw plugins install / openclaw plugins update；doctor 不會為任意外掛路徑安裝相依性。

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

Doctor 偵測舊版 gateway 服務 (launchd/systemd/schtasks) 並提議移除它們，並使用目前的 gateway 連接埠安裝 OpenClaw 服務。它也可以掃描額外的 gateway 類服務並列印清理提示。以 profile 命名的 OpenClaw gateway 服務被視為一等公民，不會被標記為「額外」。

8b) 啟動 Matrix 遷移

當 Matrix 頻道帳號有待處理或可操作的舊版狀態遷移時，doctor（在 --fix / --repair 模式下）會建立遷移前快照，然後執行盡力而為的遷移步驟：舊版 Matrix 狀態遷移和舊版加密狀態準備。這兩個步驟皆為非致命性；錯誤會被記錄，啟動會繼續。在唯讀模式（不帶 --fix 的 openclaw doctor）下，此檢查會完全跳過。

8c) 裝置配對與驗證漂移

Doctor 現在將裝置配對狀態檢查作為正常健康檢查的一部分。

它報告的內容：

待處理的首次配對請求
已配對裝置的待處理角色升級
已配對裝置的待處理範圍升級
公鑰不匹配修復（裝置 id 仍匹配，但裝置識別碼不再匹配核准的記錄）
缺少核准角色之有效權杖的已配對記錄
範圍漂移到核准配對基準之外的已配對權杖
目前機器上早於 gateway 端權杖輪替或帶有過時範圍元資料的本地快取裝置權杖項目

Doctor 不會自動核准配對請求或自動輪替裝置權杖。它會列印確切的下一步：

使用 openclaw devices list 檢查待處理請求
使用 openclaw devices approve <requestId> 核准確切請求
使用 openclaw devices rotate --device <deviceId> --role <role> 輪替新權杖
使用 openclaw devices remove <deviceId> 移除並重新核准過時記錄

這解決了常見的「已配對但仍收到需要配對」的問題：doctor 現在區分了首次配對與待處理的角色/範圍升級，以及過時的權杖/裝置識別碼漂移。

9) 安全警告

當 provider 在沒有允許清單的情況下對 DM 開放，或政策以危險方式設定時，doctor 會發出警告。

10) systemd linger (Linux)

如果以 systemd 使用者服務執行，doctor 會確保啟用 lingering，以便 gateway 在登出後保持運作。

11) 工作區狀態 (技能、外掛與舊版目錄)

Doctor 列印預設 agent 的工作區狀態摘要：

技能狀態：計算符合資格、缺少需求和被允許清單封鎖的技能數量。
舊版工作區目錄：當 ~/openclaw 或其他舊版工作區目錄與目前工作區並存時發出警告。
外掛狀態：計算已載入/已停用/錯誤的外掛數量；列出任何錯誤的外掛 ID；報告綁定外掛能力。
外掛相容性警告：標記與目前執行時期有相容性問題的外掛。
外掛診斷：呈現外掛註冊表發出的任何載入時警告或錯誤。

11b) Bootstrap 檔案大小

Doctor 檢查工作區 bootstrap 檔案（例如 AGENTS.md、CLAUDE.md 或其他注入的上下文檔案）是否接近或超過設定的字元預算。它報告每個檔案的原始與注入字元數、截斷百分比、截斷原因 (max/file 或 max/total)，以及注入字元總數佔總預算的比例。當檔案被截斷或接近限制時，doctor 會列印調整 agents.defaults.bootstrapMaxChars 和 agents.defaults.bootstrapTotalMaxChars 的提示。

11c) Shell 自動完成

Doctor 檢查目前 shell (zsh, bash, fish 或 PowerShell) 是否安裝了 tab 自動完成：

如果 shell profile 使用緩慢的動態完成模式 (source <(openclaw completion ...) )，doctor 會將其升級為更快的快取檔案變體。
如果 profile 中設定了完成功能但缺少快取檔案，doctor 會自動重新產生快取。
如果完全沒有設定完成功能，doctor 會提示安裝它（僅限互動模式；--non-interactive 會跳過）。

執行 openclaw completion --write-state 以手動重新產生快取。

12) Gateway 驗證檢查 (本地權杖)

Doctor 檢查本地 gateway 權杖驗證的就緒狀態。

如果權杖模式需要權杖且沒有權杖來源，doctor 會提議產生一個。
如果 gateway.auth.token 是由 SecretRef 管理但無法取得，doctor 會發出警告，且不會以純文字覆寫它。
openclaw doctor --generate-gateway-token 僅在未設定權杖 SecretRef 時強制產生。

12b) 唯讀 SecretRef 感知修復

某些修復流程需要檢查已設定的憑證，而不削弱執行時期的 fail-fast 行為。

openclaw doctor --fix 現在針對目標設定修復使用與狀態系列指令相同的唯讀 SecretRef 摘要模型。
範例：Telegram allowFrom / groupAllowFrom @username 修復會嘗試在可用時使用已設定的 bot 憑證。
如果 Telegram bot 權杖是透過 SecretRef 設定但無法在目前指令路徑中取得，doctor 會報告該憑證已設定但無法取得，並跳過自動解析，而不是當機或錯誤地報告權杖遺失。

13) Gateway 健康檢查 + 重啟

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

13b) 記憶體搜尋就緒狀態

Doctor 檢查預設 agent 的已設定記憶體搜尋 embedding provider 是否就緒。行為取決於已設定的後端和 provider：

QMD 後端：探測 qmd 二進位檔是否可用且可啟動。如果不是，列印修復指引，包含 npm 套件和手動二進位路徑選項。
明確的本地 provider：檢查本地模型檔案或識別出的遠端/可下載模型 URL。如果遺失，建議切換到遠端 provider。
明確的遠端 provider (openai, voyage 等)：驗證環境或驗證儲存庫中是否存在 API key。如果遺失，列印可操作的修復提示。
自動 provider：先檢查本地模型可用性，然後按自動選擇順序嘗試每個遠端 provider。

當 gateway 探測結果可用時（檢查時 gateway 是健康的），doctor 會將其結果與 CLI 可見的設定進行交叉比對，並註記任何差異。

使用 openclaw memory status --deep 在執行時期驗證 embedding 就緒狀態。

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 設定。
如果權杖驗證需要權杖且 gateway.auth.token 是由 SecretRef 管理，doctor 服務安裝/修復會驗證 SecretRef，但不會將解析後的純文字權杖值持久化到 supervisor 服務環境元資料中。
如果權杖驗證需要權杖且已設定的權杖 SecretRef 未解析，doctor 會以可操作的指引封鎖安裝/修復路徑。
如果同時設定了 gateway.auth.token 和 gateway.auth.password 且未設定 gateway.auth.mode，doctor 會封鎖安裝/修復，直到明確設定模式。
對於 Linux user-systemd 單元，doctor 權杖漂移檢查現在在比較服務驗證元資料時包含 Environment= 和 EnvironmentFile= 來源。
你隨時可以透過 openclaw gateway install --force 強制執行完整重寫。

16) Gateway 執行時期 + 連接埠診斷

Doctor 檢查服務執行時期 (PID, 最後退出狀態)，並在服務已安裝但未實際執行時發出警告。它也會檢查 gateway 連接埠（預設 18789）上的連接埠衝突，並報告可能的原因（gateway 已在執行、SSH tunnel）。

17) Gateway 執行時期最佳實踐

當 gateway 服務在 Bun 或版本管理 Node 路徑 (nvm, fnm, volta, asdf 等) 上執行時，doctor 會發出警告。WhatsApp + 頻道需要 Node，而版本管理路徑在升級後可能會中斷，因為服務不會載入你的 shell init。Doctor 提議在可用時遷移到系統 Node 安裝 (Homebrew/apt/choco)。

18) 設定寫入 + 精靈元資料

Doctor 持久化任何設定變更，並蓋上精靈元資料以記錄 doctor 的執行。

19) 工作區提示 (備份 + 記憶體系統)

Doctor 在缺少時建議工作區記憶體系統，如果工作區尚未納入 git，則列印備份提示。

請參閱 /concepts/agent-workspace 以取得工作區結構和 git 備份（建議使用私有 GitHub 或 GitLab）的完整指南。

AI Setup Assistant

OpenClaw Expert

還是卡住了？

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