故障排除

遇到问题别慌。这里收集了最常见的问题和解决方案。大多数问题都能在几分钟内解决。

安装问题

安装脚本报错 "command not found: node"

原因：Node.js 没安装或没加入 PATH。

解决：

# 手动安装 Node.js（通过 nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc  # 或 source ~/.zshrc
nvm install --lts
node --version  # 确认安装成功

npm install 报错 "EACCES: permission denied"

原因：全局 npm 目录权限问题。

解决：

# 方法一：用 nvm（推荐，避免权限问题）
nvm install --lts
npm install -g openclaw@latest

# 方法二：修复 npm 权限
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

macOS 提示 "无法验证开发者"

解决：系统设置 → 隐私与安全性 → 点击"仍要打开"。或在终端运行：

xattr -d com.apple.quarantine $(which openclaw)

Gateway 问题

Gateway 无法启动

诊断步骤：

# 1. 查看详细错误
openclaw gateway start --verbose

# 2. 检查端口是否被占用
lsof -i :3000  # 默认端口

# 3. 检查配置文件是否有语法错误
openclaw doctor

# 4. 重置配置（最后手段）
openclaw reset

Gateway 频繁崩溃

可能原因：

• 内存不足 — 检查 free -h（Linux）或活动监视器（macOS）
• Node.js 版本过低 — 需要 22+，运行 node --version 确认
• 配置文件错误 — 运行 openclaw doctor 检查

AI 不回复

这是最常见的问题。按以下顺序排查：

1. 确认 Gateway 在运行

openclaw status
# 看 Gateway 状态是否为 "running"

2. 检查日志看错误信息

openclaw logs
# 找红色的 ERROR 行

3. 检查 allowFrom 白名单

如果配置了 allowFrom，确保你的用户 ID 在列表里。不在白名单里的消息会被静默忽略。

4. 检查 AI 模型 API

# 测试 API 是否可用
openclaw doctor
# 看 "Model connectivity" 那一项

5. 确认消息到达了 Gateway

如果日志里完全没有收到消息的记录，说明聊天平台的连接有问题。检查 Bot Token 是否正确，Bot 是否在线。

模型相关

报错 "Invalid API Key"

解决：确认 API Key 正确且未过期。去对应平台的控制台重新生成一个。

报错 "Rate limit exceeded" / "429"

原因：API 调用频率超限。

解决：

• 等几分钟再试
• 配置故障转移模型（主模型限额时自动切备用）
• 升级 API 套餐以提高限额

报错 "Insufficient quota" / "402"

原因：API 余额不足。

解决：去模型平台充值。Anthropic → console.anthropic.com，OpenAI → platform.openai.com。

回复很慢

可能原因：

• 使用了大模型（如 Opus），换 Sonnet 或 Haiku 会快很多
• 网络问题（国内访问海外 API 可能需要代理）
• 模型服务器繁忙，换个时间或换模型

平台连接问题

Discord Bot 离线 / 不响应

• 确认 Bot Token 正确
• 确认 Message Content Intent 已打开（Developer Portal → Bot 页面）
• 确认 Bot 已邀请到正确的服务器，且有读取/发送消息权限
• 重启 Gateway：openclaw gateway restart

Telegram Bot 不回复

• 确认 Bot Token 正确（找 @BotFather 用 /token 查看）
• 确认没有其他程序在使用这个 Bot Token（同一个 Token 不能被两个程序同时使用）
• 私聊 Bot，发 /start 试试

WhatsApp 断连

• 重启 Gateway，终端会显示新二维码
• 手机 WhatsApp → 已关联设备 → 删除旧设备 → 重新扫码
• 确保运行 OpenClaw 的机器网络稳定

性能问题

内存占用越来越高

解决：

# 重启 Gateway 释放内存
openclaw gateway restart

# 如果频繁出现，检查是否有内存泄漏
openclaw logs | grep -i "memory\|heap"

对话越来越慢

原因：会话历史太长，每次对话都要把所有历史发给 AI。

解决：

# 压缩会话历史
# 在聊天中发送：
/compact

# 或完全重新开始：
/reset

还是解决不了？

如果上面的方法都试过了还是有问题：

1. 收集信息：运行 openclaw doctor，保存输出结果
2. 查看日志：运行 openclaw logs --tail 200，找到错误信息
3. 社区求助：
   • Discord 社区：discord.gg/clawd
   • GitHub Issues：github.com/openclaw/openclaw/issues