故障排除

出问题了？别慌！按照下面的方法一步步排查，大部分问题都能自己解决。

🔍 诊断阶梯（按顺序来）

当 OpenClaw 出现问题时，按照以下顺序逐步排查：

检查运行状态

openclaw status

看看 OpenClaw 是否还在运行。如果显示 "stopped" 或报错，请先尝试重新启动。

检查网关状态

openclaw gateway status

网关是 OpenClaw 连接聊天平台的桥梁。如果网关状态异常，聊天消息就无法收发。

查看日志

openclaw logs

日志里记录了 OpenClaw 运行的所有细节。如果有错误，日志里通常会有红色的错误信息告诉你哪里出了问题。

运行健康检查

openclaw doctor

全面的健康检查，会告诉你哪些组件正常、哪些有问题。

检查频道连接

openclaw channels status

查看各个聊天频道的连接状态，看看是不是某个频道断开了。

🐛 常见错误和解决方法

错误："openclaw: command not found"

原因：系统找不到 openclaw 命令，通常是 PATH 环境变量的问题。

解决：

# 检查 openclaw 安装位置
npm list -g openclaw

# 将 npm 全局目录加入 PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# 将上面的命令添加到你的 shell 配置文件中以永久生效
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

错误：端口冲突（EADDRINUSE: address already in use :::18789）

原因：端口 18789 已经被另一个程序占用了。

解决：

# 查找占用端口的进程
lsof -i :18789

# 停止旧的 OpenClaw 进程
openclaw stop

# 如果不是 OpenClaw 进程，你可以在配置中更换端口
# 编辑 ~/.openclaw/openclaw.json，修改 port 值

错误：429 Too Many Requests（速率限制）

原因：你发送的请求太频繁了，AI 模型提供商对 API 调用有频率限制。

解决：

等几分钟后再试
减少发送消息的频率
升级你的 API 付费计划以获得更高的速率限制
考虑切换到限制更宽松的模型提供商

错误：网关无法启动

原因：可能是 Bot Token 无效、网络连接问题、或聊天平台 API 变更。

解决：

# 检查网关日志
openclaw gateway logs

# 验证 Bot Token 是否有效
openclaw channels verify

# 重启网关
openclaw gateway restart

错误：消息发不出去

原因：可能是频道配置错误、网络问题、或 Bot 权限不足。

解决：

检查频道状态：openclaw channels status
确认 Bot 在对应平台上有发送消息的权限
检查网络连接是否正常
查看日志中是否有具体的错误信息

错误：控制面板打不开

原因：OpenClaw 服务可能没有在运行，或者端口配置有误。

解决：

# 确认 OpenClaw 正在运行
openclaw status

# 如果没有运行，启动它
openclaw start

# 然后尝试打开控制面板
openclaw dashboard

# 或者直接在浏览器访问
# http://127.0.0.1:18789/

🆘 还是解决不了？

如果按照上面的方法还是无法解决问题，你可以：

去 GitHub Issues 搜索或提交问题
加入 OpenClaw 的 Discord 社区寻求帮助
在提问时请附上 openclaw doctor 和 openclaw logs 的输出