openclaw doctor

針對閘道、頻道、外掛、Skills、模型路由、本機狀態及設定遷移進行健康檢查與快速修復。當某項功能未如預期運作，而你希望透過一個命令找出問題時，請使用此命令。

相關內容：

• 疑難排解：疑難排解
• 安全性稽核：安全性

運作模式

Doctor 有五種運作模式：

當自動化作業需要穩定的結果時，請優先使用 --lint。當人工操作人員希望 Doctor 編輯設定或狀態時，請優先使用 --fix。

範例

openclaw doctoropenclaw doctor --lintopenclaw doctor --lint --jsonopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --deepopenclaw doctor --fixopenclaw doctor --fix --non-interactiveopenclaw doctor --generate-gateway-tokenopenclaw doctor --post-upgradeopenclaw doctor --post-upgrade --jsonopenclaw doctor --state-sqlite compactopenclaw doctor --state-sqlite compact --jsonopenclaw doctor --session-sqlite inspect --session-sqlite-all-agentsopenclaw doctor --session-sqlite dry-run --session-sqlite-agent main --jsonopenclaw doctor --session-sqlite import --session-sqlite-all-agentsopenclaw doctor --session-sqlite validate --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite compact --session-sqlite-all-agentsopenclaw doctor --session-sqlite recover --github-issueopenclaw doctor --session-sqlite restore --session-sqlite-all-agents

若要檢查特定頻道的權限，請使用頻道探測功能，而非 doctor：

openclaw channels capabilities --channel discord --target channel:<channel-id>openclaw channels status --probe

channels capabilities 會回報機器人對特定頻道目標的實際權限。channels status --probe 會稽核所有已設定的頻道及語音自動加入目標。

選項

--severity-min、--all、--only 和 --skip 僅能與 --lint 一起使用；--json 可與 --lint、--post-upgrade、--state-sqlite 和 --session-sqlite 一起使用。

Lint 模式

openclaw doctor --lint 是唯讀的：不顯示提示、不進行修復，也不重寫設定／狀態。

openclaw doctor --lintopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --jsonopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

供使用者閱讀的輸出很精簡：

doctor --lint：已執行 6 項檢查，發現 1 個項目  [warning] core/doctor/gateway-config gateway.mode - gateway.mode 未設定；閘道將無法啟動。    修復方式：執行 `openclaw configure` 並設定閘道模式（本機／遠端），或執行 `openclaw config set gateway.mode local`。

JSON 輸出是供指令碼使用的介面：

{  "ok": false,  "checksRun": 5,  "checksSkipped": 0,  "findings": [    {      "checkId": "core/doctor/gateway-config",      "severity": "warning",      "message": "gateway.mode 未設定；閘道將無法啟動。",      "path": "gateway.mode",      "fixHint": "執行 `openclaw configure` 並設定閘道模式（本機／遠端），或執行 `openclaw config set gateway.mode local`。"    }  ]}

結束代碼：

--severity-min 同時控制要顯示哪些發現項目及結束門檻：即使存在嚴重性較低的 info／warning 發現項目，openclaw doctor --lint --severity-min error 仍可能不顯示任何內容並以 0 結束。

--all 控制在套用嚴重性篩選前要選取哪些檢查。預設的 Lint 執行會排除深度、歷史性或較可能揭露可修復舊版殘留項目的檢查；使用 --all 可執行完整清單。--only <id> 是最精確的選取器，可依 ID 執行任何已註冊的檢查。

core/doctor/local-audio-acceleration 會回報自動選取的本機 STT 命令、個別的可用／要求／觀測到的後端證據，以及備援順序，而不會載入語音模型。它會輸出資訊性發現項目，因此請加入 --severity-min info 以顯示該項目。

結構化健康檢查

現代化的 Doctor 檢查使用簡潔的拆分式合約：

detect(ctx, scope?) -> HealthFinding[]repair?(ctx, findings) -> HealthRepairResult

detect() 為 doctor --lint 提供功能。repair() 是選用項目，且僅會在 doctor --fix／doctor --repair 下執行。尚未遷移至此形式的檢查仍使用舊版 Doctor 貢獻流程。

修復情境可攜帶 dryRun／diff 要求；修復結果可傳回結構化的 diffs（設定／檔案編輯）及 effects（服務、程序、套件、狀態或其他副作用），因此轉換後的檢查可逐步支援 doctor --fix --dry-run，而無須將變更規劃移入 detect()。

repair() 會回報 status: "repaired" | "skipped" | "failed"（省略狀態即表示 repaired）。當修復傳回 skipped 或 failed 時，Doctor 會回報原因，並略過該檢查的驗證。修復成功後，Doctor 會針對已修復的發現項目重新執行有範圍限制的 detect()；如果發現項目仍然存在，Doctor 會回報修復警告，而不會將該變更視為已完成。

發現項目包含：

現代化的核心 doctor 檢查仍附加於擁有其面向使用者之 doctor／doctor --fix 行為的有序 doctor 貢獻項目。共用的結構化健康狀態登錄是擴充點：當內建套件與外掛支援的檢查所屬套件在目前命令路徑中註冊這些檢查後，它們會在核心 doctor 檢查之後執行。openclaw/plugin-sdk/health 為外掛作者公開相同的契約。

選取檢查

openclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --skip core/doctor/skills-readinessopenclaw doctor --lint --all --skip core/doctor/session-locks

--only 與 --skip 接受完整的檢查 ID，並可重複指定。如果某個 --only ID 尚未註冊，就不會針對該 ID 執行任何檢查；請使用輸出中的 checksRun／checksSkipped，確認聚焦式閘門選取了你預期的檢查。

升級後模式

openclaw doctor --post-upgrade 會執行外掛相容性探測，供建置或升級後串接使用。發現項目會輸出至標準輸出；若任何發現項目具有 level: "error"，結束代碼為 1。加入 --json 可取得機器可讀的封裝格式（{ probesRun, findings }），適用於 CI、社群的 fork-upgrade skill，以及其他升級後的冒煙測試工具。如果已安裝的外掛索引遺失或格式錯誤，JSON 模式仍會輸出該封裝格式，並包含一筆 plugin.index_unavailable 錯誤發現項目。

容器映像啟動是一般「更新後執行 doctor」流程的例外。當 openclaw gateway run 在新版 OpenClaw 上啟動時，會先執行安全的狀態與外掛修復，再回報已就緒。若無法安全完成修復，啟動程序會結束，並指示你先對相同的掛載狀態／設定使用相同映像執行一次 openclaw doctor --fix，再以正常方式重新啟動容器。

共用狀態 SQLite 壓縮

openclaw doctor --state-sqlite compact 是針對位於 <state-dir>/state/openclaw.sqlite 的標準共用狀態資料庫所進行的明確離線維護。它不接受任意資料庫路徑、絕不會由一般閘道操作叫用，也不屬於 openclaw doctor --fix 的一部分。

請先停止閘道並建立經驗證的備份：

openclaw gateway stopopenclaw backup create --verifyopenclaw doctor --state-sqlite compact --jsonopenclaw gateway start

此命令：

1. 要求標準共用狀態路徑上存在一般檔案。若資料庫不存在，會回報為 skipped 並成功結束。
2. 在執行檢查點或變更檔案前，會驗證目前支援的結構描述版本及 schema_meta.role = "global"。
3. 要求 wal_checkpoint(TRUNCATE) 處於非忙碌狀態。如果檢查點忙碌，請停止任何仍在執行的 OpenClaw 程序後重試。
4. 將 auto_vacuum 設為 INCREMENTAL、執行完整的 VACUUM，然後再次執行檢查點。
5. 執行 quick_check、integrity_check 與 foreign_key_check，接著重新套用資料庫與 SQLite 附屬檔案僅限擁有者的權限。

JSON 輸出會回報壓縮前後的資料庫與 WAL 大小、自由清單頁數、頁面大小及 auto_vacuum 值，並提供回收的位元組數，以及 quick_check 和 integrity_check 的結果。foreign_key_check 採取失敗即關閉的強制策略，沒有獨立的成功欄位。SQLite 回報的 auto_vacuum 值中，0 表示無、1 表示完整、2 表示增量。

若結構描述過舊、比目前執行中的 OpenClaw 建置更新，或屬於代理程式資料庫，壓縮會在不進行變更的情況下失敗。若共用狀態的結構描述較舊，請先執行 openclaw doctor --fix。若結構描述較新，請還原相容的備份或升級 OpenClaw。

工作階段 SQLite 遷移

OpenClaw 會在閘道啟動期間及執行 openclaw doctor --fix 時，自動將舊版工作階段資料列與逐字記錄歷程匯入各代理程式的 SQLite 資料庫。openclaw doctor --session-sqlite <mode> 是用於該遷移的針對性檢查與驗證工具。目前執行階段的工作階段資料列位於 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。舊版 sessions.json 檔案是遷移來源。使用中的逐字記錄 JSONL 檔案會在成功匯入後，移出作用中的工作階段目錄並封存；封存層級的 JSONL 檔案仍是支援用途的成品，而非執行階段的後援機制。

模式：

選取器：

• 預設：已設定的預設代理程式儲存區，前提是該舊版儲存區檔案存在。
• --session-sqlite-agent <id>：一個已設定的代理程式。
• --session-sqlite-all-agents：已設定的代理程式儲存區，加上探索到的代理程式儲存區。
• --session-sqlite-store <path>：一個明確指定的舊版 sessions.json 路徑。

手動檢查順序：

openclaw doctor --session-sqlite inspect --session-sqlite-all-agentsopenclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite import --session-sqlite-all-agentsopenclaw doctor --session-sqlite validate --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite compact --session-sqlite-all-agentsopenclaw doctor --session-sqlite recover --github-issue

在具有重要歷史記錄的安裝環境中執行 import 前，請先備份 OpenClaw 狀態目錄。若所選的舊版項目未存在於 SQLite 中、工作階段 ID 不同，或逐字記錄事件數量不同，validate 會以非零狀態結束。使用 --session-sqlite-store <path> 時，請確認報告包含預期的目標數量；明確指定但不存在的儲存區路徑不會選取任何目標。

SQLite 刪除作業會先回收資料庫內部的頁面，不一定會立即縮小資料庫檔案。刪除或封存大型逐字記錄後，請執行 openclaw doctor --session-sqlite compact --session-sqlite-all-agents，以建立 WAL 檔案的檢查點、執行 VACUUM，並報告處理前後的資料庫與 WAL 大小。壓縮要求目標是具有目前代理程式結構描述的普通檔案、包含所選代理程式的持久擁有者中繼資料，且 doctor 程序中沒有開啟中的控制代碼。這是明確的離線維護作業：請先停止閘道，避免正常寫入與檢查點或 VACUUM 發生競爭。

每次匯入都會先在 ~/.openclaw/session-sqlite-migration-runs/ 下寫入資訊清單，再將逐字記錄成品移入封存區。如果成品移動後，啟動時回報工作階段 SQLite 遷移失敗，請執行復原：

openclaw doctor --session-sqlite recover --github-issue

復原會選取最新的失敗遷移資訊清單，只還原該資訊清單封存的成品、驗證受影響的目標、重新整理經過清理的 .failure.md 與 .failure.json 報告，並準備 GitHub 議題本文，其中不包含逐字記錄內容、原始環境資訊、秘密及無界限的設定。若沒有失敗的遷移資訊清單，但所選代理程式的 SQLite 資料庫已損毀、不是資料庫，或只有日誌側檔而沒有主要資料庫，復原作業會將完整檔案集複製到暫存檢查目錄。SQLite 可在這份可丟棄的副本中回復有效的熱日誌，再執行 quick_check、integrity_check 與 foreign_key_check，而原始鑑識檔案則維持不變。完整性檢查失敗或存在孤立側檔時，會將整組探索到的檔案重新命名，加上同一個 .corrupt-<timestamp> 後綴，以保留 DB、WAL、SHM 與回復日誌檔案。若重新命名失敗且錯誤已被攔截，系統會在回報失敗前將已移動的檔案移回，因此不會在未告知的情況下拆散仍可復原的檔案集。復原前請停止閘道；複製或重新命名仍持續變動的 SQLite 檔案集並不安全，而且在不同作業系統上的行為也有所不同。使用 --github-issue --yes 時，doctor 會透過 GitHub 命令列介面在 openclaw/openclaw 建立議題；若未確認，則會寫入本機支援報告，並輸出預先填妥的議題 URL。

restore 仍是較低階的復原操作。它會使用資訊清單中的 sourcePath -> archivePath 記錄，僅在原始路徑不存在時，才將封存的成品移回；若兩個路徑都存在，則回報衝突，並將 SQLite 資料庫保留在原處。

工作階段 SQLite 遷移後降級

啟動較舊、以檔案為後端的 OpenClaw 版本之前，請還原已封存的舊版逐字記錄成品：

openclaw doctor --session-sqlite restore --session-sqlite-all-agents

較舊版本會讀取 sessions.json 項目，以及這些項目中記錄的 sessionFile 路徑。SQLite 遷移後，成功匯入會將使用中的 JSONL 逐字記錄移至 session-sqlite-import-archive/，因此在還原作業將資訊清單中記錄的成品移回原始路徑前，較舊的執行階段無法看到這些歷程。

還原不會刪除 SQLite 資料。在切換至 SQLite 後建立的工作階段只存在於 SQLite 中，不會出現在較舊的執行階段裡。如果你之後再次升級，請執行上述一般遷移驗證流程，讓 OpenClaw 能在匯入前，比對已還原的舊版成品與 SQLite 資料列。

注意事項

• 在 Nix 模式（OPENCLAW_NIX_MODE=1）下，唯讀的 doctor 檢查仍可運作，但 doctor --fix、doctor --repair、doctor --yes 和 doctor --generate-gateway-token 會停用，因為 openclaw.json 不可變更。請改為編輯此安裝的 Nix 來源；若使用 nix-openclaw，請參閱以代理程式為優先的快速入門。
• 互動式提示（鑰匙圈/OAuth 修正等）僅在 stdin 是終端介面，且未設定 --non-interactive 時執行。無終端執行（排程、Telegram、無終端機）會略過提示。
• 非互動式 doctor 執行會略過預先載入外掛，讓無終端健康檢查維持快速。互動式工作階段仍會載入舊版健康檢查/修復流程所需的外掛介面。
• --lint 比 --non-interactive 更嚴格：一律唯讀、絕不顯示提示，也絕不套用安全移轉。若要讓 doctor 進行變更，請使用 doctor --fix 或 doctor --repair。
• Doctor 預設不會在檢查密鑰時執行 exec SecretRef。只有在你確實希望 doctor 執行這些已設定的密鑰解析器時，才使用 --allow-exec（可搭配或不搭配 --lint）。
• 任何設定寫入（包括 --fix 修復）都會將備份輪替至 ~/.openclaw/openclaw.json.bak（並使用編號為 .bak.1 到 .bak.4 的循環備份）。--fix 也會移除結構描述驗證所回報的未知設定鍵，並逐一列出每個移除項目；更新進行期間會略過此操作，以免部分寫入的升級狀態在移轉完成前遭到移除。
• 當另一個監督程式負責閘道生命週期時，請設定 OPENCLAW_SERVICE_REPAIR_POLICY=external。Doctor 仍會回報閘道/服務健康狀態並套用非服務修復，但會略過服務安裝/啟動/重新啟動/初始設定，以及舊版服務清理。
• 在 Linux 上，doctor 會忽略未啟用的額外類閘道 systemd 單元，且修復期間不會重寫執行中 systemd 閘道服務的命令/進入點中繼資料。請先停止服務，或使用 openclaw gateway install --force 取代作用中的啟動器。
• doctor --fix --non-interactive 會回報缺少或過時的閘道服務定義，但不會在更新修復模式以外安裝或重寫這些定義。若缺少服務，請執行 openclaw gateway install；若要取代啟動器，請執行 openclaw gateway install --force。
• 狀態完整性檢查會偵測工作階段目錄中的孤立逐字記錄檔。將其封存為 .deleted.<timestamp> 需要互動式確認；--fix、--yes 和無終端執行都會將其保留在原處。
• Doctor 會掃描 ~/.openclaw/cron/jobs.json（或 cron.store）以尋找舊版排程工作格式，並在將標準資料列匯入 SQLite 前重寫這些格式。
• Doctor 會回報明確設定 payload.model 覆寫的排程工作，包括供應商命名空間計數，以及與 agents.defaults.model 不相符的項目，讓未繼承預設模型的排程工作在認證或計費調查期間可供識別。
• Doctor 會回報仍標記為執行中的排程工作（state.runningAtMs），這可能使 openclaw cron list 將其顯示為 running。此檢查為唯讀：若目前沒有閘道正在執行已標記的工作，下次排程服務啟動時會記錄遭中斷的執行並清除該標記。
• 在 Linux 上，如果使用者的 crontab 仍在執行未受維護的舊版 ~/.openclaw/bin/ensure-whatsapp.sh，doctor 會發出警告；當排程缺少 systemd 使用者匯流排環境時，此指令碼可能會錯誤回報 Gateway inactive。
• 啟用 WhatsApp 時，doctor 會檢查是否有本機 openclaw-tui 用戶端仍在執行，導致閘道事件迴圈效能降級。doctor --fix 只會停止已驗證的本機終端介面用戶端，以免 WhatsApp 回覆排在過時的終端介面重新整理迴圈之後。
• Doctor 會將主要模型、備援模型、圖片/影片生成模型、心跳偵測/子代理程式/壓縮覆寫、鉤子、頻道模型覆寫和過時工作階段路由固定設定中的舊版 openai-codex/* 模型參照，重寫為標準 openai/* 參照。--fix 也會將舊版 openai-codex:* 認證設定檔和 auth.order.openai-codex 項目移轉至 openai:*，將 Codex 意圖移至限定供應商/模型範圍的 agentRuntime.id: "codex" 項目、移除過時的整體代理程式/工作階段執行階段固定設定，並讓修復後的 OpenAI 代理程式參照繼續使用 Codex 認證路由，而非直接使用 OpenAI API 金鑰認證。
• Doctor 會回報非空的 auth.order.<provider> 清單：其中參照的設定檔已全部消失，但仍存在相容的已儲存認證資訊。doctor --fix 只會刪除這些過時的覆寫，恢復自動的每代理程式認證資訊選取；明確的空白順序、部分仍有效的清單，以及沒有相容已儲存認證資訊的順序均維持不變。如果作用中的 SQLite 認證儲存區無法讀取或格式錯誤，doctor 會說明略過此修復的原因。如果執行中閘道的設定重新載入模式不會自動套用寫入，請先重新啟動閘道，再重新檢查認證狀態。
• Doctor 會清理舊版 OpenClaw 留下的舊版外掛相依套件暫存狀態，並針對將主機 openclaw 套件宣告為同儕相依套件的受管理 npm 外掛重新建立連結。它也會修復設定所參照但缺少的可下載外掛（plugins.entries、已設定的頻道、已設定的供應商/搜尋設定、已設定的代理程式執行階段）。套件更新期間，doctor 會略過套件管理員的外掛修復，直到套件交換完成；若已設定的外掛仍需復原，請之後重新執行 openclaw doctor --fix。若下載失敗，doctor 會回報安裝錯誤，並保留已設定的外掛項目，供下次修復嘗試使用。
• 外掛探索正常時，Doctor 會移除 plugins.allow/plugins.deny/plugins.entries 中缺少的外掛 ID，以及相符的懸空頻道設定、心跳偵測目標和頻道模型覆寫，藉此修復過時的外掛設定。
• Doctor 會停用受影響的 plugins.entries.<id> 項目並移除其無效的 config 承載資料，以隔離無效的外掛設定。閘道啟動時本來就只會略過該故障外掛，讓其他外掛和頻道繼續執行。
• Doctor 會移除已淘汰的 plugins.entries.codex.config.codexDynamicToolsProfile；Codex 應用程式伺服器一律讓 Codex 原生工作區工具保持原生。
• Doctor 會自動將舊版扁平 Talk 設定（talk.voiceId、talk.modelId 等）移轉至 talk.provider + talk.providers.<provider>。若唯一差異只是物件鍵順序，重複執行 doctor --fix 不再回報或套用 Talk 正規化。
• Doctor 包含記憶搜尋就緒狀態檢查，並可在缺少嵌入認證資訊時建議執行 openclaw configure --section model。
• 未設定命令擁有者時，Doctor 會發出警告。命令擁有者是獲准執行僅限擁有者的命令，以及核准危險操作的人類操作者帳號。私訊配對只允許某人與機器人交談；若你在首次擁有者初始設定功能存在前就核准了傳送者，請明確設定 commands.ownerAllowFrom。
• 已設定 Codex 模式代理程式，且操作者的 Codex 主目錄中存在個人 Codex 命令列介面資產時，Doctor 會回報資訊提示。本機 Codex 應用程式伺服器會使用隔離的每代理程式主目錄啟動；如有需要，請先安裝 Codex 外掛，再使用 openclaw migrate plan codex 清查應刻意升級的資產。
• 當預設代理程式允許的 Skills 在目前執行階段環境中不可用（缺少執行檔、環境變數、設定或作業系統需求）時，Doctor 會發出警告。doctor --fix 可使用 skills.entries.<skill>.enabled=false 停用這些不可用的 Skills；若要讓 Skills 維持啟用，請改為安裝或設定缺少的需求。
• 若沙箱模式已啟用但 Docker 不可用，doctor 會回報明確的警告與修復方式（install Docker 或 openclaw config set agents.defaults.sandbox.mode off）。
• 若存在舊版沙箱登錄檔或分片目錄（~/.openclaw/sandbox/containers.json、~/.openclaw/sandbox/browsers.json、~/.openclaw/sandbox/containers/ 或 ~/.openclaw/sandbox/browsers/），doctor 會回報這些項目；--fix 會將有效項目移轉至 SQLite，並隔離無效的舊版檔案。
• 若 gateway.auth.token/gateway.auth.password 由 SecretRef 管理，且在目前命令路徑中無法使用，doctor 會回報唯讀警告，且不會寫入純文字備援認證資訊。對於以 exec 為基礎的 SecretRef，除非提供 --allow-exec，否則 doctor 會略過執行。
• 若在修復路徑中檢查頻道 SecretRef 失敗，doctor 會繼續執行並回報警告，而不會提前結束。
• 狀態目錄移轉後，如果已啟用的預設 Telegram 或 Discord 帳號依賴環境變數備援，且 doctor 程序無法使用 TELEGRAM_BOT_TOKEN 或 DISCORD_BOT_TOKEN，doctor 會發出警告。
• Telegram allowFrom 使用者名稱自動解析（doctor --fix）需要目前命令路徑中可解析的 Telegram 權杖。若無法檢查權杖，doctor 會回報警告，並略過該次執行的自動解析。

macOS：launchctl 環境變數覆寫

如果你先前執行過 launchctl setenv OPENCLAW_GATEWAY_TOKEN ...（或 ...PASSWORD），該值會覆寫你的設定檔，並可能導致持續出現「未授權」錯誤。

launchctl getenv OPENCLAW_GATEWAY_TOKENlaunchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKENlaunchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

相關內容

• 命令列介面參考
• 閘道 doctor