​

gateway/troubleshooting.md

​

命令阶梯

openclaw gateway status
openclaw doctor

• openclaw gateway status 显示 Runtime: running 且 RPC probe: ok。
• openclaw doctor 报告没有阻塞性的配置/服务问题。
• openclaw channels status --probe

​

消息未触发

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # 如果 logout 无法完全清除所有内容
openclaw channels login --verbose       # 重新扫描二维码

• Pairing pending for DM senders.
• Group mention gating (requireMention, mentionPatterns).
• Channel/group allowlist mismatches.

• drop guild message (mention required → group message ignored until mention.
• pairing request → sender needs approval.
• blocked / allowlist → sender/channel was filtered by policy.

• 文档：Discord、渠道故障排除。
• /channels/pairing
• /channels/groups

​

Dashboard control ui connectivity

`openclaw gateway status` 和 `openclaw doctor` 在服务看起来正在运行但端口关闭时会显示日志中的**最后 Gateway 网关错误**。

• Correct probe URL and dashboard URL.
• Auth mode/token mismatch between client and gateway.
• HTTP usage where device identity is required.

• device identity required → non-secure context or missing device auth.
• unauthorized / reconnect loop → token/password mismatch.
• gateway connect failed: → wrong host/port/url target.

• /web/control-ui
• /gateway/authentication
• /gateway/remote

​

服务运行但端口未监听

openclaw gateway status

• Runtime: stopped with exit hints.
• Config (cli): ... 和 Config (service): ... 通常应该匹配。
• Port/listener conflicts.

• “Gateway start blocked: set gateway.mode=local” openclaw config set gateway.mode local 如果你使用专用的 openclaw 用户通过 Podman 运行 OpenClaw，配置文件位于 ~openclaw/.openclaw/openclaw.json。
• 如果 Last gateway error: 提到”refusing to bind … without auth”
• another gateway instance is already listening / EADDRINUSE → port conflict.

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

​

Channel connected messages not flowing

运行 `openclaw channels status --probe` 获取审计提示。

• DM policy (pairing, allowlist, open, disabled).
• Group allowlist and mention requirements.
• Missing channel API permissions/scopes.

• mention required → message ignored by group mention policy.
• pairing / pending approval traces → sender is not approved.
• missing_scope, not_in_channel, Forbidden, 401/403 → channel auth/permissions issue.

• 特定提供商的快捷方式：/channels/troubleshooting
• 参见 WhatsApp 设置。
• /channels/telegram
• 参见 流式传输。

​

Cron and heartbeat delivery

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

• Cron enabled and next wake present.
• Job run history status (ok, skipped, error).
• Heartbeat skip reasons (quiet-hours, requests-in-flight, alerts-disabled).

• cron: scheduler disabled; jobs will not run automatically → cron disabled.
• cron: timer tick failed → scheduler tick failed; check file/log/runtime errors.
• heartbeat skipped with reason=quiet-hours → outside active hours window.
• heartbeat: unknown accountId → invalid account id for heartbeat delivery target.

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

​

Node paired tool fails

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

• Node online with expected capabilities.
• OS permission grants for camera/mic/location/screen.
• Exec approvals and allowlist state.

• NODE_BACKGROUND_UNAVAILABLE → node app must be in foreground.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → missing OS permission.
• SYSTEM_RUN_DENIED: approval required → exec approval pending.
• SYSTEM_RUN_DENIED: allowlist miss → command blocked by allowlist.

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

​

Browser tool fails

openclaw doctor
openclaw doctor --fix

• Valid browser executable path.
• CDP profile reachability.
• Extension relay tab attachment for profile="chrome".

• 如果你看到 "Failed to start Chrome CDP on port 18800"：
• browser.executablePath not found → configured path is invalid.
• Chrome extension relay is running, but no tab is connected → 扩展中继未附加。
• Browser attachOnly is enabled ... not reachable → 仅附加配置没有可达目标。

• 完整指南： 参见 browser-linux-troubleshooting
• /tools/chrome-extension
• /tools/browser

​

如果你升级后突然出现故障

​

1. 认证和 URL 覆盖行为已更改

openclaw config set gateway.mode remote
openclaw config set gateway.remote.url "wss://gateway.example.com"

• 如果你设置了 gateway.mode=remote，CLI 默认使用远程 URL。服务可能仍在本地运行，但你的 CLI 可能在探测错误的位置。使用 openclaw gateway status 查看服务解析的端口 + 探测目标（或传递 --url）。
• Explicit --url calls do not fall back to stored credentials.

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

​

2. 绑定和认证防护更严格了

# 在 Gateway 网关主机上运行（粘贴 setup-token）
openclaw models auth setup-token --provider anthropic
openclaw models status

• Non-loopback binds (lan, tailnet, custom) need auth configured.
• gateway.token 被忽略；使用 gateway.auth.token。

• Gateway 网关卡在”Starting…” without auth` → 绑定与认证不匹配。
• RPC probe: failed 且运行时仍在运行 → 网关存活，但以当前认证/URL 无法访问。

​

3. 配对和设备身份状态已更改

openclaw pairing list <channel>

• 仪表板/节点存在待批准的设备。
• 策略或身份更改后，存在待批准的 DM 配对。

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

openclaw doctor
openclaw gateway restart

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