> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Doctor

> openclaw doctor — the repair and migration tool: what it checks, how to run it safely in automation, and the config migrations it applies.

# Doctor

`openclaw doctor` is the repair and migration tool. It validates and normalises config, migrates legacy state, checks gateway, channel, and model-auth health, and offers actionable fixes. Run it after every install, upgrade, or config change.

## Quick start

```bash theme={"dark"}
openclaw doctor
```

Interactive mode prompts before applying anything. To review the current config first:

```bash theme={"dark"}
cat ~/.openclaw/openclaw.json
```

## Modes

| Command | Behaviour |
| - | - |
| `openclaw doctor` | Interactive — prompts before each fix |
| `openclaw doctor --yes` | Accept default repair prompts without asking (includes restart/service/sandbox steps) |
| `openclaw doctor --repair` | Apply recommended repairs without prompts (repairs plus safe restarts) |
| `openclaw doctor --repair --force` | Also apply aggressive repairs (overwrites custom supervisor configs) |
| `openclaw doctor --non-interactive` | No prompts; only safe migrations (config normalisation plus on-disk state moves) |
| `openclaw doctor --deep` | Scan system services for extra gateway installs (launchd/systemd/schtasks) |

> [!TIP]
>
> Use `--non-interactive` in CI or scripts — it applies only the safe migrations and skips anything that needs human confirmation. Use `--repair` when you want it to actually fix and restart unattended.

## What it checks

> [accordion] Config and state
>
> * Config normalisation for legacy value shapes.
> * Legacy config key migrations (see below) — rewrites `~/.openclaw/openclaw.json` to the current schema.
> * Legacy on-disk state migration: sessions, transcripts, agent dir, and WhatsApp (Baileys) auth into the per-agent layout.
> * State integrity and permissions: missing state dir, writability, transcript mismatches, multiple state dirs, cloud-synced state-dir warnings (iCloud), and SD/eMMC-backed state warnings on Linux.
> * Config file permission check (warns if `~/.openclaw/openclaw.json` is group/world readable; offers to tighten to `600`).

> [accordion] Auth and security
>
> * Model auth health: OAuth expiry, optional refresh of expiring tokens, and auth-profile cooldown/disabled reporting.
> * Gateway auth warnings when no `gateway.auth.token` is set on a local gateway (offers to generate one; force with `--generate-gateway-token`).
> * Security warnings for open DM policies without an allowlist.
> * OpenCode Zen provider override warnings (`models.providers.opencode`).

> [accordion] Gateway and services
>
> * Gateway health check with an offer to restart when unhealthy.
> * Service installed but not running; cached launchd label issues.
> * Port collision diagnostics on the default port `18789`.
> * Supervisor config audit (launchd/systemd/schtasks) with optional repair.
> * Runtime best-practice checks: warns when the service runs on **Bun** or a version-managed Node path (nvm, fnm, volta, asdf), which can break WhatsApp/Telegram or fail after upgrades; offers to migrate to a system Node install.
> * systemd linger check on Linux (keeps the gateway alive after logout).
> * Legacy service migration and extra-gateway detection (profile-named services are first-class, not "extra").

> [accordion] Channels, skills, sandbox, workspace
>
> * Channel status warnings (probed from the running gateway).
> * Skills status summary (eligible/missing/blocked).
> * Sandbox image repair when sandboxing is enabled.
> * Hooks model validation (`hooks.gmail.model`) against the catalog and allowlist.
> * Workspace tips: suggests a memory system and a git backup when the workspace is not under version control.
> * Source-install checks: pnpm workspace mismatch, missing UI assets, missing `tsx` binary.

## Config migrations

The gateway auto-runs doctor migrations on startup when it detects a legacy config format, so stale configs are usually repaired without manual intervention. Doctor explains which legacy keys it found, shows the migration, and rewrites the file. Current migrations include:

* `routing.allowFrom` to `channels.whatsapp.allowFrom`
* `routing.groupChat.*` to `channels.*.groups."*".requireMention` / `messages.groupChat.*`
* `routing.queue` to `messages.queue`
* `routing.bindings` to top-level `bindings`
* `routing.agents` / `routing.defaultAgentId` to `agents.list` plus `agents.list[].default`
* `routing.agentToAgent` to `tools.agentToAgent`
* `identity` to `agents.list[].identity`
* `agent.*` to `agents.defaults` plus `tools.*`
* `agent.model` / `allowedModels` / `modelAliases` / `modelFallbacks` to `agents.defaults.models` plus `agents.defaults.model.primary/fallbacks`
* `browser.ssrfPolicy.allowPrivateNetwork` to `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`

> [!NOTE]
>
> WhatsApp auth state is intentionally migrated **only** via `openclaw doctor`, not automatically on startup. If WhatsApp shows as logged out after an upgrade, run doctor.

## After a bad upgrade

If a tool refuses to run and asks you to run doctor, you have a deprecated config key. Run `openclaw doctor` (or `--repair`) to migrate it. If channels stopped working after switching the runtime, check the Bun-vs-Node warning — WhatsApp and Telegram require Node.

***

**Related:** [Upgrading](https://docs.wednesdayai.dev/next/admin/upgrading.md) · [Troubleshooting](https://docs.wednesdayai.dev/next/admin/troubleshooting.md) · [Health checks](https://docs.wednesdayai.dev/next/admin/gateway/health-checks.md) · [Multi-gateway](https://docs.wednesdayai.dev/next/admin/multi-gateway.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.