oc-doctor

Runs a comprehensive 11-section health check on local OpenClaw installations. Diagnoses configuration errors, session bloat, model drift, cron issues, securi...

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.