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

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

2. Run Basic Checks

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

3. Analyze Based on Issue Type

Refer to references/common-issues.md for diagnostic rules.

Diagnostic Workflow

User reports issue
        ↓
Gather info (config + status + logs)
        ↓
Run basic checks
        ↓
Lookup relevant docs from knowledge base
        ↓
Analyze and provide diagnosis
        ↓
Suggest fixes

Knowledge Base

The skill includes a built-in knowledge base with 335 OpenClaw documentation pages.

Location: assets/default-snapshot.json

Structure:

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

To lookup a document: 1. Read references/knowledge-base-index.md to find relevant slugs 2. Load assets/default-snapshot.json 3. Access pages[slug] for content

Common Document Slugs:

Topic	Slugs
Group Messages	008888be, 0bfb808e
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:

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

Update to latest:

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

Force update:

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

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:
2. Is the bot in the group?
3. Did the user @ mention the bot?

4. Is Gateway running?

5. Check config:

6. ackReactionScope: group-mentions means only reply to @ messages

7. groupPolicy: open allows all groups, allowlist requires whitelist

8. ⚠️ 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
2. Check cron expression
3. Check logs for trigger confirmation
4. Check mute hours settings

Channel Connection Issues

1. Run openclaw status to check status
2. Check channel-specific config
3. Look for errors in logs

Diagnosis Principles

1. Confirm basics first - Don't skip simple checks
2. Check logs - Logs usually contain the most direct error info
3. Don't over-diagnose - If config is valid, don't suggest "improvements"
4. Reference docs - Cite relevant document slugs in diagnosis

Resources

scripts/

• get-diagnostic-info.sh - Get config, status, and logs
• check-common-issues.sh - Common issue checker
• update-knowledge-base.ts - Update knowledge base (requires tsx)

assets/

• default-snapshot.json - Built-in knowledge base (335 docs)
• update-meta.json - Update tracking (created after first check)

references/

• knowledge-base-index.md - Document index by category
• common-issues.md - Diagnostic rules for common issues