OpenClaw 常见错误及解决方案

用户02074220175
2 阅读1分钟

踩坑记录，避免重复

安装类错误

错误 1：安装失败

错误信息：

Error: EACCES: permission denied

原因：权限不足

解决：

# 方案 1：使用 sudo
sudo npm install -g openclaw

# 方案 2：修改 npm 目录权限
sudo chown -R $(whoami) ~/.npm

错误 2：依赖缺失

错误信息：

Error: Cannot find module 'xxx'

原因：Node.js 版本不对或依赖未安装

解决：

# 检查 Node.js 版本
node --version  # 需要 18+

# 升级 Node.js
nvm install 18
nvm use 18

# 重装依赖
rm -rf node_modules
npm install

错误 3：端口被占用

错误信息：

Error: listen EADDRINUSE: address already in use :::3000

原因：3000 端口已被占用

解决：

# 查看占用
lsof -i :3000

# 杀掉进程
kill -9 <PID>

# 或换端口
openclaw start --port 3001

配置类错误

错误 4：配置文件格式错误

错误信息：

Error: YAML parsing error

原因：YAML 格式错误

解决：

# 检查配置
openclaw config check

# 常见错误：
# 1. 缩进不一致（必须用空格，不能用 Tab）
# 2. 冒号后没有空格
# 3. 引号未闭合

正确示例：

model:
  default: deepseek-chat  # ✅ 冒号后有空格
  providers:
    deepseek:
      api_key: xxx  # ✅ 缩进一致

错误 5：API Key 无效

错误信息：

Error: Invalid API key

原因：API Key 错误或过期

解决：

# 检查环境变量
echo $DEEPSEEK_API_KEY

# 重新设置
export DEEPSEEK_API_KEY="sk-xxx"

# 验证
openclaw test --model deepseek-chat

错误 6：环境变量未设置

错误信息：

Error: DEEPSEEK_API_KEY is not defined

原因：环境变量未设置

解决：

# 临时设置（当前会话）
export DEEPSEEK_API_KEY="sk-xxx"

# 永久设置（添加到 ~/.zshrc 或 ~/.bashrc）
echo 'export DEEPSEEK_API_KEY="sk-xxx"' >> ~/.zshrc
source ~/.zshrc

运行时错误

错误 7：内存溢出

错误信息：

Error: JavaScript heap out of memory

原因：内存不足

解决：

# 增加内存限制
export NODE_OPTIONS="--max-old-space-size=4096"

# 或减少历史记录
# config.yaml
memory:
  max_turns: 20

错误 8：网络超时

错误信息：

Error: ETIMEDOUT

原因：网络问题或 API 响应慢

解决：

# 增加超时时间
network:
  timeout: 60000  # 60 秒

# 或使用代理
proxy:
  enabled: true
  url: http://127.0.0.1:7890

错误 9：数据库锁定

错误信息：

Error: SQLITE_BUSY: database is locked

原因：SQLite 并发限制

解决：

# 方案 1：减少并发
concurrency: 1

# 方案 2：升级到 PostgreSQL
database:
  type: postgresql
  host: localhost

渠道错误

错误 10：Telegram Bot 无响应

错误信息：

Error: 404 Not Found

原因：Bot Token 错误

解决：

# 重新获取 Token
# 1. 找 @BotFather
# 2. 发送 /newbot
# 3. 获取新 Token

# 更新配置
channels:
  - name: my-bot
    type: telegram
    token: "新Token"

错误 11：微信连接失败

错误信息：

Error: Connection failed

原因：网络或配置问题

解决：

# 检查网络
ping open.weixin.qq.com

# 检查配置
openclaw channel test wechat

# 使用代理
proxy:
  enabled: true

心跳错误

错误 12：心跳任务不执行

原因：任务配置错误或脚本问题

解决：

# 测试任务
openclaw heartbeat test --task my-task

# 查看日志
openclaw logs --heartbeat

# 检查脚本权限
chmod +x ~/.openclaw/scripts/my-script.sh

错误 13：心跳卡死

原因：脚本死循环或超时

解决：

heartbeat:
  tasks:
    - name: my-task
      timeout: 30s  # 设置超时
      retry: 0      # 不重试

性能问题

问题 1：响应很慢

可能原因：

  1. 网络延迟
  2. 模型响应慢
  3. 历史记录太长

解决：

# 1. 换更快的模型
model:
  default: deepseek-chat

# 2. 减少历史
memory:
  max_turns: 20

# 3. 启用缓存
cache:
  enabled: true

问题 2：CPU 占用高

可能原因：

  1. 并发任务太多
  2. 计算密集型任务

解决：

# 限制并发
concurrency: 3

# 限制心跳频率
heartbeat:
  interval: 10m

问题 3：内存占用高

可能原因：

  1. 历史记录太多
  2. 缓存未清理

解决：

# 限制历史
memory:
  max_turns: 20

# 定期清理
heartbeat:
  tasks:
    - name: cleanup
      schedule: "0 0 * * *"
      action: |
        rm -rf ~/.openclaw/cache/*

快速诊断

# 一键诊断
openclaw doctor

# 输出示例
✅ Node.js: v18.17.0
✅ 配置文件: 正常
✅ API 连接: 正常
✅ 数据库: 正常
❌ 内存: 偏高（建议重启）

获取帮助

  1. 查看日志：openclaw logs --tail 100
  2. 检查配置：openclaw config check
  3. 搜索错误：Google + 错误信息
  4. 提交 Issue：github.com/openclaw/op…
  5. 加入社区：discord.com/invite/claw…
  6. 中文支持：微信 yang1002378395

💬 你遇到过什么错误？评论区分享！

🎯 需要问题排查服务？微信：yang1002378395

avatar
文章
阅读
粉丝