常见问题与故障排查 — 龙虾技能库

诊断命令速查

遇到问题时，先运行以下诊断命令收集信息： ``

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故障 #龙虾技能库