A comprehensive 11-section health check and diagnostic tool for OpenClaw installations that provides interactive one-click fixes for configuration and performance issues.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install oc-doctor
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install oc-doctor using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is OpenClaw Doctor?
OpenClaw Doctor is an essential diagnostic utility designed to maintain the peak performance of your local agent environment. It performs a deep-dive analysis across eleven critical domains, including session management, model alignment, and security configurations. By identifying suboptimal settings and resource bottlenecks, this tool ensures your Openclaw Skills operate reliably and efficiently.
The skill goes beyond simple error reporting by offering a structured health report with severity levels such as CRITICAL, WARNING, and INFO. It empowers developers to resolve complex issues like session bloat, model drift, and gateway misconfigurations through an interactive fix workflow, significantly reducing the manual effort required for system maintenance.
OpenClaw Doctor Use Cases
- Troubleshooting installation failures or gateway connection issues.
- Identifying session bloat and cleaning up orphan JSONL files to reclaim disk space.
- Auditing security settings for Feishu or Telegram gateway integrations to prevent unauthorized access.
- Checking system instruction token budgets to prevent context window overflows during agent interactions.
- Resolving model drift where specific sessions diverge from the globally configured default settings.
How OpenClaw Doctor Works
- The skill auto-detects the OpenClaw home directory and essential configuration paths at runtime without hardcoding locations.
- It executes a sequence of 11 diagnostic checks covering everything from installation versioning to process health and resource usage.
- A structured report is generated, categorizing findings by severity and providing clear impact descriptions for each issue found.
- The agent enters an interactive mode, offering to apply specific fixes such as clearing caches, updating configuration files, or archiving old logs.
- Sensitive information like API keys and passwords are automatically redacted in the output to ensure the report remains secure within the conversation context.
OpenClaw Doctor Setup
To use OpenClaw Doctor, ensure you have the core requirements installed on your macOS or Linux system. The skill relies on standard command-line utilities to parse data.
# Ensure openclaw and jq are available in your PATH
command -v openclaw
command -v jq
# If jq is missing, install it using your package manager
# macOS:
brew install jq
# Linux:
sudo apt install jq
The skill will automatically detect your configuration at $HOME/.openclaw/openclaw.json unless a custom OPENCLAW_HOME environment variable is set.
OpenClaw Doctor Data Schema & Taxonomy
The diagnostic process analyzes the organization of your agent data across several key files and directories to ensure metadata consistency.
| Path Type | Data Source | Purpose |
|---|---|---|
| Configuration | openclaw.json | Main settings for gateway, models, and session maintenance. |
| Registry | sessions.json | The primary index for mapping session keys to JSONL data files. |
| Models | models.json | Local definitions for model context windows and specific overrides. |
| Automation | jobs.json | Storage for cron job schedules, enabled states, and run history. |
| Workspace | *.md files | System instructions and agent personality definitions used for token counting. |
| Logs | gateway.err.log | Captured error output used to diagnose service-level stability. |
OpenClaw Doctor Advanced Features
- Context Budget Mapping: Complements runtime checks by measuring static system instruction token footprints against model context windows.
- Interactive Remediation: Offers one-click batch fixes for WARNING levels while requiring individual confirmation for CRITICAL security changes.
- Forward-Compat Patch Detection: Scans local distribution files for non-standard constants or custom patches that might affect stability.
- Orphan File Reclamation: Automatically identifies and calculates the size of zombie session entries and abandoned atomic-write artifacts.
- Security Hardening: Audits group policies and auth modes, flagging unauthenticated gateways or overly permissive messaging bot configurations.
SKILL.md
Loading
Related Openclaw Skills
E-commerce Product Image Generator
An automated AI skill for generating high-fidelity e-commerce product detail pages and carousel images using Python PIL and image generation protocols.
Daily Tech News Push
A powerful automation skill for Openclaw Skills that aggregates daily tech news and delivers them to Feishu and GetNote.
Inner Mongolia Social Insurance Backpay Calculator
A high-precision tool for calculating Inner Mongolia social insurance backpay including principal, compound interest, and daily late fees.
Shopify Store Manager CLI
A Python-based CLI tool to manage Shopify store resources including products, metaobjects, and content through the official GraphQL API.
OpenClaw Multi-Agent Orchestration
A comprehensive methodology for building and managing hierarchical AI agent teams through backend orchestration and external communication layers.
le2le-blog-writer
A sophisticated AI writing agent that transforms themes or existing text into high-quality, long-form Chinese articles with a rational, human-like perspective.
Featured*
