故障排除

前 60 秒

按顺序运行这些命令:

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

如果网关可访问,进行深度探测:

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 而不是使用标志。

网关"未授权"、无法连接或持续重连

• 网关故障排除
• 网关身份验证

控制 UI 在 HTTP 上失败(需要设备身份)

• 网关故障排除
• 控制 UI

docs.openclaw.ai 显示 SSL 错误 (Comcast/Xfinity)

某些 Comcast/Xfinity 连接通过 Xfinity Advanced Security 阻止 docs.openclaw.ai。 禁用 Advanced Security 或将 docs.openclaw.ai 添加到允许列表,然后重试。

• Xfinity Advanced Security 帮助: https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security
• 快速检查:尝试移动热点或 VPN 以确认是 ISP 级别的过滤

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

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

模型/身份验证失败(速率限制、计费、"所有模型失败")

• 模型
• OAuth / 身份验证概念

/model 显示 model not allowed

这通常意味着 agents.defaults.models 被配置为允许列表。当它非空时, 只能选择这些提供商/模型键。

• 检查允许列表: openclaw config get agents.defaults.models
• 添加你想要的模型(或清除允许列表)然后重试 /model
• 使用 /models 浏览允许的提供商/模型

提交问题时

粘贴安全报告:

openclaw status --all

如果可以,请包含来自 openclaw logs --follow 的相关日志尾部。