Gateway
Doctor
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
| Page | Read it when |
|---|---|
| Run doctor | Run the command, pick automation flags, and read the read-only lint report. |
| What doctor checks | A summary of every repair, migration, and health check, grouped by area. |
| Config and migration repairs | Checks 0-2: config normalization, the legacy config key table, and update-time schema publication. |
| Provider and route repairs | Checks 2b-2g: provider overrides, browser and Chrome MCP readiness, OAuth TLS, and route cleanup. |
| State, session, and plugin repairs | Checks 3-7b: disk layout, cron store, session integrity, model auth, sandbox, and plugin installs. |
| Gateway, service, and security checks | Checks 8-17: service migrations, pairing, security warnings, workspace status, auth, health, and supervisors. |
| Workspace tips and Dreams UI actions | Checks 18-20, plus the Control UI Dreams backfill, reset, and clear actions. |
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
Was this useful?
