OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

一般疑難排解

分流入口。2 分鐘內完成診斷，接著前往深入說明頁面。

前 60 秒

依序執行以下檢查：

bash
openclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow

正常輸出，每項一行：

  • openclaw status 顯示已設定的頻道，且沒有驗證錯誤。
  • openclaw status --all 產生完整且可分享的報告。
  • openclaw gateway probe 顯示 Reachable: yes。Capability: ... 是探測所證實的 驗證層級；Read probe: limited - missing scope: operator.read 表示診斷功能降級，而非連線失敗。
  • openclaw gateway status 顯示 Runtime: running、Connectivity probe: ok，以及合理的 Capability: ...。加上 --require-rpc，即可同時要求 讀取範圍的 RPC 驗證。
  • openclaw doctor 回報沒有阻礙運作的設定／服務錯誤。
  • 閘道可連線時，openclaw channels status --probe 會傳回各帳號即時的傳輸狀態 （works／audit ok）；無法連線時，則退回 僅依設定產生的摘要。
  • openclaw logs --follow 顯示活動穩定，且沒有重複發生的嚴重錯誤。

助理功能受限或缺少工具

檢查實際生效的工具設定檔：

bash
openclaw statusopenclaw status --allopenclaw doctor

常見原因：

  • tools.profile: "minimal" 僅允許 session_status。
  • tools.profile: "messaging" 範圍較窄，適用於僅進行聊天的代理程式。
  • tools.profile: "coding" 是新的本機設定預設值（儲存庫、檔案、 shell 和執行階段工作）。
  • tools.profile: "full" 會移除設定檔限制；僅限由受信任的 操作者控制之代理程式使用。
  • 每個代理程式的 agents.entries.*.tools 可針對單一代理程式縮限或擴大根設定檔。

變更設定檔、重新啟動或重新載入閘道，然後使用 openclaw status --all 再次檢查。完整設定檔／群組表格：工具設定檔。

Anthropic 長上下文 429

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Anthropic 429：長上下文需要額外用量。

本機 OpenAI 相容後端可直接運作，但在 OpenClaw 中失敗

你的本機／自架 /v1 後端可回應直接的 /v1/chat/completions 探測，但在 openclaw infer model run 或一般代理程式回合中失敗：

  1. 錯誤提到 messages[].content 預期收到字串：請設定 models.providers.<provider>.models[].compat.requiresStringContent: true。
  2. 仍然只在 OpenClaw 代理程式回合失敗：請設定 models.providers.<provider>.models[].compat.supportsTools: false，然後重試。
  3. 小型直接呼叫可運作，但較大的 OpenClaw 提示詞會使後端當機：這是 上游模型／伺服器的限制，並非 OpenClaw 錯誤。請繼續參閱 本機 OpenAI 相容後端通過直接探測，但代理程式執行失敗。

安裝外掛時因缺少 openclaw extensions 而失敗

package.json missing openclaw.extensions 表示外掛套件使用了 OpenClaw 已不再接受的結構。

請在外掛套件中修正：

  1. 將 openclaw.extensions 加入 package.json，並指向建置完成的執行階段 檔案（通常是 ./dist/index.js）。
  2. 重新發布，然後再次執行 openclaw plugins install <package>。
json
{  "name": "@openclaw/my-plugin",  "version": "1.2.3",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

參考：外掛架構

安裝政策封鎖外掛安裝或更新

更新完成，但外掛仍為舊版、遭停用，或顯示 blocked by install policy、install policy failed closed 或 Disabled "<plugin>" after plugin update failure：請檢查 security.installPolicy。

安裝政策會套用於外掛安裝與更新。@openclaw/* 外掛 版本通常會隨 OpenClaw 發行版本變動，因此 OpenClaw 更新後， 可能需要在更新後同步期間進行相符的外掛更新。

除非也維護相符的升級規則，否則請避免下列政策形式：

  • 將 OpenClaw 擁有的外掛固定於某個確切的舊版本（例如只允許 @openclaw/*@2026.5.3）。
  • 僅依來源類型封鎖（所有 npm、網路或 request.mode: "update" 請求）。
  • 將政策命令視為選用：啟用 security.installPolicy 時， 政策執行檔若缺少、過慢、無法讀取或因權限遭封鎖， 皆會採取失敗時封鎖。
  • 核准版本時，未將請求的 openclawVersion 與 外掛候選項目的中繼資料進行比對。

請優先採用允許受信任且與目前主機相容的 @openclaw/* 更新之規則， 而非永久固定於單一發行版本。若預設封鎖 npm， 請針對你使用的外掛 ID 新增範圍有限的例外，並對 request.mode: "update" 套用與安裝相同的信任規則。

復原：

bash
openclaw doctor --deepopenclaw plugins update --allopenclaw status --all

若政策刻意設為嚴格，請在受信任的升級 時段暫時放寬政策，重新執行 openclaw plugins update --all，再恢復較嚴格的規則。 若更新失敗導致外掛遭停用，請先檢查再重新啟用：

bash
openclaw plugins inspect <plugin-id> --runtime --jsonopenclaw plugins enable <plugin-id>

參考：操作者安裝政策

外掛存在，但因可疑的擁有權而遭封鎖

openclaw doctor、設定或啟動警告顯示：

text
遭封鎖的外掛候選項目：擁有權可疑（... uid=1000，預期 uid=0 或 root）外掛存在，但遭到封鎖

外掛檔案的擁有者與載入這些檔案的程序所屬 Unix 使用者不同。 請勿移除外掛設定；請修正檔案擁有權，或以狀態目錄擁有者的身分 執行 OpenClaw。

Docker 安裝會以 node（uid 1000）執行。請修復主機的繫結掛載：

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceopenclaw doctor --fix

若你刻意以 root 身分執行 OpenClaw，請改為修復受管理的外掛根目錄：

bash
sudo chown -R root:root /path/to/openclaw-config/npmopenclaw doctor --fix

深入說明：遭封鎖之外掛路徑的擁有權、Docker：權限與 EACCES

決策樹

flowchart TD
  A[OpenClaw 無法運作] --> B{最先發生哪種問題}
  B --> C[沒有回覆]
  B --> D[儀表板或 Control UI 無法連線]
  B --> E[閘道無法啟動或服務未執行]
  B --> F[頻道已連線，但訊息未傳遞]
  B --> G[排程或心跳偵測未觸發或未送達]
  B --> H[節點已配對，但相機、畫布、螢幕或 exec 失敗]
  B --> I[瀏覽器工具失敗]

  C --> C1[/沒有回覆章節/]
  D --> D1[/Control UI 章節/]
  E --> E1[/閘道章節/]
  F --> F1[/頻道流程章節/]
  G --> G1[/自動化章節/]
  H --> H1[/節點工具章節/]
  I --> I1[/瀏覽器章節/]
沒有回覆
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

正常輸出：

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only、write-capable 或 admin-capable
  • 頻道顯示傳輸已連線，且在支援的情況下，channels status --probe 中顯示 works 或 audit ok
  • 傳送者已核准（或私訊政策設為開放／允許清單）

記錄特徵：

  • drop guild message (mention required → Discord 提及限制封鎖了該訊息。
  • pairing request → 傳送者尚未核准，正在等待私訊配對核准。
  • 頻道記錄中的 blocked／allowlist → 傳送者、聊天室或群組遭到篩除。

深入說明：沒有回覆、頻道疑難排解、配對

儀表板或 Control UI 無法連線
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

正常輸出：

  • openclaw gateway status 中顯示 Dashboard: http://...
  • Connectivity probe: ok
  • Capability: read-only、write-capable 或 admin-capable
  • 記錄中沒有驗證迴圈

記錄特徵：

  • device identity required → HTTP／非安全內容無法完成裝置驗證。
  • origin not allowed → Control UI 閘道目標不允許瀏覽器 Origin。
  • AUTH_TOKEN_MISMATCH 搭配 canRetryWithDeviceToken=true → 系統可能會自動重試一次受信任的裝置權杖，並重複使用已配對權杖的快取範圍。
  • 該次重試後仍重複出現 unauthorized → 權杖／密碼錯誤、驗證模式不符，或已配對的裝置權杖過時。
  • too many failed authentication attempts (retry later) → 來自該瀏覽器 Origin 的重複失敗暫時遭到鎖定；其他 localhost 來源使用獨立的區間。關於 Tailscale Serve 同時重試的細節，請參閱儀表板／Control UI 連線能力。
  • gateway connect failed: → UI 指向錯誤的 URL／連接埠，或閘道無法連線。

深入說明：儀表板／Control UI 連線能力、Control UI、驗證

閘道無法啟動，或服務已安裝但未執行
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

正常輸出：

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only、write-capable 或 admin-capable

記錄特徵：

  • Gateway start blocked: set gateway.mode=local 或 existing config is missing gateway.mode → 閘道模式為遠端，或設定缺少本機模式標記而需要修復。
  • refusing to bind gateway ... without auth → 綁定非回送位址，但沒有有效的驗證路徑（權杖／密碼，或已設定的受信任 Proxy）。
  • another gateway instance is already listening 或 EADDRINUSE → 連接埠已被占用。

深入說明：閘道服務未執行、背景程序、設定

頻道已連線，但訊息未傳遞
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

正常輸出：

  • 頻道傳輸已連線。
  • 配對／允許清單檢查通過。
  • 需要提及時，已偵測到提及。

記錄特徵：

  • mention required → 群組提及限制封鎖了處理。
  • pairing／pending → 私訊傳送者尚未核准。
  • not_in_channel、missing_scope、Forbidden、401/403 → 頻道權限權杖問題。

深入說明：頻道已連線，但訊息未傳遞、頻道疑難排解

排程或心跳偵測未觸發或未送達
bash
openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw logs --follow

正常輸出：

  • cron status 顯示排程器已啟用，並有下一次喚醒時間。
  • cron runs 顯示最近的 ok 項目。
  • 心跳偵測已啟用，且目前在作用時段內。

日誌特徵：

  • cron: scheduler disabled; jobs will not run automatically → 排程已停用。
  • heartbeat skipped 原因 quiet-hours → 不在設定的作用時段內。
  • heartbeat skipped 原因 empty-heartbeat-file → 心跳偵測監控暫存內容只有空白、註解、標頭、圍欄或空白檢查清單的鷹架。
  • heartbeat skipped 原因 alerts-disabled → showOk、showAlerts 和 useIndicator 均已關閉。
  • requests-in-flight → 主要通道忙碌中；心跳偵測喚醒已延後。
  • unknown accountId → 心跳偵測傳遞目標帳號不存在。

深入頁面：排程與心跳偵測傳遞、排定的工作：疑難排解、心跳偵測

節點已配對，但工具執行 camera canvas screen exec 失敗
bash
openclaw statusopenclaw gateway statusopenclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

正常輸出：

  • 節點顯示為已連線，且已針對角色 node 完成配對。
  • 你正在叫用的命令具備所需功能。
  • 工具的權限狀態為已授予。

日誌特徵：

  • NODE_BACKGROUND_UNAVAILABLE → 將節點應用程式切換至前景。
  • *_PERMISSION_REQUIRED → 作業系統權限遭拒或缺少。
  • SYSTEM_RUN_DENIED: approval required → exec 核准待處理。
  • SYSTEM_RUN_DENIED: allowlist miss → 命令不在 exec 允許清單中。

深入頁面：節點已配對，但工具失敗、節點疑難排解、Exec 核准

Exec 突然要求核准
bash
openclaw config get tools.exec.hostopenclaw config get tools.exec.securityopenclaw config get tools.exec.askopenclaw gateway restart

變更內容：

  • 未設定的 tools.exec.host 預設為 auto；當沙箱執行階段處於作用中時， 會解析為 sandbox，否則為 gateway。
  • host=auto 只負責路由；不顯示提示的行為來自閘道／節點上的 security=full 加上 ask=off。
  • 在 gateway/node 上，未設定的 tools.exec.security 預設為 full。
  • 未設定的 tools.exec.ask 預設為 off。
  • 如果出現核准要求，表示某個主機本機或個別工作階段的原則 已收緊 exec 設定，使其偏離這些預設值。

還原目前無須核准的預設值：

bash
openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

更安全的替代方案：

  • 若要穩定地將工作路由至主機，僅設定 tools.exec.host=gateway。
  • 使用 security=allowlist 搭配 ask=on-miss，即可在允許清單未命中時， 對主機 exec 進行審查。
  • 啟用沙箱模式，讓 host=auto 重新解析為 sandbox。

日誌特徵：

  • Approval required. → 命令正在等待 /approve ...。
  • SYSTEM_RUN_DENIED: approval required → 節點主機 exec 核准待處理。
  • exec host=sandbox requires a sandbox runtime for this session → 已隱含或明確選取沙箱，但沙箱模式已關閉。

深入頁面：Exec、Exec 核准、安全性：稽核檢查的項目

瀏覽器工具失敗
bash
openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

正常輸出：

  • 瀏覽器狀態顯示 running: true，以及所選的瀏覽器／設定檔。
  • openclaw 設定檔可以啟動，或 user 設定檔可以看到本機 Chrome 分頁。

日誌特徵：

  • unknown command "browser" → 已設定 plugins.allow，且其中排除了 browser。
  • Failed to start Chrome CDP on port → 本機瀏覽器啟動失敗。
  • browser.executablePath not found → 設定的二進位檔路徑錯誤。
  • browser.cdpUrl must be http(s) or ws(s) → 設定的 CDP URL 使用不支援的配置。
  • browser.cdpUrl has invalid port → 設定的 CDP URL 連接埠無效或超出範圍。
  • No Chrome tabs found for profile="user" → Chrome MCP 附加設定檔沒有任何開啟的本機 Chrome 分頁。
  • Remote CDP for profile "<name>" is not reachable → 無法從此主機連線至設定的遠端 CDP 端點。
  • Browser attachOnly is enabled ... not reachable → 僅附加設定檔沒有即時 CDP 目標。
  • 僅附加或遠端 CDP 設定檔上有過時的檢視區／深色模式／地區設定／離線覆寫 → 執行 openclaw browser stop --browser-profile <name>，無須重新啟動閘道即可關閉控制工作階段並釋放模擬狀態。

深入頁面：瀏覽器工具失敗、缺少瀏覽器命令或工具、瀏覽器：Linux 疑難排解、瀏覽器：WSL2/Windows 遠端 CDP 疑難排解

相關內容

Was this useful?
On this page

On this page