Upgrading / Migrating

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.

After a large version jump, skim Releases and the breaking changes section for your target tag. Most people run stable GitHub releases; pre-releases are optional until you choose to opt in. Upstream doctor reference: Gateway doctor.

Upgrade checklist

  1. Backup your install: openclaw backup create
  2. Upgrade OpenClaw: openclaw update
  3. Migrate config and repair issues: openclaw doctor --fix
  4. Restart and verify: openclaw gateway restart then openclaw doctor

After that, if you use channel plugins (WhatsApp/Telegram/Discord/etc.), re-run your setup wizard steps if needed.

Upgrading from older April builds? See Since v2026.4.15 — quick delta for the fastest verification checklist.

Breaking migrations (most common)

These are frequent “why did it break?” upgrade items. In many cases, openclaw doctor --fix migrates automatically—still verify your resulting config paths.

  • v2026.4.26 — plugin config/runtime transitions: if you maintain custom plugins, account for deprecating direct config read/write helpers and moving runtime metadata/routing assumptions into manifest contracts.
  • v2026.4.24 — SDK transform path change: if you maintain plugin harness/tool-result rewrites, migrate from Pi-only api.registerEmbeddedExtensionFactory(...) compatibility to api.registerAgentToolResultMiddleware(...) plus the matching contracts.agentToolResultMiddleware declarations.
  • v2026.4.15 — provider + packaging shifts: re-check provider defaults (especially Anthropic/Codex model behavior), Model Auth status surfaces, and plugin packaging assumptions if you depend on custom runtime paths.
  • v2026.4.10 — Exec policy sync: use openclaw exec-policy (show / preset / set) if tools.exec.* and ~/.openclaw/exec-approvals.json drift after upgrades; resolves sync conflicts explicitly.
  • v2026.4.9 — Matrix DM policy: legacy channels.matrix.dm.policy: "trusted" is migrated by openclaw doctor --fix to supported policies (allowlist when allowFrom is set, pairing when empty).
  • v2026.4.5 — legacy public config aliases: keys such as talk.voiceId / talk.apiKey, agents.*.sandbox.perSession, browser.ssrfPolicy.allowPrivateNetwork, hooks.internal.handlers, and channel/group/room allow toggles are removed in favor of canonical paths and enabled. Run openclaw doctor --fix and re-verify openclaw.json.
  • v2026.4.2 — xAI 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.
  • v2026.4.2 — Firecrawl web_fetch: migrate from tools.web.fetch.firecrawl.* to plugins.entries.firecrawl.config.webFetch.*.
  • v2026.3.31 — Nodes / Gateway exec behavior: node shell wrappers were consolidated so node execution uses exec host=node; pairing and trusted-proxy rules affect which requests become allowed.

For full context and additional breaking items, see Releases & Changelog.

Since v2026.4.15 — quick delta

If your environment has been stable since around v2026.4.15, or you are catching up to current stable (v2026.5.18), verify these before/after upgrade. For command-focused checklists per tag, see v2026.5.18, v2026.5.12, v2026.5.7, v2026.5.6, v2026.5.5, v2026.5.4, and v2026.5.3 in the table below.

  • v2026.5.18 — quick checklist: upgrade Node.js to 22.19+; run openclaw doctor --fix; re-test Gateway restarts, Mac Settings (if used), browser dialog flows, Android Talk Mode, plugin build/validate, and Telegram/Discord/Codex paths you rely on.
  • v2026.5.12 — quick checklist: run openclaw doctor --fix; confirm Bedrock/Slack/Vertex (and other externalized) plugins are installed if your config references them; re-test Telegram (polling, group media, cron announce formatting), Codex/OpenAI flows, plugin installs, and rich/card replies in Control UI or WebChat.
  • v2026.5.7 — quick checklist: re-test Telegram/Discord/WhatsApp delivery, confirm owner/admin auth paths (native commands + global memory toggles), and verify cron/session behavior after openclaw doctor --fix.
  • v2026.5.6 — Codex OAuth + fetch hygiene: if you ran openclaw doctor --fix on v2026.5.5 and use ChatGPT/Codex OAuth (openai-codex/*), confirm your default model path still matches what you expect; use upstream Codex OAuth recovery if not. Re-smoke plugin HTTP calls and web-fetch tools after upgrade.
  • v2026.5.5 — reliability sweep: validate channel/session flows you rely on (Feishu topics, LINE DMs, Telegram/Codex progress drafts, Matrix approvals, Discord heartbeats/commands), then spot-check plugin update behavior and status diagnostics. If you use iOS pairing on private LAN or .local, test reconnect behavior explicitly. Re-run your normal smoke suite after openclaw doctor --fix.
  • v2026.5.4 — voice, Windows, plugins: Twilio + realtime Gemini paths for Meet/voice may behave differently (pace, backpressure, barge-in)—re-smoke long calls. On Windows, local gateway loopback bind favors 127.0.0.1; confirm clients still reach the gateway. If config lists official plugins that are not installed, expect install hints—run openclaw doctor --fix and install what you intend to keep. Discord npm plugins with SecretRef contracts should load from packaged dist/; audit openclaw models auth list after upgrade. Slack “progress” drafts: spot-check channels you use.
  • v2026.5.3 — config fail-closed + file transfer: invalid openclaw.json is not silently repaired on startup or hot reload—the gateway can refuse to run until openclaw doctor --fix (plan for a short maintenance window). If you enable the bundled file-transfer tools between paired nodes, review path allowlists and size limits. Unified streaming.mode: "progress" affects several channels—re-test draft/progress UX where you rely on it.
  • Google Meet + realtime voice: meet/session and Talk realtime transport behavior continued to evolve between v2026.4.24 and v2026.4.26; re-run voice and meeting smoke tests.
  • Provider/catalog updates: DeepSeek default shifts from v2026.4.24 plus new bundled Cerebras provider in v2026.4.26 can affect onboarding and model selection.
  • Plugin runtime assumptions: plugin config helper deprecations and manifest-first routing metadata mean custom plugin paths should be reviewed.
  • Migration tooling: prefer openclaw migrate --dry-run and backup-first flow before applying broad config/import changes.
  • SDK compatibility: keep tool-result middleware migration on your checklist if any internal plugins still rely on older transform registration paths.

Upgrade paths by version

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.5.18 Node.js 22.19+ floor, faster Gateway restart ready path, Mac Settings redesign, plugin tooling CLI, browser dialog handling, Android Talk Mode realtime, and channel/provider reliability fixes. Upgrade Node to 22.19+; openclaw doctor --fix; re-test voice, browser, plugins, and channels. Details: Releases → v2026.5.18.
v2026.5.12 Leaner core installs (externalized provider/plugin cones), Telegram resilience, Codex/OpenAI and plugin-install hardening, security/provenance pass, and UI/reply-delivery improvements. openclaw doctor --fix; install missing plugins if config references Bedrock/Slack/Vertex; re-test Telegram, Codex, plugin updates, and rich replies. Details: Releases → v2026.5.12.
v2026.5.7 Authorization enforcement hardening, Telegram/Discord/WhatsApp delivery fixes, cron/status/session reliability updates, and provider/tool runtime edge-case repairs. openclaw doctor --fix; verify command/skill auth behavior, re-test channel delivery paths and cron jobs, and confirm runtime/task/session surfaces are healthy. Details: Releases → v2026.5.7.
v2026.5.6 Hotfix for v2026.5.5 doctor --fix Codex OAuth route rewriting; plugin/runtime fetch header sanitization; web-fetch timeout cleanup for Gateway tool lanes. After upgrade, verify Codex OAuth defaults if you used doctor --fix on 5.5 (recovery doc); re-smoke plugin HTTP and web_fetch. Details: Releases → v2026.5.6.
v2026.5.5 Reliability fixes across Feishu/LINE/Telegram/Matrix/Discord, xAI/Fireworks model compatibility, Control UI session responsiveness, plugin update/install resilience, iOS private-LAN pairing, and gateway restart/shutdown hygiene. openclaw doctor --fix; re-test your channel and plugin flows; verify runtime/session surfaces in Control UI and CLI status. Details: Releases → v2026.5.5.
v2026.5.4 Voice/Meet (Twilio + realtime Gemini) tuning; Windows gateway loopback bind defaults; install hints for missing official plugins; Discord SecretRef contracts from packaged plugin dist/; Slack rich progress streaming; Control UI and gateway startup polish. openclaw doctor --fix; openclaw models auth list; smoke voice/Meet, Slack drafts, and Windows local gateway if you rely on them. Details: Releases → v2026.5.4.
v2026.5.3 Bundled file-transfer tools for paired nodes (path policy); unified streaming.mode: "progress" across several channels; lazy-loaded gateway modules; invalid config fails closed until openclaw doctor --fix; hardened plugin install/update paths. openclaw doctor --fix; review file-transfer allowlists and plugin entries; re-test channels you use with progress drafts. Details: Releases → v2026.5.3.
v2026.4.26 Talk realtime transport changes, bundled Cerebras provider onboarding, plugin config/runtime helper deprecations, and migration/import workflow additions. openclaw doctor --fix; run openclaw migrate --dry-run; smoke-test Talk/Meet and custom plugin flows.
v2026.4.24 Google Meet bundled plugin, realtime voice consult paths, DeepSeek default model shifts, browser timeout/headless profile behavior, and plugin SDK tool-result middleware migration. openclaw doctor --fix; run smoke checks for Meet/voice/browser paths; verify custom plugins moved to registerAgentToolResultMiddleware.
v2026.4.15 Anthropic default/alias changes, Codex transport normalization, memory dreaming storage defaults, and plugin packaging/runtime locality changes. openclaw doctor --fix; validate model/provider behavior with openclaw models list; verify channel/provider flows you depend on.
v2026.4.10 Codex vs OpenAI model prefixes; optional Active Memory; exec-policy for exec config vs approvals; WhatsApp gateway --media path—re-check Talk, Teams, and exec flows. openclaw exec-policy show; openclaw doctor; review Releases for your channels.
v2026.4.9 Matrix legacy dm.policy: "trusted"; stronger browser/.env/exec-event handling—verify Matrix and Slack after upgrade. openclaw doctor --fix for Matrix DM migration; skim Releases for security-related fixes.
v2026.4.5 Legacy public config aliases consolidated onto canonical paths and enabled. openclaw doctor --fix, then diff or re-open config for moved keys.
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.

Post-upgrade commands

  • openclaw doctor — health checks and reporting
  • openclaw doctor --fix — auto-migrate common issues
  • openclaw gateway restart — apply changes safely
  • openclaw --version — include version when asking for help

If something breaks

Start 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:

Commands
openclaw --version
openclaw doctor

Upgrade FAQ

What should I run after upgrading OpenClaw?

Run openclaw doctor --fix, then openclaw gateway restart, then openclaw doctor.

How do I migrate xAI 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.

How do I migrate Firecrawl 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.

What breaks in v2026.4.5 for older configs?

Legacy public aliases (talk keys, sandbox per-session paths, hooks.internal.handlers, old allow toggles, etc.) are removed in favor of canonical paths and enabled. Run openclaw doctor --fix after upgrade and confirm the resulting openclaw.json. See latest breaking changes on the Releases page.

What changed in v2026.3.31 for node execution?

Node shell execution routes through exec host=node with tighter trust/pairing behavior; re-check workflows that relied on older wrapper behavior.

What if OpenClaw still fails after migration?

Use Troubleshooting, check FAQ, and include openclaw --version plus openclaw doctor output in bug reports.

Related