Upgrading / Migrating
Post-upgrade checklist and breaking config migrations
Post-upgrade checklist and breaking config migrations
OpenClaw releases can include breaking configuration moves. This guide keeps upgrades predictable: back up, upgrade, migrate config with openclaw doctor --fix, and verify the gateway comes up cleanly.
If you only remember one thing: after any upgrade, run openclaw doctor --fix.
Page scope (upgrade niche): This page is for post-install upgrades, migrations, and breaking config changes. For brand-new installation steps use Installation. For full chronological release details use Releases.
openclaw backup createopenclaw updateopenclaw doctor --fixopenclaw gateway restart then openclaw doctorAfter that, if you use channel plugins (WhatsApp/Telegram/Discord/etc.), re-run your setup wizard steps if needed.
These are frequent “why did it break?” upgrade items. In many cases, openclaw doctor --fix migrates automatically—still verify your resulting config paths.
x_search: migrate from legacy core tools.web.x_search.* to plugins.entries.xai.config.xSearch.*; auth standardizes on plugins.entries.xai.config.webSearch.apiKey / XAI_API_KEY.web_fetch: migrate from tools.web.fetch.firecrawl.* to plugins.entries.firecrawl.config.webFetch.*.exec host=node; pairing and trusted-proxy rules affect which requests become allowed.For full context and additional breaking items, see Releases & Changelog.
Use this table when jumping across versions and you need a quick “what should I check?” list.
| Target version | What to verify | Command / action |
|---|---|---|
| v2026.4.2 | xAI x_search and Firecrawl web_fetch config paths moved to plugin-owned keys. |
openclaw doctor --fix, then verify plugin path keys in config. |
| v2026.3.31 | Node exec behavior and gateway trust/pairing rules tightened; install scanning fails closed by default. | Re-check node workflows and pairing/trust settings; use dangerous install override only if intentional. |
| v2026.3.28 | Qwen portal OAuth removed; older legacy config keys may no longer auto-migrate. | Move Qwen auth to Model Studio and run openclaw doctor + openclaw doctor --fix. |
Need deeper details? See latest breaking changes, v2026.3.31 breaking changes, and v2026.3.28 breaking changes.
openclaw doctor — health checks and reportingopenclaw doctor --fix — auto-migrate common issuesopenclaw gateway restart — apply changes safelyopenclaw --version — include version when asking for helpStart with Troubleshooting and the FAQ for symptoms like gateway token errors, startup failures, and missing browser integration.
When reporting an issue, include the output of:
openclaw --version
openclaw doctorRun openclaw doctor --fix, then openclaw gateway restart, then openclaw doctor.
x_search in v2026.4.2?Move from tools.web.x_search.* to plugins.entries.xai.config.xSearch.* and verify plugins.entries.xai.config.webSearch.apiKey / XAI_API_KEY.
web_fetch in v2026.4.2?Move from tools.web.fetch.firecrawl.* to plugins.entries.firecrawl.config.webFetch.*. Use openclaw doctor --fix for automatic migration where possible.
Node shell execution routes through exec host=node with tighter trust/pairing behavior; re-check workflows that relied on older wrapper behavior.
Use Troubleshooting, check FAQ, and include openclaw --version plus openclaw doctor output in bug reports.