{
  "title": "Doctor",
  "content": "`openclaw doctor` is the repair + migration tool for OpenClaw. It fixes stale\nconfig/state, checks health, and provides actionable repair steps.\n\n### Headless / automation\n\nAccept defaults without prompting (including restart/service/sandbox repair steps when applicable).\n\nApply recommended repairs without prompting (repairs + restarts where safe).\n\nApply aggressive repairs too (overwrites custom supervisor configs).\n\nRun without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.\nLegacy state migrations run automatically when detected.\n\nScan system services for extra gateway installs (launchd/systemd/schtasks).\n\nIf you want to review changes before writing, open the config file first:\n\n## What it does (summary)\n\n* Optional pre-flight update for git installs (interactive only).\n* UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).\n* Health check + restart prompt.\n* Skills status summary (eligible/missing/blocked).\n* Config normalization for legacy values.\n* OpenCode Zen provider override warnings (`models.providers.opencode`).\n* Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).\n* State integrity and permissions checks (sessions, transcripts, state dir).\n* Config file permission checks (chmod 600) when running locally.\n* Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.\n* Extra workspace dir detection (`~/openclaw`).\n* Sandbox image repair when sandboxing is enabled.\n* Legacy service migration and extra gateway detection.\n* Gateway runtime checks (service installed but not running; cached launchd label).\n* Channel status warnings (probed from the running gateway).\n* Supervisor config audit (launchd/systemd/schtasks) with optional repair.\n* Gateway runtime best-practice checks (Node vs Bun, version-manager paths).\n* Gateway port collision diagnostics (default `18789`).\n* Security warnings for open DM policies.\n* Gateway auth warnings when no `gateway.auth.token` is set (local mode; offers token generation).\n* systemd linger check on Linux.\n* Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).\n* Writes updated config + wizard metadata.\n\n## Detailed behavior and rationale\n\n### 0) Optional update (git installs)\n\nIf this is a git checkout and doctor is running interactively, it offers to\nupdate (fetch/rebase/build) before running doctor.\n\n### 1) Config normalization\n\nIf the config contains legacy value shapes (for example `messages.ackReaction`\nwithout a channel-specific override), doctor normalizes them into the current\nschema.\n\n### 2) Legacy config key migrations\n\nWhen the config contains deprecated keys, other commands refuse to run and ask\nyou to run `openclaw doctor`.\n\n* Explain which legacy keys were found.\n* Show the migration it applied.\n* Rewrite `~/.openclaw/openclaw.json` with the updated schema.\n\nThe Gateway also auto-runs doctor migrations on startup when it detects a\nlegacy config format, so stale configs are repaired without manual intervention.\n\n* `routing.allowFrom` → `channels.whatsapp.allowFrom`\n* `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups.\"*\".requireMention`\n* `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`\n* `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`\n* `routing.queue` → `messages.queue`\n* `routing.bindings` → top-level `bindings`\n* `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`\n* `routing.agentToAgent` → `tools.agentToAgent`\n* `routing.transcribeAudio` → `tools.media.audio.models`\n* `bindings[].match.accountID` → `bindings[].match.accountId`\n* `identity` → `agents.list[].identity`\n* `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)\n* `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`\n  → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`\n\n### 2b) OpenCode Zen provider overrides\n\nIf you’ve added `models.providers.opencode` (or `opencode-zen`) manually, it\noverrides the built-in OpenCode Zen catalog from `@mariozechner/pi-ai`. That can\nforce every model onto a single API or zero out costs. Doctor warns so you can\nremove the override and restore per-model API routing + costs.\n\n### 3) Legacy state migrations (disk layout)\n\nDoctor can migrate older on-disk layouts into the current structure:\n\n* Sessions store + transcripts:\n  * from `~/.openclaw/sessions/` to `~/.openclaw/agents/<agentId>/sessions/`\n* Agent dir:\n  * from `~/.openclaw/agent/` to `~/.openclaw/agents/<agentId>/agent/`\n* WhatsApp auth state (Baileys):\n  * from legacy `~/.openclaw/credentials/*.json` (except `oauth.json`)\n  * to `~/.openclaw/credentials/whatsapp/<accountId>/...` (default account id: `default`)\n\nThese migrations are best-effort and idempotent; doctor will emit warnings when\nit leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates\nthe legacy sessions + agent dir on startup so history/auth/models land in the\nper-agent path without a manual doctor run. WhatsApp auth is intentionally only\nmigrated via `openclaw doctor`.\n\n### 4) State integrity checks (session persistence, routing, and safety)\n\nThe state directory is the operational brainstem. If it vanishes, you lose\nsessions, credentials, logs, and config (unless you have backups elsewhere).\n\n* **State dir missing**: warns about catastrophic state loss, prompts to recreate\n  the directory, and reminds you that it cannot recover missing data.\n* **State dir permissions**: verifies writability; offers to repair permissions\n  (and emits a `chown` hint when owner/group mismatch is detected).\n* **Session dirs missing**: `sessions/` and the session store directory are\n  required to persist history and avoid `ENOENT` crashes.\n* **Transcript mismatch**: warns when recent session entries have missing\n  transcript files.\n* **Main session “1-line JSONL”**: flags when the main transcript has only one\n  line (history is not accumulating).\n* **Multiple state dirs**: warns when multiple `~/.openclaw` folders exist across\n  home directories or when `OPENCLAW_STATE_DIR` points elsewhere (history can\n  split between installs).\n* **Remote mode reminder**: if `gateway.mode=remote`, doctor reminds you to run\n  it on the remote host (the state lives there).\n* **Config file permissions**: warns if `~/.openclaw/openclaw.json` is\n  group/world readable and offers to tighten to `600`.\n\n### 5) Model auth health (OAuth expiry)\n\nDoctor inspects OAuth profiles in the auth store, warns when tokens are\nexpiring/expired, and can refresh them when safe. If the Anthropic Claude Code\nprofile is stale, it suggests running `claude setup-token` (or pasting a setup-token).\nRefresh prompts only appear when running interactively (TTY); `--non-interactive`\nskips refresh attempts.\n\nDoctor also reports auth profiles that are temporarily unusable due to:\n\n* short cooldowns (rate limits/timeouts/auth failures)\n* longer disables (billing/credit failures)\n\n### 6) Hooks model validation\n\nIf `hooks.gmail.model` is set, doctor validates the model reference against the\ncatalog and allowlist and warns when it won’t resolve or is disallowed.\n\n### 7) Sandbox image repair\n\nWhen sandboxing is enabled, doctor checks Docker images and offers to build or\nswitch to legacy names if the current image is missing.\n\n### 8) Gateway service migrations and cleanup hints\n\nDoctor detects legacy gateway services (launchd/systemd/schtasks) and\noffers to remove them and install the OpenClaw service using the current gateway\nport. It can also scan for extra gateway-like services and print cleanup hints.\nProfile-named OpenClaw gateway services are considered first-class and are not\nflagged as \"extra.\"\n\n### 9) Security warnings\n\nDoctor emits warnings when a provider is open to DMs without an allowlist, or\nwhen a policy is configured in a dangerous way.\n\n### 10) systemd linger (Linux)\n\nIf running as a systemd user service, doctor ensures lingering is enabled so the\ngateway stays alive after logout.\n\n### 11) Skills status\n\nDoctor prints a quick summary of eligible/missing/blocked skills for the current\nworkspace.\n\n### 12) Gateway auth checks (local token)\n\nDoctor warns when `gateway.auth` is missing on a local gateway and offers to\ngenerate a token. Use `openclaw doctor --generate-gateway-token` to force token\ncreation in automation.\n\n### 13) Gateway health check + restart\n\nDoctor runs a health check and offers to restart the gateway when it looks\nunhealthy.\n\n### 14) Channel status warnings\n\nIf the gateway is healthy, doctor runs a channel status probe and reports\nwarnings with suggested fixes.\n\n### 15) Supervisor config audit + repair\n\nDoctor checks the installed supervisor config (launchd/systemd/schtasks) for\nmissing or outdated defaults (e.g., systemd network-online dependencies and\nrestart delay). When it finds a mismatch, it recommends an update and can\nrewrite the service file/task to the current defaults.\n\n* `openclaw doctor` prompts before rewriting supervisor config.\n* `openclaw doctor --yes` accepts the default repair prompts.\n* `openclaw doctor --repair` applies recommended fixes without prompts.\n* `openclaw doctor --repair --force` overwrites custom supervisor configs.\n* You can always force a full rewrite via `openclaw gateway install --force`.\n\n### 16) Gateway runtime + port diagnostics\n\nDoctor inspects the service runtime (PID, last exit status) and warns when the\nservice is installed but not actually running. It also checks for port collisions\non the gateway port (default `18789`) and reports likely causes (gateway already\nrunning, SSH tunnel).\n\n### 17) Gateway runtime best practices\n\nDoctor warns when the gateway service runs on Bun or a version-managed Node path\n(`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram channels require Node,\nand version-manager paths can break after upgrades because the service does not\nload your shell init. Doctor offers to migrate to a system Node install when\navailable (Homebrew/apt/choco).\n\n### 18) Config write + wizard metadata\n\nDoctor persists any config changes and stamps wizard metadata to record the\ndoctor run.\n\n### 19) Workspace tips (backup + memory system)\n\nDoctor suggests a workspace memory system when missing and prints a backup tip\nif the workspace is not already under git.\n\nSee [/concepts/agent-workspace](/concepts/agent-workspace) for a full guide to\nworkspace structure and git backup (recommended private GitHub or GitLab).",
  "code_samples": [
    {
      "code": "### Headless / automation",
      "language": "unknown"
    },
    {
      "code": "Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).",
      "language": "unknown"
    },
    {
      "code": "Apply recommended repairs without prompting (repairs + restarts where safe).",
      "language": "unknown"
    },
    {
      "code": "Apply aggressive repairs too (overwrites custom supervisor configs).",
      "language": "unknown"
    },
    {
      "code": "Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.\nLegacy state migrations run automatically when detected.",
      "language": "unknown"
    },
    {
      "code": "Scan system services for extra gateway installs (launchd/systemd/schtasks).\n\nIf you want to review changes before writing, open the config file first:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Quick start",
      "id": "quick-start"
    },
    {
      "level": "h3",
      "text": "Headless / automation",
      "id": "headless-/-automation"
    },
    {
      "level": "h2",
      "text": "What it does (summary)",
      "id": "what-it-does-(summary)"
    },
    {
      "level": "h2",
      "text": "Detailed behavior and rationale",
      "id": "detailed-behavior-and-rationale"
    },
    {
      "level": "h3",
      "text": "0) Optional update (git installs)",
      "id": "0)-optional-update-(git-installs)"
    },
    {
      "level": "h3",
      "text": "1) Config normalization",
      "id": "1)-config-normalization"
    },
    {
      "level": "h3",
      "text": "2) Legacy config key migrations",
      "id": "2)-legacy-config-key-migrations"
    },
    {
      "level": "h3",
      "text": "2b) OpenCode Zen provider overrides",
      "id": "2b)-opencode-zen-provider-overrides"
    },
    {
      "level": "h3",
      "text": "3) Legacy state migrations (disk layout)",
      "id": "3)-legacy-state-migrations-(disk-layout)"
    },
    {
      "level": "h3",
      "text": "4) State integrity checks (session persistence, routing, and safety)",
      "id": "4)-state-integrity-checks-(session-persistence,-routing,-and-safety)"
    },
    {
      "level": "h3",
      "text": "5) Model auth health (OAuth expiry)",
      "id": "5)-model-auth-health-(oauth-expiry)"
    },
    {
      "level": "h3",
      "text": "6) Hooks model validation",
      "id": "6)-hooks-model-validation"
    },
    {
      "level": "h3",
      "text": "7) Sandbox image repair",
      "id": "7)-sandbox-image-repair"
    },
    {
      "level": "h3",
      "text": "8) Gateway service migrations and cleanup hints",
      "id": "8)-gateway-service-migrations-and-cleanup-hints"
    },
    {
      "level": "h3",
      "text": "9) Security warnings",
      "id": "9)-security-warnings"
    },
    {
      "level": "h3",
      "text": "10) systemd linger (Linux)",
      "id": "10)-systemd-linger-(linux)"
    },
    {
      "level": "h3",
      "text": "11) Skills status",
      "id": "11)-skills-status"
    },
    {
      "level": "h3",
      "text": "12) Gateway auth checks (local token)",
      "id": "12)-gateway-auth-checks-(local-token)"
    },
    {
      "level": "h3",
      "text": "13) Gateway health check + restart",
      "id": "13)-gateway-health-check-+-restart"
    },
    {
      "level": "h3",
      "text": "14) Channel status warnings",
      "id": "14)-channel-status-warnings"
    },
    {
      "level": "h3",
      "text": "15) Supervisor config audit + repair",
      "id": "15)-supervisor-config-audit-+-repair"
    },
    {
      "level": "h3",
      "text": "16) Gateway runtime + port diagnostics",
      "id": "16)-gateway-runtime-+-port-diagnostics"
    },
    {
      "level": "h3",
      "text": "17) Gateway runtime best practices",
      "id": "17)-gateway-runtime-best-practices"
    },
    {
      "level": "h3",
      "text": "18) Config write + wizard metadata",
      "id": "18)-config-write-+-wizard-metadata"
    },
    {
      "level": "h3",
      "text": "19) Workspace tips (backup + memory system)",
      "id": "19)-workspace-tips-(backup-+-memory-system)"
    }
  ],
  "url": "llms-txt#doctor",
  "links": []
}