Doctor

text

Copy

openclaw doctor

Health checks + quick fixes for the gateway and channels.

Related:

• Troubleshooting: Troubleshooting
• Security audit: Security

Examples

bash
Copy
openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
openclaw doctor --repair --non-interactive
openclaw doctor --generate-gateway-token

Options

• text

  Copy

  --no-workspace-suggestions
  : disable workspace memory/search suggestions
• text

  Copy

  --yes
  : accept defaults without prompting
• text

  Copy

  --repair
  : apply recommended repairs without prompting
• text

  Copy

  --fix
  : alias for
  text

  Copy

  --repair
• text

  Copy

  --force
  : apply aggressive repairs, including overwriting custom service config when needed
• text

  Copy

  --non-interactive
  : run without prompts; safe migrations only
• text

  Copy

  --generate-gateway-token
  : generate and configure a gateway token
• text

  Copy

  --deep
  : scan system services for extra gateway installs

Notes:

• Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and
  text

  Copy

  --non-interactive
  is not set. Headless runs (cron, Telegram, no terminal) will skip prompts.
• Performance: non-interactive
  text

  Copy

  doctor
  runs skip eager plugin loading so headless health checks stay fast. Interactive sessions still fully load plugins when a check needs their contribution.
• text

  Copy

  --fix
  (alias for
  text

  Copy

  --repair
  ) writes a backup to
  text

  Copy

  ~/.openclaw/openclaw.json.bak
  and drops unknown config keys, listing each removal.
• State integrity checks now detect orphan transcript files in the sessions directory. Archiving them as
  text

  Copy

  .deleted.<timestamp>
  requires an interactive confirmation;
  text

  Copy

  --fix
  ,
  text

  Copy

  --yes
  , and headless runs leave them in place.
• Doctor also scans
  text

  Copy

  ~/.openclaw/cron/jobs.json
  (or
  text

  Copy

  cron.store
  ) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.
• Doctor repairs missing bundled plugin runtime dependencies without writing into packaged global installs. For root-owned npm installs or hardened systemd units, set
  text

  Copy

  OPENCLAW_PLUGIN_STAGE_DIR
  to a writable directory such as
  text

  Copy

  /var/lib/openclaw/plugin-runtime-deps
  ; it can also be a path-list such as
  text

  Copy

  /opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps
  , where earlier roots are read-only lookup layers and the final root is the repair target.
• Doctor repairs stale plugin config by removing missing plugin ids from
  text

  Copy

  plugins.allow
  /
  text

  Copy

  plugins.entries
  , plus matching dangling channel config, heartbeat targets, and channel model overrides when plugin discovery is healthy.
• Doctor quarantines invalid plugin config by disabling the affected
  text

  Copy

  plugins.entries.<id>
  entry and removing its invalid
  text

  Copy

  config
  payload. Gateway startup already skips only that bad plugin so other plugins and channels can keep running.
• Set
  text

  Copy

  OPENCLAW_SERVICE_REPAIR_POLICY=external
  when another supervisor owns the gateway lifecycle. Doctor still reports gateway/service health and applies non-service repairs, but skips service install/start/restart/bootstrap and legacy service cleanup.
• On Linux, doctor ignores inactive extra gateway-like systemd units and does not rewrite command/entrypoint metadata for a running systemd gateway service during repair. Stop the service first or use
  text

  Copy

  openclaw gateway install --force
  when you intentionally want to replace the active launcher.
• Doctor auto-migrates legacy flat Talk config (
  text

  Copy

  talk.voiceId
  ,
  text

  Copy

  talk.modelId
  , and friends) into
  text

  Copy

  talk.provider
  +
  text

  Copy

  talk.providers.<provider>
  .
• Repeat
  text

  Copy

  doctor --fix
  runs no longer report/apply Talk normalization when the only difference is object key order.
• Doctor includes a memory-search readiness check and can recommend
  text

  Copy

  openclaw configure --section model
  when embedding credentials are missing.
• Doctor warns when no command owner is configured. The command owner is the human operator account allowed to run owner-only commands and approve dangerous actions. DM pairing only lets someone talk to the bot; if you approved a sender before first-owner bootstrap existed, set
  text

  Copy

  commands.ownerAllowFrom
  explicitly.
• Doctor warns when Codex-mode agents are configured and personal Codex CLI assets exist in the operator's Codex home. Local Codex app-server launches use isolated per-agent homes, so use
  text

  Copy

  openclaw migrate codex --dry-run
  to inventory assets that should be promoted deliberately.
• If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (
  text

  Copy

  install Docker
  or
  text

  Copy

  openclaw config set agents.defaults.sandbox.mode off
  ).
• If
  text

  Copy

  gateway.auth.token
  /
  text

  Copy

  gateway.auth.password
  are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials.
• If channel SecretRef inspection fails in a fix path, doctor continues and reports a warning instead of exiting early.
• Telegram
  text

  Copy

  allowFrom
  username auto-resolution (
  text

  Copy

  doctor --fix
  ) requires a resolvable Telegram token in the current command path. If token inspection is unavailable, doctor reports a warning and skips auto-resolution for that pass.

macOS:

text

Copy

launchctl

env overrides

If you previously ran

(or ), that value overrides your config file and can cause persistent “unauthorized” errors.

bash
Copy
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

Related

• CLI reference
• Gateway doctor