龙虾文档

主题

故障排查 ​

本页汇总了 OpenClaw 使用过程中的常见问题和解决方案，内容基于社区高频反馈整理。

诊断工具速查 ​

遇到问题时，先运行以下命令收集信息：

bash
openclaw status          # 查看运行状态
openclaw status --deep   # 深度健康检查
openclaw doctor          # 系统诊断和修复建议
openclaw logs --follow   # 实时查看日志
openclaw gateway restart # 重启网关

openclaw doctor 是你的第一选择

openclaw doctor 是内置的自动诊断工具，能检测大部分常见问题并给出修复建议。遇到任何异常，优先运行它。

常见问题 ​

1. Tools Profile Bug（v3.7 之前版本） ​

现象：OpenClaw 只给出建议文字，但不会实际执行任何操作（如不会创建文件、不会运行命令）。

原因：v3.7 之前的版本默认 tools.profile 为 suggest，只提供建议而不执行。

解决方案：

bash
# 将 tools.profile 设置为 full，允许完整工具调用
openclaw config set tools.profile full

# 重启网关使配置生效
openclaw gateway restart

升级到 v3.7+ 后不再需要此操作

v3.7 及以后版本已将默认值改为 full。如果你是新安装用户，通常不会遇到此问题。

2. 网关未运行 ​

现象：发送消息无响应，Web 控制台无法打开。

排查步骤：

bash
# 检查网关状态
openclaw status

# 如果显示 stopped，重启网关
openclaw gateway restart

如果重启后仍然失败，查看日志获取详细错误：

bash
openclaw logs --follow

常见原因：

  • 端口被其他进程占用
  • Node.js 版本不满足要求
  • 配置文件损坏

3. 模型 API 连接失败 ​

现象：发送消息后返回错误提示，如 API connection failed 或 401 Unauthorized。

排查步骤：

bash
# 深度健康检查，会测试 API 连通性
openclaw status --deep

逐项检查：

  • API Key 是否正确：openclaw config get models 查看当前配置，确认 Key 未过期
  • Base URL 是否正确：如果使用自定义 API 端点，确认 URL 格式正确且可访问
  • 网络是否通畅：确认能访问模型提供商的 API 地址（国内用户注意代理配置）
bash
# 重新设置 API Key
openclaw config set models.anthropic.apiKey sk-xxx

# 设置自定义 Base URL（如使用代理）
openclaw config set models.anthropic.baseUrl https://your-proxy.com/v1

4. 频道无响应 ​

现象：消息发出去了，但 AI 没有回复。

排查步骤：

bash
# 检查所有频道的连接状态
openclaw channels status

常见原因与解决：

  • Token 格式错误：确认 Token 没有多余的空格或换行符
  • Token 已失效：重新生成并配置 Token
  • 网关未运行：先确认网关状态正常
bash
# 重新配置频道 Token
openclaw channels login <channel-name>

# 重启网关
openclaw gateway restart

5. Node.js 版本问题 ​

现象：安装失败或运行时报语法错误。

要求：OpenClaw 需要 Node.js 22 或更高版本。

bash
# 检查当前版本
node --version

如果版本低于 22，请升级：

bash
# 使用 nvm 安装最新 LTS 版本
nvm install 22
nvm use 22

# 或直接从官网下载：https://nodejs.org/

不要使用 Node.js 18 或更低版本

OpenClaw 使用了大量 Node.js 22 的新特性，低版本无法运行。

6. npm install 失败（国内网络问题） ​

现象：npm install -g openclaw 卡住或报网络错误。

解决方案：切换为国内镜像源。

bash
# 设置 npm 镜像
npm config set registry https://registry.npmmirror.com

# 然后重新安装
npm install -g openclaw@latest

临时使用镜像

如果不想全局修改，可以单次指定：

bash
npm install -g openclaw@latest --registry https://registry.npmmirror.com

7. Skills 不工作 ​

现象：调用技能时无反应或报错 skill not found。

排查步骤：

bash
# 检查 tools.profile 是否为 full
openclaw config get tools.profile

# 查看已启用的技能列表
openclaw skills list

解决：

bash
# 确保 tools.profile 设置为 full
openclaw config set tools.profile full

# 如果技能未启用，手动启用
openclaw skills enable <skill-name>

# 重启网关
openclaw gateway restart

8. Token 消耗过高 ​

现象：使用一段时间后，API 费用明显增加。

原因：随着对话进行，上下文（Context）不断增长，每次请求发送的 Token 数量越来越多。

优化建议：

  • 使用更便宜的模型：日常对话可以切换到成本较低的模型
  • 使用 Coding Plan 模式：先让模型制定计划再执行，减少反复试错的 Token 消耗
  • 及时清理上下文：长对话可以通过新开会话来重置上下文
  • 设置 Token 预算：通过配置限制单次对话的最大 Token 数
bash
# 切换模型
openclaw config set models.default <cheaper-model>

9. Cron 定时任务未执行 ​

现象：设置了定时任务但没有按时运行。

排查步骤：

bash
# 查看已注册的 Cron 任务
openclaw cron list

# 确认网关正在运行（Cron 依赖网关）
openclaw status

常见原因：

  • 网关未运行：Cron 任务由网关调度，网关停止后任务不会执行
  • --channel 格式错误：确认频道名称拼写正确
  • 时区问题：确认 Cron 表达式使用的时区与预期一致
bash
# 重启网关确保 Cron 调度器运行
openclaw gateway restart

10. 使用 openclaw doctor 全面诊断 ​

当以上方法都无法定位问题时，运行完整诊断：

bash
openclaw doctor

openclaw doctor 会自动检测：

  • Node.js 版本是否满足要求
  • 网关是否正常运行
  • API Key 是否有效
  • 频道连接是否正常
  • 配置文件是否有语法错误
  • 磁盘空间和端口占用情况

根据诊断结果，它会给出具体的修复建议和命令，按提示操作即可。

11. API 限流（429 Too Many Requests） ​

现象：频繁调用后返回 429 错误。

解决方案：

  • 降低调用频率，减少活跃技能数量
  • 配置 Fallback 模型，自动切换到其他供应商
  • 联系模型供应商提升限额
json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat",
        "fallback": ["openrouter/google/gemini-flash-1.5"]
      }
    }
  }
}

12. 记忆丢失 / 上下文超出 ​

现象：Agent 忘记之前的对话内容，或提示上下文超出限制。

原因：对话过长，超出模型的上下文窗口（Context Window）。

解决：

  • 开启新会话重置上下文
  • 将重要信息写入 MEMORY.md 持久保存
  • 使用支持更长上下文的模型（如 Moonshot 128K）

13. Windows PowerShell 执行策略 ​

现象：Windows 下安装时报 ExecutionPolicy 错误。

解决：以管理员身份运行 PowerShell：

powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

日志管理 ​

bash
# 实时查看日志
openclaw logs --follow

# 最近 100 条
openclaw logs --limit 100

# JSON 格式输出（便于分析）
openclaw logs --json

# 只看错误
openclaw logs --level error

配置日志级别：

json
{
  "gateway": {
    "logging": {
      "level": "info"
    }
  }
}

开发调试时可设为 debug，生产环境建议使用 info 或 warn。

性能优化 ​

如果 Agent 响应变慢：

优化项方法
减少活跃技能openclaw skills disable <不常用的技能>
使用更快的模型简单任务切换到 DeepSeek V3 或 Gemini Flash
启用缓存减少重复 API 调用
增大心跳间隔减少后台 Token 消耗
清理历史对话定期清理 30 天前的记忆文件

还是无法解决？ ​

如果以上内容都无法帮助你解决问题：

  1. 运行 openclaw doctor 并保存输出
  2. 运行 openclaw logs --follow 复现问题并保存日志
  3. 到 GitHub Issues 提交问题，附上以上信息

社区资源 ​

  • GitHub Issues — 搜索已有问题或提交新问题
  • Discord 社区 — 实时交流和问答
  • Datawhale 中文社区 — 国内用户互助

基于 MIT 协议发布

© 2025-2026 longxia.best — OpenClaw 中文社区 · GitHub