OpenClaw 2026.9.1 Migration: Legacy Multi-Agent Upgrade Notes from r/openclaw

Upgrading OpenClaw across major versions can feel daunting, but a recent r/openclaw post shows a legacy multi-agent setup moving from 2026.7.1-2 to 2026.9.1 without major drama — especially when you let an AI coding agent handle the steps.

The Legacy Setup

The migration started from this configuration:

• Global npm installation of OpenClaw
• Version 2026.7.1-2
• User systemd gateway service
• Multiple configured agents with agent-specific workspaces
• WhatsApp channel with group-specific routing
• Browser profiles and several managed plugins

Issues Found

Only after the upgrade do you really see what's changed. The identified problems included:

• Multiple legacy config keys rejected by 2026.9.1
• Multi-agent ownership needed explicit declaration
• Shared SQLite state database required schema migrations
• Legacy workspace setup state needed migration
• Several official plugins were still on the old version
• WhatsApp had no fallback agent for unmatched messages
• Web UI reverse proxy needed trusted forwarded client attribution
• Service definition had stale or non-standard metadata

What Fixed It

The upgrade was delegated to Codex (via the VS Code extension, connected remotely to the OpenClaw machine). The full process took about 30 minutes. Key steps from the generated summary:

• Created a dated rollback backup of configuration, secrets, service files, package metadata, and runtime status.
• Updated OpenClaw to 2026.9.1 using the built-in updater.
• Migrated configuration by removing retired keys and converting supported timeout settings.
• Set multi-agent ownership to explicit.
• Ran Doctor with the external-service repair policy to let SQLite, workspace, device, and plugin state migrations complete.
• Refreshed the systemd gateway service definition.
• Updated official plugins to 2026.9.1.
• Set main as the default heartbeat owner and unmatched WhatsApp routing agent.
• Added a narrowly scoped trusted proxy entry for the local reverse proxy.

Result and Lesson

After migration, the gateway runs 2026.9.1, configuration validates, the service is active, the local HTTP/RPC listener responds, WhatsApp reports that it's listening for inbound messages, and heartbeat processing starts normally.

The main lesson: for a large version jump, back up first, expect schema and state migrations, and check both gateway ownership and multi-agent routing.