oc-doctor

---
name: oc-doctor
description: >
  Runs a comprehensive 11-section health check on local OpenClaw installations.
  Diagnoses configuration errors, session bloat, model drift, cron issues, security
  misconfigurations, gateway problems, and system instruction token budget.
  Generates a structured report with CRITICAL/WARNING/INFO findings and offers
  interactive one-click fixes. Use when: "openclaw doctor", "claw doctor",
  "claw health check", "openclaw diagnose", or troubleshooting OpenClaw.
version: 1.0.0
metadata:
  openclaw:
    requires:
      bins:
        - openclaw
        - jq
    emoji: "stethoscope"
    homepage: https://github.com/bryant24hao/oc-doctor
    os:
      - macos
      - linux
---

# 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

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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).

```bash
# 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:

```bash
# 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](scripts/sysinstruction-check.sh) for details.

Output schema:
```json
{
  "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.

• README.md 7 KB
• README.zh-CN.md 6 KB
• SKILL.md 16 KB
• _meta.json 1 KB
• assets/demo.svg 5 KB
• docs/user-story.en.md 4 KB
• docs/user-story.md 4 KB
• scripts/sysinstruction-check.sh 5 KB