OpenClaw 诊断工具

OpenClaw 的配置诊断与故障排查技能，基于内置 AI 实现，无需外部依赖。

快速诊断

当用户报告 OpenClaw 问题时，请按以下步骤操作：

1. 收集诊断信息

~/.openclaw/workspace/skills/openclaw-diagnostics/scripts/get-diagnostic-info.sh

2. 执行基础检查

~/.openclaw/workspace/skills/openclaw-diagnostics/scripts/check-common-issues.sh

3. 根据问题类型进行分析

参考 references/common-issues.md 获取诊断规则。

诊断流程

用户报告问题
        ↓
收集信息（配置 + 状态 + 日志）
        ↓
执行基础检查
        ↓
从知识库中查找相关文档
        ↓
分析并提供诊断结果
        ↓
建议修复方案

知识库

该技能包含一个内置知识库，收录了 335 篇 OpenClaw 文档。

位置： assets/default-snapshot.json

结构：

{
  "meta": { "pageCount": 335, "snapshotDate": "...", "sizeBytes": 3240482 },
  "index": [{ "slug": "...", "title": "...", "url": "...", "description": "..." }],
  "pages": { "slug": "markdown content..." }
}

文档查询方法：

1. 阅读 references/knowledge-base-index.md 以查找相关 slug
2. 加载 assets/default-snapshot.json
3. 通过 pages[slug] 获取内容

常见文档 Slug：

更新知识库

可更新知识库以获取最新的 OpenClaw 文档内容。

要求： 需要网络连接（无需 LLM）

检查更新：

cd ~/.openclaw/workspace/skills/openclaw-diagnostics
npx tsx scripts/update-knowledge-base.ts --check

更新至最新版本：

cd ~/.openclaw/workspace/skills/openclaw-diagnostics
npx tsx scripts/update-knowledge-base.ts

强制更新：

npx tsx scripts/update-knowledge-base.ts --force

功能特点：

• 基于站点地图 lastmod 进行版本比对
• 不需要 LLM —— 轻量且快速
• 记录已跳过的版本，避免重复检查

常见问题

群组消息无响应

1. 检查基础项：

- 机器人是否在群组中？

- 用户是否 @ 了机器人？

- Gateway 是否正在运行？

1. 检查配置：

- ackReactionScope: 设置为 group-mentions 表示仅回复 @ 消息

- groupPolicy: open 允许所有群组，allowlist 需要白名单

1. ⚠️ 注意： groupPolicy: "open" 是合法配置，不应误判为“空配置”

私信（DM）无响应

检查配对状态及 allowFrom 配置。

定时任务（Cron）未执行

1. 确认 Gateway 正在运行
2. 检查 Cron 表达式是否正确
3. 查看日志确认触发事件
4. 检查静音时段设置

频道连接异常

1. 执行 openclaw status 检查服务状态
2. 检查频道特定配置
3. 查看日志中的错误信息

诊断原则

1. 先确认基础项 —— 不跳过简单检查
2. 查看日志 —— 日志通常包含最直接的错误信息
3. 避免过度诊断 —— 若配置合法，不建议“优化”或“改进”
4. 引用文档 —— 诊断中应注明相关文档的 slug

资源

scripts/

• get-diagnostic-info.sh —— 收集配置、状态和日志信息
• check-common-issues.sh —— 常见问题检查脚本
• update-knowledge-base.ts —— 更新知识库（需 tsx 支持）

assets/

• default-snapshot.json —— 内置知识库（共 335 篇文档）
• update-meta.json —— 更新记录文件（首次检查后生成）

references/

• knowledge-base-index.md —— 按类别组织的文档索引
• common-issues.md —— 常见问题的诊断规则说明