故障排查15 分钟阅读

OpenClaw 常见错误及解决方法

全面指南：诊断和修复 OpenClaw 常见错误，包括安装问题、API错误、通道问题和性能问题。

OpenClaw Guides

Tutorial Authors

2025-02-04

快速诊断

在深入具体错误之前，运行这些诊断命令：

bash

# 检查整体状态
openclaw status

# 验证配置
openclaw config validate

# 查看最近的错误日志
openclaw logs --tail 50 --level error

# 运行健康检查
openclaw doctor

安装错误

错误："Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

解决方法：

bash

# 使用 nvm（推荐）
nvm install 22
nvm use 22
nvm alias default 22

# 或使用 Homebrew（macOS）
brew install node@22

# 验证
node --version  # 应显示 v22.x.x

错误："EACCES permission denied"

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

解决方法： 不要使用 sudo。改为修复 npm 权限：

bash

# 选项1：使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 选项2：更改 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

错误："Cannot find module"

Error: Cannot find module '@openclaw/core'

解决方法：

bash

# 清除 npm 缓存并重新安装
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# 或使用安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

错误："gyp ERR! build error"（原生模块）

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

解决方法： 安装构建工具：

bash

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

API 和认证错误

错误："401 Unauthorized"

Error: API request failed with status 401: Invalid API key

解决方法：

bash

# 验证 API 密钥是否已设置
openclaw config get api-key

# 如果为空或错误，重新设置
openclaw config set api-key

# 检查密钥格式（Anthropic 密钥以 sk-ant- 开头）
# 确保没有多余的空格或引号

错误："429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

解决方法：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

对于持续的速率限制，考虑升级 API 等级或使用不同的模型：

bash

openclaw config set default-model claude-3-5-haiku

错误："402 Payment Required"

Error: API request failed: Insufficient credits

解决方法：

检查 API 提供商余额
为账户充值
或设置使用限制：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

错误："Connection Refused" to API

Error: connect ECONNREFUSED api.anthropic.com:443

解决方法：

bash

# 检查网络连接
ping api.anthropic.com

# 检查是否在代理后面
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 如需要配置代理
openclaw config set proxy http://your-proxy:8080

# 或检查防火墙/VPN设置

网关错误

错误："EADDRINUSE: Port already in use"

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

解决方法：

bash

# 查找使用该端口的进程
lsof -i :18789

# 终止进程
kill -9 <PID>

# 或使用不同端口
openclaw gateway start --port 18790

# 更新配置使用新端口
openclaw config set gateway-port 18790

错误："Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

解决方法：

bash

# 验证配置文件语法
openclaw config validate

# 如果损坏，重置为默认值
openclaw config reset --confirm

# 然后重新配置
openclaw onboard

错误："Gateway not responding"

bash

# 检查网关是否运行
openclaw status

# 如果停止，检查原因
openclaw logs --tail 100

# 尝试重启
openclaw gateway restart

# 如果仍然失败，检查系统资源
free -h  # 内存
df -h    # 磁盘空间

通道特定错误

WhatsApp："Session expired"

Error: WhatsApp session invalid or expired

解决方法：

bash

# 重新认证
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# 扫描新的二维码

WhatsApp："QR code not generating"

bash

# 检查是否有其他会话活动
pkill -f "openclaw.*whatsapp"

# 清除旧会话数据
rm -rf ~/.openclaw/whatsapp-session

# 重试
openclaw channel connect whatsapp

Telegram："Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

另一个实例正在使用相同的机器人令牌。

解决方法：

bash

# 停止所有 OpenClaw 实例
pkill -f openclaw

# 检查其他运行中的实例
ps aux | grep openclaw

# 重新启动
openclaw gateway start

Discord："Invalid token"

Error: An invalid token was provided

解决方法：

bash

# 在 Discord Developer Portal 重新生成令牌
# Bot → Reset Token

# 更新 OpenClaw
openclaw config set discord-token NEW_TOKEN
openclaw gateway restart

Discord："Missing intents"

Error: Disallowed intents specified

解决方法：

进入 Discord Developer Portal
选择您的应用 → Bot
在"Privileged Gateway Intents"下启用所需的 intents
保存并重启 OpenClaw

内存和性能错误

错误："JavaScript heap out of memory"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

解决方法：

bash

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

# 添加到 shell 配置文件以持久化
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# 重启 OpenClaw
openclaw gateway restart

错误："Too many open files"

Error: EMFILE: too many open files

解决方法：

bash

# 检查当前限制
ulimit -n

# 增加限制（临时）
ulimit -n 65535

# 增加限制（永久 - Linux）
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

响应时间慢

诊断：

bash

# 检查模型延迟
openclaw benchmark

# 检查系统资源
openclaw stats

解决方法：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

配置错误

错误："Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

解决方法：

bash

# 验证 YAML
openclaw config validate

# 常见问题：
# - 使用制表符而非空格（使用2个空格）
# - 键后缺少冒号
# - 未引用的特殊字符

# 修复或重置
openclaw config edit
# 或
openclaw config reset --confirm

错误："Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

解决方法：

bash

# 检查可用选项
openclaw config list

# 移除未知键
openclaw config edit

错误："Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

解决方法：

bash

# 添加到 .env 文件
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# 或在 shell 中导出
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# 添加到 shell 配置文件以持久化
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

数据库和存储错误

错误："Database locked"

Error: SQLITE_BUSY: database is locked

解决方法：

bash

# 停止 OpenClaw
openclaw gateway stop

# 检查锁文件
ls -la ~/.openclaw/*.lock

# 移除陈旧的锁
rm ~/.openclaw/*.lock

# 重启
openclaw gateway start

错误："Disk quota exceeded"

Error: ENOSPC: no space left on device

解决方法：

bash

# 检查磁盘使用
df -h

# 清除 OpenClaw 日志和缓存
openclaw cache clear
openclaw logs clear --older-than 7d

# 清除旧会话
rm -rf ~/.openclaw/sessions/*.old

获取更多帮助

启用调试日志

bash

# 设置调试模式
export OPENCLAW_DEBUG=true
openclaw gateway start

# 或在配置中设置
openclaw config set logLevel debug

生成诊断报告

bash

openclaw doctor --report > diagnostic-report.txt

社区支持

Discord: discord.gg/openclaw
GitHub Issues: github.com/openclaw/openclaw/issues
文档: docs.openclaw.ai

提交 Bug 报告

报告问题时，请包含：

bash

# 系统信息
openclaw --version
node --version
uname -a

# 配置（隐藏敏感数据）
openclaw config show --redact

# 最近的日志
openclaw logs --tail 100

快速诊断

安装错误

错误："Node.js version too old"

错误："EACCES permission denied"

错误："Cannot find module"

错误："gyp ERR! build error"（原生模块）

API 和认证错误

错误："401 Unauthorized"

错误："429 Rate Limited"

错误："402 Payment Required"

错误："Connection Refused" to API

网关错误

错误："EADDRINUSE: Port already in use"

错误："Gateway failed to start"

错误："Gateway not responding"

通道特定错误

WhatsApp："Session expired"

WhatsApp："QR code not generating"

Telegram："Conflict: terminated by other getUpdates"

Discord："Invalid token"

Discord："Missing intents"

内存和性能错误

错误："JavaScript heap out of memory"

错误："Too many open files"

响应时间慢

配置错误

错误："Invalid YAML syntax"

错误："Unknown configuration key"

错误："Environment variable not set"

数据库和存储错误

错误："Database locked"

错误："Disk quota exceeded"

获取更多帮助

启用调试日志

生成诊断报告

社区支持

提交 Bug 报告

后续步骤