v2026.6.8

Sync with upstream openclaw 2026.6.8. Covers the v2026.6.7-beta.1 → v2026.6.8 range (no v6.7 stable was published).

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

v6.8 is a bug-fix + security-hardening + internal-CI release. It introduces no new wrapper-facing config options, CLI commands, or install dependencies, so the wrapper sync is essentially a version bump.

Wrapper changes

• VERSION + CLAUDE.md header bumped to v2026.6.8.
• templates/openclaw.json.example: documented #93616 — key-free web-search providers (Parallel Free / DuckDuckGo / Ollama / Codex Hosted Search) now require an explicit opt-in instead of being auto-selected when no API-backed provider is configured. The template already sets provider: "perplexity", so this flow is unaffected; the note is for community users who relied on auto-selection.

No changes to docs/, openclaw-orbstack-setup.sh, or scripts/commands/update.sh. v6.8 carries no breaking config for the OrbStack flow.

What v6.8 brings for the OrbStack flow

Reliability and security work that benefits this topology (Codex subscription + Telegram + self-hosted Gateway):

• Telegram delivery is richer and less brittle (#92679, #93164): structured rich text with tables, lists, expandable blockquotes, preserved intentional line breaks, prompt-preserving CLI-backend delivery, and safer rich-media boundaries.
• Provider/model replay is more resilient on the OpenAI/Codex path (#90706, #92941, #90686): storeless OpenAI Responses replay compatibility is preserved, invalid OpenAI reasoning signatures and genericized Anthropic thinking-signature replay errors recover, and OAuth image defaults route through Codex for eligible OpenAI profiles.
• Security boundaries tighten further (continuing the v6.6 hardening): HTTP session/model override surfaces now require admin privileges (#92646), CLI-backed /btw fails closed, WebSocket payload handling is hardened, and Skill Workshop symlink writes are gated and validated before rollback metadata is written.
• Memory/state/diagnostics recover cleaner (#92650, #92639, #91247): oversized OpenAI embedding batches split before 431s, SQLite avoids WAL on NFS state volumes, and stuck-session recovery scheduling no longer resets warning backoff.
• Update flow is quieter (#92911, #86629): false downgrade prompts for unresolved latest-tag updates are avoided, and doctor/install now stops after a failed Node package install rather than continuing.

A large set of v6.8 changes do not apply to the OrbStack flow (WhatsApp ACP bindings, GLM-5.2 / Claude Haiku 4.5 catalog rows, Discord auto-thread titles, /usage footer rendering, iOS reconnect, and a broad QA/CI/E2E pass).

Bugs we track — no progress this release

None of the upstream issues this wrapper tracks were fixed in the v6.7-beta.1 → v6.8 range: #90945 (Telegram stuck-lane claimed-leak), #86393 (/btw after compaction), #86184 (Codex takeover), #75593 (subagents list), and #92479 (opencode/Zen provider catalog) all remain open. Adjacent stuck-session fixes (#91247, heartbeat dedupe) do not touch the channel_ingress_events claimed-leak root cause.

Doctor non-interactive flow

No new interactive prompts in the v6.8 notes — #92911 actually removes one false prompt. The two-layer non-interactive defense in scripts/commands/update.sh (pre-archive orphan transcripts + yes n | fallback) remains valid and unchanged. After upgrading, a clean ~/.openclaw/.update-doctor.log (no Setup cancelled lines) confirms both doctor passes completed.

v2026.6.6

Sync with upstream openclaw 2026.6.6.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

v6.6 is a security-hardening + bug-fix + internal-performance release. It introduces no new wrapper-facing config options or CLI commands, so the wrapper sync is a version bump only.

Wrapper changes

• VERSION + CLAUDE.md header bumped to v2026.6.6.

No changes to templates/openclaw.json.example, docs/, openclaw-orbstack-setup.sh, or scripts/commands/update.sh. v6.6 carries no new install dependencies and no breaking config for the OrbStack flow.

What v6.6 brings for the OrbStack flow

Reliability and security work that benefits this topology (Codex subscription + Telegram + self-hosted Gateway):

• Tighter security boundaries (#91529, #89938, and others): sandbox binds, host environment inheritance, MCP stdio, Codex HTTP access, native search policy, and elevated-sender checks are all hardened. Notably, exec approvals now fail closed on timeout — worth observing on the host-exec channel after upgrade (a timed-out approval is now denied rather than implicitly allowed).
• Telegram delivery is more coherent (#91189, #88682, #90212): account-scoped topics route to the right agent, streamed text survives tool calls, /compact works on generic ingress, and durable dispatch dedupe moved into the SDK.
• Codex compaction ownership preserved (#91590) and the default compaction timeout lowered to 180s while respecting explicit configuration (#91361) — set an explicit compaction timeout in openclaw.json if you want a longer window.
• model_not_found remediation message fixed (#89192, closed by #89194 / #89508 / #91292): the hint now includes the required name field, and a blank baseUrl no longer drops a bundled provider catalog (demonstrated with Google Gemini).
• Control UI startup and first-reply latency are lower (#91531, #91538) via cached model metadata and lazy slash-command loading.

A large set of v6.6 changes do not apply to the OrbStack flow (iMessage recovery, OpenRouter OAuth onboarding, QQBot group-mention toggle, iPad/iPhone control surfaces, Android service-type fixes, and a broad CI/E2E pass).

Doctor non-interactive flow

No new interactive prompts in the v6.6 notes. The two-layer non-interactive defense in scripts/commands/update.sh (pre-archive orphan transcripts + yes n | fallback) remains valid and unchanged. After upgrading, a clean ~/.openclaw/.update-doctor.log (no Setup cancelled lines) confirms both doctor passes completed.

v2026.6.5

Sync with upstream openclaw 2026.6.5.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

v6.5 is the first stable of the 6.5 train, rolling up the v2026.6.2 → v2026.6.5 beta cycles. It is overwhelmingly upstream bug fixes, runtime hardening, and SQLite-backed state migrations, plus features the OrbStack flow doesn't use (Parallel web-search provider, QQBot / Matrix / Feishu / WhatsApp / Mattermost channel fixes, Google Vertex ADC catalog, Android / iOS surfaces, and a large CI/E2E pass). There is no breaking config for the OrbStack flow.

Wrapper changes

• VERSION + CLAUDE.md header bumped to v2026.6.5.
• templates/openclaw.json.example:
  • Updated the legacy openai-codex/* example references to the canonical openai/*. The v2026.6.1 doctor migration unified the old openai-codex provider/profile into openai (openai-codex is kept as a legacy alias); upstream clarified this in #90250.
  • Documented Parallel as a new bundled web_search provider (#85158) — set provider: "parallel" with a PARALLEL_API_KEY (endpoint api.parallel.ai/v1/search). Commented reference only; the default Perplexity setup is unchanged.
• docs/commands.md: noted that openclaw skills install can now install ClawHub skills backed by GitHub repositories (#90478) — downloaded at a pinned commit, with install-policy checks.
• scripts/refresh-mac-commands.sh: comment-only openai-codex → openai rename note.

No changes needed to openclaw-orbstack-setup.sh or scripts/commands/update.sh. v6.5 carries no new install dependencies and no breaking config for the OrbStack flow.

What v6.5 brings for the OrbStack flow

Mostly reliability work that benefits this topology (Codex subscription + Telegram + self-hosted Gateway):

• Codex / Anthropic / agent recovery hardening (#90667, #90697, #90163, #90108, #89874, #89505, #90729): Anthropic extended-thinking sessions recover after prompt-cache expiry or a Gateway restart, stale compaction thinking signatures are stripped before replay, unsigned thinking-only stalls are detected, empty completion handoffs are rejected, and Codex session/thread migration edge cases are covered. Useful for a compaction-heavy Codex setup.
• MCP tool-result coercion (#90710, #90728): richer MCP blocks (resource_link, resource, audio, malformed images) are coerced at the materialize boundary, preventing Anthropic 400s and poisoned session history.
• Provider/model resolution is stricter (#90506, #90609, #90717, #90702): fail-closed for unknown model auth, Codex alias availability and model visibility preserved, and auth is no longer resolved while merely listing models.
• More durable state (#89102, #90072): auth profiles now live in SQLite, official npm plugin install records keep their trusted pins, and legacy cron JSON stores migrate into SQLite during doctor preflight.
• Safer upgrade/service paths (#90208): service-env planning no longer lets unresolved placeholders mask state-dir .env secrets. Upstream also deliberately deferred the session-metadata SQLite migration out of the 6.5 train (the JSON-backed path is kept), which lowers upgrade risk.
• Sandbox skills stay readable in writable sandboxes (#90261) — confirms skills remain a read-only mount in the sandbox even when the workspace is writable. The Workboard stale-lifecycle fix (#86205, #88592) also lands here.

Doctor non-interactive flow

Unchanged — verify-only. v6.5 introduces no new doctor confirmation prompts. The new doctor-preflight migrations (auth profiles → SQLite, cron JSON → SQLite, legacy agent registry and Codex model metadata) are automatic and non-interactive. The wrapper's pre-archive + yes n defense in scripts/commands/update.sh remains safe. Post-upgrade, a clean ~/.openclaw/.update-doctor.log (no Setup cancelled) means all doctor passes completed.

Known active blockers

None of the issues this flow tracks are referenced or fixed in the v6.5 notes:

• #90945: Telegram lane deadlock. channel_ingress_events rows left in claimed state by a run that has died are never released (no liveness/TTL sweep), so the lane's queueDepth climbs and the bot stops replying. It survives systemctl restart, openclaw doctor --fix, openclaw sessions cleanup, and a wiped message spool — Telegram getUpdates returns count: 0, confirming the backlog is purely internal. Manual recovery: stop the Gateway, DELETE FROM channel_ingress_events WHERE status <> 'completed'; in ~/.openclaw/state/openclaw.sqlite, then restart. (Related: closed #90940; cron-lane variant #89766.)
• #75593: subagent list visibility — the agent-tool list sees children, but /subagents list on a chat channel (e.g. Telegram) returns empty (the channel-scoped requester key isn't canonicalized at the list boundary). Still open.
• #86393: /btw and /side (an alias of /btw) stop working after a long Codex session's first auto-compaction. Still open.
• #86184: embedded-attempt session takeover falling back to a generic /new. The root-cause fix landed in v5.26; v6.5's stall-recovery work (#89874, #89505) is adjacent but not a fix. Keep the timeoutSeconds: 300 workaround in place.

Upgrade guidance

The Mac-side wrapper picks these doc updates up automatically. The VM-side openclaw Gateway upgrade is a separate decision; v6.5 carries no breaking config or installer changes for the OrbStack flow, so the upgrade is low-risk and mainly delivers Codex/Anthropic recovery hardening, more durable auth/state storage, and stricter provider resolution.

---

---

Wrapper tooling update (re-released at the same version)

This v2026.6.5 tag was re-pointed to include an updater fix on top of the upstream sync (wrapper-only — no OpenClaw/runtime changes).

Root cause of the garbled-output ("screen garble") reports. The prebuilt npm install -g openclaw was actually succeeding every time. The wrapper's package-completeness check, however, ran a bare npm root -g (as the user) and looked under the user's npm prefix — ~/.openclaw/workspace/.local/lib/node_modules, the workspace Node — while sudo npm install -g installs into root's prefix, /usr/lib/node_modules. The package was never at the path being checked, so the check false-flagged "incomplete" and fell back to a source build on every update. That source build (pnpm + tsdown + vite + corepack) interleaving with the wrapper's progress lines on one TTY was the garble.

Fixes:

• The completeness check now uses sudo npm root -g (root's prefix, matching sudo npm install -g), so a successful npm install is correctly detected and no fallback fires.

• The source-build fallback is removed from openclaw-update — the updater is now npm-only. If the npm install genuinely fails or the package is truly incomplete, it prints the captured log path (~/.openclaw/.update-npm.log) and aborts with a retry hint (openclaw-update --force) instead of dropping into a multi-minute, screen-garbling source build. The installer (openclaw-orbstack-setup.sh) keeps its source-build fallback for first installs, where there's no working openclaw to fall back on.

• The updater keeps only the current ~/.openclaw/.update-doctor.log (no rotated timestamped archives).

• Follow-up — residual screen garble eliminated. Removing the source-build fallback exposed a second layer of garble: several VM-side steps streamed their output straight to the terminal, interleaving with the wrapper's spinner and progress lines. All of them are now quieted or captured: git fetch runs --quiet (openclaw has hundreds of bot branches, so a plain fetch floods the terminal with -> origin/... (forced update) lines), git checkout runs -q, the openclaw gateway stop/start CLI banner is sent to /dev/null, the @openai/codex global install is silenced, and the sandbox image builds are captured to per-image ~/.openclaw/.update-sandbox-*.log files (with the log path surfaced on failure). Real errors still reach stderr.

A VM upgraded before this fix may still have its systemd service pointing at the source checkout (~/openclaw/dist/index.js) from a past fallback build; run `openclaw gateway insta...

v2026.6.1

Sync with upstream openclaw 2026.6.1.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

v6.1 is the cumulative stable that rolls up the v2026.5.29 / 5.30 / 5.31 beta cycles. It is overwhelmingly upstream bug fixes, CI/E2E hardening, and performance work, plus features the OrbStack flow doesn't use (iOS push relay / iPad layouts, Workboard, Skill Workshop, MiniMax M3, and Copilot/Tokenjuice externalized as @openclaw/copilot / @openclaw/tokenjuice plugins).

Wrapper changes

• VERSION + CLAUDE.md header bumped to v2026.6.1.
• templates/openclaw.json.example: documented the new gateway.tailscale.serviceName field — when set, OpenClaw runs tailscale serve --service <name> to expose the Control UI as a named Tailscale Service (svc:<dns-label>) instead of the device hostname. Commented out by default; leaving it unset keeps the existing hostname-based exposure.
• docs/commands.md: added a Skill Workshop section (the skill_workshop agent tool + openclaw skills workshop CLI lifecycle: propose-create / propose-update / list / inspect / revise / apply / reject / quarantine); noted that openclaw agents add no longer needs an online provider catalog (#76284, #88314).

No changes needed to openclaw-orbstack-setup.sh or scripts/commands/update.sh. v6.1 carries no new install dependencies and no breaking config for the OrbStack flow.

What v6.1 brings for the OrbStack flow

Mostly reliability work that benefits this topology (Codex subscription + Telegram + self-hosted Gateway):

• Codex runtime recovery keeps hardening (#88129, #88136, #88141, #88162, #88182): live session locks are kept during cleanup, interrupted CLI tool transcripts are recovered, Codex auth + compaction session identity are preserved, orphan tool state is cleared, and app-server idle timers are capped. v6.1 also streams Codex app-server final-answer partials to live reply previews, migrates legacy OpenAI Codex lastGood auth state, and prevents aborted app-server turn handles from lingering (#88405, #88724, #88730). This continues the embedded-attempt takeover hardening whose root cause landed in v5.26.
• Async media generation no longer ends the Codex turn — image / music / video generation now renders in the background, so a mixed request can keep working (summaries, other tool calls) while media completes.
• Auth state is more robust (#89181): auth profiles are written atomically, auth failures are dispatched by type, a force re-login recovery path is added, and the agent compacts before oversized turns so recovery paths avoid partial state.
• New gateway.tailscale.serviceName gives the self-hosted Gateway a cleaner Tailscale exposure path — OpenClaw can bind the Control UI to a named Tailscale Service itself, instead of relying solely on a manual tailscale serve against the device hostname.
• Doctor gains disk-space health checks and post-upgrade JSON stabilization — the latter directly helps the wrapper's post-upgrade verification, which inspects doctor's JSON output.

Doctor non-interactive flow

Unchanged — verify-only. v6.1 introduces no new doctor confirmation prompts; the doctor changes are a non-interactive disk-space health check, post-upgrade JSON stabilization, and a legacy voice-call-log migration into plugin-state SQLite. The wrapper's pre-archive + yes n defense in scripts/commands/update.sh remains safe. Post-upgrade, a clean ~/.openclaw/.update-doctor.log (no Setup cancelled) means all doctor passes completed.

Known active blockers (unchanged)

All three tracked issues remain unfixed in v6.1 (none are referenced in the v6.1 notes):

• #75593: subagent list visibility — the agent-tool list sees children, but /subagents list on a chat channel (e.g. Telegram) returns empty (the channel-scoped requester key isn't canonicalized at the list boundary). Still reopened and unresolved.
• #86393: /btw and /side (an alias of /btw) stop working after a long Codex session's first auto-compaction. Still open. v6.1's "compact before oversized turns" is a different recovery path and is not a fix for this.
• #86184: embedded-attempt session takeover falling back to a generic /new. Root-cause fix landed in v5.26; v6.1 adds further Codex lock-release / recovery hardening. Keep the timeoutSeconds: 300 workaround in place.

Upgrade guidance

The Mac-side wrapper picks these doc updates up automatically. The VM-side openclaw Gateway upgrade is a separate decision; v6.1 carries no breaking config or installer changes for the OrbStack flow, so the upgrade is low-risk and mainly delivers Codex reliability, auth robustness, and the new optional Tailscale Serve exposure path.

v2026.5.28

Sync with upstream openclaw 2026.5.28.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

Wrapper changes

• VERSION + CLAUDE.md header bumped to v2026.5.28.
• docs/commands.md: noted that status output now shows active subagent details (upstream change).

No changes needed to openclaw-orbstack-setup.sh or scripts/commands/update.sh. v5.28 is overwhelmingly upstream bug fixes and input hardening, plus channels/providers the OrbStack flow doesn't use (WhatsApp, Teams, Matrix, Discord, iOS, NVIDIA, MiniMax, Fal Krea, GitHub Copilot runtime, Codex Supervisor plugin, Workboard).

What v5.28 brings for the OrbStack flow

Mostly reliability work that benefits this topology (Codex subscription + Telegram + self-hosted Gateway):

• Codex runtime recovery is steadier (#88129, #87375, #87399, #87383): session locks release on timeout abort and runtime teardown without deleting live Gateway-owned locks during cleanup, Codex app-server/helper failures no longer tear down shared runtime state, and Codex runtime models resolve first. This is continued hardening of the embedded-attempt takeover area (the #86184 family root cause landed in v5.26).
• Codex response timeouts are honored — reinforces that a provider-level timeoutSeconds (e.g. the OrbStack openai-codex 300s setting) is respected; keep that workaround in place, since backend latency itself is unchanged.
• Compaction session identity / snapshots preserved: rotated compaction session identity is preserved and compaction-timeout snapshots stay continuable, which helps long Codex sessions that compact frequently. Note: this is not a fix for the /btw /side after-compaction issue (#86393), which remains open.
• /status shows active subagent details — another surface to inspect subagents.

Security hardening — verify after upgrading the VM

v5.28 is heavy on input validation. Nothing in the default OrbStack config trips it, but it is worth a post-upgrade glance on a self-hosted Gateway:

• Stricter numeric / option validation (#87398): malformed numeric, timeout, and version options are rejected. The OrbStack timeoutSeconds:300, maxConcurrentRuns:2, and reserveTokensFloor:100000 are clean integers and pass.
• Workspace dotenv provider credentials are now ignored (#83655): provider credentials must come from the Gateway env (~/.openclaw/.env), not a workspace .env. The OrbStack flow already keeps secrets in the Gateway env, so it is unaffected.
• Browser / channel / network input hardening: tab indices, viewport sizes, CDP ports, cookie expiries, IPv6 no_proxy entries, provider/Discord retry headers, and cron epochs are validated more strictly.

Doctor non-interactive flow

Unchanged — verify-only. v5.28 introduces no new doctor confirmation prompts; the doctor changes are non-interactive migrations (legacy api_key profiles rewritten to canonical form, legacy memory auto-provider config migrated), and doctor now preserves explicit agentRuntime pins during Codex model migration. The wrapper's pre-archive + yes n defense in scripts/commands/update.sh remains safe. Post-upgrade, a clean ~/.openclaw/.update-doctor.log (no Setup cancelled) means all doctor passes completed.

Known active blockers (unchanged)

• #75593: subagent list visibility — the agent-tool list sees children, but /subagents list on a chat channel (e.g. Telegram) returns empty (channel-scoped requester key isn't canonicalized at the list boundary). Reopened and still unresolved in v5.28.
• #86393: /btw and /side (an alias of /btw) stop working after a long Codex session's first auto-compaction. Still open in v5.28.
• #86184: embedded-attempt session takeover falling back to a generic /new. Root-cause fix landed in v5.26; v5.28 adds further lock-release hardening (#88129).

Upgrade guidance

The Mac-side wrapper picks these doc updates up automatically. The VM-side openclaw Gateway upgrade is a separate decision; v5.28 carries no breaking config or installer changes for the OrbStack flow, so the upgrade is low-risk and mainly delivers Codex reliability and input-hardening.

v2026.5.27

Sync with upstream openclaw 2026.5.27.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

Wrapper changes

• VERSION + CLAUDE.md header bumped to v2026.5.27.
• templates/openclaw.json.example: documented two upstream changes as reference comments (no behavior change for the OrbStack flow):
  • No-auth Tailscale exposure is now rejected — exposing the Gateway over Tailscale requires an auth token (auth.mode: "token"). The OrbStack config already sets a Gateway auth token, so it is unaffected.
  • OpenAI-compatible embedding provider is now core (#85269) — local/hosted OpenAI-style endpoints can be used for memory-search embeddings without a plugin; the memory-specific embedding provider registration is deprecated (#85072).

No changes needed to openclaw-orbstack-setup.sh or scripts/commands/update.sh. v5.27 is overwhelmingly upstream bug fixes plus providers the OrbStack flow doesn't use (Pixverse video, DeepInfra, embeddings-as-core).

What v5.27 brings for the OrbStack flow

Mostly reliability work that benefits this topology (Codex subscription + Telegram + self-hosted Gateway):

• Codex app-server reliability (#87383, #87403, #87375, #72574, #87428): Codex runtime models resolve before generic routing, shared app-server clients survive startup and spawned-helper failures, native hook relay generations survive restarts and rotate on fresh fallbacks, false runtime live switches are avoided, and Codex OAuth compaction is routed through OpenAI-Codex.
• Telegram sendMessage actions use durable outbound delivery (#87261).
• Session write locks are released on timeout abort (#87278) — further hardening in the same area as the embedded-attempt takeover work.
• Faster Gateway and reply paths (#86439, #87044).

Security hardening — verify after upgrading the VM

v5.27 tightens several boundaries. Two are worth a quick post-upgrade check on a self-hosted Gateway:

• No-auth Tailscale exposure rejected — if you reach your Gateway over Tailscale, make sure an auth token is configured (it is in the default OrbStack setup). Confirm remote access still works after upgrading.
• Unsafe Node runtime env overrides blocked (#87308) — Node runtime-control env vars are now filtered from the shared host environment policy (including inherited-env filtering). If you set NODE_COMPILE_CACHE via a systemd drop-in, it is applied at the OS level on the Gateway process and should be unaffected; still, confirm the Gateway starts cleanly (worst case is a silent cache miss, not a crash).
• Stricter numeric config validation (#87398) — malformed numeric options (gateway timeouts, model/dir limits, message options, webhooks) are now rejected. Plain integer values are fine.

Doctor non-interactive flow

Unchanged — verify-only. v5.27 introduces no new doctor confirmation prompts, so the wrapper's pre-archive + yes n defense in scripts/commands/update.sh remains safe. Post-upgrade, a clean ~/.openclaw/.update-doctor.log (no Setup cancelled) means all doctor passes completed.

Known active blocker (unchanged)

• #75593: subagent list visibility — the agent-tool list sees children, but /subagents list on a chat channel (e.g. Telegram) returns empty (channel-scoped requester key isn't canonicalized at the list boundary). Still open in v5.27; a maintainer has indicated they will submit a fix.

Upgrade guidance

The Mac-side wrapper picks these doc updates up automatically. The VM-side openclaw Gateway upgrade is a separate decision; v5.27 carries no breaking config or installer changes for the OrbStack flow, so the upgrade is low-risk and mainly delivers Codex reliability and security hardening.

v2026.5.26

Sync with upstream openclaw 2026.5.26. Upstream skipped v5.23–v5.25 as stable, so v5.26 is a cumulative changelog from our v2026.5.20/v2026.5.22.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

Wrapper changes

• templates/openclaw.json.example: documented two new upstream defaults — cron.maxConcurrentRuns now defaults to 8 when unset (previously effectively 1), and gateway.auth.rateLimit now auto-enables a rate limiter on remote non-browser / HTTP auth failures when unset, with the loopback exemption preserved (#87148). Both are comment-only reference notes; the OrbStack config pins maxConcurrentRuns: 2 explicitly, so its behavior is unchanged.
• VERSION + CLAUDE.md header bumped to v2026.5.26.

No changes needed to openclaw-orbstack-setup.sh or scripts/commands/update.sh. The bulk of v5.26 is Gateway/perf work, transcripts-as-core, per-channel/voice bugfixes, and platform-specific (Windows/iOS/Android/Vertex/Alpine) work — none of which require wrapper updates.

Doctor non-interactive flow

Verified clean. v5.26's doctor-adjacent changes only reduce prompts: doctor skips a redundant Gateway restart prompt when a recent supervisor restart already left the Gateway healthy (#86533), and warns-and-continues instead of aborting when the cron store exists but cannot be read (#86384). No new interactive prompt is introduced, so the existing yes n pipe in both doctor passes remains safe. Post-upgrade verification: check ~/.openclaw/.update-doctor.log for Setup cancelled lines (a clean log means all doctor passes completed).

Notable upstream fixes for two issues we were tracking

v5.26 addresses both of the Codex-path pain points we hit recently — with no wrapper config change required:

• Embedded-attempt session takeover after a Codex timeout (#86184): previously, a Codex /responses guarded-fetch timeout could abort and self-write the session .jsonl during the released prompt-lock window, which the fence treated as a foreign mutation (EmbeddedAttemptSessionTakeoverError) and dropped the turn to a generic /new fallback even after the tool work succeeded. v5.26 keeps Codex turn timeouts inside the Codex runtime boundary so they no longer poison shared app-server clients or fall through to unrelated provider fallback (#86476, #86677), releases embedded-attempt session locks on all exits and from outer teardown (#86014, #85764), and reclaims wedged session lanes when stale active-run bookkeeping blocks queued work (#85639).
• Codex context-window prompt errors now recover gracefully: hitting the model's context-window limit now triggers overflow compaction with reset guidance instead of a hard failure (#85542), and overflow compaction budgets are derived from provider-reported and synthetic over-budget token counts so confirmed overflows compact before retrying (#70473). This does not change the ChatGPT-subscription input ceiling itself (still server-enforced), but hitting it is no longer a dead end.

Other notable upstream changes

• Codex CLI updated to 0.134.0, and native compaction stays disabled for budget-triggered app-server turns so OpenClaw owns the recovery boundary (#86772).
• Named model login profiles with supported credential migration for Hermes, OpenCode, and Codex auth profiles, including explicit opt-out and non-interactive controls (#85667). The migration runs during doctor with non-interactive controls; verify ~/.openclaw/.update-doctor.log after upgrade.
• Image backend replaced: Sharp is swapped for Rastermill for metadata, resizing, EXIF orientation, and PNG alpha-preserving optimization, so OpenClaw no longer installs Sharp or the WhatsApp Jimp fallback (#86437).
• Memory/dreaming: CJK-aware dreaming dedupe (#85060) and doctor no longer OOMs on large session stores (#82928).
• Gateway/perf: startup avoids repeated plugin/channel/session/usage-cost/warning/scheduled-service/filesystem scans, and reply delivery separates user-facing sends from slower follow-up work — visibly faster Gateway startup and replies.
• Security: default auth rate limiter for remote auth failures (#87148), Browser snapshot reads honor SSRF policy, fetched file text is wrapped as external content, and serialized tool-call text is scrubbed from replies.

Known active upstream blocker (unchanged)

• #75593: subagent list visibility — the agent-tool list sees children, but the /subagents list slash command on the same parent does not (alias canonicalization is not applied at the list boundary). PR #75679 is still open with no movement since 2026-05-15. v5.26 does not touch it.

Upgrade guidance

The Mac-side wrapper picks these doc updates up automatically — openclaw-update pulls the latest tag of this repo before each run. The VM-side openclaw Gateway upgrade is a separate decision. v5.26 carries no breaking config or installer changes for the OrbStack flow, so the upgrade is low-risk, and it is the recommended cut for anyone affected by the Codex takeover (#86184) or context-window dead-end behavior. The only open blocker (#75593) is a pre-existing subagent-list visibility issue that also affects v2026.5.20/v2026.5.22.

v2026.5.22

Sync with upstream openclaw 2026.5.22. Upstream skipped v5.21, so v5.22 is a cumulative changelog from our v2026.5.20; the v5.22-beta.1 intermediate has already been analyzed and its content is rolled into this stable cut.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

Wrapper changes

• docs/commands.md: documented the new upstream openclaw meeting-notes read-only CLI shipped in v5.22. This is a source-only external opt-in plugin (not bundled in the core npm package); it provides auto-start capture config, manual transcript imports, and a read-only CLI, with Discord voice as the first live source. The OrbStack wrapper does not pre-install it — openclaw meeting-notes only becomes available after you explicitly install that plugin.
• VERSION + CLAUDE.md header bumped to v2026.5.22.

No changes needed to openclaw-orbstack-setup.sh, scripts/commands/update.sh, or templates/openclaw.json.example. The bulk of v5.22 is Gateway/perf work, documentation, QA-Lab harness coverage, Windows-installer fixes, and per-channel bugfixes — none of which require wrapper updates.

Doctor non-interactive flow

Verified clean. v5.22's most notable doctor-adjacent change is the retired-model catalog prune (see below), which runs as an automatic doctor migration, not a new interactive prompt. The existing yes n pipe in scripts/commands/update.sh remains safe for both doctor passes. Post-upgrade verification: check ~/.openclaw/.update-doctor.log for Setup cancelled lines (a clean log means all doctor passes completed).

Notable upstream changes that affect existing users

• Retired-model catalog prune + doctor migration: v5.22 prunes retired Groq, GitHub Copilot, OpenAI, xAI, and old Claude catalog entries, with a doctor migration that upgrades existing configs to current provider refs. The wrapper's canonical model refs (openai/gpt-5.5 / openai/gpt-5.4 / openai/gpt-5.4-mini and the opencode/claude-opus-4-7 fallback) are all current and are not in the prune list, so the migration is a no-op for the default OrbStack config.
• Anthropic 1M context GA migration: 1M context handling now targets GA-capable Claude 4.x models directly, sizing eligible models at 1M without the retired context-1m-2025-08-07 beta and ignoring that retired beta in older configs while preserving OAuth-required Anthropic beta headers (#45613). The wrapper's Claude fallback routes through the opencode provider rather than Anthropic directly, so this is informational only.
• /models listing perf: provider auth-state is now pre-warmed at gateway startup, dropping per-call model-listing cost from ~20 s to ~5 ms (~4,100×) and re-warming after hot reloads (#84816). Makes /models and every model-listing path noticeably snappier.
• /exec host=node routing: when the effective exec host is node, native Code Mode is disabled while OpenClaw exec/process stay available, so /exec host=node routes shell commands through the selected node instead of the gateway (Fixes #85012). Relevant to the multi-Mac host-exec topology.
• Subagent / agent reliability: default sub-agent bootstrap context is now limited to AGENTS.md + TOOLS.md, keeping persona/identity/user/memory/heartbeat/setup files out of delegated workers (#85283); agent.wait returns phase-aware timeout attribution and only cools auth profiles on provider-started timeouts (refs #65504); session write-lock max-hold is now enforced at acquisition so long-held locks get reclaimed (#85764); and parallel OpenAI-compatible tool-call deltas are kept in separate argument buffers so interleaved tool calls no longer corrupt streamed arguments (#82263).
• Control UI thinking selector: the thinking selector is now disabled for known non-reasoning models instead of showing duplicate Off choices (#84069).
• macOS LaunchAgent / Windows installer hardening: numerous openclaw update restart and LaunchAgent reload fixes land in v5.22. These target the macOS app's launchd-supervised Gateway and native Windows installs — the OrbStack VM Gateway runs under systemd (systemctl --user), so they do not change the VM upgrade path.
• Security: protobufjs bumped to 8.4.0 to clear the current npm advisory, and OpenClaw-owned npm packages now ship with generated shrinkwrap so published installs use locked dependency graphs.

Resolved since v2026.5.20: the openai/* thinking blockers

The v2026.5.20 release flagged an umbrella of subagent/thinking blockers (#84489, #84646, #84706) where /think and sessions_spawn rejected every non-off thinking level on canonical openai/* models with Use one of: off. These are now resolved. The root cause turned out not to be the bundled catalog: incomplete models.providers.{openai,openai-codex}.models[] entries in user config triggered mergeProviderModels to strip the bundled compat / cost / model-level api metadata (the merge only falls back input + reasoning). Removing those incomplete user-config model blocks lets the complete bundled catalog flow through, and every thinking surface works again. All four issues are closed upstream.

Known active upstream blocker (unchanged)

One blocker remains open against upstream and is not addressed by this release:

• #75593: subagent list visibility — the agent-tool list sees children, but the /subagents list slash command on the same parent does not (alias canonicalization is not applied at the list boundary). PR #75679 (canonicalize requester keys) is still open and has had no movement since 2026-05-15. v5.22 does not touch it.

Upgrade guidance

The Mac-side wrapper picks these doc updates up automatically — openclaw-update pulls the latest tag of this repo before each run. The VM-side openclaw Gateway upgrade is a separate decision. v5.22 carries no breaking config or installer changes for the OrbStack flow, so the upgrade is low-risk; the only open blocker (#75593) is a pre-existing subagent-list visibility issue that also affects v2026.5.20.

v2026.5.20

Sync with upstream openclaw 2026.5.20. Single-step from our v2026.5.19; the v5.20-beta.1 and v5.20-beta.2 intermediates have already been analyzed and their content is rolled into this stable cut.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

Wrapper changes

• docs/commands.md: documented the new upstream CLI surfaces shipped in v5.20:
  • openclaw gateway status --json now includes the running Gateway version (upstream #56222).
  • openclaw tasks maintenance --json now enriches each retained / reconcile candidate with backing-session, cron, CLI, and wedged-subagent state (#84691).
  • /status now surfaces a hint and docs link when the session is pinned to a model other than agents.defaults.model.primary.
• VERSION + CLAUDE.md header bumped to v2026.5.20.

No changes needed to openclaw-orbstack-setup.sh, scripts/commands/update.sh, or templates/openclaw.json.example. The new @openai/codex 0.132.0 bundle, the new bundled Policy plugin, and the new agents.list[].experimental.localModelLean config option do not require wrapper updates; the Policy plugin's CLI surface is opt-in and can be inspected with openclaw plugins info policy after upgrading.

Behavior change to be aware of

v5.20 removes the legacy exec-approvals allowlist compatibility path for the cat SKILL.md && printf ... && <skill-wrapper> pattern. Skill files must now be loaded via the read tool, and only the real skill executable is auto-allowed. The wrapper itself does not use this pattern, so the OrbStack install flow is unaffected — but any user automation that relied on the old allowlist path inside the sandbox will need to switch to reading SKILL.md and invoking the skill executable directly.

Doctor non-interactive flow

Verified clean. v5.20 adds three doctor changes, all non-interactive:

• doctor now warns when the configured sandbox tool policy hides MCP server tools before provider requests (#84699) — warn-only.
• doctor now warns when openclaw.json stores plaintext secret-bearing config fields, including model provider API keys and sensitive provider headers (#84718) — warn-only; if you already use SecretRef indirection (the wrapper default), this is a no-op for you.
• doctor --fix now auto-removes unrecognized models.providers.*.models[*].compat.thinkingFormat values so post-upgrade configs validate cleanly (Fixes #77803) — silent auto-clean, no prompt.

The existing yes n pipe in scripts/commands/update.sh remains safe. Post-upgrade verification: check ~/.openclaw/.update-doctor.log for Setup cancelled lines (a clean log means all doctor passes completed).

Notable upstream fixes that affect existing users

• Codex auth precedence (/codex account): v5.20 finally honors explicit models auth order set and config.auth.order precedence over stale lastGood state, and shows no working credential when every explicit-order profile is ineligible instead of marking a lower-ranked profile as active (close #84386 via PR #84412). Useful for anyone who has trimmed their auth.order.openai array to a single OAuth profile.
• CLI update restart robustness: openclaw update no longer silently switches the gateway to a different Node binary when multiple Node installations are present, and restart health checks now survive one-version CLI/Gateway protocol skew. Helps the wrapper's openclaw-update end-to-end flow.
• Subagent / cron reliability cumulative fixes: stale completion handoff retry (#83699 / #83700), skip stale embedded-run wake probes for dormant completion requesters (#82964), trajectory queued-writer diagnostics in pi-trajectory-flush timeout warnings (#82961 / #82962), main-session cron runs on a cron-owned wake lane to keep background scheduled turns from blocking human main-session chat (#82766 / #82767), and recovered tool warnings now stay diagnostic instead of replacing final cron output (#84045). These reduce queue noise and stall risk but do not by themselves resolve the umbrella tracked in #84489.
• Anthropic shorthand routing: refs like anthropic/opus-4.7 selected with Claude CLI auth are now routed through the Claude CLI runtime instead of falling back to embedded Anthropic billing (Fixes #84222).

Known active upstream blockers (unchanged in v2026.5.20)

These remain open against upstream and are not addressed by this release:

• #84489: umbrella for subagent/Codex orchestration reliability — covers subagent list/control visibility (#75593 / #75679), isolated cron / delegated tool hydration (#84141), completion delivery / retry / terminal-state observability (#84053 / #84270 / #84272), and the missing spawn-time preflight contract. v5.20 lands cumulative chain fixes (see above) but the umbrella issues remain.
• #84646: /think picker on canonical openai/gpt-5.5 shows only default, off, and the /think directive rejects every non-off thinking level with Use one of: off. Root cause is the missing reasoning metadata on the canonical openai/* catalog entries. Workaround: set agents.defaults.thinkingDefault: "xhigh" at config time — the bot still uses xhigh for normal main-session turns, only the interactive /think switch on this model is blocked.
• #84706: sessions_spawn validation on the same canonical openai/* namespace rejects every non-off thinking level (a v5.19 regression vs. v5.18). Same root cause as #84646. No working subagent workaround in v5.20: forcing thinking: "off" on every subagent spawn loses the capability entirely, so subagents that need reasoning are currently blocked until upstream populates the catalog reasoning metadata for openai/gpt-5.5 / openai/gpt-5.4 / openai/gpt-5.4-mini.

Upgrade guidance

The Mac-side wrapper picks these doc updates up automatically — openclaw-update pulls the latest tag of this repo before each run. The VM-side openclaw Gateway upgrade is a separate decision: if you depend on the /think picker or on subagent thinking on canonical openai/* models, staying on v2026.5.19 (or v2026.5.18) until upstream fills the catalog reasoning metadata is a defensible choice.

v2026.5.19

Sync with upstream openclaw 2026.5.19. Single-step from our v2026.5.18; the v5.19-alpha.1 and v5.19-beta.1 intermediates have already been analyzed and their content is rolled into this stable cut.

Existing users: openclaw-update self-updates the wrapper repo before each run, so the next invocation picks up these changes automatically.

Wrapper changes

• docs/commands.md: documented new upstream CLI surfaces — openclaw skills install --global / openclaw skills update --global (#74466), openclaw browser dialog --dialog-id and openclaw browser evaluate --timeout-ms (#83447), and the chat command /codex plugins list / enable / disable.
• VERSION + CLAUDE.md header bumped to v2026.5.19.

No changes needed to openclaw-orbstack-setup.sh, scripts/commands/update.sh, or templates/openclaw.json.example. The Pi packages → 0.75.1 and Node.js 22.19 minimum bump from upstream do not affect us (we install Node 24 LTS), and the new image build args OPENCLAW_IMAGE_APT_PACKAGES / OPENCLAW_IMAGE_PIP_PACKAGES only matter when you custom-build the sandbox image, which we do not.

Doctor non-interactive flow

Verified clean. The v5.19 doctor migrations (oauthRef profile → inline credentials, stale timeoutMs cleanup, Anthropic CLI scope migration, non-loopback bind alias seeding for Control UI) all run automatically with no prompts. The only new interactive prompt anywhere in v5.19 is Android-specific (TLS thumbprint replacement, #83077) and does not affect our Linux/Mac flow. The existing yes n pipe in scripts/commands/update.sh remains safe. Post-upgrade verification: check ~/.openclaw/.update-doctor.log for Setup cancelled lines (a clean log means all doctor passes completed).

Notable upstream fix that affects past users

The /models picker auth-label drift we reported in openclaw#83574 is now fixed in v5.19 (PR #83726 / #83697). The picker now reflects the effective OpenAI/Codex auth profile from auth.order instead of falling back to the api-key env label. Routing was always correct in earlier releases; this resolves the UX drift only — no config change required after upgrade.

Known active upstream bugs (workarounds noted)

These are open against upstream and not fixed in v2026.5.19:

• #84489: umbrella for subagent/Codex orchestration reliability — covers subagent list/control visibility (#75593 / #75679), isolated cron / delegated tool hydration (#84141), completion delivery / retry / terminal-state observability (#84053 / #84270 / #84272), and the missing spawn-time preflight contract. No single workaround; observed symptoms are tracked individually as the chain issues land fixes.
• #84646: /think directive on canonical openai/gpt-5.5 rejects every non-off thinking level with Use one of: off, even though the picker (post-#82975 fix) now advertises the full range. The catalog-metadata / runtime-validation gap surfaces one layer below the picker filter that closed #82975. Workaround: set agents.defaults.thinkingDefault: "xhigh" at config time — the bot still uses xhigh for normal turns, only the interactive /think switch on this model is blocked.