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:

Default model validity: Is agents.defaults.model.primary a known model? Cross-check with agents.defaults.models entries.
Fallback models: Are all models in agents.defaults.model.fallbacks defined in the models list?
Legacy config files: Check if clawdbot.json or other legacy files exist in $OPENCLAW_HOME/.
Backup file accumulation: Count *.bak* files in $OPENCLAW_HOME/. More than 2 is WARNING.
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:

Maintenance mode: Missing or "warn" = WARNING (stale sessions accumulate without cleanup). Should be "enforce".
pruneAfter: Missing or > 30d = INFO. Recommended: "7d" to "14d".
maxEntries: Missing or > 200 = INFO. Default is 500, reasonable personal value is 50-100.
maxDiskBytes: Missing = INFO. Recommended: set a cap like "100mb".

4. Compaction Config

Check agents.defaults.compaction in openclaw.json:

mode: Should be "safeguard" (default, safe). Note if missing.
reserveTokensFloor: Missing = WARNING. Without this buffer, context can overflow before compaction triggers. Recommended: 20000.
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:

Session model drift: List any sessions whose model field differs from the configured default. Particularly check channel sessions (telegram:, feishu:).
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).
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.
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.
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:

Orphan JSONL files: Files in directory but not referenced in sessions.json. Calculate total size.
Zombie session entries: Entries in sessions.json pointing to non-existent JSONL files.
Empty JSONL files: Referenced files that are 0 bytes.
Deleted file accumulation: *.deleted.* files that can be cleaned up. Calculate total size.
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:

Duplicate enabled jobs: Jobs with identical name + schedule + enabled: true. Flag as WARNING with dedup suggestion.
Disabled job accumulation: Count enabled: false jobs. More than 10 = INFO (suggest cleanup if user confirms they're not needed).
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.
Cron runs directory: Check $CRON_DIR/runs/ for accumulated run logs. Count and total size.
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:

Feishu groupPolicy: "open" means any Feishu group can interact = CRITICAL.
Feishu/Telegram allowFrom: ["*"] means no restriction = WARNING.
Telegram requireMention: false on groups = WARNING (bot responds to every message).
Gateway auth mode: Read gateway.auth.mode from config. "token" is good, "none" = CRITICAL.
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/).
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 " | gr

oc-doctor