Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
openclaw doctor

Health checks + quick fixes for the gateway and channels. Related:

​
Examples

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

​
Options

  • --no-workspace-suggestions: disable workspace memory/search suggestions
  • --yes: accept defaults without prompting
  • --repair: apply recommended repairs without prompting
  • --fix: alias for --repair
  • --force: apply aggressive repairs, including overwriting custom service config when needed
  • --non-interactive: run without prompts; safe migrations only
  • --generate-gateway-token: generate and configure a gateway token
  • --deep: scan system services for extra gateway installs
Notes:
  • Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and --non-interactive is not set. Headless runs (cron, Telegram, no terminal) will skip prompts.
  • Performance: non-interactive doctor runs skip eager plugin loading so headless health checks stay fast. Interactive sessions still fully load plugins when a check needs their contribution.
  • --fix (alias for --repair) writes a backup to ~/.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 .deleted.<timestamp> requires an interactive confirmation; --fix, --yes, and headless runs leave them in place.
  • Doctor also scans ~/.openclaw/cron/jobs.json (or 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 OPENCLAW_PLUGIN_STAGE_DIR to a writable directory such as /var/lib/openclaw/plugin-runtime-deps; it can also be a path-list such as /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 plugins.allow/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 plugins.entries.<id> entry and removing its invalid config payload. Gateway startup already skips only that bad plugin so other plugins and channels can keep running.
  • Set 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 openclaw gateway install --force when you intentionally want to replace the active launcher.
  • Doctor auto-migrates legacy flat Talk config (talk.voiceId, talk.modelId, and friends) into talk.provider + talk.providers.<provider>.
  • Repeat 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 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 commands.ownerAllowFrom explicitly.
  • If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (install Docker or openclaw config set agents.defaults.sandbox.mode off).
  • If gateway.auth.token/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 allowFrom username auto-resolution (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: launchctl env overrides

If you previously ran launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (or ...PASSWORD), that value overrides your config file and can cause persistent “unauthorized” errors. 
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD