一般疑難排解

分流前門。2 分鐘完成診斷，然後跳到深入頁面。

前 60 秒

依序執行這個階梯：

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw 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 顯示穩定活動，沒有重複的致命錯誤。

助理感覺受限或缺少工具

檢查有效工具設定檔：

openclaw status
openclaw status --all
openclaw doctor

常見原因：

tools.profile: "minimal" 只允許 session_status。
tools.profile: "messaging" 範圍很窄，適用於僅聊天的代理。
tools.profile: "coding" 是新的本機設定預設值（repo、檔案、 shell 與執行階段工作）。
tools.profile: "full" 會移除設定檔限制；僅限受信任的操作者控制代理使用。
每代理的 agents.list[].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 或一般代理回合中失敗：

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

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

package.json missing openclaw.extensions 表示外掛套件使用了 OpenClaw 不再接受的形狀。在外掛套件中修正：

將 openclaw.extensions 加到 package.json，指向已建置的執行階段檔案（通常是 ./dist/index.js）。
重新發布，然後再次執行 openclaw plugins install <package>。

{
  "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、network 或 request.mode: "update" 請求）。
將政策命令視為選用：啟用 security.installPolicy 時，缺少、緩慢、不可讀或被權限阻擋的政策可執行檔會以失敗關閉。
核准版本時未根據外掛候選中繼資料檢查請求的 openclawVersion。

偏好允許與目前主機相容的受信任 @openclaw/* 更新規則，而不是永久釘選單一發行版。如果你預設封鎖 npm，請為你使用的外掛 ID 加上窄範圍例外，並將相同的信任規則套用到 request.mode: "update" 和安裝。復原：

openclaw doctor --deep
openclaw plugins update --all
openclaw status --all

如果政策刻意嚴格，請在受信任升級窗口期間放寬，重新執行 openclaw plugins update --all，然後還原較嚴格的規則。如果更新失敗停用了外掛，重新啟用前請先檢查：

openclaw plugins inspect <plugin-id> --runtime --json
openclaw plugins enable <plugin-id>

參考：操作者安裝政策

外掛存在但被可疑擁有權阻擋

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

blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
plugin present but blocked

外掛檔案的擁有者與載入它們的程序所屬 Unix 使用者不同。不要移除外掛設定；請修正檔案擁有權，或以擁有狀態目錄的使用者身分執行 OpenClaw。 Docker 安裝會以 node（uid 1000）執行。修復主機繫結掛載：

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

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

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

更深入文件：被阻擋的外掛路徑擁有權、Docker：權限與 EACCES

決策樹

沒有回覆

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw 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
傳送者已核准（或 DM 政策為開放/允許清單）

日誌特徵：

drop guild message (mention required → Discord 提及閘門阻擋了訊息。
pairing request → 傳送者未核准，正在等待 DM 配對核准。
頻道日誌中的 blocked / allowlist → 傳送者、房間或群組被篩選。

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

儀表板或 Control UI 無法連線

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

良好輸出：

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

日誌特徵：

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

深入頁面：儀表板/Control UI 連線能力、Control UI、驗證

閘道無法啟動或服務已安裝但未執行

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw 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 → 沒有有效驗證路徑（權杖/密碼，或已設定的受信任代理）卻綁定非迴路介面。
another gateway instance is already listening 或 EADDRINUSE → 連接埠已被占用。

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

頻道已連線但訊息沒有流動

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

良好輸出：

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

日誌特徵：

mention required → 群組提及閘門阻擋處理。
pairing / pending → DM 傳送者尚未核准。
not_in_channel、missing_scope、Forbidden、401/403 → 頻道權限權杖問題。

深入頁面：頻道已連線，訊息未流動、頻道疑難排解

排程或心跳偵測未觸發或未送達

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow

良好輸出：

cron status 顯示排程器已啟用並有下一次喚醒。
cron runs 顯示近期 ok 項目。
心跳偵測已啟用且在有效時段內。

日誌特徵：

cron: scheduler disabled; jobs will not run automatically → cron 已停用。
heartbeat skipped 原因 quiet-hours → 超出已設定的活動時段。
heartbeat skipped 原因 empty-heartbeat-file → HEARTBEAT.md 存在，但只包含空白、註解、標題、圍欄，或空檢查清單鷹架。
heartbeat skipped 原因 no-tasks-due → 工作模式已啟用，但尚未到任何工作間隔。
heartbeat skipped 原因 alerts-disabled → showOk、showAlerts 和 useIndicator 全部關閉。
requests-in-flight → 主要通道忙碌；心跳偵測喚醒已延後。
unknown accountId → 心跳偵測傳遞目標帳戶不存在。

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

節點已配對，但工具執行 camera canvas screen exec 失敗

openclaw status
openclaw gateway status
openclaw nodes status
openclaw 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 突然要求核准

openclaw config get tools.exec.host
openclaw config get tools.exec.security
openclaw config get tools.exec.ask
openclaw gateway restart

變更內容：

未設定的 tools.exec.host 預設為 auto；當沙箱執行階段啟用時會解析為 sandbox，否則解析為 gateway。
host=auto 只負責路由；不提示行為來自閘道/節點上的 security=full 加上 ask=off。
未設定的 tools.exec.security 在 gateway/node 上預設為 full。
未設定的 tools.exec.ask 預設為 off。
如果你看到核准提示，代表某些主機本機或每個工作階段的政策將 exec 收緊到不同於這些預設值。

還原目前不需核准的預設值：

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw 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 核准、安全性：稽核檢查的內容

瀏覽器工具失敗

openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw 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 疑難排解

​前 60 秒

​助理感覺受限或缺少工具

​Anthropic 長上下文 429

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

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

​安裝政策阻擋外掛安裝或更新

​外掛存在但被可疑擁有權阻擋

​決策樹

​相關

前 60 秒

助理感覺受限或缺少工具

Anthropic 長上下文 429

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

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

安裝政策阻擋外掛安裝或更新

外掛存在但被可疑擁有權阻擋

決策樹

相關