Gateway 故障排查

诊断命令梯队

按顺序执行：

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

健康信号：

openclaw gateway status 显示 Runtime: running、Connectivity probe: ok
openclaw doctor 无阻塞配置/服务问题
openclaw channels status --probe 显示 works 或 audit ok

版本分裂安装（Split Brain）

症状：更新后 gateway 服务意外停止，或日志显示 openclaw 二进制比 openclaw.json 写入版本旧。

which openclaw && openclaw --version
openclaw config get meta.lastTouchedVersion

修复：

修复 PATH 使 openclaw 指向新版本
openclaw gateway install --force && openclaw gateway restart
移除指向旧二进制的过期包装器

本地 OpenAI 兼容后端问题

症状：直接 curl 成功，但 agent 运行失败。

常见原因及修复：

model_not_found → 确认 baseUrl 含 /v1，api 为 "openai-completions"
messages[].content: invalid type → 设置 compat.requiresStringContent: true
validation.keys 错误 → 设置 compat.strictMessageKeys: true
工具 schema 问题 → 设置 compat.supportsTools: false

无回复

openclaw pairing list --channel <channel>
openclaw config get channels

常见原因：

drop guild message (mention required) → 群组消息需要 mention
pairing request → 发送者需要审批
blocked / allowlist → 发送者被策略过滤

Dashboard Control UI 连接问题

openclaw gateway status --json

认证错误码快速映射：

错误码	含义	处理方式
`AUTH_TOKEN_MISSING`	未发送 token	粘贴/设置 token 后重试
`AUTH_TOKEN_MISMATCH`	Token 不匹配	运行 token 漂移恢复流程
`AUTH_DEVICE_TOKEN_MISMATCH`	设备 token 过期	轮换/重新审批设备 token
`PAIRING_REQUIRED`	设备需要审批	`openclaw devices approve <requestId>`

Gateway 服务未运行

常见原因：

Gateway start blocked: set gateway.mode=local → 设置 gateway.mode="local"
refusing to bind gateway ... without auth → 非 loopback 绑定需要认证
EADDRINUSE → 端口冲突，释放端口或换端口
System-level OpenClaw gateway service detected → 系统级服务与用户级服务冲突

配置无效

openclaw config validate
openclaw doctor

修复：

openclaw doctor --fix 修复前缀/损坏配置
从 .clobbered.* 或 .rejected.* 复制需要的键
重启前运行 openclaw config validate

升级后突然出问题

检查顺序：

Auth 和 URL 覆盖行为变化：openclaw config get gateway.mode
绑定和认证守卫更严格：openclaw config get gateway.bind
配对和设备身份状态变化：openclaw devices list

若服务配置和运行时仍不一致：

openclaw gateway install --force
openclaw gateway restart

相关链接

gateway-doctor — doctor 修复工具
gateway-health — 健康检查