ClawKit Doctor

Fast diagnostics and safe auto-repair for OpenClaw environments.

Maintainer: @branzoom

Usage

npx clawkit-doctor@latest

When run without arguments in an interactive terminal, Doctor now shows:

1. language selector (en/zh/ja)
2. welcome menu (quick diagnose / paste error / tutorial / exit)
3. guided recovery loop (y/n solved confirmation)

Common modes

# Diagnose only
npx clawkit-doctor@latest

# Diagnose + safe auto-repair
npx clawkit-doctor@latest --fix

# Paste an error for instant recognition + fix steps
npx clawkit-doctor@latest --paste "Telegram getUpdates conflict 409"

# Continue to full environment checks after paste diagnosis
npx clawkit-doctor@latest --paste "token mismatch" --full

# Language selection
npx clawkit-doctor@latest --lang zh

# Skip 0/1 follow-up prompts
npx clawkit-doctor@latest --no-interactive

# Machine-readable output
npx clawkit-doctor@latest --json

Flags

• --fix: auto-repair supported issues (missing config dir, stale locks, token alignment, permissions)
• --paste "<error text>": detect known issues from pasted logs/errors and show steps
• --full: with --paste, continue into full environment checks
• --lang en|zh|ja: switch UI language
• --no-interactive: disable the y/n resolution follow-up
• --json: print full report JSON for CI/automation
• --quiet: reduce console output
• --no-report: skip shareable report URL
• --help, --version

What it checks

1. Node.js version (v22+ required)
2. Git availability
3. Docker availability
4. OpenClaw config directory (~/.openclaw)
5. Config file syntax (openclaw.json)
6. Directory write permissions
7. Gateway token alignment (auth, remote, env override)
8. Stale lock files under ~/.openclaw/sessions
9. Port 18789 (gateway)
10. Port 3000 (agent)
11. Port 18800 (browser CDP)

Resolution loop (best-practice UX)

When --paste is used in an interactive terminal, Doctor asks:

1. y/n whether the issue is solved (also accepts 1/0 for compatibility)
2. If not solved, reason selection (command, permission, timeout/network, not sure)
3. Provides fallback steps and asks y/n again
4. Only after repeated failure, shows escalation links (issue details, troubleshooting index, contact)

This avoids hard-sell behavior and keeps flow focused on incident recovery.

Built-in links (contextual)

Doctor links users naturally based on state:

• Matched issue details page (/docs/troubleshooting/...)
• Troubleshooting index: https://getclawkit.com/docs/troubleshooting
• Prevention guide (post-resolution): https://getclawkit.com/docs/guides/stable-ops

Maintainer publish

cd packages/clawkit-doctor
npm publish --access public