Gateway 疑難排解

本頁是深度排查手冊。 如果你想先快速分類，請從 /help/troubleshooting 開始。

指令階梯

先按這個順序跑一遍：

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

健康的預期信號：

  • openclaw gateway status 顯示 Runtime: running 和 RPC probe: ok。
  • openclaw doctor 沒有報告阻斷性的設定/服務問題。
  • openclaw channels status --probe 顯示頻道已連線/就緒。

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 路徑的長 session/模型執行時才失敗。

修正方式：

  1. 停用該模型的 context1m 以退回到一般的上下文視窗。
  2. 使用有計費的 Anthropic API key，或在訂閱帳號上啟用 Anthropic Extra Usage。
  3. 設定 fallback 模型，讓 Anthropic 長上下文請求被拒絕時仍能繼續執行。

相關：

沒有回覆

如果頻道正常但什麼都不回，先檢查路由和策略，再去重連任何東西。

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

檢查要點：

  • DM 發送者的配對是否待處理。
  • 群組 mention 門檻（requireMention、mentionPatterns）。
  • 頻道/群組白名單是否不匹配。

常見特徵：

  • drop guild message (mention required → 群組訊息因未 mention 而被忽略。
  • pairing request → 發送者需要核准。
  • blocked / allowlist → 發送者/頻道被策略過濾。

相關：

儀表板 control UI 連線問題

當儀表板/control UI 無法連線時，驗證 URL、認證模式和安全上下文的假設。

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

檢查要點：

  • 正確的 probe URL 和儀表板 URL。
  • 用戶端和 gateway 之間的認證模式/token 是否不匹配。
  • 在需要裝置身分的情境中使用了 HTTP。

常見特徵：

  • device identity required → 非安全上下文或缺少裝置認證。
  • device nonce required / device nonce mismatch → 用戶端未完成基於挑戰的裝置認證流程（connect.challenge + device.nonce）。
  • device signature invalid / device signature expired → 用戶端在當前交握中簽署了錯誤的 payload（或時間戳過期）。
  • AUTH_TOKEN_MISMATCH 且 canRetryWithDeviceToken=true → 用戶端可以用快取的裝置 token 做一次受信任重試。
  • 重試後仍持續 unauthorized → 共享 token/裝置 token 不一致；重新整理 token 設定，必要時重新核准/輪替裝置 token。
  • gateway connect failed: → 主機/連接埠/URL 目標錯誤。

認證詳細代碼快速對照

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

詳細代碼含義建議動作
AUTH_TOKEN_MISSING用戶端未發送必要的共享 token。在用戶端貼上/設定 token 後重試。儀表板路徑：openclaw config get gateway.auth.token 然後貼到 Control UI 設定中。
AUTH_TOKEN_MISMATCH共享 token 與 gateway 認證 token 不匹配。如果 canRetryWithDeviceToken=true，允許一次受信任重試。如果仍失敗，執行 token drift 恢復檢查清單。
AUTH_DEVICE_TOKEN_MISMATCH快取的裝置 token 已過期或被撤銷。使用 devices CLI 輪替/重新核准裝置 token，然後重新連線。
PAIRING_REQUIRED裝置身分已知但未被核准用於此角色。核准待處理的請求：openclaw devices list 然後 openclaw devices approve <requestId>。

裝置認證 v2 遷移檢查：

openclaw --version
openclaw doctor
openclaw gateway status

如果日誌顯示 nonce/簽章錯誤，請更新連線用戶端並驗證它是否：

  1. 等待 connect.challenge
  2. 簽署綁定挑戰的 payload
  3. 在 connect.params.device.nonce 中送出相同的 challenge nonce

相關：

Gateway 服務未執行

當服務已安裝但程序無法保持運行時使用。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

檢查要點：

  • Runtime: stopped 並附帶退出提示。
  • 服務設定不匹配（Config (cli) vs Config (service)）。
  • 連接埠/監聽衝突。

常見特徵：

  • Gateway start blocked: set gateway.mode=local → 本機 gateway 模式未啟用。修正：在設定中設 gateway.mode="local"（或執行 openclaw configure）。如果你透過 Podman 使用專用 openclaw 使用者執行 OpenClaw，設定位於 ~openclaw/.openclaw/openclaw.json。
  • refusing to bind gateway ... without auth → 非 loopback 綁定但未設定 token/password。
  • another gateway instance is already listening / EADDRINUSE → 連接埠衝突。

相關：

頻道已連線但訊息不流通

如果頻道狀態是已連線但訊息流程停擺，重點檢查策略、權限和頻道特定的發送規則。

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 權限/scope。

常見特徵：

  • mention required → 訊息因群組 mention 策略被忽略。
  • pairing / 待核准的追蹤記錄 → 發送者未被核准。
  • missing_scope、not_in_channel、Forbidden、401/403 → 頻道認證/權限問題。

相關：

Cron 和 heartbeat 發送

如果 cron 或 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）。

常見特徵：

  • cron: scheduler disabled; jobs will not run automatically → cron 已停用。
  • cron: timer tick failed → 排程器 tick 失敗；檢查檔案/日誌/執行時期錯誤。
  • heartbeat skipped 且 reason=quiet-hours → 不在活動時段內。
  • heartbeat: unknown accountId → heartbeat 發送目標的帳號 ID 無效。
  • heartbeat skipped 且 reason=dm-blocked → heartbeat 目標解析到 DM 型目的地，但 agents.defaults.heartbeat.directPolicy（或各代理覆寫）設為 block。

相關：

已配對節點的工具失敗

如果節點已配對但工具失敗，釐清前景狀態、權限和核准狀態。

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

檢查要點：

  • 節點是否在線且具備預期的能力。
  • OS 層級的 camera/mic/location/screen 權限授予狀況。
  • Exec 核准和白名單狀態。

常見特徵：

  • NODE_BACKGROUND_UNAVAILABLE → 節點 app 必須在前景。
  • *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → 缺少 OS 權限。
  • SYSTEM_RUN_DENIED: approval required → exec 核准待處理。
  • SYSTEM_RUN_DENIED: allowlist miss → 指令被白名單封鎖。

相關：

瀏覽器工具失敗

當瀏覽器工具動作失敗，但 gateway 本身是健康的時候使用。

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

檢查要點：

  • 瀏覽器可執行檔路徑是否有效。
  • CDP profile 是否可連線。
  • 使用 profile="chrome" 時的擴充功能 relay tab 連接狀態。

常見特徵：

  • Failed to start Chrome CDP on port → 瀏覽器程序啟動失敗。
  • browser.executablePath not found → 設定的路徑無效。
  • Chrome extension relay is running, but no tab is connected → 擴充功能 relay 未附加。
  • Browser attachOnly is enabled ... not reachable → attach-only profile 沒有可連線的目標。

相關：

升級後突然故障

多數升級後的故障是設定偏移或更嚴格的預設值被強制執行。

1) 認證和 URL 覆寫行為改變

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 呼叫不會 fallback 到已儲存的憑證。

常見特徵：

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

2) 綁定和認證防護變得更嚴格

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

檢查事項：

  • 非 loopback 綁定（lan、tailnet、custom）需要設定認證。
  • 舊的 key 如 gateway.token 不能取代 gateway.auth.token。

常見特徵：

  • refusing to bind gateway ... without auth → 綁定 + 認證不匹配。
  • RPC probe: failed 但 runtime 在運行 → gateway 存活但以目前的認證/URL 無法存取。

3) 配對和裝置身分狀態改變

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

檢查事項：

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

常見特徵：

  • device identity required → 裝置認證未滿足。
  • pairing required → 發送者/裝置需要被核准。

如果服務設定和 runtime 在檢查後仍不一致，從相同的 profile/狀態目錄重新安裝服務中繼資料：

openclaw gateway install --force
openclaw gateway restart

相關：

arrow_back
上一頁
Multiple Gateways
下一頁
Security
arrow_forward