Gateway 故障排除指南：讓你的 OpenClaw 恢復正常

指令階梯

在進行深入排查前，請先執行這些指令，確認 OpenClaw 的 Gateway 狀態是否正常。請依照下列順序執行：

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

預期應看到的健康訊號：

openclaw gateway status 顯示 Runtime: running、Connectivity probe: ok 以及一行 Capability: ...。
openclaw doctor 回報沒有阻礙性的配置或服務問題。
openclaw channels status —probe 顯示各帳號的即時傳輸狀態，且在支援的情況下，顯示如 works 或 audit ok 等探測/審核結果。

Anthropic 429 長文本額外使用量需求

當日誌或錯誤訊息包含 HTTP 429: rate_limit_error: Extra usage is required for long context requests 時，請使用此排查方式。

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

請檢查以下項目：

所選的 Anthropic Opus/Sonnet 模型是否具有 params.context1m: true。
目前的 Anthropic 憑證是否符合長文本使用資格。
請求是否僅在需要 1M beta 路徑的長對話或模型執行時失敗。

修正選項：

針對該模型停用 context1m，以退回到一般的 context window。
使用符合長文本請求資格的 Anthropic 憑證，或切換至 Anthropic API key。
配置備援模型，以便在 Anthropic 長文本請求被拒絕時，執行作業能繼續進行。

相關連結：

本地 OpenAI 相容後端通過直接探測但代理執行失敗

當出現以下情況時，請使用此排查方式：

curl 呼叫 /v1/models 運作正常。
微小的直接 /v1/chat/completions 呼叫運作正常。
OpenClaw 模型執行僅在一般的代理運作時失敗。

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

請檢查以下項目：

直接的小型呼叫成功，但 OpenClaw 執行僅在較大的 prompt 下失敗。
後端錯誤訊息顯示 messages[].content 預期為字串。
後端崩潰僅發生在較大的 prompt-token 數量或完整的代理執行 prompt 時。

常見特徵：

messages[...].content: invalid type: sequence, expected a string → 後端拒絕結構化的 Chat Completions 內容部分。修正：設定 models.providers.<provider>.models[].compat.requiresStringContent: true。
直接的小型請求成功，但 OpenClaw 代理執行因後端/模型崩潰而失敗（例如某些 inferrs 建置版本上的 Gemma）→ OpenClaw 傳輸層很可能正確，是後端在處理較大的代理執行 prompt 格式時失敗。
停用工具後故障減少但未消失 → 工具 schema 造成了部分壓力，但剩餘問題仍是上游模型/伺服器容量或後端錯誤。

修正選項：

針對僅接受字串的 Chat Completions 後端，設定 compat.requiresStringContent: true。
針對無法可靠處理 OpenClaw 工具 schema 的模型/後端，設定 compat.supportsTools: false。
盡可能降低 prompt 壓力：縮小工作區引導、縮短對話歷史、使用較輕量的本地模型，或使用具備更強長文本支援的後端。
若小型直接請求持續通過，但 OpenClaw 代理執行仍導致後端崩潰，請將其視為上游伺服器/模型的限制，並附上該請求的 payload 格式向該方回報。

相關連結：

無回應

若頻道正常運作但沒有任何回應，請在重新連接任何項目之前，先檢查路由與政策。

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

請檢查以下項目：

DM 發送者的配對狀態是否為待處理。
群組提及限制 (requireMention, mentionPatterns)。
頻道/群組允許清單不匹配。

常見特徵：

drop guild message (mention required → 群組訊息在被提及前會被忽略。
pairing request → 發送者需要核准。
blocked / allowlist → 發送者或頻道被政策過濾。

相關連結：

AI Setup Assistant

Dashboard control ui connectivity

當 Dashboard 或 Control UI 無法連線時，請檢查 URL、驗證模式以及安全上下文設定是否正確。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

請留意以下重點：

確認 Probe URL 與 Dashboard URL 是否正確。
檢查客戶端與 Gateway 之間的驗證模式或 Token 是否不匹配。
確認在需要裝置識別碼的場景下，是否錯誤地使用了 HTTP。

常見錯誤特徵：

device identity required → 代表處於非安全上下文，或是缺少裝置驗證。
origin not allowed → 瀏覽器的 Origin 不在 gateway.controlUi.allowedOrigins 設定中（或者你正從非 loopback 的瀏覽器來源連線，且未設定明確的允許清單）。
device nonce required / device nonce mismatch → 客戶端未完成基於 challenge 的裝置驗證流程（connect.challenge + device.nonce）。
device signature invalid / device signature expired → 客戶端針對當前握手簽署了錯誤的 payload 或使用了過期的時間戳。
AUTH_TOKEN_MISMATCH 伴隨 canRetryWithDeviceToken=true → 客戶端可以使用快取的裝置 Token 進行一次受信任的重試。
該快取 Token 重試會重複使用與已配對裝置 Token 儲存的 scope 設定。明確呼叫 deviceToken 或 scopes 的請求則會保留其自定義的 scope 設定。
在此重試路徑之外，連線驗證的優先順序為：明確的共享 Token/密碼，接著是明確的 deviceToken，然後是儲存的裝置 Token，最後才是 bootstrap Token。
在非同步的 Tailscale Serve Control UI 路徑上，針對相同 {scope, ip} 的失敗嘗試會在限制器記錄失敗前進行序列化。因此，來自同一個客戶端的兩次錯誤併發重試，可能會在第二次嘗試時顯示 retry later，而不是兩次單純的驗證不匹配。
來自瀏覽器來源 loopback 客戶端的 too many failed authentication attempts (retry later) → 來自同一個標準化 Origin 的重複失敗會被暫時鎖定；另一個 localhost 來源則會使用獨立的計數器。
在重試後持續出現 unauthorized → 可能是共享 Token 或裝置 Token 發生偏移；請重新整理 Token 設定，並在必要時重新核准或輪替裝置 Token。
gateway connect failed: → 目標主機、連接埠或 URL 設定錯誤。

驗證詳細代碼快速對照

請使用失敗的 connect 回應中的 error.details.code 來決定下一步操作：

詳細代碼	含義	建議操作
`AUTH_TOKEN_MISSING`	客戶端未傳送必要的共享 Token。	在客戶端貼上或設定 Token 後重試。若為 Dashboard 路徑：執行 `openclaw config get gateway.auth.token`，然後貼入 Control UI 設定。
`AUTH_TOKEN_MISMATCH`	共享 Token 與 Gateway 驗證 Token 不符。	若 `canRetryWithDeviceToken=true`，允許一次受信任的重試。快取 Token 重試會重複使用已儲存的 scope；明確的 `deviceToken` / `scopes` 呼叫會保留請求的 scope。若仍失敗，請執行 token drift recovery checklist。
`AUTH_DEVICE_TOKEN_MISMATCH`	快取的裝置 Token 已過期或被撤銷。	使用 devices CLI 輪替或重新核准裝置 Token，然後重新連線。
`PAIRING_REQUIRED`	裝置識別碼需要核准。檢查 `error.details.reason` 中的 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，並在出現時使用 `requestId` / `remediationHint`。	核准待處理請求：執行 `openclaw devices list` 然後執行 `openclaw devices approve <requestId>`。Scope/role 升級在審核請求的存取權限後，使用相同的流程。

裝置驗證 v2 遷移檢查：

openclaw --version
openclaw doctor
openclaw gateway status

如果日誌顯示 nonce 或簽章錯誤，請更新連線的客戶端並驗證其是否：

等待 connect.challenge
簽署與 challenge 綁定的 payload
傳送包含相同 challenge nonce 的 connect.params.device.nonce

如果 openclaw devices rotate / revoke / remove 被拒絕：

已配對的裝置 Token 工作階段只能管理其自身的裝置，除非呼叫者同時擁有 operator.admin 權限。
openclaw devices rotate --scope ... 只能請求呼叫者工作階段已擁有的 operator scopes。

相關連結：

/web/control-ui
/gateway/configuration (gateway auth modes)
/gateway/trusted-proxy-auth
/gateway/remote
/cli/devices

Gateway service not running

當服務已安裝但處理程序無法持續執行時，請使用此章節進行排解。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services

請留意以下重點：

Runtime: stopped 以及相關的退出提示。
服務設定不匹配 (Config (cli) 與 Config (service) 不同)。
連接埠或監聽衝突。
使用 --deep 時顯示的多餘 launchd/systemd/schtasks 安裝。
Other gateway-like services detected (best effort) 的清理提示。

常見錯誤特徵：

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 以重新產生預期的本地模式設定。若你透過 Docker 執行 OpenClaw，預設設定路徑為 ~/.openclaw/openclaw.json。
refusing to bind gateway ... without auth → 在未設定有效 Gateway 驗證路徑（Token/密碼或已設定的 trusted-proxy）的情況下，嘗試進行非 loopback 綁定。
another gateway instance is already listening / EADDRINUSE → 連接埠衝突。
Other gateway-like services detected (best effort) → 存在過時或平行的 launchd/systemd/schtasks 單元。大多數設定應保持每台機器一個 Gateway；若確實需要多個，請隔離連接埠、設定、狀態與工作區。詳見 /gateway#multiple-gateways-same-host。

相關連結：

Gateway 還原至最後已知良好的設定

當 Gateway 啟動但日誌顯示它還原了 openclaw.json 時，請使用此流程進行排查。這通常意味著系統為了保護穩定性，自動回退到了上一個可用的設定檔。

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

請檢查是否有以下跡象：

出現 Config auto-restored from last-known-good 訊息。
出現 gateway: invalid config was restored from last-known-good backup 錯誤。
出現 config reload restored last-known-good config after invalid-config 提示。
在活躍的設定檔旁發現帶有時間戳記的 openclaw.json.clobbered.* 檔案。
main-agent 系統事件以 Config recovery warning 開頭。

發生了什麼事：

被拒絕的設定在啟動或熱重載時未通過驗證。
OpenClaw 將被拒絕的內容保留為 .clobbered.* 檔案。
活躍設定已從最後驗證過的良好備份中還原。
下一個 main-agent 執行週期會收到警告，避免盲目覆寫被拒絕的設定。

檢查與修復：

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.* → 外部直接編輯或啟動時讀取導致還原。
存在 .rejected.* → OpenClaw 擁有的設定寫入在提交前未通過 schema 或 clobber 檢查。
Config write rejected: → 寫入嘗試刪除必要的結構、大幅縮減檔案或保存無效設定。
Config last-known-good promotion skipped → 候選設定包含如 *** 等已遮蔽的密鑰佔位符。

修復選項：

如果還原後的活躍設定是正確的，則保留它。
僅從 .clobbered.* 或 .rejected.* 複製你想要的 key，然後使用 openclaw config set 或 config.patch 應用它們。
在重啟前執行 openclaw config validate。
如果手動編輯，請保留完整的 JSON5 設定，不要只保留你想更改的部分物件。

相關連結：

Gateway 探測警告

當 OpenClaw 的 Gateway 執行探測指令時，若系統成功連線但仍印出警告區塊，請參考以下說明。這通常與連線權限或多重 Gateway 設定有關。

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

請檢查：

JSON 輸出中的 warnings[].code 和 primaryTargetId。
警告內容是否關於 SSH 回退、多個 Gateway、缺少 scope 或無法解析的驗證引用。

常見特徵：

SSH tunnel failed to start; falling back to direct probes. → SSH 設定失敗，但指令仍嘗試直接連線至已設定或 loopback 的目標。
multiple reachable gateways detected → 超過一個目標回應。這通常代表刻意的多 Gateway 設定，或是存在過期/重複的監聽器。
Read-probe diagnostics are limited by gateway scopes (missing operator.read) → 連線成功，但詳細的 RPC 受限於 scope；請配對裝置識別碼或使用具備 operator.read 權限的憑證。
Capability: pairing-pending 或 gateway closed (1008): pairing required → Gateway 已回應，但此客戶端在獲得一般操作權限前，仍需進行配對或審核。
無法解析的 gateway.auth.* / gateway.remote.* SecretRef 警告文字 → 在此指令路徑中，目標的驗證資料不可用。

相關連結：

AI Setup Assistant

頻道已連線但訊息無法傳送

當頻道狀態顯示為已連線，但訊息流卻沒有反應時，請優先檢查政策、權限以及該頻道特定的傳送規則。透過 OpenClaw 頻道連線與訊息傳送診斷，你可以快速釐清問題所在。

執行以下指令來確認頻道狀態與設定：

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

請留意以下檢查重點：

檢查 DM 政策設定，確認是否為 pairing、allowlist、open 或 disabled。
確認群組的白名單設定以及是否符合提及（mention）要求。
確認是否遺漏了頻道 API 的權限或 scopes。

常見的錯誤特徵如下：

mention required → 訊息因群組提及政策而被忽略。
pairing / 等待核准的軌跡 → 傳送者未經核准。
missing_scope、not_in_channel、Forbidden、401/403 → 頻道驗證或權限問題。

相關文件：

Cron 與 heartbeat 傳送問題

如果 Cron 或 heartbeat 沒有執行，或是沒有成功傳送，請先驗證排程器的狀態，接著再檢查傳送目標。使用 OpenClaw 排程與 heartbeat 診斷工具可以幫助你找出原因。

執行以下指令來檢查排程器與系統狀態：

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

請留意以下檢查重點：

確認 Cron 是否已啟用，以及是否有下一次的執行時間。
查看工作執行歷史狀態，例如 ok、skipped 或 error。
確認 heartbeat 跳過的原因，例如 quiet-hours、requests-in-flight、alerts-disabled、empty-heartbeat-file 或 no-tasks-due。

常見的錯誤特徵如下：

cron: scheduler disabled; jobs will not run automatically → Cron 已停用。
cron: timer tick failed → 排程器計時失敗；請檢查檔案、日誌或執行階段錯誤。
heartbeat skipped 且原因為 reason=quiet-hours → 目前處於非活躍時段。
heartbeat skipped 且原因為 reason=empty-heartbeat-file → HEARTBEAT.md 檔案存在但僅包含空白行或 markdown 標題，導致 OpenClaw 跳過模型呼叫。
heartbeat skipped 且原因為 reason=no-tasks-due → HEARTBEAT.md 包含 tasks: 區塊，但沒有任何任務在當前時間點需要執行。
heartbeat: unknown accountId → heartbeat 傳送目標的帳號 ID 無效。
heartbeat skipped 且原因為 reason=dm-blocked → heartbeat 目標被解析為 DM 類型的目的地，但 agents.defaults.heartbeat.directPolicy（或個別代理的覆寫設定）被設為 block。

相關文件：

AI Setup Assistant

Node paired tool fails

當節點已完成配對但工具執行失敗時，請檢查前景狀態、作業系統權限以及執行核准狀態。OpenClaw Node 相關問題通常可以透過以下指令進行診斷：

使用 openclaw nodes status 查看節點連線狀況。
使用 openclaw nodes describe —node <idOrNameOrIp> 獲取特定節點詳細資訊。
使用 openclaw approvals get —node <idOrNameOrIp> 確認執行核准狀態。
使用 openclaw logs —follow 即時追蹤錯誤日誌。
使用 openclaw status 檢查整體狀態。

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

請特別留意以下幾點：

節點是否在線上且具備預期的功能。
作業系統是否已授予相機、麥克風、定位或螢幕錄製權限。
執行核准 (Exec approvals) 與允許清單 (Allowlist) 的設定狀態。

常見的錯誤代碼與徵兆包括：

NODE_BACKGROUND_UNAVAILABLE → 節點應用程式必須處於前景執行。
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → 缺少作業系統權限。
SYSTEM_RUN_DENIED: approval required → 執行核准尚未完成。
SYSTEM_RUN_DENIED: allowlist miss → 指令被允許清單阻擋。

相關連結：

Browser tool fails

當 Gateway 本身運作正常，但瀏覽器工具執行動作時失敗，你可以透過以下步驟進行排查。OpenClaw Browser 功能的診斷指令如下：

使用 openclaw browser status 檢查瀏覽器外掛狀態。
使用 openclaw browser start —browser-profile openclaw 手動啟動瀏覽器設定檔。
使用 openclaw browser profiles 列出所有可用的設定檔。
使用 openclaw logs —follow 查看瀏覽器相關錯誤。
使用 openclaw doctor 進行自動化環境檢查。

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

請檢查以下項目：

plugins.allow 設定是否已正確包含 browser。
瀏覽器執行檔路徑是否正確。
CDP 設定檔是否可連線。
本地 Chrome 是否可供 existing-session 或 user 設定檔使用。

常見的錯誤代碼與徵兆包括：

unknown command "browser" → 瀏覽器外掛被 plugins.allow 排除。
瀏覽器工具缺失但 browser.enabled=true → 外掛未正確載入。
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 設定檔中沒有開啟的分頁。
Remote CDP for profile "<name>" is not reachable → 無法從 Gateway 主機連線至遠端 CDP。
Browser attachOnly is enabled ... not reachable → 僅附加模式 (attach-only) 的設定檔找不到目標。
Playwright is not available in this gateway build → 目前的 Gateway 安裝缺少完整的 Playwright 套件。
fullPage is not supported for element screenshots → 截圖請求同時使用了 --full-page 與 --element。
element screenshots are not supported for existing-session profiles → Chrome MCP 截圖必須使用頁面擷取或 snapshot --ref。
existing-session file uploads do not support element selectors → 檔案上傳需使用 snapshot ref。
existing-session file uploads currently support one file at a time → 每次呼叫僅限上傳一個檔案。
existing-session dialog handling does not support timeoutMs → 對話框處理不支援逾時設定。
response body is not supported for existing-session profiles yet → responsebody 需要受管理的瀏覽器或原始 CDP 設定檔。
針對 attach-only 或遠端 CDP 的設定檔出現過時的視窗狀態 → 執行 openclaw browser stop —browser-profile <name> 來關閉控制階段並釋放資源。

相關連結：

If you upgraded and something suddenly broke

升級後出現的問題通常是因為設定偏移 (config drift) 或新版本強制執行了更嚴格的預設值。

1) 驗證與 URL 覆寫行為變更

請確認 Gateway 的連線模式與目標 URL 是否正確：

使用 openclaw gateway status 檢查狀態。
使用 openclaw config get gateway.mode 確認模式。
使用 openclaw config get gateway.remote.url 確認遠端 URL。
使用 openclaw config get gateway.auth.mode 確認驗證模式。

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 → 端點可連線但驗證失敗。

2) 綁定與驗證機制變更

若你使用了非本機回送 (non-loopback) 的綁定，安全性要求會更嚴格：

使用 openclaw config get gateway.bind 查看綁定設定。
使用 openclaw config get gateway.auth.mode 查看驗證模式。
使用 openclaw config get gateway.auth.token 查看驗證 Token。
使用 openclaw gateway status 與 openclaw logs —follow 確認運作。

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

請檢查：

非回送綁定 (lan, tailnet, custom) 需要有效的 Gateway 驗證路徑。
舊的 gateway.token 設定無法取代 gateway.auth.token。

常見徵兆：

refusing to bind gateway ... without auth → 非回送綁定缺少驗證路徑。
Connectivity probe: failed → Gateway 執行中但因驗證或 URL 問題無法存取。

3) 配對與裝置識別狀態變更

若裝置識別或配對狀態發生變更，請執行以下檢查：

使用 openclaw devices list 查看裝置清單。
使用 openclaw pairing list —channel <channel> 查看配對狀態。
使用 openclaw logs —follow 與 openclaw doctor 進行診斷。

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

請檢查：

儀表板或節點是否有待處理的裝置核准。
政策或身分變更後，是否有待處理的 DM 配對核准。

常見徵兆：

device identity required → 裝置驗證未通過。
pairing required → 發送者或裝置尚未核准。

若在檢查後服務設定與執行狀態仍不一致，請嘗試重新安裝服務中繼資料：

openclaw gateway install --force
openclaw gateway restart

相關連結：

AI Setup Assistant

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

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。