feat capability CLI on latest main

Co-authored-by: Owen <oh.whenever@gmail.com>

.agents/skills/openclaw-parallels-smoke/SKILL.md

@@ -17,6 +17,7 @@ Use this skill for Parallels guest workflows and smoke interpretation. Do not lo
 - Per-phase logs land under `/tmp/openclaw-parallels-*`.
 - Do not run local and gateway agent turns in parallel on the same fresh workspace or session.
 - If `main` is moving under active multi-agent work, prefer a detached worktree pinned to one commit for long Parallels suites. The smoke scripts now verify the packed tgz commit instead of live `git rev-parse HEAD`, but a pinned worktree still avoids noisy rebuild/version drift during reruns.
+- For `openclaw update --channel dev` lanes, remember the guest clones GitHub `main`, not your local worktree. If a local fix exists but the rerun still fails inside the cloned dev checkout, do not treat that as disproof of the fix until the branch has been pushed.
 - For `prlctl exec`, pass the VM name before `--current-user` (`prlctl exec "$VM" --current-user ...`), not the other way around.
 - If the workflow installs OpenClaw from a repo checkout instead of the site installer/npm release, finish by installing a real guest CLI shim and verifying it in a fresh guest shell. `pnpm openclaw ...` inside the repo is not enough for handoff parity.
 - On macOS guests, prefer a user-global install plus a stable PATH-visible shim:
@@ -79,7 +80,9 @@ Use this skill for Parallels guest workflows and smoke interpretation. Do not lo
 - Windows installer/tgz phases now retry once after guest-ready recheck; keep new Windows smoke steps idempotent so a transport-flake retry is safe.
 - If a Windows retry sees the VM become `suspended` or `stopped`, resume/start it before the next `prlctl exec`; otherwise the second attempt just repeats the same `rc=255`.
 - Windows global `npm install -g` phases can stay quiet for a minute or more even when healthy; inspect the phase log before calling it hung, and only treat it as a regression once the retry wrapper or timeout trips.
+- When those Windows global installs stay quiet, the useful progress often lives in the guest npm debug log, not the helper phase log. The smoke script now streams incremental `npm-cache/_logs/*-debug-0.log` deltas into the phase log during long baseline/package installs; read those lines before assuming the lane is stalled.
 - The Windows baseline-package helpers now auto-dump the latest guest `npm-cache/_logs/*-debug-0.log` tail on timeout or nonzero completion. Read that tail in the phase log before opening a second guest shell.
+- The same incremental npm-debug streaming also applies to `--upgrade-from-packed-main` / packaged-install baseline phases. A phase log that still says only `install.start`, `install.download-tgz`, `install.install-tgz` can still be healthy if the streamed npm-debug section shows registry fetches or bundled-plugin postinstall work.
 - Fresh Windows tgz install phases should also use the background PowerShell runner plus done-file/log-drain pattern; do not rely on one long-lived `prlctl exec ... powershell ... npm install -g` transport for package installs.
 - Windows release-to-dev helpers should log `where pnpm` before and after the update and require `where pnpm` to succeed post-update. That proves the updater installed or enabled `pnpm` itself instead of depending on a smoke-only bootstrap.
 - Fresh Windows ref-mode onboard should use the same background PowerShell runner plus done-file/log-drain pattern as the npm-update helper, including startup materialization checks, host-side timeouts on short poll `prlctl exec` calls, and retry-on-poll-failure behavior for transient transport flakes.

.github/labeler.yml

@@ -241,6 +241,10 @@
   - changed-files:
       - any-glob-to-any-file:
           - "extensions/open-prose/**"
+"extensions: webhooks":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/webhooks/**"
 "extensions: device-pair":
   - changed-files:
       - any-glob-to-any-file:
@@ -253,6 +257,10 @@
   - changed-files:
       - any-glob-to-any-file:
           - "extensions/acpx/**"
+"extensions: arcee":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/arcee/**"
 "extensions: byteplus":
   - changed-files:
       - any-glob-to-any-file:

.github/workflows/ci.yml

@@ -743,6 +743,16 @@ jobs:
         continue-on-error: true
         run: pnpm run lint:extensions:no-relative-outside-package
 
+      - name: Run extension channel lint
+        id: extension_channel_lint
+        continue-on-error: true
+        run: pnpm run lint:extensions:channels
+
+      - name: Run bundled extension lint
+        id: extension_bundled_lint
+        continue-on-error: true
+        run: pnpm run lint:extensions:bundled
+
       - name: Enforce safe external URL opening policy
         id: no_raw_window_open
         continue-on-error: true
@@ -785,6 +795,8 @@ jobs:
           EXTENSION_SRC_OUTSIDE_PLUGIN_SDK_BOUNDARY_OUTCOME: ${{ steps.extension_src_outside_plugin_sdk_boundary.outcome }}
           EXTENSION_PLUGIN_SDK_INTERNAL_BOUNDARY_OUTCOME: ${{ steps.extension_plugin_sdk_internal_boundary.outcome }}
           EXTENSION_RELATIVE_OUTSIDE_PACKAGE_BOUNDARY_OUTCOME: ${{ steps.extension_relative_outside_package_boundary.outcome }}
+          EXTENSION_CHANNEL_LINT_OUTCOME: ${{ steps.extension_channel_lint.outcome }}
+          EXTENSION_BUNDLED_LINT_OUTCOME: ${{ steps.extension_bundled_lint.outcome }}
           NO_RAW_WINDOW_OPEN_OUTCOME: ${{ steps.no_raw_window_open.outcome }}
           CONTROL_UI_I18N_OUTCOME: ${{ steps.control_ui_i18n.outcome == 'skipped' && 'success' || steps.control_ui_i18n.outcome }}
           GATEWAY_WATCH_REGRESSION_OUTCOME: ${{ steps.gateway_watch_regression.outcome }}
@@ -806,6 +818,8 @@ jobs:
             "extension-src-outside-plugin-sdk-boundary|$EXTENSION_SRC_OUTSIDE_PLUGIN_SDK_BOUNDARY_OUTCOME" \
             "extension-plugin-sdk-internal-boundary|$EXTENSION_PLUGIN_SDK_INTERNAL_BOUNDARY_OUTCOME" \
             "extension-relative-outside-package-boundary|$EXTENSION_RELATIVE_OUTSIDE_PACKAGE_BOUNDARY_OUTCOME" \
+            "lint:extensions:channels|$EXTENSION_CHANNEL_LINT_OUTCOME" \
+            "lint:extensions:bundled|$EXTENSION_BUNDLED_LINT_OUTCOME" \
             "lint:ui:no-raw-window-open|$NO_RAW_WINDOW_OPEN_OUTCOME" \
             "ui:i18n:check|$CONTROL_UI_I18N_OUTCOME" \
             "gateway-watch-regression|$GATEWAY_WATCH_REGRESSION_OUTCOME"; do

.oxlintrc.json

@@ -25,8 +25,8 @@
   "ignorePatterns": [
     "assets/",
     "dist/",
+    "dist-runtime/",
     "docs/_layouts/",
-    "extensions/",
     "node_modules/",
     "patches/",
     "pnpm-lock.yaml",
@@ -34,6 +34,36 @@
     "src/auto-reply/reply/export-html/template.js",
     "src/canvas-host/a2ui/a2ui.bundle.js",
     "Swabble/",
-    "vendor/"
+    "vendor/",
+    "**/.cache/**",
+    "**/build/**",
+    "**/coverage/**",
+    "**/dist/**",
+    "**/dist-runtime/**",
+    "**/node_modules/**"
+  ],
+  "overrides": [
+    {
+      "files": [
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "**/*.e2e.test.ts",
+        "**/*.live.test.ts",
+        "**/*test-harness.ts",
+        "**/*test-helpers.ts",
+        "**/*test-support.ts"
+      ],
+      "rules": {
+        "typescript/await-thenable": "off",
+        "typescript/no-base-to-string": "off",
+        "typescript/no-explicit-any": "off",
+        "typescript/no-floating-promises": "off",
+        "typescript/no-misused-spread": "off",
+        "typescript/no-redundant-type-constituents": "off",
+        "typescript/no-unnecessary-template-expression": "off",
+        "typescript/unbound-method": "off",
+        "eslint/no-unsafe-optional-chaining": "off"
+      }
+    }
   ]
 }

AGENTS.md

@@ -132,7 +132,7 @@
 - Type-check/build: `pnpm build`
 - TypeScript checks: `pnpm tsgo`
 - Lint/format: `pnpm check`
-- Local agent/dev shells default to lower-memory `OPENCLAW_LOCAL_CHECK=1` behavior for `pnpm tsgo` and `pnpm lint`; set `OPENCLAW_LOCAL_CHECK=0` in CI/shared runs.
+- Local agent/dev shells default to host-aware `OPENCLAW_LOCAL_CHECK=1` behavior for `pnpm tsgo` and `pnpm lint`; set `OPENCLAW_LOCAL_CHECK_MODE=throttled` to force the lower-memory profile, `OPENCLAW_LOCAL_CHECK_MODE=full` to keep lock-only behavior, or `OPENCLAW_LOCAL_CHECK=0` in CI/shared runs.
 - Format check: `pnpm format` (oxfmt --check)
 - Format fix: `pnpm format:fix` (oxfmt --write)
 - Terminology:
@@ -296,7 +296,7 @@
 
 - When working on a GitHub Issue or PR, print the full URL at the end of the task.
 - When answering questions, respond with high-confidence answers only: verify in code; do not guess.
-- Never update the Carbon dependency.
+- Carbon: prefer latest published beta over stable when possible; do not switch to stable casually.
 - Any dependency with `pnpm.patchedDependencies` must use an exact version (no `^`/`~`).
 - Patching dependencies (pnpm patches, overrides, or vendored changes) requires explicit approval; do not do this by default.
 - **Multi-agent safety:** do **not** create/apply/drop `git stash` entries unless explicitly requested (this includes `git pull --rebase --autostash`). Assume other agents may be working; keep unrelated WIP untouched and avoid cross-cutting state changes.

CHANGELOG.md

@@ -4,11 +4,71 @@ Docs: https://docs.openclaw.ai
 
 ## Unreleased
 
+### Changes
+
+- CLI/capabilities: add a first-class `openclaw capability ...` hub for provider-backed inference workflows across model, media, web, and embedding tasks, with capability inspection, provider discovery, and consistent JSON output. Thanks @Takhoffman.
+- Providers/Anthropic: restore Claude CLI as the preferred local Anthropic path in onboarding, model-auth guidance, and doctor flows again, and keep the Docker Claude CLI live lane aligned with the restored guidance.
+- Plugins/webhooks: add a bundled webhook ingress plugin so external automation can create and drive bound TaskFlows through per-route shared-secret endpoints. (#61892) Thanks @mbelinky.
+- Tools/media: document per-provider music and video generation capabilities, and add shared live video-to-video sweep coverage for providers that support local reference clips.
+
 ### Fixes
 
+- CLI/capabilities: keep provider-backed capability behavior aligned with actual runtime execution by fixing explicit TTS override handling, profile-aware gateway TTS prefs resolution, per-request transcription `prompt`/`language` overrides, image output MIME/extension mismatches, configured web-search fallback behavior, and agent-vs-CLI web-search execution drift.
+- Channels/secrets: keep bundled channel artifact and secret-contract loading stable under lazy loading so bundled channel secrets continue to appear in `openclaw secret`, status, and security-audit surfaces.
+- Providers/xAI: recognize `api.grok.x.ai` as an xAI-native endpoint again so native xAI web-search attribution keeps working on Grok-hosted base URLs. (#61377) Thanks @jjjojoj.
+- Providers/Anthropic/cache: preserve thinking blocks for Claude Opus 4.5+, Sonnet 4.5+, and newer Claude 4-family models so Anthropic prompt-cache prefixes keep matching after thinking turns. (#61793)
+- Auth/OpenAI Codex OAuth: reload fresh on-disk credentials inside the locked refresh path and retry once after `refresh_token_reused` rotates only the stored refresh token, so relogin/restart recovery stops getting stuck on stale cached auth state. Thanks @owen-ever.
+- Providers/Ollama: honor the selected provider's `baseUrl` during streaming so multi-Ollama setups stop routing every stream to the first configured Ollama endpoint. (#61678)
+- Browser/remote CDP: retry the DevTools websocket once after remote browser restarts so healthy remote browser profiles do not fail availability checks during CDP warm-up. (#57397) Thanks @ThanhNguyxn07.
+- Memory/vector recall: surface explicit warnings when `sqlite-vec` is unavailable or vector writes are degraded so memory indexing no longer reports false-success while semantic recall is impaired.
+- MS Teams/security: validate file-consent upload URLs against HTTPS, Microsoft/SharePoint host allowlists, and private-IP DNS checks before uploading attachments, blocking SSRF-style consent-upload abuse. (#23596)
+- Discord/gateway monitor: use `ws://` again for gateway monitor sockets so Discord monitor connections recover reliably after recent gateway socket changes.
+- Control UI/auth URLs: detect mistaken `?token=` links, show the correct `#token=` fragment hint only on real auth failures, and stop masking the real problem behind a generic device-identity error. (#54842)
+- Control UI/chat layout: keep Copy and Canvas actions plus mobile exec-approval overlays from covering chat text or command previews on narrow screens. (#61514)
+- Matrix/formatting: preserve multi-paragraph and loose-list rendering in Element so numbered and bulleted Markdown keeps its content attached to the correct list item. (#60997) Thanks @gucasbrg.
+- Sessions/model selection: resolve the explicitly selected session model separately from runtime fallback resolution so session status and live model switching stay aligned with the chosen model.
+- Secrets/x_search: keep legacy `x_search` auth resolution working so older xAI web-search configs continue to load after the plugin-owned auth move.
+- iOS/Watch exec approvals: keep Apple Watch review and approval recovery working while the iPhone is locked or backgrounded, including background-safe reconnects, persisted pending approvals, notification cleanup, and APNs-backed watch refresh recovery. (#61757) Thanks @ngutman.
+- Discord/forwarding: recover forwarded referenced message text and attachments when Discord omits snapshot payloads, so forwarded-message relays keep the original content. (#61670) Thanks @artwalker.
+- TUI/status: route `/status` through the shared session-status command and move the old gateway-wide diagnostic summary to `/gateway-status` (`/gwstatus`). Thanks @vincentkoc.
+- TUI/history and heartbeat: keep assistant commentary hidden on both streamed and reloaded TUI history views, preserve the phase-sanitized REST history contract, and stop forced heartbeat runs from targeting subagent sessions. (#61463) Thanks @100yenadmin.
+- TUI/command messages: strip inbound envelope metadata before rendering command/system messages so async completion notices stop leaking raw wrappers into the operator terminal. (#59985) Thanks @MoerAI.
+- TUI/terminal: restore Kitty keyboard protocol and `modifyOtherKeys` state on TUI exit and fatal CLI crashes so parent shells stop inheriting broken keyboard input after `openclaw tui` exits. (#49130) Thanks @biefan.
+- Plugins/Windows: load plugin entrypoints through `file://` import specifiers on Windows without breaking plugin SDK alias resolution, fixing `ERR_UNSUPPORTED_ESM_URL_SCHEME` for absolute plugin paths. (#61832) Thanks @Zeesejo.
+- Plugins/Windows: disable native Jiti loading for setup and doctor contract registries on Windows so onboarding and config-doctor plugin probes stop crashing with `ERR_UNSUPPORTED_ESM_URL_SCHEME`. (#61836, #61853)
+- Plugins/install: preserve plugin-schema defaults during fresh-install raw config validation so bundled plugin installs stop failing when required fields rely on schema defaults. (#61856) Thanks @SuperMarioYL.
+- macOS/gateway version: strip trailing commit metadata from CLI version output before semver parsing so the Mac app recognizes installed gateway versions like `OpenClaw 2026.4.2 (d74a122)` again. (#61111) Thanks @oliviareid-svg.
+- Gateway/containers: auto-bind to `0.0.0.0` during container startup for Docker and Podman compatibility, while keeping host-side status and doctor checks on the hardened loopback default when `gateway.bind` is unset. (#61818) Thanks @openperf.
+- Gateway/status: probe local TLS gateways over `wss://`, forward the local cert fingerprint for self-signed loopback probes, and warn when the local TLS runtime cannot load the configured cert. (#61935) Thanks @ThanhNguyxn07.
+- Slack/threading: keep legacy thread stickiness for real replies when older callers omit `isThreadReply`, while still honoring `replyToMode` for Slack's auto-created top-level `thread_ts`. (#61835) Thanks @kaonash.
+- Discord/voice: re-arm DAVE receive passthrough without suppressing decrypt-failure rejoin recovery, and clear capture state before finalize teardown so rapid speaker restarts keep their next utterance. (#41536) Thanks @wit-oc.
+- Providers/Google: recognize Gemma model ids in native Google forward-compat resolution, keep the requested provider when cloning fallback templates, and force Gemma reasoning off so Gemma 4 routes stop failing through the Google catalog fallback. (#61507) Thanks @eyjohn.
 - Providers/Anthropic: skip `service_tier` injection for OAuth-authenticated stream wrapper requests so Claude OAuth requests stop failing with HTTP 401. (#60356) thanks @openperf.
+- Providers/OpenAI: keep WebSocket text buffered until a real assistant phase arrives, even when text deltas land before a phaseless `output_item.added` announcement. (#61954) Thanks @100yenadmin.
+- Providers/OpenAI: accept case-insensitive `plugins.entries.openai.config.personality` values, keep unknown overrides on the friendly overlay path, and add `on` as an alias for `friendly`. Thanks @vincentkoc.
+- Discord/thread titles: stop forcing a hardcoded temperature for generated auto-thread names so Codex-backed thread title generation works on `openai-codex/*` models again. (#59525)
+- Agents/message tool: add a `read` plus `threadId` discoverability hint when the configured channel actions support threaded message reads.
+- Agents/context overflow: combine oversized and aggregate tool-result recovery in one repair pass, and restore a total-context overflow backstop during tool loops so recoverable sessions retry instead of failing early. (#61651) Thanks @Takhoffman.
 - Agents/exec: preserve explicit `host=node` routing under elevated defaults when `tools.exec.host=auto`, and fail loud on invalid elevated cross-host overrides. (#61739) Thanks @obviyus.
+- Agents/heartbeat: stop truncating live session transcripts after no-op heartbeat acks, move heartbeat cleanup to prompt assembly and compaction, and keep post-filter context-engine ingestion aligned with the real session baseline. (#60998) Thanks @nxmxbbd.
+- Gateway/TUI: defer terminal chat finalization for per-attempt lifecycle errors so fallback retries keep streaming before the run is marked failed. (#60043) Thanks @jwchmodx.
+- Gateway/history: seed SSE startup history and raw transcript sequence tracking from one initial transcript snapshot so first history events cannot diverge from subsequent message sequence numbering. (#61855) Thanks @100yenadmin.
+- Agents/history: keep history-based reply reads and subagent completion summaries on `final_answer` text only so internal commentary stops leaking into user-visible follow-up replies. (#61747) Thanks @afurm.
+- Agents/history: suppress commentary-only visible-text leaks in streaming and chat history views, and keep sanitized SSE history sequence numbers monotonic after transcript-only refreshes. (#61829) Thanks @100yenadmin.
+- Agents/history: use one shared assistant-visible sanitizer across embedded delivery and chat-history extraction so leaked `<tool_call>` and `<tool_result>` XML blocks stay hidden from user-facing replies. (#61729) Thanks @openperf.
+- Agents/history: keep truly legacy unsigned replay text unphased when mixed with phased OpenAI WS assistant blocks, while still inheriting message phase for id-only replay signatures. (#61529) Thanks @100yenadmin.
+- Memory/dreaming: strip managed Light Sleep and REM blocks before daily-note ingestion so dreaming summaries stop re-ingesting their own staged output into new candidates. (#61720) Thanks @MonkeyLeeT.
+- Docs/i18n: relocalize final localized-page links after translation so generated locale pages stop keeping stale English-root links when targets appear later in the same run. (#61796) thanks @hxy91819.
 - Docs/i18n: remove the zh-CN homepage redirect override so Mintlify can resolve the localized Chinese homepage without self-redirecting `/zh-CN/index`.
+- Tools/web_fetch and web_search: fix `TypeError: fetch failed` caused by undici 8.0 enabling HTTP/2 by default; pinned SSRF-guard dispatchers now explicitly set `allowH2: false` to restore HTTP/1.1 behavior and keep the custom DNS-pinning lookup compatible. (#61738, #61777) Thanks @zozo123.
+- Agents/session keys: backfill `sessionKey` from `sessionId` in the embedded PI runner when callers omit it, so hooks, LCM, and compaction receive a valid key; also normalize whitespace-only session keys to `undefined` before downstream consumers see them. (#60555) Thanks @100yenadmin.
+- Plugins/provider hooks: stop recursive provider snapshot loads from overflowing the stack during plugin initialization, while still preserving cached nested provider-hook results. (#61922, #61938, #61946, #61951)
+- Discord/voice: re-arm DAVE receive passthrough without suppressing decrypt-failure rejoin recovery, and clear capture state before finalize teardown so rapid speaker restarts keep their next utterance. (#41536) Thanks @wit-oc.
+- Agents/exec: keep `strictInlineEval` commands blocked after approval timeouts on both gateway and node exec hosts, so timeout fallback no longer turns timed-out inline interpreter prompts into automatic execution.
+- QQ Bot/media: route gateway-side attachment and fallback downloads through guarded QQ/Tencent HTTPS fetches so QQ media handling no longer follows arbitrary remote hosts.
+- Exec/runtime events: mark background `notifyOnExit` summaries and ACP parent-stream relays as untrusted system events so lower-trust runtime output no longer re-enters later turns as trusted `System:` text.
+- Hooks/wake: queue direct and mapped wake-hook payloads as untrusted system events so external wake content no longer enters the main session as trusted input. (#62003)
+
 ## 2026.4.5
 
 ### Breaking
@@ -19,6 +79,7 @@ Docs: https://docs.openclaw.ai
 
 - Agents/video generation: add the built-in `video_generate` tool so agents can create videos through configured providers and return the generated media directly in the reply.
 - Agents/music generation: ignore unsupported optional hints such as `durationSeconds` with a warning instead of hard-failing requests on providers like Google Lyria.
+- Providers/Arcee AI: add a bundled Arcee AI provider plugin with `ARCEEAI_API_KEY` onboarding, Trinity model catalog (mini, large-preview, large-thinking), OpenAI-compatible API support, and OpenRouter as an alternative auth path. (#62068) Thanks @arthurbr11.
 - Providers/ComfyUI: add a bundled `comfy` workflow media plugin for local ComfyUI and Comfy Cloud workflows, including shared `image_generate`, `video_generate`, and workflow-backed `music_generate` support, with prompt injection, optional reference-image upload, live tests, and output download.
 - Tools/music generation: add the built-in `music_generate` tool with bundled Google (Lyria) and MiniMax providers plus workflow-backed Comfy support, including async task tracking and follow-up delivery of finished audio.
 - Providers: add bundled Qwen, Fireworks AI, and StepFun providers, plus MiniMax TTS, Ollama Web Search, and MiniMax Search integrations for chat, speech, and search workflows. (#60032, #55921, #59318, #54648)
@@ -48,8 +109,9 @@ Docs: https://docs.openclaw.ai
 - Agents/cache: stabilize cache-relevant system prompt fingerprints by normalizing equivalent structured prompt whitespace, line endings, hook-added system context, and runtime capability ordering so semantically unchanged prompts reuse KV/cache more reliably. Thanks @vincentkoc.
 - Agents/tool prompts: remove the duplicate in-band tool inventory from agent system prompts so tool-calling models rely on the structured tool definitions as the single source of truth, improving prompt stability and reducing stale tool guidance.
 - Config/schema: enrich the exported `openclaw config schema` JSON Schema with field titles and descriptions so editors, agents, and other schema consumers receive the same config help metadata. (#60067) Thanks @solavrc.
-- Providers/CLI: remove bundled CLI text-provider backends and the `agents.defaults.cliBackends` surface, while keeping ACP harness sessions and Gemini media understanding on the native bundled providers.
 - Matrix/exec approvals: clarify unavailable-approval replies so Matrix no longer claims chat approvals are unsupported when native exec approvals are merely unconfigured. (#61424) Thanks @gumadeiras.
+- Providers/OpenAI Codex: add forward-compat `openai-codex/gpt-5.4-mini` synthesis across provider runtime, model catalog, and model listing so Codex mini works before bundled Pi catalog updates land.
+- Providers/OpenAI: add an opt-in GPT personality and move GPT-5 prompt tuning onto provider-owned system-prompt contributions so cache-stable guidance stays above the prompt cache boundary and embedded runner paths reuse the same provider-specific prompt behavior.
 - Docs/IRC: replace public IRC hostname examples with `irc.example.com` and recommend private servers for bot coordination while listing common public networks for intentional use.
 - Memory/dreaming: group nearby daily-note lines into short coherent chunks before staging them for dreaming, so one-off context from recent notes reaches REM/deep with better evidence and less line-level noise.
 - Memory/dreaming: drop generic date/day headings from daily-note chunk prefixes while keeping meaningful section labels, so staged snippets stay cleaner and more reusable. (#61597) Thanks @mbelinky.
@@ -59,6 +121,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Control UI/chat: show `/tts` and other local audio-only slash replies in webchat by embedding local audio in the assistant message and rendering `<audio>` controls instead of dropping empty-text finals. Fixes #61564. (#61598) Thanks @neeravmakwana.
 - Security: preserve restrictive plugin-only tool allowlists, require owner access for `/allowlist add` and `/allowlist remove`, fail closed when `before_tool_call` hooks crash, block browser SSRF redirect bypasses earlier, and keep non-interactive auth-choice inference scoped to bundled and already-trusted plugins. (#58476, #59836, #59822, #58771, #59120) Thanks @eleqtrizit and @pgondhi987.
 - Providers/OpenAI: make GPT-5 and Codex runs act sooner with lower-verbosity defaults, visible progress during tool work, and a one-shot retry when a turn only narrates the plan instead of taking action.
 - Providers/OpenAI and reply delivery: preserve native `reasoning.effort: "none"` and strict schemas where supported, add GPT-5.4 assistant `phase` metadata across replay and the Gateway `/v1/responses` layer, and keep commentary buffered until `final_answer` so web chat, session previews, embedded replies, and Telegram partials stop leaking planning text. Fixes #59150, #59643, #61282.
@@ -66,6 +129,8 @@ Docs: https://docs.openclaw.ai
 - Telegram: restore DM voice-note preflight transcription so direct-message audio stops arriving as raw `<media:audio>` placeholders. (#61008) Thanks @manueltarouca.
 - Telegram/reasoning: only create a Telegram reasoning preview lane when the session is explicitly `reasoning:stream`, so hidden `<think>` traces from streamed replies stop surfacing as chat previews on normal sessions. Thanks @vincentkoc.
 - Telegram/native command menu: trim long menu descriptions before dropping commands so sub-100 command sets can still fit Telegram's payload budget and keep more `/` entries visible. (#61129) Thanks @neeravmakwana.
+- Telegram/startup: bound `deleteWebhook`, `getMe`, and `setWebhook` startup requests while keeping the longer `getUpdates` poll timeout, so wedged Telegram control-plane calls stop hanging startup indefinitely. (#61601) Thanks @neeravmakwana.
+- Agents/failover: classify Anthropic "extra usage" exhaustion as billing so same-turn model fallback still triggers when Claude blocks long-context requests on usage limits. (#61608) Thanks @neeravmakwana.
 - Discord: keep REST, webhook, and monitor traffic on the configured proxy, preserve component-only media sends, honor `@everyone` and `@here` mention gates, keep ACK reactions on the active account, and split voice connect/playback timeouts so auto-join is more reliable. (#57465, #60361, #60345) Thanks @geekhuashan.
 - Discord/reply tags: strip leaked `[[reply_to_current]]` control tags from preview text and honor explicit reply-tag threading during final delivery, so Discord replies stay attached to the triggering message instead of printing reply metadata into chat.
 - Discord/replies: replace the unshipped `replyToOnlyWhenBatched` flag with `replyToMode: "batched"` so native reply references only attach on debounced multi-message turns while explicit reply tags still work.
@@ -242,6 +307,7 @@ Docs: https://docs.openclaw.ai
 - Plugins: suppress trust-warning noise during non-activating snapshot and CLI metadata loads. (#61427) Thanks @gumadeiras.
 - Agents/video generation: accept `agents.defaults.videoGenerationModel` in strict config validation and `openclaw config set/get`, so gateways using `video_generate` no longer fail to boot after enabling a video model.
 - Matrix/streaming: add a quiet preview mode for streamed Matrix replies, keep legacy `partial` preview-first behavior, and finalize quiet media captions correctly so previews stop notifying early without dropping final text semantics. (#61450) Thanks @gumadeiras.
+- Agents/compaction: skip redundant partial summarization when no messages were oversized, so the same transcript is not summarized twice after a full summarization failure. Fixes #61465. (#61603) Thanks @neeravmakwana.
 - Gateway/shutdown: bound websocket-server shutdown even when no tracked clients remain, so gateway restarts stop hanging until the watchdog kills the process. (#61565) Thanks @mbelinky.
 - Control UI/multilingual: localize the remaining shared channel, instances, nodes, and gateway-confirmation strings so the dashboard stops mixing translated UI with hardcoded English labels. Thanks @vincentkoc.
 - Discord/media: raise the default inbound and outbound media cap to `100MB` so Discord matches Telegram more closely and larger attachments stop failing on the old low default.
@@ -250,6 +316,86 @@ Docs: https://docs.openclaw.ai
 - Matrix: avoid failing startup when token auth already knows the user ID but still needs optional device metadata, retry transient auth bootstrap requests, and backfill missing device IDs after startup while keeping unknown-device storage reuse conservative until metadata is repaired. (#61383) Thanks @gumadeiras.
 - Agents/exec: stop streaming `tool_execution_update` events after an exec session backgrounds, preventing delayed background output from hitting a stale listener and crashing the gateway while keeping the output available through `process poll/log`. (#61627) Thanks @openperf.
 - Matrix: pass configured `deviceId` through health probes and keep probe-only client setup out of durable Matrix storage, so health checks preserve the correct device identity without rewriting `storage-meta.json` or related probe state on disk. (#61581) Thanks @MoerAI.
+  ||||||| parent of b4694a4ac7 (Telegram: add outbound chunker regression coverage)
+- Image generation/build: write stable runtime alias files into `dist/` and route provider-auth runtime lookups through those aliases so image-generation providers keep resolving auth/runtime modules after rebuilds instead of crashing on missing hashed chunk files.
+- Config/runtime: pin the first successful config load in memory for the running process and refresh that snapshot on successful writes/reloads, so hot paths stop reparsing `openclaw.json` between watcher-driven swaps.
+- Config/legacy cleanup: stop probing obsolete alternate legacy config names and service labels during local config/service detection, while keeping the active `~/.openclaw/openclaw.json` path canonical.
+- ACP/sessions_spawn: register ACP child runs for completion tracking and lifecycle cleanup, and make registration-failure cleanup explicitly best-effort so callers do not assume an already-started ACP turn was fully aborted. (#40885) Thanks @xaeon2026 and @vincentkoc.
+- ACP/tasks: mark cleanly exited ACP runs as blocked when they end on deterministic write or authorization blockers, and wake the parent session with a follow-up instead of falsely reporting success.
+- ACPX/runtime: derive the bundled ACPX expected version from the extension package metadata instead of hardcoding a separate literal, so plugin-local ACPX installs stop drifting out of health-check parity after version bumps. (#49089) Thanks @jiejiesks and @vincentkoc.
+- Gateway/auth: make local-direct `trusted-proxy` fallback require the configured shared token instead of silently authenticating same-host callers, while keeping same-host reverse proxy identity-header flows on the normal trusted-proxy path. Thanks @zhangning-agent and @vincentkoc.
+- Memory/QMD: send MCP `query` collection filters as the upstream `collections` array instead of the legacy singular `collection` field, so mcporter-backed QMD 1.1+ searches still scope correctly after the unified `query` tool migration. (#54728) Thanks @armanddp and @vincentkoc.
+- Memory/QMD: keep `qmd embed` active in `search` mode too, so BM25-first setups still build a complete index for later vector and hybrid retrieval. (#54509) Thanks @hnshah and @vincentkoc.
+- Memory/QMD: point `QMD_CONFIG_DIR` at the nested `xdg-config/qmd` directory so per-agent collection config resolves correctly. (#39078) Thanks @smart-tinker and @vincentkoc.
+- Memory/QMD: include deduplicated default plus per-agent `memorySearch.extraPaths` when building QMD custom collections, so shared and agent-specific extra roots both get indexed consistently. (#57315) Thanks @Vitalcheffe and @vincentkoc.
+- Memory/session indexer: include `.jsonl.reset.*` and `.jsonl.deleted.*` transcripts in the memory host session scan while still excluding `.jsonl.bak.*` compaction backups and lock files, so memory search sees archived session history without duplicating stale snapshots. Thanks @hclsys and @vincentkoc.
+- Agents/sandbox: honor `tools.sandbox.tools.alsoAllow`, let explicit sandbox re-allows remove matching built-in default-deny tools, and keep sandbox explain/error guidance aligned with the effective sandbox tool policy. (#54492) Thanks @ngutman.
+- LINE/ACP: add current-conversation binding and inbound binding-routing parity so `/acp spawn ... --thread here`, configured ACP bindings, and active conversation-bound ACP sessions work on LINE like the other conversation channels.
+- LINE/markdown: preserve underscores inside Latin, Cyrillic, and CJK words when stripping markdown, while still removing standalone `_italic_` markers on the shared text-runtime path used by LINE and TTS. (#47465) Thanks @jackjin1997.
+- TTS/Microsoft: auto-switch the default Edge voice to Chinese for CJK-dominant text without overriding explicitly selected Microsoft voices. (#52355) Thanks @extrasmall0.
+- Agents/context pruning: count supplementary-plane CJK characters with the shared code-point-aware estimator so context pruning stops underestimating Japanese and Chinese text that uses Extension B ideographs. (#39985) Thanks @Edward-Qiang-2024.
+- Slack/status reactions: add a reaction lifecycle for queued, thinking, tool, done, and error phases in Slack monitors, with safer cleanup so queued ack reactions stay correct across silent runs, pre-reply failures, and delayed transitions. (#56430) Thanks @hsiaoa.
+- macOS/local gateway: stop OpenClaw.app from killing healthy local gateway listeners after startup by recognizing the current `openclaw-gateway` process title and using the current `openclaw gateway` launch shape.
+- Gateway/OpenAI compatibility: accept flat Responses API function tool definitions on `/v1/responses` and preserve `strict` when normalizing hosted tools into the embedded runner, so spec-compliant clients like Codex no longer fail validation or silently lose strict tool enforcement. Thanks @malaiwah and @vincentkoc.
+- Memory/QMD: resolve slugified `memory_search` file hints back to the indexed filesystem path before returning search hits, so `memory_get` works again for mixed-case and spaced paths. (#50313) Thanks @erra9x.
+- OpenAI/Codex fast mode: map `/fast` to priority processing on native OpenAI and Codex Responses endpoints instead of rewriting reasoning settings, and document the exact endpoint and override behavior.
+- Memory/QMD: weight CJK-heavy text correctly when estimating chunk sizes, preserve surrogate-pair characters during fine splits, and keep long Latin lines on the old chunk boundaries so memory indexing produces better-sized chunks for CJK notes. (#40271) Thanks @AaronLuo00.
+- Security/LINE: make webhook signature validation run the timing-safe compare even when the supplied signature length is wrong, closing a small timing side-channel. (#55663) Thanks @gavyngong.
+- LINE/status: stop `openclaw status` from warning about missing credentials when sanitized LINE snapshots are already configured, while still surfacing whether the missing field is the token or secret. (#45701) Thanks @tamaosamu.
+- Gateway/health: carry webhook-vs-polling account mode from channel descriptors into runtime snapshots so passive channels like LINE and BlueBubbles skip false stale-socket health failures. (#47488) Thanks @karesansui-u.
+- Agents/MCP: reuse bundled MCP runtimes across turns in the same session, while recreating them when MCP config changes and disposing stale runtimes cleanly on session rollover. (#55090) Thanks @allan0509.
+- Memory/QMD: honor `memory.qmd.update.embedInterval` even when regular QMD update cadence is disabled or slower by arming a dedicated embed-cadence maintenance timer, while avoiding redundant timers when regular updates are already frequent enough. (#37326) Thanks @barronlroth.
+- Memory/QMD: add `memory.qmd.searchTool` as an exact mcporter tool override, so custom QMD MCP tools such as `hybrid_search` can be used without weakening the validated `searchMode` config surface. (#27801) Thanks @keramblock.
+- Memory/QMD: keep reset and deleted session transcripts in QMD session export so daily session resets do not silently drop most historical recall from `memory_search`. (#30220) Thanks @pushkarsingh32.
+- Memory/QMD: rebind collections when QMD reports a changed pattern but omits path metadata, so config pattern changes stop being silently ignored on restart. (#49897) Thanks @Madruru.
+- Memory/QMD: warn explicitly when `memory.backend=qmd` is configured but the `qmd` binary is missing, so doctor and runtime fallback no longer fail as a silent builtin downgrade. (#50439) Thanks @Jimmy-xuzimo and @vincentkoc.
+- Memory/QMD: pass a direct-session key on `openclaw memory search` so CLI QMD searches no longer get denied as `session=<none>` under direct-only scope defaults. (#43517) Thanks @waynecc-at and @vincentkoc.
+- Memory/QMD: keep `memory_search` session-hit paths roundtrip-safe when exported session markdown lives under the workspace `qmd/` directory, so `memory_get` can read the exact returned path instead of failing on the generic `qmd/sessions/...` alias. (#43519) Thanks @holgergruenhagen and @vincentkoc.
+- Agents/memory flush: keep daily memory flush files append-only during embedded attempts so compaction writes do not overwrite earlier notes. (#53725) Thanks @HPluseven.
+- Web UI/markdown: stop bare auto-links from swallowing adjacent CJK text while preserving valid mixed-script path and query characters in rendered links. (#48410) Thanks @jnuyao.
+- BlueBubbles/iMessage: coalesce URL-only inbound messages with their link-preview balloon again so sharing a bare link no longer drops the URL from agent context. Thanks @vincentkoc.
+- Sandbox/browser: install `fonts-noto-cjk` in the sandbox browser image so screenshots render Chinese, Japanese, and Korean text correctly instead of tofu boxes. Fixes #35597. Thanks @carrotRakko and @vincentkoc.
+- Memory/FTS: add configurable trigram tokenization plus short-CJK substring fallback so memory search can find Chinese, Japanese, and Korean text without breaking mixed long-and-short queries. Thanks @carrotRakko.
+- Hooks/config: accept runtime channel plugin ids in `hooks.mappings[].channel` (for example `feishu`) instead of rejecting non-core channels during config validation. (#56226) Thanks @AiKrai001.
+- TUI/chat: keep optimistic outbound user messages visible during active runs by deferring local-run binding until the first gateway chat event reveals the real run id, preventing premature history reloads from wiping pending local sends. (#54722) Thanks @seanturner001.
+- TUI/model picker: keep searchable `/model` and `/models` input mode from hijacking `j`/`k` as navigation keys, and harden width bounds under `m`-filtered model lists so search no longer crashes on long rows. (#30156) Thanks @briannicholls.
+- Agents/Kimi: preserve already-valid Anthropic-compatible tool call argument objects while still clearing cached repairs when later trailing junk exceeds the repair allowance. (#54491) Thanks @yuanaichi.
+- Docker/setup: force BuildKit for local image builds (including sandbox image builds) so `./docker-setup.sh` no longer fails on `RUN --mount=...` when hosts default to Docker's legacy builder. (#56681) Thanks @zhanghui-china.
+- Control UI/agents: auto-load agent workspace files on initial Files panel open, and populate overview model/workspace/fallbacks from effective runtime agent metadata so defaulted models no longer show as `Not set`. (#56637) Thanks @dxsx84.
+- Control UI/slash commands: make `/steer` and `/redirect` work from the chat command palette with visible pending state for active-run `/steer`, correct redirected-run tracking, and a single canonical `/steer` entry in the command menu. (#54625) Thanks @fuller-stack-dev.
+- Exec/runtime: default implicit exec to `host=auto`, resolve that target to sandbox only when a sandbox runtime exists, keep explicit `host=sandbox` fail-closed without sandbox, and show `/exec` effective host state in runtime status/docs.
+- Exec: fail closed when the implicit sandbox host has no sandbox runtime, and stop denied async approval followups from reusing prior command output from the same session. (#56800) Thanks @scoootscooob.
+- Exec/approvals: infer Discord and Telegram exec approvers from existing owner config when `execApprovals.approvers` is unset, extend the default approval window to 30 minutes, and clarify approval-unavailable guidance so approvals do not appear to silently disappear.
+- Exec/node: stop gateway-side workdir fallback from rewriting explicit `host=node` cwd values to the gateway filesystem, so remote node exec approval and runs keep using the intended node-local directory. (#50961) Thanks @openperf.
+- Plugins/ClawHub: sanitize temporary archive filenames for scoped package names and slash-containing skill slugs so `openclaw plugins install @scope/name` no longer fails with `ENOENT` during archive download. (#56452) Thanks @soimy.
+- Telegram/polling: keep the watchdog from aborting long-running reply delivery by treating recent non-polling API activity as bounded liveness instead of a hard stall. (#56343) Thanks @openperf.
+- Memory/FTS: keep provider-less keyword hits visible at the default memory-search threshold, so FTS-only recall works without requiring `--min-score 0`. (#56473) Thanks @opriz.
+- Memory/LanceDB: resolve runtime dependency manifest lookup from the bundled `extensions/memory-lancedb` path (including flattened dist chunks) so startup no longer fails with a missing `@lancedb/lancedb` dependency error. (#56623) Thanks @LUKSOAgent.
+- Tools/web_search: localize the shared search cache to module scope so same-process global symbol lookups can no longer inspect or mutate cached web-search responses. Thanks @vincentkoc.
+- Agents/silent turns: fail closed on silent memory-flush runs so narrated `NO_REPLY` self-talk cannot stream or finalize into external replies even when block streaming is enabled. (#52593)
+- Browser/plugins: auto-enable the bundled browser plugin when browser config or browser tool policy already references it, and show a clearer CLI error when `plugins.allow` excludes `browser`.
+- Matrix/plugin loading: ship and source-load the crypto bootstrap runtime sidecar correctly so current `main` stops warning about failed Matrix bootstrap loads and `matrix/index` plugin-id mismatches on every invocation. (#53298) thanks @keithce.
+- iOS/Live Activities: mark the `ActivityKit` import in `LiveActivityManager.swift` as `@preconcurrency` so Xcode 26.4 / Swift 6 builds stop failing on strict concurrency checks. (#57180) Thanks @ngutman.
+- Plugins/Matrix: mirror the Matrix crypto WASM runtime dependency into the root packaged install and enforce root/plugin dependency parity so bundled Matrix E2EE crypto resolves correctly in shipped builds. (#57163) Thanks @gumadeiras.
+- Plugins/CLI: add descriptor-backed lazy plugin CLI registration so Matrix can keep its CLI module lazy-loaded without dropping `openclaw matrix ...` from parse-time command registration. (#57165) Thanks @gumadeiras.
+- Plugins/CLI: collect root-help plugin descriptors through a dedicated non-activating CLI metadata path so enabled plugins keep validated config semantics without triggering runtime-only plugin registration work, while preserving runtime CLI command registration for legacy channel plugins that still wire commands from full registration. (#57294) thanks @gumadeiras.
+- Anthropic/OAuth: inject `/fast` `service_tier` hints for direct `sk-ant-oat-*` requests so OAuth-authenticated Anthropic runs stop missing the same overload-routing signal as API-key traffic. Fixes #55758. Thanks @Cypherm and @vincentkoc.
+- Anthropic/service tiers: support explicit `serviceTier` model params for direct Anthropic requests and let them override `/fast` defaults when both are set. (#45453) Thanks @vincentkoc.
+- Auto-reply/fast: accept `/fast status` on the directive-only path, align help/status text with the documented `status|on|off` syntax, and keep current-state replies consistent across command surfaces. Fixes #46095. Thanks @weissfl and @vincentkoc.
+- Telegram/native commands: prefix native command menu callback payloads and preserve `CommandSource: "native"` when Telegram replays them through callback queries, so `/fast` and other native command menus keep working even when text-command routing is disabled. Thanks @vincentkoc.
+- Docs/anchors: fix broken English docs links and make Mint anchor audits run against the English-source docs tree. (#57039) thanks @velvet-shark.
+- Cron/announce: preserve all deliverable text payloads for announce mode instead of collapsing to the last chunk, so multi-line cron reports deliver in full to Telegram forum topics.
+- Harden async approval followup delivery in webchat-only sessions (#57359) Thanks @joshavant.
+- Status: fix cache hit rate exceeding 100% by deriving denominator from prompt-side token fields instead of potentially undersized totalTokens. Fixes #26643.
+- Config/update: stop `openclaw doctor` write-backs from persisting plugin-injected channel defaults, so `openclaw update` no longer seeds config keys that later break service refresh validation. (#56834) Thanks @openperf.
+- Agents/Anthropic failover: treat Anthropic `api_error` payloads with `An unexpected error occurred while processing the response` as transient so retry/fallback can engage instead of surfacing a terminal failure. (#57441) Thanks @zijiess and @vincentkoc.
+- Agents/compaction: keep late compaction-retry rejections handled after the aggregate timeout path wins without swallowing real pre-timeout wait failures, so timed-out retries no longer surface an unhandled rejection on later unsubscribe. (#57451) Thanks @mpz4life and @vincentkoc.
+- Matrix/delivery recovery: treat Synapse `User not in room` replay failures as permanent during startup recovery so poisoned queued messages move to `failed/` instead of crash-looping Matrix after restart. (#57426) thanks @dlardo.
+- Plugins/facades: guard bundled plugin facade loads with a cache-first sentinel so circular re-entry stops crashing `xai`, `sglang`, and `vllm` during gateway plugin startup. (#57508) Thanks @openperf.
+- Agents/MCP: dispose bundled MCP runtimes after one-shot `openclaw agent --local` runs finish, while preserving bundled MCP state across in-run retries so local JSON runs exit cleanly without restarting stateful MCP tools mid-run.
+- Gateway/OpenAI HTTP: restore default operator scopes for bearer-authenticated requests that omit `x-openclaw-scopes`, so headless `/v1/chat/completions` and session-history callers work again after the recent method-scope hardening. (#57596) Thanks @openperf.
+- Gateway/attachments: offload large inbound images without leaking `media://` markers into text-only runs, preserve mixed attachment order for model input/transcripts, and fail closed when model image capability cannot be resolved. (#55513) Thanks @Syysean.
+- Telegram/outbound chunking: use static markdown chunking when Telegram runtime state is unavailable so long outbound Telegram messages still split correctly after cold starts. (#57816) Thanks @ForestDengHK.
 
 ## 2026.4.2
 
@@ -815,6 +961,7 @@ Docs: https://docs.openclaw.ai
 - Security/path resolution: prefer non-user-writable absolute helper binaries for OpenClaw CLI, ffmpeg, and OpenSSL resolution so PATH hijacks cannot replace trusted helpers with attacker-controlled executables.
 - Security/gateway command scopes: require `operator.admin` before Telegram target writeback and Talk Voice `/voice set` config writes persist through gateway message flows.
 - Security/OpenShell mirror: exclude workspace `hooks/` from mirror sync so untrusted sandbox files cannot become trusted host hooks on gateway startup.
+- Exec env policy: block Mercurial config redirects, Rust compiler wrappers, and GNU make flag env vars in host exec sanitization so inherited env and request-scoped overrides cannot redirect build-tool execution.
 
 ## 2026.3.24-beta.2
 

Dockerfile

@@ -64,7 +64,7 @@ WORKDIR /app
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
 COPY ui/package.json ./ui/package.json
 COPY patches ./patches
-COPY scripts/postinstall-bundled-plugins.mjs scripts/npm-runner.mjs ./scripts/
+COPY scripts/postinstall-bundled-plugins.mjs scripts/npm-runner.mjs scripts/windows-cmd-helpers.mjs ./scripts/
 
 COPY --from=ext-deps /out/ ./${OPENCLAW_BUNDLED_PLUGIN_DIR}/
 

appcast.xml

@@ -6,7 +6,7 @@
             <title>2026.4.5</title>
             <pubDate>Mon, 06 Apr 2026 04:55:17 +0100</pubDate>
             <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
-            <sparkle:version>2026040501</sparkle:version>
+            <sparkle:version>2026040590</sparkle:version>
             <sparkle:shortVersionString>2026.4.5</sparkle:shortVersionString>
             <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
             <description><![CDATA[<h2>OpenClaw 2026.4.5</h2>
@@ -436,4 +436,4 @@
             <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.4.1/OpenClaw-2026.4.1.zip" length="25841903" type="application/octet-stream" sparkle:edSignature="0TPiyshScmwDbgs626JU08NOUUFJmIsVFa5g0xmizfl64Fr+IoT4l/dkXarFqbZAJidtj5WN7Bff7fG8ye/7AA=="/>
         </item>
     </channel>
-</rss>
+</rss>

apps/ios/Config/Signing.xcconfig

@@ -3,19 +3,23 @@
 
 OPENCLAW_IOS_DEFAULT_TEAM = Y5PE65HELJ
 OPENCLAW_IOS_SELECTED_TEAM = $(OPENCLAW_IOS_DEFAULT_TEAM)
+OPENCLAW_DEVELOPMENT_TEAM = $(OPENCLAW_IOS_SELECTED_TEAM)
+OPENCLAW_CODE_SIGN_STYLE = Automatic
 OPENCLAW_APP_BUNDLE_ID = ai.openclaw.client
 OPENCLAW_WATCH_APP_BUNDLE_ID = ai.openclaw.client.watchkitapp
 OPENCLAW_WATCH_EXTENSION_BUNDLE_ID = ai.openclaw.client.watchkitapp.extension
 OPENCLAW_ACTIVITY_WIDGET_BUNDLE_ID = ai.openclaw.client.activitywidget
+OPENCLAW_WATCH_APP_PROFILE =
+OPENCLAW_WATCH_EXTENSION_PROFILE =
 
 // Local contributors can override this by running scripts/ios-configure-signing.sh.
 // Keep include after defaults: xcconfig is evaluated top-to-bottom.
 #include? "../.local-signing.xcconfig"
 #include? "../LocalSigning.xcconfig"
 
-CODE_SIGN_STYLE = Automatic
+CODE_SIGN_STYLE = $(OPENCLAW_CODE_SIGN_STYLE)
 CODE_SIGN_IDENTITY = Apple Development
-DEVELOPMENT_TEAM = $(OPENCLAW_IOS_SELECTED_TEAM)
+DEVELOPMENT_TEAM = $(OPENCLAW_DEVELOPMENT_TEAM)
 
-// Let Xcode manage provisioning for the selected local team.
+// Let Xcode manage provisioning for the selected local team unless a local override pins one.
 PROVISIONING_PROFILE_SPECIFIER =

apps/ios/LocalSigning.xcconfig.example

@@ -13,3 +13,5 @@ OPENCLAW_WATCH_EXTENSION_BUNDLE_ID = ai.openclaw.client.watchkitapp.extension
 // Leave empty with automatic signing.
 OPENCLAW_APP_PROFILE =
 OPENCLAW_SHARE_PROFILE =
+OPENCLAW_WATCH_APP_PROFILE =
+OPENCLAW_WATCH_EXTENSION_PROFILE =

apps/ios/README.md

@@ -148,6 +148,9 @@ pnpm ios:beta
 - Local/manual builds default to `OpenClawPushTransport=direct` and `OpenClawPushDistribution=local`.
 - Your selected team/profile must support Push Notifications for the app bundle ID you are signing.
 - If push capability or provisioning is wrong, APNs registration fails at runtime (check Xcode logs for `APNs registration failed`).
+- The gateway host also needs direct APNs auth configured separately with `OPENCLAW_APNS_TEAM_ID`, `OPENCLAW_APNS_KEY_ID`, and either `OPENCLAW_APNS_PRIVATE_KEY_P8` or `OPENCLAW_APNS_PRIVATE_KEY_PATH`.
+- Recommended gateway-host storage for the APNs `.p8` file is `~/.openclaw/credentials/apns/AuthKey_<KEYID>.p8` with restrictive permissions, then point `OPENCLAW_APNS_PRIVATE_KEY_PATH` at that file.
+- `apps/ios/fastlane/.env` only covers App Store Connect / Fastlane auth; it does not provide gateway APNs credentials for local direct-push testing.
 - Debug builds default to `OpenClawPushAPNsEnvironment=sandbox`; Release builds default to `production`.
 
 ## APNs Expectations For Official Builds

apps/ios/Sources/Model/NodeAppModel.swift

@@ -61,9 +61,10 @@ final class NodeAppModel {
         let request: AgentDeepLink
     }
 
-    struct ExecApprovalPrompt: Identifiable, Equatable {
+    struct ExecApprovalPrompt: Identifiable, Equatable, Codable, Sendable {
         let id: String
         let commandText: String
+        let commandPreview: String?
         let allowedDecisions: [String]
         let host: String?
         let nodeId: String?
@@ -82,11 +83,17 @@ final class NodeAppModel {
         case failed(message: String)
     }
 
+    private struct PersistedWatchExecApprovalBridgeState: Codable {
+        var approvals: [ExecApprovalPrompt]
+        var pendingApprovalIDs: [String]?
+    }
+
     private let deepLinkLogger = Logger(subsystem: "ai.openclaw.ios", category: "DeepLink")
     private let pushWakeLogger = Logger(subsystem: "ai.openclaw.ios", category: "PushWake")
     private let pendingActionLogger = Logger(subsystem: "ai.openclaw.ios", category: "PendingAction")
     private let locationWakeLogger = Logger(subsystem: "ai.openclaw.ios", category: "LocationWake")
     private let watchReplyLogger = Logger(subsystem: "ai.openclaw.ios", category: "WatchReply")
+    private let watchExecApprovalLogger = Logger(subsystem: "ai.openclaw.ios", category: "WatchExecApproval")
     private let execApprovalNotificationLogger = Logger(
         subsystem: "ai.openclaw.ios",
         category: "ExecApprovalNotification")
@@ -166,6 +173,8 @@ final class NodeAppModel {
     private var backgroundReconnectLeaseUntil: Date?
     private var lastSignificantLocationWakeAt: Date?
     @ObservationIgnored private let watchReplyCoordinator = WatchReplyCoordinator()
+    private var watchExecApprovalPromptsByID: [String: ExecApprovalPrompt] = [:]
+    private var pendingWatchExecApprovalRecoveryIDs: [String] = []
     private var pendingForegroundActionDrainInFlight = false
 
     private var gatewayConnected = false
@@ -179,6 +188,8 @@ final class NodeAppModel {
     var operatorSession: GatewayNodeSession { self.operatorGateway }
     private(set) var activeGatewayConnectConfig: GatewayConnectConfig?
 
+    private static let watchExecApprovalBridgeStateKey = "watch.execApproval.bridge.state.v1"
+
     var cameraHUDText: String?
     var cameraHUDKind: CameraHUDKind?
     var cameraFlashNonce: Int = 0
@@ -213,12 +224,40 @@ final class NodeAppModel {
         self.watchMessagingService = watchMessagingService
         self.talkMode = talkMode
         self.apnsDeviceTokenHex = UserDefaults.standard.string(forKey: Self.apnsDeviceTokenUserDefaultsKey)
+        self.restorePersistedWatchExecApprovalBridgeState()
         GatewayDiagnostics.bootstrap()
+        GatewayDiagnostics.log("node app model: init start")
+        self.watchMessagingService.setStatusHandler { [weak self] status in
+            Task { @MainActor in
+                GatewayDiagnostics.log(
+                    "node app model: watch status callback reachable=\(status.reachable) activation=\(status.activationState) backgrounded=\(self?.isBackgrounded ?? false)")
+                await self?.handleWatchMessagingStatusChanged(status)
+            }
+        }
         self.watchMessagingService.setReplyHandler { [weak self] event in
             Task { @MainActor in
                 await self?.handleWatchQuickReply(event)
             }
         }
+        self.watchMessagingService.setExecApprovalResolveHandler { [weak self] event in
+            Task { @MainActor in
+                await self?.handleWatchExecApprovalResolve(event)
+            }
+        }
+        self.watchMessagingService.setExecApprovalSnapshotRequestHandler { [weak self] event in
+            Task { @MainActor in
+                guard let self else { return }
+                GatewayDiagnostics.log(
+                    "node app model: watch snapshot request id=\(event.requestId) backgrounded=\(self.isBackgrounded)")
+                guard self.isBackgrounded else {
+                    self.watchExecApprovalLogger.debug(
+                        "watch exec approval snapshot skipped reason=watch_request_foreground")
+                    GatewayDiagnostics.log("node app model: watch snapshot request skipped in foreground")
+                    return
+                }
+                await self.refreshWatchExecApprovalSnapshotOnDemand(reason: "watch_request")
+            }
+        }
 
         self.voiceWake.configure { [weak self] cmd in
             guard let self else { return }
@@ -335,6 +374,7 @@ final class NodeAppModel {
 
     func setScenePhase(_ phase: ScenePhase) {
         let keepTalkActive = UserDefaults.standard.bool(forKey: "talk.background.enabled")
+        GatewayDiagnostics.log("node app model: scene phase=\(String(describing: phase))")
         switch phase {
         case .background:
             self.isBackgrounded = true
@@ -2476,6 +2516,7 @@ extension NodeAppModel {
     func onNodeGatewayConnected() async {
         await self.registerAPNsTokenIfNeeded()
         await self.flushQueuedWatchRepliesIfConnected()
+        await self.syncWatchExecApprovalSnapshot(reason: "node_connected")
         await self.resumePendingForegroundNodeActionsIfNeeded(trigger: "node_connected")
     }
 
@@ -2622,6 +2663,378 @@ extension NodeAppModel {
         return lines.joined(separator: "\n")
     }
 
+    private func restorePersistedWatchExecApprovalBridgeState() {
+        guard let data = UserDefaults.standard.data(forKey: Self.watchExecApprovalBridgeStateKey),
+              let state = try? JSONDecoder().decode(PersistedWatchExecApprovalBridgeState.self, from: data)
+        else {
+            return
+        }
+        self.watchExecApprovalPromptsByID = Dictionary(
+            uniqueKeysWithValues: state.approvals.map { ($0.id, $0) })
+        self.pendingWatchExecApprovalRecoveryIDs = (state.pendingApprovalIDs ?? [])
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .sorted()
+        self.pruneExpiredWatchExecApprovalPrompts()
+    }
+
+    private func persistWatchExecApprovalBridgeState() {
+        self.pruneExpiredWatchExecApprovalPrompts()
+        let approvals = self.watchExecApprovalPromptsByID.values.sorted { lhs, rhs in
+            let lhsExpires = lhs.expiresAtMs ?? Int.max
+            let rhsExpires = rhs.expiresAtMs ?? Int.max
+            if lhsExpires != rhsExpires {
+                return lhsExpires < rhsExpires
+            }
+            return lhs.id < rhs.id
+        }
+        let pendingApprovalIDs = self.pendingWatchExecApprovalRecoveryIDs
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .sorted()
+        guard let data = try? JSONEncoder().encode(
+            PersistedWatchExecApprovalBridgeState(
+                approvals: approvals,
+                pendingApprovalIDs: pendingApprovalIDs))
+        else {
+            return
+        }
+        UserDefaults.standard.set(data, forKey: Self.watchExecApprovalBridgeStateKey)
+    }
+
+    private func pruneExpiredWatchExecApprovalPrompts(nowMs: Int? = nil) {
+        let currentNowMs = nowMs ?? Int(Date().timeIntervalSince1970 * 1000)
+        self.watchExecApprovalPromptsByID = self.watchExecApprovalPromptsByID.filter { _, prompt in
+            guard let expiresAtMs = prompt.expiresAtMs else { return true }
+            return expiresAtMs > currentNowMs
+        }
+    }
+
+    private func handleWatchMessagingStatusChanged(_ status: WatchMessagingStatus) async {
+        GatewayDiagnostics.log(
+            "watch exec approval: status changed reachable=\(status.reachable) activation=\(status.activationState) backgrounded=\(self.isBackgrounded)")
+        guard self.isBackgrounded else { return }
+        guard status.supported, status.paired, status.appInstalled else { return }
+        guard status.reachable || status.activationState == "activated" else { return }
+        let reason = status.reachable ? "watch_reachable" : "watch_activated"
+        await self.syncWatchExecApprovalSnapshot(reason: reason)
+    }
+
+    private func appendPendingWatchExecApprovalRecoveryID(_ approvalId: String) {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+        guard !self.pendingWatchExecApprovalRecoveryIDs.contains(normalizedApprovalID) else { return }
+        self.pendingWatchExecApprovalRecoveryIDs.append(normalizedApprovalID)
+        self.pendingWatchExecApprovalRecoveryIDs.sort()
+        GatewayDiagnostics.log(
+            "watch exec approval: queued recovery id=\(normalizedApprovalID) pendingCount=\(self.pendingWatchExecApprovalRecoveryIDs.count)")
+        self.persistWatchExecApprovalBridgeState()
+    }
+
+    private func removePendingWatchExecApprovalRecoveryID(_ approvalId: String) {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+        let originalCount = self.pendingWatchExecApprovalRecoveryIDs.count
+        self.pendingWatchExecApprovalRecoveryIDs.removeAll { $0 == normalizedApprovalID }
+        guard self.pendingWatchExecApprovalRecoveryIDs.count != originalCount else { return }
+        GatewayDiagnostics.log(
+            "watch exec approval: cleared recovery id=\(normalizedApprovalID) pendingCount=\(self.pendingWatchExecApprovalRecoveryIDs.count)")
+        self.persistWatchExecApprovalBridgeState()
+    }
+
+    private func upsertWatchExecApprovalPrompt(_ prompt: ExecApprovalPrompt) {
+        self.watchExecApprovalPromptsByID[prompt.id] = prompt
+        self.removePendingWatchExecApprovalRecoveryID(prompt.id)
+        self.persistWatchExecApprovalBridgeState()
+    }
+
+    private func removeWatchExecApprovalPrompt(_ approvalId: String) {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+        self.watchExecApprovalPromptsByID.removeValue(forKey: normalizedApprovalID)
+        self.removePendingWatchExecApprovalRecoveryID(normalizedApprovalID)
+        self.persistWatchExecApprovalBridgeState()
+    }
+
+    private static func makeWatchExecApprovalItem(from prompt: ExecApprovalPrompt) -> OpenClawWatchExecApprovalItem {
+        let decisions = prompt.allowedDecisions.compactMap { decision in
+            let normalizedDecision = decision.trimmingCharacters(in: .whitespacesAndNewlines)
+            return OpenClawWatchExecApprovalDecision(rawValue: normalizedDecision)
+        }
+        let preview = Self.trimmedOrNil(prompt.commandPreview) ?? Self.trimmedOrNil(prompt.commandText)
+        return OpenClawWatchExecApprovalItem(
+            id: prompt.id,
+            commandText: prompt.commandText,
+            commandPreview: preview,
+            host: Self.trimmedOrNil(prompt.host),
+            nodeId: Self.trimmedOrNil(prompt.nodeId),
+            agentId: Self.trimmedOrNil(prompt.agentId),
+            expiresAtMs: prompt.expiresAtMs,
+            allowedDecisions: decisions,
+            // Prefer the watch's neutral/default presentation until exec.approval.get
+            // carries an explicit risk signal for exec approvals.
+            risk: nil)
+    }
+
+    nonisolated private static func shouldResetWatchExecApprovalResolvingStateOnPrompt(
+        reason: String) -> Bool
+    {
+        reason == "resolve_retry"
+    }
+
+    private func publishWatchExecApprovalPrompt(_ prompt: ExecApprovalPrompt, reason: String) async {
+        let message = OpenClawWatchExecApprovalPromptMessage(
+            approval: Self.makeWatchExecApprovalItem(from: prompt),
+            sentAtMs: Int(Date().timeIntervalSince1970 * 1000),
+            deliveryId: UUID().uuidString,
+            resetResolvingState: Self.shouldResetWatchExecApprovalResolvingStateOnPrompt(reason: reason))
+        do {
+            _ = try await self.watchMessagingService.sendExecApprovalPrompt(message)
+            self.watchExecApprovalLogger.debug(
+                "watch exec approval prompt sent id=\(prompt.id, privacy: .public) reason=\(reason, privacy: .public)")
+        } catch {
+            self.watchExecApprovalLogger.error(
+                "watch exec approval prompt failed id=\(prompt.id, privacy: .public) reason=\(reason, privacy: .public) error=\(error.localizedDescription, privacy: .public)")
+        }
+        await self.syncWatchExecApprovalSnapshot(reason: "\(reason)_snapshot")
+    }
+
+    private func publishWatchExecApprovalResolved(
+        approvalId: String,
+        decision: OpenClawWatchExecApprovalDecision?,
+        source: String) async
+    {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+        self.removeWatchExecApprovalPrompt(normalizedApprovalID)
+        let message = OpenClawWatchExecApprovalResolvedMessage(
+            approvalId: normalizedApprovalID,
+            decision: decision,
+            resolvedAtMs: Int(Date().timeIntervalSince1970 * 1000),
+            source: source)
+        do {
+            _ = try await self.watchMessagingService.sendExecApprovalResolved(message)
+        } catch {
+            self.watchExecApprovalLogger.error(
+                "watch exec approval resolved update failed id=\(normalizedApprovalID, privacy: .public) error=\(error.localizedDescription, privacy: .public)")
+        }
+        await self.syncWatchExecApprovalSnapshot(reason: "resolved_snapshot")
+    }
+
+    private func publishWatchExecApprovalExpired(
+        approvalId: String,
+        reason: OpenClawWatchExecApprovalCloseReason) async
+    {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+        self.removeWatchExecApprovalPrompt(normalizedApprovalID)
+        let message = OpenClawWatchExecApprovalExpiredMessage(
+            approvalId: normalizedApprovalID,
+            reason: reason,
+            expiredAtMs: Int(Date().timeIntervalSince1970 * 1000))
+        do {
+            _ = try await self.watchMessagingService.sendExecApprovalExpired(message)
+        } catch {
+            self.watchExecApprovalLogger.error(
+                "watch exec approval expiry update failed id=\(normalizedApprovalID, privacy: .public) error=\(error.localizedDescription, privacy: .public)")
+        }
+        await self.syncWatchExecApprovalSnapshot(reason: "expired_\(reason.rawValue)")
+    }
+
+    private func syncWatchExecApprovalSnapshot(reason: String) async {
+        self.pruneExpiredWatchExecApprovalPrompts()
+        GatewayDiagnostics.log(
+            "watch exec approval: sync snapshot start reason=\(reason) cacheCount=\(self.watchExecApprovalPromptsByID.count) backgrounded=\(self.isBackgrounded)")
+        let approvals = self.watchExecApprovalPromptsByID.values
+            .sorted { lhs, rhs in
+                let lhsExpires = lhs.expiresAtMs ?? Int.max
+                let rhsExpires = rhs.expiresAtMs ?? Int.max
+                if lhsExpires != rhsExpires {
+                    return lhsExpires < rhsExpires
+                }
+                return lhs.id < rhs.id
+            }
+            .map(Self.makeWatchExecApprovalItem)
+        let message = OpenClawWatchExecApprovalSnapshotMessage(
+            approvals: approvals,
+            sentAtMs: Int(Date().timeIntervalSince1970 * 1000),
+            snapshotId: UUID().uuidString)
+        do {
+            _ = try await self.watchMessagingService.syncExecApprovalSnapshot(message)
+            GatewayDiagnostics.log(
+                "watch exec approval: sync snapshot sent reason=\(reason) count=\(approvals.count)")
+            self.watchExecApprovalLogger.debug(
+                "watch exec approval snapshot sent reason=\(reason, privacy: .public) count=\(approvals.count, privacy: .public)")
+        } catch {
+            GatewayDiagnostics.log(
+                "watch exec approval: sync snapshot failed reason=\(reason) error=\(error.localizedDescription)")
+            self.watchExecApprovalLogger.error(
+                "watch exec approval snapshot failed reason=\(reason, privacy: .public) error=\(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func refreshWatchExecApprovalSnapshotOnDemand(reason: String) async {
+        GatewayDiagnostics.log("watch exec approval: refresh on demand start reason=\(reason)")
+        await self.hydrateWatchExecApprovalCacheIfNeeded(reason: reason)
+        await self.syncWatchExecApprovalSnapshot(reason: reason)
+        GatewayDiagnostics.log("watch exec approval: refresh on demand end reason=\(reason)")
+    }
+
+    nonisolated private static func watchExecApprovalIDsNeedingFetch(
+        candidateIDs: [String],
+        cachedApprovalIDs: [String]) -> [String]
+    {
+        let cachedIDs = Set(cachedApprovalIDs.compactMap { id -> String? in
+            let normalizedID = id.trimmingCharacters(in: .whitespacesAndNewlines)
+            return normalizedID.isEmpty ? nil : normalizedID
+        })
+        var idsToFetch: [String] = []
+        var seen = Set<String>()
+        for rawID in candidateIDs {
+            let normalizedID = rawID.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !normalizedID.isEmpty else { continue }
+            guard seen.insert(normalizedID).inserted else { continue }
+            guard !cachedIDs.contains(normalizedID) else { continue }
+            idsToFetch.append(normalizedID)
+        }
+        return idsToFetch
+    }
+
+    private func hydrateWatchExecApprovalCacheIfNeeded(reason: String) async {
+        self.pruneExpiredWatchExecApprovalPrompts()
+
+        let approvalIDs = await self.pendingExecApprovalIDsForWatchRecovery()
+        let missingApprovalIDs = Self.watchExecApprovalIDsNeedingFetch(
+            candidateIDs: approvalIDs,
+            cachedApprovalIDs: Array(self.watchExecApprovalPromptsByID.keys))
+        GatewayDiagnostics.log(
+            "watch exec approval: hydrate candidates reason=\(reason) ids=\(approvalIDs.joined(separator: ",")) missing=\(missingApprovalIDs.joined(separator: ",")) cached=\(self.watchExecApprovalPromptsByID.count)")
+        guard !missingApprovalIDs.isEmpty else {
+            self.watchExecApprovalLogger.debug(
+                "watch exec approval hydrate skipped reason=\(reason, privacy: .public): no missing approval ids")
+            return
+        }
+
+        for approvalId in missingApprovalIDs {
+            GatewayDiagnostics.log(
+                "watch exec approval: hydrate fetch start id=\(approvalId) reason=\(reason)")
+            let outcome = await self.fetchExecApprovalPrompt(
+                approvalId: approvalId,
+                sourceReason: reason)
+            switch outcome {
+            case let .loaded(prompt):
+                GatewayDiagnostics.log("watch exec approval: hydrate fetch loaded id=\(approvalId)")
+                self.upsertWatchExecApprovalPrompt(prompt)
+            case .stale:
+                GatewayDiagnostics.log("watch exec approval: hydrate fetch stale id=\(approvalId)")
+                self.removePendingWatchExecApprovalRecoveryID(approvalId)
+                await ExecApprovalNotificationBridge.removeNotifications(
+                    forApprovalID: approvalId,
+                    notificationCenter: self.notificationCenter)
+            case let .failed(message):
+                self.watchExecApprovalLogger.error(
+                    "watch exec approval hydrate failed id=\(approvalId, privacy: .public) reason=\(reason, privacy: .public) error=\(message, privacy: .public)")
+            }
+        }
+    }
+
+    private func pendingExecApprovalIDsForWatchRecovery() async -> [String] {
+        var ids: [String] = []
+        var seen = Set<String>()
+
+        func append(_ rawID: String?) {
+            let approvalId = rawID?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            guard !approvalId.isEmpty, seen.insert(approvalId).inserted else { return }
+            ids.append(approvalId)
+        }
+
+        append(self.pendingExecApprovalPrompt?.id)
+        for approvalId in self.pendingWatchExecApprovalRecoveryIDs {
+            append(approvalId)
+        }
+        for approvalId in self.watchExecApprovalPromptsByID.keys.sorted() {
+            append(approvalId)
+        }
+
+        let delivered = await self.notificationCenter.deliveredNotifications()
+        GatewayDiagnostics.log("watch exec approval: delivered notifications count=\(delivered.count)")
+        for snapshot in delivered {
+            guard ExecApprovalNotificationBridge.payloadKind(userInfo: snapshot.userInfo)
+                == ExecApprovalNotificationBridge.requestedKind
+            else {
+                continue
+            }
+            append(ExecApprovalNotificationBridge.approvalID(from: snapshot.userInfo))
+        }
+
+        return ids
+    }
+
+    private func handleWatchExecApprovalResolve(_ event: WatchExecApprovalResolveEvent) async {
+        let normalizedApprovalID = event.approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+        if self.pendingExecApprovalPrompt?.id == normalizedApprovalID {
+            self.pendingExecApprovalPromptResolving = true
+            self.pendingExecApprovalPromptErrorText = nil
+        }
+        let outcome = await self.resolveExecApprovalNotificationDecision(
+            approvalId: normalizedApprovalID,
+            decision: event.decision.rawValue,
+            sourceReason: "watch_resolve")
+        if case let .failed(message) = outcome {
+            if self.pendingExecApprovalPrompt?.id == normalizedApprovalID {
+                self.pendingExecApprovalPromptResolving = false
+                self.pendingExecApprovalPromptErrorText = message
+            }
+            if let prompt = self.watchExecApprovalPromptsByID[normalizedApprovalID] {
+                await self.publishWatchExecApprovalPrompt(prompt, reason: "resolve_retry")
+            }
+        }
+    }
+
+    func handleExecApprovalRequestedRemotePush(approvalId: String) async -> Bool {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return false }
+        self.appendPendingWatchExecApprovalRecoveryID(normalizedApprovalID)
+        let fetchedPrompt = await self.fetchExecApprovalPrompt(
+            approvalId: normalizedApprovalID,
+            sourceReason: "push_request")
+        switch fetchedPrompt {
+        case let .loaded(prompt):
+            self.upsertWatchExecApprovalPrompt(prompt)
+            await self.publishWatchExecApprovalPrompt(prompt, reason: "push_request")
+            return true
+        case .stale:
+            await ExecApprovalNotificationBridge.removeNotifications(
+                forApprovalID: normalizedApprovalID,
+                notificationCenter: self.notificationCenter)
+            self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
+            await self.publishWatchExecApprovalExpired(
+                approvalId: normalizedApprovalID,
+                reason: .notFound)
+            return true
+        case let .failed(message):
+            self.watchExecApprovalLogger.error(
+                "watch exec approval push fetch failed id=\(normalizedApprovalID, privacy: .public) error=\(message, privacy: .public)")
+            return false
+        }
+    }
+
+    func handleExecApprovalResolvedRemotePush(approvalId: String) async {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+
+        let hadWatchPrompt = self.watchExecApprovalPromptsByID[normalizedApprovalID] != nil
+        let hadPendingPrompt = self.pendingExecApprovalPrompt?.id == normalizedApprovalID
+        let hadPendingRecoveryID = self.pendingWatchExecApprovalRecoveryIDs.contains(normalizedApprovalID)
+        guard hadWatchPrompt || hadPendingPrompt || hadPendingRecoveryID else {
+            return
+        }
+
+        await self.publishWatchExecApprovalExpired(approvalId: normalizedApprovalID, reason: .resolved)
+        self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
+    }
+
     func handleSilentPushWake(_ userInfo: [AnyHashable: Any]) async -> Bool {
         let wakeId = Self.makePushWakeAttemptID()
         guard Self.isSilentPushPayload(userInfo) else {
@@ -2641,13 +3054,24 @@ extension NodeAppModel {
             notificationCenter: self.notificationCenter)
         {
             if let approvalId = ExecApprovalNotificationBridge.approvalID(from: userInfo) {
-                self.clearPendingExecApprovalPromptIfMatches(approvalId)
+                await self.handleExecApprovalResolvedRemotePush(approvalId: approvalId)
             }
             self.execApprovalNotificationLogger.info(
                 "Handled exec approval cleanup push wakeId=\(wakeId, privacy: .public)")
             return true
         }
 
+        if ExecApprovalNotificationBridge.payloadKind(userInfo: userInfo) == ExecApprovalNotificationBridge.requestedKind,
+           let approvalId = ExecApprovalNotificationBridge.approvalID(from: userInfo)
+        {
+            let handled = await self.handleExecApprovalRequestedRemotePush(approvalId: approvalId)
+            if handled {
+                self.execApprovalNotificationLogger.info(
+                    "Handled exec approval request push wakeId=\(wakeId, privacy: .public) id=\(approvalId, privacy: .public)")
+            }
+            return handled
+        }
+
         let result = await self.reconnectGatewaySessionsForSilentPushIfNeeded(wakeId: wakeId)
         let outcomeMessage =
             "Silent push outcome wakeId=\(wakeId) "
@@ -2832,6 +3256,7 @@ extension NodeAppModel {
     private struct ExecApprovalGetResponse: Decodable {
         var id: String
         var commandText: String
+        var commandPreview: String?
         var allowedDecisions: [String]
         var host: String?
         var nodeId: String?
@@ -2861,6 +3286,7 @@ extension NodeAppModel {
                 forApprovalID: approvalId,
                 notificationCenter: self.notificationCenter)
             self.clearPendingExecApprovalPromptIfMatches(approvalId)
+            await self.publishWatchExecApprovalExpired(approvalId: approvalId, reason: .notFound)
         case let .failed(message):
             self.execApprovalNotificationLogger.error(
                 "Exec approval prompt fetch failed id=\(approvalId, privacy: .public) reason=\(message, privacy: .public)")
@@ -2877,6 +3303,10 @@ extension NodeAppModel {
         self.pendingExecApprovalPrompt = prompt
         self.pendingExecApprovalPromptResolving = false
         self.pendingExecApprovalPromptErrorText = nil
+        self.upsertWatchExecApprovalPrompt(prompt)
+        Task { @MainActor [weak self] in
+            await self?.publishWatchExecApprovalPrompt(prompt, reason: "present_prompt")
+        }
     }
 
     private static func makeExecApprovalPrompt(from details: ExecApprovalGetResponse) -> ExecApprovalPrompt? {
@@ -2886,6 +3316,7 @@ extension NodeAppModel {
         return ExecApprovalPrompt(
             id: approvalId,
             commandText: commandText,
+            commandPreview: details.commandPreview?.trimmingCharacters(in: .whitespacesAndNewlines),
             allowedDecisions: details.allowedDecisions.compactMap { decision in
                 let trimmed = decision.trimmingCharacters(in: .whitespacesAndNewlines)
                 return trimmed.isEmpty ? nil : trimmed
@@ -2896,9 +3327,46 @@ extension NodeAppModel {
             expiresAtMs: details.expiresAtMs)
     }
 
-    private func fetchExecApprovalPrompt(approvalId: String) async -> ExecApprovalPromptFetchOutcome {
-        let connected = await self.ensureOperatorApprovalConnection(timeoutMs: 12_000)
+    nonisolated private static func shouldUseBackgroundAwareExecApprovalReconnect(
+        sourceReason: String,
+        isBackgrounded: Bool) -> Bool
+    {
+        guard isBackgrounded else { return false }
+        switch sourceReason {
+        case "watch_request", "push_request", "watch_resolve", "notification_action":
+            return true
+        default:
+            return false
+        }
+    }
+
+    private func fetchExecApprovalPrompt(
+        approvalId: String,
+        sourceReason: String? = nil) async -> ExecApprovalPromptFetchOutcome
+    {
+        let normalizedSourceReason = sourceReason?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let fetchReason: String
+        if let normalizedSourceReason, !normalizedSourceReason.isEmpty {
+            fetchReason = normalizedSourceReason
+        } else {
+            fetchReason = "direct"
+        }
+        GatewayDiagnostics.log(
+            "watch exec approval: fetch prompt start id=\(approvalId) reason=\(fetchReason)")
+        let connected: Bool
+        if Self.shouldUseBackgroundAwareExecApprovalReconnect(
+            sourceReason: fetchReason,
+            isBackgrounded: self.isBackgrounded)
+        {
+            connected = await self.ensureOperatorApprovalConnectionForWatchReview(
+                timeoutMs: 12_000,
+                reason: fetchReason)
+        } else {
+            connected = await self.ensureOperatorApprovalConnection(timeoutMs: 12_000)
+        }
         guard connected else {
+            GatewayDiagnostics.log(
+                "watch exec approval: fetch prompt operator not connected id=\(approvalId) reason=\(fetchReason)")
             return .failed(message: "operator_not_connected")
         }
 
@@ -2910,13 +3378,21 @@ extension NodeAppModel {
                 timeoutSeconds: 12)
             let details = try JSONDecoder().decode(ExecApprovalGetResponse.self, from: response)
             guard let prompt = Self.makeExecApprovalPrompt(from: details) else {
+                GatewayDiagnostics.log(
+                    "watch exec approval: fetch prompt invalid payload id=\(approvalId) reason=\(fetchReason)")
                 return .failed(message: "invalid_prompt_payload")
             }
+            GatewayDiagnostics.log(
+                "watch exec approval: fetch prompt loaded id=\(approvalId) reason=\(fetchReason)")
             return .loaded(prompt)
         } catch {
             if Self.isApprovalNotificationStaleError(error) {
+                GatewayDiagnostics.log(
+                    "watch exec approval: fetch prompt stale id=\(approvalId) reason=\(fetchReason)")
                 return .stale
             }
+            GatewayDiagnostics.log(
+                "watch exec approval: fetch prompt failed id=\(approvalId) reason=\(fetchReason) error=\(error.localizedDescription)")
             return .failed(message: error.localizedDescription)
         }
     }
@@ -2950,17 +3426,56 @@ extension NodeAppModel {
         }
     }
 
-    private func resolveExecApprovalNotificationDecision(
+    func handleExecApprovalNotificationDecision(
         approvalId: String,
         decision: String
+    ) async {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+
+        if self.pendingExecApprovalPrompt?.id == normalizedApprovalID {
+            self.pendingExecApprovalPromptResolving = true
+            self.pendingExecApprovalPromptErrorText = nil
+        }
+
+        let outcome = await self.resolveExecApprovalNotificationDecision(
+            approvalId: normalizedApprovalID,
+            decision: decision)
+        switch outcome {
+        case .resolved, .stale, .unavailable:
+            break
+        case let .failed(message):
+            if self.pendingExecApprovalPrompt?.id == normalizedApprovalID {
+                self.pendingExecApprovalPromptResolving = false
+                self.pendingExecApprovalPromptErrorText = message
+            }
+        }
+    }
+
+    private func resolveExecApprovalNotificationDecision(
+        approvalId: String,
+        decision: String,
+        sourceReason: String? = nil
     ) async -> ExecApprovalResolutionOutcome {
         let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
         let normalizedDecision = decision.trimmingCharacters(in: .whitespacesAndNewlines)
+        let normalizedSourceReason = sourceReason?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let resolutionReason = (normalizedSourceReason?.isEmpty == false) ? normalizedSourceReason! : "direct"
         guard !normalizedApprovalID.isEmpty, !normalizedDecision.isEmpty else {
             return .failed(message: "Invalid approval request.")
         }
 
-        let connected = await self.ensureOperatorApprovalConnection(timeoutMs: 12_000)
+        let connected: Bool
+        if Self.shouldUseBackgroundAwareExecApprovalReconnect(
+            sourceReason: resolutionReason,
+            isBackgrounded: self.isBackgrounded)
+        {
+            connected = await self.ensureOperatorApprovalConnectionForWatchReview(
+                timeoutMs: 12_000,
+                reason: resolutionReason)
+        } else {
+            connected = await self.ensureOperatorApprovalConnection(timeoutMs: 12_000)
+        }
         guard connected else {
             self.execApprovalNotificationLogger.error(
                 "Exec approval action failed id=\(normalizedApprovalID, privacy: .public): operator not connected")
@@ -2978,6 +3493,10 @@ extension NodeAppModel {
                 forApprovalID: normalizedApprovalID,
                 notificationCenter: self.notificationCenter)
             self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
+            await self.publishWatchExecApprovalResolved(
+                approvalId: normalizedApprovalID,
+                decision: OpenClawWatchExecApprovalDecision(rawValue: normalizedDecision),
+                source: "iphone")
             return .resolved
         } catch {
             if Self.isApprovalNotificationStaleError(error) {
@@ -2985,6 +3504,7 @@ extension NodeAppModel {
                     forApprovalID: normalizedApprovalID,
                     notificationCenter: self.notificationCenter)
                 self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
+                await self.publishWatchExecApprovalExpired(approvalId: normalizedApprovalID, reason: .notFound)
                 return .stale
             }
             if Self.isApprovalNotificationUnavailableError(error) {
@@ -2992,6 +3512,7 @@ extension NodeAppModel {
                     forApprovalID: normalizedApprovalID,
                     notificationCenter: self.notificationCenter)
                 self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
+                await self.publishWatchExecApprovalExpired(approvalId: normalizedApprovalID, reason: .unavailable)
                 return .unavailable
             }
             let logMessage =
@@ -3096,6 +3617,96 @@ extension NodeAppModel {
             sessionBox: sessionBox)
     }
 
+    private func ensureOperatorApprovalConnectionForWatchReview(timeoutMs: Int, reason: String) async -> Bool {
+        let normalizedReason = reason.trimmingCharacters(in: .whitespacesAndNewlines)
+        let reconnectReason = normalizedReason.isEmpty ? "watch_request" : normalizedReason
+        if await self.isOperatorConnected() {
+            GatewayDiagnostics.log(
+                "watch exec approval: watch_request_reconnect_connected reason=\(reconnectReason) phase=already_connected")
+            return true
+        }
+
+        guard self.isBackgrounded else {
+            GatewayDiagnostics.log(
+                "watch exec approval: watch_request_reconnect_begin reason=\(reconnectReason) backgrounded=false strategy=default")
+            let connected = await self.ensureOperatorApprovalConnection(timeoutMs: timeoutMs)
+            GatewayDiagnostics.log(
+                "watch exec approval: watch_request_reconnect_\(connected ? "connected" : "timeout") reason=\(reconnectReason) phase=foreground_delegate")
+            return connected
+        }
+
+        guard self.gatewayAutoReconnectEnabled else {
+            GatewayDiagnostics.log(
+                "watch exec approval: watch_request_reconnect_timeout reason=\(reconnectReason) phase=auto_reconnect_disabled")
+            return false
+        }
+
+        guard let cfg = self.activeGatewayConnectConfig else {
+            GatewayDiagnostics.log(
+                "watch exec approval: watch_request_reconnect_timeout reason=\(reconnectReason) phase=no_active_gateway_config")
+            return false
+        }
+
+        GatewayDiagnostics.log(
+            "watch exec approval: watch_request_reconnect_begin reason=\(reconnectReason) backgrounded=true")
+        let leaseSeconds = min(45.0, max(15.0, Double(max(timeoutMs, 1_000)) / 1000.0 + 8.0))
+        self.grantBackgroundReconnectLease(seconds: leaseSeconds, reason: "watch_review_\(reconnectReason)")
+        GatewayDiagnostics.log(
+            "watch exec approval: watch_request_reconnect_lease_granted reason=\(reconnectReason) seconds=\(leaseSeconds)")
+
+        let hadReconnectLoop = self.operatorGatewayTask != nil
+        let canStartReconnectLoop = hadReconnectLoop || self.shouldStartOperatorGatewayLoop(
+            token: cfg.token,
+            bootstrapToken: cfg.bootstrapToken,
+            password: cfg.password,
+            stableID: cfg.effectiveStableID)
+        guard canStartReconnectLoop else {
+            GatewayDiagnostics.log(
+                "watch exec approval: watch_request_reconnect_timeout reason=\(reconnectReason) phase=no_operator_reconnect_auth")
+            return false
+        }
+
+        self.ensureOperatorReconnectLoopIfNeeded()
+        GatewayDiagnostics.log(
+            "watch exec approval: watch_request_reconnect_loop_\(hadReconnectLoop ? "reused" : "started") reason=\(reconnectReason)")
+
+        let initialWaitMs = min(2_500, max(750, timeoutMs / 4))
+        GatewayDiagnostics.log(
+            "watch exec approval: watch_request_reconnect_wait reason=\(reconnectReason) phase=initial timeoutMs=\(initialWaitMs)")
+        if await self.waitForOperatorConnection(timeoutMs: initialWaitMs, pollMs: 200) {
+            GatewayDiagnostics.log(
+                "watch exec approval: watch_request_reconnect_connected reason=\(reconnectReason) phase=initial")
+            return true
+        }
+
+        GatewayDiagnostics.log(
+            "watch exec approval: watch_request_reconnect_restart reason=\(reconnectReason)")
+        self.operatorGatewayTask?.cancel()
+        self.operatorGatewayTask = nil
+        await self.operatorGateway.disconnect()
+        self.operatorConnected = false
+        self.talkMode.updateGatewayConnected(false)
+        self.stopGatewayHealthMonitor()
+
+        let sessionBox = cfg.tls.map { WebSocketSessionBox(session: GatewayTLSPinningSession(params: $0)) }
+        self.startOperatorGatewayLoop(
+            url: cfg.url,
+            stableID: cfg.effectiveStableID,
+            token: cfg.token,
+            bootstrapToken: cfg.bootstrapToken,
+            password: cfg.password,
+            nodeOptions: cfg.nodeOptions,
+            sessionBox: sessionBox)
+
+        let remainingWaitMs = max(250, timeoutMs - initialWaitMs)
+        GatewayDiagnostics.log(
+            "watch exec approval: watch_request_reconnect_wait reason=\(reconnectReason) phase=restart timeoutMs=\(remainingWaitMs)")
+        let connected = await self.waitForOperatorConnection(timeoutMs: remainingWaitMs, pollMs: 200)
+        GatewayDiagnostics.log(
+            "watch exec approval: watch_request_reconnect_\(connected ? "connected" : "timeout") reason=\(reconnectReason) phase=restart")
+        return connected
+    }
+
     private func ensureOperatorApprovalConnection(timeoutMs: Int) async -> Bool {
         if await self.isOperatorConnected() {
             return true
@@ -3526,6 +4137,18 @@ extension NodeAppModel {
         self.pendingExecApprovalPrompt
     }
 
+    func _test_recordPendingWatchExecApprovalRecoveryID(_ approvalId: String) {
+        self.appendPendingWatchExecApprovalRecoveryID(approvalId)
+    }
+
+    func _test_pendingWatchExecApprovalRecoveryIDs() -> [String] {
+        self.pendingWatchExecApprovalRecoveryIDs
+    }
+
+    func _test_pendingExecApprovalIDsForWatchRecovery() async -> [String] {
+        await self.pendingExecApprovalIDsForWatchRecovery()
+    }
+
     nonisolated static func _test_isApprovalNotificationStaleError(_ error: Error) -> Bool {
         self.isApprovalNotificationStaleError(error)
     }
@@ -3534,6 +4157,30 @@ extension NodeAppModel {
         self.isApprovalNotificationUnavailableError(error)
     }
 
+    nonisolated static func _test_shouldUseBackgroundAwareExecApprovalReconnect(
+        sourceReason: String,
+        isBackgrounded: Bool) -> Bool
+    {
+        self.shouldUseBackgroundAwareExecApprovalReconnect(
+            sourceReason: sourceReason,
+            isBackgrounded: isBackgrounded)
+    }
+
+    nonisolated static func _test_watchExecApprovalIDsNeedingFetch(
+        candidateIDs: [String],
+        cachedApprovalIDs: [String]) -> [String]
+    {
+        self.watchExecApprovalIDsNeedingFetch(
+            candidateIDs: candidateIDs,
+            cachedApprovalIDs: cachedApprovalIDs)
+    }
+
+    nonisolated static func _test_shouldResetWatchExecApprovalResolvingStateOnPrompt(
+        reason: String) -> Bool
+    {
+        self.shouldResetWatchExecApprovalResolvingStateOnPrompt(reason: reason)
+    }
+
     static func _test_makeExecApprovalPrompt(
         id: String,
         commandText: String,
@@ -3547,6 +4194,7 @@ extension NodeAppModel {
             from: ExecApprovalGetResponse(
                 id: id,
                 commandText: commandText,
+                commandPreview: nil,
                 allowedDecisions: allowedDecisions,
                 host: host,
                 nodeId: nodeId,
@@ -3558,6 +4206,10 @@ extension NodeAppModel {
         self.expectedDeepLinkKey()
     }
 
+    static func _test_resetPersistedWatchExecApprovalBridgeState() {
+        UserDefaults.standard.removeObject(forKey: self.watchExecApprovalBridgeStateKey)
+    }
+
     nonisolated static func _test_shouldStartOperatorGatewayLoop(
         token: String?,
         bootstrapToken: String?,

apps/ios/Sources/OpenClawApp.swift

@@ -15,6 +15,11 @@ private struct PendingWatchPromptAction {
 
 private typealias PendingExecApprovalPrompt = ExecApprovalNotificationPrompt
 
+@MainActor
+enum OpenClawAppModelRegistry {
+    static var appModel: NodeAppModel?
+}
+
 @MainActor
 final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrency UNUserNotificationCenterDelegate {
     private let logger = Logger(subsystem: "ai.openclaw.ios", category: "Push")
@@ -24,10 +29,12 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
     private var pendingAPNsDeviceToken: Data?
     private var pendingWatchPromptActions: [PendingWatchPromptAction] = []
     private var pendingExecApprovalPrompts: [PendingExecApprovalPrompt] = []
+    private var pendingExecApprovalRequestedPushIDs: [String] = []
+    private var pendingExecApprovalResolvedPushIDs: [String] = []
 
     weak var appModel: NodeAppModel? {
         didSet {
-            guard let model = self.appModel else { return }
+            guard let model = self.resolvedAppModel() else { return }
             if let token = self.pendingAPNsDeviceToken {
                 self.pendingAPNsDeviceToken = nil
                 Task { @MainActor in
@@ -56,22 +63,56 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
                     }
                 }
             }
+            if !self.pendingExecApprovalRequestedPushIDs.isEmpty {
+                let pending = self.pendingExecApprovalRequestedPushIDs
+                self.pendingExecApprovalRequestedPushIDs.removeAll()
+                Task { @MainActor in
+                    for approvalId in pending {
+                        _ = await model.handleExecApprovalRequestedRemotePush(approvalId: approvalId)
+                    }
+                }
+            }
+            if !self.pendingExecApprovalResolvedPushIDs.isEmpty {
+                let pending = self.pendingExecApprovalResolvedPushIDs
+                self.pendingExecApprovalResolvedPushIDs.removeAll()
+                Task { @MainActor in
+                    for approvalId in pending {
+                        await model.handleExecApprovalResolvedRemotePush(approvalId: approvalId)
+                    }
+                }
+            }
         }
     }
 
+    private func resolvedAppModel() -> NodeAppModel? {
+        self.appModel ?? OpenClawAppModelRegistry.appModel
+    }
+
+#if DEBUG
+    func _test_resolvedAppModel() -> NodeAppModel? {
+        self.resolvedAppModel()
+    }
+#endif
+
     func application(
         _ application: UIApplication,
         didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
     ) -> Bool
     {
+        GatewayDiagnostics.log("app delegate: didFinishLaunching")
+        if self.appModel == nil {
+            self.appModel = OpenClawAppModelRegistry.appModel
+        }
         self.registerBackgroundWakeRefreshTask()
-        UNUserNotificationCenter.current().delegate = self
+        let notificationCenter = UNUserNotificationCenter.current()
+        notificationCenter.delegate = self
+        ExecApprovalNotificationBridge.registerCategory(center: notificationCenter)
         application.registerForRemoteNotifications()
         return true
     }
 
     func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
-        if let appModel = self.appModel {
+        if let appModel = self.resolvedAppModel() {
             Task { @MainActor in
                 appModel.updateAPNsDeviceToken(deviceToken)
             }
@@ -98,12 +139,22 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
                 notificationCenter: notificationCenter)
             {
                 if let approvalId = ExecApprovalNotificationBridge.approvalID(from: userInfo) {
-                    self.appModel?.dismissPendingExecApprovalPrompt(approvalId: approvalId)
+                    if let appModel = self.resolvedAppModel() {
+                        await appModel.handleExecApprovalResolvedRemotePush(approvalId: approvalId)
+                    } else {
+                        self.pendingExecApprovalResolvedPushIDs.append(approvalId)
+                    }
                 }
                 completionHandler(.newData)
                 return
             }
-            guard let appModel = self.appModel else {
+            guard let appModel = self.resolvedAppModel() else {
+                if ExecApprovalNotificationBridge.payloadKind(userInfo: userInfo)
+                    == ExecApprovalNotificationBridge.requestedKind,
+                   let approvalId = ExecApprovalNotificationBridge.approvalID(from: userInfo)
+                {
+                    self.pendingExecApprovalRequestedPushIDs.append(approvalId)
+                }
                 self.logger.info("APNs wake skipped: appModel unavailable")
                 self.scheduleBackgroundWakeRefresh(afterSeconds: 90, reason: "silent_push_no_model")
                 completionHandler(.noData)
@@ -119,6 +170,7 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
     }
 
     func scenePhaseChanged(_ phase: ScenePhase) {
+        GatewayDiagnostics.log("app delegate: scene phase changed=\(String(describing: phase))")
         if phase == .background {
             self.scheduleBackgroundWakeRefresh(afterSeconds: 120, reason: "scene_background")
         }
@@ -163,7 +215,7 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
         self.backgroundWakeTask?.cancel()
 
         let wakeTask = Task { @MainActor [weak self] in
-            guard let self, let appModel = self.appModel else { return false }
+            guard let self, let appModel = self.resolvedAppModel() else { return false }
             return await appModel.handleBackgroundRefreshWake(trigger: "bg_app_refresh")
         }
         self.backgroundWakeTask = wakeTask
@@ -248,7 +300,7 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
     }
 
     private func routeWatchPromptAction(_ action: PendingWatchPromptAction) async {
-        guard let appModel = self.appModel else {
+        guard let appModel = self.resolvedAppModel() else {
             self.pendingWatchPromptActions.append(action)
             return
         }
@@ -261,7 +313,7 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
     }
 
     private func routeExecApprovalPrompt(_ prompt: PendingExecApprovalPrompt) {
-        guard let appModel = self.appModel else {
+        guard let appModel = self.resolvedAppModel() else {
             self.pendingExecApprovalPrompts.append(prompt)
             return
         }
@@ -561,6 +613,7 @@ struct OpenClawApp: App {
         Self.installUncaughtExceptionLogger()
         GatewaySettingsStore.bootstrapPersistence()
         let appModel = NodeAppModel()
+        OpenClawAppModelRegistry.appModel = appModel
         _appModel = State(initialValue: appModel)
         _gatewayController = State(initialValue: GatewayConnectionController(appModel: appModel))
     }

apps/ios/Sources/Push/ExecApprovalNotificationBridge.swift

@@ -8,9 +8,30 @@ struct ExecApprovalNotificationPrompt: Sendable, Equatable {
 enum ExecApprovalNotificationBridge {
     static let requestedKind = "exec.approval.requested"
     static let resolvedKind = "exec.approval.resolved"
+    static let categoryIdentifier = "openclaw.exec-approval"
+    static let reviewActionIdentifier = "openclaw.exec-approval.review"
 
     private static let localRequestPrefix = "exec.approval."
 
+    static func registerCategory(center: UNUserNotificationCenter = .current()) {
+        let category = UNNotificationCategory(
+            identifier: self.categoryIdentifier,
+            actions: [
+                UNNotificationAction(
+                    identifier: self.reviewActionIdentifier,
+                    title: "Review",
+                    options: [.foreground]),
+            ],
+            intentIdentifiers: [],
+            options: [])
+
+        center.getNotificationCategories { categories in
+            var updated = categories
+            updated.update(with: category)
+            center.setNotificationCategories(updated)
+        }
+    }
+
     static func shouldPresentNotification(userInfo: [AnyHashable: Any]) -> Bool {
         self.payloadKind(userInfo: userInfo) == self.requestedKind
     }
@@ -20,7 +41,11 @@ enum ExecApprovalNotificationBridge {
         userInfo: [AnyHashable: Any]
     ) -> ExecApprovalNotificationPrompt?
     {
-        guard actionIdentifier == UNNotificationDefaultActionIdentifier else { return nil }
+        guard actionIdentifier == UNNotificationDefaultActionIdentifier
+            || actionIdentifier == self.reviewActionIdentifier
+        else {
+            return nil
+        }
         guard self.payloadKind(userInfo: userInfo) == self.requestedKind else { return nil }
         guard let approvalId = self.approvalID(from: userInfo) else { return nil }
         return ExecApprovalNotificationPrompt(approvalId: approvalId)
@@ -71,7 +96,7 @@ enum ExecApprovalNotificationBridge {
         "\(self.localRequestPrefix)\(approvalId)"
     }
 
-    private static func payloadKind(userInfo: [AnyHashable: Any]) -> String {
+    static func payloadKind(userInfo: [AnyHashable: Any]) -> String {
         let raw = self.openClawPayload(userInfo: userInfo)?["kind"] as? String
         let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
         return trimmed.isEmpty ? "unknown" : trimmed

apps/ios/Sources/Services/NodeServiceProtocols.swift

@@ -88,6 +88,20 @@ struct WatchQuickReplyEvent: Sendable, Equatable {
     var transport: String
 }
 
+struct WatchExecApprovalResolveEvent: Sendable, Equatable {
+    var replyId: String
+    var approvalId: String
+    var decision: OpenClawWatchExecApprovalDecision
+    var sentAtMs: Int?
+    var transport: String
+}
+
+struct WatchExecApprovalSnapshotRequestEvent: Sendable, Equatable {
+    var requestId: String
+    var sentAtMs: Int?
+    var transport: String
+}
+
 struct WatchNotificationSendResult: Sendable, Equatable {
     var deliveredImmediately: Bool
     var queuedForDelivery: Bool
@@ -96,10 +110,22 @@ struct WatchNotificationSendResult: Sendable, Equatable {
 
 protocol WatchMessagingServicing: AnyObject, Sendable {
     func status() async -> WatchMessagingStatus
+    func setStatusHandler(_ handler: (@Sendable (WatchMessagingStatus) -> Void)?)
     func setReplyHandler(_ handler: (@Sendable (WatchQuickReplyEvent) -> Void)?)
+    func setExecApprovalResolveHandler(_ handler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?)
+    func setExecApprovalSnapshotRequestHandler(
+        _ handler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?)
     func sendNotification(
         id: String,
         params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult
+    func sendExecApprovalPrompt(
+        _ message: OpenClawWatchExecApprovalPromptMessage) async throws -> WatchNotificationSendResult
+    func sendExecApprovalResolved(
+        _ message: OpenClawWatchExecApprovalResolvedMessage) async throws -> WatchNotificationSendResult
+    func sendExecApprovalExpired(
+        _ message: OpenClawWatchExecApprovalExpiredMessage) async throws -> WatchNotificationSendResult
+    func syncExecApprovalSnapshot(
+        _ message: OpenClawWatchExecApprovalSnapshotMessage) async throws -> WatchNotificationSendResult
 }
 
 extension CameraController: CameraServicing {}

apps/ios/Sources/Services/WatchConnectivityTransport.swift

@@ -0,0 +1,363 @@
+import Foundation
+import OSLog
+@preconcurrency import WatchConnectivity
+
+private struct WatchConnectivityTransportCallbacks {
+    var statusUpdateHandler: (@Sendable (WatchMessagingStatus) -> Void)?
+    var replyHandler: (@Sendable (WatchQuickReplyEvent) -> Void)?
+    var execApprovalResolveHandler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?
+    var execApprovalSnapshotRequestHandler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?
+}
+
+private func sendReachableWatchMessage(_ payload: [String: Any], with session: WCSession) async throws {
+    // WatchConnectivity replies arrive on its own queue. Keep this continuation explicitly
+    // nonisolated so Swift 6 does not inherit a caller actor (for example MainActor) into the
+    // Objective-C callback boundary and trap on the reply callback executor check.
+    try await withCheckedThrowingContinuation(isolation: nil) {
+        (continuation: CheckedContinuation<Void, Error>) in
+        session.sendMessage(
+            payload,
+            replyHandler: { _ in
+                continuation.resume(returning: ())
+            },
+            errorHandler: { error in
+                continuation.resume(throwing: error)
+            }
+        )
+    }
+}
+
+final class WatchConnectivityTransport: NSObject, @unchecked Sendable {
+    nonisolated private static let logger = Logger(subsystem: "ai.openclaw", category: "watch.messaging")
+
+    private let session: WCSession?
+    private let callbacksLock = NSLock()
+    private var callbacks = WatchConnectivityTransportCallbacks()
+
+    override init() {
+        if WCSession.isSupported() {
+            self.session = WCSession.default
+        } else {
+            self.session = nil
+        }
+        super.init()
+        if let session = self.session {
+            session.delegate = self
+            session.activate()
+        }
+    }
+
+    nonisolated static func isSupportedOnDevice() -> Bool {
+        WCSession.isSupported()
+    }
+
+    nonisolated static func currentStatusSnapshot() -> WatchMessagingStatus {
+        guard WCSession.isSupported() else {
+            return WatchMessagingStatus(
+                supported: false,
+                paired: false,
+                appInstalled: false,
+                reachable: false,
+                activationState: "unsupported")
+        }
+        return self.status(for: WCSession.default)
+    }
+
+    func status() async -> WatchMessagingStatus {
+        await self.ensureActivated()
+        return self.currentStatusSnapshot()
+    }
+
+    func currentStatusSnapshot() -> WatchMessagingStatus {
+        guard let session = self.session else {
+            return WatchMessagingStatus(
+                supported: false,
+                paired: false,
+                appInstalled: false,
+                reachable: false,
+                activationState: "unsupported")
+        }
+        return Self.status(for: session)
+    }
+
+    func setStatusUpdateHandler(_ handler: (@Sendable (WatchMessagingStatus) -> Void)?) {
+        self.updateCallbacks { $0.statusUpdateHandler = handler }
+    }
+
+    func setReplyHandler(_ handler: (@Sendable (WatchQuickReplyEvent) -> Void)?) {
+        self.updateCallbacks { $0.replyHandler = handler }
+    }
+
+    func setExecApprovalResolveHandler(_ handler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?) {
+        self.updateCallbacks { $0.execApprovalResolveHandler = handler }
+    }
+
+    func setExecApprovalSnapshotRequestHandler(
+        _ handler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?)
+    {
+        self.updateCallbacks { $0.execApprovalSnapshotRequestHandler = handler }
+    }
+
+    func sendPayload(_ payload: [String: Any]) async throws -> WatchNotificationSendResult {
+        await self.ensureActivated()
+        let session = try self.requireReadySession()
+        if session.isReachable {
+            do {
+                try await sendReachableWatchMessage(payload, with: session)
+                return WatchNotificationSendResult(
+                    deliveredImmediately: true,
+                    queuedForDelivery: false,
+                    transport: "sendMessage")
+            } catch {
+                Self.logger.error("watch sendMessage failed: \(error.localizedDescription, privacy: .public)")
+            }
+        }
+
+        _ = session.transferUserInfo(payload)
+        return WatchNotificationSendResult(
+            deliveredImmediately: false,
+            queuedForDelivery: true,
+            transport: "transferUserInfo")
+    }
+
+    func sendSnapshotPayload(_ payload: [String: Any]) async throws -> WatchNotificationSendResult {
+        await self.ensureActivated()
+        let session = try self.requireReadySession()
+        if session.isReachable {
+            do {
+                try await sendReachableWatchMessage(payload, with: session)
+                return WatchNotificationSendResult(
+                    deliveredImmediately: true,
+                    queuedForDelivery: false,
+                    transport: "sendMessage")
+            } catch {
+                Self.logger.error(
+                    "watch snapshot sendMessage failed: \(error.localizedDescription, privacy: .public)")
+            }
+        }
+
+        do {
+            try session.updateApplicationContext(payload)
+            return WatchNotificationSendResult(
+                deliveredImmediately: false,
+                queuedForDelivery: true,
+                transport: "applicationContext")
+        } catch {
+            Self.logger.error(
+                "watch updateApplicationContext failed: \(error.localizedDescription, privacy: .public)")
+            _ = session.transferUserInfo(payload)
+            return WatchNotificationSendResult(
+                deliveredImmediately: false,
+                queuedForDelivery: true,
+                transport: "transferUserInfo")
+        }
+    }
+
+    private func updateCallbacks(_ update: (inout WatchConnectivityTransportCallbacks) -> Void) {
+        self.callbacksLock.lock()
+        defer { self.callbacksLock.unlock() }
+        update(&self.callbacks)
+    }
+
+    private func callbacksSnapshot() -> WatchConnectivityTransportCallbacks {
+        self.callbacksLock.lock()
+        defer { self.callbacksLock.unlock() }
+        return self.callbacks
+    }
+
+    private func requireReadySession() throws -> WCSession {
+        guard let session = self.session else {
+            throw WatchMessagingError.unsupported
+        }
+        let snapshot = Self.status(for: session)
+        guard snapshot.paired else {
+            throw WatchMessagingError.notPaired
+        }
+        guard snapshot.appInstalled else {
+            throw WatchMessagingError.watchAppNotInstalled
+        }
+        return session
+    }
+
+    private func ensureActivated() async {
+        guard let session = self.session else { return }
+        if session.activationState == .activated {
+            return
+        }
+        session.activate()
+        for _ in 0..<8 {
+            if session.activationState == .activated {
+                return
+            }
+            try? await Task.sleep(nanoseconds: 100_000_000)
+        }
+    }
+
+    private func emitStatusUpdate(_ snapshot: WatchMessagingStatus) {
+        guard let handler = self.callbacksSnapshot().statusUpdateHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(snapshot)
+        }
+    }
+
+    private func emitReply(_ event: WatchQuickReplyEvent) {
+        guard let handler = self.callbacksSnapshot().replyHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(event)
+        }
+    }
+
+    private func emitExecApprovalResolve(_ event: WatchExecApprovalResolveEvent) {
+        guard let handler = self.callbacksSnapshot().execApprovalResolveHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(event)
+        }
+    }
+
+    private func emitExecApprovalSnapshotRequest(_ event: WatchExecApprovalSnapshotRequestEvent) {
+        guard let handler = self.callbacksSnapshot().execApprovalSnapshotRequestHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(event)
+        }
+    }
+
+    nonisolated private static func status(for session: WCSession) -> WatchMessagingStatus {
+        WatchMessagingStatus(
+            supported: true,
+            paired: session.isPaired,
+            appInstalled: session.isWatchAppInstalled,
+            reachable: session.isReachable,
+            activationState: self.activationStateLabel(session.activationState))
+    }
+
+    nonisolated private static func activationStateLabel(_ state: WCSessionActivationState) -> String {
+        switch state {
+        case .notActivated:
+            "notActivated"
+        case .inactive:
+            "inactive"
+        case .activated:
+            "activated"
+        @unknown default:
+            "unknown"
+        }
+    }
+}
+
+extension WatchConnectivityTransport: WCSessionDelegate {
+    func session(
+        _ session: WCSession,
+        activationDidCompleteWith activationState: WCSessionActivationState,
+        error: (any Error)?)
+    {
+        GatewayDiagnostics.log(
+            "watch messaging: activation complete state=\(Self.activationStateLabel(activationState)) error=\(error?.localizedDescription ?? "none")")
+        if let error {
+            Self.logger.error("watch activation failed: \(error.localizedDescription, privacy: .public)")
+        } else {
+            Self.logger.debug(
+                "watch activation state=\(Self.activationStateLabel(activationState), privacy: .public)")
+        }
+        self.emitStatusUpdate(Self.status(for: session))
+    }
+
+    func sessionDidBecomeInactive(_: WCSession) {}
+
+    func sessionDidDeactivate(_ session: WCSession) {
+        GatewayDiagnostics.log("watch messaging: session did deactivate; reactivating")
+        session.activate()
+        self.emitStatusUpdate(Self.status(for: session))
+    }
+
+    func session(_: WCSession, didReceiveMessage message: [String: Any]) {
+        let type = (message["type"] as? String) ?? "unknown"
+        GatewayDiagnostics.log("watch messaging: didReceiveMessage type=\(type)")
+        if let event = WatchMessagingPayloadCodec.parseQuickReplyPayload(message, transport: "sendMessage") {
+            self.emitReply(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalResolvePayload(
+            message,
+            transport: "sendMessage")
+        {
+            self.emitExecApprovalResolve(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalSnapshotRequestPayload(
+            message,
+            transport: "sendMessage")
+        {
+            self.emitExecApprovalSnapshotRequest(event)
+        }
+    }
+
+    func session(
+        _: WCSession,
+        didReceiveMessage message: [String: Any],
+        replyHandler: @escaping ([String: Any]) -> Void)
+    {
+        let type = (message["type"] as? String) ?? "unknown"
+        GatewayDiagnostics.log("watch messaging: didReceiveMessageWithReply type=\(type)")
+        if let event = WatchMessagingPayloadCodec.parseQuickReplyPayload(message, transport: "sendMessage") {
+            replyHandler(["ok": true])
+            self.emitReply(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalResolvePayload(
+            message,
+            transport: "sendMessage")
+        {
+            replyHandler(["ok": true])
+            self.emitExecApprovalResolve(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalSnapshotRequestPayload(
+            message,
+            transport: "sendMessage")
+        {
+            replyHandler(["ok": true])
+            self.emitExecApprovalSnapshotRequest(event)
+            return
+        }
+        replyHandler(["ok": false, "error": "unsupported_payload"])
+    }
+
+    func session(_: WCSession, didReceiveUserInfo userInfo: [String: Any]) {
+        let type = (userInfo["type"] as? String) ?? "unknown"
+        GatewayDiagnostics.log("watch messaging: didReceiveUserInfo type=\(type)")
+        if let event = WatchMessagingPayloadCodec.parseQuickReplyPayload(
+            userInfo,
+            transport: "transferUserInfo")
+        {
+            self.emitReply(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalResolvePayload(
+            userInfo,
+            transport: "transferUserInfo")
+        {
+            self.emitExecApprovalResolve(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalSnapshotRequestPayload(
+            userInfo,
+            transport: "transferUserInfo")
+        {
+            self.emitExecApprovalSnapshotRequest(event)
+        }
+    }
+
+    func sessionReachabilityDidChange(_ session: WCSession) {
+        GatewayDiagnostics.log(
+            "watch messaging: reachability changed reachable=\(session.isReachable) paired=\(session.isPaired) installed=\(session.isWatchAppInstalled)")
+        self.emitStatusUpdate(Self.status(for: session))
+    }
+}

apps/ios/Sources/Services/WatchMessagingPayloadCodec.swift

@@ -0,0 +1,219 @@
+import Foundation
+import OpenClawKit
+
+enum WatchMessagingPayloadCodec {
+    static func nowMs() -> Int {
+        Int(Date().timeIntervalSince1970 * 1000)
+    }
+
+    static func nonEmpty(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    static func encodeNotificationPayload(
+        id: String,
+        params: OpenClawWatchNotifyParams) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.notify.rawValue,
+            "id": id,
+            "title": params.title,
+            "body": params.body,
+            "priority": params.priority?.rawValue ?? OpenClawNotificationPriority.active.rawValue,
+            "sentAtMs": nowMs(),
+        ]
+        if let promptId = nonEmpty(params.promptId) {
+            payload["promptId"] = promptId
+        }
+        if let sessionKey = nonEmpty(params.sessionKey) {
+            payload["sessionKey"] = sessionKey
+        }
+        if let kind = nonEmpty(params.kind) {
+            payload["kind"] = kind
+        }
+        if let details = nonEmpty(params.details) {
+            payload["details"] = details
+        }
+        if let expiresAtMs = params.expiresAtMs {
+            payload["expiresAtMs"] = expiresAtMs
+        }
+        if let risk = params.risk {
+            payload["risk"] = risk.rawValue
+        }
+        if let actions = params.actions, !actions.isEmpty {
+            payload["actions"] = actions.map { action in
+                var encoded: [String: Any] = [
+                    "id": action.id,
+                    "label": action.label,
+                ]
+                if let style = nonEmpty(action.style) {
+                    encoded["style"] = style
+                }
+                return encoded
+            }
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalItem(_ item: OpenClawWatchExecApprovalItem) -> [String: Any] {
+        var payload: [String: Any] = [
+            "id": item.id,
+            "commandText": item.commandText,
+            "allowedDecisions": item.allowedDecisions.map(\.rawValue),
+        ]
+        if let commandPreview = nonEmpty(item.commandPreview) {
+            payload["commandPreview"] = commandPreview
+        }
+        if let host = nonEmpty(item.host) {
+            payload["host"] = host
+        }
+        if let nodeId = nonEmpty(item.nodeId) {
+            payload["nodeId"] = nodeId
+        }
+        if let agentId = nonEmpty(item.agentId) {
+            payload["agentId"] = agentId
+        }
+        if let expiresAtMs = item.expiresAtMs {
+            payload["expiresAtMs"] = expiresAtMs
+        }
+        if let risk = item.risk {
+            payload["risk"] = risk.rawValue
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalPromptPayload(
+        _ message: OpenClawWatchExecApprovalPromptMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.execApprovalPrompt.rawValue,
+            "approval": encodeExecApprovalItem(message.approval),
+        ]
+        if let sentAtMs = message.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        if let deliveryId = nonEmpty(message.deliveryId) {
+            payload["deliveryId"] = deliveryId
+        }
+        if message.resetResolvingState == true {
+            payload["resetResolvingState"] = true
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalResolvedPayload(
+        _ message: OpenClawWatchExecApprovalResolvedMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.execApprovalResolved.rawValue,
+            "approvalId": message.approvalId,
+        ]
+        if let decision = message.decision {
+            payload["decision"] = decision.rawValue
+        }
+        if let resolvedAtMs = message.resolvedAtMs {
+            payload["resolvedAtMs"] = resolvedAtMs
+        }
+        if let source = nonEmpty(message.source) {
+            payload["source"] = source
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalExpiredPayload(
+        _ message: OpenClawWatchExecApprovalExpiredMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.execApprovalExpired.rawValue,
+            "approvalId": message.approvalId,
+            "reason": message.reason.rawValue,
+        ]
+        if let expiredAtMs = message.expiredAtMs {
+            payload["expiredAtMs"] = expiredAtMs
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalSnapshotPayload(
+        _ message: OpenClawWatchExecApprovalSnapshotMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.execApprovalSnapshot.rawValue,
+            "approvals": message.approvals.map(encodeExecApprovalItem),
+        ]
+        if let sentAtMs = message.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        if let snapshotId = nonEmpty(message.snapshotId) {
+            payload["snapshotId"] = snapshotId
+        }
+        return payload
+    }
+
+    static func parseQuickReplyPayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchQuickReplyEvent?
+    {
+        guard (payload["type"] as? String) == OpenClawWatchPayloadType.reply.rawValue else {
+            return nil
+        }
+        guard let actionId = nonEmpty(payload["actionId"] as? String) else {
+            return nil
+        }
+        let promptId = nonEmpty(payload["promptId"] as? String) ?? "unknown"
+        let replyId = nonEmpty(payload["replyId"] as? String) ?? UUID().uuidString
+        let actionLabel = nonEmpty(payload["actionLabel"] as? String)
+        let sessionKey = nonEmpty(payload["sessionKey"] as? String)
+        let note = nonEmpty(payload["note"] as? String)
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+
+        return WatchQuickReplyEvent(
+            replyId: replyId,
+            promptId: promptId,
+            actionId: actionId,
+            actionLabel: actionLabel,
+            sessionKey: sessionKey,
+            note: note,
+            sentAtMs: sentAtMs,
+            transport: transport)
+    }
+
+    static func parseExecApprovalResolvePayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchExecApprovalResolveEvent?
+    {
+        guard (payload["type"] as? String) == OpenClawWatchPayloadType.execApprovalResolve.rawValue else {
+            return nil
+        }
+        guard let approvalId = nonEmpty(payload["approvalId"] as? String),
+              let rawDecision = nonEmpty(payload["decision"] as? String),
+              let decision = OpenClawWatchExecApprovalDecision(rawValue: rawDecision)
+        else {
+            return nil
+        }
+        let replyId = nonEmpty(payload["replyId"] as? String) ?? UUID().uuidString
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        return WatchExecApprovalResolveEvent(
+            replyId: replyId,
+            approvalId: approvalId,
+            decision: decision,
+            sentAtMs: sentAtMs,
+            transport: transport)
+    }
+
+    static func parseExecApprovalSnapshotRequestPayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchExecApprovalSnapshotRequestEvent?
+    {
+        guard (payload["type"] as? String) == OpenClawWatchPayloadType.execApprovalSnapshotRequest.rawValue else {
+            return nil
+        }
+        let requestId = nonEmpty(payload["requestId"] as? String) ?? UUID().uuidString
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        return WatchExecApprovalSnapshotRequestEvent(
+            requestId: requestId,
+            sentAtMs: sentAtMs,
+            transport: transport)
+    }
+}

apps/ios/Sources/Services/WatchMessagingService.swift

@@ -1,7 +1,5 @@
 import Foundation
 import OpenClawKit
-import OSLog
-@preconcurrency import WatchConnectivity
 
 enum WatchMessagingError: LocalizedError {
     case unsupported
@@ -21,272 +19,136 @@ enum WatchMessagingError: LocalizedError {
 }
 
 @MainActor
-final class WatchMessagingService: NSObject, @preconcurrency WatchMessagingServicing {
-    nonisolated private static let logger = Logger(subsystem: "ai.openclaw", category: "watch.messaging")
-    private let session: WCSession?
-    private var pendingActivationContinuations: [CheckedContinuation<Void, Never>] = []
+final class WatchMessagingService: @preconcurrency WatchMessagingServicing {
+    private let transport: WatchConnectivityTransport
+    private var statusHandler: (@Sendable (WatchMessagingStatus) -> Void)?
+    private var lastEmittedStatus: WatchMessagingStatus?
     private var replyHandler: (@Sendable (WatchQuickReplyEvent) -> Void)?
+    private var execApprovalResolveHandler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?
+    private var execApprovalSnapshotRequestHandler: (
+        @Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?
 
-    override init() {
-        if WCSession.isSupported() {
-            self.session = WCSession.default
-        } else {
-            self.session = nil
+    init(transport: WatchConnectivityTransport = WatchConnectivityTransport()) {
+        self.transport = transport
+        self.transport.setStatusUpdateHandler { [weak self] snapshot in
+            Task { @MainActor [weak self] in
+                self?.emitStatusIfChanged(snapshot)
+            }
         }
-        super.init()
-        if let session = self.session {
-            session.delegate = self
-            session.activate()
+        self.transport.setReplyHandler { [weak self] event in
+            Task { @MainActor [weak self] in
+                self?.emitReply(event)
+            }
+        }
+        self.transport.setExecApprovalResolveHandler { [weak self] event in
+            Task { @MainActor [weak self] in
+                self?.emitExecApprovalResolve(event)
+            }
+        }
+        self.transport.setExecApprovalSnapshotRequestHandler { [weak self] event in
+            Task { @MainActor [weak self] in
+                self?.emitExecApprovalSnapshotRequest(event)
+            }
         }
     }
 
     nonisolated static func isSupportedOnDevice() -> Bool {
-        WCSession.isSupported()
+        WatchConnectivityTransport.isSupportedOnDevice()
     }
 
     nonisolated static func currentStatusSnapshot() -> WatchMessagingStatus {
-        guard WCSession.isSupported() else {
-            return WatchMessagingStatus(
-                supported: false,
-                paired: false,
-                appInstalled: false,
-                reachable: false,
-                activationState: "unsupported")
-        }
-        let session = WCSession.default
-        return status(for: session)
+        WatchConnectivityTransport.currentStatusSnapshot()
     }
 
     func status() async -> WatchMessagingStatus {
-        await self.ensureActivated()
-        guard let session = self.session else {
-            return WatchMessagingStatus(
-                supported: false,
-                paired: false,
-                appInstalled: false,
-                reachable: false,
-                activationState: "unsupported")
+        await self.transport.status()
+    }
+
+    func setStatusHandler(_ handler: (@Sendable (WatchMessagingStatus) -> Void)?) {
+        self.statusHandler = handler
+        guard let handler else {
+            self.lastEmittedStatus = nil
+            GatewayDiagnostics.log("watch messaging: cleared status handler")
+            return
         }
-        return Self.status(for: session)
+        let snapshot = self.transport.currentStatusSnapshot()
+        self.lastEmittedStatus = snapshot
+        GatewayDiagnostics.log(
+            "watch messaging: set status handler supported=\(snapshot.supported) paired=\(snapshot.paired) appInstalled=\(snapshot.appInstalled) reachable=\(snapshot.reachable) activation=\(snapshot.activationState)")
+        handler(snapshot)
     }
 
     func setReplyHandler(_ handler: (@Sendable (WatchQuickReplyEvent) -> Void)?) {
         self.replyHandler = handler
     }
 
+    func setExecApprovalResolveHandler(_ handler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?) {
+        self.execApprovalResolveHandler = handler
+    }
+
+    func setExecApprovalSnapshotRequestHandler(
+        _ handler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?)
+    {
+        self.execApprovalSnapshotRequestHandler = handler
+    }
+
     func sendNotification(
         id: String,
         params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult
     {
-        await self.ensureActivated()
-        guard let session = self.session else {
-            throw WatchMessagingError.unsupported
-        }
-
-        let snapshot = Self.status(for: session)
-        guard snapshot.paired else { throw WatchMessagingError.notPaired }
-        guard snapshot.appInstalled else { throw WatchMessagingError.watchAppNotInstalled }
-
-        var payload: [String: Any] = [
-            "type": "watch.notify",
-            "id": id,
-            "title": params.title,
-            "body": params.body,
-            "priority": params.priority?.rawValue ?? OpenClawNotificationPriority.active.rawValue,
-            "sentAtMs": Int(Date().timeIntervalSince1970 * 1000),
-        ]
-        if let promptId = Self.nonEmpty(params.promptId) {
-            payload["promptId"] = promptId
-        }
-        if let sessionKey = Self.nonEmpty(params.sessionKey) {
-            payload["sessionKey"] = sessionKey
-        }
-        if let kind = Self.nonEmpty(params.kind) {
-            payload["kind"] = kind
-        }
-        if let details = Self.nonEmpty(params.details) {
-            payload["details"] = details
-        }
-        if let expiresAtMs = params.expiresAtMs {
-            payload["expiresAtMs"] = expiresAtMs
-        }
-        if let risk = params.risk {
-            payload["risk"] = risk.rawValue
-        }
-        if let actions = params.actions, !actions.isEmpty {
-            payload["actions"] = actions.map { action in
-                var encoded: [String: Any] = [
-                    "id": action.id,
-                    "label": action.label,
-                ]
-                if let style = Self.nonEmpty(action.style) {
-                    encoded["style"] = style
-                }
-                return encoded
-            }
-        }
-
-        if snapshot.reachable {
-            do {
-                try await self.sendReachableMessage(payload, with: session)
-                return WatchNotificationSendResult(
-                    deliveredImmediately: true,
-                    queuedForDelivery: false,
-                    transport: "sendMessage")
-            } catch {
-                Self.logger.error("watch sendMessage failed: \(error.localizedDescription, privacy: .public)")
-            }
-        }
-
-        _ = session.transferUserInfo(payload)
-        return WatchNotificationSendResult(
-            deliveredImmediately: false,
-            queuedForDelivery: true,
-            transport: "transferUserInfo")
+        let payload = WatchMessagingPayloadCodec.encodeNotificationPayload(id: id, params: params)
+        return try await self.transport.sendPayload(payload)
     }
 
-    private func sendReachableMessage(_ payload: [String: Any], with session: WCSession) async throws {
-        try await withCheckedThrowingContinuation { continuation in
-            session.sendMessage(
-                payload,
-                replyHandler: { _ in
-                    continuation.resume()
-                },
-                errorHandler: { error in
-                    continuation.resume(throwing: error)
-                }
-            )
+    func sendExecApprovalPrompt(
+        _ message: OpenClawWatchExecApprovalPromptMessage) async throws -> WatchNotificationSendResult
+    {
+        try await self.transport.sendPayload(
+            WatchMessagingPayloadCodec.encodeExecApprovalPromptPayload(message))
+    }
+
+    func sendExecApprovalResolved(
+        _ message: OpenClawWatchExecApprovalResolvedMessage) async throws -> WatchNotificationSendResult
+    {
+        try await self.transport.sendPayload(
+            WatchMessagingPayloadCodec.encodeExecApprovalResolvedPayload(message))
+    }
+
+    func sendExecApprovalExpired(
+        _ message: OpenClawWatchExecApprovalExpiredMessage) async throws -> WatchNotificationSendResult
+    {
+        try await self.transport.sendPayload(
+            WatchMessagingPayloadCodec.encodeExecApprovalExpiredPayload(message))
+    }
+
+    func syncExecApprovalSnapshot(
+        _ message: OpenClawWatchExecApprovalSnapshotMessage) async throws -> WatchNotificationSendResult
+    {
+        try await self.transport.sendSnapshotPayload(
+            WatchMessagingPayloadCodec.encodeExecApprovalSnapshotPayload(message))
+    }
+
+    private func emitStatusIfChanged(_ snapshot: WatchMessagingStatus) {
+        guard snapshot != self.lastEmittedStatus else {
+            return
         }
+        self.lastEmittedStatus = snapshot
+        GatewayDiagnostics.log(
+            "watch messaging: status supported=\(snapshot.supported) paired=\(snapshot.paired) appInstalled=\(snapshot.appInstalled) reachable=\(snapshot.reachable) activation=\(snapshot.activationState)")
+        self.statusHandler?(snapshot)
     }
 
     private func emitReply(_ event: WatchQuickReplyEvent) {
         self.replyHandler?(event)
     }
 
-    nonisolated private static func nonEmpty(_ value: String?) -> String? {
-        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        return trimmed.isEmpty ? nil : trimmed
+    private func emitExecApprovalResolve(_ event: WatchExecApprovalResolveEvent) {
+        self.execApprovalResolveHandler?(event)
     }
 
-    nonisolated private static func parseQuickReplyPayload(
-        _ payload: [String: Any],
-        transport: String) -> WatchQuickReplyEvent?
-    {
-        guard (payload["type"] as? String) == "watch.reply" else {
-            return nil
-        }
-        guard let actionId = nonEmpty(payload["actionId"] as? String) else {
-            return nil
-        }
-        let promptId = nonEmpty(payload["promptId"] as? String) ?? "unknown"
-        let replyId = nonEmpty(payload["replyId"] as? String) ?? UUID().uuidString
-        let actionLabel = nonEmpty(payload["actionLabel"] as? String)
-        let sessionKey = nonEmpty(payload["sessionKey"] as? String)
-        let note = nonEmpty(payload["note"] as? String)
-        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
-
-        return WatchQuickReplyEvent(
-            replyId: replyId,
-            promptId: promptId,
-            actionId: actionId,
-            actionLabel: actionLabel,
-            sessionKey: sessionKey,
-            note: note,
-            sentAtMs: sentAtMs,
-            transport: transport)
-    }
-
-    private func ensureActivated() async {
-        guard let session = self.session else { return }
-        if session.activationState == .activated { return }
-        session.activate()
-        await withCheckedContinuation { continuation in
-            self.pendingActivationContinuations.append(continuation)
-        }
-    }
-
-    nonisolated private static func status(for session: WCSession) -> WatchMessagingStatus {
-        WatchMessagingStatus(
-            supported: true,
-            paired: session.isPaired,
-            appInstalled: session.isWatchAppInstalled,
-            reachable: session.isReachable,
-            activationState: activationStateLabel(session.activationState))
-    }
-
-    nonisolated private static func activationStateLabel(_ state: WCSessionActivationState) -> String {
-        switch state {
-        case .notActivated:
-            "notActivated"
-        case .inactive:
-            "inactive"
-        case .activated:
-            "activated"
-        @unknown default:
-            "unknown"
-        }
+    private func emitExecApprovalSnapshotRequest(_ event: WatchExecApprovalSnapshotRequestEvent) {
+        GatewayDiagnostics.log(
+            "watch messaging: snapshot request id=\(event.requestId) transport=\(event.transport) sentAtMs=\(event.sentAtMs ?? -1)")
+        self.execApprovalSnapshotRequestHandler?(event)
     }
 }
-
-extension WatchMessagingService: WCSessionDelegate {
-    nonisolated func session(
-        _ session: WCSession,
-        activationDidCompleteWith activationState: WCSessionActivationState,
-        error: (any Error)?)
-    {
-        if let error {
-            Self.logger.error("watch activation failed: \(error.localizedDescription, privacy: .public)")
-        } else {
-            Self.logger.debug("watch activation state=\(Self.activationStateLabel(activationState), privacy: .public)")
-        }
-        // Always resume all waiters so callers never hang, even on error.
-        Task { @MainActor in
-            let waiters = self.pendingActivationContinuations
-            self.pendingActivationContinuations.removeAll()
-            for continuation in waiters {
-                continuation.resume()
-            }
-        }
-    }
-
-    nonisolated func sessionDidBecomeInactive(_ session: WCSession) {}
-
-    nonisolated func sessionDidDeactivate(_ session: WCSession) {
-        session.activate()
-    }
-
-    nonisolated func session(_: WCSession, didReceiveMessage message: [String: Any]) {
-        guard let event = Self.parseQuickReplyPayload(message, transport: "sendMessage") else {
-            return
-        }
-        Task { @MainActor in
-            self.emitReply(event)
-        }
-    }
-
-    nonisolated func session(
-        _: WCSession,
-        didReceiveMessage message: [String: Any],
-        replyHandler: @escaping ([String: Any]) -> Void)
-    {
-        guard let event = Self.parseQuickReplyPayload(message, transport: "sendMessage") else {
-            replyHandler(["ok": false, "error": "unsupported_payload"])
-            return
-        }
-        replyHandler(["ok": true])
-        Task { @MainActor in
-            self.emitReply(event)
-        }
-    }
-
-    nonisolated func session(_: WCSession, didReceiveUserInfo userInfo: [String: Any]) {
-        guard let event = Self.parseQuickReplyPayload(userInfo, transport: "transferUserInfo") else {
-            return
-        }
-        Task { @MainActor in
-            self.emitReply(event)
-        }
-    }
-
-    nonisolated func sessionReachabilityDidChange(_ session: WCSession) {}
-}

apps/ios/Tests/ExecApprovalNotificationBridgeTests.swift

@@ -49,6 +49,32 @@ private final class MockNotificationCenter: NotificationCentering, @unchecked Se
         #expect(prompt == ExecApprovalNotificationPrompt(approvalId: "approval-123"))
     }
 
+    @Test func parsePromptMapsReviewAction() {
+        let prompt = ExecApprovalNotificationBridge.parsePrompt(
+            actionIdentifier: ExecApprovalNotificationBridge.reviewActionIdentifier,
+            userInfo: [
+                "openclaw": [
+                    "kind": ExecApprovalNotificationBridge.requestedKind,
+                    "approvalId": "approval-456",
+                ],
+            ])
+
+        #expect(prompt == ExecApprovalNotificationPrompt(approvalId: "approval-456"))
+    }
+
+    @Test func parsePromptIgnoresUnexpectedActionIdentifiers() {
+        let prompt = ExecApprovalNotificationBridge.parsePrompt(
+            actionIdentifier: "openclaw.exec-approval.allow-once",
+            userInfo: [
+                "openclaw": [
+                    "kind": ExecApprovalNotificationBridge.requestedKind,
+                    "approvalId": "approval-789",
+                ],
+            ])
+
+        #expect(prompt == nil)
+    }
+
     @Test @MainActor func handleResolvedPushRemovesMatchingNotifications() async {
         let center = MockNotificationCenter()
         center.delivered = [

apps/ios/Tests/NodeAppModelInvokeTests.swift

@@ -46,16 +46,37 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
         transport: "sendMessage")
     var sendError: Error?
     var lastSent: (id: String, params: OpenClawWatchNotifyParams)?
+    var lastSentExecApprovalPrompt: OpenClawWatchExecApprovalPromptMessage?
+    var lastSentExecApprovalResolved: OpenClawWatchExecApprovalResolvedMessage?
+    var lastSentExecApprovalExpired: OpenClawWatchExecApprovalExpiredMessage?
+    var lastSentExecApprovalSnapshot: OpenClawWatchExecApprovalSnapshotMessage?
+    private var statusHandler: (@Sendable (WatchMessagingStatus) -> Void)?
     private var replyHandler: (@Sendable (WatchQuickReplyEvent) -> Void)?
+    private var execApprovalResolveHandler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?
+    private var execApprovalSnapshotRequestHandler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?
 
     func status() async -> WatchMessagingStatus {
         self.currentStatus
     }
 
+    func setStatusHandler(_ handler: (@Sendable (WatchMessagingStatus) -> Void)?) {
+        self.statusHandler = handler
+    }
+
     func setReplyHandler(_ handler: (@Sendable (WatchQuickReplyEvent) -> Void)?) {
         self.replyHandler = handler
     }
 
+    func setExecApprovalResolveHandler(_ handler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?) {
+        self.execApprovalResolveHandler = handler
+    }
+
+    func setExecApprovalSnapshotRequestHandler(
+        _ handler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?)
+    {
+        self.execApprovalSnapshotRequestHandler = handler
+    }
+
     func sendNotification(id: String, params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult {
         self.lastSent = (id: id, params: params)
         if let sendError = self.sendError {
@@ -64,9 +85,57 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
         return self.nextSendResult
     }
 
+    func sendExecApprovalPrompt(
+        _ message: OpenClawWatchExecApprovalPromptMessage) async throws -> WatchNotificationSendResult
+    {
+        self.lastSentExecApprovalPrompt = message
+        if let sendError = self.sendError {
+            throw sendError
+        }
+        return self.nextSendResult
+    }
+
+    func sendExecApprovalResolved(
+        _ message: OpenClawWatchExecApprovalResolvedMessage) async throws -> WatchNotificationSendResult
+    {
+        self.lastSentExecApprovalResolved = message
+        if let sendError = self.sendError {
+            throw sendError
+        }
+        return self.nextSendResult
+    }
+
+    func sendExecApprovalExpired(
+        _ message: OpenClawWatchExecApprovalExpiredMessage) async throws -> WatchNotificationSendResult
+    {
+        self.lastSentExecApprovalExpired = message
+        if let sendError = self.sendError {
+            throw sendError
+        }
+        return self.nextSendResult
+    }
+
+    func syncExecApprovalSnapshot(
+        _ message: OpenClawWatchExecApprovalSnapshotMessage) async throws -> WatchNotificationSendResult
+    {
+        self.lastSentExecApprovalSnapshot = message
+        if let sendError = self.sendError {
+            throw sendError
+        }
+        return self.nextSendResult
+    }
+
     func emitReply(_ event: WatchQuickReplyEvent) {
         self.replyHandler?(event)
     }
+
+    func emitExecApprovalResolve(_ event: WatchExecApprovalResolveEvent) {
+        self.execApprovalResolveHandler?(event)
+    }
+
+    func emitExecApprovalSnapshotRequest(_ event: WatchExecApprovalSnapshotRequestEvent) {
+        self.execApprovalSnapshotRequestHandler?(event)
+    }
 }
 
 private final class MockBootstrapNotificationCenter: NotificationCentering, @unchecked Sendable {
@@ -184,6 +253,118 @@ private final class MockBootstrapNotificationCenter: NotificationCentering, @unc
         #expect(prompt.id == "approval-active")
     }
 
+    @Test @MainActor func presentingExecApprovalPromptSyncsWatchPrompt() async throws {
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        let prompt = try #require(
+            NodeAppModel._test_makeExecApprovalPrompt(
+                id: "approval-watch-sync",
+                commandText: "npm publish",
+                allowedDecisions: ["allow-once", "deny"],
+                host: "gateway",
+                nodeId: "node-1",
+                agentId: "main",
+                expiresAtMs: 1234))
+
+        appModel._test_presentExecApprovalPrompt(prompt)
+        await Task.yield()
+
+        let sent = try #require(watchService.lastSentExecApprovalPrompt)
+        #expect(sent.approval.id == "approval-watch-sync")
+        #expect(sent.approval.allowedDecisions == [.allowOnce, .deny])
+        #expect(sent.approval.host == "gateway")
+        #expect(sent.approval.risk == nil)
+        #expect(sent.resetResolvingState != true)
+    }
+
+    @Test @MainActor func watchExecApprovalSnapshotRequestPublishesCachedApprovalsInBackground() async throws {
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        let futureExpiryMs = Int(Date().timeIntervalSince1970 * 1000) + 60_000
+        appModel._test_presentExecApprovalPrompt(
+            try #require(
+                NodeAppModel._test_makeExecApprovalPrompt(
+                    id: "approval-watch-snapshot",
+                    commandText: "echo from watch",
+                    allowedDecisions: ["allow-once", "deny"],
+                    host: "gateway",
+                    nodeId: nil,
+                    agentId: nil,
+                    expiresAtMs: futureExpiryMs)))
+        await Task.yield()
+
+        appModel.setScenePhase(.background)
+        watchService.emitExecApprovalSnapshotRequest(
+            WatchExecApprovalSnapshotRequestEvent(
+                requestId: "snapshot-1",
+                sentAtMs: 111,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        let snapshot = try #require(watchService.lastSentExecApprovalSnapshot)
+        #expect(snapshot.approvals.map(\.id) == ["approval-watch-snapshot"])
+    }
+
+    @Test @MainActor func watchExecApprovalSnapshotRequestSkipsForegroundRecovery() async throws {
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        let futureExpiryMs = Int(Date().timeIntervalSince1970 * 1000) + 60_000
+        appModel._test_presentExecApprovalPrompt(
+            try #require(
+                NodeAppModel._test_makeExecApprovalPrompt(
+                    id: "approval-watch-foreground-skip",
+                    commandText: "echo foreground",
+                    allowedDecisions: ["allow-once", "deny"],
+                    host: "gateway",
+                    nodeId: nil,
+                    agentId: nil,
+                    expiresAtMs: futureExpiryMs)))
+        await Task.yield()
+        watchService.lastSentExecApprovalSnapshot = nil
+
+        watchService.emitExecApprovalSnapshotRequest(
+            WatchExecApprovalSnapshotRequestEvent(
+                requestId: "snapshot-foreground",
+                sentAtMs: 222,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        #expect(watchService.lastSentExecApprovalSnapshot == nil)
+    }
+
+    @Test @MainActor func pendingWatchRecoveryIDsAreIncludedWithoutDeliveredNotifications() async {
+        NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState()
+        defer { NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState() }
+
+        let appModel = NodeAppModel(notificationCenter: MockBootstrapNotificationCenter())
+        appModel._test_recordPendingWatchExecApprovalRecoveryID("approval-watch-recovery")
+
+        let ids = await appModel._test_pendingExecApprovalIDsForWatchRecovery()
+        #expect(ids == ["approval-watch-recovery"])
+    }
+
+    @Test @MainActor func presentingExecApprovalPromptClearsPendingWatchRecoveryID() throws {
+        NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState()
+        defer { NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState() }
+
+        let appModel = NodeAppModel(notificationCenter: MockBootstrapNotificationCenter())
+        appModel._test_recordPendingWatchExecApprovalRecoveryID("approval-watch-clear")
+        #expect(appModel._test_pendingWatchExecApprovalRecoveryIDs() == ["approval-watch-clear"])
+
+        appModel._test_presentExecApprovalPrompt(
+            try #require(
+                NodeAppModel._test_makeExecApprovalPrompt(
+                    id: "approval-watch-clear",
+                    commandText: "echo clear",
+                    allowedDecisions: ["allow-once", "deny"],
+                    host: "gateway",
+                    nodeId: nil,
+                    agentId: nil,
+                    expiresAtMs: Int(Date().timeIntervalSince1970 * 1000) + 60_000)))
+
+        #expect(appModel._test_pendingWatchExecApprovalRecoveryIDs().isEmpty)
+    }
+
     @Test func approvalNotificationErrorClassificationPrefersStructuredDetails() {
         let staleError = GatewayResponseError(
             method: "exec.approval.get",
@@ -200,6 +381,48 @@ private final class MockBootstrapNotificationCenter: NotificationCentering, @unc
         #expect(NodeAppModel._test_isApprovalNotificationUnavailableError(unavailableError))
     }
 
+    @Test func backgroundAwareExecApprovalReconnectCoversWatchAndPushPaths() {
+        #expect(
+            NodeAppModel._test_shouldUseBackgroundAwareExecApprovalReconnect(
+                sourceReason: "watch_request",
+                isBackgrounded: true)
+        )
+        #expect(
+            NodeAppModel._test_shouldUseBackgroundAwareExecApprovalReconnect(
+                sourceReason: "push_request",
+                isBackgrounded: true)
+        )
+        #expect(
+            NodeAppModel._test_shouldUseBackgroundAwareExecApprovalReconnect(
+                sourceReason: "watch_resolve",
+                isBackgrounded: true)
+        )
+        #expect(
+            !NodeAppModel._test_shouldUseBackgroundAwareExecApprovalReconnect(
+                sourceReason: "direct",
+                isBackgrounded: true)
+        )
+        #expect(
+            !NodeAppModel._test_shouldUseBackgroundAwareExecApprovalReconnect(
+                sourceReason: "watch_request",
+                isBackgrounded: false)
+        )
+    }
+
+    @Test func watchExecApprovalHydrateFetchesOnlyMissingIDs() {
+        let idsToFetch = NodeAppModel._test_watchExecApprovalIDsNeedingFetch(
+            candidateIDs: ["cached", "pending", "cached", "other", "", "  pending  "],
+            cachedApprovalIDs: ["cached", "also-cached"])
+
+        #expect(idsToFetch == ["pending", "other"])
+    }
+
+    @Test func watchExecApprovalRetryPromptResetsResolvingStateOnlyForRetryReason() {
+        #expect(NodeAppModel._test_shouldResetWatchExecApprovalResolvingStateOnPrompt(reason: "resolve_retry"))
+        #expect(!NodeAppModel._test_shouldResetWatchExecApprovalResolvingStateOnPrompt(reason: "push_request"))
+        #expect(!NodeAppModel._test_shouldResetWatchExecApprovalResolvingStateOnPrompt(reason: "present_prompt"))
+    }
+
     @Test func operatorLoopWaitsForBootstrapHandoffBeforeUsingStoredToken() {
         #expect(
             !NodeAppModel._test_shouldStartOperatorGatewayLoop(
@@ -590,6 +813,7 @@ private final class MockBootstrapNotificationCenter: NotificationCentering, @unc
                 note: nil,
                 sentAtMs: 1234,
                 transport: "transferUserInfo"))
+        await Task.yield()
         #expect(appModel._test_queuedWatchReplyCount() == 1)
     }
 

apps/ios/Tests/OpenClawAppDelegateTests.swift

@@ -0,0 +1,26 @@
+import Testing
+@testable import OpenClaw
+
+@Suite(.serialized) struct OpenClawAppDelegateTests {
+    @Test @MainActor func resolvesRegistryModelBeforeViewTaskAssignsDelegateModel() {
+        let registryModel = NodeAppModel()
+        OpenClawAppModelRegistry.appModel = registryModel
+        defer { OpenClawAppModelRegistry.appModel = nil }
+
+        let delegate = OpenClawAppDelegate()
+
+        #expect(delegate._test_resolvedAppModel() === registryModel)
+    }
+
+    @Test @MainActor func prefersExplicitDelegateModelOverRegistryFallback() {
+        let registryModel = NodeAppModel()
+        let explicitModel = NodeAppModel()
+        OpenClawAppModelRegistry.appModel = registryModel
+        defer { OpenClawAppModelRegistry.appModel = nil }
+
+        let delegate = OpenClawAppDelegate()
+        delegate.appModel = explicitModel
+
+        #expect(delegate._test_resolvedAppModel() === explicitModel)
+    }
+}

apps/ios/WatchExtension/Sources/OpenClawWatchApp.swift

@@ -2,27 +2,79 @@ import SwiftUI
 
 @main
 struct OpenClawWatchApp: App {
+    @Environment(\.scenePhase) private var scenePhase
     @State private var inboxStore = WatchInboxStore()
     @State private var receiver: WatchConnectivityReceiver?
+    @State private var execApprovalRefreshTask: Task<Void, Never>?
 
     var body: some Scene {
         WindowGroup {
-            WatchInboxView(store: self.inboxStore) { action in
-                guard let receiver = self.receiver else { return }
-                let draft = self.inboxStore.makeReplyDraft(action: action)
-                self.inboxStore.markReplySending(actionLabel: action.label)
-                Task { @MainActor in
-                    let result = await receiver.sendReply(draft)
-                    self.inboxStore.markReplyResult(result, actionLabel: action.label)
-                }
-            }
+            WatchInboxView(
+                store: self.inboxStore,
+                onAction: { action in
+                    guard let receiver = self.receiver else { return }
+                    let draft = self.inboxStore.makeReplyDraft(action: action)
+                    self.inboxStore.markReplySending(actionLabel: action.label)
+                    Task { @MainActor in
+                        let result = await receiver.sendReply(draft)
+                        self.inboxStore.markReplyResult(result, actionLabel: action.label)
+                    }
+                },
+                onExecApprovalDecision: { approvalId, decision in
+                    guard let receiver = self.receiver else { return }
+                    self.inboxStore.markExecApprovalSending(approvalId: approvalId, decision: decision)
+                    Task { @MainActor in
+                        let result = await receiver.sendExecApprovalResolve(
+                            approvalId: approvalId,
+                            decision: decision)
+                        self.inboxStore.markExecApprovalSendResult(
+                            approvalId: approvalId,
+                            decision: decision,
+                            result: result)
+                    }
+                },
+                onRefreshExecApprovalReview: {
+                    self.refreshExecApprovalReview(force: true)
+                })
                 .task {
                     if self.receiver == nil {
                         let receiver = WatchConnectivityReceiver(store: self.inboxStore)
                         receiver.activate()
                         self.receiver = receiver
                     }
+                    self.refreshExecApprovalReview()
+                }
+                .onChange(of: self.scenePhase) { _, newPhase in
+                    guard newPhase == .active else { return }
+                    self.refreshExecApprovalReview()
                 }
         }
     }
+
+    private func refreshExecApprovalReview(force: Bool = false) {
+        guard let receiver = self.receiver else { return }
+        guard force || self.inboxStore.shouldAutoRequestExecApprovalSnapshot else { return }
+
+        self.execApprovalRefreshTask?.cancel()
+        self.execApprovalRefreshTask = Task { @MainActor in
+            self.inboxStore.beginExecApprovalReviewLoading()
+            for attempt in 0..<5 {
+                if Task.isCancelled { return }
+                await receiver.requestExecApprovalSnapshot()
+                if !self.inboxStore.execApprovals.isEmpty
+                    || self.inboxStore.hasCompletedExecApprovalSnapshotRefresh
+                {
+                    self.inboxStore.markExecApprovalReviewLoaded()
+                    return
+                }
+                if attempt < 4 {
+                    try? await Task.sleep(nanoseconds: 700_000_000)
+                }
+            }
+            if self.inboxStore.execApprovals.isEmpty {
+                self.inboxStore.markExecApprovalReviewUnavailable(
+                    "Couldn't load approval from your iPhone yet.")
+            }
+        }
+    }
 }

apps/ios/WatchExtension/Sources/WatchConnectivityReceiver.swift

@@ -52,6 +52,31 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
         }
     }
 
+    func requestExecApprovalSnapshot() async {
+        await self.ensureActivated()
+        guard let session = self.session else { return }
+        let request = WatchExecApprovalSnapshotRequestMessage(
+            requestId: UUID().uuidString,
+            sentAtMs: Self.nowMs())
+        let payload = Self.encodeSnapshotRequestPayload(request)
+        if session.isReachable {
+            do {
+                try await withCheckedThrowingContinuation(isolation: nil) {
+                    (continuation: CheckedContinuation<Void, Error>) in
+                    session.sendMessage(payload, replyHandler: { _ in
+                        continuation.resume(returning: ())
+                    }, errorHandler: { error in
+                        continuation.resume(throwing: error)
+                    })
+                }
+                return
+            } catch {
+                // Fall through to queued delivery.
+            }
+        }
+        _ = session.transferUserInfo(payload)
+    }
+
     func sendReply(_ draft: WatchReplyDraft) async -> WatchReplySendResult {
         await self.ensureActivated()
         guard let session = self.session else {
@@ -63,7 +88,7 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
         }
 
         var payload: [String: Any] = [
-            "type": "watch.reply",
+            "type": WatchPayloadType.reply.rawValue,
             "replyId": draft.replyId,
             "promptId": draft.promptId,
             "actionId": draft.actionId,
@@ -83,11 +108,38 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
             payload["note"] = note
         }
 
+        return await self.sendPayload(payload, session: session)
+    }
+
+    func sendExecApprovalResolve(
+        approvalId: String,
+        decision: WatchExecApprovalDecision) async -> WatchReplySendResult
+    {
+        await self.ensureActivated()
+        guard let session = self.session else {
+            return WatchReplySendResult(
+                deliveredImmediately: false,
+                queuedForDelivery: false,
+                transport: "none",
+                errorMessage: "watch session unavailable")
+        }
+
+        let payload = Self.encodeExecApprovalResolvePayload(
+            WatchExecApprovalResolveMessage(
+                approvalId: approvalId,
+                decision: decision,
+                replyId: UUID().uuidString,
+                sentAtMs: Self.nowMs()))
+        return await self.sendPayload(payload, session: session)
+    }
+
+    private func sendPayload(_ payload: [String: Any], session: WCSession) async -> WatchReplySendResult {
         if session.isReachable {
             do {
-                try await withCheckedThrowingContinuation { continuation in
+                try await withCheckedThrowingContinuation(isolation: nil) {
+                    (continuation: CheckedContinuation<Void, Error>) in
                     session.sendMessage(payload, replyHandler: { _ in
-                        continuation.resume()
+                        continuation.resume(returning: ())
                     }, errorHandler: { error in
                         continuation.resume(throwing: error)
                     })
@@ -110,6 +162,10 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
             errorMessage: nil)
     }
 
+    private static func nowMs() -> Int {
+        Int(Date().timeIntervalSince1970 * 1000)
+    }
+
     private static func normalizeObject(_ value: Any) -> [String: Any]? {
         if let object = value as? [String: Any] {
             return object
@@ -147,7 +203,9 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
     }
 
     private static func parseNotificationPayload(_ payload: [String: Any]) -> WatchNotifyMessage? {
-        guard let type = payload["type"] as? String, type == "watch.notify" else {
+        guard let type = payload["type"] as? String,
+              type == WatchPayloadType.notify.rawValue
+        else {
             return nil
         }
 
@@ -189,6 +247,153 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
             risk: risk,
             actions: actions)
     }
+
+    private static func parseExecApprovalDecision(_ value: Any?) -> WatchExecApprovalDecision? {
+        let raw = (value as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return WatchExecApprovalDecision(rawValue: raw)
+    }
+
+    private static func parseExecApprovalItem(_ value: Any?) -> WatchExecApprovalItem? {
+        guard let payload = value.flatMap(Self.normalizeObject) else {
+            return nil
+        }
+        let id = (payload["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let commandText = (payload["commandText"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !id.isEmpty, !commandText.isEmpty else {
+            return nil
+        }
+        let commandPreview = (payload["commandPreview"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let host = (payload["host"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let nodeId = (payload["nodeId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let agentId = (payload["agentId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let expiresAtMs = (payload["expiresAtMs"] as? Int) ?? (payload["expiresAtMs"] as? NSNumber)?.intValue
+        let riskRaw = (payload["risk"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let risk = WatchRiskLevel(rawValue: riskRaw)
+        let allowedDecisions = (payload["allowedDecisions"] as? [Any] ?? []).compactMap {
+            Self.parseExecApprovalDecision($0)
+        }
+        return WatchExecApprovalItem(
+            id: id,
+            commandText: commandText,
+            commandPreview: commandPreview,
+            host: host,
+            nodeId: nodeId,
+            agentId: agentId,
+            expiresAtMs: expiresAtMs,
+            allowedDecisions: allowedDecisions,
+            risk: risk)
+    }
+
+    private static func parseExecApprovalPromptPayload(
+        _ payload: [String: Any]) -> WatchExecApprovalPromptMessage?
+    {
+        guard let type = payload["type"] as? String,
+              type == WatchPayloadType.execApprovalPrompt.rawValue,
+              let approval = Self.parseExecApprovalItem(payload["approval"])
+        else {
+            return nil
+        }
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        let deliveryId = (payload["deliveryId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let resetResolvingState = payload["resetResolvingState"] as? Bool
+        return WatchExecApprovalPromptMessage(
+            approval: approval,
+            sentAtMs: sentAtMs,
+            deliveryId: deliveryId,
+            resetResolvingState: resetResolvingState)
+    }
+
+    private static func parseExecApprovalResolvedPayload(
+        _ payload: [String: Any]) -> WatchExecApprovalResolvedMessage?
+    {
+        guard let type = payload["type"] as? String,
+              type == WatchPayloadType.execApprovalResolved.rawValue
+        else {
+            return nil
+        }
+        let approvalId = (payload["approvalId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !approvalId.isEmpty else { return nil }
+        let decision = Self.parseExecApprovalDecision(payload["decision"])
+        let resolvedAtMs = (payload["resolvedAtMs"] as? Int)
+            ?? (payload["resolvedAtMs"] as? NSNumber)?.intValue
+        let source = (payload["source"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return WatchExecApprovalResolvedMessage(
+            approvalId: approvalId,
+            decision: decision,
+            resolvedAtMs: resolvedAtMs,
+            source: source)
+    }
+
+    private static func parseExecApprovalExpiredPayload(
+        _ payload: [String: Any]) -> WatchExecApprovalExpiredMessage?
+    {
+        guard let type = payload["type"] as? String,
+              type == WatchPayloadType.execApprovalExpired.rawValue
+        else {
+            return nil
+        }
+        let approvalId = (payload["approvalId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let rawReason = (payload["reason"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !approvalId.isEmpty,
+              let reason = WatchExecApprovalCloseReason(rawValue: rawReason)
+        else {
+            return nil
+        }
+        let expiredAtMs = (payload["expiredAtMs"] as? Int) ?? (payload["expiredAtMs"] as? NSNumber)?.intValue
+        return WatchExecApprovalExpiredMessage(
+            approvalId: approvalId,
+            reason: reason,
+            expiredAtMs: expiredAtMs)
+    }
+
+    private static func parseExecApprovalSnapshotPayload(
+        _ payload: [String: Any]) -> WatchExecApprovalSnapshotMessage?
+    {
+        guard let type = payload["type"] as? String,
+              type == WatchPayloadType.execApprovalSnapshot.rawValue
+        else {
+            return nil
+        }
+        let approvals = (payload["approvals"] as? [Any] ?? []).compactMap { item in
+            Self.parseExecApprovalItem(item)
+        }
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        let snapshotId = (payload["snapshotId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return WatchExecApprovalSnapshotMessage(
+            approvals: approvals,
+            sentAtMs: sentAtMs,
+            snapshotId: snapshotId)
+    }
+
+    private static func encodeSnapshotRequestPayload(
+        _ request: WatchExecApprovalSnapshotRequestMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": WatchPayloadType.execApprovalSnapshotRequest.rawValue,
+            "requestId": request.requestId,
+        ]
+        if let sentAtMs = request.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        return payload
+    }
+
+    private static func encodeExecApprovalResolvePayload(
+        _ message: WatchExecApprovalResolveMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": WatchPayloadType.execApprovalResolve.rawValue,
+            "approvalId": message.approvalId,
+            "decision": message.decision.rawValue,
+            "replyId": message.replyId,
+        ]
+        if let sentAtMs = message.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        return payload
+    }
 }
 
 extension WatchConnectivityReceiver: WCSessionDelegate {
@@ -196,13 +401,14 @@ extension WatchConnectivityReceiver: WCSessionDelegate {
         _: WCSession,
         activationDidCompleteWith _: WCSessionActivationState,
         error _: (any Error)?)
-    {}
+    {
+        Task {
+            await self.requestExecApprovalSnapshot()
+        }
+    }
 
     func session(_: WCSession, didReceiveMessage message: [String: Any]) {
-        guard let incoming = Self.parseNotificationPayload(message) else { return }
-        Task { @MainActor in
-            self.store.consume(message: incoming, transport: "sendMessage")
-        }
+        self.consumeIncomingPayload(message, transport: "sendMessage")
     }
 
     func session(
@@ -210,27 +416,47 @@ extension WatchConnectivityReceiver: WCSessionDelegate {
         didReceiveMessage message: [String: Any],
         replyHandler: @escaping ([String: Any]) -> Void)
     {
-        guard let incoming = Self.parseNotificationPayload(message) else {
-            replyHandler(["ok": false])
-            return
-        }
         replyHandler(["ok": true])
-        Task { @MainActor in
-            self.store.consume(message: incoming, transport: "sendMessage")
-        }
+        self.consumeIncomingPayload(message, transport: "sendMessage")
     }
 
     func session(_: WCSession, didReceiveUserInfo userInfo: [String: Any]) {
-        guard let incoming = Self.parseNotificationPayload(userInfo) else { return }
-        Task { @MainActor in
-            self.store.consume(message: incoming, transport: "transferUserInfo")
-        }
+        self.consumeIncomingPayload(userInfo, transport: "transferUserInfo")
     }
 
     func session(_: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
-        guard let incoming = Self.parseNotificationPayload(applicationContext) else { return }
-        Task { @MainActor in
-            self.store.consume(message: incoming, transport: "applicationContext")
+        self.consumeIncomingPayload(applicationContext, transport: "applicationContext")
+    }
+
+    private func consumeIncomingPayload(_ payload: [String: Any], transport: String) {
+        if let incoming = Self.parseNotificationPayload(payload) {
+            Task { @MainActor in
+                self.store.consume(message: incoming, transport: transport)
+            }
+            return
+        }
+        if let prompt = Self.parseExecApprovalPromptPayload(payload) {
+            Task { @MainActor in
+                self.store.consume(execApprovalPrompt: prompt, transport: transport)
+            }
+            return
+        }
+        if let resolved = Self.parseExecApprovalResolvedPayload(payload) {
+            Task { @MainActor in
+                self.store.consume(execApprovalResolved: resolved)
+            }
+            return
+        }
+        if let expired = Self.parseExecApprovalExpiredPayload(payload) {
+            Task { @MainActor in
+                self.store.consume(execApprovalExpired: expired)
+            }
+            return
+        }
+        if let snapshot = Self.parseExecApprovalSnapshotPayload(payload) {
+            Task { @MainActor in
+                self.store.consume(execApprovalSnapshot: snapshot, transport: transport)
+            }
         }
     }
 }

apps/ios/WatchExtension/Sources/WatchInboxStore.swift

@@ -3,6 +3,86 @@ import Observation
 import UserNotifications
 import WatchKit
 
+enum WatchPayloadType: String, Codable, Sendable, Equatable {
+    case notify = "watch.notify"
+    case reply = "watch.reply"
+    case execApprovalPrompt = "watch.execApproval.prompt"
+    case execApprovalResolve = "watch.execApproval.resolve"
+    case execApprovalResolved = "watch.execApproval.resolved"
+    case execApprovalExpired = "watch.execApproval.expired"
+    case execApprovalSnapshot = "watch.execApproval.snapshot"
+    case execApprovalSnapshotRequest = "watch.execApproval.snapshotRequest"
+}
+
+enum WatchRiskLevel: String, Codable, Sendable, Equatable {
+    case low
+    case medium
+    case high
+}
+
+enum WatchExecApprovalDecision: String, Codable, Sendable, Equatable {
+    case allowOnce = "allow-once"
+    case deny
+}
+
+enum WatchExecApprovalCloseReason: String, Codable, Sendable, Equatable {
+    case expired
+    case notFound = "not-found"
+    case unavailable
+    case replaced
+    case resolved
+}
+
+struct WatchExecApprovalItem: Codable, Sendable, Equatable, Identifiable {
+    var id: String
+    var commandText: String
+    var commandPreview: String?
+    var host: String?
+    var nodeId: String?
+    var agentId: String?
+    var expiresAtMs: Int?
+    var allowedDecisions: [WatchExecApprovalDecision]
+    var risk: WatchRiskLevel?
+}
+
+struct WatchExecApprovalPromptMessage: Codable, Sendable, Equatable {
+    var approval: WatchExecApprovalItem
+    var sentAtMs: Int?
+    var deliveryId: String?
+    var resetResolvingState: Bool?
+}
+
+struct WatchExecApprovalResolvedMessage: Codable, Sendable, Equatable {
+    var approvalId: String
+    var decision: WatchExecApprovalDecision?
+    var resolvedAtMs: Int?
+    var source: String?
+}
+
+struct WatchExecApprovalExpiredMessage: Codable, Sendable, Equatable {
+    var approvalId: String
+    var reason: WatchExecApprovalCloseReason
+    var expiredAtMs: Int?
+}
+
+struct WatchExecApprovalSnapshotMessage: Codable, Sendable, Equatable {
+    var approvals: [WatchExecApprovalItem]
+    var sentAtMs: Int?
+    var snapshotId: String?
+}
+
+struct WatchExecApprovalSnapshotRequestMessage: Codable, Sendable, Equatable {
+    var requestId: String
+    var sentAtMs: Int?
+}
+
+struct WatchExecApprovalResolveMessage: Codable, Sendable, Equatable {
+    var approvalId: String
+    var decision: WatchExecApprovalDecision
+    var replyId: String
+    var sentAtMs: Int?
+}
+
 struct WatchPromptAction: Codable, Sendable, Equatable, Identifiable {
     var id: String
     var label: String
@@ -23,6 +103,18 @@ struct WatchNotifyMessage: Sendable {
     var actions: [WatchPromptAction]
 }
 
+struct WatchExecApprovalRecord: Codable, Sendable, Equatable, Identifiable {
+    var approval: WatchExecApprovalItem
+    var transport: String
+    var updatedAt: Date
+    var isResolving: Bool
+    var pendingDecision: WatchExecApprovalDecision?
+    var statusText: String?
+    var statusAt: Date?
+
+    var id: String { self.approval.id }
+}
+
 @MainActor @Observable final class WatchInboxStore {
     private struct PersistedState: Codable {
         var title: String
@@ -39,13 +131,20 @@ struct WatchNotifyMessage: Sendable {
         var actions: [WatchPromptAction]?
         var replyStatusText: String?
         var replyStatusAt: Date?
+        var execApprovals: [WatchExecApprovalRecord]
+        var selectedExecApprovalID: String?
+        var lastExecApprovalSnapshotID: String?
+        var lastExecApprovalOutcomeText: String?
+        var lastExecApprovalOutcomeAt: Date?
     }
 
-    private static let persistedStateKey = "watch.inbox.state.v1"
+    private static let persistedStateKey = "watch.inbox.state.v2"
+    private static let defaultTitle = "OpenClaw"
+    private static let defaultBody = "Waiting for messages from your iPhone."
     private let defaults: UserDefaults
 
-    var title = "OpenClaw"
-    var body = "Waiting for messages from your iPhone."
+    var title = WatchInboxStore.defaultTitle
+    var body = WatchInboxStore.defaultBody
     var transport = "none"
     var updatedAt: Date?
     var promptId: String?
@@ -58,16 +157,88 @@ struct WatchNotifyMessage: Sendable {
     var replyStatusText: String?
     var replyStatusAt: Date?
     var isReplySending = false
+    var execApprovals: [WatchExecApprovalRecord] = []
+    var selectedExecApprovalID: String?
+    var lastExecApprovalOutcomeText: String?
+    var lastExecApprovalOutcomeAt: Date?
+    var isExecApprovalReviewLoading = false
+    var execApprovalReviewStatusText: String?
+    var execApprovalReviewStatusAt: Date?
+    private var lastExecApprovalSnapshotID: String?
+    private var hasCompletedExecApprovalSnapshotRefreshInSession = false
     private var lastDeliveryKey: String?
 
     init(defaults: UserDefaults = .standard) {
         self.defaults = defaults
         self.restorePersistedState()
+        self.pruneExpiredExecApprovals(nowMs: Self.nowMs())
         Task {
             await self.ensureNotificationAuthorization()
         }
     }
 
+    var sortedExecApprovals: [WatchExecApprovalRecord] {
+        self.execApprovals.sorted { lhs, rhs in
+            let lhsExpires = lhs.approval.expiresAtMs ?? Int.max
+            let rhsExpires = rhs.approval.expiresAtMs ?? Int.max
+            if lhsExpires != rhsExpires {
+                return lhsExpires < rhsExpires
+            }
+            return lhs.updatedAt > rhs.updatedAt
+        }
+    }
+
+    var activeExecApproval: WatchExecApprovalRecord? {
+        if let selectedExecApprovalID,
+           let selected = self.execApprovals.first(where: { $0.id == selectedExecApprovalID })
+        {
+            return selected
+        }
+        return self.sortedExecApprovals.first
+    }
+
+    var shouldAutoRequestExecApprovalSnapshot: Bool {
+        self.execApprovals.isEmpty
+            && self.actions.isEmpty
+            && self.title == Self.defaultTitle
+            && self.body == Self.defaultBody
+            && !self.hasCompletedExecApprovalSnapshotRefreshInSession
+    }
+
+    var hasCompletedExecApprovalSnapshotRefresh: Bool {
+        self.hasCompletedExecApprovalSnapshotRefreshInSession
+    }
+
+    var shouldShowExecApprovalReviewStatus: Bool {
+        self.execApprovals.isEmpty && !(self.execApprovalReviewStatusText?.isEmpty ?? true)
+    }
+
+    func beginExecApprovalReviewLoading() {
+        guard self.execApprovals.isEmpty else {
+            self.markExecApprovalReviewLoaded()
+            return
+        }
+        self.isExecApprovalReviewLoading = true
+        self.execApprovalReviewStatusText = "Loading approval from iPhone…"
+        self.execApprovalReviewStatusAt = Date()
+    }
+
+    func markExecApprovalReviewLoaded() {
+        self.isExecApprovalReviewLoading = false
+        self.execApprovalReviewStatusText = nil
+        self.execApprovalReviewStatusAt = nil
+    }
+
+    func markExecApprovalReviewUnavailable(_ message: String) {
+        guard self.execApprovals.isEmpty else {
+            self.markExecApprovalReviewLoaded()
+            return
+        }
+        self.isExecApprovalReviewLoading = false
+        self.execApprovalReviewStatusText = message
+        self.execApprovalReviewStatusAt = Date()
+    }
+
     func consume(message: WatchNotifyMessage, transport: String) {
         let messageID = message.id?
             .trimmingCharacters(in: .whitespacesAndNewlines)
@@ -82,6 +253,7 @@ struct WatchNotifyMessage: Sendable {
         self.title = normalizedTitle
         self.body = message.body
         self.transport = transport
+        self.markExecApprovalReviewLoaded()
         self.updatedAt = Date()
         self.promptId = message.promptId
         self.sessionKey = message.sessionKey
@@ -105,6 +277,209 @@ struct WatchNotifyMessage: Sendable {
         }
     }
 
+    func consume(
+        execApprovalPrompt message: WatchExecApprovalPromptMessage,
+        transport: String)
+    {
+        self.pruneExpiredExecApprovals(nowMs: Self.nowMs())
+        self.upsertExecApproval(
+            message.approval,
+            transport: transport,
+            keepSelectionIfPossible: true,
+            resetResolvingState: message.resetResolvingState == true)
+        self.markExecApprovalReviewLoaded()
+        self.lastExecApprovalOutcomeText = nil
+        self.lastExecApprovalOutcomeAt = nil
+
+        Task {
+            await self.postLocalNotification(
+                identifier: "watch.execApproval.\(message.approval.id)",
+                title: "Exec approval required",
+                body: message.approval.commandPreview ?? message.approval.commandText,
+                risk: message.approval.risk?.rawValue)
+        }
+    }
+
+    func consume(
+        execApprovalSnapshot message: WatchExecApprovalSnapshotMessage,
+        transport: String)
+    {
+        let snapshotID = message.snapshotId?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let snapshotID, !snapshotID.isEmpty, snapshotID == self.lastExecApprovalSnapshotID {
+            return
+        }
+
+        let existingRecordsByID = Dictionary(
+            uniqueKeysWithValues: self.execApprovals.map { ($0.id, $0) })
+        self.execApprovals = message.approvals.map { approval in
+            self.mergedExecApprovalRecord(
+                approval: approval,
+                transport: transport,
+                existingRecord: existingRecordsByID[approval.id])
+        }
+        self.lastExecApprovalSnapshotID = snapshotID
+        self.hasCompletedExecApprovalSnapshotRefreshInSession = true
+        if let selectedExecApprovalID,
+           !self.execApprovals.contains(where: { $0.id == selectedExecApprovalID })
+        {
+            self.selectedExecApprovalID = self.sortedExecApprovals.first?.id
+        } else if self.selectedExecApprovalID == nil {
+            self.selectedExecApprovalID = self.sortedExecApprovals.first?.id
+        }
+        self.pruneExpiredExecApprovals(nowMs: Self.nowMs())
+        self.markExecApprovalReviewLoaded()
+        self.persistState()
+    }
+
+    func consume(execApprovalResolved message: WatchExecApprovalResolvedMessage) {
+        self.removeExecApproval(id: message.approvalId)
+        let statusText: String
+        switch message.decision {
+        case .allowOnce:
+            statusText = "Allowed once"
+        case .deny:
+            statusText = "Denied"
+        case nil:
+            statusText = "Approval resolved"
+        }
+        self.lastExecApprovalOutcomeText = statusText
+        self.lastExecApprovalOutcomeAt = Date()
+        self.persistState()
+    }
+
+    func consume(execApprovalExpired message: WatchExecApprovalExpiredMessage) {
+        self.removeExecApproval(id: message.approvalId)
+        let statusText: String
+        switch message.reason {
+        case .expired:
+            statusText = "Approval expired"
+        case .notFound:
+            statusText = "Approval no longer available"
+        case .resolved:
+            statusText = "Approval resolved elsewhere"
+        case .replaced:
+            statusText = "Approval replaced"
+        case .unavailable:
+            statusText = "Approval unavailable"
+        }
+        self.lastExecApprovalOutcomeText = statusText
+        self.lastExecApprovalOutcomeAt = Date()
+        self.persistState()
+    }
+
+    func selectExecApproval(id: String) {
+        let normalizedID = id.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedID.isEmpty else { return }
+        guard self.execApprovals.contains(where: { $0.id == normalizedID }) else { return }
+        self.selectedExecApprovalID = normalizedID
+        self.persistState()
+    }
+
+    func markExecApprovalSending(approvalId: String, decision: WatchExecApprovalDecision) {
+        guard let index = self.execApprovals.firstIndex(where: { $0.id == approvalId }) else { return }
+        self.execApprovals[index].isResolving = true
+        self.execApprovals[index].pendingDecision = decision
+        self.execApprovals[index].statusText = "Sending \(Self.decisionLabel(decision))…"
+        self.execApprovals[index].statusAt = Date()
+        self.persistState()
+    }
+
+    func markExecApprovalSendResult(
+        approvalId: String,
+        decision: WatchExecApprovalDecision,
+        result: WatchReplySendResult)
+    {
+        guard let index = self.execApprovals.firstIndex(where: { $0.id == approvalId }) else { return }
+        if let errorMessage = result.errorMessage, !errorMessage.isEmpty {
+            self.execApprovals[index].isResolving = false
+            self.execApprovals[index].statusText = "Failed: \(errorMessage)"
+        } else if result.deliveredImmediately {
+            self.execApprovals[index].isResolving = true
+            self.execApprovals[index].statusText = "\(Self.decisionLabel(decision)): sent"
+        } else if result.queuedForDelivery {
+            self.execApprovals[index].isResolving = true
+            self.execApprovals[index].statusText = "\(Self.decisionLabel(decision)): queued"
+        } else {
+            self.execApprovals[index].isResolving = true
+            self.execApprovals[index].statusText = "\(Self.decisionLabel(decision)): sent"
+        }
+        self.execApprovals[index].pendingDecision = result.errorMessage == nil ? decision : nil
+        self.execApprovals[index].statusAt = Date()
+        self.persistState()
+    }
+
+    private func upsertExecApproval(
+        _ approval: WatchExecApprovalItem,
+        transport: String,
+        keepSelectionIfPossible: Bool,
+        resetResolvingState: Bool = false)
+    {
+        if let index = self.execApprovals.firstIndex(where: { $0.id == approval.id }) {
+            self.execApprovals[index] = self.mergedExecApprovalRecord(
+                approval: approval,
+                transport: transport,
+                existingRecord: self.execApprovals[index],
+                resetResolvingState: resetResolvingState)
+        } else {
+            self.execApprovals.append(
+                self.mergedExecApprovalRecord(
+                    approval: approval,
+                    transport: transport,
+                    existingRecord: nil,
+                    resetResolvingState: resetResolvingState))
+        }
+        if !keepSelectionIfPossible || self.selectedExecApprovalID == nil {
+            self.selectedExecApprovalID = approval.id
+        }
+        self.persistState()
+    }
+
+    private func mergedExecApprovalRecord(
+        approval: WatchExecApprovalItem,
+        transport: String,
+        existingRecord: WatchExecApprovalRecord?,
+        resetResolvingState: Bool = false) -> WatchExecApprovalRecord
+    {
+        // Preserve in-flight state across ordinary snapshot/prompt refreshes so duplicate
+        // submissions stay disabled, but clear it when the iPhone explicitly republishes a
+        // prompt after a failed resolve so the watch can retry.
+        let isResolving = resetResolvingState ? false : (existingRecord?.isResolving ?? false)
+        let pendingDecision = resetResolvingState ? nil : existingRecord?.pendingDecision
+        let statusText = resetResolvingState ? nil : existingRecord?.statusText
+        let statusAt = resetResolvingState ? nil : existingRecord?.statusAt
+        return WatchExecApprovalRecord(
+            approval: approval,
+            transport: transport,
+            updatedAt: Date(),
+            isResolving: isResolving,
+            pendingDecision: pendingDecision,
+            statusText: statusText,
+            statusAt: statusAt)
+    }
+
+    private func removeExecApproval(id: String) {
+        let normalizedID = id.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedID.isEmpty else { return }
+        self.execApprovals.removeAll { $0.id == normalizedID }
+        if self.selectedExecApprovalID == normalizedID {
+            self.selectedExecApprovalID = self.sortedExecApprovals.first?.id
+        }
+        self.persistState()
+    }
+
+    private func pruneExpiredExecApprovals(nowMs: Int) {
+        self.execApprovals.removeAll { record in
+            guard let expiresAtMs = record.approval.expiresAtMs else { return false }
+            return expiresAtMs <= nowMs
+        }
+        if let selectedExecApprovalID,
+           !self.execApprovals.contains(where: { $0.id == selectedExecApprovalID })
+        {
+            self.selectedExecApprovalID = self.sortedExecApprovals.first?.id
+        }
+        self.persistState()
+    }
+
     private func restorePersistedState() {
         guard let data = self.defaults.data(forKey: Self.persistedStateKey),
             let state = try? JSONDecoder().decode(PersistedState.self, from: data)
@@ -126,10 +501,15 @@ struct WatchNotifyMessage: Sendable {
         self.actions = state.actions ?? []
         self.replyStatusText = state.replyStatusText
         self.replyStatusAt = state.replyStatusAt
+        self.execApprovals = state.execApprovals
+        self.selectedExecApprovalID = state.selectedExecApprovalID
+        self.lastExecApprovalSnapshotID = state.lastExecApprovalSnapshotID
+        self.lastExecApprovalOutcomeText = state.lastExecApprovalOutcomeText
+        self.lastExecApprovalOutcomeAt = state.lastExecApprovalOutcomeAt
     }
 
     private func persistState() {
-        guard let updatedAt = self.updatedAt else { return }
+        let updatedAt = self.updatedAt ?? self.lastExecApprovalOutcomeAt ?? Date()
         let state = PersistedState(
             title: self.title,
             body: self.body,
@@ -144,7 +524,12 @@ struct WatchNotifyMessage: Sendable {
             risk: self.risk,
             actions: self.actions,
             replyStatusText: self.replyStatusText,
-            replyStatusAt: self.replyStatusAt)
+            replyStatusAt: self.replyStatusAt,
+            execApprovals: self.execApprovals,
+            selectedExecApprovalID: self.selectedExecApprovalID,
+            lastExecApprovalSnapshotID: self.lastExecApprovalSnapshotID,
+            lastExecApprovalOutcomeText: self.lastExecApprovalOutcomeText,
+            lastExecApprovalOutcomeAt: self.lastExecApprovalOutcomeAt)
         guard let data = try? JSONEncoder().encode(state) else { return }
         self.defaults.set(data, forKey: Self.persistedStateKey)
     }
@@ -187,7 +572,7 @@ struct WatchNotifyMessage: Sendable {
             actionLabel: action.label,
             sessionKey: self.sessionKey,
             note: nil,
-            sentAtMs: Int(Date().timeIntervalSince1970 * 1000))
+            sentAtMs: Self.nowMs())
     }
 
     func markReplySending(actionLabel: String) {
@@ -227,4 +612,17 @@ struct WatchNotifyMessage: Sendable {
         _ = try? await UNUserNotificationCenter.current().add(request)
         WKInterfaceDevice.current().play(self.mapHapticRisk(risk))
     }
+
+    private static func decisionLabel(_ decision: WatchExecApprovalDecision) -> String {
+        switch decision {
+        case .allowOnce:
+            "Allow Once"
+        case .deny:
+            "Deny"
+        }
+    }
+
+    private static func nowMs() -> Int {
+        Int(Date().timeIntervalSince1970 * 1000)
+    }
 }

apps/ios/WatchExtension/Sources/WatchInboxView.swift

@@ -1,7 +1,246 @@
 import SwiftUI
 
 struct WatchInboxView: View {
-    @Bindable var store: WatchInboxStore
+    var store: WatchInboxStore
+    var onAction: ((WatchPromptAction) -> Void)?
+    var onExecApprovalDecision: ((String, WatchExecApprovalDecision) -> Void)?
+    var onRefreshExecApprovalReview: (() -> Void)?
+
+    var body: some View {
+        NavigationStack {
+            if self.store.sortedExecApprovals.count == 1,
+               let record = self.store.activeExecApproval
+            {
+                WatchExecApprovalDetailView(
+                    store: self.store,
+                    record: record,
+                    onDecision: self.onExecApprovalDecision)
+            } else if !self.store.sortedExecApprovals.isEmpty {
+                WatchExecApprovalListView(
+                    store: self.store,
+                    onDecision: self.onExecApprovalDecision)
+            } else if self.store.shouldShowExecApprovalReviewStatus {
+                WatchExecApprovalLoadingView(
+                    store: self.store,
+                    onRetry: self.onRefreshExecApprovalReview)
+            } else {
+                WatchGenericInboxView(store: self.store, onAction: self.onAction)
+            }
+        }
+    }
+}
+
+private struct WatchExecApprovalLoadingView: View {
+    var store: WatchInboxStore
+    var onRetry: (() -> Void)?
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 10) {
+                Text("Exec approval")
+                    .font(.headline)
+
+                if self.store.isExecApprovalReviewLoading {
+                    ProgressView()
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                }
+
+                if let statusText = self.store.execApprovalReviewStatusText, !statusText.isEmpty {
+                    Text(statusText)
+                        .font(.body)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if !self.store.isExecApprovalReviewLoading {
+                    Button("Retry") {
+                        self.onRetry?()
+                    }
+                }
+
+                Text("Keep your iPhone nearby and unlocked if review details take a moment to appear.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding()
+        }
+        .navigationTitle("Exec approval")
+    }
+}
+
+private struct WatchExecApprovalListView: View {
+    var store: WatchInboxStore
+    var onDecision: ((String, WatchExecApprovalDecision) -> Void)?
+
+    var body: some View {
+        List {
+            Section("Exec approvals") {
+                ForEach(self.store.sortedExecApprovals) { record in
+                    NavigationLink {
+                        WatchExecApprovalDetailView(
+                            store: self.store,
+                            record: record,
+                            onDecision: self.onDecision)
+                    } label: {
+                        VStack(alignment: .leading, spacing: 4) {
+                            Text(record.approval.commandPreview ?? record.approval.commandText)
+                                .font(.headline)
+                                .lineLimit(2)
+                            Text(self.metadataLine(for: record))
+                                .font(.footnote)
+                                .foregroundStyle(.secondary)
+                                .lineLimit(2)
+                            if let statusText = record.statusText, !statusText.isEmpty {
+                                Text(statusText)
+                                    .font(.footnote)
+                                    .foregroundStyle(record.isResolving ? Color.secondary : Color.red)
+                                    .lineLimit(2)
+                            }
+                        }
+                    }
+                }
+            }
+
+            if let outcome = self.store.lastExecApprovalOutcomeText, !outcome.isEmpty {
+                Section("Last result") {
+                    Text(outcome)
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+            }
+        }
+        .navigationTitle("Approvals")
+    }
+
+    private func metadataLine(for record: WatchExecApprovalRecord) -> String {
+        var parts: [String] = []
+        if let host = record.approval.host, !host.isEmpty {
+            parts.append(host)
+        }
+        if let nodeId = record.approval.nodeId, !nodeId.isEmpty {
+            parts.append(nodeId)
+        }
+        if let expiresText = Self.expiresText(record.approval.expiresAtMs) {
+            parts.append(expiresText)
+        }
+        return parts.isEmpty ? "Pending review" : parts.joined(separator: " · ")
+    }
+
+    private static func expiresText(_ expiresAtMs: Int?) -> String? {
+        guard let expiresAtMs else { return nil }
+        let deltaSeconds = max(0, (expiresAtMs - Int(Date().timeIntervalSince1970 * 1000)) / 1000)
+        if deltaSeconds < 60 {
+            return "Expires in <1m"
+        }
+        return "Expires in \(deltaSeconds / 60)m"
+    }
+}
+
+private struct WatchExecApprovalDetailView: View {
+    var store: WatchInboxStore
+    let record: WatchExecApprovalRecord
+    var onDecision: ((String, WatchExecApprovalDecision) -> Void)?
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 10) {
+                Text(self.record.approval.commandText)
+                    .font(.headline)
+                    .fixedSize(horizontal: false, vertical: true)
+
+                if let host = self.record.approval.host, !host.isEmpty {
+                    self.metadataRow(label: "Host", value: host)
+                }
+                if let nodeId = self.record.approval.nodeId, !nodeId.isEmpty {
+                    self.metadataRow(label: "Node", value: nodeId)
+                }
+                if let agentId = self.record.approval.agentId, !agentId.isEmpty {
+                    self.metadataRow(label: "Agent", value: agentId)
+                }
+                if let expiresText = Self.expiresText(self.record.approval.expiresAtMs) {
+                    self.metadataRow(label: "Expires", value: expiresText)
+                }
+                if let riskText = self.riskText(self.record.approval.risk) {
+                    self.metadataRow(label: "Risk", value: riskText)
+                }
+
+                if let statusText = self.currentRecord?.statusText, !statusText.isEmpty {
+                    Text(statusText)
+                        .font(.footnote)
+                        .foregroundStyle((self.currentRecord?.isResolving ?? false) ? Color.secondary : Color.red)
+                }
+
+                if let currentRecord,
+                   currentRecord.approval.allowedDecisions.contains(.allowOnce)
+                {
+                    Button("Allow Once") {
+                        self.onDecision?(currentRecord.id, .allowOnce)
+                    }
+                    .disabled(currentRecord.isResolving)
+                }
+
+                if let currentRecord,
+                   currentRecord.approval.allowedDecisions.contains(.deny)
+                {
+                    Button(role: .destructive) {
+                        self.onDecision?(currentRecord.id, .deny)
+                    } label: {
+                        Text("Deny")
+                            .frame(maxWidth: .infinity)
+                    }
+                    .disabled(currentRecord.isResolving)
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding()
+        }
+        .navigationTitle("Exec approval")
+        .onAppear {
+            self.store.selectExecApproval(id: self.record.id)
+        }
+    }
+
+    private var currentRecord: WatchExecApprovalRecord? {
+        self.store.execApprovals.first(where: { $0.id == self.record.id })
+    }
+
+    private func metadataRow(label: String, value: String) -> some View {
+        VStack(alignment: .leading, spacing: 2) {
+            Text(label)
+                .font(.caption2)
+                .foregroundStyle(.secondary)
+            Text(value)
+                .font(.footnote)
+                .fixedSize(horizontal: false, vertical: true)
+        }
+    }
+
+    private func riskText(_ risk: WatchRiskLevel?) -> String? {
+        switch risk {
+        case .high:
+            return "High"
+        case .medium:
+            return "Medium"
+        case .low:
+            return "Low"
+        case nil:
+            return nil
+        }
+    }
+
+    private static func expiresText(_ expiresAtMs: Int?) -> String? {
+        guard let expiresAtMs else { return nil }
+        let deltaSeconds = max(0, (expiresAtMs - Int(Date().timeIntervalSince1970 * 1000)) / 1000)
+        if deltaSeconds < 60 {
+            return "<1 minute"
+        }
+        return "\(deltaSeconds / 60) minutes"
+    }
+}
+
+private struct WatchGenericInboxView: View {
+    var store: WatchInboxStore
     var onAction: ((WatchPromptAction) -> Void)?
 
     private func role(for action: WatchPromptAction) -> ButtonRole? {
@@ -18,40 +257,46 @@ struct WatchInboxView: View {
     var body: some View {
         ScrollView {
             VStack(alignment: .leading, spacing: 8) {
-                Text(store.title)
+                Text(self.store.title)
                     .font(.headline)
                     .lineLimit(2)
 
-                Text(store.body)
+                Text(self.store.body)
                     .font(.body)
                     .fixedSize(horizontal: false, vertical: true)
 
-                if let details = store.details, !details.isEmpty {
+                if let details = self.store.details, !details.isEmpty {
                     Text(details)
                         .font(.footnote)
                         .foregroundStyle(.secondary)
                         .fixedSize(horizontal: false, vertical: true)
                 }
 
-                if !store.actions.isEmpty {
-                    ForEach(store.actions) { action in
+                if let outcome = self.store.lastExecApprovalOutcomeText, !outcome.isEmpty {
+                    Text(outcome)
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+
+                if !self.store.actions.isEmpty {
+                    ForEach(self.store.actions) { action in
                         Button(role: self.role(for: action)) {
                             self.onAction?(action)
                         } label: {
                             Text(action.label)
                                 .frame(maxWidth: .infinity)
                         }
-                        .disabled(store.isReplySending)
+                        .disabled(self.store.isReplySending)
                     }
                 }
 
-                if let replyStatusText = store.replyStatusText, !replyStatusText.isEmpty {
+                if let replyStatusText = self.store.replyStatusText, !replyStatusText.isEmpty {
                     Text(replyStatusText)
                         .font(.footnote)
                         .foregroundStyle(.secondary)
                 }
 
-                if let updatedAt = store.updatedAt {
+                if let updatedAt = self.store.updatedAt {
                     Text("Updated \(updatedAt.formatted(date: .omitted, time: .shortened))")
                         .font(.footnote)
                         .foregroundStyle(.secondary)
@@ -60,5 +305,6 @@ struct WatchInboxView: View {
             .frame(maxWidth: .infinity, alignment: .leading)
             .padding()
         }
+        .navigationTitle("OpenClaw")
     }
 }

apps/ios/fastlane/SETUP.md

@@ -29,6 +29,8 @@ ASC_KEYCHAIN_SERVICE=openclaw-asc-key
 ASC_KEYCHAIN_ACCOUNT=YOUR_MAC_USERNAME
 ```
 
+Important: `apps/ios/fastlane/.env` is only for Fastlane/App Store Connect auth and optional beta-archive settings. It does **not** configure gateway-side direct APNs push delivery for local iOS builds.
+
 Optional app targeting variables (helpful if Fastlane cannot auto-resolve app by bundle):
 
 ```bash
@@ -53,6 +55,8 @@ IOS_DEVELOPMENT_TEAM=YOUR_TEAM_ID
 
 Tip: run `scripts/ios-team-id.sh` from repo root to print a Team ID for `.env`. The helper prefers the canonical OpenClaw team (`Y5PE65HELJ`) when present locally; otherwise it prefers the first non-personal team from your Xcode account (then personal team if needed). Fastlane uses this helper automatically if `IOS_DEVELOPMENT_TEAM` is missing.
 
+For local/manual iOS builds that stay on direct APNs, configure the gateway host separately with `OPENCLAW_APNS_TEAM_ID`, `OPENCLAW_APNS_KEY_ID`, and either `OPENCLAW_APNS_PRIVATE_KEY_P8` or `OPENCLAW_APNS_PRIVATE_KEY_PATH`. Those gateway runtime env vars are separate from Fastlane's `.env`.
+
 Validate auth:
 
 ```bash

apps/ios/project.yml

@@ -237,12 +237,19 @@ targets:
     configFiles:
       Debug: Config/Signing.xcconfig
       Release: Config/Signing.xcconfig
+    attributes:
+      DevelopmentTeam: "$(OPENCLAW_DEVELOPMENT_TEAM)"
+      ProvisioningStyle: "$(OPENCLAW_CODE_SIGN_STYLE)"
     settings:
       base:
         ASSETCATALOG_COMPILER_APPICON_NAME: AppIcon
+        CODE_SIGN_IDENTITY: "Apple Development"
+        CODE_SIGN_STYLE: "$(OPENCLAW_CODE_SIGN_STYLE)"
+        DEVELOPMENT_TEAM: "$(OPENCLAW_DEVELOPMENT_TEAM)"
         ENABLE_APPINTENTS_METADATA: NO
         ENABLE_APP_INTENTS_METADATA_GENERATION: NO
         PRODUCT_BUNDLE_IDENTIFIER: "$(OPENCLAW_WATCH_APP_BUNDLE_ID)"
+        PROVISIONING_PROFILE_SPECIFIER: "$(OPENCLAW_WATCH_APP_PROFILE)"
     info:
       path: WatchApp/Info.plist
       properties:
@@ -265,9 +272,16 @@ targets:
     configFiles:
       Debug: Config/Signing.xcconfig
       Release: Config/Signing.xcconfig
+    attributes:
+      DevelopmentTeam: "$(OPENCLAW_DEVELOPMENT_TEAM)"
+      ProvisioningStyle: "$(OPENCLAW_CODE_SIGN_STYLE)"
     settings:
       base:
+        CODE_SIGN_IDENTITY: "Apple Development"
+        CODE_SIGN_STYLE: "$(OPENCLAW_CODE_SIGN_STYLE)"
+        DEVELOPMENT_TEAM: "$(OPENCLAW_DEVELOPMENT_TEAM)"
         PRODUCT_BUNDLE_IDENTIFIER: "$(OPENCLAW_WATCH_EXTENSION_BUNDLE_ID)"
+        PROVISIONING_PROFILE_SPECIFIER: "$(OPENCLAW_WATCH_EXTENSION_PROFILE)"
     info:
       path: WatchExtension/Info.plist
       properties:

apps/macos/Sources/OpenClaw/GatewayEnvironment.swift

@@ -299,6 +299,10 @@ enum GatewayEnvironment {
         if normalized.lowercased().hasPrefix("openclaw ") {
             normalized = String(normalized.dropFirst("openclaw ".count))
         }
+        // Strip trailing commit metadata, e.g. "2026.4.2 (d74a122)" → "2026.4.2"
+        if let parenRange = normalized.range(of: #"\s*\([0-9a-fA-F]+\)\s*$"#, options: .regularExpression) {
+            normalized = String(normalized[normalized.startIndex..<parenRange.lowerBound])
+        }
         return normalized
     }
 

apps/macos/Sources/OpenClaw/HostEnvSecurityPolicy.generated.swift

@@ -28,6 +28,8 @@ enum HostEnvSecurityPolicy {
         "CC",
         "CXX",
         "CARGO_BUILD_RUSTC",
+        "CARGO_BUILD_RUSTC_WRAPPER",
+        "RUSTC_WRAPPER",
         "CMAKE_C_COMPILER",
         "CMAKE_CXX_COMPILER",
         "SHELL",
@@ -44,9 +46,12 @@ enum HostEnvSecurityPolicy {
         "DOTNET_ADDITIONAL_DEPS",
         "GLIBC_TUNABLES",
         "MAVEN_OPTS",
+        "MAKEFLAGS",
+        "MFLAGS",
         "SBT_OPTS",
         "GRADLE_OPTS",
-        "ANT_OPTS"
+        "ANT_OPTS",
+        "HGRCPATH"
     ]
 
     static let blockedOverrideKeys: Set<String> = [
@@ -83,6 +88,8 @@ enum HostEnvSecurityPolicy {
         "CGO_CFLAGS",
         "CGO_LDFLAGS",
         "GOFLAGS",
+        "MAKEFLAGS",
+        "MFLAGS",
         "CORECLR_PROFILER_PATH",
         "PHPRC",
         "PHP_INI_SCAN_DIR",
@@ -134,7 +141,9 @@ enum HostEnvSecurityPolicy {
         "GOPRIVATE",
         "GOENV",
         "GOPATH",
+        "HGRCPATH",
         "PYTHONUSERBASE",
+        "RUSTC_WRAPPER",
         "VIRTUAL_ENV",
         "LUA_PATH",
         "LUA_CPATH",
@@ -142,6 +151,7 @@ enum HostEnvSecurityPolicy {
         "GEM_PATH",
         "BUNDLE_GEMFILE",
         "COMPOSER_HOME",
+        "CARGO_BUILD_RUSTC_WRAPPER",
         "XDG_CONFIG_HOME",
         "AWS_CONFIG_FILE"
     ]

apps/macos/Tests/OpenClawIPCTests/GatewayEnvironmentTests.swift

@@ -30,6 +30,17 @@ struct GatewayEnvironmentTests {
         #expect(Semver.parse(normalized) == Semver(major: 2026, minor: 3, patch: 23))
     }
 
+    @Test func `gateway version output strips trailing commit hash`() {
+        let normalized = GatewayEnvironment.normalizeGatewayVersionOutput("OpenClaw 2026.4.2 (d74a122)")
+        #expect(normalized == "2026.4.2")
+        #expect(Semver.parse(normalized) == Semver(major: 2026, minor: 4, patch: 2))
+
+        // Pre-release suffix + commit hash combined
+        let normalized2 = GatewayEnvironment.normalizeGatewayVersionOutput("OpenClaw 2026.4.2-1 (d74a122)")
+        #expect(normalized2 == "2026.4.2-1")
+        #expect(Semver.parse(normalized2) == Semver(major: 2026, minor: 4, patch: 2))
+    }
+
     @Test func `semver compatibility requires same major and not older`() {
         let required = Semver(major: 2, minor: 1, patch: 0)
         #expect(Semver(major: 2, minor: 1, patch: 0).compatible(with: required))

apps/shared/OpenClawKit/Sources/OpenClawKit/Resources/tool-display.json

@@ -361,14 +361,6 @@
         }
       }
     },
-    "update_plan": {
-      "emoji": "🗺️",
-      "title": "Update Plan",
-      "detailKeys": [
-        "explanation",
-        "plan.0.step"
-      ]
-    },
     "gateway": {
       "emoji": "🔌",
       "title": "Gateway",

apps/shared/OpenClawKit/Sources/OpenClawKit/WatchCommands.swift

@@ -5,12 +5,36 @@ public enum OpenClawWatchCommand: String, Codable, Sendable {
     case notify = "watch.notify"
 }
 
+public enum OpenClawWatchPayloadType: String, Codable, Sendable, Equatable {
+    case notify = "watch.notify"
+    case reply = "watch.reply"
+    case execApprovalPrompt = "watch.execApproval.prompt"
+    case execApprovalResolve = "watch.execApproval.resolve"
+    case execApprovalResolved = "watch.execApproval.resolved"
+    case execApprovalExpired = "watch.execApproval.expired"
+    case execApprovalSnapshot = "watch.execApproval.snapshot"
+    case execApprovalSnapshotRequest = "watch.execApproval.snapshotRequest"
+}
+
 public enum OpenClawWatchRisk: String, Codable, Sendable, Equatable {
     case low
     case medium
     case high
 }
 
+public enum OpenClawWatchExecApprovalDecision: String, Codable, Sendable, Equatable {
+    case allowOnce = "allow-once"
+    case deny
+}
+
+public enum OpenClawWatchExecApprovalCloseReason: String, Codable, Sendable, Equatable {
+    case expired
+    case notFound = "not-found"
+    case unavailable
+    case replaced
+    case resolved
+}
+
 public struct OpenClawWatchAction: Codable, Sendable, Equatable {
     public var id: String
     public var label: String
@@ -23,6 +47,151 @@ public struct OpenClawWatchAction: Codable, Sendable, Equatable {
     }
 }
 
+public struct OpenClawWatchExecApprovalItem: Codable, Sendable, Equatable, Identifiable {
+    public var id: String
+    public var commandText: String
+    public var commandPreview: String?
+    public var host: String?
+    public var nodeId: String?
+    public var agentId: String?
+    public var expiresAtMs: Int?
+    public var allowedDecisions: [OpenClawWatchExecApprovalDecision]
+    public var risk: OpenClawWatchRisk?
+
+    public init(
+        id: String,
+        commandText: String,
+        commandPreview: String? = nil,
+        host: String? = nil,
+        nodeId: String? = nil,
+        agentId: String? = nil,
+        expiresAtMs: Int? = nil,
+        allowedDecisions: [OpenClawWatchExecApprovalDecision] = [],
+        risk: OpenClawWatchRisk? = nil)
+    {
+        self.id = id
+        self.commandText = commandText
+        self.commandPreview = commandPreview
+        self.host = host
+        self.nodeId = nodeId
+        self.agentId = agentId
+        self.expiresAtMs = expiresAtMs
+        self.allowedDecisions = allowedDecisions
+        self.risk = risk
+    }
+}
+
+public struct OpenClawWatchExecApprovalPromptMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var approval: OpenClawWatchExecApprovalItem
+    public var sentAtMs: Int?
+    public var deliveryId: String?
+    public var resetResolvingState: Bool?
+
+    public init(
+        approval: OpenClawWatchExecApprovalItem,
+        sentAtMs: Int? = nil,
+        deliveryId: String? = nil,
+        resetResolvingState: Bool? = nil)
+    {
+        self.type = .execApprovalPrompt
+        self.approval = approval
+        self.sentAtMs = sentAtMs
+        self.deliveryId = deliveryId
+        self.resetResolvingState = resetResolvingState
+    }
+}
+
+public struct OpenClawWatchExecApprovalResolveMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var approvalId: String
+    public var decision: OpenClawWatchExecApprovalDecision
+    public var replyId: String
+    public var sentAtMs: Int?
+
+    public init(
+        approvalId: String,
+        decision: OpenClawWatchExecApprovalDecision,
+        replyId: String,
+        sentAtMs: Int? = nil)
+    {
+        self.type = .execApprovalResolve
+        self.approvalId = approvalId
+        self.decision = decision
+        self.replyId = replyId
+        self.sentAtMs = sentAtMs
+    }
+}
+
+public struct OpenClawWatchExecApprovalResolvedMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var approvalId: String
+    public var decision: OpenClawWatchExecApprovalDecision?
+    public var resolvedAtMs: Int?
+    public var source: String?
+
+    public init(
+        approvalId: String,
+        decision: OpenClawWatchExecApprovalDecision? = nil,
+        resolvedAtMs: Int? = nil,
+        source: String? = nil)
+    {
+        self.type = .execApprovalResolved
+        self.approvalId = approvalId
+        self.decision = decision
+        self.resolvedAtMs = resolvedAtMs
+        self.source = source
+    }
+}
+
+public struct OpenClawWatchExecApprovalExpiredMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var approvalId: String
+    public var reason: OpenClawWatchExecApprovalCloseReason
+    public var expiredAtMs: Int?
+
+    public init(
+        approvalId: String,
+        reason: OpenClawWatchExecApprovalCloseReason,
+        expiredAtMs: Int? = nil)
+    {
+        self.type = .execApprovalExpired
+        self.approvalId = approvalId
+        self.reason = reason
+        self.expiredAtMs = expiredAtMs
+    }
+}
+
+public struct OpenClawWatchExecApprovalSnapshotMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var approvals: [OpenClawWatchExecApprovalItem]
+    public var sentAtMs: Int?
+    public var snapshotId: String?
+
+    public init(
+        approvals: [OpenClawWatchExecApprovalItem],
+        sentAtMs: Int? = nil,
+        snapshotId: String? = nil)
+    {
+        self.type = .execApprovalSnapshot
+        self.approvals = approvals
+        self.sentAtMs = sentAtMs
+        self.snapshotId = snapshotId
+    }
+}
+
+public struct OpenClawWatchExecApprovalSnapshotRequestMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var requestId: String
+    public var sentAtMs: Int?
+
+    public init(requestId: String, sentAtMs: Int? = nil) {
+        self.type = .execApprovalSnapshotRequest
+        self.requestId = requestId
+        self.sentAtMs = sentAtMs
+    }
+}
+
 public struct OpenClawWatchStatusPayload: Codable, Sendable, Equatable {
     public var supported: Bool
     public var paired: Bool

docs/.generated/plugin-sdk-api-baseline.sha256

@@ -1,2 +1,2 @@
-7770bd71ffc20bd65c90f0eb1aa33f46784809f87f014004f8e7a0a5acd2506b  plugin-sdk-api-baseline.json
-ebe0d3f30710a7a977530d7d15b390b0b30bbaecb1a586dd56292dea667cb06e  plugin-sdk-api-baseline.jsonl
+08615a28ed3deb20a96c9cd8fd7237a4cbb209ceec93dca03b543979304459e4  plugin-sdk-api-baseline.json
+683c1249dc15529d8e79bc75e9c00484551cb74126befee507fffcf786e01833  plugin-sdk-api-baseline.jsonl

docs/channels/groups.md

@@ -190,8 +190,8 @@ Control how group/room messages are handled per channel:
       groupPolicy: "allowlist",
       groupAllowFrom: ["@owner:example.org"],
       groups: {
-        "!roomId:example.org": { allow: true },
-        "#alias:example.org": { allow: true },
+        "!roomId:example.org": { enabled: true },
+        "#alias:example.org": { enabled: true },
       },
     },
   },

docs/channels/matrix.md

@@ -44,6 +44,7 @@ See [Plugins](/tools/plugin) for plugin behavior and install rules.
    - `homeserver` + `userId` + `password`.
 4. Restart the gateway.
 5. Start a DM with the bot or invite it to a room.
+   - Fresh Matrix invites only work when `channels.matrix.autoJoin` allows them.
 
 Interactive setup paths:
 
@@ -70,6 +71,44 @@ Wizard behavior that matters:
 - Runtime room/session identity uses the stable Matrix room ID. Room-declared aliases are only used as lookup inputs, not as the long-term session key or stable group identity.
 - To resolve room names before saving them, use `openclaw channels resolve --channel matrix "Project Room"`.
 
+<Warning>
+`channels.matrix.autoJoin` defaults to `off`.
+
+If you leave it unset, the bot will not join invited rooms or fresh DM-style invites, so it will not appear in new groups or invited DMs unless you join manually first.
+
+Set `autoJoin: "allowlist"` together with `autoJoinAllowlist` to restrict which invites it accepts, or set `autoJoin: "always"` if you want it to join every invite.
+</Warning>
+
+Allowlist example:
+
+```json5
+{
+  channels: {
+    matrix: {
+      autoJoin: "allowlist",
+      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
+      groups: {
+        "!ops:example.org": {
+          requireMention: true,
+        },
+      },
+    },
+  },
+}
+```
+
+Join every invite:
+
+```json5
+{
+  channels: {
+    matrix: {
+      autoJoin: "always",
+    },
+  },
+}
+```
+
 Minimal token-based setup:
 
 ```json5
@@ -920,14 +959,16 @@ By default, OpenClaw blocks private/internal Matrix homeservers for SSRF protect
 explicitly opt in per account.
 
 If your homeserver runs on localhost, a LAN/Tailscale IP, or an internal hostname, enable
-`allowPrivateNetwork` for that Matrix account:
+`network.dangerouslyAllowPrivateNetwork` for that Matrix account:
 
 ```json5
 {
   channels: {
     matrix: {
       homeserver: "http://matrix-synapse:8008",
-      allowPrivateNetwork: true,
+      network: {
+        dangerouslyAllowPrivateNetwork: true,
+      },
       accessToken: "syt_internal_xxx",
     },
   },
@@ -986,7 +1027,7 @@ Live directory lookup uses the logged-in Matrix account:
 - `name`: optional label for the account.
 - `defaultAccount`: preferred account ID when multiple Matrix accounts are configured.
 - `homeserver`: homeserver URL, for example `https://matrix.example.org`.
-- `allowPrivateNetwork`: allow this Matrix account to connect to private/internal homeservers. Enable this when the homeserver resolves to `localhost`, a LAN/Tailscale IP, or an internal host such as `matrix-synapse`.
+- `network.dangerouslyAllowPrivateNetwork`: allow this Matrix account to connect to private/internal homeservers. Enable this when the homeserver resolves to `localhost`, a LAN/Tailscale IP, or an internal host such as `matrix-synapse`.
 - `proxy`: optional HTTP(S) proxy URL for Matrix traffic. Named accounts can override the top-level default with their own `proxy`.
 - `userId`: full Matrix user ID, for example `@bot:example.org`.
 - `accessToken`: access token for token-based auth. Plaintext values and SecretRef values are supported for `channels.matrix.accessToken` and `channels.matrix.accounts.<id>.accessToken` across env/file/exec providers. See [Secrets Management](/gateway/secrets).
@@ -1003,7 +1044,7 @@ Live directory lookup uses the logged-in Matrix account:
 - `groupAllowFrom`: allowlist of user IDs for room traffic.
 - `groupAllowFrom` entries should be full Matrix user IDs. Unresolved names are ignored at runtime.
 - `historyLimit`: max room messages to include as group history context. Falls back to `messages.groupChat.historyLimit`; if both are unset, the effective default is `0`. Set `0` to disable.
-- `replyToMode`: `off`, `first`, or `all`.
+- `replyToMode`: `off`, `first`, `all`, or `batched`.
 - `markdown`: optional Markdown rendering configuration for outbound Matrix text.
 - `streaming`: `off` (default), `partial`, `quiet`, `true`, or `false`. `partial` and `true` enable preview-first draft updates with normal Matrix text messages. `quiet` uses non-notifying preview notices for self-hosted push-rule setups.
 - `blockStreaming`: `true` enables separate progress messages for completed assistant blocks while draft preview streaming is active.

docs/channels/qa-channel.md

@@ -75,10 +75,13 @@ self-check, and writes a Markdown report under `.artifacts/qa-e2e/`.
 Private debugger UI:
 
 ```bash
-pnpm qa:lab:build
-pnpm openclaw qa ui
+pnpm qa:lab:up
 ```
 
+That one command builds the QA site, starts the Docker-backed gateway + QA Lab
+stack, and prints the QA Lab URL. From that site you can pick scenarios, choose
+the model lane, launch individual runs, and watch results live.
+
 Full repo-backed QA suite:
 
 ```bash
@@ -96,10 +99,10 @@ Current scope is intentionally narrow:
 - threaded routing grammar
 - channel-owned message actions
 - Markdown reporting
+- Docker-backed QA site with run controls
 
 Follow-up work will add:
 
-- Dockerized OpenClaw orchestration
 - provider/model matrix execution
 - richer scenario discovery
 - OpenClaw-native orchestration later

docs/channels/whatsapp.md

@@ -145,6 +145,7 @@ OpenClaw recommends running WhatsApp on a separate number when possible. (The ch
 - Status and broadcast chats are ignored (`@status`, `@broadcast`).
 - Direct chats use DM session rules (`session.dmScope`; default `main` collapses DMs to the agent main session).
 - Group sessions are isolated (`agent:<agentId>:whatsapp:group:<jid>`).
+- WhatsApp Web transport honors standard proxy environment variables on the gateway host (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / lowercase variants). Prefer host-level proxy config over channel-specific WhatsApp proxy settings.
 
 ## Access control and activation
 

docs/cli/capability.md

@@ -0,0 +1,116 @@
+---
+summary: "Capability-first CLI for provider-backed model, media, web, and embedding workflows"
+read_when:
+  - Adding or modifying `openclaw capability` commands
+  - Designing stable headless capability automation
+title: "Capability CLI"
+---
+
+# Capability CLI
+
+`openclaw capability` is the canonical headless surface for provider-backed capabilities.
+
+It intentionally exposes capability families, not raw gateway RPC names and not raw agent tool ids.
+
+## Command tree
+
+```text
+openclaw capability
+  list
+  inspect
+
+  model
+    run
+    list
+    inspect
+    providers
+    auth login
+    auth logout
+    auth status
+
+  media
+    image
+      generate
+      edit
+      describe
+      describe-many
+      providers
+    audio
+      transcribe
+      providers
+    tts
+      convert
+      voices
+      providers
+      status
+      enable
+      disable
+      set-provider
+    video
+      generate
+      describe
+      providers
+
+  web
+    search
+    fetch
+    providers
+
+  memory
+    embedding
+      create
+      providers
+```
+
+## Transport
+
+Supported transport flags:
+
+- `--local`
+- `--gateway`
+
+Default transport is implicit auto at the command-family level:
+
+- Stateless execution commands default to local.
+- Gateway-managed state commands default to gateway.
+
+Examples:
+
+```bash
+openclaw capability model run --prompt "hello" --json
+openclaw capability media image generate --prompt "friendly lobster" --json
+openclaw capability media tts status --json
+openclaw capability embedding create --text "hello world" --json
+```
+
+## JSON output
+
+Capability commands normalize JSON output under a shared envelope:
+
+```json
+{
+  "ok": true,
+  "capability": "media.image.generate",
+  "transport": "local",
+  "provider": "openai",
+  "model": "gpt-image-1",
+  "attempts": [],
+  "outputs": []
+}
+```
+
+Top-level fields are stable:
+
+- `ok`
+- `capability`
+- `transport`
+- `provider`
+- `model`
+- `attempts`
+- `outputs`
+- `error`
+
+## Notes
+
+- `model run` reuses the agent runtime so provider/model overrides behave like normal agent execution.
+- `media tts status` defaults to gateway because it reflects gateway-managed TTS state.

docs/cli/gateway.md

@@ -57,6 +57,7 @@ Notes:
 - `--reset`: reset dev config + credentials + sessions + workspace (requires `--dev`).
 - `--force`: kill any existing listener on the selected port before starting.
 - `--verbose`: verbose logs.
+- `--cli-backend-logs`: only show CLI backend logs in the console (and enable stdout/stderr).
 - `--ws-log <auto|full|compact>`: websocket log style (default `auto`).
 - `--compact`: alias for `--ws-log compact`.
 - `--raw-stream`: log raw model stream events to jsonl.

docs/cli/index.md

@@ -35,6 +35,7 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`logs`](/cli/logs)
 - [`system`](/cli/system)
 - [`models`](/cli/models)
+- [`capability`](/cli/capability)
 - [`memory`](/cli/memory)
 - [`directory`](/cli/directory)
 - [`nodes`](/cli/nodes)
@@ -248,6 +249,16 @@ openclaw [--dev] [--profile <name>] <command>
     fallbacks list|add|remove|clear
     image-fallbacks list|add|remove|clear
     scan
+  capability
+    list
+    inspect
+    model run|list|inspect|providers|auth login|logout|status
+    media image generate|edit|describe|describe-many|providers
+    media audio transcribe|providers
+    media tts convert|voices|providers|status|enable|disable|set-provider
+    media video generate|describe|providers
+    web search|fetch|providers
+    embedding create|providers
     auth add|login|login-github-copilot|setup-token|paste-token
     auth order get|set|clear
   sandbox
@@ -501,7 +512,7 @@ Options:
   `openrouter-api-key`, `kilocode-api-key`, `litellm-api-key`, `ai-gateway-api-key`,
   `cloudflare-ai-gateway-api-key`, `moonshot-api-key`, `moonshot-api-key-cn`,
   `kimi-code-api-key`, `synthetic-api-key`, `venice-api-key`, `together-api-key`,
-  `huggingface-api-key`, `apiKey`, `gemini-api-key`, `zai-api-key`,
+  `huggingface-api-key`, `apiKey`, `gemini-api-key`, `google-gemini-cli`, `zai-api-key`,
   `zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`, `xiaomi-api-key`,
   `minimax-global-oauth`, `minimax-global-api`, `minimax-cn-oauth`, `minimax-cn-api`,
   `opencode-zen`, `opencode-go`, `github-copilot`, `copilot-proxy`, `xai-api-key`,
@@ -1353,6 +1364,7 @@ Options:
 - `--reset` (reset dev config + credentials + sessions + workspace)
 - `--force` (kill existing listener on port)
 - `--verbose`
+- `--cli-backend-logs`
 - `--ws-log <auto|full|compact>`
 - `--compact` (alias for `--ws-log compact`)
 - `--raw-stream`
@@ -1477,20 +1489,14 @@ Tip: the owner-only `gateway` runtime tool still refuses to rewrite `tools.exec.
 
 See [/concepts/models](/concepts/models) for fallback behavior and scanning strategy.
 
-Billing note: for Anthropic in OpenClaw, the practical split is **API key** or
-**Claude subscription with Extra Usage**. Anthropic notified OpenClaw users on
-**April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw**
-Claude-login path counts as third-party harness usage and requires
-**Extra Usage** billed separately from the subscription. Our local repros also
-show the OpenClaw-identifying prompt string does not reproduce on the
-Anthropic SDK + API-key path. For production, prefer an Anthropic API key or
-another supported subscription-style provider such as OpenAI Codex, Alibaba
-Cloud Model Studio Coding Plan, MiniMax Coding Plan, or Z.AI / GLM Coding
-Plan.
+Anthropic note: Anthropic staff told us OpenClaw-style Claude CLI usage is
+allowed again, so OpenClaw treats Claude CLI reuse and `claude -p` usage as
+sanctioned for this integration unless Anthropic publishes a new policy. For
+production, prefer an Anthropic API key or another supported
+subscription-style provider such as OpenAI Codex, Alibaba Cloud Model Studio
+Coding Plan, MiniMax Coding Plan, or Z.AI / GLM Coding Plan.
 
-Anthropic setup-token is available again as a legacy/manual auth path.
-Use it only with the expectation that Anthropic told OpenClaw users the
-OpenClaw-managed Anthropic subscription path requires **Extra Usage**.
+Anthropic setup-token remains available as a supported token-auth path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
 
 ### `models` (root)
 
@@ -1600,7 +1606,7 @@ Notes:
 - `setup-token` and `paste-token` are generic token commands for providers that expose token auth methods.
 - `setup-token` requires an interactive TTY and runs the provider's token-auth method.
 - `paste-token` prompts for the token value and defaults to auth profile id `<provider>:manual` when `--profile-id` is omitted.
-- Anthropic `setup-token` / `paste-token` are available again as a legacy/manual OpenClaw path. Anthropic told OpenClaw users this path requires **Extra Usage** on the Claude account.
+- Anthropic `setup-token` / `paste-token` remain available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
 
 ### `models auth order get|set|clear`
 

docs/cli/models.md

@@ -130,5 +130,5 @@ Notes:
   `--profile-id`.
 - `paste-token --expires-in <duration>` stores an absolute token expiry from a
   relative duration such as `365d` or `12h`.
-- Anthropic billing note: for Anthropic in OpenClaw, the practical split is **API key** or **Claude subscription with Extra Usage**. Anthropic notified OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription. Our local repros also show the OpenClaw-identifying prompt string does not reproduce on the Anthropic SDK + API-key path.
-- Anthropic `setup-token` / `paste-token` are available again as a legacy/manual OpenClaw path. Use them with the expectation that Anthropic told OpenClaw users this path requires **Extra Usage**.
+- Anthropic note: Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned for this integration unless Anthropic publishes a new policy.
+- Anthropic `setup-token` / `paste-token` remain available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.

docs/concepts/context.md

@@ -167,7 +167,7 @@ pluggable interface, lifecycle hooks, and configuration.
 `/context` prefers the latest **run-built** system prompt report when available:
 
 - `System prompt (run)` = captured from the last embedded (tool-capable) run and persisted in the session store.
-- `System prompt (estimate)` = computed on the fly when no run report exists yet.
+- `System prompt (estimate)` = computed on the fly when no run report exists (or when running via a CLI backend that doesn’t generate the report).
 
 Either way, it reports sizes and top contributors; it does **not** dump the full system prompt or tool schemas.
 

docs/concepts/model-failover.md

@@ -59,6 +59,7 @@ happened while the attempt was running.
 OpenClaw uses **auth profiles** for both API keys and OAuth tokens.
 
 - Secrets live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (legacy: `~/.openclaw/agent/auth-profiles.json`).
+- Runtime auth-routing state lives in `~/.openclaw/agents/<agentId>/agent/auth-state.json`.
 - Config `auth.profiles` / `auth.order` are **metadata + routing only** (no secrets).
 - Legacy import-only OAuth file: `~/.openclaw/credentials/oauth.json` (imported into `auth-profiles.json` on first use).
 
@@ -155,7 +156,7 @@ Cooldowns use exponential backoff:
 - 25 minutes
 - 1 hour (cap)
 
-State is stored in `auth-profiles.json` under `usageStats`:
+State is stored in `auth-state.json` under `usageStats`:
 
 ```json
 {
@@ -184,7 +185,7 @@ limit reached, resets tomorrow`, or `organization spending limit exceeded`).
 Those stay on the short cooldown/failover path instead of the long
 billing-disable path.
 
-State is stored in `auth-profiles.json`:
+State is stored in `auth-state.json`:
 
 ```json
 {

docs/concepts/model-providers.md

@@ -165,11 +165,13 @@ Current bundled examples:
   wrappers, provider-family metadata, bundled image-generation provider
   registration for `gpt-image-1`, and bundled video-generation provider
   registration for `sora-2`
-- `google`: Gemini 3.1 forward-compat fallback, native Gemini replay
-  validation, bootstrap replay sanitation, tagged reasoning-output mode,
-  modern-model matching, bundled image-generation provider registration for
-  Gemini image-preview models, and bundled video-generation provider
-  registration for Veo models
+- `google` and `google-gemini-cli`: Gemini 3.1 forward-compat fallback,
+  native Gemini replay validation, bootstrap replay sanitation, tagged
+  reasoning-output mode, modern-model matching, bundled image-generation
+  provider registration for Gemini image-preview models, and bundled
+  video-generation provider registration for Veo models; Gemini CLI OAuth also
+  owns auth-profile token formatting, usage-token parsing, and quota endpoint
+  fetching for usage surfaces
 - `moonshot`: shared transport, plugin-owned thinking payload normalization
 - `kilocode`: shared transport, plugin-owned request headers, reasoning payload
   normalization, proxy-Gemini thought-signature sanitation, and cache-TTL
@@ -271,8 +273,8 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Example model: `anthropic/claude-opus-4-6`
 - CLI: `openclaw onboard --auth-choice apiKey`
 - Direct public Anthropic requests support the shared `/fast` toggle and `params.fastMode`, including API-key and OAuth-authenticated traffic sent to `api.anthropic.com`; OpenClaw maps that to Anthropic `service_tier` (`auto` vs `standard_only`)
-- Billing note: for Anthropic in OpenClaw, the practical split is **API key** or **Claude subscription with Extra Usage**. Anthropic notified OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription. Our local repros also show the OpenClaw-identifying prompt string does not reproduce on the Anthropic SDK + API-key path.
-- Anthropic setup-token is available again as a legacy/manual OpenClaw path. Use it with the expectation that Anthropic told OpenClaw users this path requires **Extra Usage**.
+- Anthropic note: Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned for this integration unless Anthropic publishes a new policy.
+- Anthropic setup-token remains available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
 
 ```json5
 {
@@ -347,10 +349,21 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
   (or legacy `cached_content`) to forward a provider-native
   `cachedContents/...` handle; Gemini cache hits surface as OpenClaw `cacheRead`
 
-### Google Vertex
+### Google Vertex and Gemini CLI
 
-- Provider: `google-vertex`
-- Auth: gcloud ADC
+- Providers: `google-vertex`, `google-gemini-cli`
+- Auth: Vertex uses gcloud ADC; Gemini CLI uses its OAuth flow
+- Caution: Gemini CLI OAuth in OpenClaw is an unofficial integration. Some users have reported Google account restrictions after using third-party clients. Review Google terms and use a non-critical account if you choose to proceed.
+- Gemini CLI OAuth is shipped as part of the bundled `google` plugin.
+  - Install Gemini CLI first:
+    - `brew install gemini-cli`
+    - or `npm install -g @google/gemini-cli`
+  - Enable: `openclaw plugins enable google`
+  - Login: `openclaw models auth login --provider google-gemini-cli --set-default`
+  - Default model: `google-gemini-cli/gemini-3.1-pro-preview`
+  - Note: you do **not** paste a client id or secret into `openclaw.json`. The CLI login flow stores
+    tokens in auth profiles on the gateway host.
+  - If requests fail after login, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host.
   - Gemini CLI JSON replies are parsed from `response`; usage falls back to
     `stats`, with `stats.cached` normalized into OpenClaw `cacheRead`.
 

docs/concepts/oauth.md

@@ -15,9 +15,8 @@ OpenClaw supports “subscription auth” via OAuth for providers that offer it
 is now:
 
 - **Anthropic API key**: normal Anthropic API billing
-- **Anthropic subscription auth inside OpenClaw**: Anthropic notified OpenClaw
-  users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that this now
-  requires **Extra Usage**
+- **Anthropic Claude CLI / subscription auth inside OpenClaw**: Anthropic staff
+  told us this usage is allowed again
 
 OpenAI Codex OAuth is explicitly supported for use in external tools like
 OpenClaw. This page explains:
@@ -71,12 +70,10 @@ For static secret refs and runtime snapshot activation behavior, see [Secrets Ma
 
 <Warning>
 Anthropic's public Claude Code docs say direct Claude Code use stays within
-Claude subscription limits. Separately, Anthropic told OpenClaw users on
-**April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that **OpenClaw counts as a
-third-party harness**. Existing Anthropic token profiles remain technically
-usable in OpenClaw, but Anthropic says the OpenClaw path now requires **Extra
-Usage** (pay-as-you-go billed separately from the subscription) for that
-traffic.
+Claude subscription limits, and Anthropic staff told us OpenClaw-style Claude
+CLI usage is allowed again. OpenClaw therefore treats Claude CLI reuse and
+`claude -p` usage as sanctioned for this integration unless Anthropic
+publishes a new policy.
 
 For Anthropic's current direct-Claude-Code plan docs, see [Using Claude Code
 with your Pro or Max
@@ -90,17 +87,12 @@ Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax),
 and [Z.AI / GLM Coding Plan](/providers/glm).
 </Warning>
 
-OpenClaw now exposes Anthropic setup-token again as a legacy/manual path.
-Anthropic's OpenClaw-specific billing notice still applies to that path, so
-use it with the expectation that Anthropic requires **Extra Usage** for
-OpenClaw-driven Claude-login traffic.
+OpenClaw also exposes Anthropic setup-token as a supported token-auth path, but it now prefers Claude CLI reuse and `claude -p` when available.
 
 ## Anthropic Claude CLI migration
 
-Anthropic no longer has a supported local Claude CLI migration path in
-OpenClaw. Use Anthropic API keys for Anthropic traffic, or keep legacy
-token-based auth only where it is already configured and with the expectation
-that Anthropic treats that OpenClaw path as **Extra Usage**.
+OpenClaw supports Anthropic Claude CLI reuse again. If you already have a local
+Claude login on the host, onboarding/configure can reuse it directly.
 
 ## OAuth exchange (how login works)
 

docs/concepts/qa-e2e-automation.md

@@ -21,13 +21,21 @@ Current pieces:
 - `qa/`: repo-backed seed assets for the kickoff task and baseline QA
   scenarios.
 
-The long-term goal is a two-pane QA site:
+The current QA operator flow is a two-pane QA site:
 
 - Left: Gateway dashboard (Control UI) with the agent.
 - Right: QA Lab, showing the Slack-ish transcript and scenario plan.
 
-That lets an operator or automation loop give the agent a QA mission, observe
-real channel behavior, and record what worked, failed, or stayed blocked.
+Run it with:
+
+```bash
+pnpm qa:lab:up
+```
+
+That builds the QA site, starts the Docker-backed gateway lane, and exposes the
+QA Lab page where an operator or automation loop can give the agent a QA
+mission, observe real channel behavior, and record what worked, failed, or
+stayed blocked.
 
 ## Repo-backed seeds
 

docs/docs.json

@@ -1108,6 +1108,7 @@
                   "tools/plugin",
                   "plugins/community",
                   "plugins/bundles",
+                  "plugins/webhooks",
                   "plugins/voice-call",
                   {
                     "group": "Building Plugins",
@@ -1157,6 +1158,7 @@
               {
                 "group": "Tools",
                 "pages": [
+                  "tools/media-overview",
                   "tools/apply-patch",
                   {
                     "group": "Web Browser",
@@ -1229,6 +1231,7 @@
                 "pages": [
                   "providers/alibaba",
                   "providers/anthropic",
+                  "providers/arcee",
                   "providers/bedrock",
                   "providers/bedrock-mantle",
                   "providers/chutes",
@@ -1358,6 +1361,7 @@
                       "gateway/openai-http-api",
                       "gateway/openresponses-http-api",
                       "gateway/tools-invoke-http-api",
+                      "gateway/cli-backends",
                       "gateway/local-models"
                     ]
                   },

docs/gateway/authentication.md

@@ -1,5 +1,5 @@
 ---
-summary: "Model authentication: OAuth, API keys, and legacy Anthropic setup-token"
+summary: "Model authentication: OAuth, API keys, Claude CLI reuse, and Anthropic setup-token"
 read_when:
   - Debugging model auth or OAuth expiry
   - Documenting authentication or credential storage
@@ -9,7 +9,7 @@ title: "Authentication"
 # Authentication (Model Providers)
 
 <Note>
-This page covers **model provider** authentication (API keys, OAuth, and legacy Anthropic setup-token). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth).
+This page covers **model provider** authentication (API keys, OAuth, Claude CLI reuse, and Anthropic setup-token). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth).
 </Note>
 
 OpenClaw supports OAuth and API keys for model providers. For always-on gateway
@@ -26,9 +26,8 @@ For credential eligibility/reason-code rules used by `models status --probe`, se
 
 If you’re running a long-lived gateway, start with an API key for your chosen
 provider.
-For Anthropic specifically, API key auth is the safe path. Anthropic
-subscription-style auth inside OpenClaw is the legacy setup-token path and
-should be treated as an **Extra Usage** path, not a plan-limits path.
+For Anthropic specifically, API key auth is still the most predictable server
+setup, but OpenClaw also supports reusing a local Claude CLI login.
 
 1. Create an API key in your provider console.
 2. Put it on the **gateway host** (the machine running `openclaw gateway`).
@@ -60,18 +59,17 @@ API keys for daemon use: `openclaw onboard`.
 See [Help](/help) for details on env inheritance (`env.shellEnv`,
 `~/.openclaw/.env`, systemd/launchd).
 
-## Anthropic: legacy token compatibility
+## Anthropic: Claude CLI and token compatibility
 
-Anthropic setup-token auth is still available in OpenClaw as a
-legacy/manual path. Anthropic's public Claude Code docs still cover direct
-Claude Code terminal use under Claude plans, but Anthropic separately told
-OpenClaw users that the **OpenClaw** Claude-login path counts as third-party
-harness usage and requires **Extra Usage** billed separately from the
-subscription.
+Anthropic setup-token auth is still available in OpenClaw as a supported token
+path. Anthropic staff has since told us that OpenClaw-style Claude CLI usage is
+allowed again, so OpenClaw treats Claude CLI reuse and `claude -p` usage as
+sanctioned for this integration unless Anthropic publishes a new policy. When
+Claude CLI reuse is available on the host, that is now the preferred path.
 
-For the clearest setup path, use an Anthropic API key. If you must keep a
-subscription-style Anthropic path in OpenClaw, use the legacy setup-token path
-with the expectation that Anthropic treats it as **Extra Usage**.
+For long-lived gateway hosts, an Anthropic API key is still the most predictable
+setup. If you want to reuse an existing Claude login on the same host, use the
+Anthropic Claude CLI path in onboarding/configure.
 
 Manual token entry (any provider; writes `auth-profiles.json` + updates config):
 
@@ -112,15 +110,13 @@ Optional ops scripts (systemd/Termux) are documented here:
 
 ## Anthropic note
 
-The Anthropic `claude-cli` backend was removed.
+The Anthropic `claude-cli` backend is supported again.
 
-- Use Anthropic API keys for Anthropic traffic in OpenClaw.
-- Anthropic setup-token remains a legacy/manual path and should be used with
-  the Extra Usage billing expectation Anthropic communicated to OpenClaw users.
-- `openclaw doctor` now detects stale removed Anthropic Claude CLI state. If
-  stored credential bytes still exist, doctor converts them back into
-  Anthropic token/OAuth profiles. If not, doctor removes the stale Claude CLI
-  config and points you to API key or setup-token recovery.
+- Anthropic staff told us this OpenClaw integration path is allowed again.
+- OpenClaw therefore treats Claude CLI reuse and `claude -p` usage as sanctioned
+  for Anthropic-backed runs unless Anthropic publishes a new policy.
+- Anthropic API keys remain the most predictable choice for long-lived gateway
+  hosts and explicit server-side billing control.
 
 ## Checking model auth status
 
@@ -158,7 +154,7 @@ Use `/model` (or `/model list`) for a compact picker; use `/model status` for th
 
 ### Per-agent (CLI override)
 
-Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
+Set an explicit auth profile order override for an agent (stored in that agent’s `auth-state.json`):
 
 ```bash
 openclaw models auth order get --provider anthropic
@@ -177,7 +173,7 @@ to one model id rather than the whole provider profile.
 ### "No credentials found"
 
 If the Anthropic profile is missing, configure an Anthropic API key on the
-**gateway host** or set up the legacy Anthropic setup-token path, then re-check:
+**gateway host** or set up the Anthropic setup-token path, then re-check:
 
 ```bash
 openclaw models status
@@ -185,17 +181,6 @@ openclaw models status
 
 ### Token expiring/expired
 
-Run `openclaw models status` to confirm which profile is expiring. If a legacy
+Run `openclaw models status` to confirm which profile is expiring. If an
 Anthropic token profile is missing or expired, refresh that setup via
 setup-token or migrate to an Anthropic API key.
-
-If the machine still has stale removed Anthropic Claude CLI state from older
-builds, run:
-
-```bash
-openclaw doctor --yes
-```
-
-Doctor converts `anthropic:claude-cli` back to Anthropic token/OAuth when the
-stored credential bytes still exist. Otherwise it removes stale Claude CLI
-profile/config/model refs and leaves the next-step guidance.

docs/gateway/cli-backends.md

@@ -0,0 +1,287 @@
+---
+summary: "CLI backends: local AI CLI fallback with optional MCP tool bridge"
+read_when:
+  - You want a reliable fallback when API providers fail
+  - You are running Codex CLI or other local AI CLIs and want to reuse them
+  - You want to understand the MCP loopback bridge for CLI backend tool access
+title: "CLI Backends"
+---
+
+# CLI backends (fallback runtime)
+
+OpenClaw can run **local AI CLIs** as a **text-only fallback** when API providers are down,
+rate-limited, or temporarily misbehaving. This is intentionally conservative:
+
+- **OpenClaw tools are not injected directly**, but backends with `bundleMcp: true`
+  can receive gateway tools via a loopback MCP bridge.
+- **JSONL streaming** for CLIs that support it.
+- **Sessions are supported** (so follow-up turns stay coherent).
+- **Images can be passed through** if the CLI accepts image paths.
+
+This is designed as a **safety net** rather than a primary path. Use it when you
+want “always works” text responses without relying on external APIs.
+
+If you want a full harness runtime with ACP session controls, background tasks,
+thread/conversation binding, and persistent external coding sessions, use
+[ACP Agents](/tools/acp-agents) instead. CLI backends are not ACP.
+
+## Beginner-friendly quick start
+
+You can use Codex CLI **without any config** (the bundled OpenAI plugin
+registers a default backend):
+
+```bash
+openclaw agent --message "hi" --model codex-cli/gpt-5.4
+```
+
+If your gateway runs under launchd/systemd and PATH is minimal, add just the
+command path:
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "codex-cli": {
+          command: "/opt/homebrew/bin/codex",
+        },
+      },
+    },
+  },
+}
+```
+
+That’s it. No keys, no extra auth config needed beyond the CLI itself.
+
+If you use a bundled CLI backend as the **primary message provider** on a
+gateway host, OpenClaw now auto-loads the owning bundled plugin when your config
+explicitly references that backend in a model ref or under
+`agents.defaults.cliBackends`.
+
+## Using it as a fallback
+
+Add a CLI backend to your fallback list so it only runs when primary models fail:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "anthropic/claude-opus-4-6",
+        fallbacks: ["codex-cli/gpt-5.4"],
+      },
+      models: {
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
+        "codex-cli/gpt-5.4": {},
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- If you use `agents.defaults.models` (allowlist), you must include your CLI backend models there too.
+- If the primary provider fails (auth, rate limits, timeouts), OpenClaw will
+  try the CLI backend next.
+
+## Configuration overview
+
+All CLI backends live under:
+
+```
+agents.defaults.cliBackends
+```
+
+Each entry is keyed by a **provider id** (e.g. `codex-cli`, `my-cli`).
+The provider id becomes the left side of your model ref:
+
+```
+<provider>/<model>
+```
+
+### Example configuration
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "codex-cli": {
+          command: "/opt/homebrew/bin/codex",
+        },
+        "my-cli": {
+          command: "my-cli",
+          args: ["--json"],
+          output: "json",
+          input: "arg",
+          modelArg: "--model",
+          modelAliases: {
+            "claude-opus-4-6": "opus",
+            "claude-sonnet-4-6": "sonnet",
+          },
+          sessionArg: "--session",
+          sessionMode: "existing",
+          sessionIdFields: ["session_id", "conversation_id"],
+          systemPromptArg: "--system",
+          systemPromptWhen: "first",
+          imageArg: "--image",
+          imageMode: "repeat",
+          serialize: true,
+        },
+      },
+    },
+  },
+}
+```
+
+## How it works
+
+1. **Selects a backend** based on the provider prefix (`codex-cli/...`).
+2. **Builds a system prompt** using the same OpenClaw prompt + workspace context.
+3. **Executes the CLI** with a session id (if supported) so history stays consistent.
+4. **Parses output** (JSON or plain text) and returns the final text.
+5. **Persists session ids** per backend, so follow-ups reuse the same CLI session.
+
+<Note>
+The bundled Anthropic `claude-cli` backend is supported again. Anthropic staff
+told us OpenClaw-style Claude CLI usage is allowed again, so OpenClaw treats
+`claude -p` usage as sanctioned for this integration unless Anthropic publishes
+a new policy.
+</Note>
+
+## Sessions
+
+- If the CLI supports sessions, set `sessionArg` (e.g. `--session-id`) or
+  `sessionArgs` (placeholder `{sessionId}`) when the ID needs to be inserted
+  into multiple flags.
+- If the CLI uses a **resume subcommand** with different flags, set
+  `resumeArgs` (replaces `args` when resuming) and optionally `resumeOutput`
+  (for non-JSON resumes).
+- `sessionMode`:
+  - `always`: always send a session id (new UUID if none stored).
+  - `existing`: only send a session id if one was stored before.
+  - `none`: never send a session id.
+
+Serialization notes:
+
+- `serialize: true` keeps same-lane runs ordered.
+- Most CLIs serialize on one provider lane.
+- OpenClaw drops stored CLI session reuse when the backend auth state changes, including relogin, token rotation, or a changed auth profile credential.
+
+## Images (pass-through)
+
+If your CLI accepts image paths, set `imageArg`:
+
+```json5
+imageArg: "--image",
+imageMode: "repeat"
+```
+
+OpenClaw will write base64 images to temp files. If `imageArg` is set, those
+paths are passed as CLI args. If `imageArg` is missing, OpenClaw appends the
+file paths to the prompt (path injection), which is enough for CLIs that auto-
+load local files from plain paths.
+
+## Inputs / outputs
+
+- `output: "json"` (default) tries to parse JSON and extract text + session id.
+- For Gemini CLI JSON output, OpenClaw reads reply text from `response` and
+  usage from `stats` when `usage` is missing or empty.
+- `output: "jsonl"` parses JSONL streams (for example Codex CLI `--json`) and extracts the final agent message plus session
+  identifiers when present.
+- `output: "text"` treats stdout as the final response.
+
+Input modes:
+
+- `input: "arg"` (default) passes the prompt as the last CLI arg.
+- `input: "stdin"` sends the prompt via stdin.
+- If the prompt is very long and `maxPromptArgChars` is set, stdin is used.
+
+## Defaults (plugin-owned)
+
+The bundled OpenAI plugin also registers a default for `codex-cli`:
+
+- `command: "codex"`
+- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
+- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
+- `output: "jsonl"`
+- `resumeOutput: "text"`
+- `modelArg: "--model"`
+- `imageArg: "--image"`
+- `sessionMode: "existing"`
+
+The bundled Google plugin also registers a default for `google-gemini-cli`:
+
+- `command: "gemini"`
+- `args: ["--prompt", "--output-format", "json"]`
+- `resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]`
+- `modelArg: "--model"`
+- `sessionMode: "existing"`
+- `sessionIdFields: ["session_id", "sessionId"]`
+
+Prerequisite: the local Gemini CLI must be installed and available as
+`gemini` on `PATH` (`brew install gemini-cli` or
+`npm install -g @google/gemini-cli`).
+
+Gemini CLI JSON notes:
+
+- Reply text is read from the JSON `response` field.
+- Usage falls back to `stats` when `usage` is absent or empty.
+- `stats.cached` is normalized into OpenClaw `cacheRead`.
+- If `stats.input` is missing, OpenClaw derives input tokens from
+  `stats.input_tokens - stats.cached`.
+
+Override only if needed (common: absolute `command` path).
+
+## Plugin-owned defaults
+
+CLI backend defaults are now part of the plugin surface:
+
+- Plugins register them with `api.registerCliBackend(...)`.
+- The backend `id` becomes the provider prefix in model refs.
+- User config in `agents.defaults.cliBackends.<id>` still overrides the plugin default.
+- Backend-specific config cleanup stays plugin-owned through the optional
+  `normalizeConfig` hook.
+
+## Bundle MCP overlays
+
+CLI backends do **not** receive OpenClaw tool calls directly, but a backend can
+opt into a generated MCP config overlay with `bundleMcp: true`.
+
+Current bundled behavior:
+
+- `codex-cli`: no bundle MCP overlay
+- `google-gemini-cli`: no bundle MCP overlay
+
+When bundle MCP is enabled, OpenClaw:
+
+- spawns a loopback HTTP MCP server that exposes gateway tools to the CLI process
+- authenticates the bridge with a per-session token (`OPENCLAW_MCP_TOKEN`)
+- scopes tool access to the current session, account, and channel context
+- loads enabled bundle-MCP servers for the current workspace
+- merges them with any existing backend `--mcp-config`
+- rewrites the CLI args to pass `--strict-mcp-config --mcp-config <generated-file>`
+
+If no MCP servers are enabled, OpenClaw still injects a strict config when a
+backend opts into bundle MCP so background runs stay isolated.
+
+## Limitations
+
+- **No direct OpenClaw tool calls.** OpenClaw does not inject tool calls into
+  the CLI backend protocol. Backends only see gateway tools when they opt into
+  `bundleMcp: true`.
+- **Streaming is backend-specific.** Some backends stream JSONL; others buffer
+  until exit.
+- **Structured outputs** depend on the CLI’s JSON format.
+- **Codex CLI sessions** resume via text output (no JSONL), which is less
+  structured than the initial `--json` run. OpenClaw sessions still work
+  normally.
+
+## Troubleshooting
+
+- **CLI not found**: set `command` to a full path.
+- **Wrong model name**: use `modelAliases` to map `provider/model` → CLI model.
+- **No session continuity**: ensure `sessionArg` is set and `sessionMode` is not
+  `none` (Codex CLI currently cannot resume with JSON output).
+- **Images ignored**: set `imageArg` (and verify CLI supports file paths).

docs/gateway/configuration-reference.md

@@ -646,8 +646,9 @@ Matrix is extension-backed and configured under `channels.matrix`.
 
 - Token auth uses `accessToken`; password auth uses `userId` + `password`.
 - `channels.matrix.proxy` routes Matrix HTTP traffic through an explicit HTTP(S) proxy. Named accounts can override it with `channels.matrix.accounts.<id>.proxy`.
-- `channels.matrix.allowPrivateNetwork` allows private/internal homeservers. `proxy` and `allowPrivateNetwork` are independent controls.
+- `channels.matrix.network.dangerouslyAllowPrivateNetwork` allows private/internal homeservers. `proxy` and this network opt-in are independent controls.
 - `channels.matrix.defaultAccount` selects the preferred account in multi-account setups.
+- `channels.matrix.autoJoin` defaults to `off`, so invited rooms and fresh DM-style invites are ignored until you set `autoJoin: "allowlist"` with `autoJoinAllowlist` or `autoJoin: "always"`.
 - `channels.matrix.execApprovals`: Matrix-native exec approval delivery and approver authorization.
   - `enabled`: `true`, `false`, or `"auto"` (default). In auto mode, exec approvals activate when approvers can be resolved from `approvers` or `commands.ownerAllowFrom`.
   - `approvers`: Matrix user IDs (e.g. `@owner:example.org`) allowed to approve exec requests.
@@ -1082,6 +1083,37 @@ Z.AI GLM-4.x models automatically enable thinking mode unless you set `--thinkin
 Z.AI models enable `tool_stream` by default for tool call streaming. Set `agents.defaults.models["zai/<model>"].params.tool_stream` to `false` to disable it.
 Anthropic Claude 4.6 models default to `adaptive` thinking when no explicit thinking level is set.
 
+### `agents.defaults.cliBackends`
+
+Optional CLI backends for text-only fallback runs (no tool calls). Useful as a backup when API providers fail.
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "codex-cli": {
+          command: "/opt/homebrew/bin/codex",
+        },
+        "my-cli": {
+          command: "my-cli",
+          args: ["--json"],
+          output: "json",
+          modelArg: "--model",
+          sessionArg: "--session",
+          sessionMode: "existing",
+          systemPromptArg: "--system",
+          systemPromptWhen: "first",
+          imageArg: "--image",
+          imageMode: "repeat",
+        },
+      },
+    },
+  },
+}
+```
+
+- CLI backends are text-first; tools are always disabled.
 - Sessions supported when `sessionArg` is set.
 - Image pass-through supported when `imageArg` accepts file paths.
 

docs/gateway/doctor.md

@@ -307,18 +307,11 @@ Doctor checks:
 
 Doctor inspects OAuth profiles in the auth store, warns when tokens are
 expiring/expired, and can refresh them when safe. If the Anthropic
-OAuth/token profile is stale, it suggests an Anthropic API key or the legacy
+OAuth/token profile is stale, it suggests an Anthropic API key or the
 Anthropic setup-token path.
 Refresh prompts only appear when running interactively (TTY); `--non-interactive`
 skips refresh attempts.
 
-Doctor also detects stale removed Anthropic Claude CLI state. If old
-`anthropic:claude-cli` credential bytes still exist in `auth-profiles.json`,
-doctor converts them back into Anthropic token/OAuth profiles and rewrites
-stale `claude-cli/...` model refs.
-If the bytes are gone, doctor removes the stale config and prints recovery
-commands instead.
-
 Doctor also reports auth profiles that are temporarily unusable due to:
 
 - short cooldowns (rate limits/timeouts/auth failures)

docs/gateway/index.md

@@ -173,7 +173,7 @@ Fallback: SSH tunnel.
 ssh -N -L 18789:127.0.0.1:18789 user@host
 ```
 
-Then connect clients to `ws://127.0.0.1:18789` locally.
+Then connect clients locally to `ws://127.0.0.1:18789`.
 
 <Warning>
 SSH tunnels do not bypass gateway auth. For shared-secret auth, clients still

docs/gateway/troubleshooting.md

@@ -50,7 +50,7 @@ Look for:
 Fix options:
 
 1. Disable `context1m` for that model to fall back to the normal context window.
-2. Use an Anthropic API key with billing, or enable Anthropic Extra Usage on the Anthropic OAuth/subscription account.
+2. Use an Anthropic credential that is eligible for long-context requests, or switch to an Anthropic API key.
 3. Configure fallback models so runs continue when Anthropic long-context requests are rejected.
 
 Related:

docs/help/faq.md

@@ -565,7 +565,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   <Accordion title="What does onboarding actually do?">
     `openclaw onboard` is the recommended setup path. In **local mode** it walks you through:
 
-    - **Model/auth setup** (provider OAuth, API keys, Anthropic legacy setup-token, plus local model options such as LM Studio)
+    - **Model/auth setup** (provider OAuth, API keys, Anthropic setup-token, plus local model options such as LM Studio)
     - **Workspace** location + bootstrap files
     - **Gateway settings** (bind/port/auth/tailscale)
     - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, plus bundled channel plugins like QQ Bot)
@@ -584,15 +584,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
     For Anthropic in OpenClaw, the practical split is:
 
     - **Anthropic API key**: normal Anthropic API billing
-    - **Claude subscription auth in OpenClaw**: Anthropic told OpenClaw users on
-      **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that this requires
-      **Extra Usage** billed separately from the subscription
+    - **Claude CLI / Claude subscription auth in OpenClaw**: Anthropic staff
+      told us this usage is allowed again, and OpenClaw is treating `claude -p`
+      usage as sanctioned for this integration unless Anthropic publishes a new
+      policy
 
-    Our local repros also show that `claude -p --append-system-prompt ...` can
-    hit the same Extra Usage guard when the appended prompt identifies
-    OpenClaw, while the same prompt string does **not** reproduce that block on
-    the Anthropic SDK + API-key path. OpenAI Codex OAuth is explicitly
-    supported for external tools like OpenClaw.
+    For long-lived gateway hosts, Anthropic API keys are still the more
+    predictable setup. OpenAI Codex OAuth is explicitly supported for external
+    tools like OpenClaw.
 
     OpenClaw also supports other hosted subscription-style options including
     **Qwen Cloud Coding Plan**, **MiniMax Coding Plan**, and
@@ -606,33 +605,28 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   </Accordion>
 
   <Accordion title="Can I use Claude Max subscription without an API key?">
-    Yes, but treat it as **Claude subscription auth with Extra Usage**.
+    Yes.
 
-    Claude Pro/Max subscriptions do not include an API key. In OpenClaw, that
-    means Anthropic's OpenClaw-specific billing notice applies: subscription
-    traffic requires **Extra Usage**. If you want Anthropic traffic without
-    that Extra Usage path, use an Anthropic API key instead.
+    Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so
+    OpenClaw treats Claude subscription auth and `claude -p` usage as sanctioned
+    for this integration unless Anthropic publishes a new policy. If you want
+    the most predictable server-side setup, use an Anthropic API key instead.
 
   </Accordion>
 
   <Accordion title="Do you support Claude subscription auth (Claude Pro or Max)?">
-    Yes, but the supported interpretation is now:
+    Yes.
 
-    - Anthropic in OpenClaw with a subscription means **Extra Usage**
-    - Anthropic in OpenClaw without that path means **API key**
+    Anthropic staff told us this usage is allowed again, so OpenClaw treats
+    Claude CLI reuse and `claude -p` usage as sanctioned for this integration
+    unless Anthropic publishes a new policy.
 
-    Anthropic setup-token is still available as a legacy/manual OpenClaw path,
-    and Anthropic's OpenClaw-specific billing notice still applies there. We
-    also reproduced the same billing guard locally with direct
-    `claude -p --append-system-prompt ...` usage when the appended prompt
-    identifies OpenClaw, while the same prompt string did **not** reproduce on
-    the Anthropic SDK + API-key path.
-
-    For production or multi-user workloads, Anthropic API key auth is the
-    safer, recommended choice. If you want other subscription-style hosted
+    Anthropic setup-token is still available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
+    For production or multi-user workloads, Anthropic API key auth is still the
+    safer, more predictable choice. If you want other subscription-style hosted
     options in OpenClaw, see [OpenAI](/providers/openai), [Qwen / Model
-    Cloud](/providers/qwen), [MiniMax](/providers/minimax), and
-    [GLM Models](/providers/glm).
+    Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [GLM
+    Models](/providers/glm).
 
   </Accordion>
 
@@ -663,6 +657,31 @@ for usage/billing and raise limits as needed.
     OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Onboarding can run the OAuth flow and will set the default model to `openai-codex/gpt-5.4` when appropriate. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard).
   </Accordion>
 
+  <Accordion title="Why does ChatGPT GPT-5.4 not unlock openai/gpt-5.4 in OpenClaw?">
+    OpenClaw treats the two routes separately:
+
+    - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth
+    - `openai/gpt-5.4` = direct OpenAI Platform API
+
+    In OpenClaw, ChatGPT/Codex sign-in is wired to the `openai-codex/*` route,
+    not the direct `openai/*` route. If you want the direct API path in
+    OpenClaw, set `OPENAI_API_KEY` (or the equivalent OpenAI provider config).
+    If you want ChatGPT/Codex sign-in in OpenClaw, use `openai-codex/*`.
+
+  </Accordion>
+
+  <Accordion title="Why can Codex OAuth limits differ from ChatGPT web?">
+    `openai-codex/*` uses the Codex OAuth route, and its usable quota windows are
+    OpenAI-managed and plan-dependent. In practice, those limits can differ from
+    the ChatGPT website/app experience, even when both are tied to the same account.
+
+    OpenClaw can show the currently visible provider usage/quota windows in
+    `openclaw models status`, but it does not invent or normalize ChatGPT-web
+    entitlements into direct API access. If you want the direct OpenAI Platform
+    billing/limit path, use `openai/*` with an API key.
+
+  </Accordion>
+
   <Accordion title="Do you support OpenAI subscription auth (Codex OAuth)?">
     Yes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**.
     OpenAI explicitly allows subscription OAuth usage in external tools/workflows
@@ -675,11 +694,17 @@ for usage/billing and raise limits as needed.
   <Accordion title="How do I set up Gemini CLI OAuth?">
     Gemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`.
 
-    Use the Gemini API provider instead:
+    Steps:
 
-    1. Enable the plugin: `openclaw plugins enable google`
-    2. Run `openclaw onboard --auth-choice gemini-api-key`
-    3. Set a Google model such as `google/gemini-3.1-pro-preview`
+    1. Install Gemini CLI locally so `gemini` is on `PATH`
+       - Homebrew: `brew install gemini-cli`
+       - npm: `npm install -g @google/gemini-cli`
+    2. Enable the plugin: `openclaw plugins enable google`
+    3. Login: `openclaw models auth login --provider google-gemini-cli --set-default`
+    4. Default model after login: `google-gemini-cli/gemini-3.1-pro-preview`
+    5. If requests fail, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host
+
+    This stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers).
 
   </Accordion>
 
@@ -2645,7 +2670,7 @@ Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-a
     for one model can still be usable for a sibling model on the same provider,
     while billing/disabled windows still block the whole profile.
 
-    You can also set a **per-agent** order override (stored in that agent's `auth-profiles.json`) via the CLI:
+    You can also set a **per-agent** order override (stored in that agent's `auth-state.json`) via the CLI:
 
     ```bash
     # Defaults to the configured default agent (omit --agent)

docs/help/testing.md

@@ -24,8 +24,9 @@ Most days:
 
 - Full gate (expected before push): `pnpm build && pnpm check && pnpm test`
 - Faster local full-suite run on a roomy machine: `pnpm test:max`
-- Direct Vitest watch loop (modern projects config): `pnpm test:watch`
+- Direct Vitest watch loop: `pnpm test:watch`
 - Direct file targeting now routes extension/channel paths too: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
+- Docker-backed QA site: `pnpm qa:lab:up`
 
 When you touch tests or want extra confidence:
 
@@ -46,7 +47,7 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
 ### Unit / integration (default)
 
 - Command: `pnpm test`
-- Config: native Vitest `projects` via `vitest.config.ts`
+- Config: five sequential shard runs (`vitest.full-*.config.ts`) over the existing scoped Vitest projects
 - Files: core/unit inventories under `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts`, and the whitelisted `ui` node tests covered by `vitest.unit.config.ts`
 - Scope:
   - Pure unit tests
@@ -57,8 +58,13 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
   - No real keys required
   - Should be fast and stable
 - Projects note:
-  - `pnpm test`, `pnpm test:watch`, and `pnpm test:changed` all use the same native Vitest root `projects` config now.
-  - Direct file filters route natively through the root project graph, so `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` works without a custom wrapper.
+  - Untargeted `pnpm test` now runs eight smaller shard configs (`core-unit-src`, `core-unit-security`, `core-unit-support`, `core-contracts`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) instead of one giant native root-project process. This cuts peak RSS on loaded machines and avoids auto-reply/extension work starving unrelated suites.
+  - `pnpm test --watch` still uses the native root `vitest.config.ts` project graph, because a multi-shard watch loop is not practical.
+  - `pnpm test`, `pnpm test:watch`, and `pnpm test:perf:imports` route explicit file/directory targets through scoped lanes first, so `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` avoids paying the full root project startup tax.
+  - `pnpm test:changed` expands changed git paths into the same scoped lanes when the diff only touches routable source/test files; config/setup edits still fall back to the broad root-project rerun.
+  - Selected `plugin-sdk` and `commands` tests also route through dedicated light lanes that skip `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy files stay on the existing lanes.
+  - Selected `plugin-sdk` and `commands` helper source files also map changed-mode runs to explicit sibling tests in those light lanes, so helper edits avoid rerunning the full heavy suite for that directory.
+  - `auto-reply` now has three dedicated buckets: top-level core helpers, top-level `reply.*` integration tests, and the `src/auto-reply/reply/**` subtree. This keeps the heaviest reply harness work off the cheap status/chunk/token tests.
 - Embedded runner note:
   - When you change message-tool discovery inputs or compaction runtime context,
     keep both levels of coverage.
@@ -74,17 +80,19 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
   - Base Vitest config now defaults to `threads`.
   - The shared Vitest config also fixes `isolate: false` and uses the non-isolated runner across the root projects, e2e, and live configs.
   - The root UI lane keeps its `jsdom` setup and optimizer, but now runs on the shared non-isolated runner too.
-  - `pnpm test` inherits the same `threads` + `isolate: false` defaults from the root `vitest.config.ts` projects config.
+  - Each `pnpm test` shard inherits the same `threads` + `isolate: false` defaults from the shared Vitest config.
   - The shared `scripts/run-vitest.mjs` launcher now also adds `--no-maglev` for Vitest child Node processes by default to reduce V8 compile churn during big local runs. Set `OPENCLAW_VITEST_ENABLE_MAGLEV=1` if you need to compare against stock V8 behavior.
 - Fast-local iteration note:
-  - `pnpm test:changed` runs the native projects config with `--changed origin/main`.
-  - `pnpm test:max` and `pnpm test:changed:max` keep the same native projects config, just with a higher worker cap.
+  - `pnpm test:changed` routes through scoped lanes when the changed paths map cleanly to a smaller suite.
+  - `pnpm test:max` and `pnpm test:changed:max` keep the same routing behavior, just with a higher worker cap.
   - Local worker auto-scaling is intentionally conservative now and also backs off when the host load average is already high, so multiple concurrent Vitest runs do less damage by default.
   - The base Vitest config marks the projects/config files as `forceRerunTriggers` so changed-mode reruns stay correct when test wiring changes.
   - The config keeps `OPENCLAW_VITEST_FS_MODULE_CACHE` enabled on supported hosts; set `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` if you want one explicit cache location for direct profiling.
 - Perf-debug note:
   - `pnpm test:perf:imports` enables Vitest import-duration reporting plus import-breakdown output.
   - `pnpm test:perf:imports:changed` scopes the same profiling view to files changed since `origin/main`.
+- `pnpm test:perf:changed:bench -- --ref <git-ref>` compares routed `test:changed` against the native root-project path for that committed diff and prints wall time plus macOS max RSS.
+- `pnpm test:perf:changed:bench -- --worktree` benchmarks the current dirty tree by routing the changed file list through `scripts/test-projects.mjs` and the root Vitest config.
   - `pnpm test:perf:profile:main` writes a main-thread CPU profile for Vitest/Vite startup and transform overhead.
   - `pnpm test:perf:profile:runner` writes runner CPU+heap profiles for the unit suite with file parallelism disabled.
 
@@ -196,7 +204,7 @@ Live tests are split into two layers so we can isolate failures:
   - `OPENCLAW_LIVE_MODELS=all` is an alias for the modern allowlist
   - or `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (comma allowlist)
 - How to select providers:
-  - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity"` (comma allowlist)
+  - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (comma allowlist)
 - Where keys come from:
   - By default: profile store and env fallbacks
   - Set `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` to enforce **profile store** only
@@ -227,7 +235,7 @@ Live tests are split into two layers so we can isolate failures:
   - `OPENCLAW_LIVE_GATEWAY_MODELS=all` is an alias for the modern allowlist
   - Or set `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (or comma list) to narrow
 - How to select providers (avoid “OpenRouter everything”):
-  - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,openai,anthropic,zai,minimax"` (comma allowlist)
+  - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (comma allowlist)
 - Tool + image probes are always on in this live test:
   - `read` probe + `exec+read` probe (tool stress)
   - image probe runs when the model advertises image input support
@@ -245,6 +253,46 @@ openclaw models list
 openclaw models list --json
 ```
 
+## Live: CLI backend smoke (Codex CLI or other local CLIs)
+
+- Test: `src/gateway/gateway-cli-backend.live.test.ts`
+- Goal: validate the Gateway + agent pipeline using a local CLI backend, without touching your default config.
+- Enable:
+  - `pnpm test:live` (or `OPENCLAW_LIVE_TEST=1` if invoking Vitest directly)
+  - `OPENCLAW_LIVE_CLI_BACKEND=1`
+- Defaults:
+  - Model: `codex-cli/gpt-5.4`
+  - Command: `codex`
+  - Args: `["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
+- Overrides (optional):
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` to send a real image attachment (paths are injected into the prompt).
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` to pass image file paths as CLI args instead of prompt injection.
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (or `"list"`) to control how image args are passed when `IMAGE_ARG` is set.
+  - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` to send a second turn and validate resume flow.
+
+Example:
+
+```bash
+OPENCLAW_LIVE_CLI_BACKEND=1 \
+  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
+  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
+```
+
+Docker recipe:
+
+```bash
+pnpm test:docker:live-cli-backend
+```
+
+Notes:
+
+- The Docker runner lives at `scripts/test-live-cli-backend-docker.sh`.
+- It runs the live CLI-backend smoke inside the repo Docker image as the non-root `node` user.
+- For `codex-cli`, it installs the Linux `@openai/codex` package into a cached writable prefix at `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`).
+
 ## Live: ACP bind smoke (`/acp spawn ... --bind here`)
 
 - Test: `src/gateway/gateway-acp-bind.live.test.ts`
@@ -309,6 +357,10 @@ Notes:
 
 - `google/...` uses the Gemini API (API key).
 - `google-antigravity/...` uses the Antigravity OAuth bridge (Cloud Code Assist-style agent endpoint).
+- `google-gemini-cli/...` uses the local Gemini CLI on your machine (separate auth + tooling quirks).
+- Gemini API vs Gemini CLI:
+  - API: OpenClaw calls Google’s hosted Gemini API over HTTP (API key / profile auth); this is what most users mean by “Gemini”.
+  - CLI: OpenClaw shells out to a local `gemini` binary; it has its own auth and can behave differently (streaming/tool support/version skew).
 
 ## Live: model matrix (what we cover)
 
@@ -359,7 +411,7 @@ If you have keys enabled, we also support testing via:
 
 More providers you can include in the live matrix (if you have creds/config):
 
-- Built-in: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
+- Built-in: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
 - Via `models.providers` (custom endpoints): `minimax` (cloud/API), plus any OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM, etc.)
 
 Tip: don’t try to hardcode “all models” in docs. The authoritative list is whatever `discoverModels(...)` returns on your machine + whatever keys are available.
@@ -402,6 +454,7 @@ If you want to rely on env keys (e.g. exported in your `~/.profile`), run local
 
 - Test: `src/image-generation/runtime.live.test.ts`
 - Command: `pnpm test:live src/image-generation/runtime.live.test.ts`
+- Harness: `pnpm test:live:media image`
 - Scope:
   - Enumerates every registered image-generation provider plugin
   - Loads missing provider env vars from your login shell (`~/.profile`) before probing
@@ -426,14 +479,70 @@ If you want to rely on env keys (e.g. exported in your `~/.profile`), run local
 
 - Test: `extensions/music-generation-providers.live.test.ts`
 - Enable: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
+- Harness: `pnpm test:live:media music`
 - Scope:
   - Exercises the shared bundled music-generation provider path
   - Currently covers Google and MiniMax
   - Loads provider env vars from your login shell (`~/.profile`) before probing
+  - Uses live/env API keys ahead of stored auth profiles by default, so stale test keys in `auth-profiles.json` do not mask real shell credentials
   - Skips providers with no usable auth/profile/model
+  - Runs both declared runtime modes when available:
+    - `generate` with prompt-only input
+    - `edit` when the provider declares `capabilities.edit.enabled`
+  - Current shared-lane coverage:
+    - `google`: `generate`, `edit`
+    - `minimax`: `generate`
+    - `comfy`: separate Comfy live file, not this shared sweep
 - Optional narrowing:
   - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
   - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"`
+- Optional auth behavior:
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` to force profile-store auth and ignore env-only overrides
+
+## Video generation live
+
+- Test: `extensions/video-generation-providers.live.test.ts`
+- Enable: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
+- Harness: `pnpm test:live:media video`
+- Scope:
+  - Exercises the shared bundled video-generation provider path
+  - Loads provider env vars from your login shell (`~/.profile`) before probing
+  - Uses live/env API keys ahead of stored auth profiles by default, so stale test keys in `auth-profiles.json` do not mask real shell credentials
+  - Skips providers with no usable auth/profile/model
+  - Runs both declared runtime modes when available:
+    - `generate` with prompt-only input
+    - `imageToVideo` when the provider declares `capabilities.imageToVideo.enabled` and the selected provider/model accepts buffer-backed local image input in the shared sweep
+    - `videoToVideo` when the provider declares `capabilities.videoToVideo.enabled` and the selected provider/model accepts buffer-backed local video input in the shared sweep
+  - Current declared-but-skipped `imageToVideo` providers in the shared sweep:
+    - `vydra` because bundled `veo3` is text-only and bundled `kling` requires a remote image URL
+  - Provider-specific Vydra coverage:
+    - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
+    - that file runs `veo3` text-to-video plus a `kling` lane that uses a remote image URL fixture by default
+  - Current `videoToVideo` live coverage:
+    - `runway` only when the selected model is `runway/gen4_aleph`
+  - Current declared-but-skipped `videoToVideo` providers in the shared sweep:
+    - `alibaba`, `qwen`, `xai` because those paths currently require remote `http(s)` / MP4 reference URLs
+    - `google` because the current shared Gemini/Veo lane uses local buffer-backed input and that path is not accepted in the shared sweep
+    - `openai` because the current shared lane lacks org-specific video inpaint/remix access guarantees
+- Optional narrowing:
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"`
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
+- Optional auth behavior:
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` to force profile-store auth and ignore env-only overrides
+
+## Media live harness
+
+- Command: `pnpm test:live:media`
+- Purpose:
+  - Runs the shared image, music, and video live suites through one repo-native entrypoint
+  - Auto-loads missing provider env vars from `~/.profile`
+  - Auto-narrows each suite to providers that currently have usable auth by default
+  - Reuses `scripts/test-live.mjs`, so heartbeat and quiet-mode behavior stay consistent
+- Examples:
+  - `pnpm test:live:media`
+  - `pnpm test:live:media image video --providers openai,google,minimax`
+  - `pnpm test:live:media video --video-providers openai,runway --all-providers`
+  - `pnpm test:live:media music --quiet`
 
 ## Docker runners (optional "works in Linux" checks)
 
@@ -454,6 +563,7 @@ The live-model Docker runners also bind-mount only the needed CLI auth homes (or
 
 - Direct models: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`)
 - ACP bind smoke: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`)
+- CLI backend smoke: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`)
 - Gateway + dev agent: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`)
 - Open WebUI live smoke: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`)
 - Onboarding wizard (TTY, full scaffolding): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`)

docs/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md

@@ -0,0 +1,580 @@
+---
+title: "refactor: Make plugin-sdk a real workspace package incrementally"
+type: refactor
+status: active
+date: 2026-04-05
+---
+
+# refactor: Make plugin-sdk a real workspace package incrementally
+
+## Overview
+
+This plan introduces a real workspace package for the plugin SDK at
+`packages/plugin-sdk` and uses it to opt in a small first wave of extensions to
+compiler-enforced package boundaries. The goal is to make illegal relative
+imports fail under normal `tsc` for a selected set of bundled provider
+extensions, without forcing a repo-wide migration or a giant merge-conflict
+surface.
+
+The key incremental move is to run two modes in parallel for a while:
+
+| Mode        | Import shape             | Who uses it                          | Enforcement                                  |
+| ----------- | ------------------------ | ------------------------------------ | -------------------------------------------- |
+| Legacy mode | `openclaw/plugin-sdk/*`  | all existing non-opted-in extensions | current permissive behavior remains          |
+| Opt-in mode | `@openclaw/plugin-sdk/*` | first-wave extensions only           | package-local `rootDir` + project references |
+
+## Problem Frame
+
+The current repo exports a large public plugin SDK surface, but it is not a real
+workspace package. Instead:
+
+- root `tsconfig.json` maps `openclaw/plugin-sdk/*` directly to
+  `src/plugin-sdk/*.ts`
+- extensions that were not opted into the previous experiment still share that
+  global source-alias behavior
+- adding `rootDir` only works when allowed SDK imports stop resolving into raw
+  repo source
+
+That means the repo can describe the desired boundary policy, but TypeScript
+does not enforce it cleanly for most extensions.
+
+You want an incremental path that:
+
+- makes `plugin-sdk` real
+- moves the SDK toward a workspace package named `@openclaw/plugin-sdk`
+- changes only about 10 extensions in the first PR
+- leaves the rest of the extension tree on the old scheme until later cleanup
+- avoids the `tsconfig.plugin-sdk.dts.json` + postinstall-generated declaration
+  workflow as the primary mechanism for the first-wave rollout
+
+## Requirements Trace
+
+- R1. Create a real workspace package for the plugin SDK under `packages/`.
+- R2. Name the new package `@openclaw/plugin-sdk`.
+- R3. Give the new SDK package its own `package.json` and `tsconfig.json`.
+- R4. Keep legacy `openclaw/plugin-sdk/*` imports working for non-opted-in
+  extensions during the migration window.
+- R5. Opt in only a small first wave of extensions in the first PR.
+- R6. The first-wave extensions must fail closed for relative imports that leave
+  their package root.
+- R7. The first-wave extensions must consume the SDK through a package
+  dependency and a TS project reference, not through root `paths` aliases.
+- R8. The plan must avoid a repo-wide mandatory postinstall generation step for
+  editor correctness.
+- R9. The first-wave rollout must be reviewable and mergeable as a moderate PR,
+  not a repo-wide 300+ file refactor.
+
+## Scope Boundaries
+
+- No full migration of all bundled extensions in the first PR.
+- No requirement to delete `src/plugin-sdk` in the first PR.
+- No requirement to rewire every root build or test path to use the new package
+  immediately.
+- No attempt to force VS Code squiggles for every non-opted-in extension.
+- No broad lint cleanup for the rest of the extension tree.
+- No large runtime behavior changes beyond import resolution, package ownership,
+  and boundary enforcement for the opted-in extensions.
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `pnpm-workspace.yaml` already includes `packages/*` and `extensions/*`, so a
+  new workspace package under `packages/plugin-sdk` fits the existing repo
+  layout.
+- Existing workspace packages such as `packages/memory-host-sdk/package.json`
+  and `packages/plugin-package-contract/package.json` already use package-local
+  `exports` maps rooted in `src/*.ts`.
+- Root `package.json` currently publishes the SDK surface through `./plugin-sdk`
+  and `./plugin-sdk/*` exports backed by `dist/plugin-sdk/*.js` and
+  `dist/plugin-sdk/*.d.ts`.
+- `src/plugin-sdk/entrypoints.ts` and `scripts/lib/plugin-sdk-entrypoints.json`
+  already act as the canonical entrypoint inventory for the SDK surface.
+- Root `tsconfig.json` currently maps:
+  - `openclaw/plugin-sdk` -> `src/plugin-sdk/index.ts`
+  - `openclaw/plugin-sdk/*` -> `src/plugin-sdk/*.ts`
+- The previous boundary experiment showed that package-local `rootDir` works for
+  illegal relative imports only after allowed SDK imports stop resolving to raw
+  source outside the extension package.
+
+### First-Wave Extension Set
+
+This plan assumes the first wave is the provider-heavy set that is least likely
+to drag in complex channel-runtime edge cases:
+
+- `extensions/anthropic`
+- `extensions/exa`
+- `extensions/firecrawl`
+- `extensions/groq`
+- `extensions/mistral`
+- `extensions/openai`
+- `extensions/perplexity`
+- `extensions/tavily`
+- `extensions/together`
+- `extensions/xai`
+
+### First-Wave SDK Surface Inventory
+
+The first-wave extensions currently import a manageable subset of SDK subpaths.
+The initial `@openclaw/plugin-sdk` package only needs to cover these:
+
+- `agent-runtime`
+- `cli-runtime`
+- `config-runtime`
+- `core`
+- `image-generation`
+- `media-runtime`
+- `media-understanding`
+- `plugin-entry`
+- `plugin-runtime`
+- `provider-auth`
+- `provider-auth-api-key`
+- `provider-auth-login`
+- `provider-auth-runtime`
+- `provider-catalog-shared`
+- `provider-entry`
+- `provider-http`
+- `provider-model-shared`
+- `provider-onboard`
+- `provider-stream-family`
+- `provider-stream-shared`
+- `provider-tools`
+- `provider-usage`
+- `provider-web-fetch`
+- `provider-web-search`
+- `realtime-transcription`
+- `realtime-voice`
+- `runtime-env`
+- `secret-input`
+- `security-runtime`
+- `speech`
+- `testing`
+
+### Institutional Learnings
+
+- No relevant `docs/solutions/` entries were present in this worktree.
+
+### External References
+
+- No external research was needed for this plan. The repo already contains the
+  relevant workspace-package and SDK-export patterns.
+
+## Key Technical Decisions
+
+- Introduce `@openclaw/plugin-sdk` as a new workspace package while keeping the
+  legacy root `openclaw/plugin-sdk/*` surface alive during migration.
+  Rationale: this lets a first-wave extension set move onto real package
+  resolution without forcing every extension and every root build path to change
+  at once.
+
+- Use a dedicated opt-in boundary base config such as
+  `extensions/tsconfig.package-boundary.base.json` instead of replacing the
+  existing extension base for everyone.
+  Rationale: the repo needs to support both legacy and opt-in extension modes
+  simultaneously during migration.
+
+- Use TS project references from first-wave extensions to
+  `packages/plugin-sdk/tsconfig.json` and set
+  `disableSourceOfProjectReferenceRedirect` for the opt-in boundary mode.
+  Rationale: this gives `tsc` a real package graph while discouraging editor and
+  compiler fallback to raw source traversal.
+
+- Keep `@openclaw/plugin-sdk` private in the first wave.
+  Rationale: the immediate goal is internal boundary enforcement and migration
+  safety, not publishing a second external SDK contract before the surface is
+  stable.
+
+- Move only the first-wave SDK subpaths in the first implementation slice, and
+  keep compatibility bridges for the rest.
+  Rationale: physically moving all 315 `src/plugin-sdk/*.ts` files in one PR is
+  exactly the merge-conflict surface this plan is trying to avoid.
+
+- Do not rely on `scripts/postinstall-bundled-plugins.mjs` to build SDK
+  declarations for the first wave.
+  Rationale: explicit build/reference flows are easier to reason about and keep
+  repo behavior more predictable.
+
+## Open Questions
+
+### Resolved During Planning
+
+- Which extensions should be in the first wave?
+  Use the 10 provider/web-search extensions listed above because they are more
+  structurally isolated than the heavier channel packages.
+
+- Should the first PR replace the entire extension tree?
+  No. The first PR should support two modes in parallel and only opt in the
+  first wave.
+
+- Should the first wave require a postinstall declaration build?
+  No. The package/reference graph should be explicit, and CI should run the
+  relevant package-local typecheck intentionally.
+
+### Deferred to Implementation
+
+- Whether the first-wave package can point directly at package-local `src/*.ts`
+  via project references alone, or whether a small declaration-emission step is
+  still required for the `@openclaw/plugin-sdk` package.
+  This is an implementation-owned TS graph validation question.
+
+- Whether the root `openclaw` package should proxy first-wave SDK subpaths to
+  `packages/plugin-sdk` outputs immediately or continue using generated
+  compatibility shims under `src/plugin-sdk`.
+  This is a compatibility and build-shape detail that depends on the minimal
+  implementation path that keeps CI green.
+
+## High-Level Technical Design
+
+> This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.
+
+```mermaid
+flowchart TB
+  subgraph Legacy["Legacy extensions (unchanged)"]
+    L1["extensions/*\nopenclaw/plugin-sdk/*"]
+    L2["root tsconfig paths"]
+    L1 --> L2
+    L2 --> L3["src/plugin-sdk/*"]
+  end
+
+  subgraph OptIn["First-wave extensions"]
+    O1["10 opted-in extensions"]
+    O2["extensions/tsconfig.package-boundary.base.json"]
+    O3["rootDir = '.'\nproject reference"]
+    O4["@openclaw/plugin-sdk"]
+    O1 --> O2
+    O2 --> O3
+    O3 --> O4
+  end
+
+  subgraph SDK["New workspace package"]
+    P1["packages/plugin-sdk/package.json"]
+    P2["packages/plugin-sdk/tsconfig.json"]
+    P3["packages/plugin-sdk/src/<first-wave-subpaths>.ts"]
+    P1 --> P2
+    P2 --> P3
+  end
+
+  O4 --> SDK
+```
+
+## Implementation Units
+
+- [ ] **Unit 1: Introduce the real `@openclaw/plugin-sdk` workspace package**
+
+**Goal:** Create a real workspace package for the SDK that can own the
+first-wave subpath surface without forcing a repo-wide migration.
+
+**Requirements:** R1, R2, R3, R8, R9
+
+**Dependencies:** None
+
+**Files:**
+
+- Create: `packages/plugin-sdk/package.json`
+- Create: `packages/plugin-sdk/tsconfig.json`
+- Create: `packages/plugin-sdk/src/index.ts`
+- Create: `packages/plugin-sdk/src/*.ts` for the first-wave SDK subpaths
+- Modify: `pnpm-workspace.yaml` only if package-glob adjustments are needed
+- Modify: `package.json`
+- Modify: `src/plugin-sdk/entrypoints.ts`
+- Modify: `scripts/lib/plugin-sdk-entrypoints.json`
+- Test: `src/plugins/contracts/plugin-sdk-workspace-package.contract.test.ts`
+
+**Approach:**
+
+- Add a new workspace package named `@openclaw/plugin-sdk`.
+- Start with the first-wave SDK subpaths only, not the entire 315-file tree.
+- If directly moving a first-wave entrypoint would create an oversized diff, the
+  first PR may introduce that subpath in `packages/plugin-sdk/src` as a thin
+  package wrapper first and then flip the source of truth to the package in a
+  follow-up PR for that subpath cluster.
+- Reuse the existing entrypoint inventory machinery so the first-wave package
+  surface is declared in one canonical place.
+- Keep the root package exports alive for legacy users while the workspace
+  package becomes the new opt-in contract.
+
+**Patterns to follow:**
+
+- `packages/memory-host-sdk/package.json`
+- `packages/plugin-package-contract/package.json`
+- `src/plugin-sdk/entrypoints.ts`
+
+**Test scenarios:**
+
+- Happy path: the workspace package exports every first-wave subpath listed in
+  the plan and no required first-wave export is missing.
+- Edge case: package export metadata remains stable when the first-wave entry
+  list is re-generated or compared against the canonical inventory.
+- Integration: root package legacy SDK exports remain present after introducing
+  the new workspace package.
+
+**Verification:**
+
+- The repo contains a valid `@openclaw/plugin-sdk` workspace package with a
+  stable first-wave export map and no legacy export regression in root
+  `package.json`.
+
+- [ ] **Unit 2: Add an opt-in TS boundary mode for package-enforced extensions**
+
+**Goal:** Define the TS configuration mode that opted-in extensions will use,
+while leaving the existing extension TS behavior unchanged for everyone else.
+
+**Requirements:** R4, R6, R7, R8, R9
+
+**Dependencies:** Unit 1
+
+**Files:**
+
+- Create: `extensions/tsconfig.package-boundary.base.json`
+- Create: `tsconfig.boundary-optin.json`
+- Modify: `extensions/xai/tsconfig.json`
+- Modify: `extensions/openai/tsconfig.json`
+- Modify: `extensions/anthropic/tsconfig.json`
+- Modify: `extensions/mistral/tsconfig.json`
+- Modify: `extensions/groq/tsconfig.json`
+- Modify: `extensions/together/tsconfig.json`
+- Modify: `extensions/perplexity/tsconfig.json`
+- Modify: `extensions/tavily/tsconfig.json`
+- Modify: `extensions/exa/tsconfig.json`
+- Modify: `extensions/firecrawl/tsconfig.json`
+- Test: `src/plugins/contracts/extension-package-project-boundaries.test.ts`
+- Test: `test/extension-package-tsc-boundary.test.ts`
+
+**Approach:**
+
+- Leave `extensions/tsconfig.base.json` in place for legacy extensions.
+- Add a new opt-in base config that:
+  - sets `rootDir: "."`
+  - references `packages/plugin-sdk`
+  - enables `composite`
+  - disables project-reference source redirect when needed
+- Add a dedicated solution config for the first-wave typecheck graph instead of
+  reshaping the root repo TS project in the same PR.
+
+**Execution note:** Start with a failing package-local canary typecheck for one
+opted-in extension before applying the pattern to all 10.
+
+**Patterns to follow:**
+
+- Existing package-local extension `tsconfig.json` pattern from the prior
+  boundary work
+- Workspace package pattern from `packages/memory-host-sdk`
+
+**Test scenarios:**
+
+- Happy path: each opted-in extension typechecks successfully through the
+  package-boundary TS config.
+- Error path: a canary relative import from `../../src/cli/acp-cli.ts` fails
+  with `TS6059` for an opted-in extension.
+- Integration: non-opted-in extensions remain untouched and do not need to
+  participate in the new solution config.
+
+**Verification:**
+
+- There is a dedicated typecheck graph for the 10 opted-in extensions, and bad
+  relative imports from one of them fail through normal `tsc`.
+
+- [ ] **Unit 3: Migrate the first-wave extensions onto `@openclaw/plugin-sdk`**
+
+**Goal:** Change the first-wave extensions to consume the real SDK package
+through dependency metadata, project references, and package-name imports.
+
+**Requirements:** R5, R6, R7, R9
+
+**Dependencies:** Unit 2
+
+**Files:**
+
+- Modify: `extensions/anthropic/package.json`
+- Modify: `extensions/exa/package.json`
+- Modify: `extensions/firecrawl/package.json`
+- Modify: `extensions/groq/package.json`
+- Modify: `extensions/mistral/package.json`
+- Modify: `extensions/openai/package.json`
+- Modify: `extensions/perplexity/package.json`
+- Modify: `extensions/tavily/package.json`
+- Modify: `extensions/together/package.json`
+- Modify: `extensions/xai/package.json`
+- Modify: production and test imports under each of the 10 extension roots that
+  currently reference `openclaw/plugin-sdk/*`
+
+**Approach:**
+
+- Add `@openclaw/plugin-sdk: workspace:*` to the first-wave extension
+  `devDependencies`.
+- Replace `openclaw/plugin-sdk/*` imports in those packages with
+  `@openclaw/plugin-sdk/*`.
+- Keep local extension-internal imports on local barrels such as `./api.ts` and
+  `./runtime-api.ts`.
+- Do not change non-opted-in extensions in this PR.
+
+**Patterns to follow:**
+
+- Existing extension-local import barrels (`api.ts`, `runtime-api.ts`)
+- Package dependency shape used by other `@openclaw/*` workspace packages
+
+**Test scenarios:**
+
+- Happy path: each migrated extension still registers/loads through its existing
+  plugin tests after the import rewrite.
+- Edge case: test-only SDK imports in the opted-in extension set still resolve
+  correctly through the new package.
+- Integration: migrated extensions do not require root `openclaw/plugin-sdk/*`
+  aliases for typechecking.
+
+**Verification:**
+
+- The first-wave extensions build and test against `@openclaw/plugin-sdk`
+  without needing the legacy root SDK alias path.
+
+- [ ] **Unit 4: Preserve legacy compatibility while the migration is partial**
+
+**Goal:** Keep the rest of the repo working while the SDK exists in both legacy
+and new-package forms during migration.
+
+**Requirements:** R4, R8, R9
+
+**Dependencies:** Units 1-3
+
+**Files:**
+
+- Modify: `src/plugin-sdk/*.ts` for first-wave compatibility shims as needed
+- Modify: `package.json`
+- Modify: build or export plumbing that assembles SDK artifacts
+- Test: `src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts`
+- Test: `src/plugins/contracts/plugin-sdk-index.bundle.test.ts`
+
+**Approach:**
+
+- Keep root `openclaw/plugin-sdk/*` as the compatibility surface for legacy
+  extensions and for external consumers that are not moving yet.
+- Use either generated shims or root-export proxy wiring for the first-wave
+  subpaths that have moved into `packages/plugin-sdk`.
+- Do not attempt to retire the root SDK surface in this phase.
+
+**Patterns to follow:**
+
+- Existing root SDK export generation via `src/plugin-sdk/entrypoints.ts`
+- Existing package export compatibility in root `package.json`
+
+**Test scenarios:**
+
+- Happy path: a legacy root SDK import still resolves for a non-opted-in
+  extension after the new package exists.
+- Edge case: a first-wave subpath works through both the legacy root surface and
+  the new package surface during the migration window.
+- Integration: plugin-sdk index/bundle contract tests continue to see a coherent
+  public surface.
+
+**Verification:**
+
+- The repo supports both legacy and opt-in SDK consumption modes without
+  breaking unchanged extensions.
+
+- [ ] **Unit 5: Add scoped enforcement and document the migration contract**
+
+**Goal:** Land CI and contributor guidance that enforce the new behavior for the
+first wave without pretending the entire extension tree is migrated.
+
+**Requirements:** R5, R6, R8, R9
+
+**Dependencies:** Units 1-4
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: CI workflow files that should run the opt-in boundary typecheck
+- Modify: `AGENTS.md`
+- Modify: `docs/plugins/sdk-overview.md`
+- Modify: `docs/plugins/sdk-entrypoints.md`
+- Modify: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md`
+
+**Approach:**
+
+- Add an explicit first-wave gate, such as a dedicated `tsc -b` solution run for
+  `packages/plugin-sdk` plus the 10 opted-in extensions.
+- Document that the repo now supports both legacy and opt-in extension modes,
+  and that new extension boundary work should prefer the new package route.
+- Record the next-wave migration rule so later PRs can add more extensions
+  without re-litigating the architecture.
+
+**Patterns to follow:**
+
+- Existing contract tests under `src/plugins/contracts/`
+- Existing docs updates that explain staged migrations
+
+**Test scenarios:**
+
+- Happy path: the new first-wave typecheck gate passes for the workspace package
+  and the opted-in extensions.
+- Error path: introducing a new illegal relative import in an opted-in
+  extension fails the scoped typecheck gate.
+- Integration: CI does not require non-opted-in extensions to satisfy the new
+  package-boundary mode yet.
+
+**Verification:**
+
+- The first-wave enforcement path is documented, tested, and runnable without
+  forcing the entire extension tree to migrate.
+
+## System-Wide Impact
+
+- **Interaction graph:** this work touches the SDK source-of-truth, root package
+  exports, extension package metadata, TS graph layout, and CI verification.
+- **Error propagation:** the main intended failure mode becomes compile-time TS
+  errors (`TS6059`) in opted-in extensions instead of custom script-only
+  failures.
+- **State lifecycle risks:** dual-surface migration introduces drift risk between
+  root compatibility exports and the new workspace package.
+- **API surface parity:** first-wave subpaths must remain semantically identical
+  through both `openclaw/plugin-sdk/*` and `@openclaw/plugin-sdk/*` during the
+  transition.
+- **Integration coverage:** unit tests are not enough; scoped package-graph
+  typechecks are required to prove the boundary.
+- **Unchanged invariants:** non-opted-in extensions keep their current behavior
+  in PR 1. This plan does not claim repo-wide import-boundary enforcement.
+
+## Risks & Dependencies
+
+| Risk                                                                                                   | Mitigation                                                                                                              |
+| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| The first-wave package still resolves back into raw source and `rootDir` does not actually fail closed | Make the first implementation step a package-reference canary on one opted-in extension before widening to the full set |
+| Moving too much SDK source at once recreates the original merge-conflict problem                       | Move only the first-wave subpaths in the first PR and keep root compatibility bridges                                   |
+| Legacy and new SDK surfaces drift semantically                                                         | Keep a single entrypoint inventory, add compatibility contract tests, and make dual-surface parity explicit             |
+| Root repo build/test paths accidentally start depending on the new package in uncontrolled ways        | Use a dedicated opt-in solution config and keep root-wide TS topology changes out of the first PR                       |
+
+## Phased Delivery
+
+### Phase 1
+
+- Introduce `@openclaw/plugin-sdk`
+- Define the first-wave subpath surface
+- Prove one opted-in extension can fail closed through `rootDir`
+
+### Phase 2
+
+- Opt in the 10 first-wave extensions
+- Keep root compatibility alive for everyone else
+
+### Phase 3
+
+- Add more extensions in later PRs
+- Move more SDK subpaths into the workspace package
+- Retire root compatibility only after the legacy extension set is gone
+
+## Documentation / Operational Notes
+
+- The first PR should explicitly describe itself as a dual-mode migration, not a
+  repo-wide enforcement completion.
+- The migration guide should make it easy for later PRs to add more extensions
+  by following the same package/dependency/reference pattern.
+
+## Sources & References
+
+- Prior plan: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md`
+- Workspace config: `pnpm-workspace.yaml`
+- Existing SDK entrypoint inventory: `src/plugin-sdk/entrypoints.ts`
+- Existing root SDK exports: `package.json`
+- Existing workspace package patterns:
+  - `packages/memory-host-sdk/package.json`
+  - `packages/plugin-package-contract/package.json`

docs/platforms/ios.md

@@ -161,6 +161,22 @@ export OPENCLAW_APNS_KEY_ID="KEYID"
 export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"
 ```
 
+These are gateway-host runtime env vars, not Fastlane settings. `apps/ios/fastlane/.env` only stores
+App Store Connect / TestFlight auth such as `ASC_KEY_ID` and `ASC_ISSUER_ID`; it does not configure
+direct APNs delivery for local iOS builds.
+
+Recommended gateway-host storage:
+
+```bash
+mkdir -p ~/.openclaw/credentials/apns
+chmod 700 ~/.openclaw/credentials/apns
+mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
+chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
+export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8"
+```
+
+Do not commit the `.p8` file or place it under the repo checkout.
+
 ## Discovery paths
 
 ### Bonjour (LAN)

docs/plugins/architecture.md

@@ -30,6 +30,7 @@ native OpenClaw plugin registers against one or more capability types:
 | Capability             | Registration method                              | Example plugins                      |
 | ---------------------- | ------------------------------------------------ | ------------------------------------ |
 | Text inference         | `api.registerProvider(...)`                      | `openai`, `anthropic`                |
+| CLI inference backend  | `api.registerCliBackend(...)`                    | `openai`, `anthropic`                |
 | Speech                 | `api.registerSpeechProvider(...)`                | `elevenlabs`, `microsoft`            |
 | Realtime transcription | `api.registerRealtimeTranscriptionProvider(...)` | `openai`                             |
 | Realtime voice         | `api.registerRealtimeVoiceProvider(...)`         | `openai`                             |
@@ -608,14 +609,16 @@ conversation, and it runs after core approval handling finishes.
 
 Provider plugins now have two layers:
 
-- manifest metadata: `providerAuthEnvVars` for cheap env-auth lookup before
-  runtime load, plus `providerAuthChoices` for cheap onboarding/auth-choice
+- manifest metadata: `providerAuthEnvVars` for cheap provider env-auth lookup
+  before runtime load, `channelEnvVars` for cheap channel env/setup lookup
+  before runtime load, plus `providerAuthChoices` for cheap onboarding/auth-choice
   labels and CLI flag metadata before runtime load
 - config-time hooks: `catalog` / legacy `discovery` plus `applyConfigDefaults`
 - runtime hooks: `normalizeModelId`, `normalizeTransport`,
   `normalizeConfig`,
   `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
-  `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`,
+  `resolveSyntheticAuth`, `resolveExternalAuthProfiles`,
+  `shouldDeferSyntheticProfileAuth`,
   `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`,
   `contributeResolvedModelCompat`, `capabilities`,
   `normalizeToolSchemas`, `inspectToolSchemas`,
@@ -643,57 +646,62 @@ one-flag auth wiring without loading provider runtime. Keep provider runtime
 `envVars` for operator-facing hints such as onboarding labels or OAuth
 client-id/client-secret setup vars.
 
+Use manifest `channelEnvVars` when a channel has env-driven auth or setup that
+generic shell-env fallback, config/status checks, or setup prompts should see
+without loading channel runtime.
+
 ### Hook order and usage
 
 For model/provider plugins, OpenClaw calls hooks in this rough order.
 The "When to use" column is the quick decision guide.
 
-| #   | Hook                              | What it does                                                                             | When to use                                                                                                                                 |
-| --- | --------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | `catalog`                         | Publish provider config into `models.providers` during `models.json` generation          | Provider owns a catalog or base URL defaults                                                                                                |
-| 2   | `applyConfigDefaults`             | Apply provider-owned global config defaults during config materialization                | Defaults depend on auth mode, env, or provider model-family semantics                                                                       |
-| --  | _(built-in model lookup)_         | OpenClaw tries the normal registry/catalog path first                                    | _(not a plugin hook)_                                                                                                                       |
-| 3   | `normalizeModelId`                | Normalize legacy or preview model-id aliases before lookup                               | Provider owns alias cleanup before canonical model resolution                                                                               |
-| 4   | `normalizeTransport`              | Normalize provider-family `api` / `baseUrl` before generic model assembly                | Provider owns transport cleanup for custom provider ids in the same transport family                                                        |
-| 5   | `normalizeConfig`                 | Normalize `models.providers.<id>` before runtime/provider resolution                     | Provider needs config cleanup that should live with the plugin; bundled Google-family helpers also backstop supported Google config entries |
-| 6   | `applyNativeStreamingUsageCompat` | Apply native streaming-usage compat rewrites to config providers                         | Provider needs endpoint-driven native streaming usage metadata fixes                                                                        |
-| 7   | `resolveConfigApiKey`             | Resolve env-marker auth for config providers before runtime auth loading                 | Provider has provider-owned env-marker API-key resolution; `amazon-bedrock` also has a built-in AWS env-marker resolver here                |
-| 8   | `resolveSyntheticAuth`            | Surface local/self-hosted or config-backed auth without persisting plaintext             | Provider can operate with a synthetic/local credential marker                                                                               |
-| 9   | `shouldDeferSyntheticProfileAuth` | Lower stored synthetic profile placeholders behind env/config-backed auth                | Provider stores synthetic placeholder profiles that should not win precedence                                                               |
-| 10  | `resolveDynamicModel`             | Sync fallback for provider-owned model ids not in the local registry yet                 | Provider accepts arbitrary upstream model ids                                                                                               |
-| 11  | `prepareDynamicModel`             | Async warm-up, then `resolveDynamicModel` runs again                                     | Provider needs network metadata before resolving unknown ids                                                                                |
-| 12  | `normalizeResolvedModel`          | Final rewrite before the embedded runner uses the resolved model                         | Provider needs transport rewrites but still uses a core transport                                                                           |
-| 13  | `contributeResolvedModelCompat`   | Contribute compat flags for vendor models behind another compatible transport            | Provider recognizes its own models on proxy transports without taking over the provider                                                     |
-| 14  | `capabilities`                    | Provider-owned transcript/tooling metadata used by shared core logic                     | Provider needs transcript/provider-family quirks                                                                                            |
-| 15  | `normalizeToolSchemas`            | Normalize tool schemas before the embedded runner sees them                              | Provider needs transport-family schema cleanup                                                                                              |
-| 16  | `inspectToolSchemas`              | Surface provider-owned schema diagnostics after normalization                            | Provider wants keyword warnings without teaching core provider-specific rules                                                               |
-| 17  | `resolveReasoningOutputMode`      | Select native vs tagged reasoning-output contract                                        | Provider needs tagged reasoning/final output instead of native fields                                                                       |
-| 18  | `prepareExtraParams`              | Request-param normalization before generic stream option wrappers                        | Provider needs default request params or per-provider param cleanup                                                                         |
-| 19  | `createStreamFn`                  | Fully replace the normal stream path with a custom transport                             | Provider needs a custom wire protocol, not just a wrapper                                                                                   |
-| 20  | `wrapStreamFn`                    | Stream wrapper after generic wrappers are applied                                        | Provider needs request headers/body/model compat wrappers without a custom transport                                                        |
-| 21  | `resolveTransportTurnState`       | Attach native per-turn transport headers or metadata                                     | Provider wants generic transports to send provider-native turn identity                                                                     |
-| 22  | `resolveWebSocketSessionPolicy`   | Attach native WebSocket headers or session cool-down policy                              | Provider wants generic WS transports to tune session headers or fallback policy                                                             |
-| 23  | `formatApiKey`                    | Auth-profile formatter: stored profile becomes the runtime `apiKey` string               | Provider stores extra auth metadata and needs a custom runtime token shape                                                                  |
-| 24  | `refreshOAuth`                    | OAuth refresh override for custom refresh endpoints or refresh-failure policy            | Provider does not fit the shared `pi-ai` refreshers                                                                                         |
-| 25  | `buildAuthDoctorHint`             | Repair hint appended when OAuth refresh fails                                            | Provider needs provider-owned auth repair guidance after refresh failure                                                                    |
-| 26  | `matchesContextOverflowError`     | Provider-owned context-window overflow matcher                                           | Provider has raw overflow errors generic heuristics would miss                                                                              |
-| 27  | `classifyFailoverReason`          | Provider-owned failover reason classification                                            | Provider can map raw API/transport errors to rate-limit/overload/etc                                                                        |
-| 28  | `isCacheTtlEligible`              | Prompt-cache policy for proxy/backhaul providers                                         | Provider needs proxy-specific cache TTL gating                                                                                              |
-| 29  | `buildMissingAuthMessage`         | Replacement for the generic missing-auth recovery message                                | Provider needs a provider-specific missing-auth recovery hint                                                                               |
-| 30  | `suppressBuiltInModel`            | Stale upstream model suppression plus optional user-facing error hint                    | Provider needs to hide stale upstream rows or replace them with a vendor hint                                                               |
-| 31  | `augmentModelCatalog`             | Synthetic/final catalog rows appended after discovery                                    | Provider needs synthetic forward-compat rows in `models list` and pickers                                                                   |
-| 32  | `isBinaryThinking`                | On/off reasoning toggle for binary-thinking providers                                    | Provider exposes only binary thinking on/off                                                                                                |
-| 33  | `supportsXHighThinking`           | `xhigh` reasoning support for selected models                                            | Provider wants `xhigh` on only a subset of models                                                                                           |
-| 34  | `resolveDefaultThinkingLevel`     | Default `/think` level for a specific model family                                       | Provider owns default `/think` policy for a model family                                                                                    |
-| 35  | `isModernModelRef`                | Modern-model matcher for live profile filters and smoke selection                        | Provider owns live/smoke preferred-model matching                                                                                           |
-| 36  | `prepareRuntimeAuth`              | Exchange a configured credential into the actual runtime token/key just before inference | Provider needs a token exchange or short-lived request credential                                                                           |
-| 37  | `resolveUsageAuth`                | Resolve usage/billing credentials for `/usage` and related status surfaces               | Provider needs custom usage/quota token parsing or a different usage credential                                                             |
-| 38  | `fetchUsageSnapshot`              | Fetch and normalize provider-specific usage/quota snapshots after auth is resolved       | Provider needs a provider-specific usage endpoint or payload parser                                                                         |
-| 39  | `createEmbeddingProvider`         | Build a provider-owned embedding adapter for memory/search                               | Memory embedding behavior belongs with the provider plugin                                                                                  |
-| 40  | `buildReplayPolicy`               | Return a replay policy controlling transcript handling for the provider                  | Provider needs custom transcript policy (for example, thinking-block stripping)                                                             |
-| 41  | `sanitizeReplayHistory`           | Rewrite replay history after generic transcript cleanup                                  | Provider needs provider-specific replay rewrites beyond shared compaction helpers                                                           |
-| 42  | `validateReplayTurns`             | Final replay-turn validation or reshaping before the embedded runner                     | Provider transport needs stricter turn validation after generic sanitation                                                                  |
-| 43  | `onModelSelected`                 | Run provider-owned post-selection side effects                                           | Provider needs telemetry or provider-owned state when a model becomes active                                                                |
+| #   | Hook                              | What it does                                                                                                   | When to use                                                                                                                                 |
+| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `catalog`                         | Publish provider config into `models.providers` during `models.json` generation                                | Provider owns a catalog or base URL defaults                                                                                                |
+| 2   | `applyConfigDefaults`             | Apply provider-owned global config defaults during config materialization                                      | Defaults depend on auth mode, env, or provider model-family semantics                                                                       |
+| --  | _(built-in model lookup)_         | OpenClaw tries the normal registry/catalog path first                                                          | _(not a plugin hook)_                                                                                                                       |
+| 3   | `normalizeModelId`                | Normalize legacy or preview model-id aliases before lookup                                                     | Provider owns alias cleanup before canonical model resolution                                                                               |
+| 4   | `normalizeTransport`              | Normalize provider-family `api` / `baseUrl` before generic model assembly                                      | Provider owns transport cleanup for custom provider ids in the same transport family                                                        |
+| 5   | `normalizeConfig`                 | Normalize `models.providers.<id>` before runtime/provider resolution                                           | Provider needs config cleanup that should live with the plugin; bundled Google-family helpers also backstop supported Google config entries |
+| 6   | `applyNativeStreamingUsageCompat` | Apply native streaming-usage compat rewrites to config providers                                               | Provider needs endpoint-driven native streaming usage metadata fixes                                                                        |
+| 7   | `resolveConfigApiKey`             | Resolve env-marker auth for config providers before runtime auth loading                                       | Provider has provider-owned env-marker API-key resolution; `amazon-bedrock` also has a built-in AWS env-marker resolver here                |
+| 8   | `resolveSyntheticAuth`            | Surface local/self-hosted or config-backed auth without persisting plaintext                                   | Provider can operate with a synthetic/local credential marker                                                                               |
+| 9   | `resolveExternalAuthProfiles`     | Overlay provider-owned external auth profiles; default `persistence` is `runtime-only` for CLI/app-owned creds | Provider reuses external auth credentials without persisting copied refresh tokens                                                          |
+| 10  | `shouldDeferSyntheticProfileAuth` | Lower stored synthetic profile placeholders behind env/config-backed auth                                      | Provider stores synthetic placeholder profiles that should not win precedence                                                               |
+| 11  | `resolveDynamicModel`             | Sync fallback for provider-owned model ids not in the local registry yet                                       | Provider accepts arbitrary upstream model ids                                                                                               |
+| 12  | `prepareDynamicModel`             | Async warm-up, then `resolveDynamicModel` runs again                                                           | Provider needs network metadata before resolving unknown ids                                                                                |
+| 13  | `normalizeResolvedModel`          | Final rewrite before the embedded runner uses the resolved model                                               | Provider needs transport rewrites but still uses a core transport                                                                           |
+| 14  | `contributeResolvedModelCompat`   | Contribute compat flags for vendor models behind another compatible transport                                  | Provider recognizes its own models on proxy transports without taking over the provider                                                     |
+| 15  | `capabilities`                    | Provider-owned transcript/tooling metadata used by shared core logic                                           | Provider needs transcript/provider-family quirks                                                                                            |
+| 16  | `normalizeToolSchemas`            | Normalize tool schemas before the embedded runner sees them                                                    | Provider needs transport-family schema cleanup                                                                                              |
+| 17  | `inspectToolSchemas`              | Surface provider-owned schema diagnostics after normalization                                                  | Provider wants keyword warnings without teaching core provider-specific rules                                                               |
+| 18  | `resolveReasoningOutputMode`      | Select native vs tagged reasoning-output contract                                                              | Provider needs tagged reasoning/final output instead of native fields                                                                       |
+| 19  | `prepareExtraParams`              | Request-param normalization before generic stream option wrappers                                              | Provider needs default request params or per-provider param cleanup                                                                         |
+| 20  | `createStreamFn`                  | Fully replace the normal stream path with a custom transport                                                   | Provider needs a custom wire protocol, not just a wrapper                                                                                   |
+| 21  | `wrapStreamFn`                    | Stream wrapper after generic wrappers are applied                                                              | Provider needs request headers/body/model compat wrappers without a custom transport                                                        |
+| 22  | `resolveTransportTurnState`       | Attach native per-turn transport headers or metadata                                                           | Provider wants generic transports to send provider-native turn identity                                                                     |
+| 23  | `resolveWebSocketSessionPolicy`   | Attach native WebSocket headers or session cool-down policy                                                    | Provider wants generic WS transports to tune session headers or fallback policy                                                             |
+| 24  | `formatApiKey`                    | Auth-profile formatter: stored profile becomes the runtime `apiKey` string                                     | Provider stores extra auth metadata and needs a custom runtime token shape                                                                  |
+| 25  | `refreshOAuth`                    | OAuth refresh override for custom refresh endpoints or refresh-failure policy                                  | Provider does not fit the shared `pi-ai` refreshers                                                                                         |
+| 26  | `buildAuthDoctorHint`             | Repair hint appended when OAuth refresh fails                                                                  | Provider needs provider-owned auth repair guidance after refresh failure                                                                    |
+| 27  | `matchesContextOverflowError`     | Provider-owned context-window overflow matcher                                                                 | Provider has raw overflow errors generic heuristics would miss                                                                              |
+| 28  | `classifyFailoverReason`          | Provider-owned failover reason classification                                                                  | Provider can map raw API/transport errors to rate-limit/overload/etc                                                                        |
+| 29  | `isCacheTtlEligible`              | Prompt-cache policy for proxy/backhaul providers                                                               | Provider needs proxy-specific cache TTL gating                                                                                              |
+| 30  | `buildMissingAuthMessage`         | Replacement for the generic missing-auth recovery message                                                      | Provider needs a provider-specific missing-auth recovery hint                                                                               |
+| 31  | `suppressBuiltInModel`            | Stale upstream model suppression plus optional user-facing error hint                                          | Provider needs to hide stale upstream rows or replace them with a vendor hint                                                               |
+| 32  | `augmentModelCatalog`             | Synthetic/final catalog rows appended after discovery                                                          | Provider needs synthetic forward-compat rows in `models list` and pickers                                                                   |
+| 33  | `isBinaryThinking`                | On/off reasoning toggle for binary-thinking providers                                                          | Provider exposes only binary thinking on/off                                                                                                |
+| 34  | `supportsXHighThinking`           | `xhigh` reasoning support for selected models                                                                  | Provider wants `xhigh` on only a subset of models                                                                                           |
+| 35  | `resolveDefaultThinkingLevel`     | Default `/think` level for a specific model family                                                             | Provider owns default `/think` policy for a model family                                                                                    |
+| 36  | `isModernModelRef`                | Modern-model matcher for live profile filters and smoke selection                                              | Provider owns live/smoke preferred-model matching                                                                                           |
+| 37  | `prepareRuntimeAuth`              | Exchange a configured credential into the actual runtime token/key just before inference                       | Provider needs a token exchange or short-lived request credential                                                                           |
+| 38  | `resolveUsageAuth`                | Resolve usage/billing credentials for `/usage` and related status surfaces                                     | Provider needs custom usage/quota token parsing or a different usage credential                                                             |
+| 39  | `fetchUsageSnapshot`              | Fetch and normalize provider-specific usage/quota snapshots after auth is resolved                             | Provider needs a provider-specific usage endpoint or payload parser                                                                         |
+| 40  | `createEmbeddingProvider`         | Build a provider-owned embedding adapter for memory/search                                                     | Memory embedding behavior belongs with the provider plugin                                                                                  |
+| 41  | `buildReplayPolicy`               | Return a replay policy controlling transcript handling for the provider                                        | Provider needs custom transcript policy (for example, thinking-block stripping)                                                             |
+| 42  | `sanitizeReplayHistory`           | Rewrite replay history after generic transcript cleanup                                                        | Provider needs provider-specific replay rewrites beyond shared compaction helpers                                                           |
+| 43  | `validateReplayTurns`             | Final replay-turn validation or reshaping before the embedded runner                                           | Provider transport needs stricter turn validation after generic sanitation                                                                  |
+| 44  | `onModelSelected`                 | Run provider-owned post-selection side effects                                                                 | Provider needs telemetry or provider-owned state when a model becomes active                                                                |
 
 `normalizeModelId`, `normalizeTransport`, and `normalizeConfig` first check the
 matched provider plugin, then fall through other hook-capable provider plugins

docs/plugins/building-plugins.md

@@ -151,6 +151,7 @@ A single plugin can register any number of capabilities via the `api` object:
 | Capability             | Registration method                              | Detailed guide                                                                  |
 | ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
 | Text inference (LLM)   | `api.registerProvider(...)`                      | [Provider Plugins](/plugins/sdk-provider-plugins)                               |
+| CLI inference backend  | `api.registerCliBackend(...)`                    | [CLI Backends](/gateway/cli-backends)                                           |
 | Channel / messaging    | `api.registerChannel(...)`                       | [Channel Plugins](/plugins/sdk-channel-plugins)                                 |
 | Speech (TTS/STT)       | `api.registerSpeechProvider(...)`                | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
 | Realtime transcription | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |

docs/plugins/manifest.md

@@ -89,9 +89,13 @@ Those belong in your plugin code and `package.json`.
   "modelSupport": {
     "modelPrefixes": ["router-"]
   },
+  "cliBackends": ["openrouter-cli"],
   "providerAuthEnvVars": {
     "openrouter": ["OPENROUTER_API_KEY"]
   },
+  "channelEnvVars": {
+    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
+  },
   "providerAuthChoices": [
     {
       "provider": "openrouter",
@@ -139,7 +143,9 @@ Those belong in your plugin code and `package.json`.
 | `channels`                          | No       | `string[]`                       | Channel ids owned by this plugin. Used for discovery and config validation.                                                                                                                                  |
 | `providers`                         | No       | `string[]`                       | Provider ids owned by this plugin.                                                                                                                                                                           |
 | `modelSupport`                      | No       | `object`                         | Manifest-owned shorthand model-family metadata used to auto-load the plugin before runtime.                                                                                                                  |
+| `cliBackends`                       | No       | `string[]`                       | CLI inference backend ids owned by this plugin. Used for startup auto-activation from explicit config refs.                                                                                                  |
 | `providerAuthEnvVars`               | No       | `Record<string, string[]>`       | Cheap provider-auth env metadata that OpenClaw can inspect without loading plugin code.                                                                                                                      |
+| `channelEnvVars`                    | No       | `Record<string, string[]>`       | Cheap channel env metadata that OpenClaw can inspect without loading plugin code. Use this for env-driven channel setup or auth surfaces that generic startup/config helpers should see.                     |
 | `providerAuthChoices`               | No       | `object[]`                       | Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring.                                                                                                |
 | `contracts`                         | No       | `object`                         | Static bundled capability snapshot for speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, and tool ownership. |
 | `channelConfigs`                    | No       | `Record<string, object>`         | Manifest-owned channel config metadata merged into discovery and validation surfaces before runtime loads.                                                                                                   |
@@ -434,6 +440,9 @@ See [Configuration reference](/gateway/configuration) for the full `plugins.*` s
 - `providerAuthEnvVars` is the cheap metadata path for auth probes, env-marker
   validation, and similar provider-auth surfaces that should not boot plugin
   runtime just to inspect env names.
+- `channelEnvVars` is the cheap metadata path for shell-env fallback, setup
+  prompts, and similar channel surfaces that should not boot plugin runtime
+  just to inspect env names.
 - `providerAuthChoices` is the cheap metadata path for auth-choice pickers,
   `--auth-choice` resolution, preferred-provider mapping, and simple onboarding
   CLI flag registration before provider runtime loads. For runtime wizard
@@ -443,7 +452,7 @@ See [Configuration reference](/gateway/configuration) for the full `plugins.*` s
   - `kind: "memory"` is selected by `plugins.slots.memory`.
   - `kind: "context-engine"` is selected by `plugins.slots.contextEngine`
     (default: built-in `legacy`).
-- `channels`, `providers`, and `skills` can be omitted when a
+- `channels`, `providers`, `cliBackends`, and `skills` can be omitted when a
   plugin does not need them.
 - If your plugin depends on native modules, document the build steps and any
   package-manager allowlist requirements (for example, pnpm `allow-build-scripts`

docs/plugins/sdk-channel-plugins.md

@@ -108,9 +108,15 @@ For setup specifically:
 - `openclaw/plugin-sdk/channel-setup` covers the optional-install setup
   builders plus a few setup-safe primitives:
   `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
-  `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
-  `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, and
-  `splitSetupEntries`
+
+If your channel supports env-driven setup or auth and generic startup/config
+flows should know those env names before runtime loads, declare them in the
+plugin manifest with `channelEnvVars`. Keep channel runtime `envVars` or local
+constants for operator-facing copy only.
+`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
+`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, and
+`splitSetupEntries`
+
 - use the broader `openclaw/plugin-sdk/setup` seam only when you also need the
   heavier shared setup/config helpers such as
   `moveSingleAccountChannelSectionToDefaultAccount(...)`

docs/plugins/sdk-migration.md

@@ -276,7 +276,7 @@ Current bundled provider examples:
   | `plugin-sdk/allowlist-config-edit` | Allowlist config helpers | Allowlist config edit/read helpers |
   | `plugin-sdk/group-access` | Group access helpers | Shared group-access decision helpers |
   | `plugin-sdk/direct-dm` | Direct-DM helpers | Shared direct-DM auth/guard helpers |
-  | `plugin-sdk/extension-shared` | Shared extension helpers | Passive-channel/status helper primitives |
+  | `plugin-sdk/extension-shared` | Shared extension helpers | Passive-channel/status and ambient proxy helper primitives |
   | `plugin-sdk/webhook-targets` | Webhook target helpers | Webhook target registry and route-install helpers |
   | `plugin-sdk/webhook-path` | Webhook path helpers | Webhook path normalization helpers |
   | `plugin-sdk/web-media` | Shared web media helpers | Remote/local media loading helpers |

docs/plugins/sdk-overview.md

@@ -114,6 +114,7 @@ explicitly promotes one as public.
     | `plugin-sdk/channel-targets` | Target parsing/matching helpers |
     | `plugin-sdk/channel-contract` | Channel contract types |
     | `plugin-sdk/channel-feedback` | Feedback/reaction wiring |
+    | `plugin-sdk/channel-secret-runtime` | Narrow secret-contract helpers such as `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, and secret target types |
   </Accordion>
 
   <Accordion title="Provider subpaths">
@@ -122,12 +123,13 @@ explicitly promotes one as public.
     | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
     | `plugin-sdk/provider-setup` | Curated local/self-hosted provider setup helpers |
     | `plugin-sdk/self-hosted-provider-setup` | Focused OpenAI-compatible self-hosted provider setup helpers |
+    | `plugin-sdk/cli-backend` | CLI backend defaults + watchdog constants |
     | `plugin-sdk/provider-auth-runtime` | Runtime API-key resolution helpers for provider plugins |
-    | `plugin-sdk/provider-auth-api-key` | API-key onboarding/profile-write helpers |
+    | `plugin-sdk/provider-auth-api-key` | API-key onboarding/profile-write helpers such as `upsertApiKeyProfile` |
     | `plugin-sdk/provider-auth-result` | Standard OAuth auth-result builder |
     | `plugin-sdk/provider-auth-login` | Shared interactive login helpers for provider plugins |
     | `plugin-sdk/provider-env-vars` | Provider auth env-var lookup helpers |
-    | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
+    | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
     | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, shared replay-policy builders, provider-endpoint helpers, and model-id normalization helpers such as `normalizeNativeXaiModelId` |
     | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
     | `plugin-sdk/provider-http` | Generic provider HTTP/endpoint capability helpers |
@@ -153,6 +155,7 @@ explicitly promotes one as public.
     | `plugin-sdk/command-detection` | Shared command detection helpers |
     | `plugin-sdk/command-surface` | Command-body normalization and command-surface helpers |
     | `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
+    | `plugin-sdk/channel-secret-runtime` | Narrow secret-contract collection helpers for channel/plugin secret surfaces |
     | `plugin-sdk/security-runtime` | Shared trust, DM gating, external-content, and secret-collection helpers |
     | `plugin-sdk/ssrf-policy` | Host allowlist and private-network SSRF policy helpers |
     | `plugin-sdk/ssrf-runtime` | Pinned-dispatcher, SSRF-guarded fetch, and SSRF policy helpers |
@@ -202,7 +205,7 @@ explicitly promotes one as public.
     | `plugin-sdk/boolean-param` | Loose boolean param reader |
     | `plugin-sdk/dangerous-name-runtime` | Dangerous-name matching resolution helpers |
     | `plugin-sdk/device-bootstrap` | Device bootstrap and pairing token helpers |
-    | `plugin-sdk/extension-shared` | Shared passive-channel and status helper primitives |
+    | `plugin-sdk/extension-shared` | Shared passive-channel, status, and ambient proxy helper primitives |
     | `plugin-sdk/models-provider-runtime` | `/models` command/provider reply helpers |
     | `plugin-sdk/skill-commands-runtime` | Skill command listing helpers |
     | `plugin-sdk/native-command-registry` | Native command registry/build/serialize helpers |
@@ -292,6 +295,7 @@ methods:
 | Method                                           | What it registers                |
 | ------------------------------------------------ | -------------------------------- |
 | `api.registerProvider(...)`                      | Text inference (LLM)             |
+| `api.registerCliBackend(...)`                    | Local CLI inference backend      |
 | `api.registerChannel(...)`                       | Messaging channel                |
 | `api.registerSpeechProvider(...)`                | Text-to-speech / STT synthesis   |
 | `api.registerRealtimeTranscriptionProvider(...)` | Streaming realtime transcription |
@@ -362,6 +366,18 @@ Use `commands` by itself only when you do not need lazy root CLI registration.
 That eager compatibility path remains supported, but it does not install
 descriptor-backed placeholders for parse-time lazy loading.
 
+### CLI backend registration
+
+`api.registerCliBackend(...)` lets a plugin own the default config for a local
+AI CLI backend such as `codex-cli`.
+
+- The backend `id` becomes the provider prefix in model refs like `codex-cli/gpt-5`.
+- The backend `config` uses the same shape as `agents.defaults.cliBackends.<id>`.
+- User config still wins. OpenClaw merges `agents.defaults.cliBackends.<id>` over the
+  plugin default before running the CLI.
+- Use `normalizeConfig` when a backend needs compatibility rewrites after merge
+  (for example normalizing old flag shapes).
+
 ### Exclusive slots
 
 | Method                                     | What it registers                     |

docs/plugins/sdk-provider-plugins.md

@@ -283,7 +283,7 @@ API key auth, and dynamic model resolution.
 
     Real bundled examples:
 
-    - `google`: `google-gemini`
+    - `google` and `google-gemini-cli`: `google-gemini`
     - `openrouter`, `kilocode`, `opencode`, and `opencode-go`: `passthrough-gemini`
     - `amazon-bedrock` and `anthropic-vertex`: `anthropic-by-model`
     - `minimax`: `hybrid-anthropic-openai`
@@ -303,7 +303,7 @@ API key auth, and dynamic model resolution.
 
     Real bundled examples:
 
-    - `google`: `google-thinking`
+    - `google` and `google-gemini-cli`: `google-thinking`
     - `kilocode`: `kilocode-thinking`
     - `moonshot`: `moonshot-thinking`
     - `minimax` and `minimax-portal`: `minimax-fast-mode`
@@ -592,9 +592,20 @@ API key auth, and dynamic model resolution.
         id: "acme-ai",
         label: "Acme Video",
         capabilities: {
-          maxVideos: 1,
-          maxDurationSeconds: 10,
-          supportsResolution: true,
+          generate: {
+            maxVideos: 1,
+            maxDurationSeconds: 10,
+            supportsResolution: true,
+          },
+          imageToVideo: {
+            enabled: true,
+            maxVideos: 1,
+            maxInputImages: 1,
+            maxDurationSeconds: 5,
+          },
+          videoToVideo: {
+            enabled: false,
+          },
         },
         generateVideo: async (req) => ({ videos: [] }),
       });
@@ -631,6 +642,17 @@ API key auth, and dynamic model resolution.
     recommended pattern for company plugins (one plugin per vendor). See
     [Internals: Capability Ownership](/plugins/architecture#capability-ownership-model).
 
+    For video generation, prefer the mode-aware capability shape shown above:
+    `generate`, `imageToVideo`, and `videoToVideo`. Flat aggregate fields such
+    as `maxInputImages`, `maxInputVideos`, and `maxDurationSeconds` are not
+    enough to advertise transform-mode support or disabled modes cleanly.
+
+    Music-generation providers should follow the same pattern:
+    `generate` for prompt-only generation and `edit` for reference-image-based
+    generation. Flat aggregate fields such as `maxInputImages`,
+    `supportsLyrics`, and `supportsFormat` are not enough to advertise edit
+    support; explicit `generate` / `edit` blocks are the expected contract.
+
   </Step>
 
   <Step title="Test">

docs/plugins/webhooks.md

@@ -0,0 +1,194 @@
+---
+summary: "Webhooks plugin: authenticated TaskFlow ingress for trusted external automation"
+read_when:
+  - You want to trigger or drive TaskFlows from an external system
+  - You are configuring the bundled webhooks plugin
+title: "Webhooks Plugin"
+---
+
+# Webhooks (plugin)
+
+The Webhooks plugin adds authenticated HTTP routes that bind external
+automation to OpenClaw TaskFlows.
+
+Use it when you want a trusted system such as Zapier, n8n, a CI job, or an
+internal service to create and drive managed TaskFlows without writing a custom
+plugin first.
+
+## Where it runs
+
+The Webhooks plugin runs inside the Gateway process.
+
+If your Gateway runs on another machine, install and configure the plugin on
+that Gateway host, then restart the Gateway.
+
+## Configure routes
+
+Set config under `plugins.entries.webhooks.config`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      webhooks: {
+        enabled: true,
+        config: {
+          routes: {
+            zapier: {
+              path: "/plugins/webhooks/zapier",
+              sessionKey: "agent:main:main",
+              secret: {
+                source: "env",
+                provider: "default",
+                id: "OPENCLAW_WEBHOOK_SECRET",
+              },
+              controllerId: "webhooks/zapier",
+              description: "Zapier TaskFlow bridge",
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Route fields:
+
+- `enabled`: optional, defaults to `true`
+- `path`: optional, defaults to `/plugins/webhooks/<routeId>`
+- `sessionKey`: required session that owns the bound TaskFlows
+- `secret`: required shared secret or SecretRef
+- `controllerId`: optional controller id for created managed flows
+- `description`: optional operator note
+
+Supported `secret` inputs:
+
+- Plain string
+- SecretRef with `source: "env" | "file" | "exec"`
+
+If a secret-backed route cannot resolve its secret at startup, the plugin skips
+that route and logs a warning instead of exposing a broken endpoint.
+
+## Security model
+
+Each route is trusted to act with the TaskFlow authority of its configured
+`sessionKey`.
+
+This means the route can inspect and mutate TaskFlows owned by that session, so
+you should:
+
+- Use a strong unique secret per route
+- Prefer secret references over inline plaintext secrets
+- Bind routes to the narrowest session that fits the workflow
+- Expose only the specific webhook path you need
+
+The plugin applies:
+
+- Shared-secret authentication
+- Request body size and timeout guards
+- Fixed-window rate limiting
+- In-flight request limiting
+- Owner-bound TaskFlow access through `api.runtime.taskFlow.bindSession(...)`
+
+## Request format
+
+Send `POST` requests with:
+
+- `Content-Type: application/json`
+- `Authorization: Bearer <secret>` or `x-openclaw-webhook-secret: <secret>`
+
+Example:
+
+```bash
+curl -X POST https://gateway.example.com/plugins/webhooks/zapier \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_SHARED_SECRET' \
+  -d '{"action":"create_flow","goal":"Review inbound queue"}'
+```
+
+## Supported actions
+
+The plugin currently accepts these JSON `action` values:
+
+- `create_flow`
+- `get_flow`
+- `list_flows`
+- `find_latest_flow`
+- `resolve_flow`
+- `get_task_summary`
+- `set_waiting`
+- `resume_flow`
+- `finish_flow`
+- `fail_flow`
+- `request_cancel`
+- `cancel_flow`
+- `run_task`
+
+### `create_flow`
+
+Creates a managed TaskFlow for the route's bound session.
+
+Example:
+
+```json
+{
+  "action": "create_flow",
+  "goal": "Review inbound queue",
+  "status": "queued",
+  "notifyPolicy": "done_only"
+}
+```
+
+### `run_task`
+
+Creates a managed child task inside an existing managed TaskFlow.
+
+Allowed runtimes are:
+
+- `subagent`
+- `acp`
+
+Example:
+
+```json
+{
+  "action": "run_task",
+  "flowId": "flow_123",
+  "runtime": "acp",
+  "childSessionKey": "agent:main:acp:worker",
+  "task": "Inspect the next message batch"
+}
+```
+
+## Response shape
+
+Successful responses return:
+
+```json
+{
+  "ok": true,
+  "routeId": "zapier",
+  "result": {}
+}
+```
+
+Rejected requests return:
+
+```json
+{
+  "ok": false,
+  "routeId": "zapier",
+  "code": "not_found",
+  "error": "TaskFlow not found.",
+  "result": {}
+}
+```
+
+The plugin intentionally scrubs owner/session metadata from webhook responses.
+
+## Related docs
+
+- [Plugin runtime SDK](/plugins/sdk-runtime)
+- [Hooks and webhooks overview](/automation/hooks)
+- [CLI webhooks](/cli/webhooks)

docs/providers/anthropic.md

@@ -1,5 +1,5 @@
 ---
-summary: "Use Anthropic Claude via API keys in OpenClaw"
+summary: "Use Anthropic Claude via API keys or Claude CLI in OpenClaw"
 read_when:
   - You want to use Anthropic models in OpenClaw
 title: "Anthropic"
@@ -7,31 +7,19 @@ title: "Anthropic"
 
 # Anthropic (Claude)
 
-Anthropic builds the **Claude** model family and provides access via an API.
-In OpenClaw, new Anthropic setup should use an API key. Existing legacy
-Anthropic token profiles are still honored at runtime if they are already
-configured.
+Anthropic builds the **Claude** model family and provides access via an API and
+Claude CLI. In OpenClaw, Anthropic API keys and Claude CLI reuse are both
+supported. Existing legacy Anthropic token profiles are still honored at
+runtime if they are already configured.
 
 <Warning>
-For Anthropic in OpenClaw, the billing split is:
+Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so
+OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned for this
+integration unless Anthropic publishes a new policy.
 
-- **Anthropic API key**: normal Anthropic API billing.
-- **Claude subscription auth inside OpenClaw**: Anthropic told OpenClaw users on
-  **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that this counts as
-  third-party harness usage and requires **Extra Usage** (pay-as-you-go,
-  billed separately from the subscription).
-
-Our local repros match that split:
-
-- direct `claude -p` may still work
-- `claude -p --append-system-prompt ...` can trip the Extra Usage guard when
-  the prompt identifies OpenClaw
-- the same OpenClaw-like system prompt does **not** reproduce the block on the
-  Anthropic SDK + `ANTHROPIC_API_KEY` path
-
-So the practical rule is: **Anthropic API key, or Claude subscription with
-Extra Usage**. If you want the clearest production path, use an Anthropic API
-key.
+For long-lived gateway hosts, Anthropic API keys are still the clearest and
+most predictable production path. If you already use Claude CLI on the host,
+OpenClaw can reuse that login directly.
 
 Anthropic's current public docs:
 
@@ -202,10 +190,7 @@ requests.
 This only activates when `params.context1m` is explicitly set to `true` for
 that model.
 
-Requirement: Anthropic must allow long-context usage on that credential
-(typically API key billing, or OpenClaw's Claude-login path / legacy token auth
-with Extra Usage enabled). Otherwise Anthropic returns:
-`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
+Requirement: Anthropic must allow long-context usage on that credential.
 
 Note: Anthropic currently rejects `context-1m-*` beta requests when using
 legacy Anthropic token auth (`sk-ant-oat-*`). If you configure
@@ -213,38 +198,31 @@ legacy Anthropic token auth (`sk-ant-oat-*`). If you configure
 falls back to the standard context window by skipping the context1m beta
 header while keeping the required OAuth betas.
 
-## Removed: Claude CLI backend
+## Claude CLI backend
 
-The bundled Anthropic `claude-cli` backend was removed.
+The bundled Anthropic `claude-cli` backend is supported in OpenClaw.
 
-- Anthropic's April 4, 2026 notice says OpenClaw-driven Claude-login traffic is
-  third-party harness usage and requires **Extra Usage**.
-- Our local repros also show that direct
-  `claude -p --append-system-prompt ...` can hit the same guard when the
-  appended prompt identifies OpenClaw.
-- The same OpenClaw-like system prompt does not hit that guard on the
-  Anthropic SDK + `ANTHROPIC_API_KEY` path.
-- Use Anthropic API keys for Anthropic traffic in OpenClaw.
+- Anthropic staff told us this usage is allowed again.
+- OpenClaw therefore treats Claude CLI reuse and `claude -p` usage as
+  sanctioned for this integration unless Anthropic publishes a new policy.
+- Anthropic API keys remain the clearest production path for always-on gateway
+  hosts and explicit server-side billing control.
+- Setup and runtime details are in [/gateway/cli-backends](/gateway/cli-backends).
 
 ## Notes
 
 - Anthropic's public Claude Code docs still document direct CLI usage such as
-  `claude -p`, but Anthropic's separate notice to OpenClaw users says the
-  **OpenClaw** Claude-login path is third-party harness usage and requires
-  **Extra Usage** (pay-as-you-go billed separately from the subscription).
-  Our local repros also show that direct
-  `claude -p --append-system-prompt ...` can hit the same guard when the
-  appended prompt identifies OpenClaw, while the same prompt shape does not
-  reproduce on the Anthropic SDK + `ANTHROPIC_API_KEY` path. For production, we
-  recommend Anthropic API keys instead.
-- Anthropic setup-token is available again in OpenClaw as a legacy/manual path. Anthropic's OpenClaw-specific billing notice still applies, so use it with the expectation that Anthropic requires **Extra Usage** for this path.
+  `claude -p`, and Anthropic staff told us OpenClaw-style Claude CLI usage is
+  allowed again. We are treating that guidance as settled unless Anthropic
+  publishes a new policy change.
+- Anthropic setup-token remains available in OpenClaw as a supported token-auth path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
 - Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).
 
 ## Troubleshooting
 
 **401 errors / token suddenly invalid**
 
-- Legacy Anthropic token auth can expire or be revoked.
+- Anthropic token auth can expire or be revoked.
 - For new setup, migrate to an Anthropic API key.
 
 **No API key found for provider "anthropic"**

docs/providers/arcee.md

@@ -0,0 +1,87 @@
+---
+title: "Arcee AI"
+summary: "Arcee AI setup (auth + model selection)"
+read_when:
+  - You want to use Arcee AI with OpenClaw
+  - You need the API key env var or CLI auth choice
+---
+
+# Arcee AI
+
+[Arcee AI](https://arcee.ai) provides access to the Trinity family of mixture-of-experts models through an OpenAI-compatible API. All Trinity models are Apache 2.0 licensed.
+
+Arcee AI models can be accessed directly via the Arcee platform or through [OpenRouter](/providers/openrouter).
+
+- Provider: `arcee`
+- Auth: `ARCEEAI_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter)
+- API: OpenAI-compatible
+- Base URL: `https://api.arcee.ai/api/v1` (direct) or `https://openrouter.ai/api/v1` (OpenRouter)
+
+## Quick start
+
+1. Get an API key from [Arcee AI](https://chat.arcee.ai/) or [OpenRouter](https://openrouter.ai/keys).
+
+2. Set the API key (recommended: store it for the Gateway):
+
+```bash
+# Direct (Arcee platform)
+openclaw onboard --auth-choice arceeai-api-key
+
+# Via OpenRouter
+openclaw onboard --auth-choice arceeai-openrouter
+```
+
+3. Set a default model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "arcee/trinity-large-thinking" },
+    },
+  },
+}
+```
+
+## Non-interactive example
+
+```bash
+# Direct (Arcee platform)
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice arceeai-api-key \
+  --arceeai-api-key "$ARCEEAI_API_KEY"
+
+# Via OpenRouter
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice arceeai-openrouter \
+  --openrouter-api-key "$OPENROUTER_API_KEY"
+```
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure `ARCEEAI_API_KEY`
+(or `OPENROUTER_API_KEY`) is available to that process (for example, in
+`~/.openclaw/.env` or via `env.shellEnv`).
+
+## Built-in catalog
+
+OpenClaw currently ships this bundled Arcee catalog:
+
+| Model ref                      | Name                   | Input | Context | Cost (in/out per 1M) | Notes                                     |
+| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ----------------------------------------- |
+| `arcee/trinity-large-thinking` | Trinity Large Thinking | text  | 256K    | $0.25 / $0.90        | Default model; reasoning enabled          |
+| `arcee/trinity-large-preview`  | Trinity Large Preview  | text  | 128K    | $0.25 / $1.00        | General-purpose; 400B params, 13B active  |
+| `arcee/trinity-mini`           | Trinity Mini 26B       | text  | 128K    | $0.045 / $0.15       | Fast and cost-efficient; function calling |
+
+The same model refs work for both direct and OpenRouter setups (for example `arcee/trinity-large-thinking`).
+
+The onboarding preset sets `arcee/trinity-large-thinking` as the default model.
+
+## Supported features
+
+- Streaming
+- Tool use / function calling
+- Structured output (JSON mode and JSON schema)
+- Extended thinking (Trinity Large Thinking)

docs/providers/google.md

@@ -1,9 +1,9 @@
 ---
 title: "Google (Gemini)"
-summary: "Google Gemini setup (API key, image generation, media understanding, web search)"
+summary: "Google Gemini setup (API key + OAuth, image generation, media understanding, web search)"
 read_when:
   - You want to use Google Gemini models with OpenClaw
-  - You need the API key auth flow
+  - You need the API key or OAuth auth flow
 ---
 
 # Google (Gemini)
@@ -15,6 +15,7 @@ Gemini Grounding.
 - Provider: `google`
 - Auth: `GEMINI_API_KEY` or `GOOGLE_API_KEY`
 - API: Google Gemini API
+- Alternative provider: `google-gemini-cli` (OAuth)
 
 ## Quick start
 
@@ -45,6 +46,46 @@ openclaw onboard --non-interactive \
   --gemini-api-key "$GEMINI_API_KEY"
 ```
 
+## OAuth (Gemini CLI)
+
+An alternative provider `google-gemini-cli` uses PKCE OAuth instead of an API
+key. This is an unofficial integration; some users report account
+restrictions. Use at your own risk.
+
+- Default model: `google-gemini-cli/gemini-3.1-pro-preview`
+- Alias: `gemini-cli`
+- Install prerequisite: local Gemini CLI available as `gemini`
+  - Homebrew: `brew install gemini-cli`
+  - npm: `npm install -g @google/gemini-cli`
+- Login:
+
+```bash
+openclaw models auth login --provider google-gemini-cli --set-default
+```
+
+Environment variables:
+
+- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
+- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
+
+(Or the `GEMINI_CLI_*` variants.)
+
+If Gemini CLI OAuth requests fail after login, set
+`GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host and
+retry.
+
+If login fails before the browser flow starts, make sure the local `gemini`
+command is installed and on `PATH`. OpenClaw supports both Homebrew installs
+and global npm installs, including common Windows/npm layouts.
+
+Gemini CLI JSON usage notes:
+
+- Reply text comes from the CLI JSON `response` field.
+- Usage falls back to `stats` when the CLI leaves `usage` empty.
+- `stats.cached` is normalized into OpenClaw `cacheRead`.
+- If `stats.input` is missing, OpenClaw derives input tokens from
+  `stats.input_tokens - stats.cached`.
+
 ## Capabilities
 
 | Capability             | Supported         |
@@ -98,8 +139,9 @@ The bundled `google` image-generation provider defaults to
 - Edit mode: enabled, up to 5 input images
 - Geometry controls: `size`, `aspectRatio`, and `resolution`
 
-Image generation, media understanding, and Gemini Grounding all stay on the
-`google` provider id.
+The OAuth-only `google-gemini-cli` provider is a separate text-inference
+surface. Image generation, media understanding, and Gemini Grounding stay on
+the `google` provider id.
 
 To use Google as the default image provider:
 

docs/providers/index.md

@@ -29,6 +29,7 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugi
 - [Alibaba Model Studio](/providers/alibaba)
 - [Amazon Bedrock](/providers/bedrock)
 - [Anthropic (API + Claude CLI)](/providers/anthropic)
+- [Arcee AI (Trinity models)](/providers/arcee)
 - [BytePlus (International)](/concepts/model-providers#byteplus-international)
 - [Chutes](/providers/chutes)
 - [ComfyUI](/providers/comfy)

docs/providers/models.md

@@ -54,6 +54,7 @@ model as `provider/model`.
 
 - `anthropic-vertex` - implicit Anthropic on Google Vertex support when Vertex credentials are available; no separate onboarding auth choice
 - `copilot-proxy` - local VS Code Copilot Proxy bridge; use `openclaw onboard --auth-choice copilot-proxy`
+- `google-gemini-cli` - unofficial Gemini CLI OAuth flow; requires a local `gemini` install (`brew install gemini-cli` or `npm install -g @google/gemini-cli`); default model `google-gemini-cli/gemini-3.1-pro-preview`; use `openclaw onboard --auth-choice google-gemini-cli` or `openclaw models auth login --provider google-gemini-cli --set-default`
 
 For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
 see [Model providers](/concepts/model-providers).

docs/providers/openai.md

@@ -28,6 +28,7 @@ Config key:
 Allowed values:
 
 - `"friendly"`: default; enable the OpenAI-specific overlay.
+- `"on"`: alias for `"friendly"`.
 - `"off"`: disable the overlay and use the base OpenClaw prompt only.
 
 Scope:
@@ -77,11 +78,20 @@ You can also set it directly with the config CLI:
 openclaw config set plugins.entries.openai.config.personality off
 ```
 
+OpenClaw normalizes this setting case-insensitively at runtime, so values like
+`"Off"` still disable the friendly overlay.
+
 ## Option A: OpenAI API key (OpenAI Platform)
 
 **Best for:** direct API access and usage-based billing.
 Get your API key from the OpenAI dashboard.
 
+Route summary:
+
+- `openai/gpt-5.4` = direct OpenAI Platform API route
+- Requires `OPENAI_API_KEY` (or equivalent OpenAI provider config)
+- In OpenClaw, ChatGPT/Codex sign-in is routed through `openai-codex/*`, not `openai/*`
+
 ### CLI setup
 
 ```bash
@@ -172,6 +182,12 @@ parameters, provider selection, and failover behavior.
 **Best for:** using ChatGPT/Codex subscription access instead of an API key.
 Codex cloud requires ChatGPT sign-in, while the Codex CLI supports ChatGPT or API key sign-in.
 
+Route summary:
+
+- `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth route
+- Uses ChatGPT/Codex sign-in, not a direct OpenAI Platform API key
+- Provider-side limits for `openai-codex/*` can differ from the ChatGPT web/app experience
+
 ### CLI setup (Codex OAuth)
 
 ```bash
@@ -193,6 +209,10 @@ openclaw models auth login --provider openai-codex
 OpenAI's current Codex docs list `gpt-5.4` as the current Codex model. OpenClaw
 maps that to `openai-codex/gpt-5.4` for ChatGPT/Codex OAuth usage.
 
+This route is intentionally separate from `openai/gpt-5.4`. If you want the
+direct OpenAI Platform API path, use `openai/*` with an API key. If you want
+ChatGPT/Codex sign-in, use `openai-codex/*`.
+
 If onboarding reuses an existing Codex CLI login, those credentials stay
 managed by Codex CLI. On expiry, OpenClaw re-reads the external Codex source
 first and, when the provider can refresh it, writes the refreshed credential

docs/providers/vydra.md

@@ -85,8 +85,28 @@ Notes:
 
 - `vydra/veo3` is bundled as text-to-video only.
 - `vydra/kling` currently requires a remote image URL reference. Local file uploads are rejected up front.
+- Vydra's current `kling` HTTP route has been inconsistent about whether it requires `image_url` or `video_url`; the bundled provider maps the same remote image URL into both fields.
 - The bundled plugin stays conservative and does not forward undocumented style knobs such as aspect ratio, resolution, watermark, or generated audio.
 
+Provider-specific live coverage:
+
+```bash
+OPENCLAW_LIVE_TEST=1 \
+OPENCLAW_LIVE_VYDRA_VIDEO=1 \
+pnpm test:live -- extensions/vydra/vydra.live.test.ts
+```
+
+The bundled Vydra live file now covers:
+
+- `vydra/veo3` text-to-video
+- `vydra/kling` image-to-video using a remote image URL
+
+Override the remote image fixture when needed:
+
+```bash
+export OPENCLAW_LIVE_VYDRA_KLING_IMAGE_URL="https://example.com/reference.png"
+```
+
 See [Video Generation](/tools/video-generation) for shared tool behavior.
 
 ## Speech synthesis

docs/reference/api-usage-costs.md

@@ -31,13 +31,11 @@ OpenClaw features that can generate provider usage or paid API calls.
   `stats`, normalizes `stats.cached` into `cacheRead`, and derives input tokens
   from `stats.input_tokens - stats.cached` when needed.
 
-Anthropic note: Anthropic's public Claude Code docs still include direct Claude
-Code terminal usage in Claude plan limits. Separately, Anthropic told OpenClaw
-users that starting **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**, the
-**OpenClaw** Claude-login path counts as third-party harness usage and
-requires **Extra Usage** billed separately from the subscription. Anthropic
-does not expose a per-message dollar estimate that OpenClaw can show in
-`/usage full`.
+Anthropic note: Anthropic staff told us OpenClaw-style Claude CLI usage is
+allowed again, so OpenClaw treats Claude CLI reuse and `claude -p` usage as
+sanctioned for this integration unless Anthropic publishes a new policy.
+Anthropic still does not expose a per-message dollar estimate that OpenClaw can
+show in `/usage full`.
 
 **CLI usage windows (provider quotas)**
 

docs/reference/secretref-credential-surface.md

@@ -41,7 +41,6 @@ Scope intent:
 - `talk.providers.*.apiKey`
 - `messages.tts.providers.*.apiKey`
 - `tools.web.fetch.firecrawl.apiKey`
-- `plugins.entries.firecrawl.config.webFetch.apiKey`
 - `plugins.entries.brave.config.webSearch.apiKey`
 - `plugins.entries.google.config.webSearch.apiKey`
 - `plugins.entries.xai.config.webSearch.apiKey`

docs/reference/session-management-compaction.md

@@ -332,7 +332,7 @@ Notes:
 - The default prompt/system prompt include a `NO_REPLY` hint to suppress
   delivery.
 - The flush runs once per compaction cycle (tracked in `sessions.json`).
-- The flush runs only for embedded Pi sessions.
+- The flush runs only for embedded Pi sessions (CLI backends skip it).
 - The flush is skipped when the session workspace is read-only (`workspaceAccess: "ro"` or `"none"`).
 - See [Memory](/concepts/memory) for the workspace file layout and write patterns.
 

docs/reference/test.md

@@ -12,14 +12,19 @@ title: "Tests"
 - `pnpm test:force`: Kills any lingering gateway process holding the default control port, then runs the full Vitest suite with an isolated gateway port so server tests don’t collide with a running instance. Use this when a prior gateway run left port 18789 occupied.
 - `pnpm test:coverage`: Runs the unit suite with V8 coverage (via `vitest.unit.config.ts`). Global thresholds are 70% lines/branches/functions/statements. Coverage excludes integration-heavy entrypoints (CLI wiring, gateway/telegram bridges, webchat static server) to keep the target focused on unit-testable logic.
 - `pnpm test:coverage:changed`: Runs unit coverage only for files changed since `origin/main`.
-- `pnpm test:changed`: runs the native Vitest projects config with `--changed origin/main`. The base config treats the projects/config files as `forceRerunTriggers` so wiring changes still rerun broadly when needed.
-- `pnpm test`: runs the native Vitest root projects config directly. File filters work natively across the configured projects.
+- `pnpm test:changed`: expands changed git paths into scoped Vitest lanes when the diff only touches routable source/test files. Config/setup changes still fall back to the native root projects run so wiring edits rerun broadly when needed.
+- `pnpm test`: routes explicit file/directory targets through scoped Vitest lanes. Untargeted runs now execute eight sequential shard configs (`vitest.full-core-unit-src.config.ts`, `vitest.full-core-unit-security.config.ts`, `vitest.full-core-unit-support.config.ts`, `vitest.full-core-contracts.config.ts`, `vitest.full-core-runtime.config.ts`, `vitest.full-agentic.config.ts`, `vitest.full-auto-reply.config.ts`, `vitest.full-extensions.config.ts`) instead of one giant root-project process.
+- Selected `plugin-sdk` and `commands` test files now route through dedicated light lanes that keep only `test/setup.ts`, leaving runtime-heavy cases on their existing lanes.
+- Selected `plugin-sdk` and `commands` helper source files also map `pnpm test:changed` to explicit sibling tests in those light lanes, so small helper edits avoid rerunning the heavy runtime-backed suites.
+- `auto-reply` now also splits into three dedicated configs (`core`, `top-level`, `reply`) so the reply harness does not dominate the lighter top-level status/token/helper tests.
 - Base Vitest config now defaults to `pool: "threads"` and `isolate: false`, with the shared non-isolated runner enabled across the repo configs.
 - `pnpm test:channels` runs `vitest.channels.config.ts`.
 - `pnpm test:extensions` runs `vitest.extensions.config.ts`.
 - `pnpm test:extensions`: runs extension/plugin suites.
-- `pnpm test:perf:imports`: enables Vitest import-duration + import-breakdown reporting for the native root projects run.
+- `pnpm test:perf:imports`: enables Vitest import-duration + import-breakdown reporting, while still using scoped lane routing for explicit file/directory targets.
 - `pnpm test:perf:imports:changed`: same import profiling, but only for files changed since `origin/main`.
+- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarks the routed changed-mode path against the native root-project run for the same committed git diff.
+- `pnpm test:perf:changed:bench -- --worktree` benchmarks the current worktree change set without committing first.
 - `pnpm test:perf:profile:main`: writes a CPU profile for the Vitest main thread (`.artifacts/vitest-main-profile`).
 - `pnpm test:perf:profile:runner`: writes CPU + heap profiles for the unit runner (`.artifacts/vitest-runner-profile`).
 - Gateway integration: opt-in via `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` or `pnpm test:gateway`.

docs/reference/token-use.md

@@ -177,10 +177,8 @@ This maps to Anthropic's `context-1m-2025-08-07` beta header.
 
 This only applies when `context1m: true` is set on that model entry.
 
-Requirement: the credential must be eligible for long-context usage (API key
-billing, or OpenClaw's Claude-login path with Extra Usage enabled). If not,
-Anthropic responds
-with `HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
+Requirement: the credential must be eligible for long-context usage. If not,
+Anthropic responds with a provider-side rate limit error for that request.
 
 If you authenticate Anthropic with OAuth/subscription tokens (`sk-ant-oat-*`),
 OpenClaw skips the `context-1m-*` beta header because Anthropic currently

docs/reference/wizard.md

@@ -32,7 +32,7 @@ For a high-level overview, see [Onboarding (CLI)](/start/wizard).
   <Step title="Model/Auth">
     - **Anthropic API key**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
     - **Anthropic API key**: preferred Anthropic assistant choice in onboarding/configure.
-    - **Anthropic setup-token (legacy/manual)**: available again in onboarding/configure, but Anthropic told OpenClaw users that the OpenClaw Claude-login path counts as third-party harness usage and requires **Extra Usage** on the Claude account.
+    - **Anthropic setup-token**: still available in onboarding/configure, though OpenClaw now prefers Claude CLI reuse when available.
     - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, onboarding can reuse it. Reused Codex CLI credentials stay managed by Codex CLI; on expiry OpenClaw re-reads that source first and, when the provider can refresh it, writes the refreshed credential back to Codex storage instead of taking ownership itself.
     - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
       - Sets `agents.defaults.model` to `openai-codex/gpt-5.4` when model is unset or `openai/*`.

docs/start/wizard-cli-automation.md

@@ -192,10 +192,8 @@ openclaw onboard --non-interactive \
   </Accordion>
 </AccordionGroup>
 
-Anthropic setup-token is available again as a legacy/manual onboarding path.
-Use it with the expectation that Anthropic told OpenClaw users the OpenClaw
-Claude-login path requires **Extra Usage**. For production, prefer an
-Anthropic API key.
+Anthropic setup-token remains available as a supported onboarding token path, but OpenClaw now prefers Claude CLI reuse when available.
+For production, prefer an Anthropic API key.
 
 ## Add another agent
 

docs/start/wizard.md

@@ -72,7 +72,7 @@ Onboarding starts with **QuickStart** (defaults) vs **Advanced** (full control).
    For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
    In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
    In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref (`file` or `exec`), with a fast preflight validation before saving.
-   For Anthropic, interactive onboarding/configure offers **Anthropic Claude CLI** as a local fallback and **Anthropic API key** as the recommended production path. Anthropic setup-token is also available again as a legacy/manual OpenClaw path, with Anthropic's OpenClaw-specific **Extra Usage** billing expectation.
+   For Anthropic, interactive onboarding/configure offers **Anthropic Claude CLI** as the preferred local path and **Anthropic API key** as the recommended production path. Anthropic setup-token also remains available as a supported token-auth path.
 2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files.
 3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
    In interactive token mode, choose default plaintext token storage or opt into SecretRef.

docs/tools/acp-agents.md

@@ -23,10 +23,11 @@ instead of ACP.
 
 There are three nearby surfaces that are easy to confuse:
 
-| You want to...                                                                     | Use this                   | Notes                                                                                                       |
-| ---------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Run Codex, Claude Code, Gemini CLI, or another external harness _through_ OpenClaw | This page: ACP agents      | Chat-bound sessions, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, background tasks, runtime controls |
-| Expose an OpenClaw Gateway session _as_ an ACP server for an editor or client      | [`openclaw acp`](/cli/acp) | Bridge mode. IDE/client talks ACP to OpenClaw over stdio/WebSocket                                          |
+| You want to...                                                                     | Use this                              | Notes                                                                                                       |
+| ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Run Codex, Claude Code, Gemini CLI, or another external harness _through_ OpenClaw | This page: ACP agents                 | Chat-bound sessions, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, background tasks, runtime controls |
+| Expose an OpenClaw Gateway session _as_ an ACP server for an editor or client      | [`openclaw acp`](/cli/acp)            | Bridge mode. IDE/client talks ACP to OpenClaw over stdio/WebSocket                                          |
+| Reuse a local AI CLI as a text-only fallback model                                 | [CLI Backends](/gateway/cli-backends) | Not ACP. No OpenClaw tools, no ACP controls, no harness runtime                                             |
 
 ## Does this work out of the box?
 
@@ -111,9 +112,12 @@ For Claude Code through ACP, the stack is:
 Important distinction:
 
 - ACP Claude is a harness session with ACP controls, session resume, background-task tracking, and optional conversation/thread binding.
-  For operators, the practical rule is:
+- CLI backends are separate text-only local fallback runtimes. See [CLI Backends](/gateway/cli-backends).
+
+For operators, the practical rule is:
 
 - want `/acp spawn`, bindable sessions, runtime controls, or persistent harness work: use ACP
+- want simple local text fallback through the raw CLI: use CLI backends
 
 ## Bound sessions
 

docs/tools/media-overview.md

@@ -0,0 +1,60 @@
+---
+summary: "Unified landing page for media generation, understanding, and speech capabilities"
+read_when:
+  - Looking for an overview of media capabilities
+  - Deciding which media provider to configure
+  - Understanding how async media generation works
+title: "Media Overview"
+---
+
+# Media Generation and Understanding
+
+OpenClaw generates images, videos, and music, understands inbound media (images, audio, video), and speaks replies aloud with text-to-speech. All media capabilities are tool-driven: the agent decides when to use them based on the conversation, and each tool only appears when at least one backing provider is configured.
+
+## Capabilities at a glance
+
+| Capability           | Tool             | Providers                                                                                    | What it does                                            |
+| -------------------- | ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Image generation     | `image_generate` | ComfyUI, fal, Google, MiniMax, OpenAI, Vydra                                                 | Creates or edits images from text prompts or references |
+| Video generation     | `video_generate` | Alibaba, BytePlus, ComfyUI, fal, Google, MiniMax, OpenAI, Qwen, Runway, Together, Vydra, xAI | Creates videos from text, images, or existing videos    |
+| Music generation     | `music_generate` | ComfyUI, Google, MiniMax                                                                     | Creates music or audio tracks from text prompts         |
+| Text-to-speech (TTS) | `tts`            | ElevenLabs, Microsoft, MiniMax, OpenAI                                                       | Converts outbound replies to spoken audio               |
+| Media understanding  | (automatic)      | Any vision/audio-capable model provider, plus CLI fallbacks                                  | Summarizes inbound images, audio, and video             |
+
+## Provider capability matrix
+
+This table shows which providers support which media capabilities across the platform.
+
+| Provider   | Image | Video | Music | TTS | STT / Transcription | Media Understanding |
+| ---------- | ----- | ----- | ----- | --- | ------------------- | ------------------- |
+| Alibaba    |       | Yes   |       |     |                     |                     |
+| BytePlus   |       | Yes   |       |     |                     |                     |
+| ComfyUI    | Yes   | Yes   | Yes   |     |                     |                     |
+| Deepgram   |       |       |       |     | Yes                 |                     |
+| ElevenLabs |       |       |       | Yes |                     |                     |
+| fal        | Yes   | Yes   |       |     |                     |                     |
+| Google     | Yes   | Yes   | Yes   |     |                     | Yes                 |
+| Microsoft  |       |       |       | Yes |                     |                     |
+| MiniMax    | Yes   | Yes   | Yes   | Yes |                     |                     |
+| OpenAI     | Yes   | Yes   |       | Yes | Yes                 | Yes                 |
+| Qwen       |       | Yes   |       |     |                     |                     |
+| Runway     |       | Yes   |       |     |                     |                     |
+| Together   |       | Yes   |       |     |                     |                     |
+| Vydra      | Yes   | Yes   |       |     |                     |                     |
+| xAI        |       | Yes   |       |     |                     |                     |
+
+<Note>
+Media understanding uses any vision-capable or audio-capable model registered in your provider config. The table above highlights providers with dedicated media-understanding support; most LLM providers with multimodal models (Anthropic, Google, OpenAI, etc.) can also understand inbound media when configured as the active reply model.
+</Note>
+
+## How async generation works
+
+Video and music generation run as background tasks because provider processing typically takes 30 seconds to several minutes. When the agent calls `video_generate` or `music_generate`, OpenClaw submits the request to the provider, returns a task ID immediately, and tracks the job in the task ledger. The agent continues responding to other messages while the job runs. When the provider finishes, OpenClaw wakes the agent so it can post the finished media back into the original channel. Image generation and TTS are synchronous and complete inline with the reply.
+
+## Quick links
+
+- [Image Generation](/tools/image-generation) -- generating and editing images
+- [Video Generation](/tools/video-generation) -- text-to-video, image-to-video, and video-to-video
+- [Music Generation](/tools/music-generation) -- creating music and audio tracks
+- [Text-to-Speech](/tools/tts) -- converting replies to spoken audio
+- [Media Understanding](/nodes/media-understanding) -- understanding inbound images, audio, and video

docs/tools/music-generation.md

@@ -85,6 +85,17 @@ Example:
 | Google   | `lyria-3-clip-preview` | Up to 10 images  | `lyrics`, `instrumental`, `format`                        | `GEMINI_API_KEY`, `GOOGLE_API_KEY`     |
 | MiniMax  | `music-2.5+`           | None             | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY`                      |
 
+### Declared capability matrix
+
+This is the explicit mode contract used by `music_generate`, contract tests,
+and the shared live sweep.
+
+| Provider | `generate` | `edit` | Edit limit | Shared live lanes                                                         |
+| -------- | ---------- | ------ | ---------- | ------------------------------------------------------------------------- |
+| ComfyUI  | Yes        | Yes    | 1 image    | Not in the shared sweep; covered by `extensions/comfy/comfy.live.test.ts` |
+| Google   | Yes        | Yes    | 10 images  | `generate`, `edit`                                                        |
+| MiniMax  | Yes        | No     | None       | `generate`                                                                |
+
 Use `action: "list"` to inspect available shared providers and models at
 runtime:
 
@@ -133,6 +144,25 @@ ignored with a warning when the selected provider or model cannot honor them.
 - Prompt hint: later user/manual turns in the same session get a small runtime hint when a music task is already in flight so the model does not blindly call `music_generate` again.
 - No-session fallback: direct/local contexts without a real agent session still run inline and return the final audio result in the same turn.
 
+### Task lifecycle
+
+Each `music_generate` request moves through four states:
+
+1. **queued** -- task created, waiting for the provider to accept it.
+2. **running** -- provider is processing (typically 30 seconds to 3 minutes depending on provider and duration).
+3. **succeeded** -- track ready; the agent wakes and posts it to the conversation.
+4. **failed** -- provider error or timeout; the agent wakes with error details.
+
+Check status from the CLI:
+
+```bash
+openclaw tasks list
+openclaw tasks show <taskId>
+openclaw tasks cancel <taskId>
+```
+
+Duplicate prevention: if a music task is already `queued` or `running` for the current session, `music_generate` returns the existing task status instead of starting a new one. Use `action: "status"` to check explicitly without triggering a new generation.
+
 ## Configuration
 
 ### Model selection
@@ -174,6 +204,36 @@ error includes details from each attempt.
 - ComfyUI support is workflow-driven and depends on the configured graph plus
   node mapping for prompt/output fields.
 
+## Provider capability modes
+
+The shared music-generation contract now supports explicit mode declarations:
+
+- `generate` for prompt-only generation
+- `edit` when the request includes one or more reference images
+
+New provider implementations should prefer explicit mode blocks:
+
+```typescript
+capabilities: {
+  generate: {
+    maxTracks: 1,
+    supportsLyrics: true,
+    supportsFormat: true,
+  },
+  edit: {
+    enabled: true,
+    maxTracks: 1,
+    maxInputImages: 1,
+    supportsFormat: true,
+  },
+}
+```
+
+Legacy flat fields such as `maxInputImages`, `supportsLyrics`, and
+`supportsFormat` are not enough to advertise edit support. Providers should
+declare `generate` and `edit` explicitly so live tests, contract tests, and
+the shared `music_generate` tool can validate mode support deterministically.
+
 ## Choosing the right path
 
 - Use the shared provider-backed path when you want model selection, provider failover, and the built-in async task/status flow.
@@ -188,6 +248,22 @@ Opt-in live coverage for the shared bundled providers:
 OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
 ```
 
+Repo wrapper:
+
+```bash
+pnpm test:live:media music
+```
+
+This live file loads missing provider env vars from `~/.profile`, prefers
+live/env API keys ahead of stored auth profiles by default, and runs both
+`generate` and declared `edit` coverage when the provider enables edit mode.
+
+Today that means:
+
+- `google`: `generate` plus `edit`
+- `minimax`: `generate` only
+- `comfy`: separate Comfy live coverage, not the shared provider sweep
+
 Opt-in live coverage for the bundled ComfyUI music path:
 
 ```bash

docs/tools/video-generation.md

@@ -15,6 +15,15 @@ OpenClaw agents can generate videos from text prompts, reference images, or exis
 The `video_generate` tool only appears when at least one video-generation provider is available. If you do not see it in your agent tools, set a provider API key or configure `agents.defaults.videoGenerationModel`.
 </Note>
 
+OpenClaw treats video generation as three runtime modes:
+
+- `generate` for text-to-video requests with no reference media
+- `imageToVideo` when the request includes one or more reference images
+- `videoToVideo` when the request includes one or more reference videos
+
+Providers can support any subset of those modes. The tool validates the active
+mode before submission and reports supported modes in `action=list`.
+
 ## Quick start
 
 1. Set an API key for any supported provider:
@@ -48,6 +57,25 @@ While a job is in flight, duplicate `video_generate` calls in the same session r
 
 Outside of session-backed agent runs (for example, direct tool invocations), the tool falls back to inline generation and returns the final media path in the same turn.
 
+### Task lifecycle
+
+Each `video_generate` request moves through four states:
+
+1. **queued** -- task created, waiting for the provider to accept it.
+2. **running** -- provider is processing (typically 30 seconds to 5 minutes depending on provider and resolution).
+3. **succeeded** -- video ready; the agent wakes and posts it to the conversation.
+4. **failed** -- provider error or timeout; the agent wakes with error details.
+
+Check status from the CLI:
+
+```bash
+openclaw tasks list
+openclaw tasks show <taskId>
+openclaw tasks cancel <taskId>
+```
+
+Duplicate prevention: if a video task is already `queued` or `running` for the current session, `video_generate` returns the existing task status instead of starting a new one. Use `action: "status"` to check explicitly without triggering a new generation.
+
 ## Supported providers
 
 | Provider | Default model                   | Text | Image ref         | Video ref        | API key                                  |
@@ -67,7 +95,28 @@ Outside of session-backed agent runs (for example, direct tool invocations), the
 
 Some providers accept additional or alternate API key env vars. See individual [provider pages](#related) for details.
 
-Run `video_generate action=list` to inspect available providers and models at runtime.
+Run `video_generate action=list` to inspect available providers, models, and
+runtime modes at runtime.
+
+### Declared capability matrix
+
+This is the explicit mode contract used by `video_generate`, contract tests,
+and the shared live sweep.
+
+| Provider | `generate` | `imageToVideo` | `videoToVideo` | Shared live lanes today                                                                                                                  |
+| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Alibaba  | Yes        | Yes            | Yes            | `generate`, `imageToVideo`; `videoToVideo` skipped because this provider needs remote `http(s)` video URLs                               |
+| BytePlus | Yes        | Yes            | No             | `generate`, `imageToVideo`                                                                                                               |
+| ComfyUI  | Yes        | Yes            | No             | Not in the shared sweep; workflow-specific coverage lives with Comfy tests                                                               |
+| fal      | Yes        | Yes            | No             | `generate`, `imageToVideo`                                                                                                               |
+| Google   | Yes        | Yes            | Yes            | `generate`, `imageToVideo`; shared `videoToVideo` skipped because the current buffer-backed Gemini/Veo sweep does not accept that input  |
+| MiniMax  | Yes        | Yes            | No             | `generate`, `imageToVideo`                                                                                                               |
+| OpenAI   | Yes        | Yes            | Yes            | `generate`, `imageToVideo`; shared `videoToVideo` skipped because this org/input path currently needs provider-side inpaint/remix access |
+| Qwen     | Yes        | Yes            | Yes            | `generate`, `imageToVideo`; `videoToVideo` skipped because this provider needs remote `http(s)` video URLs                               |
+| Runway   | Yes        | Yes            | Yes            | `generate`, `imageToVideo`; `videoToVideo` runs only when the selected model is `runway/gen4_aleph`                                      |
+| Together | Yes        | Yes            | No             | `generate`, `imageToVideo`                                                                                                               |
+| Vydra    | Yes        | Yes            | No             | `generate`; shared `imageToVideo` skipped because bundled `veo3` is text-only and bundled `kling` requires a remote image URL            |
+| xAI      | Yes        | Yes            | Yes            | `generate`, `imageToVideo`; `videoToVideo` skipped because this provider currently needs a remote MP4 URL                                |
 
 ## Tool parameters
 
@@ -91,7 +140,7 @@ Run `video_generate action=list` to inspect available providers and models at ru
 | Parameter         | Type    | Description                                                              |
 | ----------------- | ------- | ------------------------------------------------------------------------ |
 | `aspectRatio`     | string  | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`  |
-| `resolution`      | string  | `480P`, `720P`, or `1080P`                                               |
+| `resolution`      | string  | `480P`, `720P`, `768P`, or `1080P`                                       |
 | `durationSeconds` | number  | Target duration in seconds (rounded to nearest provider-supported value) |
 | `size`            | string  | Size hint when the provider supports it                                  |
 | `audio`           | boolean | Enable generated audio when supported                                    |
@@ -107,6 +156,15 @@ Run `video_generate action=list` to inspect available providers and models at ru
 
 Not all providers support all parameters. Unsupported overrides are ignored on a best-effort basis and reported as warnings in the tool result. Hard capability limits (such as too many reference inputs) fail before submission.
 
+Reference inputs also select the runtime mode:
+
+- No reference media: `generate`
+- Any image reference: `imageToVideo`
+- Any video reference: `videoToVideo`
+
+Mixed image and video references are not a stable shared capability surface.
+Prefer one reference type per request.
+
 ## Actions
 
 - **generate** (default) -- create a video from the given prompt and optional reference inputs.
@@ -154,6 +212,67 @@ If a provider fails, the next candidate is tried automatically. If all candidate
 | Vydra    | Uses `https://www.vydra.ai/api/v1` directly to avoid auth-dropping redirects. `veo3` is bundled as text-to-video only; `kling` requires a remote image URL. |
 | xAI      | Supports text-to-video, image-to-video, and remote video edit/extend flows.                                                                                 |
 
+## Provider capability modes
+
+The shared video-generation contract now lets providers declare mode-specific
+capabilities instead of only flat aggregate limits. New provider
+implementations should prefer explicit mode blocks:
+
+```typescript
+capabilities: {
+  generate: {
+    maxVideos: 1,
+    maxDurationSeconds: 10,
+    supportsResolution: true,
+  },
+  imageToVideo: {
+    enabled: true,
+    maxVideos: 1,
+    maxInputImages: 1,
+    maxDurationSeconds: 5,
+  },
+  videoToVideo: {
+    enabled: true,
+    maxVideos: 1,
+    maxInputVideos: 1,
+    maxDurationSeconds: 5,
+  },
+}
+```
+
+Flat aggregate fields such as `maxInputImages` and `maxInputVideos` are not
+enough to advertise transform-mode support. Providers should declare
+`generate`, `imageToVideo`, and `videoToVideo` explicitly so live tests,
+contract tests, and the shared `video_generate` tool can validate mode support
+deterministically.
+
+## Live tests
+
+Opt-in live coverage for the shared bundled providers:
+
+```bash
+OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
+```
+
+Repo wrapper:
+
+```bash
+pnpm test:live:media video
+```
+
+This live file loads missing provider env vars from `~/.profile`, prefers
+live/env API keys ahead of stored auth profiles by default, and runs the
+declared modes it can exercise safely with local media:
+
+- `generate` for every provider in the sweep
+- `imageToVideo` when `capabilities.imageToVideo.enabled`
+- `videoToVideo` when `capabilities.videoToVideo.enabled` and the provider/model
+  accepts buffer-backed local video input in the shared sweep
+
+Today the shared `videoToVideo` live lane covers:
+
+- `runway` only when you select `runway/gen4_aleph`
+
 ## Configuration
 
 Set the default video generation model in your OpenClaw config:

docs/tts.md

@@ -1,452 +1,6 @@
 ---
-summary: "Text-to-speech (TTS) for outbound replies"
-read_when:
-  - Enabling text-to-speech for replies
-  - Configuring TTS providers or limits
-  - Using /tts commands
-title: "Text-to-Speech (legacy path)"
+title: "Text-to-Speech"
+redirect: /tools/tts
 ---
 
-# Text-to-speech (TTS)
-
-OpenClaw can convert outbound replies into audio using ElevenLabs, Microsoft, MiniMax, or OpenAI.
-It works anywhere OpenClaw can send audio.
-
-## Supported services
-
-- **ElevenLabs** (primary or fallback provider)
-- **Microsoft** (primary or fallback provider; current bundled implementation uses `node-edge-tts`)
-- **MiniMax** (primary or fallback provider; uses the T2A v2 API)
-- **OpenAI** (primary or fallback provider; also used for summaries)
-
-### Microsoft speech notes
-
-The bundled Microsoft speech provider currently uses Microsoft Edge's online
-neural TTS service via the `node-edge-tts` library. It's a hosted service (not
-local), uses Microsoft endpoints, and does not require an API key.
-`node-edge-tts` exposes speech configuration options and output formats, but
-not all options are supported by the service. Legacy config and directive input
-using `edge` still works and is normalized to `microsoft`.
-
-Because this path is a public web service without a published SLA or quota,
-treat it as best-effort. If you need guaranteed limits and support, use OpenAI
-or ElevenLabs.
-
-## Optional keys
-
-If you want OpenAI, ElevenLabs, or MiniMax:
-
-- `ELEVENLABS_API_KEY` (or `XI_API_KEY`)
-- `MINIMAX_API_KEY`
-- `OPENAI_API_KEY`
-
-Microsoft speech does **not** require an API key.
-
-If multiple providers are configured, the selected provider is used first and the others are fallback options.
-Auto-summary uses the configured `summaryModel` (or `agents.defaults.model.primary`),
-so that provider must also be authenticated if you enable summaries.
-
-## Service links
-
-- [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech)
-- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio)
-- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech)
-- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication)
-- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2)
-- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
-- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
-
-## Is it enabled by default?
-
-No. Auto‑TTS is **off** by default. Enable it in config with
-`messages.tts.auto` or per session with `/tts always` (alias: `/tts on`).
-
-When `messages.tts.provider` is unset, OpenClaw picks the first configured
-speech provider in registry auto-select order.
-
-## Config
-
-TTS config lives under `messages.tts` in `openclaw.json`.
-Full schema is in [Gateway configuration](/gateway/configuration).
-
-### Minimal config (enable + provider)
-
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-      provider: "elevenlabs",
-    },
-  },
-}
-```
-
-### OpenAI primary with ElevenLabs fallback
-
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-      provider: "openai",
-      summaryModel: "openai/gpt-4.1-mini",
-      modelOverrides: {
-        enabled: true,
-      },
-      providers: {
-        openai: {
-          apiKey: "openai_api_key",
-          baseUrl: "https://api.openai.com/v1",
-          model: "gpt-4o-mini-tts",
-          voice: "alloy",
-        },
-        elevenlabs: {
-          apiKey: "elevenlabs_api_key",
-          baseUrl: "https://api.elevenlabs.io",
-          voiceId: "voice_id",
-          modelId: "eleven_multilingual_v2",
-          seed: 42,
-          applyTextNormalization: "auto",
-          languageCode: "en",
-          voiceSettings: {
-            stability: 0.5,
-            similarityBoost: 0.75,
-            style: 0.0,
-            useSpeakerBoost: true,
-            speed: 1.0,
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-### Microsoft primary (no API key)
-
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-      provider: "microsoft",
-      providers: {
-        microsoft: {
-          enabled: true,
-          voice: "en-US-MichelleNeural",
-          lang: "en-US",
-          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
-          rate: "+10%",
-          pitch: "-5%",
-        },
-      },
-    },
-  },
-}
-```
-
-### MiniMax primary
-
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-      provider: "minimax",
-      providers: {
-        minimax: {
-          apiKey: "minimax_api_key",
-          baseUrl: "https://api.minimax.io",
-          model: "speech-2.8-hd",
-          voiceId: "English_expressive_narrator",
-          speed: 1.0,
-          vol: 1.0,
-          pitch: 0,
-        },
-      },
-    },
-  },
-}
-```
-
-### Disable Microsoft speech
-
-```json5
-{
-  messages: {
-    tts: {
-      providers: {
-        microsoft: {
-          enabled: false,
-        },
-      },
-    },
-  },
-}
-```
-
-### Custom limits + prefs path
-
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-      maxTextLength: 4000,
-      timeoutMs: 30000,
-      prefsPath: "~/.openclaw/settings/tts.json",
-    },
-  },
-}
-```
-
-### Only reply with audio after an inbound voice message
-
-```json5
-{
-  messages: {
-    tts: {
-      auto: "inbound",
-    },
-  },
-}
-```
-
-### Disable auto-summary for long replies
-
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-    },
-  },
-}
-```
-
-Then run:
-
-```
-/tts summary off
-```
-
-### Notes on fields
-
-- `auto`: auto‑TTS mode (`off`, `always`, `inbound`, `tagged`).
-  - `inbound` only sends audio after an inbound voice message.
-  - `tagged` only sends audio when the reply includes `[[tts]]` tags.
-- `enabled`: legacy toggle (doctor migrates this to `auto`).
-- `mode`: `"final"` (default) or `"all"` (includes tool/block replies).
-- `provider`: speech provider id such as `"elevenlabs"`, `"microsoft"`, `"minimax"`, or `"openai"` (fallback is automatic).
-- If `provider` is **unset**, OpenClaw uses the first configured speech provider in registry auto-select order.
-- Legacy `provider: "edge"` still works and is normalized to `microsoft`.
-- `summaryModel`: optional cheap model for auto-summary; defaults to `agents.defaults.model.primary`.
-  - Accepts `provider/model` or a configured model alias.
-- `modelOverrides`: allow the model to emit TTS directives (on by default).
-  - `allowProvider` defaults to `false` (provider switching is opt-in).
-- `providers.<id>`: provider-owned settings keyed by speech provider id.
-- Legacy direct provider blocks (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) are auto-migrated to `messages.tts.providers.<id>` on load.
-- `maxTextLength`: hard cap for TTS input (chars). `/tts audio` fails if exceeded.
-- `timeoutMs`: request timeout (ms).
-- `prefsPath`: override the local prefs JSON path (provider/limit/summary).
-- `apiKey` values fall back to env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`).
-- `providers.elevenlabs.baseUrl`: override ElevenLabs API base URL.
-- `providers.openai.baseUrl`: override the OpenAI TTS endpoint.
-  - Resolution order: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1`
-  - Non-default values are treated as OpenAI-compatible TTS endpoints, so custom model and voice names are accepted.
-- `providers.elevenlabs.voiceSettings`:
-  - `stability`, `similarityBoost`, `style`: `0..1`
-  - `useSpeakerBoost`: `true|false`
-  - `speed`: `0.5..2.0` (1.0 = normal)
-- `providers.elevenlabs.applyTextNormalization`: `auto|on|off`
-- `providers.elevenlabs.languageCode`: 2-letter ISO 639-1 (e.g. `en`, `de`)
-- `providers.elevenlabs.seed`: integer `0..4294967295` (best-effort determinism)
-- `providers.minimax.baseUrl`: override MiniMax API base URL (default `https://api.minimax.io`, env: `MINIMAX_API_HOST`).
-- `providers.minimax.model`: TTS model (default `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`).
-- `providers.minimax.voiceId`: voice identifier (default `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`).
-- `providers.minimax.speed`: playback speed `0.5..2.0` (default 1.0).
-- `providers.minimax.vol`: volume `(0, 10]` (default 1.0; must be greater than 0).
-- `providers.minimax.pitch`: pitch shift `-12..12` (default 0).
-- `providers.microsoft.enabled`: allow Microsoft speech usage (default `true`; no API key).
-- `providers.microsoft.voice`: Microsoft neural voice name (e.g. `en-US-MichelleNeural`).
-- `providers.microsoft.lang`: language code (e.g. `en-US`).
-- `providers.microsoft.outputFormat`: Microsoft output format (e.g. `audio-24khz-48kbitrate-mono-mp3`).
-  - See Microsoft Speech output formats for valid values; not all formats are supported by the bundled Edge-backed transport.
-- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: percent strings (e.g. `+10%`, `-5%`).
-- `providers.microsoft.saveSubtitles`: write JSON subtitles alongside the audio file.
-- `providers.microsoft.proxy`: proxy URL for Microsoft speech requests.
-- `providers.microsoft.timeoutMs`: request timeout override (ms).
-- `edge.*`: legacy alias for the same Microsoft settings.
-
-## Model-driven overrides (default on)
-
-By default, the model **can** emit TTS directives for a single reply.
-When `messages.tts.auto` is `tagged`, these directives are required to trigger audio.
-
-When enabled, the model can emit `[[tts:...]]` directives to override the voice
-for a single reply, plus an optional `[[tts:text]]...[[/tts:text]]` block to
-provide expressive tags (laughter, singing cues, etc) that should only appear in
-the audio.
-
-`provider=...` directives are ignored unless `modelOverrides.allowProvider: true`.
-
-Example reply payload:
-
-```
-Here you go.
-
-[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
-[[tts:text]](laughs) Read the song once more.[[/tts:text]]
-```
-
-Available directive keys (when enabled):
-
-- `provider` (registered speech provider id, for example `openai`, `elevenlabs`, `minimax`, or `microsoft`; requires `allowProvider: true`)
-- `voice` (OpenAI voice) or `voiceId` (ElevenLabs / MiniMax)
-- `model` (OpenAI TTS model, ElevenLabs model id, or MiniMax model)
-- `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`
-- `vol` / `volume` (MiniMax volume, 0-10)
-- `pitch` (MiniMax pitch, -12 to 12)
-- `applyTextNormalization` (`auto|on|off`)
-- `languageCode` (ISO 639-1)
-- `seed`
-
-Disable all model overrides:
-
-```json5
-{
-  messages: {
-    tts: {
-      modelOverrides: {
-        enabled: false,
-      },
-    },
-  },
-}
-```
-
-Optional allowlist (enable provider switching while keeping other knobs configurable):
-
-```json5
-{
-  messages: {
-    tts: {
-      modelOverrides: {
-        enabled: true,
-        allowProvider: true,
-        allowSeed: false,
-      },
-    },
-  },
-}
-```
-
-## Per-user preferences
-
-Slash commands write local overrides to `prefsPath` (default:
-`~/.openclaw/settings/tts.json`, override with `OPENCLAW_TTS_PREFS` or
-`messages.tts.prefsPath`).
-
-Stored fields:
-
-- `enabled`
-- `provider`
-- `maxLength` (summary threshold; default 1500 chars)
-- `summarize` (default `true`)
-
-These override `messages.tts.*` for that host.
-
-## Output formats (fixed)
-
-- **Feishu / Matrix / Telegram / WhatsApp**: Opus voice message (`opus_48000_64` from ElevenLabs, `opus` from OpenAI).
-  - 48kHz / 64kbps is a good voice message tradeoff.
-- **Other channels**: MP3 (`mp3_44100_128` from ElevenLabs, `mp3` from OpenAI).
-  - 44.1kHz / 128kbps is the default balance for speech clarity.
-- **MiniMax**: MP3 (`speech-2.8-hd` model, 32kHz sample rate). Voice-note format not natively supported; use OpenAI or ElevenLabs for guaranteed Opus voice messages.
-- **Microsoft**: uses `microsoft.outputFormat` (default `audio-24khz-48kbitrate-mono-mp3`).
-  - The bundled transport accepts an `outputFormat`, but not all formats are available from the service.
-  - Output format values follow Microsoft Speech output formats (including Ogg/WebM Opus).
-  - Telegram `sendVoice` accepts OGG/MP3/M4A; use OpenAI/ElevenLabs if you need
-    guaranteed Opus voice messages.
-  - If the configured Microsoft output format fails, OpenClaw retries with MP3.
-
-OpenAI/ElevenLabs output formats are fixed per channel (see above).
-
-## Auto-TTS behavior
-
-When enabled, OpenClaw:
-
-- skips TTS if the reply already contains media or a `MEDIA:` directive.
-- skips very short replies (< 10 chars).
-- summarizes long replies when enabled using `agents.defaults.model.primary` (or `summaryModel`).
-- attaches the generated audio to the reply.
-
-If the reply exceeds `maxLength` and summary is off (or no API key for the
-summary model), audio
-is skipped and the normal text reply is sent.
-
-## Flow diagram
-
-```
-Reply -> TTS enabled?
-  no  -> send text
-  yes -> has media / MEDIA: / short?
-          yes -> send text
-          no  -> length > limit?
-                   no  -> TTS -> attach audio
-                   yes -> summary enabled?
-                            no  -> send text
-                            yes -> summarize (summaryModel or agents.defaults.model.primary)
-                                      -> TTS -> attach audio
-```
-
-## Slash command usage
-
-There is a single command: `/tts`.
-See [Slash commands](/tools/slash-commands) for enablement details.
-
-Discord note: `/tts` is a built-in Discord command, so OpenClaw registers
-`/voice` as the native command there. Text `/tts ...` still works.
-
-```
-/tts off
-/tts always
-/tts inbound
-/tts tagged
-/tts status
-/tts provider openai
-/tts limit 2000
-/tts summary off
-/tts audio Hello from OpenClaw
-```
-
-Notes:
-
-- Commands require an authorized sender (allowlist/owner rules still apply).
-- `commands.text` or native command registration must be enabled.
-- `off|always|inbound|tagged` are per‑session toggles (`/tts on` is an alias for `/tts always`).
-- `limit` and `summary` are stored in local prefs, not the main config.
-- `/tts audio` generates a one-off audio reply (does not toggle TTS on).
-- `/tts status` includes fallback visibility for the latest attempt:
-  - success fallback: `Fallback: <primary> -> <used>` plus `Attempts: ...`
-  - failure: `Error: ...` plus `Attempts: ...`
-  - detailed diagnostics: `Attempt details: provider:outcome(reasonCode) latency`
-- OpenAI and ElevenLabs API failures now include parsed provider error detail and request id (when returned by the provider), which is surfaced in TTS errors/logs.
-
-## Agent tool
-
-The `tts` tool converts text to speech and returns an audio attachment for
-reply delivery. When the channel is Feishu, Matrix, Telegram, or WhatsApp,
-the audio is delivered as a voice message rather than a file attachment.
-
-## Gateway RPC
-
-Gateway methods:
-
-- `tts.status`
-- `tts.enable`
-- `tts.disable`
-- `tts.convert`
-- `tts.setProvider`
-- `tts.providers`
+This page has moved to [Text-to-Speech](/tools/tts).

extensions/acpx/AGENTS.md

@@ -0,0 +1,54 @@
+# ACPX Extension Notes
+
+This file applies to work under `extensions/acpx/`.
+
+## Purpose
+
+The bundled ACPX extension is a thin OpenClaw wrapper around the published `acpx` package. Keep reusable ACP runtime logic in `openclaw/acpx`, not in this extension.
+
+## Default Version Policy
+
+- `extensions/acpx/package.json` should point at a published npm release by default.
+- Do not leave the extension pinned to a temporary GitHub commit or local checkout once the ACPX release exists.
+- Do not leave temporary pnpm build-script allowlist exceptions behind after switching back to a published ACPX package.
+
+## Unreleased ACPX Development Flow
+
+Use this flow when OpenClaw needs unreleased ACPX changes before the ACPX version is published.
+
+1. Make the ACPX code change in the `openclaw/acpx` repo first.
+2. In OpenClaw, temporarily point `extensions/acpx/package.json` at the ACPX GitHub commit you need.
+3. If pnpm blocks ACPX lifecycle/build scripts for that temporary GitHub-sourced package, temporarily add `acpx` to `onlyBuiltDependencies` in both `package.json` and `pnpm-workspace.yaml`.
+4. Refresh the root workspace lock:
+   - `pnpm install --lockfile-only --filter ./extensions/acpx`
+5. Refresh the extension-local npm lock for install metadata:
+   - `cd extensions/acpx && npm install --package-lock-only --ignore-scripts`
+6. Rebuild OpenClaw and restart the gateway before doing live ACP validation.
+7. Once ACPX is released, switch `extensions/acpx/package.json` back to the published npm version and refresh the same lockfiles again.
+8. Remove any temporary `acpx` build-script allowlist entries that were only needed for the GitHub-sourced development pin.
+
+## Lockfile Notes
+
+- `pnpm-lock.yaml` is the tracked workspace lockfile and must match the ACPX version referenced by `extensions/acpx/package.json`.
+- `extensions/acpx/package-lock.json` is useful local install metadata for the bundled plugin package.
+- If `extensions/acpx/package-lock.json` is gitignored in this repo state, regenerating it is still useful for local verification, but it will not appear in `git status`.
+
+## Local Runtime Validation
+
+When ACPX integration changes here, prefer this sequence:
+
+1. `pnpm install --filter ./extensions/acpx`
+2. `pnpm test:extension acpx`
+3. `pnpm build`
+4. Restart the local gateway if ACP runtime behavior or bundled plugin wiring changed.
+5. If the change affects direct ACP behavior in chat, run a real ACP smoke after restart.
+
+## Direct ACPX Binary Policy
+
+- Prefer the plugin-local ACPX binary under `extensions/acpx/node_modules/.bin/acpx`.
+- Do not rely on a globally installed `acpx` binary for OpenClaw ACP validation.
+- If the plugin-local ACPX binary is missing or on the wrong version, reinstall it from the version pinned in `extensions/acpx/package.json`.
+
+## Boundary Rule
+
+If a change feels like shared ACP runtime behavior instead of OpenClaw-specific glue, move it to `openclaw/acpx` and consume it from here instead of re-implementing it inside `extensions/acpx`.

extensions/acpx/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

extensions/acpx/openclaw.plugin.json

@@ -101,7 +101,7 @@
     },
     "strictWindowsCmdWrapper": {
       "label": "Strict Windows cmd Wrapper",
-      "help": "Enabled by default. On Windows, reject unresolved .cmd/.bat wrappers instead of shell fallback. Disable only for compatibility with non-standard wrappers.",
+      "help": "Legacy compatibility field. The current embedded acpx/runtime package uses its own Windows command resolution behavior. Setting this to false is accepted for compatibility and logged as ignored.",
       "advanced": true
     },
     "timeoutSeconds": {
@@ -111,7 +111,7 @@
     },
     "queueOwnerTtlSeconds": {
       "label": "Queue Owner TTL Seconds",
-      "help": "Reserved compatibility field for future queued embedded prompt ownership.",
+      "help": "Reserved compatibility field for the older embedded ACPX queue-owner path. Accepted for compatibility and logged as ignored.",
       "advanced": true
     },
     "mcpServers": {
@@ -124,5 +124,22 @@
       "help": "Optional per-agent command overrides for the embedded ACP runtime.",
       "advanced": true
     }
+  },
+  "configContracts": {
+    "dangerousFlags": [
+      {
+        "path": "permissionMode",
+        "equals": "approve-all"
+      }
+    ],
+    "secretInputs": {
+      "bundledDefaultEnabled": false,
+      "paths": [
+        {
+          "path": "mcpServers.*.env.*",
+          "expected": "string"
+        }
+      ]
+    }
   }
 }

extensions/acpx/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@openclaw/acpx",
-  "version": "2026.4.5",
+  "version": "2026.4.6",
   "description": "OpenClaw ACP runtime backend",
   "type": "module",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.18.0"
+    "acpx": "0.5.0"
   },
   "openclaw": {
     "extensions": [

extensions/acpx/src/acp-error-shapes.ts

@@ -1,153 +0,0 @@
-import type { OutputErrorAcpPayload } from "./runtime-types.js";
-
-const RESOURCE_NOT_FOUND_ACP_CODES = new Set([-32001, -32002]);
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return undefined;
-  }
-  return value as Record<string, unknown>;
-}
-
-function toAcpErrorPayload(value: unknown): OutputErrorAcpPayload | undefined {
-  const record = asRecord(value);
-  if (!record) {
-    return undefined;
-  }
-
-  if (typeof record.code !== "number" || !Number.isFinite(record.code)) {
-    return undefined;
-  }
-  if (typeof record.message !== "string" || record.message.length === 0) {
-    return undefined;
-  }
-
-  return {
-    code: record.code,
-    message: record.message,
-    data: record.data,
-  };
-}
-
-function extractAcpErrorInternal(value: unknown, depth: number): OutputErrorAcpPayload | undefined {
-  if (depth > 5) {
-    return undefined;
-  }
-
-  const direct = toAcpErrorPayload(value);
-  if (direct) {
-    return direct;
-  }
-
-  const record = asRecord(value);
-  if (!record) {
-    return undefined;
-  }
-
-  if ("error" in record) {
-    const nested = extractAcpErrorInternal(record.error, depth + 1);
-    if (nested) {
-      return nested;
-    }
-  }
-
-  if ("acp" in record) {
-    const nested = extractAcpErrorInternal(record.acp, depth + 1);
-    if (nested) {
-      return nested;
-    }
-  }
-
-  if ("cause" in record) {
-    const nested = extractAcpErrorInternal(record.cause, depth + 1);
-    if (nested) {
-      return nested;
-    }
-  }
-
-  return undefined;
-}
-
-export function formatUnknownErrorMessage(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
-
-  if (error && typeof error === "object") {
-    const maybeMessage = (error as { message?: unknown }).message;
-    if (typeof maybeMessage === "string" && maybeMessage.length > 0) {
-      return maybeMessage;
-    }
-
-    try {
-      return JSON.stringify(error);
-    } catch {
-      // fall through
-    }
-  }
-
-  return String(error);
-}
-
-// Matches "session" followed by optional ID (quoted or unquoted) followed by "not found"
-// Examples: "Session \"abc\" not found", "Session abc-123 not found"
-const SESSION_NOT_FOUND_PATTERN = /session\s+["'\w-]+\s+not found/i;
-
-function isSessionNotFoundText(value: unknown): boolean {
-  if (typeof value !== "string") {
-    return false;
-  }
-
-  const normalized = value.toLowerCase();
-  return (
-    normalized.includes("resource_not_found") ||
-    normalized.includes("resource not found") ||
-    normalized.includes("session not found") ||
-    normalized.includes("unknown session") ||
-    normalized.includes("invalid session identifier") ||
-    SESSION_NOT_FOUND_PATTERN.test(value)
-  );
-}
-
-function hasSessionNotFoundHint(value: unknown, depth = 0): boolean {
-  if (depth > 4) {
-    return false;
-  }
-
-  if (isSessionNotFoundText(value)) {
-    return true;
-  }
-
-  if (Array.isArray(value)) {
-    return value.some((entry) => hasSessionNotFoundHint(entry, depth + 1));
-  }
-
-  const record = asRecord(value);
-  if (!record) {
-    return false;
-  }
-
-  return Object.values(record).some((entry) => hasSessionNotFoundHint(entry, depth + 1));
-}
-
-export function extractAcpError(error: unknown): OutputErrorAcpPayload | undefined {
-  return extractAcpErrorInternal(error, 0);
-}
-
-export function isAcpResourceNotFoundError(error: unknown): boolean {
-  const acp = extractAcpError(error);
-  if (acp && RESOURCE_NOT_FOUND_ACP_CODES.has(acp.code)) {
-    return true;
-  }
-
-  if (acp) {
-    if (isSessionNotFoundText(acp.message)) {
-      return true;
-    }
-    if (hasSessionNotFoundHint(acp.data)) {
-      return true;
-    }
-  }
-
-  return isSessionNotFoundText(formatUnknownErrorMessage(error));
-}

extensions/acpx/src/acp-jsonrpc.ts

@@ -1,137 +0,0 @@
-import type { AnyMessage, SessionNotification } from "@agentclientprotocol/sdk";
-
-type JsonRpcId = string | number | null;
-
-function asRecord(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  return value as Record<string, unknown>;
-}
-
-function hasValidId(value: unknown): value is JsonRpcId {
-  return (
-    value === null ||
-    typeof value === "string" ||
-    (typeof value === "number" && Number.isFinite(value))
-  );
-}
-
-function isErrorObject(value: unknown): value is { code: number; message: string } {
-  const record = asRecord(value);
-  return (
-    !!record &&
-    typeof record.code === "number" &&
-    Number.isFinite(record.code) &&
-    typeof record.message === "string"
-  );
-}
-
-function hasResultOrError(value: Record<string, unknown>): boolean {
-  const hasResult = Object.hasOwn(value, "result");
-  const hasError = Object.hasOwn(value, "error");
-  if (hasResult && hasError) {
-    return false;
-  }
-  if (!hasResult && !hasError) {
-    return false;
-  }
-  if (hasError && !isErrorObject(value.error)) {
-    return false;
-  }
-  return true;
-}
-
-export function isAcpJsonRpcMessage(value: unknown): value is AnyMessage {
-  const record = asRecord(value);
-  if (!record || record.jsonrpc !== "2.0") {
-    return false;
-  }
-
-  const hasMethod = typeof record.method === "string" && record.method.length > 0;
-  const hasId = Object.hasOwn(record, "id");
-
-  if (hasMethod && !hasId) {
-    // Notification
-    return true;
-  }
-
-  if (hasMethod && hasId) {
-    // Request
-    return hasValidId(record.id);
-  }
-
-  if (!hasMethod && hasId) {
-    // Response
-    if (!hasValidId(record.id)) {
-      return false;
-    }
-    return hasResultOrError(record);
-  }
-
-  return false;
-}
-
-export function isJsonRpcNotification(message: AnyMessage): boolean {
-  return (
-    Object.hasOwn(message, "method") &&
-    typeof (message as { method?: unknown }).method === "string" &&
-    !Object.hasOwn(message, "id")
-  );
-}
-
-export function isSessionUpdateNotification(message: AnyMessage): boolean {
-  return (
-    isJsonRpcNotification(message) && (message as { method?: unknown }).method === "session/update"
-  );
-}
-
-export function extractSessionUpdateNotification(
-  message: AnyMessage,
-): SessionNotification | undefined {
-  if (!isSessionUpdateNotification(message)) {
-    return undefined;
-  }
-
-  const params = asRecord((message as { params?: unknown }).params);
-  if (!params) {
-    return undefined;
-  }
-
-  const sessionId = typeof params.sessionId === "string" ? params.sessionId : null;
-  if (!sessionId) {
-    return undefined;
-  }
-
-  const update = asRecord(params.update);
-  if (!update || typeof update.sessionUpdate !== "string") {
-    return undefined;
-  }
-
-  return {
-    sessionId,
-    update: update as SessionNotification["update"],
-  };
-}
-
-export function parsePromptStopReason(message: AnyMessage): string | undefined {
-  if (!Object.hasOwn(message, "id") || !Object.hasOwn(message, "result")) {
-    return undefined;
-  }
-  const record = asRecord((message as { result?: unknown }).result);
-  if (!record) {
-    return undefined;
-  }
-  return typeof record.stopReason === "string" ? record.stopReason : undefined;
-}
-
-export function parseJsonRpcErrorMessage(message: AnyMessage): string | undefined {
-  if (!Object.hasOwn(message, "error")) {
-    return undefined;
-  }
-  const errorRecord = asRecord((message as { error?: unknown }).error);
-  if (!errorRecord || typeof errorRecord.message !== "string") {
-    return undefined;
-  }
-  return errorRecord.message;
-}

extensions/acpx/src/acpx-runtime.d.ts

@@ -0,0 +1,55 @@
+declare module "acpx/runtime" {
+  export const ACPX_BACKEND_ID: string;
+
+  export type AcpRuntimeDoctorReport =
+    import("../../../src/acp/runtime/types.js").AcpRuntimeDoctorReport;
+  export type AcpRuntimeEnsureInput =
+    import("../../../src/acp/runtime/types.js").AcpRuntimeEnsureInput;
+  export type AcpRuntimeEvent = import("../../../src/acp/runtime/types.js").AcpRuntimeEvent;
+  export type AcpRuntimeHandle = import("../../../src/acp/runtime/types.js").AcpRuntimeHandle;
+  export type AcpRuntimeTurnInput = import("../../../src/acp/runtime/types.js").AcpRuntimeTurnInput;
+  export type AcpRuntimeStatus = import("../../../src/acp/runtime/types.js").AcpRuntimeStatus;
+  export type AcpRuntimeCapabilities =
+    import("../../../src/acp/runtime/types.js").AcpRuntimeCapabilities;
+
+  export type AcpSessionStore = {
+    load(sessionId: string): Promise<unknown>;
+    save(record: unknown): Promise<void>;
+  };
+
+  export type AcpAgentRegistry = {
+    resolve(agentId: string): string;
+    list(): string[];
+  };
+
+  export type AcpRuntimeOptions = {
+    cwd: string;
+    sessionStore: AcpSessionStore;
+    agentRegistry: AcpAgentRegistry;
+    permissionMode: string;
+    mcpServers?: unknown[];
+    nonInteractivePermissions?: unknown;
+    timeoutMs?: number;
+  };
+
+  export class AcpxRuntime {
+    constructor(options: AcpRuntimeOptions, testOptions?: unknown);
+    isHealthy(): boolean;
+    probeAvailability(): Promise<void>;
+    doctor(): Promise<AcpRuntimeDoctorReport>;
+    ensureSession(input: AcpRuntimeEnsureInput): Promise<AcpRuntimeHandle>;
+    runTurn(input: AcpRuntimeTurnInput): AsyncIterable<AcpRuntimeEvent>;
+    getCapabilities(input?: { handle?: AcpRuntimeHandle }): AcpRuntimeCapabilities;
+    getStatus(input: { handle: AcpRuntimeHandle; signal?: AbortSignal }): Promise<AcpRuntimeStatus>;
+    setMode(input: { handle: AcpRuntimeHandle; mode: string }): Promise<void>;
+    setConfigOption(input: { handle: AcpRuntimeHandle; key: string; value: string }): Promise<void>;
+    cancel(input: { handle: AcpRuntimeHandle; reason?: string }): Promise<void>;
+    close(input: { handle: AcpRuntimeHandle; reason: string }): Promise<void>;
+  }
+
+  export function createAcpRuntime(...args: unknown[]): unknown;
+  export function createAgentRegistry(...args: unknown[]): AcpAgentRegistry;
+  export function createFileSessionStore(...args: unknown[]): AcpSessionStore;
+  export function decodeAcpxRuntimeHandleState(...args: unknown[]): unknown;
+  export function encodeAcpxRuntimeHandleState(...args: unknown[]): unknown;
+}

extensions/acpx/src/agent-session-id.ts

@@ -1,35 +0,0 @@
-const AGENT_SESSION_ID_META_KEYS = ["agentSessionId", "sessionId"] as const;
-
-export function normalizeAgentSessionId(value: unknown): string | undefined {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function asMetaRecord(meta: unknown): Record<string, unknown> | undefined {
-  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
-    return undefined;
-  }
-  return meta as Record<string, unknown>;
-}
-
-export function extractAgentSessionId(meta: unknown): string | undefined {
-  const record = asMetaRecord(meta);
-  if (!record) {
-    return undefined;
-  }
-
-  for (const key of AGENT_SESSION_ID_META_KEYS) {
-    const normalized = normalizeAgentSessionId(record[key]);
-    if (normalized) {
-      return normalized;
-    }
-  }
-
-  return undefined;
-}
-
-export { AGENT_SESSION_ID_META_KEYS };

extensions/acpx/src/agents/registry.ts

@@ -1,61 +0,0 @@
-const ACP_ADAPTER_PACKAGE_RANGES = {
-  pi: "^0.0.22",
-  codex: "^0.11.1",
-  claude: "^0.25.0",
-} as const;
-
-export const AGENT_REGISTRY: Record<string, string> = {
-  pi: `npx pi-acp@${ACP_ADAPTER_PACKAGE_RANGES.pi}`,
-  openclaw: "openclaw acp",
-  codex: `npx @zed-industries/codex-acp@${ACP_ADAPTER_PACKAGE_RANGES.codex}`,
-  claude: `npx -y @agentclientprotocol/claude-agent-acp@${ACP_ADAPTER_PACKAGE_RANGES.claude}`,
-  gemini: "gemini --acp",
-  cursor: "cursor-agent acp",
-  copilot: "copilot --acp --stdio",
-  droid: "droid exec --output-format acp",
-  iflow: "iflow --experimental-acp",
-  kilocode: "npx -y @kilocode/cli acp",
-  kimi: "kimi acp",
-  kiro: "kiro-cli-chat acp",
-  opencode: "npx -y opencode-ai acp",
-  qoder: "qodercli --acp",
-  qwen: "qwen --acp",
-  trae: "traecli acp serve",
-};
-
-const AGENT_ALIASES: Record<string, string> = {
-  "factory-droid": "droid",
-  factorydroid: "droid",
-};
-
-export const DEFAULT_AGENT_NAME = "codex";
-
-export function normalizeAgentName(value: string): string {
-  return value.trim().toLowerCase();
-}
-
-export function mergeAgentRegistry(overrides?: Record<string, string>): Record<string, string> {
-  if (!overrides) {
-    return { ...AGENT_REGISTRY };
-  }
-
-  const merged = { ...AGENT_REGISTRY };
-  for (const [name, command] of Object.entries(overrides)) {
-    const normalized = normalizeAgentName(name);
-    if (!normalized || !command.trim()) {
-      continue;
-    }
-    merged[normalized] = command.trim();
-  }
-  return merged;
-}
-
-export function resolveAgentCommand(agentName: string, overrides?: Record<string, string>): string {
-  const normalized = normalizeAgentName(agentName);
-  const registry = mergeAgentRegistry(overrides);
-  return registry[normalized] ?? registry[AGENT_ALIASES[normalized] ?? normalized] ?? agentName;
-}
-
-export function listBuiltInAgents(overrides?: Record<string, string>): string[] {
-  return Object.keys(mergeAgentRegistry(overrides));
-}

extensions/acpx/src/config-schema.ts

@@ -43,6 +43,10 @@ export type ResolvedAcpxPluginConfig = {
   strictWindowsCmdWrapper: boolean;
   timeoutSeconds?: number;
   queueOwnerTtlSeconds: number;
+  legacyCompatibilityConfig: {
+    strictWindowsCmdWrapper?: boolean;
+    queueOwnerTtlSeconds?: number;
+  };
   mcpServers: Record<string, McpServerConfig>;
   agents: Record<string, string>;
 };

extensions/acpx/src/config.ts

@@ -176,7 +176,7 @@ function resolveConfiguredMcpServers(params: {
   pluginToolsMcpBridge: boolean;
   moduleUrl?: string;
 }): Record<string, McpServerConfig> {
-  const resolved = { ...(params.mcpServers ?? {}) };
+  const resolved = { ...params.mcpServers };
   if (!params.pluginToolsMcpBridge) {
     return resolved;
   }
@@ -239,6 +239,10 @@ export function resolveAcpxPluginConfig(params: {
       normalized.strictWindowsCmdWrapper ?? DEFAULT_STRICT_WINDOWS_CMD_WRAPPER,
     timeoutSeconds: normalized.timeoutSeconds,
     queueOwnerTtlSeconds: normalized.queueOwnerTtlSeconds ?? DEFAULT_QUEUE_OWNER_TTL_SECONDS,
+    legacyCompatibilityConfig: {
+      strictWindowsCmdWrapper: normalized.strictWindowsCmdWrapper,
+      queueOwnerTtlSeconds: normalized.queueOwnerTtlSeconds,
+    },
     mcpServers,
     agents,
   };

extensions/acpx/src/error-normalization.ts

@@ -1,287 +0,0 @@
-import {
-  extractAcpError,
-  formatUnknownErrorMessage,
-  isAcpResourceNotFoundError,
-} from "./acp-error-shapes.js";
-import {
-  AuthPolicyError,
-  PermissionDeniedError,
-  PermissionPromptUnavailableError,
-} from "./errors.js";
-import {
-  EXIT_CODES,
-  OUTPUT_ERROR_CODES,
-  OUTPUT_ERROR_ORIGINS,
-  type ExitCode,
-  type OutputErrorAcpPayload,
-  type OutputErrorCode,
-  type OutputErrorOrigin,
-} from "./runtime-types.js";
-
-const AUTH_REQUIRED_ACP_CODES = new Set([-32000]);
-const QUERY_CLOSED_BEFORE_RESPONSE_DETAIL = "query closed before response received";
-
-type ErrorMeta = {
-  outputCode?: OutputErrorCode;
-  detailCode?: string;
-  origin?: OutputErrorOrigin;
-  retryable?: boolean;
-  acp?: OutputErrorAcpPayload;
-};
-
-export type NormalizedOutputError = {
-  code: OutputErrorCode;
-  message: string;
-  detailCode?: string;
-  origin?: OutputErrorOrigin;
-  retryable?: boolean;
-  acp?: OutputErrorAcpPayload;
-};
-
-export type NormalizeOutputErrorOptions = {
-  defaultCode?: OutputErrorCode;
-  detailCode?: string;
-  origin?: OutputErrorOrigin;
-  retryable?: boolean;
-  acp?: OutputErrorAcpPayload;
-};
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return undefined;
-  }
-  return value as Record<string, unknown>;
-}
-
-function isAuthRequiredMessage(value: string | undefined): boolean {
-  if (!value) {
-    return false;
-  }
-  const normalized = value.toLowerCase();
-  return (
-    normalized.includes("auth required") ||
-    normalized.includes("authentication required") ||
-    normalized.includes("authorization required") ||
-    normalized.includes("credential required") ||
-    normalized.includes("credentials required") ||
-    normalized.includes("token required") ||
-    normalized.includes("login required")
-  );
-}
-
-function isAcpAuthRequiredPayload(acp: OutputErrorAcpPayload | undefined): boolean {
-  if (!acp) {
-    return false;
-  }
-  if (!AUTH_REQUIRED_ACP_CODES.has(acp.code)) {
-    return false;
-  }
-  if (isAuthRequiredMessage(acp.message)) {
-    return true;
-  }
-
-  const data = asRecord(acp.data);
-  if (!data) {
-    return false;
-  }
-
-  if (data.authRequired === true) {
-    return true;
-  }
-
-  const methodId = data.methodId;
-  if (typeof methodId === "string" && methodId.trim().length > 0) {
-    return true;
-  }
-
-  const methods = data.methods;
-  if (Array.isArray(methods) && methods.length > 0) {
-    return true;
-  }
-
-  return false;
-}
-
-function isOutputErrorCode(value: unknown): value is OutputErrorCode {
-  return typeof value === "string" && OUTPUT_ERROR_CODES.includes(value as OutputErrorCode);
-}
-
-function isOutputErrorOrigin(value: unknown): value is OutputErrorOrigin {
-  return typeof value === "string" && OUTPUT_ERROR_ORIGINS.includes(value as OutputErrorOrigin);
-}
-
-function readOutputErrorMeta(error: unknown): ErrorMeta {
-  const record = asRecord(error);
-  if (!record) {
-    return {};
-  }
-
-  const outputCode = isOutputErrorCode(record.outputCode) ? record.outputCode : undefined;
-  const detailCode =
-    typeof record.detailCode === "string" && record.detailCode.trim().length > 0
-      ? record.detailCode
-      : undefined;
-  const origin = isOutputErrorOrigin(record.origin) ? record.origin : undefined;
-  const retryable = typeof record.retryable === "boolean" ? record.retryable : undefined;
-
-  const acp = extractAcpError(record.acp);
-  return {
-    outputCode,
-    detailCode,
-    origin,
-    retryable,
-    acp,
-  };
-}
-
-function isTimeoutLike(error: unknown): boolean {
-  return error instanceof Error && error.name === "TimeoutError";
-}
-
-function isNoSessionLike(error: unknown): boolean {
-  return error instanceof Error && error.name === "NoSessionError";
-}
-
-function isUsageLike(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
-  }
-  return (
-    error.name === "CommanderError" ||
-    error.name === "InvalidArgumentError" ||
-    asRecord(error)?.code === "commander.invalidArgument"
-  );
-}
-
-export function formatErrorMessage(error: unknown): string {
-  return formatUnknownErrorMessage(error);
-}
-
-export { extractAcpError, isAcpResourceNotFoundError };
-
-export function isAcpQueryClosedBeforeResponseError(error: unknown): boolean {
-  const acp = extractAcpError(error);
-  if (!acp || acp.code !== -32603) {
-    return false;
-  }
-
-  const data = asRecord(acp.data);
-  const details = data?.details;
-  if (typeof details !== "string") {
-    return false;
-  }
-
-  return details.toLowerCase().includes(QUERY_CLOSED_BEFORE_RESPONSE_DETAIL);
-}
-
-function mapErrorCode(error: unknown): OutputErrorCode | undefined {
-  if (error instanceof PermissionPromptUnavailableError) {
-    return "PERMISSION_PROMPT_UNAVAILABLE";
-  }
-  if (error instanceof PermissionDeniedError) {
-    return "PERMISSION_DENIED";
-  }
-  if (isTimeoutLike(error)) {
-    return "TIMEOUT";
-  }
-  if (isNoSessionLike(error) || isAcpResourceNotFoundError(error)) {
-    return "NO_SESSION";
-  }
-  if (isUsageLike(error)) {
-    return "USAGE";
-  }
-  return undefined;
-}
-
-export function normalizeOutputError(
-  error: unknown,
-  options: NormalizeOutputErrorOptions = {},
-): NormalizedOutputError {
-  const meta = readOutputErrorMeta(error);
-  const mapped = mapErrorCode(error);
-  let code = mapped ?? options.defaultCode ?? "RUNTIME";
-
-  if (meta.outputCode) {
-    code = meta.outputCode;
-  }
-
-  if (code === "RUNTIME" && isAcpResourceNotFoundError(error)) {
-    code = "NO_SESSION";
-  }
-
-  const acp = options.acp ?? meta.acp ?? extractAcpError(error);
-  const detailCode =
-    meta.detailCode ??
-    options.detailCode ??
-    (error instanceof AuthPolicyError || isAcpAuthRequiredPayload(acp)
-      ? "AUTH_REQUIRED"
-      : undefined);
-  return {
-    code,
-    message: formatErrorMessage(error),
-    detailCode,
-    origin: meta.origin ?? options.origin,
-    retryable: meta.retryable ?? options.retryable,
-    acp,
-  };
-}
-
-/**
- * Returns true when an error from `client.prompt()` looks transient and
- * can reasonably be retried (e.g. model-API 400/500, network hiccups that
- * surface as ACP internal errors).
- *
- * Errors that are definitively non-recoverable (auth, missing session,
- * invalid params, timeout, permission) return false.
- */
-export function isRetryablePromptError(error: unknown): boolean {
-  if (error instanceof PermissionDeniedError || error instanceof PermissionPromptUnavailableError) {
-    return false;
-  }
-  if (isTimeoutLike(error) || isNoSessionLike(error) || isUsageLike(error)) {
-    return false;
-  }
-
-  // Extract ACP payload once and reuse for all subsequent checks.
-  const acp = extractAcpError(error);
-  if (!acp) {
-    // Non-ACP errors (e.g. process crash) are not retried at the prompt level.
-    return false;
-  }
-
-  // Resource-not-found (session gone) — check using the already-extracted payload.
-  if (acp.code === -32001 || acp.code === -32002) {
-    return false;
-  }
-
-  // Auth-required errors are never retryable. Use the same thorough check as normalizeOutputError.
-  if (isAcpAuthRequiredPayload(acp)) {
-    return false;
-  }
-
-  // Method-not-found or invalid-params are permanent protocol errors.
-  if (acp.code === -32601 || acp.code === -32602) {
-    return false;
-  }
-
-  // ACP internal errors (-32603) typically wrap model-API failures → retryable.
-  // Parse errors (-32700) can also be transient.
-  return acp.code === -32603 || acp.code === -32700;
-}
-
-export function exitCodeForOutputErrorCode(code: OutputErrorCode): ExitCode {
-  switch (code) {
-    case "USAGE":
-      return EXIT_CODES.USAGE;
-    case "TIMEOUT":
-      return EXIT_CODES.TIMEOUT;
-    case "NO_SESSION":
-      return EXIT_CODES.NO_SESSION;
-    case "PERMISSION_DENIED":
-    case "PERMISSION_PROMPT_UNAVAILABLE":
-      return EXIT_CODES.PERMISSION_DENIED;
-    case "RUNTIME":
-    default:
-      return EXIT_CODES.ERROR;
-  }
-}

extensions/acpx/src/errors.ts

@@ -1,168 +0,0 @@
-import type { OutputErrorAcpPayload, OutputErrorCode, OutputErrorOrigin } from "./runtime-types.js";
-
-type AcpxErrorOptions = ErrorOptions & {
-  outputCode?: OutputErrorCode;
-  detailCode?: string;
-  origin?: OutputErrorOrigin;
-  retryable?: boolean;
-  acp?: OutputErrorAcpPayload;
-  outputAlreadyEmitted?: boolean;
-};
-
-export class AcpxOperationalError extends Error {
-  readonly outputCode?: OutputErrorCode;
-  readonly detailCode?: string;
-  readonly origin?: OutputErrorOrigin;
-  readonly retryable?: boolean;
-  readonly acp?: OutputErrorAcpPayload;
-  readonly outputAlreadyEmitted?: boolean;
-
-  constructor(message: string, options?: AcpxErrorOptions) {
-    super(message, options);
-    this.name = new.target.name;
-    this.outputCode = options?.outputCode;
-    this.detailCode = options?.detailCode;
-    this.origin = options?.origin;
-    this.retryable = options?.retryable;
-    this.acp = options?.acp;
-    this.outputAlreadyEmitted = options?.outputAlreadyEmitted;
-  }
-}
-
-export class SessionNotFoundError extends AcpxOperationalError {
-  readonly sessionId: string;
-
-  constructor(sessionId: string) {
-    super(`Session not found: ${sessionId}`);
-    this.sessionId = sessionId;
-  }
-}
-
-export class SessionResolutionError extends AcpxOperationalError {}
-
-export class AgentSpawnError extends AcpxOperationalError {
-  readonly agentCommand: string;
-
-  constructor(agentCommand: string, cause?: unknown) {
-    super(`Failed to spawn agent command: ${agentCommand}`, {
-      cause: cause instanceof Error ? cause : undefined,
-    });
-    this.agentCommand = agentCommand;
-  }
-}
-
-export class AgentDisconnectedError extends AcpxOperationalError {
-  readonly reason: string;
-  readonly exitCode: number | null;
-  readonly signal: NodeJS.Signals | null;
-
-  constructor(
-    reason: string,
-    exitCode: number | null,
-    signal: NodeJS.Signals | null,
-    options?: AcpxErrorOptions,
-  ) {
-    super(
-      `ACP agent disconnected during request (${reason}, exit=${exitCode ?? "null"}, signal=${signal ?? "null"})`,
-      {
-        outputCode: "RUNTIME",
-        detailCode: "AGENT_DISCONNECTED",
-        origin: "acp",
-        ...options,
-      },
-    );
-    this.reason = reason;
-    this.exitCode = exitCode;
-    this.signal = signal;
-  }
-}
-
-export class SessionResumeRequiredError extends AcpxOperationalError {
-  constructor(message: string, options?: AcpxErrorOptions) {
-    super(message, {
-      outputCode: "RUNTIME",
-      detailCode: "SESSION_RESUME_REQUIRED",
-      origin: "acp",
-      retryable: true,
-      ...options,
-    });
-  }
-}
-
-export class GeminiAcpStartupTimeoutError extends AcpxOperationalError {
-  constructor(message: string, options?: AcpxErrorOptions) {
-    super(message, {
-      outputCode: "TIMEOUT",
-      detailCode: "GEMINI_ACP_STARTUP_TIMEOUT",
-      origin: "acp",
-      ...options,
-    });
-  }
-}
-
-export class SessionModeReplayError extends AcpxOperationalError {
-  constructor(message: string, options?: AcpxErrorOptions) {
-    super(message, {
-      outputCode: "RUNTIME",
-      detailCode: "SESSION_MODE_REPLAY_FAILED",
-      origin: "acp",
-      ...options,
-    });
-  }
-}
-
-export class SessionModelReplayError extends AcpxOperationalError {
-  constructor(message: string, options?: AcpxErrorOptions) {
-    super(message, {
-      outputCode: "RUNTIME",
-      detailCode: "SESSION_MODEL_REPLAY_FAILED",
-      origin: "acp",
-      ...options,
-    });
-  }
-}
-
-export class ClaudeAcpSessionCreateTimeoutError extends AcpxOperationalError {
-  constructor(message: string, options?: AcpxErrorOptions) {
-    super(message, {
-      outputCode: "TIMEOUT",
-      detailCode: "CLAUDE_ACP_SESSION_CREATE_TIMEOUT",
-      origin: "acp",
-      ...options,
-    });
-  }
-}
-
-export class CopilotAcpUnsupportedError extends AcpxOperationalError {
-  constructor(message: string, options?: AcpxErrorOptions) {
-    super(message, {
-      outputCode: "RUNTIME",
-      detailCode: "COPILOT_ACP_UNSUPPORTED",
-      origin: "acp",
-      ...options,
-    });
-  }
-}
-
-export class AuthPolicyError extends AcpxOperationalError {
-  constructor(message: string, options?: AcpxErrorOptions) {
-    super(message, {
-      outputCode: "RUNTIME",
-      detailCode: "AUTH_REQUIRED",
-      origin: "acp",
-      ...options,
-    });
-  }
-}
-
-export class QueueConnectionError extends AcpxOperationalError {}
-
-export class QueueProtocolError extends AcpxOperationalError {}
-
-export class PermissionDeniedError extends AcpxOperationalError {}
-
-export class PermissionPromptUnavailableError extends AcpxOperationalError {
-  constructor() {
-    super("Permission prompt unavailable in non-interactive mode");
-  }
-}