## 诊断命令速查
遇到问题时，先运行以下诊断命令收集信息：
```bash
# 全面环境检查（推荐首先运行）
openclaw doctor
# 查看 Gateway 运行状态
openclaw gateway status
# 健康检查
openclaw health
```
`openclaw doctor` 会自动检测 Node.js 版本、依赖完整性、配置文件、网络连通性等，并给出修复建议。
## 安装问题
### Node.js 版本不满足要求
**错误信息**：`Node.js version X.X.X is not supported` 或安装时出现语法错误
**原因**：OpenClaw 要求 Node 22.14 或更高版本，推荐 Node 24。
**解决方案**：
```bash
# 检查当前版本
node --version
# 使用 nvm 升级（推荐）
nvm install 24
nvm use 24
# 或直接从官网下载最新 LTS 版本
# https://nodejs.org/
```
### npm 全局安装权限不足（EACCES）
**错误信息**：`EACCES: permission denied` 或 `Error: EACCES`
**原因**：npm 全局目录没有当前用户的写入权限。
**解决方案**：
```bash
# 方案一：使用 nvm 管理 Node.js（推荐，自动解决权限问题）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 24
# 方案二：修改 npm 全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# 将 ~/.npm-global/bin 添加到 PATH
```
> ⚠️ **不推荐**使用 `sudo npm install -g`，这会导致后续权限问题。
### PATH 配置问题
**错误信息**：`command not found: openclaw` 或 `openclaw 不是内部或外部命令`
**原因**：npm 全局 bin 目录不在系统 PATH 中。
**解决方案**：
```bash
# 查看 npm 全局 bin 目录
npm bin -g
# Linux/macOS：添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$(npm bin -g):$PATH"
# 重新加载配置
source ~/.bashrc
```
Windows 用户需要在"系统环境变量"中添加 npm 全局路径。
## 网络问题
### ECONNREFUSED 连接被拒绝
**错误信息**：`Error: connect ECONNREFUSED 127.0.0.1:18789`
**原因**：Gateway 未启动，或目标服务未运行。
**解决方案**：
```bash
# 检查 Gateway 是否在运行
openclaw gateway status
# 如果未运行，启动 Gateway
openclaw gateway start
# 如果是连接外部 API，检查网络连通性
curl -v https://api.openai.com
```
### ETIMEDOUT 连接超时
**错误信息**：`Error: connect ETIMEDOUT` 或下载速度极慢
**原因**：国内网络访问国外服务器不稳定。
**解决方案**：
```bash
# 配置 npm 淘宝镜像
npm config set registry https://registry.npmmirror.com
# 配置 ClawHub 镜像源
clawhub config set registry https://cn.clawhub-mirror.com
```
### 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
# 临时跳过验证（仅用于调试，不推荐生产环境）
export NODE_TLS_REJECT_UNAUTHORIZED=0
```
## Gateway 问题
### 端口冲突
**错误信息**：`EADDRINUSE: address already in use :::18789`
**原因**：端口 18789 已被其他进程占用。
**解决方案**：
```bash
# 查看占用端口的进程
# Linux/macOS
lsof -i :18789
# Windows
netstat -ano | findstr 18789
# 终止占用进程后重新启动
openclaw gateway start
# 或修改 Gateway 端口（在 openclaw.json 中配置）
```
### 认证失败
**错误信息**：`Authentication failed` 或 `Invalid token`
**原因**：Gateway 认证 token 配置错误或过期。
**解决方案**：
```bash
# 查看当前配置
openclaw configure
# 重新配置认证
openclaw onboard
```
### 绑定错误
**错误信息**：`EADDRNOTAVAIL` 或 `Cannot bind to address`
**原因**：配置的绑定地址不可用（如配置了不存在的 IP）。
**解决方案**：
在 `~/.openclaw/openclaw.json` 中检查 `gateway.host` 配置：
```json
{
"gateway": {
"host": "127.0.0.1",
"port": 18789
}
}
```
如果需要外部访问，改为 `"0.0.0.0"`；如果只需本地访问，使用 `"127.0.0.1"`。
## 渠道问题
### WhatsApp 二维码过期
**现象**：扫描二维码后提示过期或无法连接。
**解决方案**：
```bash
# 重新生成二维码
openclaw channels login whatsapp
# 如果反复过期，检查网络连接是否稳定
# WhatsApp 配对需要稳定的网络连接
```
> 💡 **提示**：二维码有效期约 60 秒，生成后请尽快扫描。
### Telegram Bot 无响应
**现象**：发送消息给 Bot 后没有回复。
**排查步骤**：
1. 确认 Gateway 正在运行：`openclaw gateway status`
2. 确认 Bot Token 配置正确：检查 `openclaw.json` 中的 `channels.telegram.token`
3. 确认已向 BotFather 注册 Bot 并获取 Token
4. 查看 Gateway 日志排查错误：`openclaw gateway logs`
```bash
# 检查渠道连接状态
openclaw channels status
```
### 渠道连接断开
**现象**：之前正常的渠道突然断开连接。
**解决方案**：
```bash
# 查看所有渠道状态
openclaw channels status
# 重新登录断开的渠道
openclaw channels login <渠道名>
# 重启 Gateway
openclaw gateway restart
```
## 技能和插件问题
### 依赖缺失
**错误信息**：`requires_bins` 中的工具未安装，或 `Missing required binary: xxx`
**原因**：技能依赖外部工具（如 curl、python、ffmpeg 等），但系统未安装。
**解决方案**：
1. 查看技能详情页的"运行时依赖"部分
2. 安装缺失的依赖工具：
```bash
# Ubuntu/Debian
sudo apt install curl python3 ffmpeg
# macOS
brew install curl python ffmpeg
```
3. 确保依赖工具在系统 PATH 中：`which <工具名>`
### 版本冲突
**错误信息**：技能版本不兼容或行为异常。
**解决方案**：
```bash
# 更新到最新版本
clawhub update <技能名称>
# 或更新全部技能
clawhub update --all
# 如果新版本有问题，可以安装指定版本
clawhub install <技能名称>@<版本号>
```
### 环境变量未设置
**错误信息**：`Missing required environment variable: XXX_API_KEY`
**原因**：技能需要 API Key 或其他环境变量才能工作。
**解决方案**：
```bash
# 查看技能需要的环境变量
# 在技能详情页的"环境变量"部分查看
# 设置环境变量
# Linux/macOS（添加到 ~/.bashrc 或 ~/.zshrc）
export XXX_API_KEY=your_api_key_here
# 或在 openclaw.json 中配置 secrets
```
### 插件安装后不生效
**原因**：插件安装后需要重启 Gateway 才能加载。
**解决方案**：
```bash
# 重启 Gateway
openclaw gateway restart
# 确认插件已加载
openclaw plugins list
```
## 其他常见问题
### 磁盘空间不足
**解决方案**：
```bash
# 清理不需要的技能
clawhub uninstall <不需要的技能>
# 清理 npm 缓存
npm cache clean --force
```
### 进程残留
**现象**：Gateway 无法启动，提示已有实例在运行。
**解决方案**：
```bash
# 强制停止所有 OpenClaw 进程
openclaw gateway stop --force
# 如果仍然无法停止
# Linux/macOS
pkill -f openclaw
# 然后重新启动
openclaw gateway start
```
## 获取更多帮助
如果以上方案无法解决你的问题：
1. 运行 `openclaw doctor` 获取完整的环境诊断报告
2. 查看 Gateway 日志：`openclaw gateway logs`
3. 访问 OpenClaw 官方文档：docs.openclaw.ai/zh-CN
4. 在龙虾技能库的教程区搜索相关关键词或错误信息
#OpenClaw常见错误 #安装问题 #网络错误 #Gateway故障 #龙虾技能库