OpenClaw Diagnostics
Configuration diagnostics and troubleshooting skill for OpenClaw, powered by built-in AI without external dependencies.
Quick Diagnostics
When a user reports an OpenClaw issue:
1. Gather Diagnostic Info
CODEBLOCK0
2. Run Basic Checks
CODEBLOCK1
3. Analyze Based on Issue Type
Refer to references/common-issues.md for diagnostic rules.
Diagnostic Workflow
CODEBLOCK2
Knowledge Base
The skill includes a built-in knowledge base with 335 OpenClaw documentation pages.
Location: INLINECODE1
Structure:
CODEBLOCK3
To lookup a document:
- 1. Read
references/knowledge-base-index.md to find relevant slugs - Load INLINECODE3
- Access
pages[slug] for content
Common Document Slugs:
| Topic | Slugs |
|---|
| Group Messages | INLINECODE5 , INLINECODE6 |
| Pairing |
919c126f |
| Message Routing |
a99b0ed8 |
| Automation Troubleshooting |
a632126a |
| Auth Monitoring |
87e3285b |
| Cron Jobs |
b239629c |
| Channels Overview |
6569d3b4 |
| WhatsApp |
d09047a0 |
| Telegram |
d423ce29 |
| Feishu |
90a33c43 |
Updating Knowledge Base
The knowledge base can be updated to get the latest OpenClaw documentation.
Requirements: Network connection (no LLM needed)
Check for updates:
CODEBLOCK4
Update to latest:
CODEBLOCK5
Force update:
CODEBLOCK6
Features:
- - Version checking based on sitemap lastmod
- No LLM required - lightweight and fast
- Remembers previously skipped versions
Common Issues
Group Messages Not Responding
- 1. Check basics:
- Is the bot in the group?
- Did the user @ mention the bot?
- Is Gateway running?
- 2. Check config:
-
ackReactionScope:
group-mentions means only reply to @ messages
-
groupPolicy:
open allows all groups,
allowlist requires whitelist
- 3. ⚠️ Don't misdiagnose:
groupPolicy: "open" is valid config, not "empty"
DM Not Responding
Check pairing status and allowFrom configuration.
Cron Jobs Not Running
- 1. Confirm Gateway is running
- Check cron expression
- Check logs for trigger confirmation
- Check mute hours settings
Channel Connection Issues
- 1. Run
openclaw status to check status - Check channel-specific config
- Look for errors in logs
Diagnosis Principles
- 1. Confirm basics first - Don't skip simple checks
- Check logs - Logs usually contain the most direct error info
- Don't over-diagnose - If config is valid, don't suggest "improvements"
- Reference docs - Cite relevant document slugs in diagnosis
Resources
scripts/
- -
get-diagnostic-info.sh - Get config, status, and logs - INLINECODE25 - Common issue checker
- INLINECODE26 - Update knowledge base (requires tsx)
assets/
- -
default-snapshot.json - Built-in knowledge base (335 docs) - INLINECODE28 - Update tracking (created after first check)
references/
- -
knowledge-base-index.md - Document index by category - INLINECODE30 - Diagnostic rules for common issues
OpenClaw 诊断
OpenClaw 的配置诊断与故障排查技能，由内置 AI 驱动，无需外部依赖。
快速诊断
当用户报告 OpenClaw 问题时：
1. 收集诊断信息
bash
~/.openclaw/workspace/skills/openclaw-diagnostics/scripts/get-diagnostic-info.sh
2. 运行基本检查
bash
~/.openclaw/workspace/skills/openclaw-diagnostics/scripts/check-common-issues.sh
3. 根据问题类型进行分析
请参考 references/common-issues.md 中的诊断规则。
诊断流程
用户报告问题
↓
收集信息（配置 + 状态 + 日志）
↓
运行基本检查
↓
从知识库中查找相关文档
↓
分析并提供诊断
↓
建议修复方案
知识库
该技能包含一个内置知识库，包含 335 个 OpenClaw 文档页面。
位置： assets/default-snapshot.json
结构：
json
{
meta: { pageCount: 335, snapshotDate: ..., sizeBytes: 3240482 },
index: [{ slug: ..., title: ..., url: ..., description: ... }],
pages: { slug: markdown content... }
}
查找文档：
- 1. 阅读 references/knowledge-base-index.md 查找相关 slug
- 加载 assets/default-snapshot.json
- 访问 pages[slug] 获取内容
常用文档 Slug：
| 主题 | Slug |
|---|
| 群组消息 | 008888be, 0bfb808e |
| 配对 |
919c126f |
| 消息路由 | a99b0ed8 |
| 自动化故障排查 | a632126a |
| 认证监控 | 87e3285b |
| 定时任务 | b239629c |
| 频道概览 | 6569d3b4 |
| WhatsApp | d09047a0 |
| Telegram | d423ce29 |
| 飞书 | 90a33c43 |
更新知识库
知识库可以更新以获取最新的 OpenClaw 文档。
要求： 网络连接（无需 LLM）
检查更新：
bash
cd ~/.openclaw/workspace/skills/openclaw-diagnostics
npx tsx scripts/update-knowledge-base.ts --check
更新到最新版本：
bash
cd ~/.openclaw/workspace/skills/openclaw-diagnostics
npx tsx scripts/update-knowledge-base.ts
强制更新：
bash
npx tsx scripts/update-knowledge-base.ts --force
特性：
- - 基于站点地图最后修改时间的版本检查
- 无需 LLM - 轻量且快速
- 记住之前跳过的版本
常见问题
群组消息无响应
- 1. 检查基础项：
- 机器人是否在群组中？
- 用户是否 @ 了机器人？
- Gateway 是否在运行？
- 2. 检查配置：
- ackReactionScope：group-mentions 表示仅回复 @ 消息
- groupPolicy：open 允许所有群组，allowlist 需要白名单
- 3. ⚠️ 不要误诊： groupPolicy: open 是有效配置，不是空配置
私聊无响应
检查配对状态和 allowFrom 配置。
定时任务未运行
- 1. 确认 Gateway 正在运行
- 检查 cron 表达式
- 检查日志确认触发情况
- 检查静音时段设置
频道连接问题
- 1. 运行 openclaw status 检查状态
- 检查频道特定配置
- 在日志中查找错误信息
诊断原则
- 1. 首先确认基础项 - 不要跳过简单检查
- 检查日志 - 日志通常包含最直接的错误信息
- 不要过度诊断 - 如果配置有效，不要建议改进
- 参考文档 - 在诊断中引用相关文档 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 - 常见问题的诊断规则
