OpenClawSkills
GitHub
帮助与常见问题 • 8 分钟阅读

故障排除

OpenClaw 安装与运行问题的快速检查与常见修复

Tutorial.step

前 60 秒（快速定位）

先跑这些命令快速获取信号：

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

如果仍未解决，再跑更深的探测：

Bash
openclaw status --deep
Tutorial.step

常见场景

更多常见场景整理中。

Tutorial.step

找不到 openclaw 命令

通常是 PATH 或安装方式问题。先从这里检查：

- Node/npm/PATH 检查

仍失败的话，重新运行安装脚本，并确认你的 shell 载入了更新后的 PATH。

Tutorial.step

安装脚本失败

用 verbose 重新运行安装：

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

安装 beta 版本：

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

提交问题时请附上 --verbose 输出。

如果你在代理/企业网络下，换个网络再试，并保留 verbose 输出。

Tutorial.step

Dashboard 提示 unauthorized

- Gateway 排障

- Gateway 鉴权

使用带 token 的 dashboard URL（或可信 Tailscale 身份头）完成鉴权。

Tutorial.step

Web UI 打不开

- Gateway 排障

- TUI Web 界面

确认网关可达，且端口/绑定模式与你的网络一致。

Tutorial.step

无法访问 docs.openclaw.ai（SSL 错误）

看到 ERR_CERT_DATE_INVALID 时，检查系统时间与 TLS 检查设置。

看到 NET::ERR_CERT_AUTHORITY_INVALID 时，可能是网络在拦截 TLS。

- 换一个网络（例如手机热点）。

- 关闭企业 TLS 检查或安装正确的根证书。

仍失败请提供完整浏览器报错与 OS/网络信息。

Tutorial.step

RPC 探测失败

- Gateway 排障

- 后台进程

确认守护进程在运行，且 RPC endpoint 可达。

Tutorial.step

模型/提供商鉴权失败

- 模型状态

- OAuth 概念

检查提供商凭证与当前启用的鉴权 profile。

Tutorial.step

模型不被允许

出现 Model … is not allowed 说明网关策略阻止了该模型。

更新配置允许该模型，或切换到允许的模型。

- 检查 models.default 中配置的默认模型。

- 用 openclaw models status 验证提供商可用性。

- 如果使用订阅 OAuth，确认选择了正确的 profile。

不确定时请贴脱敏后的 <code>openclaw models status</code> 输出。

Tutorial.step

提交问题（Issue）

求助时请提供可复现描述，以及这些输出：

Bash
openclaw status --all

附上 openclaw status --all（会脱敏 token）和一小段相关日志尾部。