疑難排解

• 本機 MLX/vLLM 風格伺服器出現 model_not_found → 確認 baseUrl 包含 /v1，對 /v1/chat/completions 後端而言 api 是 "openai-completions"，且 models.providers.<provider>.models[].id 是裸的供應商本機 id。選取時加一次供應商前綴，例如 mlx/mlx-community/Qwen3-30B-A3B-6bit；目錄項目則保持為 mlx-community/Qwen3-30B-A3B-6bit。
• messages[...].content: invalid type: sequence, expected a string → 後端拒絕結構化 Chat Completions 內容片段。修正：設定 models.providers.<provider>.models[].compat.requiresStringContent: true。
• incomplete turn detected ... stopReason=stop payloads=0 → 後端完成了 Chat Completions 請求，但該回合沒有傳回使用者可見的助理文字。OpenClaw 會對可安全重播的空白 OpenAI 相容回合重試一次；若持續失敗，通常表示後端正在發出空白/非文字內容，或抑制最終答案文字。
• 直接微型請求成功，但 OpenClaw 代理執行因後端/模型當機而失敗（例如某些 inferrs 建置上的 Gemma）→ OpenClaw 傳輸很可能已正確；後端在較大的代理執行階段提示形狀上失敗。
• 停用工具後失敗範圍縮小但未消失 → 工具結構描述是壓力來源之一，但剩餘問題仍是上游模型/伺服器容量或後端錯誤。

1. 對僅支援字串的 Chat Completions 後端設定 compat.requiresStringContent: true。
2. 對無法可靠處理 OpenClaw 工具結構描述表面的模型/後端設定 compat.supportsTools: false。
3. 盡可能降低提示壓力：較小的工作區啟動內容、較短的工作階段歷史、較輕量的本機模型，或具備更強長上下文支援的後端。
4. 如果微型直接請求持續通過，但 OpenClaw 代理回合仍在後端內部當機，請將其視為上游伺服器/模型限制，並使用已接受的酬載形狀在上游提交重現案例。

• device identity required → 非安全上下文或缺少裝置驗證。
• origin not allowed → 瀏覽器 Origin 不在 gateway.controlUi.allowedOrigins 中（或你正從非 loopback 瀏覽器來源連線，且沒有明確允許清單）。
• device nonce required / device nonce mismatch → 用戶端未完成以挑戰為基礎的裝置驗證流程（connect.challenge + device.nonce）。
• device signature invalid / device signature expired → 用戶端針對目前握手簽署了錯誤的酬載（或過期的時間戳記）。
• AUTH_TOKEN_MISMATCH 且 canRetryWithDeviceToken=true → 用戶端可使用快取的裝置 Token 執行一次受信任重試。
• 該快取 Token 重試會重用與已配對裝置 Token 一起儲存的快取範圍集。明確 deviceToken / 明確 scopes 呼叫者則保留其要求的範圍集。
• 在該重試路徑之外，連線驗證優先順序為明確共享 Token/密碼優先，接著是明確 deviceToken，再來是已儲存的裝置 Token，最後是啟動 Token。
• 在非同步 Tailscale Serve 控制 UI 路徑上，來自相同 {scope, ip} 的失敗嘗試會在限制器記錄失敗之前被序列化。因此，來自相同用戶端的兩次錯誤並行重試，可能會在第二次嘗試顯示 retry later，而不是兩次單純的不相符。
• 來自瀏覽器來源 loopback 用戶端的 too many failed authentication attempts (retry later) → 來自相同正規化 Origin 的重複失敗會被暫時鎖定；另一個 localhost 來源會使用獨立的儲存桶。
• 該重試後仍反覆出現 unauthorized → 共享 Token/裝置 Token 漂移；請重新整理 Token 設定，必要時重新核准/輪替裝置 Token。
• gateway connect failed: → 錯誤的主機/連接埠/url 目標。

• Gateway start blocked: set gateway.mode=local 或 existing config is missing gateway.mode → local Gateway 模式未啟用，或設定檔被覆寫並遺失 gateway.mode。修正：在你的設定中設定 gateway.mode="local"，或重新執行 openclaw onboard --mode local / openclaw setup，以重新標記預期的 local 模式設定。如果你透過 Podman 執行 OpenClaw，預設設定路徑是 ~/.openclaw/openclaw.json。
• refusing to bind gateway ... without auth → 非 loopback 綁定缺少有效的 Gateway 驗證路徑（權杖/密碼，或已設定時的受信任 Proxy）。
• another gateway instance is already listening / EADDRINUSE → 連接埠衝突。
• Other gateway-like services detected (best effort) → 存在過時或並行的 launchd/systemd/schtasks 單元。大多數設定應每台機器保留一個 Gateway；如果你確實需要多個，請隔離連接埠 + 設定/狀態/工作區。請參閱 /gateway#multiple-gateways-same-host。
• doctor 顯示 System-level OpenClaw gateway service detected → user-level 服務缺失，但存在 systemd system 單元。在允許 doctor 安裝使用者服務前，請移除或停用重複項；如果該 system 單元是預期的監督程式，請設定 OPENCLAW_SERVICE_REPAIR_POLICY=external。
• Gateway service port does not match current gateway config → 已安裝的監督程式仍固定舊的 --port。執行 openclaw doctor --fix 或 openclaw gateway install --force，然後重新啟動 Gateway 服務。

• 設定在啟動、熱重新載入或 OpenClaw 擁有的寫入期間未通過驗證。
• Gateway 啟動會安全失敗，而不是重寫 openclaw.json。
• 熱重新載入會略過無效的外部編輯，並保持目前的執行階段設定作用中。
• OpenClaw 擁有的寫入會在提交前拒絕無效/破壞性承載資料，並儲存 .rejected.*。
• openclaw doctor --fix 負責修復。它可以移除非 JSON 前置內容，或還原最後已知良好副本，同時將被拒絕的承載資料保留為 .clobbered.*。

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• .clobbered.* 存在 → doctor 在修復作用中設定時保留了損壞的外部編輯。
• .rejected.* 存在 → OpenClaw 擁有的設定寫入在提交前未通過 schema 或覆寫檢查。
• Config write rejected: → 寫入嘗試移除必要結構、大幅縮小檔案，或保留無效設定。
• config reload skipped (invalid config): → 直接編輯驗證失敗，並被執行中的 Gateway 忽略。
• Invalid config at ... → Gateway 服務啟動前，啟動已失敗。
• missing-meta-vs-last-good、gateway-mode-missing-vs-last-good 或 size-drop-vs-last-good:* → OpenClaw 擁有的寫入因相較於最後已知良好備份遺失欄位或大小而遭拒絕。
• Config last-known-good promotion skipped → 候選內容包含已遮蔽的秘密預留位置，例如 ***。

1. 執行 openclaw doctor --fix，讓 doctor 修復帶前置內容/被覆寫的設定，或還原最後已知良好設定。
2. 只從 .clobbered.* 或 .rejected.* 複製預期的鍵，然後使用 openclaw config set 或 config.patch 套用。
3. 重新啟動前執行 openclaw config validate。
4. 如果你手動編輯，請保留完整 JSON5 設定，而不是只保留你想變更的部分物件。

• cron: scheduler disabled; jobs will not run automatically → Cron 已停用。
• cron: timer tick failed → 排程器 tick 失敗；檢查檔案/日誌/執行階段錯誤。
• heartbeat skipped 搭配 reason=quiet-hours → 不在作用中時段視窗內。
• heartbeat skipped 搭配 reason=empty-heartbeat-file → HEARTBEAT.md 存在但只包含空白行/Markdown 標題，因此 OpenClaw 會略過模型呼叫。
• heartbeat skipped 搭配 reason=no-tasks-due → HEARTBEAT.md 包含 tasks: 區塊，但這次 tick 沒有任何到期任務。
• heartbeat: unknown accountId → Heartbeat 傳遞目標的帳戶 ID 無效。
• heartbeat skipped 搭配 reason=dm-blocked → Heartbeat 目標解析為 DM 樣式目的地，而 agents.defaults.heartbeat.directPolicy（或每個 agent 的覆寫）設定為 block。

• unknown command "browser" 或 unknown command 'browser' → 內建瀏覽器 Plugin 被 plugins.allow 排除。
• 瀏覽器工具缺少/不可用，但 browser.enabled=true → plugins.allow 排除 browser，因此 Plugin 從未載入。
• Failed to start Chrome CDP on port → 瀏覽器程序啟動失敗。
• browser.executablePath not found → 設定的路徑無效。
• browser.cdpUrl must be http(s) or ws(s) → 設定的 CDP URL 使用不支援的 scheme，例如 file: 或 ftp:。
• browser.cdpUrl has invalid port → 設定的 CDP URL 有錯誤或超出範圍的連接埠。
• Playwright is not available in this gateway build; '<feature>' is unsupported. → 目前的 Gateway 安裝缺少核心瀏覽器執行階段相依性；重新安裝或更新 OpenClaw，然後重新啟動 Gateway。ARIA 快照與基本頁面截圖仍可運作，但導覽、AI 快照、CSS selector 元素截圖與 PDF 匯出仍不可用。

• Could not find DevToolsActivePort for chrome → Chrome MCP existing-session 尚無法連接到所選瀏覽器資料目錄。開啟瀏覽器檢查頁面、啟用遠端偵錯、保持瀏覽器開啟、核准第一次連接提示，然後重試。如果不需要登入狀態，請優先使用受管理的 openclaw 設定檔。
• No Chrome tabs found for profile="user" → Chrome MCP attach 設定檔沒有開啟中的本機 Chrome 分頁。
• Remote CDP for profile "<name>" is not reachable → 設定的遠端 CDP 端點無法從 Gateway 主機連線。
• Browser attachOnly is enabled ... not reachable 或 Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only 設定檔沒有可連線的目標，或 HTTP 端點有回應，但 CDP WebSocket 仍無法開啟。

• fullPage is not supported for element screenshots → 截圖請求將 --full-page 與 --ref 或 --element 混用。
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session 截圖呼叫必須使用頁面擷取或快照 --ref，不能使用 CSS --element。
• existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP 上傳 hook 需要快照 ref，而不是 CSS selector。
• existing-session file uploads currently support one file at a time. → 在 Chrome MCP 設定檔上，每次呼叫傳送一個上傳。
• existing-session dialog handling does not support timeoutMs. → Chrome MCP 設定檔上的對話框 hook 不支援逾時覆寫。
• existing-session type does not support timeoutMs overrides. → 在 profile="user" / Chrome MCP existing-session 設定檔上，對 act:type 省略 timeoutMs；或在需要自訂逾時時使用受管理/CDP 瀏覽器設定檔。
• existing-session evaluate does not support timeoutMs overrides. → 在 profile="user" / Chrome MCP existing-session 設定檔上，對 act:evaluate 省略 timeoutMs；或在需要自訂逾時時使用受管理/CDP 瀏覽器設定檔。
• response body is not supported for existing-session profiles yet. → responsebody 仍需要受管理瀏覽器或原始 CDP 設定檔。
• attach-only 或遠端 CDP 設定檔上的過期 viewport / 深色模式 / locale / 離線覆寫 → 執行 openclaw browser stop --browser-profile <name>，關閉作用中的控制工作階段並釋放 Playwright/CDP 模擬狀態，而不重新啟動整個 Gateway。

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

要檢查的項目：

• 如果 gateway.mode=remote，CLI 呼叫可能會以遠端為目標，而你的本機服務是正常的。
• 明確的 --url 呼叫不會回退到已儲存的認證。

常見特徵：

• gateway connect failed: → URL 目標錯誤。
• unauthorized → 端點可連線，但驗證錯誤。

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

要檢查的項目：

• 非 loopback 繫結（lan、tailnet、custom）需要有效的 Gateway 驗證路徑：共用 token/password 驗證，或正確設定的非 loopback trusted-proxy 部署。
• 舊鍵如 gateway.token 不會取代 gateway.auth.token。

常見特徵：

• refusing to bind gateway ... without auth → 非 loopback 繫結缺少有效的 Gateway 驗證路徑。
• Connectivity probe: failed 但執行階段正在執行 → Gateway 存活，但目前 auth/url 無法存取。

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

要檢查的項目：

• dashboard/nodes 的待核准裝置。
• 政策或身分變更後待核准的 DM 配對。

常見特徵：

• device identity required → 裝置驗證未滿足。
• pairing required → 傳送者/裝置必須核准。