故障排查

本页面按问题类型整理了 OpenClaw 常见故障的排查步骤和解决方案。

第一步：快速诊断

在深入排查之前，先运行自动诊断：

# 一键诊断所有常见问题
openclaw doctor

openclaw doctor 会自动检查以下项目并给出修复建议：

• ✅ Node.js 版本兼容性
• ✅ 端口可用性
• ✅ 配置文件完整性
• ✅ 模型连接状态
• ✅ 通道认证状态
• ✅ 磁盘空间
• ✅ 网络连通性

安装问题

Node.js 未找到或版本不兼容

# 检查 Node.js 是否安装
node --version

# 如未安装，使用 nvm 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20

Windows 用户

Windows 用户建议在 WSL2 中安装 Node.js，避免路径和权限问题。

npm 权限错误

# 错误：EACCES permission denied
# 解决方案 1：修复 npm 全局目录权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# 解决方案 2：使用 npx 直接运行（无需全局安装）
npx openclaw start

PATH 环境变量问题

安装后执行 openclaw 提示命令未找到：

Linux / macOS

# 将以下内容添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$HOME/.npm-global/bin:$PATH"

# 重新加载配置
source ~/.bashrc

Windows (PowerShell)

# 查看当前 PATH
$env:PATH

# 临时添加
$env:PATH += ";$env:APPDATA\npm"

网关（Gateway）启动失败

端口被占用

# 检查端口占用情况
lsof -i :7681   # Linux/macOS
netstat -ano | findstr 7681   # Windows

# 解决方案 1：终止占用进程
kill -9 <PID>

# 解决方案 2：更换端口
openclaw start --port 8080
# 或设置环境变量
export OPENCLAW_PORT=8080

配置文件错误

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

# 常见错误：YAML 缩进不正确、缺少必填字段
# 查看默认配置作为参考
openclaw config show --defaults

YAML 格式注意事项

• 使用空格缩进，不要使用 Tab（制表符）
• 冒号后必须有空格：key: value
• 字符串中包含特殊字符时需要用引号包裹

依赖缺失

# 重新安装依赖
cd ~/.openclaw && npm install

# 或重建 node_modules
rm -rf node_modules package-lock.json
npm install

Agent 无响应

API Key 无效

[ERROR] Model provider "openai" returned 401: Invalid API key

# 测试 API Key 是否有效
openclaw models test --provider deepseek

# 重新设置 API Key
openclaw config set models.deepseek.apiKey "sk-new-key-here"

速率限制（Rate Limiting）

[WARN] Model provider "openai" returned 429: Rate limit exceeded

解决方案：

1. 等待限制窗口重置（通常 1 分钟）
2. 配置请求重试（Retry）策略：

# config.yaml
models:
  retry:
    maxRetries: 3
    backoffMs: 1000

3. 配置模型备选方案（Failover）：

models:
  failover:
    - deepseek
    - qwen-max
    - glm-4

上下文溢出（Context Overflow）

# 查看当前会话的 Token 用量
openclaw sessions inspect --id <session-id>

# 清理历史会话释放资源
openclaw sessions prune --older-than 3d

通道连接问题

网络超时

# 检查通道网络连通性
openclaw channels status --probe

# 如使用海外通道，检查代理配置
curl -x http://127.0.0.1:7890 https://api.telegram.org/bot<TOKEN>/getMe

认证失败

各通道认证排查：

通道	常见原因	排查命令
企业微信	IP 白名单未配置	检查企业微信后台「安全设置」
钉钉	AppKey/AppSecret 错误	openclaw channels test --name dingtalk
飞书	事件订阅（Event Subscription）未开启	检查飞书开放平台应用设置
Telegram	Bot Token 过期	在 BotFather 重新生成 Token

性能问题

响应缓慢

# 性能分析
openclaw doctor --profile

# 检查各环节耗时
openclaw logs --follow --level debug --module performance

常见瓶颈及解决方案：

瓶颈	症状	解决方案
模型响应慢	首 Token 延迟 > 5s	换用更快的模型或更近的 API 端点
网络延迟高	请求耗时 > 3s	配置代理或使用国内模型
内存不足	OOM（Out of Memory）错误	增加服务器内存或限制并发
磁盘空间不足	写入失败	清理日志和历史数据

高内存占用

# 查看详细内存使用
openclaw status --memory

# 清理缓存和历史会话
openclaw sessions prune --older-than 7d
openclaw cache clear

磁盘空间不足

# 查看 OpenClaw 各组件占用空间
openclaw status --disk

# 清理旧日志
openclaw logs clean --older-than 30d

# 压缩数据库
openclaw db vacuum

恢复流程

使用 openclaw doctor 自动修复

# 自动检测并修复可修复的问题
openclaw doctor --fix

使用 openclaw reset 重置配置

# 重置为默认配置（保留数据）
openclaw reset --config

# 重置所有设置（保留数据）
openclaw reset --settings

谨慎使用

以下命令会清除数据，请确保已经备份。

备份与还原

# 备份当前数据
openclaw backup create --output ~/openclaw-backup.tar.gz

# 从备份还原
openclaw backup restore --input ~/openclaw-backup.tar.gz

完全重装（最终手段）

如果所有方法都无法解决问题：

# 1. 备份数据
openclaw backup create --output ~/openclaw-backup.tar.gz

# 2. 完全卸载
npm uninstall -g openclaw
rm -rf ~/.openclaw

# 3. 重新安装
npm install -g openclaw

# 4. 还原数据
openclaw backup restore --input ~/openclaw-backup.tar.gz

如果问题仍然存在

请将 openclaw doctor --export 的输出附上，前往 GitHub Issues 提交详细的问题报告，社区和维护者会尽快协助解决。