openclaw doctor是什么
openclaw doctor是OpenClaw内置的诊断工具，它会自动检查你的运行环境、配置文件和各项服务连接状态，帮助你快速定位和解决安装部署中的问题。无论你是刚完成安装还是运行中遇到故障，openclaw doctor都应该是你的第一个排查手段。
基本用法
在终端中运行：
openclaw doctor
命令会依次执行多项检查，并以清晰的格式输出结果。每一项检查会标记为通过、警告或失败状态。
检查项详解
openclaw doctor会检查以下关键项目，让我们逐一了解每项检查的含义和常见问题。
Node.js版本检查
OpenClaw要求Node.js 22或更高版本。doctor会检查当前Node.js版本是否满足要求。
常见问题：系统安装了多个Node.js版本，实际运行的版本低于22。
解决方法：
node --version
如果版本低于22，需要升级。推荐使用nvm管理Node.js版本：
nvm install 22
nvm use 22
nvm alias default 22
特别注意：不要使用Bun作为Node.js替代品。虽然Bun在某些场景下更快，但在处理WhatsApp和Telegram的WebSocket连接时存在已知兼容性问题，OpenClaw官方不建议使用。
配置文件检查
doctor会验证~/.openclaw/openclaw.json配置文件是否存在且格式正确。
常见问题：
- 配置文件不存在：通常是因为没有运行过初始化引导
- JSON格式错误：手动编辑时引入了语法错误
解决方法：
如果配置文件不存在，运行引导程序：
openclaw onboard --install-daemon
如果JSON格式错误，可以用以下命令验证：
python3 -m json.tool ~/.openclaw/openclaw.json
错误的JSON通常是因为缺少逗号、多余的逗号或引号不匹配。
网络连通性检查
doctor会测试与OpenClaw核心服务和各AI模型API的网络连接。
常见问题：
- 防火墙阻止出站连接
- 代理配置不正确
- DNS解析失败
解决方法：
检查基本网络连通性：
curl -I https://api.openai.com
curl -I https://api.anthropic.com
如果你在需要代理的网络环境中，确保设置了正确的代理环境变量：
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port
AI模型API检查
doctor会验证配置的AI模型API密钥是否有效，并测试API连接。
常见问题：
- API密钥已过期或无效
- API额度已耗尽
- 选择的模型不可用
解决方法：
打开配置文件检查API密钥：
cat ~/.openclaw/openclaw.json
确认密钥格式正确且未过期。你可以通过各AI提供商的控制台检查密钥状态和剩余额度。如需更新密钥，直接编辑配置文件或重新运行引导程序。
聊天平台连接检查
doctor会逐一检查已配置的聊天平台连接状态，包括WhatsApp、Telegram、Discord等。
常见问题：
- WhatsApp会话过期需要重新扫码
- Telegram Bot Token无效
- Discord Bot未被邀请到目标服务器
- Webhook URL不可达
解决方法：
对于WhatsApp连接问题：
openclaw onboard
重新进入引导程序，选择重新连接WhatsApp并按提示扫码。
对于Telegram问题，确认Bot Token有效：
curl https://api.telegram.org/bot你的TOKEN/getMe
对于Webhook URL问题，确保你的服务器可以从外部访问，且端口3000（或你配置的端口）未被防火墙阻止。
端口占用检查
doctor会检查OpenClaw需要使用的端口（默认3000）是否被其他程序占用。
常见问题：
- 另一个OpenClaw实例已在运行
- 其他Web应用占用了同一端口
解决方法：
查看端口占用情况：
# Linux
ss -tlnp | grep 3000
# macOS
lsof -i :3000
如果端口被占用，可以停止占用端口的进程，或者修改OpenClaw配置使用其他端口。
磁盘空间检查
doctor会检查~/.openclaw/所在分区是否有足够的磁盘空间。
常见问题：
- 日志文件积累过多
- 磁盘空间不足导致服务异常
解决方法：
df -h ~
du -sh ~/.openclaw/*
如果空间不足，清理不必要的日志文件：
rm -rf ~/.openclaw/logs/*.log.old
守护进程状态检查
doctor会检查OpenClaw的守护进程是否正确配置和运行。
常见问题：
- systemd服务未启用（Linux）
- LaunchAgent未加载（macOS）
- 服务已停止或处于失败状态
解决方法：
在Linux上：
systemctl status openclaw
sudo systemctl restart openclaw
在macOS上：
launchctl list | grep openclaw
launchctl start com.openclaw.agent
常见诊断场景
场景一：刚安装完成
安装后第一件事就是运行openclaw doctor，确认环境满足所有要求：
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw doctor
场景二：服务突然停止工作
当OpenClaw突然不响应消息时：
openclaw doctor
根据检查结果定位问题。通常是网络变化、API密钥过期或聊天平台会话超时导致的。
场景三：升级后出现问题
升级OpenClaw版本后运行doctor确认兼容性：
npm install -g openclaw@latest
openclaw doctor
场景四：迁移后验证
将OpenClaw从一台服务器迁移到另一台后：
openclaw doctor
确认配置文件正确恢复、所有连接在新环境中正常工作。
输出解读
doctor的输出使用颜色和符号标记每项检查的状态：
- 通过：该项检查完全正常，无需任何操作
- 警告：该项存在潜在问题但不影响基本运行，建议关注
- 失败：该项检查未通过，需要立即修复
对于失败的检查项，doctor通常会给出具体的错误信息和修复建议。按照建议逐一修复后，重新运行openclaw doctor直到所有检查通过。
获取更详细的诊断信息
如果标准诊断不够详细，可以查看OpenClaw的运行日志获取更多信息：
# Linux systemd
journalctl -u openclaw -n 100
# macOS LaunchAgent
cat /tmp/openclaw.stderr.log
# 或者查看OpenClaw自身日志
ls ~/.openclaw/logs/
寻求社区帮助
如果自行排查无法解决问题，可以将openclaw doctor的完整输出分享到OpenClaw的GitHub Issues或社区论坛中寻求帮助。诊断输出提供了足够的环境信息，社区成员可以据此快速帮你定位问题。
提交问题时建议包含：
openclaw doctor完整输出openclaw --version版本信息node --version版本信息- 操作系统类型和版本
- 问题的详细描述和复现步骤
总结
openclaw doctor是OpenClaw生态中最实用的诊断工具之一。养成在安装后、升级后、遇到问题时第一时间运行doctor的习惯，可以帮助你快速识别和解决绝大多数安装部署问题。它系统化地检查了从运行环境到服务连接的方方面面，是确保OpenClaw稳定运行的重要保障。