第3章 常见问题 60 秒自救 - 新手最容易踩的 8 个坑
第3章 常见问题 60 秒自救
新手在使用 OpenClaw 时最容易遇到的 8 个问题及快速解决方案。
🎯 本章目标
-
快速诊断和解决常见问题
-
了解问题的根本原因
-
掌握自助排查的方法
-
知道何时寻求帮助
坑位 1：Node.js 版本不对
症状
Error: The engine "node" is incompatible with this module原因
OpenClaw 要求 Node.js >= 22，但你的版本过低。
60 秒解决方案
# 检查当前版本
node -v
# 使用 nvm 升级
nvm install 22
nvm use 22
nvm alias default 22
# 验证
node -v # 应该显示 v22.x.x根本原因
OpenClaw 使用了 Node.js 22+ 的新特性（如原生 TypeScript 支持）。
坑位 2：网络代理问题
症状
Error: connect ETIMEDOUT
Error: getaddrinfo ENOTFOUND api.openai.com原因
无法访问大模型 API（通常是 OpenAI、Claude 等国外服务）。
60 秒解决方案
方案 A：配置系统代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
openclaw agent --message "测试"方案 B：使用国内模型
openclaw config set model.provider alibaba
openclaw config set model.apiKey YOUR_QWEN_KEY方案 C：配置 OpenClaw 代理
openclaw config set network.proxy http://127.0.0.1:7890坑位 3：API Key 配置错误
症状
Error: Invalid API key provided
Error: Incorrect API key provided原因
-
API Key 输入错误
-
API Key 已过期
-
API Key 没有权限
60 秒解决方案
# 重新设置 API Key
openclaw config set model.apiKey sk-proj-YOUR_ACTUAL_KEY
# 验证配置
openclaw config get model.apiKey
# 测试连接
openclaw doctor检查清单
-
✅ API Key 是否完整复制（没有多余空格）
-
✅ API Key 是否在有效期内
-
✅ API Key 是否有足够的配额
-
✅ API Key 是否有正确的权限
坑位 4：权限问题
症状
Error: EACCES: permission denied
Error: Cannot write to /usr/local/lib/node_modules原因
没有权限写入全局 npm 目录。
60 秒解决方案
推荐方案：修改 npm 全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# 重新安装
npm install -g openclaw@latest临时方案：使用 sudo（不推荐）
sudo npm install -g openclaw@latest坑位 5：端口冲突
症状
Error: listen EADDRINUSE: address already in use :::3000原因
默认端口被其他程序占用。
60 秒解决方案
方案 A：更改端口
openclaw config set server.port 3001方案 B：找到并关闭占用端口的程序
# macOS/Linux
lsof -i :3000
kill -9 <PID>
# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F坑位 6：配置文件损坏
症状
Error: Invalid configuration file
SyntaxError: Unexpected token原因
配置文件格式错误或损坏。
60 秒解决方案
# 备份当前配置
cp ~/.openclaw/config.json ~/.openclaw/config.json.bak
# 重置配置
openclaw config reset
# 重新初始化
openclaw onboard坑位 7：模型不可用
症状
Error: Model 'gpt-4' not found
Error: You don't have access to this model原因
-
模型名称错误
-
API Key 没有该模型的访问权限
-
模型已被弃用
60 秒解决方案
# 查看可用模型
openclaw models list
# 切换到可用模型
openclaw config set model.name gpt-4o-mini
# 或使用其他提供商
openclaw config set model.provider anthropic
openclaw config set model.name claude-3-5-sonnet-20241022坑位 8：Skill 安装失败
症状
Error: Failed to install skill 'web_search'
Error: Skill not found原因
-
网络问题
-
Skill 名称错误
-
依赖冲突
60 秒解决方案
# 清理缓存
openclaw skills cache clear
# 重新安装
openclaw skills install web_search
# 查看详细错误
openclaw skills install web_search --verbose
# 手动安装依赖
cd ~/.openclaw/workspace/skills
npm install快速诊断工具
使用 doctor 命令
openclaw doctor这个命令会自动检查：
-
✅ Node.js 版本
-
✅ OpenClaw 版本
-
✅ 配置文件
-
✅ 模型连接
-
✅ Skills 状态
-
✅ 沙箱环境
查看详细日志
# 启用调试模式
openclaw config set log.level debug
# 查看日志
tail -f ~/.openclaw/logs/openclaw.log获取帮助的正确姿势
1. 查看官方文档
-
本教程：返回目录
2. 搜索已知问题
-
GitHub Issues：https://github.com/openclaw/openclaw/issues
3. 提问前的准备
收集以下信息：
# 系统信息
uname -a
node -v
npm -v
# OpenClaw 信息
openclaw --version
openclaw doctor
# 错误日志
tail -n 50 ~/.openclaw/logs/openclaw.log4. 提交 Issue
在 GitHub 上提交 Issue 时，请包含：
-
问题描述
-
复现步骤
-
预期行为
-
实际行为
-
系统信息
-
错误日志
预防性检查清单
每周检查
-
[ ] 检查 OpenClaw 更新：
npm update -g openclaw -
[ ] 检查 API 配额使用情况
-
[ ] 清理日志文件：
openclaw logs clean -
[ ] 备份配置：
cp ~/.openclaw/config.json ~/backup/
每月检查
-
[ ] 更新 Skills：
openclaw skills update --all -
[ ] 检查安全更新
-
[ ] 审查 API Key 权限
-
[ ] 清理向量数据库
下一步
📚 本章小结
✅ 了解了 8 个最常见的问题
✅ 掌握了 60 秒快速解决方案
✅ 学会了使用 openclaw doctor 诊断
✅ 知道了如何获取帮助
记住：遇到问题不要慌，先运行 openclaw doctor！