openclaw doctor: Keeping Your Multi-Agent Setup Healthy

The Problem With Growing Agent Setups

A single AI agent is straightforward to manage. But once you're running multiple agents, the surface area for silent failures grows:

These problems aren't loud. No crash, no red error. The agent just becomes... less reliable than it was.

That's where `openclaw doctor` comes in.

---

What Does openclaw doctor Do?

The `doctor` command is a combined diagnosis, repair, and migration pipeline for your OpenClaw setup. It systematically checks:

Just run it:

```bash

openclaw doctor

```

Output is color-coded: green (OK), yellow (warning), red (critical problem).

---

The Three Most Useful Flags

1. `--fix` — Automatic Repair

This is the most useful flag in day-to-day operation. `openclaw doctor --fix` automatically repairs found issues:

```bash

openclaw doctor --fix

```

What gets fixed automatically:

Safety net: Before any repair, `--fix` automatically creates a backup of `~/.openclaw/openclaw.json`. You can always roll back.

When to use it: After OpenClaw updates, after config changes, when an agent starts misbehaving.

2. `--deep` — Deep Scan

```bash

openclaw doctor --deep

```

Additionally checks system services (e.g. whether the Gateway is correctly configured as a systemd service) and runs live probes for every channel.

In our 6-agent installation: `--deep` takes around 45 seconds, but it's the most reliable way to catch issues before they turn into actual outages.

3. `--non-interactive` — For Automation

```bash

openclaw doctor --fix --non-interactive

```

Skips all confirmation dialogs and applies only safe repairs. Exactly what you want in a cron job.

---

openclaw status vs. openclaw health vs. openclaw doctor

These three commands get confused a lot. Here's the difference:

| Command | Purpose | When to use |

|---------|---------|-------------|

| `openclaw status` | Current state snapshot | Quick check: "Is everything running?" |

| `openclaw health --json` | Detailed health report as JSON | Monitoring, alerting, dashboards |

| `openclaw doctor` | Diagnosis + optional repair | After updates, when something's off |

For quick triage:

```bash

# Quick status check

openclaw status

# More detail + channel probes

openclaw status --deep

# As JSON for further processing

openclaw health --json | jq '.channels'

```

---

How We Use doctor in Our 6-Agent Setup

We run 6 agents on a Hetzner server, each in its own Docker container. An agent that silently fails costs time — we often don't notice it for hours.

Our solution: `openclaw doctor` runs automatically as an OpenClaw cron job, every morning at 06:30.

The cron setup looks roughly like this:

```json

{

"schedule": { "kind": "cron", "expr": "30 6 * * *", "tz": "Europe/Berlin" },

"payload": {

"kind": "agentTurn",

"message": "Run 'openclaw doctor --fix --non-interactive' on all agent containers and report any issues found. If any agent has a critical problem, alert via Telegram immediately."

},

"sessionTarget": "isolated"

}

```

What happens: Every morning at 6:30 Berlin time, Sam checks all 6 agent containers. If an issue is found, a Telegram message arrives: "Peter container: skill 'coding-agent' not found — please check."

We know before the first workday starts whether everything is running.

---

Gateway Token Regeneration

A common issue after reinstalls or container migrations: the Gateway token isn't configured or is invalid.

```bash

openclaw doctor --generate-gateway-token

```

This flag forces generation of a new Gateway token. Afterward, restart the Gateway:

```bash

openclaw gateway restart

```

---

Security Checks With doctor

`openclaw doctor` also checks basic security aspects — for example whether the Gateway is binding to a LAN interface that shouldn't be externally exposed. For a dedicated security audit there's also:

```bash

openclaw security audit --deep

```

This is especially important when you're adding a new channel (e.g. WhatsApp) or have moved the server.

---

When doctor Itself Can't Help

In rare cases the setup is damaged enough that doctor can't make progress. That's when `--force` helps:

```bash

openclaw doctor --fix --force

```

Warning: `--force` also overwrites custom supervisor configurations. Only use it when you're certain the service configuration is genuinely broken — and manually back things up before running it.

---

Our Maintenance Routine

For reference — this is what we do every month:

1. Daily (automated): `openclaw doctor --fix --non-interactive` via cron

2. Weekly (manual): `openclaw doctor --deep` — thorough check including system services

3. After every update: `openclaw doctor --fix` — migrates stale configuration

4. Before major changes: Manual backup of `~/.openclaw/` in addition to doctor's automatic backup

With this routine, our 6-agent system has run stably for months — no emergency manual interventions needed.

---

The Bottom Line

`openclaw doctor` isn't a "crash fix button." It's prevention. Run regularly — ideally automatically — it keeps your setup clean, migrates config after updates, and warns you before a small problem becomes a big one.

How we built the complete maintenance routine for all 6 agents — including cron configuration, alerting, and container restart policies — is documented in the OpenClaw Setup Playbook.

Fully available in German too. 🇩🇪