ReleaseFebruary 20, 2026

ClawKit Doctor v2.0: 11 Checks, Auto-Fix Mode & Shareable Reports

Doctor v2.0 is a complete rewrite of our environment diagnostic CLI. It now runs 11 checks (up from 5), auto-repairs the most common issues with a single --fix flag, and generates a shareable report URL you can paste directly into a GitHub issue or Discord thread.

Run Doctor (no install required)

npx clawkit-doctor@latest

Add --fix to auto-repair detected issues.

What's New in v2.0

Checks

11 (was 5 in v1)

--fix mode

Auto-repairs 4 common issues

Shareable URL

Base64 report for GitHub/Discord

New checks

Git, Docker, token alignment, lock files, CDP port

Why We Rebuilt It

Doctor v1 shipped 5 basic checks: Node.js version, config directory, config file, permissions, and agent port. It was good enough for initial setup but missed the issues that actually show up on our troubleshooting pages: token mismatches, stale lock files, missing Git/Docker, and zombie processes holding ports.

v2.0 was built by looking at real data — the most-visited troubleshooting pages and the most common errors in the OpenClaw Discord #help channel. Every new check maps directly to a documented error.

All 11 Checks

Node.js version — Ensures you are running v18+

Git in PATH — Git missing causes spawn ENOENT errors in many plugins

Docker in PATH — Required for sandbox mode — warns if absent

Config directory — ~/.openclaw exists and is accessible

Config file validity — Parses clawhub.json and catches syntax errors

Write permissions — Confirms the process can write to ~/.openclaw

Gateway token alignment — Detects auth.token ≠ remote.token and env var overrides

Stale lock files — Finds .lock files that cause "gateway already running" loops

Gateway port 18789 — Confirms whether the gateway process is running

Agent port 3000 — Checks if the local agent is up

Browser CDP port 18800 — Detects stray browser control processes

Auto-Fix Mode

Pass --fix and Doctor will repair issues automatically — no manual config edits required.

Creates missing ~/.openclaw directory

Removes stale session lock files

Aligns mismatched gateway tokens

Fixes directory ownership (macOS/Linux)

Auto-repair everything it can

npx clawkit-doctor@latest --fix

Shareable Report URL

After every run, Doctor generates a URL that encodes your full diagnostic result. Paste it in a GitHub issue or Discord and anyone can instantly see your environment state — no screenshots, no copy-pasting terminal output.

https://getclawkit.com/tools/doctor?r=eyJ0IjoiMjAyNi0wMi0yMFQxMj...

The URL contains only your OS type, Node.js version, and check results. No tokens, no file contents, no personal data.

Upgrading from v1

No action needed. npx clawkit-doctor@latest always runs the latest version. If you had Doctor installed globally, uninstall and re-run with npx:

Uninstall old global version (if needed)

npm uninstall -g clawkit-doctor
npx clawkit-doctor@latest

What's Next

v2.0 establishes the foundation for smarter diagnostics. Coming in future releases:

Auto-generated fix scripts — download a shell script tailored to your specific failures
Plugin health checks — validate Discord, Slack, Telegram plugin configs
Provider connectivity tests — ping OpenAI, Anthropic, Ollama endpoints
Web paste mode — paste an error message on getclawkit.com/tools/doctor and get a direct match to your issue

Issues Doctor v2.0 Catches

Each check links to a dedicated troubleshooting guide:

Run Doctor on Your Machine

No install needed. One command, 11 checks, instant results.

Web Doctor Troubleshooting Docs

← Back to Blog Open Doctor →