oc-doctor

# 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...

# oc-doctor

[English](README.md) | [中文](README.zh-CN.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform: macOS | Linux | Windows (WSL)](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows%20(WSL)-lightgrey.svg)](https://github.com/bryant24hao/oc-doctor)

> One command to diagnose your entire OpenClaw setup. Finds problems, explains impact, offers fixes.

<p align="center">
  <img src="assets/demo.svg" alt="oc-doctor demo report" width="800">
</p>

A Claude Code / OpenClaw skill that runs **11 diagnostic sections** on your local OpenClaw installation and generates a structured health report with `CRITICAL` / `WARNING` / `INFO` findings — then offers to fix them interactively, in your language.

## Why

Midnight. Your Telegram bot is responding to every message in a group because `requireMention` was set to `false` weeks ago and nobody noticed. It keeps "forgetting" conversations — turns out a model swap left `contextTokens` at 272k on a 200k model. And now Gateway is down because two processes are fighting over the same port.

You spend two hours digging through config files, grepping logs, searching GitHub Issues. You fix three things but have no idea what else is lurking.

**With oc-doctor, one command finds all of it in 60 seconds — and fixes it in 30 more.**

```
/oc-doctor
→ 12 findings: 1 CRITICAL, 4 WARNING, 7 INFO
→ "Fix all?" → Yes
→ Done. Security patched, models aligned, 282 MB cache cleared, dead files cleaned.
```

What used to take hours of manual troubleshooting now takes 2 minutes. Run it weekly — like a health check for your OpenClaw setup. ([Full story](docs/user-story.en.md))

## Highlights

- **11 diagnostic sections** covering installation, config, sessions, cron, security, resources, gateway, and system instructions
- **Interactive one-click fixes** — batch-fix WARNINGs, confirm CRITICALs individually
- **Cross-reference integrity** — detects when AGENTS.md references files tha...