back
loading skill details...
Runs a comprehensive 11-section health check on local OpenClaw installations. Diagnoses configuration errors, session bloat, model drift, cron issues, securi...
---
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.
don't have the plugin yet? install it then click "run inline in claude" again.