OpenClaw 2.0 Fleet Migration: What Actually Broke

Upgrading a single OpenClaw instance is one thing, but doing it for a fleet of live clients means every breakage multiplies. One team spent a full day migrating to OpenClaw 2.0 and shared the sharpest edges. Here's what actually broke and how to avoid it.

Config Schema Got Stricter

In 2.0, the config schema is stricter, and several fields moved (env keys, TTS, media models). The biggest trap: doctor --fix silently deletes unknown fields. If your model key is in an area that's now deprecated, it can vanish along with those fields. The team rewrote configs by hand before running doctor to avoid losing keys.

External Plugins Break the Gateway

WhatsApp, Brave, Discord, and Perplexity are no longer in the core image; they're external plugins. If your config still references them, the gateway never becomes ready, the container enters a restart loop, and from the outside it looks like a 502. Simply adding the plugins to the image isn't enough because capability consent is tied to the specific machine, and doctor doesn't accept it. The only working approach is running openclaw plugins install ... --accept-capabilities as a separate step.

Device Pairing: Cloudflare Headers Break Locality

The webchat started throwing PAIRING_REQUIRED. The root cause: 2.0 only trusts requests from loopback without any forwarded headers. Not setting them in nginx isn't enough—Cloudflare sends its own headers, so you have to explicitly null them in nginx. This looked like a broken token but was actually a conflict between Cloudflare, nginx, and OpenClaw's locality logic.

Perplexity Auto-Loads Unwanted

Perplexity will auto-load if it detects an OpenRouter key, then demands consent even if you don't want the plugin. Setting enabled: false doesn't help; you must use plugins.deny to block it.

Takeaway: Favor Uptime Over Features

The ending principle: it's better to temporarily lose web search or a single channel than to take the whole agent down with a 502. Plan for multiple breakages and test each component individually.

This is based on a real migration report from a cloud platform hosting OpenClaw for clients. If you're planning an upgrade, read the source for more details and community insights.