1. 安装失败: 无法连接到 GitHub

问题现象

npm error code ECONNREFUSED
npm error syscall connect
npm error errno ECONNREFUSED
npm error FetchError: request to https://codeload.github.com/... failed
npm error reason: connect ECONNREFUSED 127.0.0.1:443

原因分析

• 网络无法直接访问 GitHub
• proxy未配置或配置错误
• 防火墙拦截连接

解决步骤

步骤 1: 检查网络连接

# 测试是否能访问 GitHub
ping github.com

# 测试是否能访问 codeload.github.com
curl -I https://codeload.github.com

步骤 2: 确认proxy软件正在运行

• 打开您的proxy软件 (Cla, Sd 等)
• 确认proxy已开启
• 查看本地监听端口

步骤 3: 配置 npm proxy

# Cla 用户 (端口 7890)
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

# Sd 用户 (端口 1080)
npm config set proxy http://127.0.0.1:1080
npm config set https-proxy http://127.0.0.1:1080

步骤 4: 验证proxy配置

npm config get proxy
npm config get https-proxy

步骤 5: 清理 npm 缓存

npm cache clean --force

步骤 6: 重新安装

npm install -g openclaw

2. Node.js 版本不兼容

问题现象

error openclaw@2026.3.8: The engine "node" is incompatible with this module.
error Expected version ">=22.0.0".
error Got "20.19.0"

原因分析

• 当前 Node.js 版本低于 22.0.0
• OpenClaw 要求 Node.js >= 22.0.0

解决步骤

步骤 1: 检查当前版本

node -v

步骤 2: 使用 nvm 安装 Node.js 22

如果已安装 nvm:

# 安装 Node.js 22
nvm install 22

# 切换到 Node.js 22
nvm use 22

# 验证版本
node -v

如果未安装 nvm:

Windows:

# 使用 winget 安装
winget install OpenJS.NodeJS.22

# 或下载 nvm-windows
# https://github.com/coreybutler/nvm-windows/releases

macOS/Linux:

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js 22
nvm install 22
nvm use 22

步骤 3: 重新安装 OpenClaw

npm install -g openclaw

3. 找不到 openclaw 命令

问题现象

openclaw --version
# 输出: 'openclaw' 不是内部或外部命令,也不是可运行的程序或批处理文件。
# 或: command not found: openclaw

原因分析

• npm 全局路径未添加到 PATH 环境变量
• Node.js 安装路径问题
• 使用了不同的 Node.js 版本管理器

解决步骤

步骤 1: 检查 npm 全局路径

npm config get prefix

输出示例:

C:\Users\<用户名>\AppData\Local\nvm\v22.22.1
# 或
C:\Program Files\nodejs

步骤 2: 检查 openclaw 是否已安装

# Windows
dir "C:\Users\<用户名>\AppData\Local\nvm\v22.22.1\node_modules\openclaw"

# macOS/Linux
ls -la /usr/local/lib/node_modules/openclaw
# 或
ls -la ~/.nvm/versions/node/v22.22.1/lib/node_modules/openclaw

步骤 3: 添加到 PATH 环境变量 (Windows)

方法一: 通过系统设置

1. 右键"此电脑" -> “属性”
2. 点击"高级系统设置"
3. 点击"环境变量"
4. 在"系统变量"或"用户变量"中找到 Path
5. 点击"编辑"
6. 点击"新建"
7. 添加 npm 全局路径 (如 C:\Users\<用户名>\AppData\Local\nvm\v22.22.1)
8. 点击"确定"保存

方法二: 通过 PowerShell (临时)

$env:Path += ";C:\Users\<用户名>\AppData\Local\nvm\v22.22.1"

方法三: 通过 PowerShell (永久)

# 添加到用户环境变量
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\<用户名>\AppData\Local\nvm\v22.22.1", "User")

步骤 4: 添加到 PATH (macOS/Linux)

编辑 ~/.bashrc 或 ~/.zshrc:

# 打开配置文件
nano ~/.bashrc  # 或 nano ~/.zshrc

# 添加以下行 (根据实际路径调整)
export PATH="$(npm config get prefix)/bin:$PATH"

# 保存并退出 (Ctrl+O, Enter, Ctrl+X)

# 重新加载配置
source ~/.bashrc  # 或 source ~/.zshrc

步骤 5: 验证

# 关闭并重新打开终端
openclaw --version

步骤 6: 使用完整路径 (临时方案)

# Windows
C:\Users\<用户名>\AppData\Local\nvm\v22.22.1\openclaw.cmd --version

# macOS/Linux
/usr/local/bin/openclaw --version
# 或
~/.nvm/versions/node/v22.22.1/bin/openclaw --version

4. 配置文件损坏

问题现象

• OpenClaw 启动失败
• 配置文件格式错误
• JSON 解析错误

原因分析

• 手动编辑时 JSON 格式错误
• 文件编码问题
• 意外中断导致文件损坏

解决步骤

步骤 1: 备份当前配置

# Windows
copy C:\Users\$env:USERNAME\.openclaw\openclaw.json C:\Users\$env:USERNAME\.openclaw\openclaw.json.backup

# macOS/Linux
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

步骤 2: 检查 JSON 格式

使用在线 JSON 验证工具:

• https://jsonlint.com/
• https://jsonformatter.curiousconcept.com/

复制配置文件内容,粘贴到验证工具,检查格式错误。

步骤 3: 修复或重新生成配置

方法一: 手动修复

根据验证工具的提示,修复 JSON 格式错误。

方法二: 重新生成配置

# 删除配置文件
rm ~/.openclaw/openclaw.json

# 重新启动 OpenClaw (会自动生成默认配置)
openclaw gateway

# 停止服务 (Ctrl+C)
# 然后重新配置 API Key

步骤 4: 恢复配置

重新按照 OpenClaw（二）：配置教程 配置 API Key。

5. 端口被占用

问题现象

Error: listen EADDRINUSE: address already in use 127.0.0.1:18789

=

原因分析

• OpenClaw 已在运行
• 其他程序占用了 18789 端口

解决步骤

步骤 1: 检查端口占用

Windows:

netstat -ano | findstr 18789

输出示例:

TCP    127.0.0.1:18789    0.0.0.0:0    LISTENING    12345

macOS/Linux:

lsof -i :18789

输出示例:

COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
node    12345 user   22u  IPv6  12345      0t0  TCP *:18789 (LISTEN)

步骤 2: 结束占用端口的进程

如果是 OpenClaw 进程:

# Windows
taskkill /F /PID 12345

# macOS/Linux
kill 12345

如果是其他程序:

• 确认是否可以安全结束该程序
• 或者修改 OpenClaw 端口

步骤 3: 修改 OpenClaw 端口 (可选)

如果不想结束占用端口的程序,可以修改 OpenClaw 端口:

openclaw config set gateway.port 18790

然后重新启动 OpenClaw,访问地址变为:

http://127.0.0.1:18790/#token=<您的token>

步骤 4: 验证端口已释放

# Windows
netstat -ano | findstr 18789

# macOS/Linux
lsof -i :18789

# 应该没有输出

6. API Key 无效

问题现象

• OpenClaw 启动成功,但无法使用模型
• 提示认证失败
• API 调用返回 401 或 403 错误

原因分析

• API Key 错误或过期
• API Key 权限不足
• baseUrl 配置错误
• 模型 ID 错误

解决步骤

步骤 1: 检查 API Key 是否正确

华为云:

1. 访问: https://developer.huaweicloud.com/space/developerspace/tokens.html
2. 确认 API Key 是否正确
3. 检查 API Key 是否有权限访问指定模型

Doubao:

1. 访问火山引擎控制台
2. 确认 API Key 和 Endpoint ID 是否正确
3. 检查 Endpoint 是否已启用

Anthropic:

1. 访问: https://console.anthropic.com/
2. 确认 API Key 是否正确
3. 检查账户是否有余额

步骤 2: 检查配置文件

打开配置文件,确认:

• apiKey 是否正确 (没有多余空格或换行)
• baseUrl 是否正确
• models[0].id 是否正确

步骤 3: 测试 API 连接

华为云:

curl -X POST https://api.modelarts-maas.com/openai/v1/chat/completions \
  -H "Authorization: Bearer 您的API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

步骤 4: 查看日志

查看 OpenClaw 日志文件,查找详细错误信息:

# Windows
type C:\Users\$env:USERNAME\AppData\Local\Temp\openclaw\openclaw-*.log | findstr "error"

# macOS/Linux
cat /tmp/openclaw/openclaw-*.log | grep -i error

步骤 5: 重新配置 API Key

如果确认 API Key 正确但仍然失败,尝试重新配置:

# 删除旧配置
openclaw config set models.providers.huawei.apiKey "新的API Key"

# 或直接编辑配置文件