OpenClaw 故障排除：常见问题与解决方案

在使用 OpenClaw 的过程中，你可能会遇到各种问题。本文整理了最常见的故障场景及其解决方案，帮助你快速定位和解决问题。无论你是新手还是老用户，这份故障排除指南都将对你有所帮助。

快速诊断流程

遇到问题时，可以按照以下流程进行诊断：

问题出现
    │
    ├─ 检查服务是否运行
    │   └─ 查看进程状态
    │
    ├─ 查看错误日志
    │   └─ 分析错误信息
    │
    ├─ 检查配置是否正确
    │   └─ 验证配置文件
    │
    └─ 搜索解决方案
        └─ 社区/文档/搜索

服务相关问题

问题 1：服务无法启动

症状：

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

原因：端口 3000 被其他程序占用

解决方案：

# 1. 查找占用端口的进程
lsof -i :3000

# 2. 终止占用进程
kill -9 <PID>

# 3. 或者修改 OpenClaw 端口
# 在 config/app.yaml 中：
app:
  port: 3001

问题 2：服务启动后立即退出

症状：进程启动后马上退出

排查步骤：

# 1. 查看详细日志
npm run dev

# 2. 检查是否有错误输出
# 常见原因：
# - 配置文件格式错误
# - 缺少依赖
# - 环境变量未设置

常见原因与解决方案：

原因 解决方案
配置文件 YAML 语法错误 检查缩进和格式
缺少 .env 文件 复制 .env.example 为 .env
API Key 未设置 在 .env 中添加 OPENAI_API_KEY
Node.js 版本不对 确认使用 Node.js 18+

问题 3：服务运行缓慢

症状：响应时间很长

解决方案：

# config/app.yaml
app:
  # 检查是否开启了调试模式
  debug: false

# 优化 LLM 请求
llm:
  parameters:
    maxTokens: 1000  # 减少不必要的 tokens

LLM 相关问题

问题 1：API 调用失败

症状：

Error: OpenAI API error: Invalid API key

排查步骤：

# 1. 检查 API Key 是否正确
echo $OPENAI_API_KEY

# 2. 确认 API Key 有效
# 访问 https://platform.openai.com/account/api-keys

常见错误代码：

错误代码 说明 解决方案
401 API Key 无效 检查 Key 是否正确
403 无权限 确认 API Key 有权限
429 请求过多 等待或升级套餐
500 服务器错误 稍后重试

问题 2：LLM 返回空响应

症状：AI 不回复或返回空内容

解决方案：

# 增加 maxTokens
llm:
  parameters:
    maxTokens: 2000

# 检查 prompt
prompt:
  system: "你是一个有帮助的助手"

问题 3：响应质量差

症状：回复不符合预期

解决方案：

  1. 调整 temperature：
llm:
  parameters:
    temperature: 0.7  # 0-1，越高越有创意
  1. 优化 System Prompt：
prompt:
  system: |
    你是一个专业的技术顾问。
    回答要简洁、专业。
    使用中文回复。

平台集成问题

问题 1：Telegram Bot 不响应

排查流程：

# 1. 检查 Bot Token
curl https://api.telegram.org/bot<TOKEN>/getMe

# 2. 检查配置
# config/app.yaml 中：
telegram:
  enabled: true
  botToken: "${TELEGRAM_BOT_TOKEN}"

常见原因：

原因 解决方案
Token 错误 重新获取 Token
Bot 未激活 在 Telegram 中启动 Bot
用户不在白名单 添加用户到 allowedUsers
权限不足 检查 Bot 权限设置

问题 2：Discord Bot 离线

排查步骤：

# 1. 检查 Token
curl -H "Authorization: Bot <TOKEN>" \
  https://discord.com/api/v10/users/@me

常见原因：

原因 解决方案
Token 过期 重新生成 Token
Gateway 断开 检查网络连接
Intents 未开启 在开发者后台开启 Intent
未加入服务器 使用邀请链接添加 Bot

问题 3：飞书消息接收失败

排查步骤：

  1. 确认事件订阅 URL 可访问
  2. 验证 Token 配置
  3. 检查应用状态（是否发布）
# 验证服务可访问性
curl -X POST https://your-domain.com/webhook/feishu \
  -H "Content-Type: application/json" \
  -d '{"challenge":"test"}'

技能相关问题

问题 1：技能不触发

症状：发送关键词但技能没有执行

排查步骤：

# 1. 查看日志中的触发记录
# 日志应该显示类似：
# "Skill 'weather' triggered by keyword '天气'"

常见原因：

原因 解决方案
技能未启用 检查 enabled: true
触发词不匹配 检查 triggers 配置
技能加载失败 查看错误日志
权限不足 检查用户权限

检查配置：

# config/skills.yaml
skills:
  - path: "./skills/weather"
    enabled: true  # 确保启用

问题 2：技能执行超时

症状：

Error: Skill execution timeout

解决方案：

# 增加超时时间
skills:
  - path: "./skills/my-skill"
    timeout: 60000  # 60秒

或优化技能代码，减少执行时间。

问题 3：技能返回错误

症状：技能执行失败

排查步骤：

// 添加错误处理
module.exports = {
  async execute(params, context) {
    try {
      // 业务逻辑
    } catch (error) {
      // 记录错误
      context.logger.error('Skill error', error);

      // 返回友好错误信息
      return {
        type: 'text',
        content: '处理失败，请稍后重试'
      };
    }
  }
};

定时任务问题

问题 1：定时任务不执行

排查步骤：

# 1. 检查任务配置
# config/cron.yaml
tasks:
  - name: "my-task"
    enabled: true  # 确保启用

# 2. 查看 Cron 日志
# 日志应该显示任务执行记录

常见原因：

原因 解决方案
Cron 表达式错误 验证表达式格式
任务未启用 enabled: true
服务未运行 重启服务
时区设置错误 检查 timezone 配置

问题 2：任务执行两次

原因：可能启动了多个实例

解决方案：

# 检查运行的进程
ps aux | grep openclaw

# 只保留一个进程
kill <extra-pid>

问题 3：任务超时

解决方案：

tasks:
  - name: "long-task"
    timeout: 300000  # 5分钟
    retry:
      enabled: true
      maxAttempts: 2

内存/存储问题

问题 1：内存占用过高

症状：服务响应变慢，可能崩溃

排查：

# 查看内存使用
docker stats
# 或
top

# Node.js 内存问题
# 检查是否有内存泄漏
node --inspect dist/index.js

解决方案：

# 限制内存使用
# Docker 方式
deploy:
  resources:
    limits:
      memory: 2G

问题 2：磁盘空间不足

症状：

# 检查磁盘
df -h

解决方案：

# 清理日志
rm -f logs/*.log

# 清理缓存
rm -rf data/cache/*

# 清理 Docker
docker system prune -a

网络相关问题

问题 1：无法访问外部 API

症状：网络请求超时

排查：

# 测试网络连接
curl -I https://api.openai.com

# 检查代理设置
env | grep -i proxy

解决方案：

# 设置代理
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

问题 2：WebSocket 连接失败

症状：实时消息无法接收

解决方案：

# 配置 WebSocket
app:
  websocket:
    enabled: true
    path: "/ws"

配置相关问题

问题 1：配置文件不生效

原因：配置加载顺序问题

排查：

# 1. 检查配置文件位置
# 配置文件应该在 config/ 目录下

# 2. 验证配置是否正确加载
# 查看启动日志中的配置信息

问题 2：环境变量读取失败

症状：

Error: Environment variable not set: OPENAI_API_KEY

解决方案：

# 1. 检查 .env 文件位置
# 应该在项目根目录

# 2. 确认 .env 文件存在
ls -la .env

# 3. 重新加载配置
# 重启服务

日志分析指南

查看日志的方法

# 方式 1：控制台日志
npm run dev

# 方式 2：文件日志
tail -f logs/app.log

# 方式 3：Docker 日志
docker logs openclaw

日志级别

级别 说明
error 错误信息
warn 警告信息
info 一般信息
debug 调试信息

设置日志级别：

logging:
  level: "debug"  # 开发时使用

诊断命令汇总

# 检查服务状态
systemctl status openclaw

# 查看进程
ps aux | grep openclaw

# 检查端口
netstat -tlnp | grep 3000

# 检查资源使用
docker stats

# 查看日志
tail -f logs/app.log

# 测试配置
npm run test:config

寻求帮助

如果以上方法都无法解决你的问题：

  1. 查看文档：官方文档可能有更多信息
  2. 搜索社区：可能有人遇到过相同问题
  3. 提交 Issue：如果确定是 bug
  4. 社区求助：提供详细的错误日志

总结

遇到问题时： 1. 保持冷静，仔细阅读错误信息 2. 按照本文档的排查流程逐步检查 3. 利用日志和调试工具定位问题 4. 必要时寻求社区帮助

祝你顺利解决问题！

相关阅读： - OpenClaw 安装指南 - OpenClaw 配置详解 - OpenClaw 最佳实践