在安装和使用OpenClaw的过程中，难免会遇到各种问题。本文汇总了社区中最常见的错误场景和对应的解决方案，帮助你快速定位和修复问题。在排查之前，强烈建议先运行OpenClaw内置的诊断工具。更多帮助请访问OpenClaw。
第一招：善用openclaw doctor
OpenClaw提供了一个强大的自诊断命令，它会自动检查运行环境、配置文件、网络连接等各项状态：
openclaw doctor
该命令会输出一份详细的诊断报告，包括：
- Node.js版本是否满足要求
- 配置文件是否存在且格式正确
- 网关服务是否在运行
- 各个AI提供商的连接状态
- 已配置频道的连接状态
大多数问题都可以通过 openclaw doctor 的输出快速定位原因。建议每次遇到问题时都先运行一次。
Node.js版本不满足要求
错误表现：
Error: OpenClaw requires Node.js >= 22.0.0, current version: 18.x.x
或安装时出现语法错误、模块找不到等异常。
解决方法：
OpenClaw要求Node.js 22或更高版本。检查当前版本：
node --version
如果版本低于22，需要升级：
# 使用NodeSource仓库（Ubuntu/Debian）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# 或使用nvm
nvm install 22
nvm use 22
nvm alias default 22
升级后重新安装OpenClaw：
npm install -g openclaw@latest
网关Token缺失或无效
错误表现：
Error: Gateway token is missing or invalid
或Dashboard显示"Unauthorized"。
解决方法：
网关Token在初次运行 openclaw onboard 时自动生成，保存在配置文件中。检查配置文件：
cat ~/.config/openclaw/openclaw.json5
确认 gateway 部分包含有效的 token 字段。如果Token丢失或损坏，可以重新生成：
openclaw gateway reset-token
然后重启网关：
openclaw gateway restart
如果你使用systemd管理服务：
sudo systemctl restart openclaw
端口18789被占用
错误表现：
Error: listen EADDRINUSE: address already in use :::18789
解决方法：
首先查看是什么进程占用了该端口：
# Linux
sudo lsof -i :18789
# 或
sudo ss -tlnp | grep 18789
可能的情况：
- 已有OpenClaw实例在运行： 先停止旧实例
openclaw gateway stop
# 或强制终止
kill $(lsof -t -i:18789)
- 其他程序占用了端口： 修改OpenClaw的端口配置
nano ~/.config/openclaw/openclaw.json5
{
gateway: {
port: 18790, // 改用其他端口
}
}
修改端口后，如果你配置了Nginx反向代理，记得同步更新Nginx配置中的upstream地址。
API密钥错误
错误表现：
Error: 401 Unauthorized - Invalid API key
或AI模型无法响应消息。
解决方法：
逐项检查你的API密钥配置：
nano ~/.config/openclaw/openclaw.json5
Anthropic Claude：
- 密钥格式应为
sk-ant-api03-... - 在 console.anthropic.com 确认密钥未过期且有额度
OpenAI：
- 密钥格式应为
sk-proj-...或sk-... - 确认账户有可用额度
Ollama（本地模型）：
apiKey可以填任意非空字符串如"ollama"- 确保Ollama服务在运行：
curl http://localhost:11434/api/tags
常见错误是复制密钥时前后多了空格，或者在配置文件中缺少引号。
频道连接失败
Telegram连接失败：
Error: Telegram Bot API: 401 Unauthorized
解决方法：
- 确认Bot Token正确且未被撤销
- 通过BotFather检查机器人状态：发送
/mybots - 如果Token泄露，使用
/revoke重新生成
Discord连接失败：
Error: Discord Gateway: Authentication failed
解决方法：
- 检查Bot Token是否正确
- 在Discord Developer Portal确认Bot已启用Message Content Intent
- 确认Bot已被邀请到目标服务器
WhatsApp连接失败：
WhatsApp使用扫码认证，如果连接断开：
openclaw channel reconnect whatsapp
然后按照提示重新扫码。
配置文件格式错误
错误表现：
Error: Failed to parse config file
SyntaxError: Unexpected token ...
解决方法：
OpenClaw使用JSON5格式配置文件，它比标准JSON更宽松（支持注释和尾逗号），但仍有语法要求。常见错误包括：
- 缺少逗号分隔
- 字符串值未用引号包裹
- 大括号不匹配
你可以用以下方式验证配置：
openclaw doctor
诊断工具会指出配置文件中的具体错误位置。如果配置损坏严重，可以备份后重新初始化：
cp ~/.config/openclaw/openclaw.json5 ~/.config/openclaw/openclaw.json5.bak
openclaw onboard
内存不足导致崩溃
错误表现： 网关频繁重启，日志中出现 JavaScript heap out of memory。
解决方法：
增加Node.js的内存限制：
export NODE_OPTIONS="--max-old-space-size=4096"
如果你使用systemd管理服务，在service文件中添加环境变量：
Environment=NODE_OPTIONS=--max-old-space-size=4096
然后重新加载并重启：
sudo systemctl daemon-reload
sudo systemctl restart openclaw
如果问题持续，考虑升级服务器内存配置。
获取更多帮助
如果以上方案都无法解决你的问题，可以通过以下途径获取帮助：
- 查阅官方文档： OpenClaw官方文档包含最全面的配置参考
- 搜索GitHub Issue： 在OpenClaw GitHub仓库中搜索你遇到的错误信息，很可能已经有人遇到过相同问题
- 提交新Issue： 如果确认是Bug，提交Issue时请附上
openclaw doctor的完整输出和相关日志 - 查看日志： 详细日志可以帮助定位深层问题
# 查看网关实时日志
sudo journalctl -u openclaw -f
# 查看最近100行日志
sudo journalctl -u openclaw -n 100
保持OpenClaw更新到最新版本也很重要，许多Bug在新版本中已经修复：
npm update -g openclaw@latest