疑難排解

• 搭配本機 MLX/vLLM 風格伺服器時出現 model_not_found → 驗證 baseUrl 包含 /v1，/v1/chat/completions 後端的 api 是 "openai-completions"，且 models.providers.<provider>.models[].id 是裸的 provider 本機 ID。選取時使用一次 provider 前綴，例如 mlx/mlx-community/Qwen3-30B-A3B-6bit；保留 catalog 項目為 mlx-community/Qwen3-30B-A3B-6bit。
• messages[...].content: invalid type: sequence, expected a string → 後端拒絕結構化 Chat Completions 內容片段。修正：設定 models.providers.<provider>.models[].compat.requiresStringContent: true。
• validation.keys 或允許的訊息鍵如 ["role","content"] → 後端拒絕 Chat Completions 訊息上的 OpenAI 風格重播中繼資料。修正：設定 models.providers.<provider>.models[].compat.strictMessageKeys: true。
• incomplete turn detected ... stopReason=stop payloads=0 → 後端完成了 Chat Completions 請求，但該回合沒有回傳使用者可見的 assistant 文字。OpenClaw 會對可安全重播的空 OpenAI 相容回合重試一次；持續失敗通常表示後端正在發出空白/非文字內容，或抑制最終答案文字。
• 直接的極小請求成功，但 OpenClaw agent 執行因後端/模型崩潰而失敗（例如某些 inferrs 建置上的 Gemma）→ OpenClaw 傳輸很可能已經正確；後端在較大的 agent 執行階段提示形狀上失敗。
• 停用工具後失敗減少但未消失 → 工具 schema 是壓力的一部分，但剩餘問題仍是上游模型/伺服器容量或後端錯誤。

1. 對只支援字串的 Chat Completions 後端設定 compat.requiresStringContent: true。
2. 對每則訊息只接受 role 和 content 的嚴格 Chat Completions 後端設定 compat.strictMessageKeys: true。
3. 對無法可靠處理 OpenClaw 工具 schema 介面的模型/後端設定 compat.supportsTools: false。
4. 在可行處降低提示壓力：較小的工作區啟動內容、較短的工作階段歷史、較輕量的本機模型，或長上下文支援更強的後端。
5. 如果極小直接請求持續通過，但 OpenClaw agent 回合仍在後端內崩潰，請將其視為上游伺服器/模型限制，並以已接受的 payload 形狀在上游提交重現案例。

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

• Gateway start blocked: set gateway.mode=local 或 existing config is missing gateway.mode → 本機 gateway 模式未啟用，或設定檔遭覆寫而遺失 gateway.mode。修正：在設定中設定 gateway.mode="local"，或重新執行 openclaw onboard --mode local / openclaw setup 以重新標記預期的本機模式設定。如果你透過 Podman 執行 OpenClaw，預設設定路徑為 ~/.openclaw/openclaw.json。
• refusing to bind gateway ... without auth → 非回送繫結缺少有效的 gateway 驗證路徑（權杖/密碼，或已設定時的 trusted-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 → 當使用者層級服務缺失時，存在 systemd 系統單元。在允許 doctor 安裝使用者服務前，移除或停用重複項；如果該系統單元是預期的監督器，請設定 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.*。

• .clobbered.* 存在 → doctor 在修復作用中設定時，保留了損壞的外部編輯。
• .rejected.* 存在 → OpenClaw 擁有的設定寫入在提交前未通過 schema 或 clobber 檢查。
• 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 with reason=quiet-hours → 不在有效時段視窗內。
• heartbeat skipped with reason=empty-heartbeat-file → HEARTBEAT.md 存在，但只包含空白列 / markdown 標題，因此 OpenClaw 會略過模型呼叫。
• heartbeat skipped with reason=no-tasks-due → HEARTBEAT.md 包含 tasks: 區塊，但此 tick 沒有任何到期任務。
• heartbeat: unknown accountId → heartbeat 遞送目標的帳號 ID 無效。
• heartbeat skipped with reason=dm-blocked → heartbeat 目標解析為 DM 樣式目的地，而 agents.defaults.heartbeat.directPolicy（或個別 agent 覆寫）設定為 block。

• unknown command "browser" or unknown command 'browser' → 內建的瀏覽器 plugin 被 plugins.allow 排除。
• browser tool missing / unavailable while 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 選擇器元素截圖和 PDF 匯出仍不可用。

• Could not find DevToolsActivePort for chrome → Chrome MCP existing-session 尚無法附加到所選的瀏覽器資料目錄。開啟瀏覽器 inspect 頁面、啟用遠端偵錯、保持瀏覽器開啟、核准第一次附加提示，然後重試。如果不需要已登入狀態，請優先使用受管理的 openclaw profile。
• No Chrome tabs found for profile="user" → Chrome MCP 附加 profile 沒有開啟中的本機 Chrome 分頁。
• Remote CDP for profile "<name>" is not reachable → 設定的遠端 CDP 端點無法從 gateway 主機連線。
• Browser attachOnly is enabled ... not reachable or Browser attachOnly is enabled and CDP websocket ... is not reachable → 僅附加 profile 沒有可連線的目標，或 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 選擇器。
• existing-session file uploads currently support one file at a time. → 在 Chrome MCP profiles 上每次呼叫傳送一個上傳。
• existing-session dialog handling does not support timeoutMs. → Chrome MCP profiles 上的對話框 hook 不支援 timeout 覆寫。
• existing-session type does not support timeoutMs overrides. → 對 profile="user" / Chrome MCP existing-session profiles 的 act:type 省略 timeoutMs，或在需要自訂 timeout 時使用受管理/CDP 瀏覽器 profile。
• existing-session evaluate does not support timeoutMs overrides. → 對 profile="user" / Chrome MCP existing-session profiles 的 act:evaluate 省略 timeoutMs，或在需要自訂 timeout 時使用受管理/CDP 瀏覽器 profile。
• response body is not supported for existing-session profiles yet. → responsebody 仍需要受管理瀏覽器或原始 CDP profile。
• stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → 執行 openclaw browser stop --browser-profile <name> 以關閉作用中的控制工作階段，並釋放 Playwright/CDP 模擬狀態，而不必重新啟動整個 gateway。

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

要檢查的項目：

• 如果 gateway.mode=remote，CLI 呼叫可能會指向遠端，而你的本機服務其實正常。
• 明確的 --url 呼叫不會回退到已儲存的憑證。

常見特徵：

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

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

要檢查的項目：

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

常見特徵：

• refusing to bind gateway ... without auth → 非 loopback 繫結缺少有效的 gateway 驗證路徑。
• Connectivity probe: failed while runtime is running → gateway 存活，但使用目前的 auth/url 無法存取。

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

要檢查的項目：

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

常見特徵：

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