故障排除

前 60 秒

按顺序运行这些命令：

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

如果 Gateway 可以访问，运行深度探测：

openclaw status --deep

常见”出问题”的情况

openclaw: command not found

几乎都是 Node/npm PATH 的问题。从这里开始：

• 安装（Node/npm PATH 检查）

安装程序失败（或需要完整日志）

用详细模式重新运行安装程序，查看完整的跟踪和 npm 输出：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

如果是 beta 版本安装：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose

你也可以设置 OPENCLAW_VERBOSE=1 环境变量来代替这个标志。

Gateway “unauthorized”、无法连接或持续重连

• Gateway 故障排除
• Gateway 认证

Control UI 在 HTTP 下失败（需要设备身份）

• Gateway 故障排除
• Control UI

docs.openclaw.ai 显示 SSL 错误（Comcast/Xfinity）

某些 Comcast/Xfinity 连接会通过 Xfinity Advanced Security 阻止 docs.openclaw.ai。 禁用 Advanced Security 或将 docs.openclaw.ai 添加到 Allowlist，然后重试。

• Xfinity Advanced Security 帮助：https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security
• 快速检查：试试用手机热点或 VPN 来确认是不是运营商级别的过滤

服务显示正在运行，但 RPC 探测失败

• Gateway 故障排除
• 后台进程 / 服务

模型/认证失败（速率限制、账单、“所有模型都失败”）

• 模型
• OAuth / 认证概念

/model 显示 model not allowed

这通常意味着 agents.defaults.models 被配置为 Allowlist。当它不为空时， 只有列表中的 provider/model 键可以被选择。

• 检查 Allowlist：openclaw config get agents.defaults.models
• 添加你想要的模型（或清空 Allowlist）然后重试 /model
• 使用 /models 浏览允许的 providers/models

提交问题时

粘贴一份安全报告：

openclaw status --all

如果可以的话，附上 openclaw logs --follow 的相关日志尾部。