docs: OpenClaw 3.7 → 4.12 upgrade risk assessment

[lefarcen]

What

Adds a research memo assessing the risks, costs, and path for upgrading Nexu's bundled OpenClaw runtime from v2026.3.7 to v2026.4.12.

File: openclaw-upgrade-risk-assessment.md

Why

The goal is to make Nexu's embedded agent runtime pluggable (replace the built-in PI with Codex-style harnesses). The AgentHarness plugin API first shipped in v2026.4.10, which Nexu's current v2026.3.7 does not have.

This memo exists so the team can align on risk, scope, and rollout plan before we start the upgrade work, rather than discovering surprises mid-flight.

How

Traced every coupling point between Nexu and OpenClaw across all 13,667 commits between 3.7 and 4.12. Document layout:

• §1 Goals & premises + a compatibility-findings summary
• §2 Harness API timeline (v2026.4.10 is the floor)
• §3 Target version rationale (4.10 vs 4.11 vs 4.12 vs 4.14 reputation)
• §4 Interface-layer compatibility (config schema, plugin SDK paths, CLI entrypoint, security policy)
• §5 Runtime-behavior compatibility (WS RPC, process lifecycle, Skill install, BYOK — four subsystems)
• §6 Upgrade cost & required changes (code-change checklist, audit checklist, effort estimate)
• §7 Rollout strategy (3.7 → 3.22 → 4.12 in three stages + when to flip on harness)
• §8 Key file index
• §9 One-liner conclusion

Affected areas

• Desktop app (Electron shell)
• Controller (backend / API)
• Web dashboard (React UI)
• OpenClaw runtime
• Skills
• Shared schemas / packages
• Build / CI / Tooling
• Docs only — no code changes

Checklist

• pnpm typecheck passes (N/A, docs-only)
• pnpm lint passes (N/A, docs-only)
• pnpm test passes (N/A, docs-only)
• pnpm generate-types run (if API routes/schemas changed) (N/A)
• No credentials or tokens in code or logs
• No any types introduced

Notes for reviewers

Please sanity-check the following conclusions, since they directly drive the upgrade scope and effort estimate:

1. Target version = v2026.4.12: 4.10 has the Codex harness init-hang on macOS, 4.11 introduced several Codex / QQ / WhatsApp regressions, 4.12 is the first stabilization release; 4.13/4.14 are too new and have no community feedback yet.
2. Replacement plan for the two channel plugins
   • WhatsApp: OpenClaw has shipped extensions/whatsapp/ bundled since v2026.1.22, so Nexu's in-tree copy can simply be deleted.
   • WeChat: the official Tencent npm @tencent-weixin/openclaw-weixin@2.1.8 (Nexu is on 1.0.2, 13 versions behind) — Tencent has already done the new-SDK migration work for us.
3. Four platform plugins are immune to the SDK refactor: nexu-runtime-model / nexu-credit-guard / nexu-platform-bootstrap / langfuse-tracer use the duck-typed register(api) API and don't import openclaw/plugin-sdk.
4. WS protocol is byte-identical: the 6 RPCs + 3 events Nexu uses are all additive-only in 4.12.
5. Only one orange-level runtime risk: in packaged launchd mode, supervisor-restart semantics changed from "detached fork + spawned pid N" to "exit(0) + launchd respawn". Nexu's successor-PID regex won't match anymore — needs extension plus a check that RUNTIME_MANAGE_OPENCLAW_PROCESS=false actually takes effect at runtime.
6. Codex harness itself is still unstable: upstream issue openclaw/openclaw#66251 is still open. After the upgrade, keep embeddedHarness.runtime: "auto" + fallback: "pi"; ship the harness pilot as a separate follow-up PR once upstream stabilizes.

Effort estimate: ~1.5 weeks for code changes + verification.

[sentry]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!