openclaw doctor is the repair and migration tool for OpenClaw. It fixes stale config/state, checks health, and provides actionable repair steps.
This page is an index. Doctor is documented on seven pages, one per reader job.
Open the page that matches your task.
Doctor pages
Where each section moved
Every section and check title from the previous single-page version keeps its anchor here, so an existing link such as/gateway/doctor#9-security-warnings
still resolves. Each entry points at the page that now holds the content.
- Quick start
- Headless and automation modes
- Schema publication during a 2026.9.2 update
- Read-only lint mode
- What it does (summary)
- Dreams UI backfill and reset
- Detailed behavior and rationale — now five pages, listed above.
- Schema publication during a 2026.9.2 update
- What it does (summary)
- —yes
- —fix
- —lint
- —fix —force
- —non-interactive
- —deep
- Health, UI, and updates
- Config and migrations
- State and integrity
- Gateway, services, and supervisors
- Auth, security, and pairing
- Workspace and shell
- 0. Optional update (git installs)
- 1. Config normalization
- 2. Legacy config key migrations
- 2b. OpenCode provider overrides
- 2c. Browser migration and Chrome MCP readiness
- 2d. OAuth TLS prerequisites
- 2e. Codex OAuth provider overrides
- 2f. Codex route repair
- 2g. Session route cleanup
- 3. Legacy state migrations (disk layout)
- 3a. Legacy plugin manifest migrations
- 3b. Legacy cron store migrations
- 3c. Session lock cleanup
- 3d. Session transcript branch repair
- 4. State integrity checks (session persistence, routing, and safety)
- 5. Model auth health (OAuth expiry)
- 6. Hooks model validation
- 7. Sandbox image repair
- 7b. Plugin install cleanup
- 8. Gateway service migrations and cleanup hints
- 8b. Startup Matrix migration
- 8c. Device pairing and auth drift
- 9. Security warnings
- 10. systemd linger (Linux)
- 11. Workspace status (skills, plugins, and TaskFlows)
- 11b. Bootstrap file size
- 11c. Shell completion
- 11d. Stale channel plugin cleanup
- 11e. Project clone shape
- 12. Gateway auth checks (local token)
- 12b. Read-only SecretRef-aware repairs
- 13. Gateway health check + restart
- 13b. Memory search readiness
- 14. Channel status warnings
- 15. Supervisor config audit + repair
- 16. Gateway runtime + port diagnostics
- 17. Gateway runtime best practices
- 18. Config write + wizard metadata
- 19. Workspace tips (backup + memory system)
- 20. Repointed workspace aliases
Related
- Gateway runbook
- Gateway troubleshooting
openclaw status— local diagnosis and channel probes- Configuration reference — core config keys, defaults, and links to subsystem references