OpenClaw 核心排障指南：常见错误诊断与完整解决方案

太长不看 (TL;DR)：OpenClaw 的常见故障主要集中在连接中断、认证失败、路由错误和性能问题上。绝大多数问题源于网络不稳定、API 密钥错误或频道配置不当。本文提供了一份详尽的排障指南，针对最常见的 OpenClaw 错误提供了逐步解决的方案。

1. 安装与配置问题

Node.js 版本不匹配

问题：提示 openclaw command not found 或报错 unsupported Node version。
原因：OpenClaw 需要 Node.js 22 或更高版本。
修复方法：

# 检查 Node 版本
node --version

# 如果低于 22，请使用 nvm 升级到最新的长期支持版本 (LTS)：
nvm install --lts
nvm use --lts

# 重新安装 OpenClaw：
npm install -g openclaw@latest
openclaw --version

安装时提示权限被拒绝 (Permission denied)

问题：运行 npm install -g openclaw 时出现 EACCES 或权限错误。
原因：npm 试图在没有足够权限的情况下写入系统目录。
修复方法：不要使用 sudo。配置 npm 使用用户目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

然后将路径添加到你的 shell 配置文件（~/.zshrc 或 ~/.bashrc）：

export PATH=~/.npm-global/bin:$PATH
source ~/.zshrc
npm install -g openclaw@latest

找不到配置文件

问题：安装后 OpenClaw 找不到 ~/.openclaw/config.json。
原因：初始化向导未运行或静默失败。
修复方法：手动运行向导：openclaw onboard。如果失败，手动创建最简配置：

mkdir -p ~/.openclaw
cat > ~/.openclaw/config.json << 'EOF'
{
  "version": "1.0.0",
  "providers": {},
  "agents": {},
  "channels": {},
  "routing": []
}
EOF
openclaw onboard

2. 频道连接故障

WhatsApp 二维码无法扫描

问题：二维码已显示，但手机提示“无效的二维码”或无反应。
原因：二维码已过期（只有 30 秒有效期）或网络隔离。
修复方法：确保手机和电脑在同一个网络。重新生成二维码：

openclaw channels logout whatsapp
openclaw channels login whatsapp

如果仍失败，检查防火墙是否放行了 18789 端口。

WhatsApp 几小时后自动断开

问题：初始连接正常，但 2-4 小时后断开连接。
原因：WhatsApp 协议需要定期心跳。网络切换或电脑休眠会打断连接。
修复方法：开启自动重连（每 5 分钟检查一次）：

openclaw channels config whatsapp --auto-reconnect true --reconnect-interval 300

如果你在使用笔记本，请防止运行期间休眠（macOS: caffeinate -i openclaw gateway）。建议在服务器上运行生产环境。

Telegram 机器人不接收消息

问题：Bot 显示在线，但对消息无响应。
原因：缺乏权限或 Token 无效。
修复方法：测试 Token 是否有效（curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe）。如果报错，去 @BotFather 重新生成 Token 并更新：

openclaw channels update telegram --token NEW_TOKEN

如果是群聊，需将 Bot 设为管理员并开启“读取消息”权限。

Discord 机器人显示离线

问题：在 Discord 服务器里机器人始终是灰色离线状态。
原因：开发者后台未开启 “Message Content Intent” 特权。
修复方法：去 Discord Developer Portal -> Bot 选项卡 -> 开启 Message Content Intent，保存后重启网关：

openclaw gateway restart

3. 认证与 API 错误

API 密钥无效

问题：日志显示 Authentication failed 或 Invalid API key。
修复方法：在终端里用原生 curl 测试你的 OpenAI 或 Anthropic API Key。确认无效后，在后台生成新 Key 并更新：

openclaw config set --provider anthropic --api-key NEW_KEY
openclaw gateway restart

触发速率限制 (Rate limit exceeded)

原因：发送给大模型提供商的请求过于频繁。
修复方法：开启内置限流与队列机制：

# 限制每小时 50 次请求
openclaw limits set --max-requests 50 --window 3600

# 开启请求队列（缓冲突发流量）
openclaw config set --enable-queue true --queue-max-size 100

模型未找到 / 余额不足

修复模型未找到：确保你配置的模型名称正确，并且你的账号拥有该模型的权限。更新 Agent 模型配置：

openclaw agents update default --model claude-sonnet-4-6

修复余额不足：去服务商后台充值。充值期间可以临时将路由切换到本地免费模型：

openclaw agents add fallback --provider ollama --model llama3
openclaw routing add --fallback fallback

4. 消息路由故障

消息发送给了错误的 Agent

问题：配置了路由规则，但消息还是去了默认 Agent。
原因：路由规则冲突，或者优先级 (priority) 设置不当。优先级越高的规则越先匹配。
修复方法：列出规则 openclaw routing list，删除冲突项，并重新设置正确的优先级（数字越大优先级越高）。使用以下命令测试路由而不实际发送消息：

openclaw routing test --channel whatsapp --sender +1234567890 --message "test"

自定义路由函数报错

原因：JavaScript 语法错误，或使用了不支持的异步函数。
修复方法：路由函数必须是同步 (synchronous) 的。禁止使用 async/await。始终返回 Agent 的名称（字符串）。测试你的脚本：

openclaw routing test-custom ~/.openclaw/routing.js --message "test"

5. 性能与内存问题

内存占用过高 (2GB+)

原因：OpenClaw 将会话历史保存在内存中以实现快速访问。会话数据随时间堆积。
修复方法：缩短会话超时时间，并开启自动清理：

# 将会话超时改为 30 分钟（默认 1 小时）
openclaw config set --session-timeout 1800

# 开启每小时自动清理
openclaw config set --auto-cleanup true --cleanup-interval 3600

# 手动清理 7 天前的旧数据
openclaw sessions clear --older-than 7d

响应缓慢或网关无响应

修复响应慢：检查队列积压情况 openclaw queue status。如果积压严重，增加并发数：

openclaw config set --max-concurrent-requests 10

修复假死：开启健康检查，让网关在无响应时自动重启：

openclaw config set --health-check-interval 60

6. 网关崩溃与数据丢失

启动时立即崩溃：通常是配置文件损坏或依赖丢失。尝试使用 openclaw gateway --debug 启动以查看详细报错，或重置配置 openclaw config reset。
运行期间崩溃：开启崩溃转储以捕获错误：openclaw config set --enable-crash-dumps true。在生产环境中，务必使用 pm2 或 systemd 来守护进程。
重启后会话丢失：默认状态下会话在内存中。开启磁盘持久化：

openclaw config set --persist-sessions true --session-file ~/.openclaw/sessions.db

7. 必备的调试工具与指令

当你遇到任何未知的疑难杂症时，以下指令是你的救命稻草：

开启 Debug 级别日志：

openclaw config set --log-level debug
openclaw gateway restart
tail -f ~/.openclaw/gateway.log

检查网关当前状态与内存用量：

openclaw gateway inspect

导出完整的诊断报告（脱敏版，用于提交 Issue）：

openclaw diagnostics export > openclaw-diagnostics.json

测试与 AI 厂商的网络连通性：

openclaw network test anthropic

**结语：**绝大多数 OpenClaw 的问题都可以通过查看 ~/.openclaw/gateway.log 并在节点层级进行组件测试来解决。如果你的应用已经走向生产环境，请务必将其部署在服务器上，使用进程守护工具（如 pm2），并配置好会话持久化与限流策略。