Deployment Upgrade Runbook

Page scope (operations runbook niche): This page is for operator workflows (preflight, rollout, smoke tests, rollback). For config migration details use Upgrading / Migrating. For release history use Releases.

1. Create a backup: openclaw backup create.
2. Capture current version and health: openclaw --version, openclaw doctor.
3. Verify maintenance window and owner comms (channel impact, rollback owner).
4. Confirm host resources (disk, memory, network) and dependency versions.

openclaw update
openclaw doctor --fix
openclaw gateway restart
openclaw doctor

If migration-related warnings appear, continue with Upgrading / Migrating and provider-specific guides.

• Gateway health: service starts cleanly, no auth/pairing regressions.
• Tool path: run one safe tool call and verify expected response.
• Channel path: send one test message and confirm delivery + reply.
• Provider path: test at least one model/provider call relevant to your production flow.

If you upgraded to v2026.6.10 (or skipped from v2026.6.9 / v2026.6.8), add these checks to the smoke list:

• Talk fast mode (v2026.6.10+): smoke short conversational turns and confirm fallback to normal mode on longer runs.
• Zai / GLM routing (v2026.6.10+): re-test GLM models under load and native /think menu levels if you use them.
• Channel switching (v2026.6.10+): switch active channel/session and confirm stale origin fields do not leak routing context.
• Cron delivery (v2026.6.10+): if you use cron announce to sessions, confirm delivery awareness follows the target session after upgrade.
• Hook policies (v2026.6.10+): re-smoke exec-approval or trusted-tool flows that depend on composed hook registries.

Migration checklist: Upgrading → v2026.6.10 · Release highlights: Releases → v2026.6.10

If you upgraded to v2026.6.9 (or skipped from v2026.6.8), add these checks to the smoke list:

• Telegram rich HTML (v2026.6.9+): smoke tables, lists, and progress drafts in channels you rely on.
• Codex Spark (v2026.6.9+): if using GPT-5.3 Spark OAuth, confirm auth routing and auto plugin approvals.
• Session workspace rail (v2026.6.9+): confirm Control UI workspace rail and extension health in status.
• Provider plugins (v2026.6.9+): verify standalone provider npm packages load at Gateway startup after install.
• Codex Hosted Search (v2026.6.9+): if enabled, smoke one search query and confirm opt-in behavior for key-free providers.

Migration checklist: Upgrading → v2026.6.9 · Release highlights: Releases → v2026.6.9

If you upgraded to v2026.6.8 (or skipped from v2026.6.6 / v2026.6.5), add these checks to the smoke list:

• Telegram / WhatsApp (v2026.6.8+): smoke rich Telegram formatting (lists, tables) and WhatsApp ACP bindings if configured.
• Usage footers (v2026.6.8+): if you use /usage or reply payload hooks, confirm footer templates render and broken templates warn instead of failing silently.
• Providers (v2026.6.8+): smoke GLM-5.2 or Claude Haiku 4.5 if in your model catalog; confirm web search still uses your configured provider (key-free providers are opt-in only).
• Memory / state (v2026.6.8+): on NFS-backed storage, confirm SQLite state and memory search still work; re-smoke large embedding indexes if applicable.
• Control UI / WebChat (v2026.6.8+): confirm WebChat backscroll during streaming and session picker interactivity after upgrade.

Migration checklist: Upgrading → v2026.6.8 · Release highlights: Releases → v2026.6.8

If you upgraded to v2026.6.6 (or skipped from v2026.6.5 / v2026.6.1), add these checks to the smoke list:

• Security (v2026.6.6+): re-run openclaw security audit --deep; confirm exec approvals fail closed on timeout.
• Telegram / iMessage (v2026.6.6+): smoke account-scoped topics and streamed text through tool calls; confirm iMessage inbound restart survives gateway bounce.
• MCP / browser (v2026.6.6+): one CDP/browser tool session if you use automation; confirm Streamable HTTP MCP transport if applicable.
• OpenRouter OAuth (v2026.6.6+): if using browser login, smoke openclaw models auth login --provider openrouter. Guide: OpenRouter OAuth.
• Control UI (v2026.6.6+): confirm faster startup and first-reply tracing; re-test /models picker.

Migration checklist: Upgrading → v2026.6.6 · Release highlights: Releases → v2026.6.6

If you upgraded to v2026.6.5 (or are on v2026.6.1 / v2026.5.28), add these checks to the smoke list:

• Parallel web search (v2026.6.5+): smoke one web_search query if agents use bundled search; confirm PARALLEL_API_KEY or onboarding picker config. Guide: Parallel setup.
• MCP tools (v2026.6.5+): run one MCP tool that returns rich content (images, audio, resources) and confirm no Anthropic 400s or poisoned session history.
• SQLite state (v2026.6.5+): restart gateway and confirm auth profiles, plugin install pins, and channel-sidecar state recover cleanly. Policy: plugin install policy.
• Channels (v2026.6.5+): re-smoke QQBot/Matrix/WhatsApp/Google Chat paths you rely on; confirm reasoning tags do not leak in QQBot replies.

Migration checklist: Upgrading → v2026.6.5 · Release highlights: Releases → v2026.6.5

If you upgraded to v2026.6.1 (or skipped from v2026.5.28), add these checks to the smoke list:

• Skill Workshop (v2026.6.1+): smoke one proposal create/review flow if you use governed skills. Guide: Skill Workshop.
• Workboard (v2026.6.1+): one multi-agent handoff if you use board orchestration. Guide: Workboard.
• SQLite state (v2026.6.1+): restart gateway and confirm iMessage/plugin install state recovers cleanly.
• Control UI chat (v2026.6.1+): send while history loads; confirm stream deltas and composer behavior.

Migration checklist: Upgrading → v2026.6.1 · Release highlights: Releases → v2026.6.1

If you upgraded to v2026.5.28 (or skipped from v2026.5.27), also verify:

• Copilot / Codex plugins (v2026.5.28+): if using @openclaw/copilot or Codex Supervisor, smoke one delegated workflow and confirm plugin install from registry.
• iOS / mobile (v2026.5.28+): Pro UI, push relay, and realtime Talk tab—one reconnect after gateway restart.
• PDF / media (v2026.5.28+): one encrypted-PDF extraction path if agents read documents in your workflow.
• Channels (v2026.5.28+): re-smoke Matrix room routing, iMessage approvals, Slack final replies, Teams service URLs.

Migration checklist: Upgrading → v2026.5.28 · Release highlights: Releases → v2026.5.28

If you upgraded to v2026.5.27 (or skipped from v2026.5.22 / v2026.5.20), also verify:

• Gateway auth / Tailscale (v2026.5.27+): confirm remote auth rate limiting and that no-auth Tailscale exposure is not enabled unintentionally.
• Embeddings / memory (v2026.5.27+): if you use workspace memory search, verify OpenAI-compatible embedding provider config and run openclaw doctor for deprecated plugin embedding registration warnings.
• Codex (v2026.5.27+): smoke one app-server thread resume and a tool path that routes workspace memory through tools.
• Channels (v2026.5.27+): one outbound test per production channel (Telegram durable send, iMessage approvals, Slack final reply, Matrix mention preview, Discord guild routing, Google Chat DM thread behavior).

Migration checklist: Upgrading → v2026.5.27 · Release highlights: Releases → v2026.5.27

If you upgraded to v2026.5.22 (or skipped directly from v2026.5.20 / v2026.5.19), also verify:

• Node runtime: node -v shows 22.19+ before openclaw update completes.
• Restart latency: openclaw gateway restart reaches ready without prolonged sidecar stalls (compare to pre-upgrade if you log restart traces).
• Mac app (if used): open Settings panes (permissions, voice, skills, cron); confirm menu bar app version matches Gateway.
• Discord voice (if used): smoke voice follow into an allowed channel; confirm exec approvals still allow skills loaded via read (v2026.5.20+).
• Subagents (v2026.5.22+): spot-check delegated runs—bootstrap now defaults to AGENTS.md + TOOLS.md only; explicitly opt back in to persona/memory files if a subagent relied on them.
• Gateway / /models (v2026.5.22+): confirm startup readiness time and /models latency reflect the pre-warmed provider auth path.
• Browser automation (if used): one snapshot with a pending dialog; answer with browser dialog --dialog-id if your flow depends on modals.
• Android Talk Mode (if used): paired node on 5.18+; one short realtime voice turn with transcript on device (Android guide).
• Plugins (if used): openclaw plugins validate on any custom tool plugins; spot-check openclaw plugins build in CI if you ship plugins.

Migration checklist: Upgrading → v2026.5.22 · Release highlights: Releases → v2026.5.22

1. Stop active automation if behavior is unstable.
2. Restore known-good backup/config.
3. Restart gateway and re-run smoke tests.
4. Document incident scope and root cause before retrying upgrade.

On Docker, pin image tags before upgrade and keep the previous tag for rollback. Managed vendors may auto-update—ask whether you can defer upgrades during incidents. Always export config (openclaw backup create) before vendor-side maintenance windows.

Before upgrading, notify channel users: expected downtime (usually gateway restart only), whether pairing must be re-approved, and who to ping if replies stop. After smoke tests pass, send an all-clear with the new openclaw --version string for support tickets.