OpenClaw Doctor

Comprehensive health check for OpenClaw installations. Outputs a structured diagnostic report with severity levels and actionable fixes.

Language

Respond in the same language the user used to invoke this skill. If invoked via slash command with no additional text, infer the preferred language from context: check recent conversation history, workspace file content (e.g., CJK content in AGENTS.md or cron job payloads), and system locale. Fall back to English only if no language signal is found.

Prerequisites

command -v openclaw >/dev/null || echo "CRITICAL: openclaw not found in PATH"
command -v jq >/dev/null || echo "CRITICAL: jq not found — install with: brew install jq (macOS) or apt install jq (Linux)"

Paths

Auto-detect all paths at runtime. Do NOT hardcode platform-specific locations.

OPENCLAW_HOME="${OPENCLAW_HOME:-$HOME/.openclaw}"
OPENCLAW_CONFIG="$OPENCLAW_HOME/openclaw.json"
OPENCLAW_DIST=""
if command -v openclaw &>/dev/null; then
  OPENCLAW_DIST="$(dirname "$(readlink -f "$(command -v openclaw)")")/../lib/node_modules/openclaw/dist"
  [ -d "$OPENCLAW_DIST" ] || OPENCLAW_DIST=""
fi
SESSIONS_DIR="$OPENCLAW_HOME/agents/main/sessions"
SESSIONS_INDEX="$SESSIONS_DIR/sessions.json"
MODELS_JSON="$OPENCLAW_HOME/agents/main/agent/models.json"
WORKSPACE_GLOB="$OPENCLAW_HOME/workspace-*"
LOGS_DIR="$OPENCLAW_HOME/logs"
BROWSER_CACHE="$OPENCLAW_HOME/browser"
CRON_DIR="$OPENCLAW_HOME/cron"

If any path doesn't exist, note it and skip that check section.

Diagnostic Sections

Run ALL sections below sequentially. For each finding, assign a severity:

• CRITICAL

  — broken functionality, data loss risk

• WARNING

  — suboptimal config, potential issues

• INFO

  — informational, optimization opportunity

1. Installation & Version

Use the built-in status command as the primary data source:

openclaw status --all 2>&1
openclaw --version 2>/dev/null

Report: version, gateway running status, LaunchAgent status, channel health.

2. Config Consistency

Read

$OPENCLAW_CONFIG

and check:

1. Default model validity: Is

   agents.defaults.model.primary

   a known model? Cross-check with

   agents.defaults.models

   entries.
2. Fallback models: Are all models in

   agents.defaults.model.fallbacks

   defined in the models list?
3. Legacy config files: Check if

   clawdbot.json

   or other legacy files exist in

   $OPENCLAW_HOME/

   .
4. Backup file accumulation: Count

   *.bak*

   files in

   $OPENCLAW_HOME/

   . More than 2 is WARNING.
5. Channel config:
   • Telegram: Check

     requireMention

     setting per group.

     false

     = WARNING (bot responds to all messages).
   • Feishu: Check

     groupPolicy

     .

     "open"

     = WARNING (any group can interact).

3. Session Maintenance Config

Check

openclaw.json

for

session.maintenance

settings:

1. Maintenance mode: Missing or

   "warn"

   = WARNING (stale sessions accumulate without cleanup). Should be

   "enforce"

   .
2. pruneAfter: Missing or > 30d = INFO. Recommended:

   "7d"

   to

   "14d"

   .
3. maxEntries: Missing or > 200 = INFO. Default is 500, reasonable personal value is 50-100.
4. maxDiskBytes: Missing = INFO. Recommended: set a cap like

   "100mb"

   .

4. Compaction Config

Check

agents.defaults.compaction

in

openclaw.json

:

1. mode: Should be

   "safeguard"

   (default, safe). Note if missing.
2. reserveTokensFloor: Missing = WARNING. Without this buffer, context can overflow before compaction triggers. Recommended:

   20000

   .
3. keepRecentTokens: Missing = INFO. Controls how much recent conversation is preserved verbatim during compaction. Recommended:

   8000

   .

5. Model Alignment

Use the built-in sessions list, then cross-reference with config:

openclaw sessions 2>&1

Also read

sessions.json

programmatically to check:

1. Session model drift: List any sessions whose

   model

   field differs from the configured default. Particularly check channel sessions (telegram:, feishu:).
2. contextTokens vs model contextWindow: Compare each session's

   contextTokens

   against its model's actual

   contextWindow

   (from

   models.json

   or built-in registry). Mismatch = WARNING (e.g., 272k contextTokens on a 200k model can cause overflow).
3. Forward-compat patches: Check if dist files have been locally patched by searching for non-standard constants (e.g. model IDs not in the official

   XHIGH_MODEL_REFS

   or custom

   resolveForwardCompatModel

   additions) in

   $OPENCLAW_DIST/*.js

   .
4. Thinking config: Read the thinking config file (find via

   grep -rl "XHIGH_MODEL_REFS" $OPENCLAW_DIST/

   ) and verify the current default model is included in

   XHIGH_MODEL_REFS

   if it should support xhigh thinking.
5. models.json override: Read

   $MODELS_JSON

   and check if inline model definitions are consistent with

   openclaw.json

   .

6. Session Health

Use the built-in cleanup dry-run as primary data source:

openclaw sessions cleanup --dry-run --fix-missing 2>&1

Then supplement with filesystem checks:

1. Orphan JSONL files: Files in directory but not referenced in

   sessions.json

   . Calculate total size.
2. Zombie session entries: Entries in

   sessions.json

   pointing to non-existent JSONL files.
3. Empty JSONL files: Referenced files that are 0 bytes.
4. Deleted file accumulation:

   *.deleted.*

   files that can be cleaned up. Calculate total size.
5. Cron session accumulation: Count sessions with

   :cron:

   in their key. Separate parent jobs from

   :run:

   sub-sessions. Large numbers (>20) indicate cleanup isn't working.

7. Cron Health

Read

$CRON_DIR/jobs.json

and check:

1. Duplicate enabled jobs: Jobs with identical

   name

   +

   schedule

   +

   enabled: true

   . Flag as WARNING with dedup suggestion.
2. Disabled job accumulation: Count

   enabled: false

   jobs. More than 10 = INFO (suggest cleanup if user confirms they're not needed).
3. Tmp file accumulation: Count

   jobs.json.*.tmp

   files in

   $CRON_DIR

   . These are abandoned atomic-write artifacts. Any count > 0 with no process holding them open (

   lsof

   ) = safe to delete.
4. Cron runs directory: Check

   $CRON_DIR/runs/

   for accumulated run logs. Count and total size.
5. Stale enabled jobs: Enabled jobs whose

   state.lastRunAtMs

   is older than expected based on their schedule (e.g., a daily job that hasn't run in 3+ days).

8. Security Audit

Check

openclaw.json

for:

1. Feishu groupPolicy:

   "open"

   means any Feishu group can interact = CRITICAL.
2. Feishu/Telegram allowFrom:

   ["*"]

   means no restriction = WARNING.
3. Telegram requireMention:

   false

   on groups = WARNING (bot responds to every message).
4. Gateway auth mode: Read

   gateway.auth.mode

   from config.

   "token"

   is good,

   "none"

   = CRITICAL.
5. Exposed secrets in non-gitignored files: Check if

   $OPENCLAW_HOME/

   contains any files that might be accidentally synced (e.g., check for

   .git

   directory in

   $OPENCLAW_HOME/

   ).
6. API keys in models.json: Note if API keys are stored in plaintext in

   models.json

   (this is expected but worth noting).

9. Resource Usage

du -sh $OPENCLAW_HOME/browser/ 2>/dev/null    # Browser cache
du -sh $OPENCLAW_HOME/logs/ 2>/dev/null       # Logs
du -sh $SESSIONS_DIR/ 2>/dev/null             # Sessions
du -sh $OPENCLAW_HOME/media/ 2>/dev/null      # Media files
du -sh $OPENCLAW_HOME/memory/ 2>/dev/null     # Memory files
du -sh $CRON_DIR/ 2>/dev/null                 # Cron data
du -sh $OPENCLAW_HOME/ 2>/dev/null            # Total

# Log file sizes
ls -lhS $LOGS_DIR/ 2>/dev/null

# Large JSONL sessions (top 5)
ls -lhS $SESSIONS_DIR/*.jsonl 2>/dev/null | head -5

Flag:

• Browser cache > 200MB = WARNING
• Logs > 50MB = WARNING
• Any single JSONL > 10MB = INFO
• Total

  $OPENCLAW_HOME/

  > 1GB = WARNING

10. Gateway & Process Health

Read

gateway.port

from

openclaw.json

to determine the correct port (do NOT hardcode).

# Check for stuck/zombie openclaw processes
ps aux | grep -E "openclaw-gateway|openclaw " | grep -v grep

# Check gateway port binding (use port from config)
lsof -i :<port> 2>/dev/null | head -5

# Check gateway error log for recent errors
tail -20 $LOGS_DIR/gateway.err.log 2>/dev/null

Flag:

• Multiple gateway processes = CRITICAL
• Gateway not listening on configured port = CRITICAL
• Recent errors in gateway.err.log = WARNING (show last 5 errors)

11. System Instruction Health

Measures static system instruction token footprint. Complements Section 5 (runtime session pressure) — together they form the Context Budget picture.

Step A: Data Collection (deterministic script)

Locate and run the bundled collector script from the skill directory:

# Find the skill directory (works whether installed via skills.sh, clawhub, or manually)
SKILL_DIR="$(find ~/.claude/skills ~/.agents/skills -maxdepth 3 -name 'sysinstruction-check.sh' -path '*/oc-doctor/*' 2>/dev/null | head -1 | xargs dirname)"
bash "$SKILL_DIR/sysinstruction-check.sh"

The script auto-detects workspace directories and outputs structured JSON. See scripts/sysinstruction-check.sh for details.

Output schema:

{
  "workspace_files": [
    {"file": "workspace-name/FILE.md", "chars": 0, "lines": 0, "est_tokens": 0, "is_empty_template": false}
  ],
  "total_est_tokens": 0,
  "largest_file": "AGENTS.md",
  "empty_template_files": [],
  "tool_bloat_files": [],
  "tool_bloat_est_tokens": 0,
  "bootstrap_still_present": false,
  "context_window": 200000,
  "context_window_source": "models.json | default_fallback",
  "pct_of_context": "0.0"
}

Step B: LLM Analysis

Analyze the JSON output along these dimensions:

1. Context budget ratio (complements Section 5's runtime check):

   • pct_of_context < 2%

     =

     INFO

     healthy

   • 2-5%

     =

     INFO

     acceptable but worth reviewing

   • 5-10%

     =

     WARNING

     consider trimming

   • 10-15%

     =

     WARNING

     (strong) actively optimize

   • > 15%

     =

     CRITICAL

     only if paired with runtime truncation evidence
   • If

     context_window_source

     is

     "default_fallback"

     , note that thresholds may be inaccurate

2. Tool description bloat:

   • tool_bloat_files

     non-empty =

     WARNING

     , list files and estimated token cost
   • These are auto-injected by OpenClaw (e.g., Feishu bitable tools) — check if all are necessary

3. Reclaimable space (read

   empty_template_files

   and

   bootstrap_still_present

   ):

   • bootstrap_still_present = true

     =

     INFO

     , can be deleted after initial setup

   • empty_template_files

     non-empty =

     INFO

     , list files and estimated token savings

4. Per-file analysis:

   • Single file > 40% of total tokens =

     WARNING

     , consider splitting
   • Single file > 2% of context window =

     WARNING

     , review individually
   • AGENTS.md is typically the largest (memory/group-chat/heartbeat rules), but > 5000 tokens warrants review

5. Benchmarks (dynamic, based on actual context window):

   Healthy:        < 2% of context_window
   Needs review:   2-5% of context_window
   Needs optimization: > 5% of context_window
   

6. Cross-reference integrity:

   • Scan the largest workspace file (typically AGENTS.md) for references to other

     .md

     filenames (e.g.,

     HEARTBEAT.md

     ,

     BOOTSTRAP.md

     ,

     MEMORY.md

     ).
   • For each referenced file: check if it exists in any

     workspace-*/ directory

     and whether it is an empty template.
   • Referenced but missing =

     WARNING

     — the agent has instructions that depend on a file that doesn't exist. Offer to generate a practical version based on the user's actual config (cron jobs, channels, heartbeat rules in AGENTS.md).
   • Referenced but empty template =

     WARNING

     — the file exists but has no real content, so the agent's instructions referencing it are ineffective. Offer to populate it with useful content or remove the dead reference.

Output (integrated into main report)

Add a System Instruction section to Findings:

### [SEVERITY] System Instruction Token Usage

| File | Lines | Chars | ~Tokens | % of Context |
|------|-------|-------|---------|--------------|
| AGENTS.md | N | N | N | N% |
| SOUL.md | N | N | N | N% |
| ... | ... | ... | ... | ... |
| **Total** | **N** | **N** | **N** | **N%** |

- Status: Healthy / Elevated / Needs Optimization
- Suggestions: (specific optimization actions, if any)

Output Format

Present results as a structured diagnostic report:

# OpenClaw Doctor Report

## Summary
- Version: x.x.x
- Gateway: running/stopped
- Overall Health: HEALTHY / NEEDS ATTENTION / CRITICAL

## Findings

### [SEVERITY] Finding Title
- Description: ...
- Impact: ...
- Fix: (specific command or config change)

(repeat for each finding)

## Quick Stats
| Metric | Value |
|---|---|
| Active sessions | N |
| Cron jobs (enabled/disabled) | N / N |
| Orphan files | N (size) |
| Browser cache | size |
| Total disk usage | size |

## Recommended Actions
1. (prioritized list of suggested fixes)

Interactive Mode

After presenting the report, ask the user (in their language):

"Would you like me to fix these issues? I can address them one by one, or batch-fix all WARNING-level and below. CRITICAL issues will be confirmed individually."

For fixes:

• Orphan/deleted files: Offer to delete with size summary.
• Model drift / contextTokens mismatch: Offer to align all sessions to default model and correct contextWindow.
• Config issues: Show the specific config change needed, confirm before applying.
• Cron dedup / tmp cleanup: Show what will be removed, confirm before applying.
• Maintenance config: Suggest optimal values, confirm before applying.
• Resource cleanup: Offer to clear browser cache, rotate logs.
• Security issues: Show the config change and explain the tradeoff before applying.
• System instruction bloat: Offer to archive BOOTSTRAP.md (rename to

  .bak

  ), clean empty template files, flag tool description injection.
• Referenced but missing/empty workspace files: Generate a practical version based on the user's actual config. For HEARTBEAT.md specifically, analyze cron jobs, channels, and heartbeat rules in AGENTS.md to produce a useful checklist (not an empty template).

Secret Redaction (MANDATORY)

When displaying config excerpts in the report, always redact sensitive values:

• API keys / tokens: show only first 8 chars +

  ...

  (e.g.,

  8263689670:A...

  )
• Passwords / secrets: show

  ***REDACTED***

• Never include full botToken, appSecret, auth token, or API key values in the report output.

Security & Privacy

This skill operates locally and makes no network requests. However, diagnostic output becomes part of the LLM conversation context.

Files read (read-only unless user approves a fix):

• $OPENCLAW_HOME/openclaw.json

  — main config

• $OPENCLAW_HOME/agents/main/agent/models.json

  — model definitions

• $OPENCLAW_HOME/agents/main/sessions/sessions.json

  — session index

• $OPENCLAW_HOME/workspace-*/*.md

  — system instruction files

• $OPENCLAW_HOME/cron/jobs.json

  — cron job definitions

• $OPENCLAW_HOME/logs/gateway.err.log

  — recent gateway errors

• $OPENCLAW_DIST/*.js

  — installed dist files (for patch detection)

Files modified (only with explicit user confirmation):

• Session JSONL files (orphan cleanup)
• Config JSON files (optimization)
• Workspace

  .md

  files (BOOTSTRAP.md archival)
• Cron tmp files (cleanup)

Environment variables read:

OPENCLAW_HOME

(optional override).

No secrets are transmitted or logged. The skill may display config excerpts in the diagnostic report shown to the user.