[Epic] Qualify and migrate managed OpenClaw from 2026.7.1 to OpenClaw 2.0 (2026.8.1)

## Summary

Migrate NemoClaw’s managed OpenClaw runtime from the current exact `2026.7.1` pin to stable OpenClaw 2.0, published as [`v2026.8.1`](https://github.com/openclaw/openclaw/releases/tag/v2026.8.1).

This is a stateful runtime migration, not a pin-only update. Keep production defaults, release aliases, and support claims on `2026.7.1` until the exact 2.0 candidate image passes dependency review, installed-base migration, rollback, security, and full supported E2E qualification.

## Verified baseline

NemoClaw `main` at [`67d6abeb811296f22cf5c00df5c0fd5536f27bf1`](https://github.com/NVIDIA/NemoClaw/commit/67d6abeb811296f22cf5c00df5c0fd5536f27bf1) currently pins:

- `openclaw@2026.7.1` in the [runtime lock](https://github.com/NVIDIA/NemoClaw/blob/67d6abeb811296f22cf5c00df5c0fd5536f27bf1/agents/openclaw/openclaw-runtime/package.json#L8-L16), Dockerfiles, agent manifest, workflows, and security review.
- Matching `2026.7.1` official plugins for diagnostics, Brave, Discord, Google Chat, Microsoft Teams, Slack, and WhatsApp.
- `@tencent-weixin/openclaw-weixin@2.4.3`.

OpenClaw 2.0 identities:

- Release/tag: [`v2026.8.1`](https://github.com/openclaw/openclaw/releases/tag/v2026.8.1)
- Tag commit: [`ea806575e6450e4d1efdfc72c19f04be982a1b9b`](https://github.com/openclaw/openclaw/commit/ea806575e6450e4d1efdfc72c19f04be982a1b9b)
- npm integrity: `sha512-bSaFeaDFnQH/bU1vgKMac6eHkHHPHG0C/uwduXGI3eIS3lyiYSwmDU5ehhBUUhlPeV85tL5/KVwmoH48nX1tWw==`
- Tarball SHA-256: `43c4b1f81afcd50244c85bcb5686fa6e39f0da6a5941735811b58064b7e0ca10`
- Node requirement: `>=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0`

NemoClaw’s current sandbox Node runtime already satisfies this range.

## Confirmed blockers

### Generated configuration

Representative NemoClaw configs fail the real 2.0 validator because these current fields are no longer accepted:

- `agents.defaults.compaction.maxHistoryShare`
- `agents.defaults.compaction.truncateAfterCompaction`
- `gateway.controlUi.allowInsecureAuth`
- `gateway.reload.mode: "hot"`; 2.0 accepts `off` or `hybrid`

Update the generator to the canonical 2.0 schema and validate every supported profile using the exact published runtime.

The first migration should also explicitly preserve current behavior rather than inherit new 2.0 defaults:

- Disable memory dreaming until separately qualified.
- Set autonomous self-learning to `off` until separately approved.
- Pin top-level concurrency to the current value rather than inheriting CPU-scaled 8–16 execution.
- Encode the intended session reset/retention policy explicitly.
- Do not implicitly enable telemetry, cloud workers, Portals, Fleet, Daytona, A2A, IMAP, device hosting, or other newly shipped capabilities.

### NemoClaw plugin and SDK contracts

The NemoClaw plugin can load on 2.0, but the current installation and manifest contracts are insufficient:

- Local and `npm-pack:` installs now require explicit source forcing and capability acceptance.
- `before_prompt_build` is blocked unless `plugins.entries.nemoclaw.hooks.allowConversationAccess=true`.
- Runtime inspection observes provider and hook registrations that are absent from the accepted capability declaration.
- The package still records `openclawVersion: 2026.7.1`.
- Current locally mirrored SDK types must be checked against the focused 2.0 SDK surface and the September 1 removal gate.

Update the manifest/package metadata so the accepted capabilities exactly match the command, provider, secret-scanner hook, and runtime-context hook actually registered. Run `openclaw doctor --post-upgrade --json` and runtime plugin inspection as required qualification.

See the upstream [Plugin SDK migration guide](https://docs.openclaw.ai/plugins/sdk-migration).

### Stateful migration and rollback

OpenClaw 2.0 makes SQLite the authoritative state boundary:

- Shared state: `state/openclaw.sqlite`
- Per-agent state and transcripts: `agents//agent/openclaw-agent.sqlite`
- Legacy session JSON/JSONL is migration input, not active runtime state.

NemoClaw’s current manifest backs up `agents/` and selected directories/files but does not declare the global `state/` database. Raw copying of live SQLite/WAL files is not an acceptable rollback contract.

Implement a stopped or properly quiesced migration that:

1. Captures WAL-consistent global and per-agent database snapshots plus config, credentials, workspaces, plugin records, and the exact pre-upgrade image/runtime receipt.
2. Runs the target 2.0 database/config preflight before activation.
3. Runs required Doctor migrations under NemoClaw-owned lifecycle authority with native service repair disabled.
4. Preserves the prior sandbox and last recoverable snapshot until the new gateway, inference, pairing, and plugin state are proven healthy.
5. Restores the exact pre-upgrade state on failure instead of starting `2026.7.1` against a database already advanced by 2.0.
6. Covers rollback of session history using the documented SQLite restore path when required.

If the existing manifest cannot express dynamic per-agent SQLite snapshots, land the smallest agent-neutral state-file contract separately. Do not add OpenClaw-name branches to shared backup core.

See upstream [Doctor migration](https://docs.openclaw.ai/cli/doctor) and [Gateway external-supervisor guidance](https://docs.openclaw.ai/cli/gateway).

### External supervision and health

Adopt and qualify:

- `OPENCLAW_SUPERVISOR_MODE=external`
- `OPENCLAW_SERVICE_REPAIR_POLICY=external`

These align with NemoClaw’s PID 1 and host-controlled gateway lifecycle, but setting the variables alone is insufficient. Prove restart handoff consumption, safe/forced restart behavior, tracked PID identity, crash respawn, config resealing, and host-requested recovery.

Map health semantics deliberately:

- `/healthz`: liveness and restart decisions
- `/startupz`: startup/traffic admission
- `/readyz`: deep channel readiness and diagnostics, not an automatic restart trigger

See upstream [health semantics](https://docs.openclaw.ai/health).

### Official plugin cohort

Every first-party plugin shipped by NemoClaw must move to `2026.8.1` with the core runtime; the 2.0 packages declare `openclaw >=2026.8.1`.

Regenerate exact archives, locks, integrity pins, offline cache metadata, lifecycle allowlists, audit registries, workflow assertions, and managed-image validation for:

- Diagnostics OTEL
- Brave
- Discord
- Google Chat
- Microsoft Teams
- Slack
- WhatsApp
- Any newly required Tavily package

iMessage moved from bundled to an external official plugin. Remove the stale bundled-iMessage assertion or install and qualify the exact package if NemoClaw intends to retain it as an inert managed-image capability.

### Plugin install-state schema

NemoClaw currently reads the OpenClaw plugin install registry directly from SQLite table `installed_plugin_index`.

OpenClaw 2.0 moves the canonical installed-plugin index into `config_machine_state` under `plugins.installedIndex`. Update fresh-plugin discovery, rebuild reconciliation, and restore behavior. Prefer a supported OpenClaw CLI/API query over another direct private-table dependency.

Prove that NemoClaw, image-managed messaging plugins, and user-installed plugins survive rebuild without resurrecting removed image-owned extensions.

### Compiled-dist patch disposition

Static compatibility against the published 2.0 tarball produced this initial disposition:

| Patch | 2.0 disposition |
| --- | --- |
| `patch-openclaw-issue-4434-diagnostics` | Applies unchanged |
| `patch-openclaw-mcp-tools-list-timeout` | Applies after exact-version gate update |
| `patch-openclaw-mcp-npx` | Native upstream behavior exists; retire after behavioral proof |
| `patch-openclaw-tool-catalog` | Native Tool Search/catalog exists; retire after behavioral proof |
| Chat correlation | Rebase |
| Device self-approval | Security-sensitive redesign/rebase |
| Gateway daemon dialback | Partial rebase |
| MCP startup recovery | Behavioral review/rebase |
| Managed MCP transport diagnostics | Rebase |
| Shared-state permissions | Rebase for split-user SQLite layout |

Seven inline fetch/proxy, cron-preflight, plugin-symlink, and handshake transformations still match the exact 2.0 dist. The old install-package-directory symlink subpatch safely classifies itself as unnecessary.

For every patch:

- Run the unpatched behavior test first.
- Retire only when upstream behavior satisfies the existing postcondition.
- Port only behavior still required by NemoClaw’s OpenShell/split-user environment.
- Keep the real-dist and exact-shape gates.
- Record the disposition in [#5896](https://github.com/NVIDIA/NemoClaw/issues/5896).

## Delivery plan

Use seven focused child issues/PRs:

- [ ] 1. Add candidate-only 2.0 artifact and trust support without changing production defaults.
- [ ] 2. Migrate generated config and NemoClaw plugin/capability contracts.
- [ ] 3. Reconcile every compiled-dist patch against the exact published 2.0 distribution.
- [ ] 4. Implement the 7.1→2.0 state migration, interrupted-upgrade recovery, and rollback contract.
- [ ] 5. Move the complete official plugin cohort to exact 2.0 artifacts.
- [ ] 6. Publish exact candidate managed images and run qualification without moving production aliases.
- [ ] 7. Flip the production pin, update support metadata/docs, and cut the NemoClaw release.

PRs 2, 3, and 5 may proceed after PR 1. PR 4 consumes the config and patch decisions. PR 6 requires PRs 2–5. PR 7 requires immutable candidate evidence from PR 6.

## Acceptance criteria

- [ ] Exact 2.0 core and official plugin artifacts are independently integrity-pinned, signature/provenance checked, dependency-reviewed, license-reviewed, and scanned.
- [ ] Upstream lifecycle code runs only with an isolated `HOME` and `OPENCLAW_STATE_DIR`; image/audit builds cannot initialize or migrate operator state.
- [ ] Every generated config variant passes the real 2.0 validator.
- [ ] Runtime inspection proves the NemoClaw command, provider, secret-scanner hook, and runtime-context hook are loaded and match the accepted capability set.
- [ ] Dreaming, self-learning, telemetry, updates, cloud workers, and other new optional capabilities remain off unless separately selected and qualified.
- [ ] Every compiled-dist patch has an explicit retained, rebased, or retired disposition backed by behavior and exact-dist tests.
- [ ] Fresh install, stateful 7.1 upgrade, rebuild, restore, rollback, and interrupted migration preserve state and never delete the last recoverable copy.
- [ ] Global and per-agent SQLite snapshots are WAL-consistent and pass target-version preflight before activation.
- [ ] Split gateway/sandbox users, shared database permissions, Shields up/down, config sealing, pairing, scope settlement, and external-supervisor recovery pass.
- [ ] `/healthz`, `/startupz`, and `/readyz` are used according to their distinct contracts.
- [ ] MCP, TUI/chat correlation, web fetch/search, hosted and local inference, dashboard pairing, plugin lifecycle, OTEL, Brave, and supported messaging providers pass.
- [ ] Exact amd64 and arm64 candidate manifests, image/SBOM scans, size/startup budgets, source revision, and runtime version are recorded.
- [ ] The complete unfiltered supported NemoClaw E2E matrix passes on the exact candidate digest before production aliases or defaults move.
- [ ] Upstream release waivers remain recorded as waivers rather than being treated as NemoClaw qualification evidence.
- [ ] Documentation covers changed defaults, state migration, rollback, data retention, failure recovery, and unsupported scope.

## Non-goals

- Attaching NemoClaw to arbitrary existing OpenClaw deployments; that remains [#2217](https://github.com/NVIDIA/NemoClaw/issues/2217).
- General compiled-dist cleanup beyond the 2.0 dispositions; that remains [#5896](https://github.com/NVIDIA/NemoClaw/issues/5896).
- Silently declaring Portable OpenClaw supported.
- Enabling every new OpenClaw 2.0 feature.
- Folding this migration into the broader runtime-package modularization work.
- Changing Hermes, Deep Agents Code, or agent-neutral core behavior unless a separately approved generic contract is required.

## Related work

- [#2217 — OpenClaw version upgrade/attachment flexibility](https://github.com/NVIDIA/NemoClaw/issues/2217)
- [#4271 — Resolve legacy blueprint image pin and OpenClaw version floor](https://github.com/NVIDIA/NemoClaw/issues/4271)
- [#5896 — OpenClaw compiled-dist patch and compatibility debt](https://github.com/NVIDIA/NemoClaw/issues/5896)
- [#6691 — Speculative candidate compatibility testing](https://github.com/NVIDIA/NemoClaw/issues/6691)

No existing issue or PR was found for exact `2026.8.1`; this epic is the release-specific execution and qualification boundary.

Start with the seven child issues, the runtime lock in agents/openclaw/openclaw-runtime/package.json, Dockerfiles, the agent manifest, workflows, and security review. First qualify the exact 2026.8.1 candidate without changing production defaults, then follow the dependent config, plugin, patch, state-migration, image, and release work. Done means the exact candidate passes integrity, migration, rollback, security, and complete supported E2E qualification before production aliases move.

Written by the indexing model from the issue text.