OpenClaw Diagnostics

Diagnoses and troubleshoots OpenClaw config, channel, group message, cron job, and authentication issues using logs and built-in knowledge base.

Security Scan

The skill largely matches its described diagnostic purpose, but it reads local OpenClaw config/logs and performs network updates without declaring those accesses, and automated scanners flagged potential prompt-injection patterns — review before trusting or enabling it.

Purpose & Capability

The skill's name/description match what the scripts do (gather local OpenClaw config, status, and logs and consult a bundled docs snapshot). However the package does not declare that it expects the OpenClaw CLI or that it will read $HOME/.openclaw/openclaw.json, which is inconsistent with its actual behavior.

Instruction Scope

Runtime instructions and included scripts explicitly read the user's OpenClaw config and logs (~$HOME/.openclaw/openclaw.json and calling `openclaw logs`/`openclaw status`). That is appropriate for diagnostics, but SKILL.md gives the skill broad discretion to load and print those files; this can expose secrets. The SKILL.md also instructs running update-knowledge-base (network fetch) which will contact docs.openclaw.ai to download many pages.

Install Mechanism

No install spec (instruction-only with shipped scripts and assets). The update script fetches docs from a single official-looking domain (docs.openclaw.ai). No ad-hoc binary downloads or extract-from-unknown-URLs were found.

Credentials

The skill requests no env vars in metadata but its scripts access the user's home config and may print auth-related fields from openclaw.json or from `openclaw logs` output. This access is plausible for a diagnostics tool but the lack of declared config paths or a required-binary entry is a mismatch and increases risk of accidental secret exposure.

Persistence & Privilege

always is false and the skill writes only to its own assets directory when updating the knowledge base. It does not appear to modify other skills or global agent settings.

Scan Findings in Context

[system-prompt-override] unexpected: Pre-scan flagged a system-prompt-override pattern in SKILL.md. The visible SKILL.md content does not contain an obvious system-prompt override block, so this may be a false positive or hidden/obfuscated content; recommend manual inspection for any injected instructions that attempt to change agent prompts or behavior.

[base64-block] unexpected: Scanner found a base64-block pattern. The included files do not obviously contain long base64 strings in the visible excerpts, so this could be a false positive or indicate embedded/obfuscated payloads in files (check assets and scripts for encoded data before running).

[unicode-control-chars] unexpected: Scanner detected unicode-control-chars patterns that can hide or alter displayed text. The SKILL.md and references should be examined for non-printing characters that might hide instructions or malicious strings.

What to consider before installing

This skill appears to be a legitimate OpenClaw diagnostics tool, but it will read and print files from $HOME/.openclaw (including openclaw.json) and may call your local openclaw CLI; those files can contain tokens or secrets. Before installing or running: 1) Inspect ~/.openclaw/openclaw.json for sensitive fields and consider redacting secrets or running the scripts in a sandbox; 2) Review scripts/get-diagnostic-info.sh and scripts/check-common-issues.sh (already included) and the entire update-knowledge-base.ts for any unexpected endpoints or embedded data; 3) Because the SKILL.md/meta do not declare the config path or required binary, assume it will access local OpenClaw credentials and logs — if you cannot risk disclosure, do not enable autonomous invocation and run the scripts manually instead; 4) The pre-scan flags (prompt-override, base64, unicode control chars) may be false positives but warrant a manual check of SKILL.md and assets for obfuscated content. If the publisher/source is unknown or untrusted, prefer to run diagnostics locally rather than grant the skill ongoing or autonomous privileges.

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:

   • 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
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