Gateway 故障排查

本页是深度排查手册。 如果你想先走快速分诊流程，请访问 /openclaw/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 显示实时的每账号传输状态，以及（受支持时）探测/审计结果，如 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 路径的长会话/模型运行时失败。

解决方案：

1. 禁用该模型的 context1m，回退到普通上下文窗口。
2. 使用已计费的 Anthropic API key，或在 Anthropic OAuth/订阅账户上启用 Anthropic 额外用量。
3. 配置备用模型，当 Anthropic 长上下文请求被拒绝时继续运行。

相关文档：

• /openclaw/providers/anthropic
• /openclaw/reference/token-use

没有回复

频道正常但没有任何响应时，在重新连接任何东西之前先检查路由和策略。

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 → 发送者/频道被策略过滤。

相关文档：

• /openclaw/channels/troubleshooting
• /openclaw/channels/pairing
• /openclaw/channels/groups

控制台/控制 UI 连接失败

当 dashboard/控制 UI 无法连接时，验证 URL、认证模式和安全上下文假设。

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

排查要点：

• 正确的探测 URL 和 dashboard URL。
• 客户端和 gateway 之间认证模式/token 不匹配。
• 在需要设备身份的情况下使用了 HTTP。

常见错误特征：

• device identity required → 非安全上下文或缺少设备认证。
• origin not allowed → 浏览器 Origin 不在 gateway.controlUi.allowedOrigins 中（或你从非 loopback 浏览器 origin 连接但没有配置显式允许列表）。
• device nonce required / device nonce mismatch → 客户端未完成基于挑战的设备认证流（connect.challenge + device.nonce）。
• device signature invalid / device signature expired → 客户端对当前握手签署了错误的载荷（或时间戳过期）。
• AUTH_TOKEN_MISMATCH 且 canRetryWithDeviceToken=true → 客户端可以用缓存的设备 token 进行一次可信重试。
• 该缓存 token 重试会复用与配对设备 token 一起存储的作用域集。显式传入 deviceToken / scopes 的调用方则保持其请求的作用域集。
• 在此重试路径之外，connect 认证优先级依次为：显式共享 token/密码 > 显式 deviceToken > 存储的设备 token > bootstrap token。
• 在 Tailscale Serve 控制 UI 的异步路径上，同一 {scope, ip} 的失败重试会在限速器记录失败前被串行化，因此同一客户端的两个并发错误重试，第二次可能返回 retry later 而非两次独立的 mismatch。
• too many failed authentication attempts (retry later) 来自浏览器 loopback 客户端 → 同一归一化 Origin 多次失败后会被暂时锁定；来自其他 localhost origin 的请求使用独立桶。
• 重试后仍出现 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 然后粘贴到控制 UI 设置中。
AUTH_TOKEN_MISMATCH	共享 token 与 gateway 认证 token 不匹配。	如果 canRetryWithDeviceToken=true，允许一次可信重试。缓存 token 重试复用已批准的存储作用域集；显式传入 deviceToken / scopes 的调用方保持其请求作用域。仍然失败则运行 token 漂移恢复清单。
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. 签署绑定挑战的载荷
3. 发送带相同挑战 nonce 的 connect.params.device.nonce

如果 openclaw devices rotate / revoke / remove 被意外拒绝：

• 配对设备 token 会话只能管理自身的设备，除非调用方同时具有 operator.admin
• openclaw devices rotate --scope ... 只能请求当前调用方会话已持有的 operator 作用域

相关文档：

• /openclaw/web/control-ui
• /openclaw/gateway/configuration（gateway 认证模式）
• /openclaw/gateway/trusted-proxy-auth
• /openclaw/gateway/remote
• /openclaw/cli/devices

Gateway 服务不运行

当服务已安装但进程无法保持运行时使用：

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # 同时扫描系统级服务

排查要点：

• 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 来重建预期的本地模式配置。如果通过 Podman 运行 OpenClaw，默认配置路径为 ~/.openclaw/openclaw.json。
• refusing to bind gateway ... without auth → 非 loopback 绑定但没有有效的 gateway 认证路径（token/密码，或已配置的 trusted-proxy）。
• another gateway instance is already listening / EADDRINUSE → 端口冲突。
• Other gateway-like services detected (best effort) → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数场景应在每台机器只运行一个 gateway；如果确实需要多个，请隔离端口 + 配置/状态/工作区。参见 /openclaw/gateway#multiple-gateways-same-host。

相关文档：

• /openclaw/gateway/background-process
• /openclaw/gateway/configuration
• /openclaw/gateway/doctor

Gateway probe 警告

当 openclaw gateway probe 能够连接到目标，但仍然打印了警告块时使用：

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

排查要点：

• JSON 输出中的 warnings[].code 和 primaryTargetId。
• 警告是关于 SSH 回退、多个 gateway、缺少作用域，还是未解析的认证引用。

常见错误特征：

• SSH tunnel failed to start; falling back to direct probes. → SSH 配置失败，但命令仍然尝试了直接配置/loopback 目标。
• multiple reachable gateways detected → 多个目标响应了探测。通常意味着有意的多 gateway 配置或过期/重复监听器。
• Probe diagnostics are limited by gateway scopes (missing operator.read) → 连接成功，但 RPC 详情受作用域限制；配对设备身份或使用含 operator.read 的凭据。
• 未解析的 gateway.auth.* / gateway.remote.* SecretRef 警告文本 → 该命令路径在失败目标上无法获取认证材料。

相关文档：

• /openclaw/cli/gateway
• /openclaw/gateway#multiple-gateways-same-host
• /openclaw/gateway/remote

频道已连接但消息不流动

频道状态为已连接但消息流中断时，重点检查策略、权限和频道特定的交付规则：

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）。
• 群组允许列表和提及需求。
• 缺少频道 API 权限/范围。

常见错误特征：

• mention required → 群组提及策略忽略了消息。
• pairing / 待审批跟踪 → 发送者未获批准。
• missing_scope、not_in_channel、Forbidden、401/403 → 频道认证/权限问题。

相关文档：

• /openclaw/channels/troubleshooting
• /openclaw/channels/whatsapp
• /openclaw/channels/telegram
• /openclaw/channels/discord

定时任务和心跳投递

如果定时任务或心跳未运行或未投递，先验证调度器状态，再验证投递目标：

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

排查要点：

• 定时任务已启用且下次唤醒时间存在。
• 任务运行历史状态（ok、skipped、error）。
• 心跳跳过原因（quiet-hours、requests-in-flight、alerts-disabled、empty-heartbeat-file、no-tasks-due）。

常见错误特征：

• cron: scheduler disabled; jobs will not run automatically → 定时任务已禁用。
• 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: 块，但本次 tick 没有任何到期任务。
• heartbeat: unknown accountId → 心跳投递目标的 account id 无效。
• heartbeat skipped 且 reason=dm-blocked → 心跳目标解析到 DM 类目标，但 agents.defaults.heartbeat.directPolicy（或每个 agent 覆盖）设为 block。

相关文档：

• /openclaw/automation/cron-jobs#troubleshooting
• /openclaw/automation/cron-jobs
• /openclaw/gateway/heartbeat

节点已配对但工具失败

节点已配对但工具失败时，隔离前台、权限和审批状态：

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

排查要点：

• 节点在线且具有预期功能。
• 摄像头/麦克风/位置/屏幕的 OS 权限授予。
• Exec 审批和允许列表状态。

常见错误特征：

• NODE_BACKGROUND_UNAVAILABLE → 节点应用必须在前台。
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → 缺少 OS 权限。
• SYSTEM_RUN_DENIED: approval required → exec 审批待处理。
• SYSTEM_RUN_DENIED: allowlist miss → 命令被允许列表阻止。

相关文档：

• /openclaw/nodes/troubleshooting
• /openclaw/nodes/index
• /openclaw/tools/exec-approvals

浏览器工具失败

Gateway 本身健康但浏览器工具操作失败时使用：

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

排查要点：

• 检查 plugins.allow 是否已设置并包含 browser。
• 有效的浏览器可执行文件路径。
• CDP 配置文件可达性。
• existing-session / user 配置文件的本地 Chrome 可用性。

常见错误特征：

• unknown command "browser" 或 unknown command 'browser' → 捆绑浏览器插件被 plugins.allow 排除。
• 浏览器工具缺失/不可用但 browser.enabled=true → 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 使用了不支持的协议（如 file: 或 ftp:）。
• 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 端点从 gateway 主机不可达。
• Browser attachOnly is enabled ... not reachable 或 Browser attachOnly is enabled and CDP websocket ... is not reachable → 仅附加配置文件没有可达目标，或 HTTP 端点响应但 CDP WebSocket 仍然无法打开。
• Playwright is not available in this gateway build; '<feature>' is unsupported. → 当前 gateway 安装缺少完整的 Playwright 包；ARIA 快照和基础页面截图仍然可用，但导航、AI 快照、CSS 选择器元素截图和 PDF 导出不可用。
• fullPage is not supported for element screenshots → 截图请求同时传入了 --full-page 和 --ref / --element。
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session 截图调用必须使用页面捕获或快照 --ref，而非 CSS --element。
• existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP 上传钩子需要快照 ref，而非 CSS 选择器。
• existing-session file uploads currently support one file at a time. → 在 Chrome MCP 配置文件上每次调用只能上传一个文件。
• existing-session dialog handling does not support timeoutMs. → Chrome MCP 配置文件上的对话框钩子不支持超时覆盖。
• response body is not supported for existing-session profiles yet. → responsebody 仍然需要托管浏览器或原始 CDP 配置文件。
• 仅附加或远程 CDP 配置文件上的过期 viewport / 深色模式 / 语言 / 离线覆盖 → 运行 openclaw browser stop --browser-profile <name> 关闭当前控制会话并释放 Playwright/CDP 仿真状态，而无需重启整个 gateway。

相关文档：

• /openclaw/tools/browser-linux-troubleshooting
• /openclaw/tools/browser

升级后突然出现问题

大多数升级后的问题是配置漂移或更严格的默认值被强制执行。

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 调用不会回退到存储的凭据。

常见错误特征：

• gateway connect failed: → URL 目标错误。
• unauthorized → 端点可达但认证错误。

2）绑定和认证防护更严格

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

检查内容：

• 非 loopback 绑定（lan、tailnet、custom）需要有效的 gateway 认证路径：共享 token/密码认证，或已正确配置的非 loopback trusted-proxy 部署。
• 旧密钥如 gateway.token 不能替代 gateway.auth.token。

常见错误特征：

• refusing to bind gateway ... without auth → 非 loopback 绑定但没有有效的 gateway 认证路径。
• RPC probe: failed 但运行时在运行 → gateway 存活但当前认证/URL 无法访问。

3）配对和设备身份状态变化

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

检查内容：

• dashboard/节点的待处理设备审批。
• 策略或身份变更后的 DM 配对审批待处理。

常见错误特征：

• device identity required → 设备认证未满足。
• pairing required → 发送者/设备必须被审批。

如果服务配置和运行时在检查后仍然不一致，从相同配置文件/状态目录重新安装服务元数据：

openclaw gateway install --force
openclaw gateway restart

相关文档：

• /openclaw/gateway/pairing
• /openclaw/gateway/authentication
• /openclaw/gateway/background-process