一、前置诊断：3 条万能命令，先定位问题根源
遇到异常优先执行以下指令，自动检测环境、服务、网络、配置，精准锁定故障点：
bash
运行
# 全方位体检（首选，检测版本、依赖、配置、网络并给出修复建议）
openclaw doctor
# 查看网关运行状态，判断服务是否正常启动
openclaw gateway status
# 服务健康自检
openclaw health
二、安装阶段故障排查
1. Node.js 版本不兼容
报错：Node.js version X.X.X is not supported、代码语法报错
原因：OpenClaw 要求 Node 22.14 及以上，推荐使用 Node 24 版本。
bash
运行
# 查看当前版本
node --version
# 推荐：用 nvm 管理多版本 Node（一键升级）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 24
nvm use 24
也可前往 Node.js 官网 下载最新 LTS 版本。
2. npm 全局安装权限报错（EACCES）
报错：EACCES: permission denied
原因：系统目录写入权限不足，禁止使用 sudo npm install -g，会遗留后续权限隐患。
方案一（推荐）：使用 nvm 管理 Node，自动规避权限问题
参考上方 Node.js 安装步骤即可。
方案二：自定义 npm 全局目录
bash
运行
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# 将路径写入环境变量（Linux/macOS）
echo 'export PATH="~/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Windows 需手动把 npm 全局目录 添加到系统环境变量。
3. 命令未找到：openclaw 无法识别
报错：command not found: openclaw、不是内部 / 外部命令
原因：npm 全局执行目录未加入系统 PATH。
bash
运行
# 查看 npm 全局 bin 路径
npm bin -g
# Linux/macOS 临时生效
export PATH="$(npm bin -g):$PATH"
# 永久写入配置文件
echo "export PATH=\"$(npm bin -g):\$PATH\"" >> ~/.bashrc
source ~/.bashrc
三、网络连接类故障
1. 连接被拒绝（ECONNREFUSED）
报错：connect ECONNREFUSED 127.0.0.1:18789
原因：本地网关未启动，或目标 API 服务离线。
bash
运行
# 检查网关状态
openclaw gateway status
# 启动网关
openclaw gateway start
# 测试外网API连通性
curl -v https://api.openai.com
2. 连接超时 / 下载缓慢（ETIMEDOUT）
报错：connect ETIMEDOUT、依赖下载卡住
原因：境外网络不稳定，切换国内镜像源提速。
bash
运行
# npm 切换淘宝镜像
npm config set registry shturl.cc/ZKgfMLIUZsjrGDZ02BNP
# ClawHub 切换国内镜像
clawhub config set registry https://cn.clawhub-mirror.com
3. SSL 证书验证失败
报错：UNABLE_TO_VERIFY_LEAF_SIGNATURE、SSL certificate problem
正式环境（推荐）：更新系统证书
bash
运行
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates
# macOS
brew install ca-certificates
临时调试（仅测试用，不建议线上使用）
bash
运行
export NODE_TLS_REJECT_UNAUTHORIZED=0
四、Gateway 网关核心故障
1. 端口冲突（EADDRINUSE）
报错：EADDRINUSE: address already in use :::18789
原因：默认端口 18789 被其他程序占用。
bash
运行
# Linux/macOS 查找占用进程
lsof -i :18789
# Windows 查找占用进程
netstat -ano | findstr 18789
# 结束占用进程后重启网关
openclaw gateway start
也可修改 ~/.openclaw/openclaw.json 手动更换网关端口。
2. 认证失败
报错：Authentication failed、Invalid token
原因：网关认证令牌配置错误、过期。
bash
运行
# 查看当前认证配置
openclaw configure
# 重新完成初始化认证
openclaw onboard
3. 地址绑定失败（EADDRNOTAVAIL）
报错：Cannot bind to address
原因：配置了无效 IP 地址，检查网关绑定配置：
json
{
"gateway": {
"host": "127.0.0.1", // 仅本地访问
"port": 18789
}
}
需要外网设备访问时，将 host 改为 0.0.0.0。
4. 进程残留，无法重复启动
现象：提示服务已运行，但实际无响应
bash
运行
# 强制停止网关
openclaw gateway stop --force
# 彻底清除残留进程（Linux/macOS）
pkill -f openclaw
# 重新启动
openclaw gateway start
五、多聊天渠道专项故障
1. WhatsApp 二维码过期 / 扫码失败
现象：二维码弹出后快速失效、扫码无反应
提示：二维码有效期约 60 秒，生成后立即扫码。
bash
运行
# 重新生成登录二维码
openclaw channels login whatsapp
反复过期请检查网络稳定性，WhatsApp 配对要求网络持续连通。
2. Telegram 机器人无响应
现象：发送消息，Bot 零回复
- 确认网关正常运行：
openclaw gateway status - 核对
openclaw.json内botToken是否填写正确 - 查看渠道整体状态：
openclaw channels status - 查看网关日志定位详细错误：
openclaw gateway logs
3. 渠道无故掉线、连接中断
bash
运行
# 查看全渠道在线状态
openclaw channels status
# 单独重连指定渠道
openclaw channels login 渠道名
# 全局重启网关，恢复所有渠道
openclaw gateway restart
六、技能 & 插件相关故障
1. 缺失依赖工具
报错：Missing required binary: xxx、requires_bins 校验失败
原因：技能依赖系统工具（curl、python、ffmpeg 等），本地未安装。
bash
运行
# Ubuntu/Debian 安装常用依赖
sudo apt install curl python3 ffmpeg
# macOS 安装常用依赖
brew install curl python ffmpeg
# 验证工具是否加入环境变量
which 工具名
2. 技能版本不兼容、功能异常
bash
运行
# 更新单个技能至最新版
clawhub update 技能名称
# 一键更新全部技能
clawhub update --all
# 回退/安装指定版本
clawhub install 技能名称@版本号
3. 缺失环境变量 / 密钥
报错：Missing required environment variable: XXX_API_KEY
原因：技能所需 API 密钥、配置项未填写。
- 查看技能文档，确认必填环境变量
- 临时设置（Linux/macOS）：
bash
运行
export XXX_API_KEY=你的密钥
- 永久配置：在
openclaw.json的secrets节点中添加密钥。
4. 插件安装后不生效
原因：插件需重启网关才能加载。
bash
运行
# 重启网关
openclaw gateway restart
# 查看已加载插件列表，确认是否生效
openclaw plugins list
七、其他杂项问题
1. 磁盘空间不足
bash
运行
# 卸载闲置技能释放空间
clawhub uninstall 无用技能名
# 清理 npm 缓存
npm cache clean --force
2. 微信 / QQ 频繁触发风控
现象：账号掉线、限制发言
优化方案：降低自动回复频率，控制单条消息长度，避免短时间批量群发消息。
八、终极求助渠道
若以上方案仍未解决问题，按顺序排查：
- 执行
openclaw doctor获取完整诊断报告； - 查看运行日志：
openclaw gateway logs； - 查阅官方文档：docs.openclaw.ai/zh-CN；
- 在龙虾技能库检索报错关键词与对应解决方案。