Skip to main content

​
Gateway 閘道器 疑難排解

This page is the deep runbook. 本頁為深入的操作手冊。 Start at /help/troubleshooting if you want the fast triage flow first.

​
指令階梯

請先依序執行以下指令：
預期的健康訊號：
  • openclaw gateway status 顯示 Runtime: running 與 RPC probe: ok。
  • openclaw doctor 回報沒有阻擋的設定或服務問題。
  • openclaw channels status --probe 顯示已連線／就緒的頻道。

​
沒有回覆

如果頻道已啟用但沒有任何回應，請在重新連線任何項目之前，先檢查路由與政策。
Look for:
  • DM 發送者的配對仍在等待中。
  • 群組提及限制（requireMention、mentionPatterns）。
  • 頻道／群組允許清單不相符。
Common signatures:
  • drop guild message (mention required → 群組訊息在被提及之前會被忽略。
  • pairing request → 寄件者需要核准。
  • blocked / allowlist → 寄件者／頻道被政策過濾。
Related:

​
Dashboard 控制 UI 連線

當 dashboard／控制 UI 無法連線時，請驗證 URL、驗證模式，以及安全內容的假設。
尋找：
  • 正確的探測 URL 與 dashboard URL。
  • 用戶端與 gateway 之間的驗證模式／權杖不一致。
  • 在需要裝置身分識別時使用了 HTTP。
Common signatures:
  • device identity required → 非安全內容或缺少裝置驗證。
  • unauthorized ／ 重連循環 → 權杖／密碼不一致。
  • gateway connect failed: → 主機／連接埠／URL 目標錯誤。
Related:

​
Gateway 服務未執行

Use this when service is installed but process does not stay up.
Look for:
  • Runtime: stopped 及其結束提示。
  • 服務設定不一致（Config (cli) 與 Config (service)）。
  • Port/listener conflicts.
Common signatures:
  • Gateway start blocked: set gateway.mode=local → 未啟用本機 Gateway 模式。 修正方式：在您的設定中將 gateway.mode="local"（或執行 openclaw configure）。 如果您使用專用的 openclaw 使用者透過 Podman 執行 OpenClaw，設定檔位於 ~openclaw/.openclaw/openclaw.json。
  • refusing to bind gateway ... without auth → 非 local loopback 綁定且未設定權杖／密碼。
  • another gateway instance is already listening ／ EADDRINUSE → 連接埠衝突。
Related:

​
頻道已連線但訊息未流動

如果通道狀態為已連線但訊息流量停滯，請專注於政策、權限，以及通道特定的投遞規則。
Look for:
  • 私訊政策（pairing、allowlist、open、disabled）。
  • 群組允許清單與提及需求。
  • 缺少頻道 API 權限／範圍。
Common signatures:
  • mention required → 訊息被群組提及政策忽略。
  • pairing ／ 等待核准的痕跡 → 寄件者尚未核准。
  • missing_scope、not_in_channel、Forbidden、401/403 → 頻道驗證／權限問題。
Related:

​
Cron 與心跳投遞

如果 cron 或心跳未執行或未投遞，請先驗證排程器狀態，再檢查投遞目標。
Look for:
  • 已啟用 cron 且存在下一次喚醒時間。
  • 工作執行歷史狀態（ok、skipped、error）。
  • 心跳跳過原因（quiet-hours、requests-in-flight、alerts-disabled）。
Common signatures:
  • cron: scheduler disabled; jobs will not run automatically → cron 已停用。
  • cron: timer tick failed → 排程器 tick 失敗；請檢查檔案／日誌／執行階段錯誤。
  • heartbeat skipped 搭配 reason=quiet-hours → 位於啟用時段視窗之外。
  • heartbeat: unknown accountId → 心跳投遞目標的帳戶 ID 無效。
Related:

​
已配對的節點工具失敗

If a node is paired but tools fail, isolate foreground, permission, and approval state.
尋找：
  • Node online with expected capabilities.
  • 作業系統對相機／麥克風／位置／螢幕的權限授與。
  • Exec approvals and allowlist state.
Common signatures:
  • NODE_BACKGROUND_UNAVAILABLE → 節點應用程式必須在前景。
  • *_PERMISSION_REQUIRED ／ LOCATION_PERMISSION_REQUIRED → 缺少作業系統權限。
  • SYSTEM_RUN_DENIED: approval required → Exec 核准仍在等待中。
  • SYSTEM_RUN_DENIED: allowlist miss → 指令被允許清單阻擋。
Related:

​
瀏覽器工具失敗

當 Gateway 本身健康，但瀏覽器工具動作仍然失敗時使用。
Look for:
  • Valid browser executable path.
  • CDP 設定檔可達性。
  • 針對 profile="chrome" 的擴充功能轉接分頁附掛。
Common signatures:
  • Failed to start Chrome CDP on port → 瀏覽器程序啟動失敗。
  • browser.executablePath not found → 設定的路徑無效。
  • Chrome extension relay is running, but no tab is connected → 擴充功能轉接未附掛。
  • Browser attachOnly is enabled ... not reachable → 僅附掛的設定檔沒有可達的目標。
Related:

​
若你升級後突然出現問題

Most post-upgrade breakage is config drift or stricter defaults now being enforced.

​
1. 驗證與 URL 覆寫行為已變更

檢查項目：
  • 若 gateway.mode=remote，CLI 呼叫可能指向遠端，而你的本機服務其實正常。
  • 明確的 --url 呼叫不會回退到已儲存的認證。
Common signatures:
  • gateway connect failed: → URL 目標錯誤。
  • unauthorized → 端點可達但驗證錯誤。

​
2. 綁定與驗證防護更為嚴格

檢查項目：
  • 非 local loopback 綁定（lan、tailnet、custom）需要設定驗證。
  • 舊金鑰如 gateway.token 不會取代 gateway.auth.token。
Common signatures:
  • refusing to bind gateway ... without auth → 綁定與驗證不相符。
  • 在執行階段仍在運作時出現 RPC probe: failed → Gateway 存活，但以目前的驗證／URL 無法存取。

​
3. 配對與裝置身分識別狀態已變更

檢查項目：
  • Pending device approvals for dashboard/nodes.
  • 在政策或身分變更後，DM 配對核准待處理。
Common signatures:
  • device identity required → 裝置驗證未滿足。
  • pairing required → 寄件者／裝置必須被核准。
如果在檢查後服務設定與執行階段仍不一致，請從相同的設定檔／狀態目錄重新安裝服務中繼資料：
Related: