Doctor

clawdbot doctor is the repair + migration tool for Clawdbot. It runs a quick health check, audits skills, and can migrate deprecated config entries to the new schema.

What it does

Runs a health check and offers to restart the gateway if it looks unhealthy.
Prints a skills status summary (eligible/missing/blocked).
Detects deprecated config keys and offers to migrate them.
Migrates legacy ~/.clawdis/clawdis.json when no Clawdbot config exists.
Checks sandbox Docker images when sandboxing is enabled (offers to build or switch to legacy names).
Detects legacy Clawdis services (launchd/systemd; legacy schtasks for native Windows) and offers to migrate them.
On Linux, checks if systemd user lingering is enabled and can enable it (required to keep the Gateway alive after logout).
Migrates legacy on-disk state layouts (sessions, agentDir, provider auth dirs) into the current per-agent/per-account structure.

Legacy config file migration

If ~/.clawdis/clawdis.json exists and ~/.clawdbot/clawdbot.json does not, doctor will migrate the file and normalize old paths/image names.

Legacy config migrations

When the config contains deprecated keys, other commands will refuse to run and ask you to run clawdbot doctor. Doctor will:

Explain which legacy keys were found.
Show the migration it applied.
Rewrite ~/.clawdbot/clawdbot.json with the updated schema.

The Gateway also auto-runs doctor migrations on startup when it detects a legacy config format, so stale configs are repaired without manual intervention.

Current migrations:

routing.allowFrom → whatsapp.allowFrom
agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agent.models + agent.model.primary/fallbacks + agent.imageModel.primary/fallbacks

Legacy state migrations (disk layout)

Doctor can migrate older on-disk layouts into the current structure:

Sessions store + transcripts:
- from ~/.clawdbot/sessions/ to ~/.clawdbot/agents/<agentId>/sessions/
Agent dir:
- from ~/.clawdbot/agent/ to ~/.clawdbot/agents/<agentId>/agent/
WhatsApp auth state (Baileys):
- from legacy ~/.clawdbot/credentials/*.json (except oauth.json)
- to ~/.clawdbot/credentials/whatsapp/<accountId>/... (default account id: default)

These migrations are best-effort and idempotent; doctor will emit warnings when it leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates the legacy sessions + agent dir on startup so history/auth/models land in the per-agent path without a manual doctor run. WhatsApp auth is intentionally only migrated via clawdbot doctor.

Usage

clawdbot doctor

Headless / automation

clawdbot doctor --yes

Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).

clawdbot doctor --non-interactive

Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.

If you want to review changes before writing, open the config file first:

cat ~/.clawdbot/clawdbot.json

Legacy service migrations

Doctor checks for older Clawdis gateway services (launchd/systemd/schtasks). WSL2 installs use systemd. If found, it offers to remove them and install the Clawdbot service using the current gateway port. Remote mode skips the install step, and Nix mode only reports what it finds.

3.6 KiB Raw Blame History