fix(cli): lazy-load model auth runtime

Refresh loaded gateway service installs when the current service embeds stale gateway auth instead of returning already-installed, avoiding LaunchAgent token-mismatch loops after token rotation.

Fixes #70752.
Thanks @hyspacex.

Co-authored-by: Harry Xie <harryhsieh963@yahoo.com>

.agents/skills/openclaw-pr-maintainer/SKILL.md

@@ -7,6 +7,22 @@ description: Review, triage, close, label, comment on, or land OpenClaw PRs/issu
 
 Use this skill for maintainer-facing GitHub workflow, not for ordinary code changes.
 
+## Start issue and PR triage with ghcrawl
+
+- Anytime you inspect OpenClaw issues or PRs, check local `ghcrawl` data first for related threads, duplicate attempts, and already-landed fixes.
+- Use `ghcrawl` for candidate discovery and clustering; use `gh`, `gh api`, and the current checkout to verify live state before commenting, labeling, closing, or landing.
+- If `ghcrawl` is missing, stale, lacks the target thread, or has no embeddings for neighbor/search commands, fall back to the GitHub search workflow below.
+- Do not run expensive/update commands such as `ghcrawl refresh`, `ghcrawl embed`, or `ghcrawl cluster` unless the user asked to update the local store or the stale data is blocking the decision.
+
+Common read-only path:
+
+```bash
+ghcrawl threads openclaw/openclaw --numbers <issue-or-pr-number> --include-closed --json
+ghcrawl neighbors openclaw/openclaw --number <issue-or-pr-number> --limit 12 --json
+ghcrawl search openclaw/openclaw --query "<scope or title keywords>" --mode hybrid --json
+ghcrawl cluster-detail openclaw/openclaw --id <cluster-id> --member-limit 20 --body-chars 280 --json
+```
+
 ## Apply close and triage labels correctly
 
 - If an issue or PR matches an auto-close reason, apply the label and let `.github/workflows/auto-response.yml` handle the comment/close/lock flow.
@@ -59,9 +75,9 @@ Use this skill for maintainer-facing GitHub workflow, not for ordinary code chan
 
 ## Search broadly before deciding
 
-- Prefer targeted keyword search before proposing new work or closing something as duplicate.
-- Use `--repo openclaw/openclaw` with `--match title,body` first.
-- Add `--match comments` when triaging follow-up discussion.
+- Prefer `ghcrawl` first. Then use targeted GitHub keyword search to verify gaps, live status, comments, and candidates not present in the local store.
+- Use `--repo openclaw/openclaw` with `--match title,body` first when using `gh search`.
+- Add `--match comments` when triaging follow-up discussion or closed-as-duplicate chains.
 - Do not stop at the first 500 results when the task requires a full search.
 
 Examples:

.agents/skills/openclaw-qa-testing/SKILL.md

@@ -49,6 +49,19 @@ pnpm openclaw qa suite \
 5. If the user wants to watch the live UI, find the current `openclaw-qa` listen port and report `http://127.0.0.1:<port>`.
 6. If a scenario fails, fix the product or harness root cause, then rerun the full lane.
 
+## OTEL smoke
+
+For local QA-lab OpenTelemetry validation, use:
+
+```bash
+pnpm qa:otel:smoke
+```
+
+This starts a local OTLP/HTTP trace receiver, runs the `otel-trace-smoke`
+scenario through qa-channel, decodes the emitted protobuf spans, and verifies
+the exported trace names and privacy contract. It does not require Opik,
+Langfuse, or external collector credentials.
+
 ## QA credentials and 1Password
 
 - Use `op` only inside `tmux` for QA secret lookup in this repo.

.agents/skills/openclaw-release-maintainer/SKILL.md

@@ -202,10 +202,16 @@ Before tagging or publishing, run:
 pnpm check:architecture
 pnpm build
 pnpm ui:build
+pnpm qa:otel:smoke
 pnpm release:check
 pnpm test:install:smoke
 ```
 
+- Use `pnpm qa:otel:smoke` when release validation needs telemetry coverage.
+  It starts a local OTLP/HTTP trace receiver, runs QA-lab's
+  `otel-trace-smoke`, and checks span names plus content/identifier redaction
+  without external Opik or Langfuse credentials.
+
 For a non-root smoke path:
 
 ```bash

.github/workflows/docs-agent.yml

@@ -197,7 +197,8 @@ jobs:
 
       - name: Restore Node 24 path
         if: steps.gate.outputs.run_agent == 'true'
-        run: | # zizmor: ignore[github-env] NODE_BIN is set by the trusted local setup-node-env action in this same job
+        run:
+          | # zizmor: ignore[github-env] NODE_BIN is set by the trusted local setup-node-env action in this same job
           set -euo pipefail
           export PATH="${NODE_BIN}:${PATH}"
           echo "${NODE_BIN}" >> "$GITHUB_PATH"

.github/workflows/install-smoke.yml

@@ -114,7 +114,21 @@ jobs:
 
       - name: Run root Dockerfile CLI smoke
         run: |
-          docker run --rm --entrypoint sh openclaw-dockerfile-smoke:local -lc 'which openclaw && openclaw --version'
+          docker run --rm --entrypoint sh openclaw-dockerfile-smoke:local -lc '
+            which openclaw &&
+            openclaw --version &&
+            node -e "
+              const fs = require(\"node:fs\");
+              const path = require(\"node:path\");
+              const pkg = require(\"/app/package.json\");
+              for (const [dep, rel] of Object.entries(pkg.pnpm?.patchedDependencies ?? {})) {
+                const absolute = path.join(\"/app\", rel);
+                if (!fs.existsSync(absolute)) {
+                  throw new Error(`missing patch for ${dep}: ${rel}`);
+                }
+              }
+            "
+          '
 
       - name: Run agents delete shared workspace Docker CLI smoke
         env:

.github/workflows/test-performance-agent.yml

@@ -181,7 +181,8 @@ jobs:
 
       - name: Restore Node 24 path
         if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
-        run: | # zizmor: ignore[github-env] NODE_BIN is set by the trusted local setup-node-env action in this same job
+        run:
+          | # zizmor: ignore[github-env] NODE_BIN is set by the trusted local setup-node-env action in this same job
           set -euo pipefail
           export PATH="${NODE_BIN}:${PATH}"
           echo "${NODE_BIN}" >> "$GITHUB_PATH"

AGENTS.md

@@ -86,6 +86,13 @@ Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work.
   - public SDK/plugin contract: extension prod/test too
   - unknown root/config: all lanes
 - Before handoff/push: `pnpm check:changed`. Tests-only: `pnpm test:changed`. Full prod sweep: `pnpm check`.
+- Rebase sanity: after a green `pnpm check:changed`, a clean rebase onto current
+  `origin/main` does not require rerunning the full changed gate when the rebase
+  has no conflicts and the branch diff is materially unchanged. Do a quick
+  `git status`, `git diff --check`, and diff/stat sanity check; rerun targeted or
+  full checks only if conflict resolution, upstream overlap, generated drift,
+  dependency/config changes, or touched-file content changes make the prior
+  result stale.
 - Landing on `main`: verify touched surface near landing. Default feasible bar: `pnpm check` + `pnpm test`.
 - Hard build gate: `pnpm build` before push if build output, packaging, lazy/module boundaries, or published surfaces can change.
 - Do not land related failing format/lint/type/build/tests. If unrelated on latest `origin/main`, say so with scoped proof.
@@ -125,13 +132,16 @@ Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work.
 - Docs change with behavior/API. Use docs list/read_when hints; docs links per `docs/AGENTS.md`.
 - Changelog user-facing only; pure test/internal usually no entry.
 - Changelog placement: active version `### Changes`/`### Fixes`; every added entry must include at least one `Thanks @author` attribution, using credited GitHub username(s). Never add `Thanks @steipete`.
+- Changelog bullets are always single-line. No wrapping/continuation across multiple lines. Long entries stay on one long line so dedupe, PR-ref, and credit-audit tooling work and so the visual style stays uniform.
 
 ## Git
 
 - Commit via `scripts/committer "<msg>" <file...>`; stage intended files only. It formats staged files; still run gates.
 - Commits: conventional-ish, concise, grouped.
 - No manual stash/autostash unless explicit. No branch/worktree changes unless requested.
-- `main`: no merge commits; rebase on latest `origin/main` before push.
+- `main`: no merge commits; rebase on latest `origin/main` before push. Do not
+  keep chasing `main` with repeated full gates after one green run plus a clean
+  rebase sanity pass.
 - User says `commit`: your changes only. `commit all`: all changes in grouped chunks. `push`: may `git pull --rebase` first.
 - Do not delete/rename unexpected files; ask if blocking, else ignore.
 - Bulk PR close/reopen >5: ask with count/scope.

CHANGELOG.md

@@ -8,17 +8,15 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- Codex/agent: translate `--thinking minimal` to `low` for modern Codex models (gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.2) at request build time so the first turn is accepted instead of paying a wasted call + retry-with-low fallback. Older Codex models still receive `minimal` directly. Fixes #71946. Thanks @hclsys.
+- TTS/WhatsApp: add `/tts latest` read-aloud support with duplicate suppression and `/tts chat on|off|default` session-scoped auto-TTS overrides, completing the on-demand voice-note UX for current-chat replies. Fixes #66032.
 - Plugins/tokenjuice: bump the bundled tokenjuice runtime to 0.6.3. Thanks @vincentkoc.
-- Providers/Azure Speech: add Azure Speech as a bundled TTS provider with
-  Speech-resource auth, voice listing, SSML escaping, native Ogg/Opus
-  voice-note output, and telephony output. (#51776) Thanks @leonchui.
-- CLI/image generation: expose generic `--background` on
-  `openclaw infer image generate` and `openclaw infer image edit`, keep
-  `--openai-background` as an OpenAI alias, and let fal image generation honor
-  `--output-format png|jpeg`. Thanks @steipete.
-- Browser/config: allow local managed Chrome launch discovery and post-launch
-  CDP readiness timeouts to be raised for slower hosts such as Raspberry Pi.
-  Fixes #66803. Thanks @beat843796.
+- TTS/agents: allow `agents.list[].tts` to override global `messages.tts` for per-agent voices while keeping shared provider credentials and preferences in the existing TTS config surface.
+- TTS/agents: make `/tts audio`, `/tts status`, and the `tts` agent tool honor the active `agents.list[].tts` voice/provider override.
+- Providers/Azure Speech: add Azure Speech as a bundled TTS provider with Speech-resource auth, voice listing, SSML escaping, native Ogg/Opus voice-note output, and telephony output. (#51776) Thanks @leonchui.
+- Browser automation: add a CDP-native role snapshot fallback with iframe-aware refs, cursor-clickable detection, target attach preparation, and `openclaw browser doctor --deep` live snapshot probing.
+- CLI/image generation: expose generic `--background` on `openclaw infer image generate` and `openclaw infer image edit`, keep `--openai-background` as an OpenAI alias, and let fal image generation honor `--output-format png|jpeg`. Thanks @steipete.
+- Browser/config: allow local managed Chrome launch discovery and post-launch CDP readiness timeouts to be raised for slower hosts such as Raspberry Pi. Fixes #66803. Thanks @beat843796.
 - Discord: allow `channels.discord.voice.model` to override the LLM used for voice channel responses while keeping STT and TTS on their existing media settings. (#64368) Thanks @mrdavey.
 - Browser/CLI: add `openclaw browser start --headless` as a one-shot local managed browser launch override without rewriting persisted browser config. Thanks @BenediktSchackenberg.
 - CLI/Crestodian: open interactive Crestodian in the full OpenClaw TUI shell instead of a basic readline prompt.
@@ -28,12 +26,19 @@ Docs: https://docs.openclaw.ai
 - Diagnostics/OTEL: align model-call GenAI span attributes with OpenTelemetry stability opt-in semantics, keeping legacy `gen_ai.system` by default while emitting `gen_ai.provider.name` under `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`. Thanks @vincentkoc.
 - Diagnostics/OTEL: support signal-specific OTLP endpoint overrides for traces, metrics, and logs via config or standard OTEL environment variables. Thanks @vincentkoc.
 - Diagnostics/OTEL: emit bounded telemetry exporter health diagnostics for startup and log-export failures without exporting raw error text. Thanks @vincentkoc.
+- Diagnostics/OTEL: export agent harness lifecycle telemetry as bounded `openclaw.harness.run` spans and `openclaw.harness.duration_ms` metrics so QA-lab, Codex, and future harnesses share one trace shape. Thanks @vincentkoc.
 - Plugins/CLI: add `openclaw plugins registry` for explicit persisted-registry inspection and `--refresh` repair without making normal startup rescan plugin locations. Thanks @vincentkoc.
 - Plugins/CLI: make `openclaw plugins list` read the cold persisted registry snapshot by default, leaving module-aware diagnostics to `plugins doctor` and `plugins inspect`. Thanks @vincentkoc.
 - Plugins/startup: move gateway startup plugin planning onto the versioned cold registry index, with postinstall repair for older registry files that predate startup metadata. Thanks @vincentkoc.
 - Plugins/startup: normalize startup and provider plugin enablement through registry aliases so boot paths do not need the legacy manifest alias scan. Thanks @vincentkoc.
 - Providers/plugins: resolve provider ownership, provider discovery scopes, and catalog-hook provider ids from the cold plugin registry instead of rescanning manifests on those paths. Thanks @vincentkoc.
 - Plugins/registry: keep installed plugin index records focused on install/state/load paths and resolve plugin capabilities from manifests scoped to indexed plugins. Thanks @shakkernerd.
+- Plugins/registry: route cold manifest and capability lookups through the installed plugin index so setup, channels, config, secrets, doctor, and provider metadata paths avoid broad plugin-root scans before runtime execution. Thanks @shakkernerd.
+- CLI/models: speed up `models list --all --provider <id>` for static manifest-backed providers by loading catalog rows through the installed plugin index instead of broad manifest scans or runtime suppression hooks. Thanks @shakkernerd.
+- CLI/models: use OpenClaw Provider Index preview rows as the final cold fallback for installable providers, while keeping user config, installed manifests, and refreshed cache rows above provider-index metadata. Thanks @vincentkoc.
+- Providers/plugins: keep onboarding and auth-choice setup lists on cold manifest/install metadata and add Provider Index install metadata for not-yet-installed provider plugins. Thanks @vincentkoc.
+- Providers/plugins: keep provider setup guidance and configure auth imports on cold manifest metadata, with a regression guard against static provider-runtime imports on setup/configure list paths. Thanks @vincentkoc.
+- CLI/capabilities: keep capability command registration from importing the models auth runtime until `model auth login` actually runs. Thanks @vincentkoc.
 - Plugins/chat commands: refresh the persisted plugin registry after `/plugins enable` and `/plugins disable`, matching the CLI mutation path. Thanks @vincentkoc.
 - Plugins/compat: mark `OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY` as a deprecated break-glass switch and point operators at registry repair instead. Thanks @vincentkoc.
 - Plugins/registry: ignore stale persisted registry reads when plugin policy no longer matches current config, and stamp generated registry files with a do-not-edit warning. Thanks @vincentkoc.
@@ -43,6 +48,7 @@ Docs: https://docs.openclaw.ai
 - Diagnostics/OTEL: export existing tool-loop diagnostics as `openclaw.tool.loop` counters and spans without loop messages, session identifiers, params, or tool output. Thanks @vincentkoc.
 - Diagnostics/OTEL: export diagnostic memory samples and pressure as bounded memory histograms, counters, and pressure spans to help spot leak regressions without session or payload data. Thanks @vincentkoc.
 - Diagnostics/OTEL: add the GenAI `gen_ai.client.token.usage` histogram for input/output model usage while keeping session identifiers and aggregate cache counters out of the semantic metric. Thanks @vincentkoc.
+- Diagnostics/OTEL: add a bounded `openclaw.agent` label to OpenClaw token metrics so per-agent Grafana dashboards can group usage without exporting session identifiers. Thanks @oc-factus.
 - Plugins/install: consolidate managed plugin install metadata into the state-managed plugin index at `plugins/installs.json`, replacing the temporary `plugins/installed-index.json` path and removing `plugins.installs` as an authored config surface. Thanks @vincentkoc and @shakkernerd.
 - Diagnostics/OTEL: add the GenAI `gen_ai.client.operation.duration` histogram for model-call latency in seconds with bounded provider/model/API and error attributes. Thanks @vincentkoc.
 - Diagnostics/OTEL: add GenAI usage token attributes to model-usage spans, including cache read/write input token counts without session identifiers or prompt/response content. Thanks @vincentkoc.
@@ -61,254 +67,237 @@ Docs: https://docs.openclaw.ai
 - Providers/Volcengine: add Volcengine/BytePlus Seed Speech as a bundled TTS provider with API-key auth, native Ogg/Opus voice-note output, and MP3 audio-file output. (#55641) Thanks @xuruiray.
 - Android/Talk Mode: expose Talk Mode in the Voice tab with runtime-owned voice capture modes and microphone foreground-service escalation. Thanks @alex-latitude.
 - Providers/LiteLLM: register `litellm` as an image-generation provider so `image_generate model=litellm/...` calls and `agents.defaults.imageGenerationModel.fallbacks` entries resolve through the LiteLLM proxy. Thanks @zqchris.
-- Providers/fal: add Seedance 2.0 reference-to-video models with multi-image,
-  video, and audio reference input mapping plus model-specific capability limits
-  for `video_generate`. Thanks @shivanker.
+- Providers/fal: add Seedance 2.0 reference-to-video models with multi-image, video, and audio reference input mapping plus model-specific capability limits for `video_generate`. Thanks @shivanker.
 - Codex harness: require Codex app-server `0.125.0` or newer and cover native MCP `PreToolUse`, `PostToolUse`, and `PermissionRequest` payloads through the OpenClaw hook relay.
 - Agents/Codex: teach prompts and `agents_list` to surface native Codex app-server availability so agents prefer `/codex ...` over Codex ACP unless ACP/acpx is explicit. Thanks @vincentkoc.
-- ACPX/Droid: add Factory Droid to the live ACP bind Docker matrix, including
-  `.factory` settings staging, `FACTORY_API_KEY` forwarding, and the single-agent
-  `test:docker:live-acp-bind:droid` recipe.
+- ACPX/Droid: add Factory Droid to the live ACP bind Docker matrix, including `.factory` settings staging, `FACTORY_API_KEY` forwarding, and the single-agent `test:docker:live-acp-bind:droid` recipe.
+- TTS/personas: add provider-aware TTS personas with deterministic provider binding merges, `/tts persona` controls, gateway/CLI persona state, Google Gemini `audio-profile-v1` prompt wrapping, and OpenAI instruction mapping. (#70748) Thanks @barronlroth.
+- Voice Wake: add trigger-based routing so macOS voice wake phrases can select a configured agent or session target, with Gateway routing APIs and node update events. (#30354) Thanks @longbiaochen.
 
 ### Fixes
 
-- ACP: wait for the configured runtime backend to become healthy before startup
-  identity reconciliation, avoiding transient acpx warnings during Gateway boot.
-  Fixes #40566.
-- Control UI: hide the chat loading skeleton during background history reloads
-  when existing messages or active stream content are already visible, avoiding
-  reload flashes on high-latency local gateways. Fixes #71844. Thanks
-  @WolvenRA.
-- CLI/status: label the OpenClaw Serve/Funnel setting as `Tailscale exposure`
-  and show daemon state separately when available, so `gateway.tailscale.mode:
-"off"` no longer reads like the Tailscale daemon is stopped. Fixes #71790.
-  Thanks @pesvobodak.
-- Plugins/Bonjour: stop ciao mDNS watchdog failures from looping forever when
-  the advertiser stays stuck in `probing` or `announcing`; Bonjour now disables
-  itself for the current Gateway process after repeated failed restarts while
-  the Gateway keeps running. Fixes #69011. Thanks @siddharthaagarwalofficial-ux,
-  @FiredMosquito831, and @spikefcz.
-- Gateway/Fly.io: seed Control UI allowed origins from the actual runtime
-  bind and port so CLI-driven non-loopback starts do not crash before config
-  exists. Fixes #71823.
-- Gateway/proxy: bootstrap env proxy dispatching from direct Gateway startup
-  so provider and plugin network requests honor `HTTPS_PROXY`/`HTTP_PROXY`
-  before the first embedded agent attempt runs. (#71833) Thanks @mjamiv.
-- Models/LM Studio: preserve `@iq*` quant suffixes in model refs and provider
-  matching so `/model lmstudio/...@iq3_xxs` keeps the exact LM Studio variant.
-  Fixes #71474. (#71486) Thanks @Bartok9, @XinwuC, and @Sanjays2402.
-- Matrix/cron: preserve the live Matrix delivery target when creating implicit
-  announce reminder jobs so mixed-case room IDs are not reconstructed from
-  lowercased session keys. Fixes #71798.
-- Feishu: accept Schema 2.0 card action callbacks that report
-  `context.open_chat_id` instead of legacy `context.chat_id`, so button
-  callbacks no longer drop as malformed. Fixes #71670. Thanks @eddy1068.
-- Feishu: keep synthetic card-action and bot-menu ids out of platform reply
-  targets, using the real card callback message id when Feishu provides one and
-  plain-sending otherwise. Fixes #71673. Thanks @eddy1068.
-- Plugins/QQ Bot: prefer an installed QQ Bot plugin that declares it replaces
-  the bundled `qqbot` channel, preventing duplicate `qqbot_channel_api` and
-  `qqbot_remind` tool registration noise. Fixes #63102.
-- Browser automation: keep stable tab ids and labels attached when Chromium
-  replaces the raw target after form submissions or other action-triggered
-  navigations, and return the replacement `targetId` from `/act` when the match
-  is provable. Fixes #46137.
-- QQ Bot: make `qqbot_remind` schedule, list, and remove Gateway cron jobs
-  directly for owner-authorized senders instead of returning `cronParams` and
-  relying on a follow-up generic `cron` tool call. Fixes #70865. (#70937)
-  Thanks @GaosCode.
-- Agents/ACP: hide `sessions_spawn` ACP runtime options unless an ACP backend is
-  loaded, and make `/acp doctor` call out `plugins.allow` blocking bundled
-  `acpx`. Thanks @vincentkoc.
-- Media delivery: avoid sending generated image attachments twice when the
-  assistant reply already includes explicit `MEDIA:` lines for the same turn,
-  and reject unsafe remote `MEDIA:` URLs before delivery. Thanks @pashpashpash.
-- Codex harness: ignore retryable app-server error notifications after Codex
-  recovers, and preserve the real nested error message for terminal app-server
-  failures instead of replacing it with a generic failure. Thanks @pashpashpash.
-- Agents/subagents: keep queued subagent announces session-only when the
-  requester has no external channel target, avoiding ambiguous multi-channel
-  delivery failures. Fixes #59201. Thanks @larrylhollan.
-- Image understanding: preserve configured provider-prefixed vision model
-  metadata when callers request the model without the provider prefix, so custom
-  image models keep their `input: ["text", "image"]` capability. Fixes #33185.
-  Thanks @Kobe9312 and @vincentkoc.
+- Gateway/install: refresh loaded gateway service installs when the current service embeds stale gateway auth instead of returning already-installed, avoiding LaunchAgent token-mismatch loops after token rotation. Fixes #70752. Thanks @hyspacex.
+- Update: ignore bundled plugin `.openclaw-install-stage` directories during global install verification and packaged dist pruning so leftover runtime-dep staging files do not turn successful updates into `unexpected packaged dist file` failures. Fixes #71752. Thanks @waynegault.
+- Gateway/plugins: stop persisted WhatsApp auth state from activating bundled channel runtime-dependency repair during startup when `channels.whatsapp` is absent, avoiding npm/git stalls on packaged Linux installs. Fixes #71994. Thanks @xiao398008.
+- Gateway/device tokens: enforce caller-scope containment inside token rotation and revocation so pairing-only sessions cannot mutate higher-scope operator tokens. Fixes #71990. Thanks @coygeek.
+- CLI/model runs: keep `openclaw infer model run` on explicit OpenRouter models from loading the full provider catalog or inheriting chat-agent silent-reply policy, restoring non-empty one-shot probe output. Fixes #68791. Thanks @limpredator.
+- Installer/macOS: rerun Homebrew install steps without the gum spinner when raw-mode ioctl failures occur, and avoid claiming `node@24` was installed when the Homebrew keg binary is missing. Fixes #70411. Thanks @1fanwang and @dad-io.
+- Installer: load nvm before Node.js detection so `curl | bash` installs respect nvm-managed Node instead of stale system Node. Fixes #49556. Thanks @heavenlxj.
+- Installer/Windows: route PowerShell install failures through a top-level handler so `iwr ... | iex` returns control to the current shell while direct script-file runs still exit non-zero. Fixes #38054. Thanks @PwrSrg.
+- CLI/Volta: respawn raw `openclaw` CLI runs through the named `node` shim when the current Node executable resolves to `volta-shim`, avoiding direct shim execution failures in non-interactive shells. Fixes #68672. Thanks @sanchezm86.
+- Installer: warn when multiple npm global roots contain OpenClaw installs, showing active Node/npm/openclaw plus each install path and version so stale version-manager installs are visible. Fixes #40839. Thanks @zhixianio.
+- Cron/tasks: recover completed cron task ledger records from durable run logs and job state before marking them `lost`, reducing false `backing session missing` audit errors for isolated cron runs and keeping offline CLI audit from treating its empty local cron active-job set as authoritative. Fixes #71963.
+- Docker: copy patched dependency files into runtime images so downstream `pnpm install` layers keep working. Fixes #69224. Thanks @gucasbrg.
+- Agents/runtime: submit heartbeat, cron, and exec wakeups as transient runtime context instead of visible user prompts, keeping synthetic system work out of chat transcripts. Fixes #66496 and #66814. Thanks @jeades and @mandomaker.
+- Telegram: include native quote excerpts automatically for threaded replies and reply tags when the original Telegram text is available, without adding another config knob. Fixes #6975. Thanks @rex05ai.
+- Node/Linux: make `openclaw node install` enable and restart the `openclaw-node` systemd unit instead of the gateway unit on node-only VMs. Fixes #68287. Thanks @dlebee-agent.
+- Browser/CDP: retry transient raw-CDP WebSocket handshake failures before any
+  browser command is sent, and reconnect stale persistent Playwright CDP
+  sessions for safe tab-list reads without replaying mutating browser actions.
+  Fixes #67728.
+- Gateway/Linux: retry `systemctl --user enable` after a second daemon reload when the freshly written gateway unit is not visible yet on migrated systemd installs. Fixes #65184. Thanks @liushuaiiu.
+- Telegram: preserve exact selected quote text when sending native quote replies, and retry with legacy replies if Telegram rejects quote parameters. (#71952) Thanks @rubencu.
+- Plugins/CLI: preserve manifest name, description, format, and source metadata in cold `openclaw plugins list` output without importing plugin runtime. Thanks @shakkernerd.
+- Security/audit: read channel exposure and plugin allowlist ownership from read-only plugin index metadata so cold audits do not depend on loaded channel runtime. Thanks @shakkernerd.
+- Plugins/chat: keep `/plugins list`, `/plugins enable`, and `/plugins disable` on the persisted plugin index path so chat plugin management does not load diagnostic/runtime plugin registries before execution. Thanks @shakkernerd.
+- Plugins/doctor: read workspace plugin status and legacy web-search ownership through installed-index manifest metadata instead of broad manifest registry scans. Thanks @shakkernerd.
+- CLI/agents: read channel provider status from read-only plugin index metadata for text `agents list` output instead of the loaded channel registry. Thanks @shakkernerd.
+- Logging: redact configured secret patterns at console and file-log sink exits
+  so credentials that reach the logger are masked before terminal display or
+  JSONL persistence. Fixes #67953. Thanks @Ziy1-Tan.
+- Gateway/services: refuse process and service mutations from an older OpenClaw
+  binary when the config was last written by a newer version, preventing
+  split-brain installs from stopping or rewriting newer gateway services. Fixes
+  #57079.
+- Gateway: reserve `/healthz` and `/readyz` ahead of plugin, canvas, and Control UI HTTP stages so liveness/readiness probes still answer when a later route handler stalls. Fixes #69674. Thanks @Xike-Creek.
+- Logging: load `logging.file` and redaction settings directly from the active
+  OpenClaw config path in bundled runtimes, so packaged gateways stop falling
+  back to `/tmp/openclaw`. Fixes #59370, #67168, and #61295. Thanks @KeaneYan,
+  @Pan9hu, and @zsjlovelike.
+- Logging: rotate file logs at `logging.maxFileBytes`, keep bounded numbered
+  archives, and make long-lived rolling loggers follow the current-day file
+  instead of suppressing diagnostics or writing stale dated files. Fixes #58583
+  and #62381. Thanks @jpeghead and @zhaoleink.
+- Agents/groups: treat clean empty assistant stops as silent `NO_REPLY` only for always-on groups where silent replies are allowed, while keeping direct and mention-gated sessions on the incomplete-turn retry path. Thanks @MagnaAI.
+- macOS/Node: keep native remote app nodes from advertising `browser.proxy`,
+  start browser-capable CLI node services through the restored
+  `openclaw node start` command, and show an actionable browser-control error
+  when the local control service is missing. Fixes #66637.
+- Gateway/update: fail package updates when the restarted managed gateway reports the wrong version, including fallback restarts and JSON mode, avoiding false-success mixed-version restarts after macOS LaunchAgent updates. Fixes #71835. Thanks @abhinas90 and @jsompis.
+- Gateway/update: warn before package updates and bundled plugin runtime-dependency repairs when the target volume appears low on disk space, without blocking installs on best-effort filesystem checks. Fixes #71835. Thanks @abhinas90 and @jsompis.
+- Plugins/runtime deps: surface activated plugin load failures in health and fail package-update restart verification or doctor repair when bundled runtime deps still cannot load, avoiding false-success repairs. (#71883) Thanks @Solvely-Colin.
+- Gateway/Linux: include fnm `aliases/default/bin` in generated service PATHs and let doctor accept either modern fnm aliases or the legacy `current/bin` symlink, avoiding false PATH repair prompts. Fixes #68169. Thanks @richard-scott.
+- Installer/Linux: run apt installs with noninteractive dpkg and needrestart settings so fresh Ubuntu 24.04 `curl | bash` installs do not hang while installing Node.js, Git, or build tools. Fixes #41146. Thanks @iht76, @alexcarv318, @cs3gallery, @firofame, and @cgdusek.
+- Providers/Bedrock: defer the AWS SDK import until Bedrock discovery actually runs so plugin registration and setup stay lightweight on cold start. Fixes #71690. Thanks @jarvis-ai-gregmoser.
+- Installer/macOS: stop immediately when Homebrew `node@24` installation fails and avoid printing PATH advice for missing Homebrew Node installs. Fixes #70411. Thanks @1fanwang.
+- WhatsApp: remove ack reactions after a visible reply when `messages.removeAckAfterReply` is enabled, matching other reaction-capable channels. Fixes #26183. Thanks @MrUnforsaken.
+- Providers/Z.AI: map OpenClaw thinking controls to Z.AI's `thinking` payload and add opt-in preserved thinking replay via `params.preserveThinking`, so GLM 5.x can keep prior `reasoning_content` when requested. Fixes #58680. Thanks @xuanmingguo.
+- Channels/status: keep read-only channel lists on manifest and package metadata by default, loading setup runtime only for explicit fallback callers. Thanks @shakkernerd.
+- Plugins: scope setup and web-provider metadata manifest reads to explicit plugin ids when callers already know the owning plugin set. Thanks @vincentkoc.
+- Plugins/onboarding: defer onboarding install-record index writes until the guarded config commit so setup failures cannot leave the plugin index ahead of `openclaw.json`. Thanks @shakkernerd.
+- Plugins/registry: resolve web provider ownership from the installed plugin index instead of broad manifest scans on secret, tool, and pricing paths. Thanks @shakkernerd.
+- Config/providers: accept `video` and `audio` in configured model `input` values and
+  preserve them in provider catalog entries. Fixes #20721. Thanks @alvinttang.
+- Models/auth: honor the parent `--agent` flag for auth write commands (`add`, `login`, `setup-token`, `paste-token`, and the GitHub Copilot shortcut) so OAuth/API-key/token results are written to the requested agent store instead of the default agent. Fixes #71864. (#71933) Thanks @balric-seo.
+- TTS: strip model-emitted TTS directives from streamed block text before channel
+  delivery, including directives split across adjacent blocks, while preserving
+  the accumulated raw reply for final-mode synthesis. Fixes #38937.
+- TTS: keep explicit `provider=...` directive keys scoped to that provider and
+  warn on unsupported keys instead of letting another speech provider consume
+  overlapping keys. Fixes #60131.
+- TTS/Feishu: normalize final-mode streamed TTS-only audio before delivery so
+  generated voice-note files use the same safe media path and native voice
+  routing as normal final replies. Fixes #71920.
+- Feishu: transcribe inbound voice-note audio with the shared media audio path
+  before agent dispatch and keep raw Feishu `file_key` payloads out of message
+  text. Fixes #67120 and #61876.
+- Tasks: terminalize async Gateway agent task records from the Gateway run result while preserving aborted, failed, and cancelled outcomes instead of leaving completed runs stuck as active or lost. (#71905) Thanks @likewen-tech.
+- WhatsApp: let authorized group voice-note transcripts satisfy mention gating
+  before reply dispatch, while keeping unmentioned transcripts in pending group
+  history. Fixes #44908.
+- Media understanding: carry channel voice-note preflight state into attachment
+  selection so WhatsApp, Feishu, Telegram, and Discord do not transcribe the
+  same inbound audio twice. Fixes #70580.
+- TTS/BlueBubbles: deliver compatible auto-TTS audio as iMessage voice memo
+  bubbles instead of plain MP3/CAF file attachments. Fixes #16848.
+- TTS: resolve voice-note and voice-memo routing from channel plugin
+  capabilities instead of speech-core-owned channel id lists.
+- ACP: send subagent and async-task completion wakes to external ACP harnesses as
+  plain prompts instead of OpenClaw internal runtime-context envelopes, while
+  keeping those envelopes out of ACP transcripts.
+- TTS/status: show configured TTS model, voice, and sanitized custom endpoint in `/status`, preserve OpenAI-compatible TTS instructions on custom endpoints, and retry empty Microsoft/Edge TTS output once. Addresses #46602, #47232, and #43936. Thanks @leekuangtao, @Huntterxx, and @rex993.
+- Agents/Gateway: steer agent-driven config edits and restarts through the owner-only `gateway` tool, document `config.schema.lookup` as the field-doc source, and warn against using `gateway stop && gateway start` as a restart substitute on macOS. Fixes #71929. Thanks @ygc3817922006-sketch.
+- Media understanding/audio: inject a deterministic transcript placeholder for too-small voice notes so agents do not hallucinate transcription or provider failures. Fixes #48944. Thanks @eulicesl.
+- Providers/vLLM: send Nemotron 3 chat-template kwargs when thinking is off
+  and honor configured `params.chat_template_kwargs` for OpenAI-compatible
+  completions, so vLLM/Nemotron replies stay visible instead of becoming
+  thinking-only. Fixes #71891. Thanks @jmystaki-create and @dennis-lynch.
+- Channels/replies: strip copied inbound metadata blocks from user-facing
+  assistant replies and model replay history, so Discord/vLLM sessions do not
+  leak `Conversation info` / `UNTRUSTED ... message body` envelopes after a
+  model echoes them. Fixes #71847. Thanks @jmystaki-create.
+- Subagents/memory: keep inter-session completion wakes out of memory and
+  dreaming session exports, and strip internal runtime-context blocks from
+  realtime Control UI chat events.
+- Agents/Claude: treat zero-token empty `stop` turns as failed provider output,
+  retry once, repair replay, and allow configured model fallback instead of
+  preserving them as successful silent replies. Fixes #71880. Thanks @MagnaAI.
+- Tasks: normalize task lifecycle timestamps at create, update, and restore time, and report retained lost tasks as audit warnings until their cleanup window expires. (#71871) Thanks @likewen-tech.
+- Diagnostics/OTEL: treat normal early model stream cleanup as a completed model call instead of exporting a misleading `StreamAbandoned` error span. Thanks @vincentkoc.
+- Gateway/pairing: stop corrupt or unreadable device/node pairing stores from being treated as empty state, preserving `paired.json` for repair instead of overwriting approved pairings. Fixes #71873. Thanks @iret77.
+- ACP: keep `/acp` management commands, plus local `/status` and `/unfocus`, on the Gateway path inside ACP-bound threads so they are not consumed as ACP prompt text. Fixes #66298. Thanks @kindomLee.
+- ACPX: stop probing ACP agents during normal Gateway startup; the embedded backend now registers without spawning Codex/ACP child processes unless `OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=1` is explicitly set.
+- CLI/image edit: accept `--size`, `--aspect-ratio`, and `--resolution` on `openclaw infer image edit` and report all supported edit flags from `capability inspect image.edit`. Thanks @Pinghuachiu.
+- ACP: wait for the configured runtime backend to become healthy before startup identity reconciliation, avoiding transient acpx warnings during Gateway boot. Fixes #40566.
+- Channels/ACP bindings: time out configured binding readiness checks instead of letting Discord preflight hang forever when an ACP target never settles. Fixes #68776.
+- Control UI: hide the chat loading skeleton during background history reloads when existing messages or active stream content are already visible, avoiding reload flashes on high-latency local gateways. Fixes #71844. Thanks @WolvenRA.
+- Control UI: keep locally optimistic chat messages visible when a history reload temporarily returns empty, avoiding lost first-turn messages on high-latency gateways. Fixes #71878. Thanks @WolvenRA.
+- Control UI: keep chat history limits based on visible messages after filtering heartbeat and control-only transcript rows, so recent hidden entries no longer make older visible replies disappear. Thanks @WolvenRA.
+- Agents/images: scrub old `[media attached: ...]`, `[Image: source: ...]`,
+  and `media://inbound/...` markers from pruned model replay context so stale
+  media refs are not rehydrated as fresh prompt images. Fixes #71868. Thanks
+  @jmeadlock.
+- Docker/Bonjour: disable Bonjour/mDNS advertising by default for bundled
+  Compose gateways on bridge networking, while keeping host/macvlan opt-in with
+  `OPENCLAW_DISABLE_BONJOUR=0`. Fixes #71879. Thanks @gbballpack.
+- CLI/status: label the OpenClaw Serve/Funnel setting as `Tailscale exposure` and show daemon state separately when available, so `gateway.tailscale.mode: "off"` no longer reads like the Tailscale daemon is stopped. Fixes #71790. Thanks @pesvobodak.
+- Plugins/Bonjour: stop ciao mDNS watchdog failures from looping forever when the advertiser stays stuck in `probing` or `announcing`; Bonjour now disables itself for the current Gateway process after repeated failed restarts while the Gateway keeps running. Fixes #69011. Thanks @siddharthaagarwalofficial-ux, @FiredMosquito831, and @spikefcz.
+- Gateway/Fly.io: seed Control UI allowed origins from the actual runtime bind and port so CLI-driven non-loopback starts do not crash before config exists. Fixes #71823.
+- macOS/remote SSH: keep discovered gateway hosts in `gateway.remote.sshTarget` while pinning SSH transport URLs to the local loopback tunnel, so browser automation does not regress into blocked non-loopback `ws://` endpoints. Fixes #67336.
+- Gateway/proxy: bootstrap env proxy dispatching from direct Gateway startup so provider and plugin network requests honor `HTTPS_PROXY`/`HTTP_PROXY` before the first embedded agent attempt runs. (#71833) Thanks @mjamiv.
+- Plugins/runtime deps: verify clean npm installs actually place requested bundled runtime packages in the managed install root, reporting exact missing specs instead of a false successful repair. (#71883) Thanks @Solvely-Colin.
+- Plugins/discovery: ignore stale `plugins.load.paths` aliases that point back at packaged bundled plugin directories and have doctor remove them, keeping bundled plugins on the runtime-deps staging path. Thanks @codex.
+- Models/LM Studio: preserve `@iq*` quant suffixes in model refs and provider matching so `/model lmstudio/...@iq3_xxs` keeps the exact LM Studio variant. Fixes #71474. (#71486) Thanks @Bartok9, @XinwuC, and @Sanjays2402.
+- Matrix/cron: preserve the live Matrix delivery target when creating implicit announce reminder jobs so mixed-case room IDs are not reconstructed from lowercased session keys. Fixes #71798.
+- Feishu: accept Schema 2.0 card action callbacks that report `context.open_chat_id` instead of legacy `context.chat_id`, so button callbacks no longer drop as malformed. Fixes #71670. Thanks @eddy1068.
+- Feishu: keep synthetic card-action and bot-menu ids out of platform reply targets, using the real card callback message id when Feishu provides one and plain-sending otherwise. Fixes #71673. Thanks @eddy1068.
+- Plugins/QQ Bot: prefer an installed QQ Bot plugin that declares it replaces the bundled `qqbot` channel, preventing duplicate `qqbot_channel_api` and `qqbot_remind` tool registration noise. Fixes #63102.
+- Browser automation: keep stable tab ids and labels attached when Chromium replaces the raw target after form submissions or other action-triggered navigations, and return the replacement `targetId` from `/act` when the match is provable. Fixes #46137.
+- QQ Bot: make `qqbot_remind` schedule, list, and remove Gateway cron jobs directly for owner-authorized senders instead of returning `cronParams` and relying on a follow-up generic `cron` tool call. Fixes #70865. (#70937) Thanks @GaosCode.
+- Agents/ACP: hide `sessions_spawn` ACP runtime options unless an ACP backend is loaded, and make `/acp doctor` call out `plugins.allow` blocking bundled `acpx`. Thanks @vincentkoc.
+- Agents/Codex: keep ACP prompt/skill routing hidden unless an ACP runtime backend is available, and warn in doctor when enabled Codex plugin configs still route `openai-codex/*` models through PI. Thanks @vincentkoc.
+- Media delivery: avoid sending generated image attachments twice when the assistant reply already includes explicit `MEDIA:` lines for the same turn, and reject unsafe remote `MEDIA:` URLs before delivery. Thanks @pashpashpash.
+- Codex harness: ignore retryable app-server error notifications after Codex recovers, and preserve the real nested error message for terminal app-server failures instead of replacing it with a generic failure. Thanks @pashpashpash.
+- Agents/Codex: prepare native Codex sub-agent session metadata without a
+  nested Gateway session patch and add a focused Docker smoke for the app-server
+  sub-agent path. Thanks @vincentkoc.
+- Agents/subagents: keep queued subagent announces session-only when the requester has no external channel target, avoiding ambiguous multi-channel delivery failures. Fixes #59201. Thanks @larrylhollan.
+- Image understanding: preserve configured provider-prefixed vision model metadata when callers request the model without the provider prefix, so custom image models keep their `input: ["text", "image"]` capability. Fixes #33185. Thanks @Kobe9312 and @vincentkoc.
 - Plugins/install: restore the previous plugin index records if a concurrent config write conflict interrupts install, update, or uninstall metadata commits. Thanks @shakkernerd.
+- Plugins/install: reject native plugin archives that do not include a valid `openclaw.plugin.json`, preventing manifestless archives from writing install records that later show missing-manifest diagnostics. Thanks @shakkernerd.
+- Plugins/uninstall: remove tracked managed plugin install directories even when the persisted install path differs from the default id-derived target, while still refusing deletes outside the managed extensions root. Thanks @shakkernerd.
 - Plugins/update: restore previous plugin index records if core update or channel setup hits a concurrent config write conflict after plugin metadata changes. Thanks @shakkernerd.
 - Plugins/onboarding: defer channel/provider plugin install records until the owning config write commits, keeping setup failures from advancing the plugin index ahead of `openclaw.json`. Thanks @shakkernerd.
 - Plugins/config: route configure and agent setup writes with pending plugin install records through the plugin index commit helper so provider onboarding metadata is not stripped by plain config writes. Thanks @shakkernerd.
-- Sessions: keep embedded runtime context out of the visible user prompt by
-  sending it as a hidden next-turn custom message, and teach doctor to repair
-  affected 2026.4.24 transcripts with duplicated prompt-rewrite branches.
-  Fixes #71761.
-- Gateway/subagents: keep direct-loopback backend RPCs authenticated with the
-  shared gateway token/password off stale CLI paired-device scope baselines, so
-  internal calls no longer hit `scope-upgrade` pairing prompts while remote,
-  browser, node, device-token, and explicit-device paths still require normal
-  pairing approval. Fixes #63548.
-- Providers/Azure OpenAI: give deployment-scoped image generation requests a
-  longer 600s default timeout so slow `gpt-image-2` generations can complete
-  without a per-call `timeoutMs`. Fixes #71705. Thanks @voytas75.
-- Gateway/plugins: link source-checkout bundled runtime dependency caches instead
-  of recursively copying `node_modules` on the gateway main thread, preventing
-  local status, node, and skill probes from timing out during startup cache
-  restores. Thanks @steipete.
-- Skills/remote nodes: only expose remote macOS skill bins for connected nodes,
-  clear stale bin matches when node probes fail, and include probe command,
-  timeout, bin count, and connection state in timeout logs. Thanks @steipete.
-- CLI/gateway: keep diagnostic probes from creating first-time read-only device
-  pairings, while still reusing cached device tokens for detailed read probes.
-  Fixes #71766. Thanks @SunboZ.
-- CLI/plugins: keep `message` startup, `channels logs`, `agents delete`, and
-  `agents set-identity` off broad plugin preloading; message delivery still
-  loads plugins when the action actually runs.
-- Image understanding: resolve configured image models such as local LM Studio
-  vision entries before reporting `Unknown model` when the discovery registry
-  has not registered that provider. Fixes #66486. Thanks @zhanggpcsu.
-- Sessions: separate reset freshness from session-store `updatedAt`, so
-  heartbeat, cron, exec, and gateway bookkeeping no longer prevent configured
-  daily/idle resets from rolling long-running channel sessions. Fixes #68315,
-  #63732, #63820, and #69083. Thanks @maxatv, @longhairedsi, @bradfreels,
-  and @akessel56.
-- CLI/agents: keep `agents bind`, `agents unbind`, and `agents bindings` on
-  setup-safe channel metadata paths so they do not preload bundled plugin
-  runtimes or stage runtime dependencies. Fixes #71743.
+- Plugins/channels: merge pending channel plugin install records with the existing plugin index before config writes, preserving unrelated tracked installs during channel setup, resolve, remove, and capability repair flows. Thanks @shakkernerd.
+- Plugins/config: defer shipped `plugins.installs` index migration during config writes until the guarded config commit window and roll it back if the config write fails before commit. Thanks @shakkernerd.
+- Sessions: keep embedded runtime context out of the visible user prompt by sending it as a hidden next-turn custom message, and teach doctor to repair affected 2026.4.24 transcripts with duplicated prompt-rewrite branches. Fixes #71761.
+- Gateway/subagents: keep direct-loopback backend RPCs authenticated with the shared gateway token/password off stale CLI paired-device scope baselines, so internal calls no longer hit `scope-upgrade` pairing prompts while remote, browser, node, device-token, and explicit-device paths still require normal pairing approval. Fixes #63548.
+- Providers/Azure OpenAI: give deployment-scoped image generation requests a longer 600s default timeout so slow `gpt-image-2` generations can complete without a per-call `timeoutMs`. Fixes #71705. Thanks @voytas75.
+- Gateway/plugins: link source-checkout bundled runtime dependency caches instead of recursively copying `node_modules` on the gateway main thread, preventing local status, node, and skill probes from timing out during startup cache restores. Thanks @steipete.
+- Skills/remote nodes: only expose remote macOS skill bins for connected nodes, clear stale bin matches when node probes fail, and include probe command, timeout, bin count, and connection state in timeout logs. Thanks @steipete.
+- Skills/remote nodes: recognize `system.which` object-map responses when probing connected macOS nodes, so Linux gateways can expose macOS-only skills such as Apple Notes when the required binaries are installed remotely. Fixes #71877. Thanks @miguelarios.
+- CLI/gateway: keep diagnostic probes from creating first-time read-only device pairings, while still reusing cached device tokens for detailed read probes. Fixes #71766. Thanks @SunboZ.
+- CLI/plugins: keep `message` startup, `channels logs`, `agents delete`, and `agents set-identity` off broad plugin preloading; message delivery still loads plugins when the action actually runs.
+- Image understanding: resolve configured image models such as local LM Studio vision entries before reporting `Unknown model` when the discovery registry has not registered that provider. Fixes #66486. Thanks @zhanggpcsu.
+- QQ Bot: ignore self-echoed bot messages using the outbound ref-index marker, preventing mirrored replies from re-entering the agent loop while still allowing users to quote bot replies. Fixes #71912. Thanks @wangyc6003.
+- Sessions: separate reset freshness from session-store `updatedAt`, so heartbeat, cron, exec, and gateway bookkeeping no longer prevent configured daily/idle resets from rolling long-running channel sessions. Fixes #68315, #63732, #63820, and #69083. Thanks @maxatv, @longhairedsi, @bradfreels, and @akessel56.
+- Sessions: clear queued system-event notices during `/new`, `/reset`, gateway `sessions.reset`, and daily/idle rollover so stale background updates cannot leak into the first prompt of the fresh session. Fixes #66864. Thanks @opeyio, @Magicray1217, and @cedillarack.
+- CLI/agents: keep `agents bind`, `agents unbind`, and `agents bindings` on setup-safe channel metadata paths so they do not preload bundled plugin runtimes or stage runtime dependencies. Fixes #71743.
 - Plugins/registry: preserve explicit disabled plugin records during registry migration without persisting every unused bundled plugin discovered on disk. Thanks @shakkernerd.
-- Windows/native: keep CLI startup and bundled provider plugin loading off
-  Windows ESM raw-path failure paths, fixing native onboarding/install smoke on
-  Node 24. Thanks @steipete.
-- Plugins/doctor: read bundled channel doctor capabilities through the same
-  packaged plugin directory resolver used by plugin loading, so published
-  installs keep Matrix DM allowlist repairs on `channels.matrix.dm.*` instead
-  of writing invalid top-level `dmPolicy` keys. Fixes #71757.
-- Plugins/Windows: keep bundled plugin Jiti loaders off the native import path
-  on Windows so channel plugins such as Telegram no longer crash with
-  `ERR_UNSUPPORTED_ESM_URL_SCHEME` on `C:\...` paths. Fixes #71749. Thanks
-  @smeyer9.
-- Providers/Ollama: use Ollama's current `/api/web_search` endpoint and honor
-  `https://ollama.com` model-provider base URLs for Ollama Web Search. Fixes
-  #71741. Thanks @madhvidua.
-- Memory/Ollama: serialize Ollama memory embedding batches and add an inline
-  batch timeout override, with longer defaults for local/self-hosted embedding
-  providers. Thanks @steipete.
-- Sessions/usage: exclude compaction checkpoint transcript snapshots from usage
-  totals and session discovery, while keeping old checkpoint files removable.
-  Thanks @steipete.
-- CLI/agents: keep `openclaw agents list --json` on the config-only path by
-  default, avoiding bundled plugin loading unless callers request
-  `--bindings`. Fixes #71739. Thanks @kaloster.
-- Plugins/install: force plugin dependency installs to stay project-local even
-  when inherited npm config requests global installs, so successful installs
-  still materialize the plugin's staged `node_modules`.
-- Providers/Google: transcode Gemini TTS PCM to Opus for voice-note targets so
-  WhatsApp and other native voice-note replies can play as voice messages.
-- Plugins/runtime deps: reuse existing external bundled-plugin stage roots when
-  mirrored plugin roots are inspected again, avoiding second-generation
-  `openclaw-unknown-*` stages and repeated first-turn restaging. Fixes #71599.
-- iOS/macOS Talk Mode: allow `talk.speechLocale` to set the speech
-  recognition locale for non-English voice conversations. Fixes #44688.
-- Plugins/providers: honor explicit plugin candidate lists instead of reading a
-  persisted registry snapshot from local state, keeping candidate-scoped
-  provider discovery hermetic.
-- Plugins/doctor: keep bundled plugin runtime-dependency repairs inside the
-  managed OpenClaw stage even when user npm prefix/global config points npm at
-  `$HOME/node_modules`. Fixes #71730.
-- ACP/sessions_spawn: reject normal OpenClaw config agent ids when callers
-  explicitly request `runtime="acp"`, while allowing agents configured with
-  `runtime.type="acp"` to resolve to their ACP harness id. Fixes #63914.
-- ACP/sessions_spawn: apply `runTimeoutSeconds` to ACP child turns and dispatch
-  those turns on the background subagent lane, so quota-stalled ACP harnesses do
-  not occupy the main agent lane indefinitely. Fixes #68823.
-- ACP/oneshot: reconcile runtime session identity before closing completed
-  oneshot ACP runs, so finished `sessions.json` entries do not stay stuck with
-  `acp.identity.state="pending"`.
-- ACPX: bundle `acpx@0.6.1` so unsupported generic model overrides fail
-  clearly instead of silently falling back to the target adapter default.
-- ACP/models: document that non-Codex ACP model overrides require adapter
-  support for ACP `models` plus `session/set_model`, so unsupported harnesses
-  fail clearly instead of silently falling back to their defaults.
-- Plugins/Voice Call: treat missing provider credentials as setup-incomplete
-  during Gateway startup and log the missing keys as a warning instead of a
-  runtime startup error, while keeping explicit command/tool errors when used. Thanks
-  @steipete.
-- Android/Talk Mode: prevent duplicate TTS playback when fast or repeated final
-  chat events arrive while Talk Mode is waiting for its own response. Fixes #46546.
-- Tooling/check:changed: pass parent heavy-check lock markers to lint lanes so
-  `pnpm check:changed` no longer waits on its own `lint:extensions` child.
-  Thanks @steipete.
-- CLI/completion: dedupe provider auth flags before registering `openclaw onboard`
-  options, so completion-cache refresh during update no longer fails when stale
-  core fallback flags overlap plugin manifest flags. Fixes #71667.
-- Diagnostics/trace: report live context usage from the current prompt snapshot
-  instead of provider turn totals, avoiding false near-full context spikes on
-  cached or tool-heavy runs.
-- Providers/Google: honor `models.providers.google.request.allowPrivateNetwork`
-  for Gemini TTS and telephony TTS, matching Google image generation and media
-  understanding. (#71723) Thanks @ro-hansolo.
-- Providers/MiniMax: register `minimax-portal` for music and video generation,
-  preserving OAuth auth and regional MiniMax base URLs across the shared
-  `music_generate` and `video_generate` tools. (#63241) Thanks @tars90percent.
-- Providers/onboarding: keep Runway and Alibaba Model Studio out of the
-  text-inference setup picker by scoping their video-generation auth choices to
-  the media setup flow. (#65856) Thanks @Jah-yee.
+- Windows/native: keep CLI startup and bundled provider plugin loading off Windows ESM raw-path failure paths, fixing native onboarding/install smoke on Node 24. Thanks @steipete.
+- Plugins/doctor: read bundled channel doctor capabilities through the same packaged plugin directory resolver used by plugin loading, so published installs keep Matrix DM allowlist repairs on `channels.matrix.dm.*` instead of writing invalid top-level `dmPolicy` keys. Fixes #71757.
+- Plugins/Windows: keep bundled plugin Jiti loaders off the native import path on Windows so channel plugins such as Telegram no longer crash with `ERR_UNSUPPORTED_ESM_URL_SCHEME` on `C:\...` paths. Fixes #71749. Thanks @smeyer9.
+- Providers/Ollama: use Ollama's current `/api/web_search` endpoint and honor `https://ollama.com` model-provider base URLs for Ollama Web Search. Fixes #71741. Thanks @madhvidua.
+- Memory/Ollama: serialize Ollama memory embedding batches and add an inline batch timeout override, with longer defaults for local/self-hosted embedding providers. Thanks @steipete.
+- Sessions/usage: exclude compaction checkpoint transcript snapshots from usage totals and session discovery, while keeping old checkpoint files removable. Thanks @steipete.
+- CLI/agents: keep `openclaw agents list --json` on the config-only path by default, avoiding bundled plugin loading unless callers request `--bindings`. Fixes #71739. Thanks @kaloster.
+- Plugins/install: force plugin dependency installs to stay project-local even when inherited npm config requests global installs, so successful installs still materialize the plugin's staged `node_modules`.
+- Providers/Google: transcode Gemini TTS PCM to Opus for voice-note targets so WhatsApp and other native voice-note replies can play as voice messages.
+- TTS/WhatsApp: mark non-Opus provider output as voice-note intent so channel delivery transcodes MP3/WebM replies to Ogg/Opus PTT audio.
+- Plugins/runtime deps: reuse existing external bundled-plugin stage roots when mirrored plugin roots are inspected again, avoiding second-generation `openclaw-unknown-*` stages and repeated first-turn restaging. Fixes #71599.
+- iOS/macOS Talk Mode: allow `talk.speechLocale` to set the speech recognition locale for non-English voice conversations. Fixes #44688.
+- Plugins/providers: honor explicit plugin candidate lists instead of reading a persisted registry snapshot from local state, keeping candidate-scoped provider discovery hermetic.
+- Plugins/doctor: keep bundled plugin runtime-dependency repairs inside the managed OpenClaw stage even when user npm prefix/global config points npm at `$HOME/node_modules`. Fixes #71730.
+- ACP/sessions_spawn: reject normal OpenClaw config agent ids when callers explicitly request `runtime="acp"`, while allowing agents configured with `runtime.type="acp"` to resolve to their ACP harness id. Fixes #63914.
+- ACP/sessions_spawn: apply `runTimeoutSeconds` to ACP child turns and dispatch those turns on the background subagent lane, so quota-stalled ACP harnesses do not occupy the main agent lane indefinitely. Fixes #68823.
+- ACP/oneshot: reconcile runtime session identity before closing completed oneshot ACP runs, so finished `sessions.json` entries do not stay stuck with `acp.identity.state="pending"`.
+- ACPX: bundle `acpx@0.6.1` so unsupported generic model overrides fail clearly instead of silently falling back to the target adapter default.
+- ACP/models: document that non-Codex ACP model overrides require adapter support for ACP `models` plus `session/set_model`, so unsupported harnesses fail clearly instead of silently falling back to their defaults.
+- Plugins/Voice Call: treat missing provider credentials as setup-incomplete during Gateway startup and log the missing keys as a warning instead of a runtime startup error, while keeping explicit command/tool errors when used. Thanks @steipete.
+- Android/Talk Mode: prevent duplicate TTS playback when fast or repeated final chat events arrive while Talk Mode is waiting for its own response. Fixes #46546.
+- Tooling/check:changed: pass parent heavy-check lock markers to lint lanes so `pnpm check:changed` no longer waits on its own `lint:extensions` child. Thanks @steipete.
+- CLI/completion: dedupe provider auth flags before registering `openclaw onboard` options, so completion-cache refresh during update no longer fails when stale core fallback flags overlap plugin manifest flags. Fixes #71667.
+- Diagnostics/trace: report live context usage from the current prompt snapshot instead of provider turn totals, avoiding false near-full context spikes on cached or tool-heavy runs.
+- Providers/Google: honor `models.providers.google.request.allowPrivateNetwork` for Gemini TTS and telephony TTS, matching Google image generation and media understanding. (#71723) Thanks @ro-hansolo.
+- Providers/MiniMax: register `minimax-portal` for music and video generation, preserving OAuth auth and regional MiniMax base URLs across the shared `music_generate` and `video_generate` tools. (#63241) Thanks @tars90percent.
+- Providers/onboarding: keep Runway and Alibaba Model Studio out of the text-inference setup picker by scoping their video-generation auth choices to the media setup flow. (#65856) Thanks @Jah-yee.
 - Plugins/Bonjour: stop the gateway from crash-looping on `CIAO PROBING CANCELLED` when the mDNS watchdog cancels a stuck probe. Restores the rejection-handler wiring dropped during the bonjour plugin migration and shares unhandled-rejection state across module instances so plugin-staged copies of `openclaw/plugin-sdk/runtime` register into the same handler set the host consults. Especially affects Docker on macOS, where mDNS probing reliably hits the watchdog. Thanks @troyhitch.
-- Google Meet: report pinned Chrome nodes as offline or missing capabilities in
-  setup/join diagnostics, keep inaccessible nodes out of auto-selection, and
-  preflight local BlackHole/SoX requirements before agents try local Chrome.
-  Thanks @steipete.
-- Providers/MiniMax: route `image-01` requests to the dedicated image
-  generation endpoint while preserving CN endpoint selection. Fixes #61149.
-  Thanks @mushuiyu886.
-- Plugins/startup: remove ownerless bundled runtime-dependency install locks
-  after a short grace window and include lock owner details when startup times
-  out waiting for a plugin runtime-deps lock.
-- Plugins/install: anchor bundled runtime-dependency npm installs with an
-  OpenClaw-owned package manifest so Linux updates cannot accidentally write to
-  a parent `$HOME/node_modules` tree. Fixes #71730.
+- Google Meet: report pinned Chrome nodes as offline or missing capabilities in setup/join diagnostics, keep inaccessible nodes out of auto-selection, and preflight local BlackHole/SoX requirements before agents try local Chrome. Thanks @steipete.
+- Providers/MiniMax: route `image-01` requests to the dedicated image generation endpoint while preserving CN endpoint selection. Fixes #61149. Thanks @mushuiyu886.
+- Plugins/startup: remove ownerless bundled runtime-dependency install locks after a short grace window and include lock owner details when startup times out waiting for a plugin runtime-deps lock.
+- Plugins/install: anchor bundled runtime-dependency npm installs with an OpenClaw-owned package manifest so Linux updates cannot accidentally write to a parent `$HOME/node_modules` tree. Fixes #71730.
 - Plugins/install: pass onboarding plugin config into plugin index writes so local plugin installs outside default discovery roots keep their install records. Thanks @shakkernerd.
 - Plugins/install: migrate shipped `plugins.installs` config records into the plugin index while stripping them from runtime config and future writes. Thanks @shakkernerd.
+- Plugins/install: durably remove shipped `plugins.installs` from `openclaw.json` after its records are copied into the plugin index, while rolling back the index write if config cleanup fails. Thanks @shakkernerd.
 - Plugins/install: keep migrated plugin install records in the plugin index even when the plugin manifest is missing or invalid, so update, uninstall, inspect, and audit can still recover broken installs. Thanks @shakkernerd.
 - Plugins/security: keep plugin audit JSON check ids stable while reporting plugin index install-record findings with updated wording. Thanks @shakkernerd.
 - CLI/config: reject direct `plugins.installs` edits with guidance to use `openclaw plugins install`, `openclaw plugins update`, or `openclaw plugins uninstall` instead. Thanks @shakkernerd.
-- Live tests/voice: accept common STT variants for OpenClaw and ElevenLabs
-  brand names so provider smoke tests fail on real regressions rather than
-  equivalent transcripts.
-- Agents/replies: forward sanitized underlying agent failure details on external
-  channels instead of replacing unknown failures with a generic retry message.
-- CLI/MCP: translate OpenClaw `mcp.servers.*.transport` entries into
-  Claude/Gemini CLI `type` fields so streamable HTTP MCP servers load in CLI
-  backend sessions. (#71724) Thanks @Blockchain-Oracle.
-- Browser/CDP: honor configured remote and `attachOnly` CDP HTTP/WebSocket
-  timeouts when opening tabs through raw CDP or `/json/new` fallback. (#54238)
-  Thanks @FuncWei.
-- WhatsApp/TTS: send visible text separately from PTT voice-note audio instead
-  of relying on hidden voice-note captions. Fixes #51081.
-- Browser/client: avoid telling agents to restart OpenClaw for dispatcher
-  timeouts on external browser profiles such as `attachOnly`, remote CDP, and
-  existing-session. (#40815) Thanks @0xsline.
-- Agents/TTS: preserve `[[audio_as_voice]]` directives on trusted text
-  tool-result `MEDIA:` payloads so generated audio still delivers as a voice
-  note. (#46535) Thanks @azade-c.
-- Agents/TTS: keep queued tool media when an assistant ends with `NO_REPLY` on
-  non-block delivery paths, so media-only generated audio replies still send.
-  (#60025) Thanks @bradlind1.
-- Telegram/STT: frame inbound voice-note transcripts as machine-generated,
-  untrusted text in agent context while preserving raw transcript mention
-  detection. Closes #33360. Thanks @smartchainark.
+- Live tests/voice: accept common STT variants for OpenClaw and ElevenLabs brand names so provider smoke tests fail on real regressions rather than equivalent transcripts.
+- Agents/replies: forward sanitized underlying agent failure details on external channels instead of replacing unknown failures with a generic retry message.
+- CLI/MCP: translate OpenClaw `mcp.servers.*.transport` entries into Claude/Gemini CLI `type` fields so streamable HTTP MCP servers load in CLI backend sessions. (#71724) Thanks @Blockchain-Oracle.
+- Browser/CDP: honor configured remote and `attachOnly` CDP HTTP/WebSocket timeouts when opening tabs through raw CDP or `/json/new` fallback. (#54238) Thanks @FuncWei.
+- WhatsApp/TTS: send visible text separately from PTT voice-note audio instead of relying on hidden voice-note captions. Fixes #51081.
+- Browser/client: avoid telling agents to restart OpenClaw for dispatcher timeouts on external browser profiles such as `attachOnly`, remote CDP, and existing-session. (#40815) Thanks @0xsline.
+- Agents/TTS: preserve `[[audio_as_voice]]` directives on trusted text tool-result `MEDIA:` payloads so generated audio still delivers as a voice note. (#46535) Thanks @azade-c.
+- Agents/TTS: keep queued tool media when an assistant ends with `NO_REPLY` on non-block delivery paths, so media-only generated audio replies still send. (#60025) Thanks @bradlind1.
+- Telegram/STT: frame inbound voice-note transcripts as machine-generated, untrusted text in agent context while preserving raw transcript mention detection. Closes #33360. Thanks @smartchainark.
 - Subagents/browser: show an actionable `/tools` notice when browser automation is configured but filtered out by the active tool profile, and document that coding-profile agents should use `tools.alsoAllow: ["browser"]` rather than subagent allowlists alone.
 - Control UI/Quick Settings: persist the assistant avatar override to browser local storage (mirroring the user avatar) so uploaded image data URLs no longer fail config validation with "Too big: expected string to have <=200 characters". Also lift the gateway-side `ui.assistant.avatar` length cap to match the user avatar size budget for non-UI clients writing the field directly. Thanks @BunsDev.
-- Plugin SDK: share diagnostic event subscriptions across duplicate source/dist
-  module graphs so legacy root SDK imports still receive runtime diagnostic events.
-- Agents/Bedrock: prevent empty assistant stream-error turns from poisoning
-  Converse replay by persisting, repairing, and replaying a non-empty fallback
-  block. Fixes #71572. (#71627) Thanks @openperf.
-- Agents/Anthropic/Bedrock: strip thinking blocks with missing, empty, or blank
-  replay signatures before provider conversion, falling back to non-empty
-  omitted-reasoning text when needed so corrupted signed-thinking history no
-  longer poisons subsequent turns. Fixes #45010. (#70054) Thanks @castaples.
-- Agents/Anthropic/Bedrock: preserve stripped thinking-only assistant replay
-  turns with non-empty omitted-reasoning text so provider adapters keep strict
-  user/assistant turn shape. Thanks @wujiaming88.
+- Plugin SDK: share diagnostic event subscriptions across duplicate source/dist module graphs so legacy root SDK imports still receive runtime diagnostic events.
+- Agents/Bedrock: prevent empty assistant stream-error turns from poisoning Converse replay by persisting, repairing, and replaying a non-empty fallback block. Fixes #71572. (#71627) Thanks @openperf.
+- Agents/Anthropic/Bedrock: strip thinking blocks with missing, empty, or blank replay signatures before provider conversion, falling back to non-empty omitted-reasoning text when needed so corrupted signed-thinking history no longer poisons subsequent turns. Fixes #45010. (#70054) Thanks @castaples.
+- Agents/Anthropic/Bedrock: preserve stripped thinking-only assistant replay turns with non-empty omitted-reasoning text so provider adapters keep strict user/assistant turn shape. Thanks @wujiaming88.
 - ACP/Codex: pass `sessions_spawn(runtime="acp")` model and thinking overrides into Codex ACP startup, normalize `openai-codex/*` refs and slash reasoning suffixes, and recognize managed Codex ACP wrapper commands without blocking current `gpt-5.5` sessions. Fixes #40393. (#71643) Thanks @91wan.
 - Browser/CDP: make readiness diagnostics use the same discovery-first fallback as reachability for bare `ws://` Browserless and Browserbase CDP URLs. Fixes #69532.
 - Browser/CDP: explain that loopback Browserless or other externally managed CDP services need `attachOnly: true` and matching Browserless `EXTERNAL` endpoint when reporting local port ownership conflicts, and fall back to the configured bare WebSocket root when a discovered Browserless endpoint rejects CDP. Fixes #49815.
@@ -320,9 +309,7 @@ Docs: https://docs.openclaw.ai
 - Plugins/model defaults: run Skill Workshop review, Active Memory recall, and session-memory slug generation on the configured agent default model instead of the hardcoded OpenAI SDK fallback when hook context lacks model metadata. Fixes #71659.
 - Providers/Venice: fill the required DeepSeek V4 `reasoning_content` placeholder for `venice/deepseek-v4-pro` and `venice/deepseek-v4-flash` replay turns without sending native DeepSeek `thinking` controls that Venice rejects. Fixes #71628.
 - Browser/existing-session: support per-profile Chrome MCP command/args, map `cdpUrl` to `--browserUrl` or `--wsEndpoint`, and avoid combining endpoint flags with `--userDataDir`. Fixes #47879, #48037, and #62706. Thanks @puneet1409, @zhehao, and @madkow1001.
-- Media/plugins: bound MIME sniffing and ZIP archive preflight before handing
-  untrusted files to `file-type` or `jszip`, reducing parser CPU and memory
-  exposure for attachments and ClawHub plugin archives. Thanks @vincentkoc.
+- Media/plugins: bound MIME sniffing and ZIP archive preflight before handing untrusted files to `file-type` or `jszip`, reducing parser CPU and memory exposure for attachments and ClawHub plugin archives. Thanks @vincentkoc.
 - Memory-host SDK: use trusted env-proxy mode for remote embedding and batch HTTP calls only when Undici will proxy that target, preserving SSRF DNS pinning for `ALL_PROXY`-only and `NO_PROXY` bypass cases. Fixes #52162. (#71506) Thanks @DhtIsCoding.
 - Gateway/dashboard: render Control UI and WebSocket links with `https://`/`wss://` when `gateway.tls.enabled=true`, including `openclaw gateway status`. Fixes #71494. (#71499) Thanks @deepkilo.
 - Agents/OpenAI-compatible: default proxy/local completions tool requests to `tool_choice: "auto"` when tools are present, so providers enter native tool-calling mode instead of replying with plain-text tool directives. (#71472) Thanks @Speed-maker.
@@ -362,8 +349,7 @@ Docs: https://docs.openclaw.ai
 - Browser/Linux: detect Chromium-based installs under `/opt/google`, `/opt/brave.com`, `/usr/lib/chromium`, and `/usr/lib/chromium-browser` before asking users to set `browser.executablePath`. (#48563) Thanks @lupuletic.
 - Sessions/browser: close tracked browser tabs when idle, daily, `/new`, or `/reset` session rollover archives the previous transcript, preventing tabs from leaking past the old session. Thanks @jakozloski.
 - Sessions/forking: fall back to transcript-estimated parent token counts when cached totals are stale or missing, so oversized thread forks start fresh instead of cloning the full parent transcript. Thanks @jalehman.
-- OpenAI/Codex: send Codex Responses system prompts through top-level
-  `instructions` while preserving the existing native Codex payload controls.
+- OpenAI/Codex: send Codex Responses system prompts through top-level `instructions` while preserving the existing native Codex payload controls.
 - MCP/CLI: retire bundled MCP runtimes at the end of one-shot `openclaw agent` and `openclaw infer model run` gateway/local executions, so repeated scripted runs do not accumulate stdio MCP child processes. Fixes #71457. Thanks @spartoviMD.
 - OpenAI/Codex image generation: canonicalize legacy `openai-codex.baseUrl` values such as `https://chatgpt.com/backend-api` to the Codex Responses backend before calling `gpt-image-2`, matching the chat transport. Fixes #71460. Thanks @GodsBoy.
 - Control UI: make `/usage` use the fresh context snapshot for context percentage, and include cache-write tokens in the Usage overview cache-hit denominator. Fixes #47885. Thanks @imwyvern and @Ante042.
@@ -384,9 +370,15 @@ Docs: https://docs.openclaw.ai
 - Agents/CLI sessions: bind `google-gemini-cli` session auth-epoch to the Google account identity in `~/.gemini/oauth_creds.json`, so Gemini-backed agents resume their conversation after gateway restart instead of minting a fresh session, and stale bindings are invalidated when the authenticated Google account changes. Fixes #70973. (#71076) Thanks @openperf.
 - Slack: stop treating user mentions in assistant-authored message edit blocks as sender attribution, preventing edited bot messages from spoofing a mentioned DM user. (#71700) Thanks @vincentkoc.
 - Codex: consume unauthorized bound conversation inbound claims before they can fall through to other claim handlers or enqueue Codex turns. (#71702) Thanks @vincentkoc.
-- Codex media understanding: require approval-checked app-server image turns while
-  explicitly declining tool, file, permission, and elicitation approval requests
-  for the bounded image worker. (#71703) Thanks @vincentkoc.
+- Codex media understanding: require approval-checked app-server image turns while explicitly declining tool, file, permission, and elicitation approval requests for the bounded image worker. (#71703) Thanks @vincentkoc.
+- Agents/Claude CLI: allow large live `stream-json` JSONL lines up to the existing per-turn raw limit, preventing large Telegram, WebChat, MCP, and image turns from aborting on the old stdout buffer cap. Fixes #71793, #71080, and #70766. (#71897) Thanks @chacher86, @shivamgrover21, and @tpjordan.
+- Agents/Claude CLI: unwrap nested Claude result envelopes in CLI JSON output so delegated agent responses surface as final text instead of raw result JSON. (#66819) Thanks @mraleko.
+- Agents/Claude CLI: apply the configured 1M context window override to eligible Claude CLI Opus and Sonnet models when `context1m` is enabled. (#70863) Thanks @bidadh.
+- Models/status: report fresh Claude CLI native auth instead of stale stored `anthropic:claude-cli` profile expiry when local credentials are current. Fixes #71256. (#71332) Thanks @matthiasjanke and @neeravmakwana.
+- CLI backends: compact OpenClaw transcripts after over-budget CLI turns and reseed fresh CLI sessions from the compacted transcript instead of stale external resume state. Fixes #68329. (#71916) Thanks @obviyus.
+- Telegram: keep default tool progress messages visible when answer preview streaming is disabled. (#71825) Thanks @VACInc.
+- Configure/models: clear deselected model fallbacks when updating the model picker allowlist, including provider-scoped setup flows. (#71596) Thanks @rubencu.
+- Agents/streaming: strip namespaced `<antml:thinking>` reasoning tags from streamed assistant replies before user-visible text is emitted. (#69288) Thanks @xialonglee.
 
 ## 2026.4.24
 

Dockerfile

@@ -173,6 +173,7 @@ RUN chown node:node /app
 COPY --from=runtime-assets --chown=node:node /app/dist ./dist
 COPY --from=runtime-assets --chown=node:node /app/node_modules ./node_modules
 COPY --from=runtime-assets --chown=node:node /app/package.json .
+COPY --from=runtime-assets --chown=node:node /app/patches ./patches
 COPY --from=runtime-assets --chown=node:node /app/openclaw.mjs .
 COPY --from=runtime-assets --chown=node:node /app/${OPENCLAW_BUNDLED_PLUGIN_DIR} ./${OPENCLAW_BUNDLED_PLUGIN_DIR}
 COPY --from=runtime-assets --chown=node:node /app/skills ./skills

Swabble/Sources/SwabbleKit/WakeWordGate.swift

@@ -35,11 +35,18 @@ public struct WakeWordGateMatch: Sendable, Equatable {
     public let triggerEndTime: TimeInterval
     public let postGap: TimeInterval
     public let command: String
+    public let trigger: String?
 
-    public init(triggerEndTime: TimeInterval, postGap: TimeInterval, command: String) {
+    public init(
+        triggerEndTime: TimeInterval,
+        postGap: TimeInterval,
+        command: String,
+        trigger: String? = nil)
+    {
         self.triggerEndTime = triggerEndTime
         self.postGap = postGap
         self.command = command
+        self.trigger = trigger
     }
 }
 
@@ -53,13 +60,17 @@ public enum WakeWordGate {
     }
 
     private struct TriggerTokens {
+        let source: String
         let tokens: [String]
     }
 
     private struct MatchCandidate {
         let index: Int
+        let endIndex: Int
+        let tokenCount: Int
         let triggerEnd: TimeInterval
         let gap: TimeInterval
+        let trigger: String
     }
 
     public static func match(
@@ -87,9 +98,19 @@ public enum WakeWordGate {
                 let gap = nextToken.start - triggerEnd
                 if gap < config.minPostTriggerGap { continue }
 
-                if let best, i <= best.index { continue }
+                let endIndex = i + count - 1
+                if let best {
+                    if endIndex < best.endIndex { continue }
+                    if endIndex == best.endIndex, count <= best.tokenCount { continue }
+                }
 
-                best = MatchCandidate(index: i, triggerEnd: triggerEnd, gap: gap)
+                best = MatchCandidate(
+                    index: i,
+                    endIndex: endIndex,
+                    tokenCount: count,
+                    triggerEnd: triggerEnd,
+                    gap: gap,
+                    trigger: trigger.source)
             }
         }
 
@@ -97,7 +118,11 @@ public enum WakeWordGate {
         let command = commandText(transcript: transcript, segments: segments, triggerEndTime: best.triggerEnd)
             .trimmingCharacters(in: Self.whitespaceAndPunctuation)
         guard command.count >= config.minCommandLength else { return nil }
-        return WakeWordGateMatch(triggerEndTime: best.triggerEnd, postGap: best.gap, command: command)
+        return WakeWordGateMatch(
+            triggerEndTime: best.triggerEnd,
+            postGap: best.gap,
+            command: command,
+            trigger: best.trigger)
     }
 
     public static func commandText(
@@ -145,7 +170,7 @@ public enum WakeWordGate {
                 .map { normalizeToken(String($0)) }
                 .filter { !$0.isEmpty }
             if tokens.isEmpty { continue }
-            output.append(TriggerTokens(tokens: tokens))
+            output.append(TriggerTokens(source: tokens.joined(separator: " "), tokens: tokens))
         }
         return output
     }

Swabble/Tests/SwabbleKitTests/WakeWordGateTests.swift

@@ -47,6 +47,21 @@ import Testing
         #expect(match?.command == "do it")
     }
 
+    @Test func matchPrefersMostSpecificTriggerWhenOverlapping() {
+        let transcript = "hey clawd do it"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.8, 0.1),
+                ("it", 1.0, 0.1),
+            ])
+        let config = WakeWordGateConfig(triggers: ["clawd", "hey clawd"], minPostTriggerGap: 0.3)
+        let match = WakeWordGate.match(transcript: transcript, segments: segments, config: config)
+        #expect(match?.trigger == "hey clawd")
+    }
+
     @Test func commandTextHandlesForeignRangeIndices() {
         let transcript = "hey clawd do thing"
         let other = "do thing"

apps/macos/Sources/OpenClaw/AppState.swift

@@ -1,6 +1,7 @@
 import AppKit
 import Foundation
 import Observation
+import OpenClawKit
 import ServiceManagement
 import SwiftUI
 
@@ -366,7 +367,8 @@ final class AppState {
         if resolvedConnectionMode == .remote,
            configRemoteTransport != .direct,
            storedRemoteTarget.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
-           let host = AppState.remoteHost(from: configRemoteUrl)
+           let host = AppState.remoteHost(from: configRemoteUrl),
+           !LoopbackHost.isLoopbackHost(host)
         {
             self.remoteTarget = "\(NSUserName())@\(host)"
         } else {
@@ -435,6 +437,30 @@ final class AppState {
         return trimmed
     }
 
+    private static func sshTunnelGatewayUrl(existingUrl: String?, expectedRemoteHost: String?) -> String {
+        let fallback = "ws://127.0.0.1:18789"
+        let trimmed = existingUrl?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty,
+              let url = URL(string: trimmed),
+              let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !host.isEmpty
+        else {
+            return fallback
+        }
+
+        let preservePort: Bool = if LoopbackHost.isLoopbackHost(host) {
+            true
+        } else if let expectedRemoteHost {
+            OpenClawConfigFile.canonicalHostForComparison(host) ==
+                OpenClawConfigFile.canonicalHostForComparison(expectedRemoteHost)
+        } else {
+            false
+        }
+        guard preservePort else { return fallback }
+
+        return "ws://127.0.0.1:\(url.port ?? 18789)"
+    }
+
     private static func updateGatewayString(
         _ dictionary: inout [String: Any],
         key: String,
@@ -491,17 +517,14 @@ final class AppState {
         case .ssh:
             changed = Self.updateGatewayString(&remote, key: "transport", value: nil) || changed
 
-            if let host = draft.remoteHost {
-                let existingUrl = (remote["url"] as? String)?
-                    .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-                let parsedExisting = existingUrl.isEmpty ? nil : URL(string: existingUrl)
-                let scheme = parsedExisting?.scheme?.isEmpty == false ? parsedExisting?.scheme : "ws"
-                let port = parsedExisting?.port ?? 18789
-                let desiredUrl = "\(scheme ?? "ws")://\(host):\(port)"
-                changed = Self.updateGatewayString(&remote, key: "url", value: desiredUrl) || changed
-            }
-
             let sanitizedTarget = Self.sanitizeSSHTarget(draft.remoteTarget)
+            let expectedRemoteHost = CommandResolver.parseSSHTarget(sanitizedTarget)?.host ?? draft.remoteHost
+            let existingUrl = (remote["url"] as? String)?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            let desiredUrl = Self.sshTunnelGatewayUrl(
+                existingUrl: existingUrl,
+                expectedRemoteHost: expectedRemoteHost)
+            changed = Self.updateGatewayString(&remote, key: "url", value: desiredUrl) || changed
             changed = Self.updateGatewayString(&remote, key: "sshTarget", value: sanitizedTarget) || changed
             changed = Self.updateGatewayString(&remote, key: "sshIdentity", value: draft.remoteIdentity) || changed
         }
@@ -569,7 +592,8 @@ final class AppState {
         let targetMode = desiredMode ?? self.connectionMode
         if targetMode == .remote,
            remoteTransport != .direct,
-           let host = AppState.remoteHost(from: remoteUrl)
+           let host = AppState.remoteHost(from: remoteUrl),
+           !LoopbackHost.isLoopbackHost(host)
         {
             self.updateRemoteTarget(host: host)
         }

apps/macos/Sources/OpenClaw/GatewayConnection.swift

@@ -42,6 +42,7 @@ struct GatewayAgentInvocation {
     var channel: GatewayAgentChannel = .last
     var timeoutSeconds: Int?
     var idempotencyKey: String = UUID().uuidString
+    var voiceWakeTrigger: String?
 }
 
 /// Single, shared Gateway websocket connection for the whole app.
@@ -499,6 +500,10 @@ extension GatewayConnection {
         if let timeout = invocation.timeoutSeconds {
             params["timeout"] = AnyCodable(timeout)
         }
+        if let trigger = invocation.voiceWakeTrigger {
+            params["voiceWakeTrigger"] = AnyCodable(
+                trigger.trimmingCharacters(in: .whitespacesAndNewlines))
+        }
 
         do {
             try await self.requestVoid(method: .agent, params: params)

apps/macos/Sources/OpenClaw/GatewayDiscoverySelectionSupport.swift

@@ -1,7 +1,11 @@
+import Foundation
 import OpenClawDiscovery
+import OpenClawKit
 
 @MainActor
 enum GatewayDiscoverySelectionSupport {
+    private static let defaultSshTunnelGatewayUrl = "ws://127.0.0.1:18789"
+
     static func applyRemoteSelection(
         gateway: GatewayDiscoveryModel.DiscoveredGateway,
         state: AppState)
@@ -13,18 +17,40 @@ enum GatewayDiscoverySelectionSupport {
             state.remoteTransport = preferredTransport
         }
 
-        state.remoteUrl = GatewayDiscoveryHelpers.directUrl(for: gateway) ?? ""
+        if preferredTransport == .direct {
+            state.remoteUrl = GatewayDiscoveryHelpers.directUrl(for: gateway) ?? ""
+        } else {
+            state.remoteUrl = self.sshTunnelGatewayUrl(current: state.remoteUrl)
+        }
         state.remoteTarget = GatewayDiscoveryHelpers.sshTarget(for: gateway) ?? ""
 
-        if let endpoint = GatewayDiscoveryHelpers.serviceEndpoint(for: gateway) {
-            OpenClawConfigFile.setRemoteGatewayUrl(
-                host: endpoint.host,
-                port: endpoint.port)
+        if preferredTransport == .direct {
+            if let endpoint = GatewayDiscoveryHelpers.serviceEndpoint(for: gateway) {
+                OpenClawConfigFile.setRemoteGatewayUrl(
+                    host: endpoint.host,
+                    port: endpoint.port)
+            } else {
+                OpenClawConfigFile.clearRemoteGatewayUrl()
+            }
         } else {
-            OpenClawConfigFile.clearRemoteGatewayUrl()
+            OpenClawConfigFile.setRemoteGatewayUrlString(state.remoteUrl)
         }
     }
 
+    private static func sshTunnelGatewayUrl(current: String) -> String {
+        let trimmed = current.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty,
+              let url = URL(string: trimmed),
+              let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !host.isEmpty,
+              LoopbackHost.isLoopbackHost(host)
+        else {
+            return self.defaultSshTunnelGatewayUrl
+        }
+
+        return "ws://127.0.0.1:\(url.port ?? 18789)"
+    }
+
     static func preferredTransport(
         for gateway: GatewayDiscoveryModel.DiscoveredGateway,
         current: AppState.RemoteTransport) -> AppState.RemoteTransport

apps/macos/Sources/OpenClaw/Logging/OpenClawLogging.swift

@@ -135,6 +135,10 @@ struct OpenClawOSLogHandler: AppLogLevelBackedHandler {
         self.osLogger = os.Logger(subsystem: subsystem, category: category)
     }
 
+    func log(event: LogEvent) {
+        self.writeLog(level: event.level, message: event.message, metadata: event.metadata)
+    }
+
     func log(
         level: Logger.Level,
         message: Logger.Message,
@@ -143,6 +147,14 @@ struct OpenClawOSLogHandler: AppLogLevelBackedHandler {
         file: String,
         function: String,
         line: UInt)
+    {
+        self.writeLog(level: level, message: message, metadata: metadata)
+    }
+
+    private func writeLog(
+        level: Logger.Level,
+        message: Logger.Message,
+        metadata: Logger.Metadata?)
     {
         let merged = Self.mergeMetadata(self.metadata, metadata)
         let rendered = Self.renderMessage(message, metadata: merged)
@@ -186,6 +198,17 @@ struct OpenClawFileLogHandler: AppLogLevelBackedHandler {
     let label: String
     var metadata: Logger.Metadata = [:]
 
+    func log(event: LogEvent) {
+        self.writeLog(
+            level: event.level,
+            message: event.message,
+            metadata: event.metadata,
+            source: event.source,
+            file: event.file,
+            function: event.function,
+            line: event.line)
+    }
+
     func log(
         level: Logger.Level,
         message: Logger.Message,
@@ -194,6 +217,25 @@ struct OpenClawFileLogHandler: AppLogLevelBackedHandler {
         file: String,
         function: String,
         line: UInt)
+    {
+        self.writeLog(
+            level: level,
+            message: message,
+            metadata: metadata,
+            source: source,
+            file: file,
+            function: function,
+            line: line)
+    }
+
+    private func writeLog(
+        level: Logger.Level,
+        message: Logger.Message,
+        metadata: Logger.Metadata?,
+        source: String,
+        file: String,
+        function: String,
+        line: UInt)
     {
         guard AppLogSettings.fileLoggingEnabled() else { return }
         let (subsystem, category) = OpenClawLogging.parseLabel(self.label)

apps/macos/Sources/OpenClaw/NodeMode/MacNodeBrowserProxy.swift

@@ -54,8 +54,15 @@ actor MacNodeBrowserProxy {
 
     func request(paramsJSON: String?) async throws -> String {
         let params = try Self.decodeRequestParams(from: paramsJSON)
-        let request = try Self.makeRequest(params: params, endpoint: self.endpointProvider())
-        let (data, response) = try await self.performRequest(request)
+        let endpoint = self.endpointProvider()
+        let request = try Self.makeRequest(params: params, endpoint: endpoint)
+        let data: Data
+        let response: URLResponse
+        do {
+            (data, response) = try await self.performRequest(request)
+        } catch {
+            throw Self.unavailableError(endpoint: endpoint, cause: error)
+        }
         let http = try Self.requireHTTPResponse(response)
         guard (200..<300).contains(http.statusCode) else {
             throw NSError(domain: "MacNodeBrowserProxy", code: http.statusCode, userInfo: [
@@ -165,6 +172,19 @@ actor MacNodeBrowserProxy {
         return http
     }
 
+    private static func unavailableError(endpoint: Endpoint, cause: Error) -> NSError {
+        let url = endpoint.baseURL.absoluteString
+        let message = """
+        UNAVAILABLE: macOS app node could not reach the local browser control service at \(url). \
+        In remote mode, browser control is owned by the CLI node-host; start `openclaw node start` \
+        on this Mac and target that browser node. Underlying error: \(cause.localizedDescription)
+        """
+        return NSError(domain: "MacNodeBrowserProxy", code: 9, userInfo: [
+            NSLocalizedDescriptionKey: message,
+            NSUnderlyingErrorKey: cause,
+        ])
+    }
+
     private static func httpErrorMessage(statusCode: Int, data: Data) -> String {
         if let object = try? JSONSerialization.jsonObject(with: data, options: [.fragmentsAllowed]) as? [String: Any],
            let error = object["error"] as? String,

apps/macos/Sources/OpenClaw/NodeMode/MacNodeModeCoordinator.swift

@@ -116,27 +116,40 @@ final class MacNodeModeCoordinator {
         }
     }
 
-    private func currentCaps() -> [String] {
+    nonisolated static func resolvedCaps(
+        browserControlEnabled: Bool,
+        cameraEnabled: Bool,
+        locationMode: OpenClawLocationMode,
+        connectionMode: AppState.ConnectionMode) -> [String]
+    {
         var caps: [String] = [OpenClawCapability.canvas.rawValue, OpenClawCapability.screen.rawValue]
-        if OpenClawConfigFile.browserControlEnabled() {
+        if browserControlEnabled, connectionMode == .local {
             caps.append(OpenClawCapability.browser.rawValue)
         }
-        if UserDefaults.standard.object(forKey: cameraEnabledKey) as? Bool ?? false {
+        if cameraEnabled {
             caps.append(OpenClawCapability.camera.rawValue)
         }
-        let rawLocationMode = UserDefaults.standard.string(forKey: locationModeKey) ?? "off"
-        if OpenClawLocationMode(rawValue: rawLocationMode) != .off {
+        if locationMode != .off {
             caps.append(OpenClawCapability.location.rawValue)
         }
         return caps
     }
 
+    private func currentCaps() -> [String] {
+        let rawLocationMode = UserDefaults.standard.string(forKey: locationModeKey) ?? "off"
+        return Self.resolvedCaps(
+            browserControlEnabled: OpenClawConfigFile.browserControlEnabled(),
+            cameraEnabled: UserDefaults.standard.object(forKey: cameraEnabledKey) as? Bool ?? false,
+            locationMode: OpenClawLocationMode(rawValue: rawLocationMode) ?? .off,
+            connectionMode: AppStateStore.shared.connectionMode)
+    }
+
     private func currentPermissions() async -> [String: Bool] {
         let statuses = await PermissionManager.status()
         return Dictionary(uniqueKeysWithValues: statuses.map { ($0.key.rawValue, $0.value) })
     }
 
-    private func currentCommands(caps: [String]) -> [String] {
+    nonisolated static func resolvedCommands(caps: [String]) -> [String] {
         var commands: [String] = [
             OpenClawCanvasCommand.present.rawValue,
             OpenClawCanvasCommand.hide.rawValue,
@@ -171,6 +184,10 @@ final class MacNodeModeCoordinator {
         return commands
     }
 
+    private func currentCommands(caps: [String]) -> [String] {
+        Self.resolvedCommands(caps: caps)
+    }
+
     private func buildSessionBox(url: URL) -> WebSocketSessionBox? {
         guard url.scheme?.lowercased() == "wss" else { return nil }
         let host = url.host ?? "gateway"

apps/macos/Sources/OpenClaw/OpenClawConfigFile.swift

@@ -192,20 +192,17 @@ enum OpenClawConfigFile {
     }
 
     static func remoteGatewayPort(matchingHost sshHost: String) -> Int? {
-        let trimmedSshHost = sshHost.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmedSshHost.isEmpty,
+        guard let normalizedSshHost = canonicalHostForComparison(sshHost),
               let url = self.remoteGatewayUrl(),
               let port = url.port,
               port > 0,
-              let urlHost = url.host?.trimmingCharacters(in: .whitespacesAndNewlines),
-              !urlHost.isEmpty
+              let urlHost = url.host,
+              let normalizedUrlHost = canonicalHostForComparison(urlHost)
         else {
             return nil
         }
 
-        let sshKey = Self.hostKey(trimmedSshHost)
-        let urlKey = Self.hostKey(urlHost)
-        guard !sshKey.isEmpty, !urlKey.isEmpty, sshKey == urlKey else { return nil }
+        guard normalizedSshHost == normalizedUrlHost else { return nil }
         return port
     }
 
@@ -223,6 +220,16 @@ enum OpenClawConfigFile {
         }
     }
 
+    static func setRemoteGatewayUrlString(_ value: String) {
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        self.updateGatewayDict { gateway in
+            var remote = gateway["remote"] as? [String: Any] ?? [:]
+            remote["url"] = trimmed
+            gateway["remote"] = remote
+        }
+    }
+
     static func clearRemoteGatewayUrl() {
         self.updateGatewayDict { gateway in
             guard var remote = gateway["remote"] as? [String: Any] else { return }
@@ -249,15 +256,17 @@ enum OpenClawConfigFile {
         return url
     }
 
-    static func hostKey(_ host: String) -> String {
-        let trimmed = host.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-        guard !trimmed.isEmpty else { return "" }
-        if trimmed.contains(":") { return trimmed }
-        let digits = CharacterSet(charactersIn: "0123456789.")
-        if trimmed.rangeOfCharacter(from: digits.inverted) == nil {
-            return trimmed
+    static func canonicalHostForComparison(_ raw: String?) -> String? {
+        guard var host = raw?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased(),
+              !host.isEmpty
+        else {
+            return nil
         }
-        return trimmed.split(separator: ".").first.map(String.init) ?? trimmed
+        host = host.trimmingCharacters(in: CharacterSet(charactersIn: "[]"))
+        while host.hasSuffix(".") {
+            host.removeLast()
+        }
+        return host.isEmpty ? nil : host
     }
 
     private static func parseConfigData(_ data: Data) -> [String: Any]? {

apps/macos/Sources/OpenClaw/RemotePortTunnel.swift

@@ -150,9 +150,11 @@ final class RemotePortTunnel {
         else {
             return nil
         }
-        let sshKey = OpenClawConfigFile.hostKey(sshHost)
-        let urlKey = OpenClawConfigFile.hostKey(host)
-        guard !sshKey.isEmpty, !urlKey.isEmpty else { return nil }
+        guard let sshKey = OpenClawConfigFile.canonicalHostForComparison(sshHost),
+              let urlKey = OpenClawConfigFile.canonicalHostForComparison(host)
+        else {
+            return nil
+        }
         guard sshKey == urlKey else {
             Self.logger.debug(
                 "remote url host mismatch sshHost=\(sshHost, privacy: .public) urlHost=\(host, privacy: .public)")

apps/macos/Sources/OpenClaw/VoiceSessionCoordinator.swift

@@ -17,6 +17,7 @@ final class VoiceSessionCoordinator {
         var isFinal: Bool
         var sendChime: VoiceWakeChime
         var autoSendDelay: TimeInterval?
+        var voiceWakeTrigger: String?
     }
 
     private let logger = Logger(subsystem: "ai.openclaw", category: "voicewake.coordinator")
@@ -28,7 +29,8 @@ final class VoiceSessionCoordinator {
         source: Source,
         text: String,
         attributed: NSAttributedString? = nil,
-        forwardEnabled: Bool = false) -> UUID
+        forwardEnabled: Bool = false,
+        voiceWakeTrigger: String? = nil) -> UUID
     {
         let token = UUID()
         self.logger.info("coordinator start token=\(token.uuidString) source=\(source.rawValue) len=\(text.count)")
@@ -40,7 +42,8 @@ final class VoiceSessionCoordinator {
             attributed: attributedText,
             isFinal: false,
             sendChime: .none,
-            autoSendDelay: nil)
+            autoSendDelay: nil,
+            voiceWakeTrigger: voiceWakeTrigger)
         self.session = session
         VoiceWakeOverlayController.shared.startSession(
             token: token,
@@ -63,7 +66,8 @@ final class VoiceSessionCoordinator {
         token: UUID,
         text: String,
         sendChime: VoiceWakeChime,
-        autoSendAfter: TimeInterval?)
+        autoSendAfter: TimeInterval?,
+        voiceWakeTrigger: String? = nil)
     {
         guard let session, session.token == token else { return }
         self.logger
@@ -73,6 +77,9 @@ final class VoiceSessionCoordinator {
         self.session?.isFinal = true
         self.session?.sendChime = sendChime
         self.session?.autoSendDelay = autoSendAfter
+        if let voiceWakeTrigger {
+            self.session?.voiceWakeTrigger = voiceWakeTrigger
+        }
 
         let attributed = VoiceWakeOverlayController.shared.makeAttributed(from: text)
         VoiceWakeOverlayController.shared.presentFinal(
@@ -86,15 +93,20 @@ final class VoiceSessionCoordinator {
     func sendNow(token: UUID, reason: String = "explicit") {
         guard let session, session.token == token else { return }
         let text = session.text.trimmingCharacters(in: .whitespacesAndNewlines)
+        let voiceWakeTrigger = session.voiceWakeTrigger
+        let sendChime = session.sendChime
         guard !text.isEmpty else {
             self.logger.info("coordinator sendNow \(reason) empty -> dismiss")
             VoiceWakeOverlayController.shared.dismiss(token: token, reason: .empty, outcome: .empty)
             self.clearSession()
             return
         }
-        VoiceWakeOverlayController.shared.beginSendUI(token: token, sendChime: session.sendChime)
+        VoiceWakeOverlayController.shared.beginSendUI(token: token, sendChime: sendChime)
         Task.detached {
-            _ = await VoiceWakeForwarder.forward(transcript: text)
+            _ = await VoiceWakeForwarder.forward(
+                transcript: text,
+                options: .init(
+                    voiceWakeTrigger: voiceWakeTrigger))
         }
     }
 

apps/macos/Sources/OpenClaw/VoiceWakeForwarder.swift

@@ -38,6 +38,7 @@ enum VoiceWakeForwarder {
         var deliver: Bool = true
         var to: String?
         var channel: GatewayAgentChannel = .webchat
+        var voiceWakeTrigger: String?
     }
 
     @discardableResult
@@ -53,7 +54,8 @@ enum VoiceWakeForwarder {
             thinking: options.thinking,
             deliver: deliver,
             to: options.to,
-            channel: options.channel))
+            channel: options.channel,
+            voiceWakeTrigger: options.voiceWakeTrigger))
 
         if result.ok {
             self.logger.info("voice wake forward ok")

apps/macos/Sources/OpenClaw/VoiceWakeRecognitionDebugSupport.swift

@@ -41,7 +41,11 @@ enum VoiceWakeRecognitionDebugSupport {
             minCommandLength: config.minCommandLength,
             trimWake: trimWake)
         else { return nil }
-        return WakeWordGateMatch(triggerEndTime: 0, postGap: 0, command: command)
+        return WakeWordGateMatch(
+            triggerEndTime: 0,
+            postGap: 0,
+            command: command,
+            trigger: VoiceWakeTextUtils.matchedTriggerWord(transcript: transcript, triggers: triggers))
     }
 
     static func transcriptSummary(

apps/macos/Sources/OpenClaw/VoiceWakeRuntime.swift

@@ -37,6 +37,7 @@ actor VoiceWakeRuntime {
     private var listeningState: ListeningState = .idle
     private var overlayToken: UUID?
     private var activeTriggerEndTime: TimeInterval?
+    private var activeTriggerWord: String?
     private var scheduledRestartTask: Task<Void, Never>?
     private var lastLoggedText: String?
     private var lastLoggedAt: Date?
@@ -256,6 +257,7 @@ actor VoiceWakeRuntime {
         self.currentConfig = nil
         self.listeningState = .idle
         self.activeTriggerEndTime = nil
+        self.activeTriggerWord = nil
         self.logger.debug("voicewake runtime stopped")
         DiagnosticsFileLog.shared.log(category: "voicewake.runtime", event: "stopped")
 
@@ -366,7 +368,11 @@ actor VoiceWakeRuntime {
             } else {
                 self.logger.info("voicewake runtime detected len=\(match.command.count)")
             }
-            await self.beginCapture(command: match.command, triggerEndTime: match.triggerEndTime, config: config)
+            await self.beginCapture(
+                command: match.command,
+                triggerEndTime: match.triggerEndTime,
+                triggerWord: match.trigger,
+                config: config)
         } else if !transcript.isEmpty, update.error == nil {
             if self.isTriggerOnly(transcript: transcript, triggers: config.triggers) {
                 self.preDetectTask?.cancel()
@@ -494,13 +500,33 @@ actor VoiceWakeRuntime {
             return
         }
         self.logger.info("voicewake runtime detected (trigger-only pause)")
-        await self.beginCapture(command: "", triggerEndTime: nil, config: config)
+        let matchedTrigger = self.matchedTriggerWord(transcript: lastText, triggers: triggers)
+        await self.beginCapture(
+            command: "",
+            triggerEndTime: nil,
+            triggerWord: matchedTrigger,
+            config: config)
     }
 
     private func isTriggerOnly(transcript: String, triggers: [String]) -> Bool {
+        Self.isTriggerOnlyText(transcript: transcript, triggers: triggers)
+    }
+
+    private func matchedTriggerWord(transcript: String, triggers: [String]) -> String? {
+        Self.matchedTriggerWordText(transcript: transcript, triggers: triggers)
+    }
+
+    private static func isTriggerOnlyText(transcript: String, triggers: [String]) -> Bool {
         guard WakeWordGate.matchesTextOnly(text: transcript, triggers: triggers) else { return false }
-        guard VoiceWakeTextUtils.startsWithTrigger(transcript: transcript, triggers: triggers) else { return false }
-        return Self.trimmedAfterTrigger(transcript, triggers: triggers).isEmpty
+        guard
+            VoiceWakeTextUtils.startsWithTrigger(transcript: transcript, triggers: triggers)
+            || VoiceWakeTextUtils.hasOnlyFillerBeforeTrigger(transcript: transcript, triggers: triggers)
+        else { return false }
+        return self.trimmedAfterTrigger(transcript, triggers: triggers).isEmpty
+    }
+
+    private static func matchedTriggerWordText(transcript: String, triggers: [String]) -> String? {
+        VoiceWakeTextUtils.matchedTriggerWord(transcript: transcript, triggers: triggers)
     }
 
     private func preDetectSilenceCheck(
@@ -527,10 +553,16 @@ actor VoiceWakeRuntime {
         await self.beginCapture(
             command: match.command,
             triggerEndTime: match.triggerEndTime,
+            triggerWord: match.trigger,
             config: config)
     }
 
-    private func beginCapture(command: String, triggerEndTime: TimeInterval?, config: RuntimeConfig) async {
+    private func beginCapture(
+        command: String,
+        triggerEndTime: TimeInterval?,
+        triggerWord: String?,
+        config: RuntimeConfig) async
+    {
         // When "Trigger Talk Mode" is enabled, skip the capture/overlay flow entirely
         // and activate Talk Mode immediately. Talk Mode handles its own STT pipeline.
         // Pause the wake listener to avoid two audio pipelines competing on the mic
@@ -545,7 +577,6 @@ actor VoiceWakeRuntime {
             await AppStateStore.shared.setTalkEnabled(true)
             return
         }
-
         self.listeningState = .voiceWake
         self.isCapturing = true
         DiagnosticsFileLog.shared.log(category: "voicewake.runtime", event: "beginCapture")
@@ -557,6 +588,7 @@ actor VoiceWakeRuntime {
         self.heardBeyondTrigger = !command.isEmpty
         self.triggerChimePlayed = false
         self.activeTriggerEndTime = triggerEndTime
+        self.activeTriggerWord = triggerWord
         self.preDetectTask?.cancel()
         self.preDetectTask = nil
         self.triggerOnlyTask?.cancel()
@@ -577,7 +609,8 @@ actor VoiceWakeRuntime {
                 source: .wakeWord,
                 text: snapshot,
                 attributed: attributed,
-                forwardEnabled: true)
+                forwardEnabled: true,
+                voiceWakeTrigger: triggerWord)
         }
 
         // Keep the "ears" boosted for the capture window so the status icon animates while recording.
@@ -632,7 +665,9 @@ actor VoiceWakeRuntime {
         self.lastHeard = nil
         self.heardBeyondTrigger = false
         self.triggerChimePlayed = false
+        let triggerWord = self.activeTriggerWord
         self.activeTriggerEndTime = nil
+        self.activeTriggerWord = nil
         self.lastTranscript = nil
         self.lastTranscriptAt = nil
         self.preDetectTask?.cancel()
@@ -653,14 +688,17 @@ actor VoiceWakeRuntime {
                     token: token,
                     text: finalTranscript,
                     sendChime: sendChime,
-                    autoSendAfter: delay)
+                    autoSendAfter: delay,
+                    voiceWakeTrigger: triggerWord)
             }
         } else if !finalTranscript.isEmpty {
             if sendChime != .none {
                 await MainActor.run { VoiceWakeChimePlayer.play(sendChime, reason: "voicewake.send") }
             }
             Task.detached {
-                await VoiceWakeForwarder.forward(transcript: finalTranscript)
+                await VoiceWakeForwarder.forward(
+                    transcript: finalTranscript,
+                    options: .init(voiceWakeTrigger: triggerWord))
             }
         }
         self.overlayToken = nil
@@ -784,6 +822,14 @@ actor VoiceWakeRuntime {
         !self.trimmedAfterTrigger(text, triggers: triggers).isEmpty
     }
 
+    static func _testIsTriggerOnly(_ text: String, triggers: [String]) -> Bool {
+        self.isTriggerOnlyText(transcript: text, triggers: triggers)
+    }
+
+    static func _testMatchedTriggerWord(_ text: String, triggers: [String]) -> String? {
+        self.matchedTriggerWordText(transcript: text, triggers: triggers)
+    }
+
     static func _testAttributedColor(isFinal: Bool) -> NSColor {
         VoiceOverlayTextFormatting.makeAttributed(committed: "sample", volatile: "", isFinal: isFinal)
             .attribute(.foregroundColor, at: 0, effectiveRange: nil) as? NSColor ?? .clear

apps/macos/Sources/OpenClaw/VoiceWakeTextUtils.swift

@@ -4,6 +4,11 @@ import SwabbleKit
 enum VoiceWakeTextUtils {
     private static let whitespaceAndPunctuation = CharacterSet.whitespacesAndNewlines
         .union(.punctuationCharacters)
+        .union(.symbols)
+    private static let wakePrefixFillers: Set<String> = [
+        "a", "ah", "eh", "er", "erm", "hey", "hmm", "huh", "mhm", "mm", "oh", "uh", "um",
+        "yo", "呃", "嗯", "啊", "诶", "欸",
+    ]
     typealias TrimWake = (String, [String]) -> String
 
     static func normalizeToken(_ token: String) -> String {
@@ -12,6 +17,104 @@ enum VoiceWakeTextUtils {
             .lowercased()
     }
 
+    private static func normalizedTriggerTokens(_ trigger: String) -> [String] {
+        trigger
+            .split(whereSeparator: { $0.isWhitespace })
+            .map { self.normalizeToken(String($0)) }
+            .filter { !$0.isEmpty }
+    }
+
+    private static func isASCIIWordScalar(_ scalar: UnicodeScalar) -> Bool {
+        scalar.isASCII && CharacterSet.alphanumerics.contains(scalar)
+    }
+
+    private static func requiresASCIIWordBoundaries(_ value: String) -> Bool {
+        value.unicodeScalars.contains(where: self.isASCIIWordScalar)
+    }
+
+    private static func hasASCIIWordBoundaries(
+        transcript: String,
+        range: Range<String.Index>,
+        trigger: String) -> Bool
+    {
+        guard self.requiresASCIIWordBoundaries(trigger) else { return true }
+
+        if range.lowerBound > transcript.startIndex {
+            let beforeIndex = transcript.index(before: range.lowerBound)
+            let beforeScalars = transcript[beforeIndex].unicodeScalars
+            if beforeScalars.contains(where: self.isASCIIWordScalar) {
+                return false
+            }
+        }
+
+        if range.upperBound < transcript.endIndex {
+            let afterScalars = transcript[range.upperBound].unicodeScalars
+            if afterScalars.contains(where: self.isASCIIWordScalar) {
+                return false
+            }
+        }
+
+        return true
+    }
+
+    private static func bestRawTriggerMatch(
+        transcript: String,
+        triggers: [String]) -> (range: Range<String.Index>, normalizedTrigger: String)?
+    {
+        var bestMatch: (range: Range<String.Index>, normalizedTrigger: String, tokenCount: Int)?
+
+        for trigger in triggers {
+            let normalizedTokens = self.normalizedTriggerTokens(trigger)
+            guard !normalizedTokens.isEmpty else { continue }
+            let rawTrigger = trigger.trimmingCharacters(in: self.whitespaceAndPunctuation)
+            let tokenCount = normalizedTokens.count
+            guard !rawTrigger.isEmpty else { continue }
+
+            var searchStart = transcript.startIndex
+            while searchStart < transcript.endIndex,
+                  let range = transcript.range(
+                      of: rawTrigger,
+                      options: [.caseInsensitive, .diacriticInsensitive, .widthInsensitive],
+                      range: searchStart..<transcript.endIndex)
+            {
+                defer {
+                    searchStart = transcript.index(after: range.lowerBound)
+                }
+                guard self.hasASCIIWordBoundaries(
+                    transcript: transcript,
+                    range: range,
+                    trigger: rawTrigger)
+                else { continue }
+
+                if let bestMatch {
+                    if range.lowerBound > bestMatch.range.lowerBound { continue }
+                    if range.lowerBound == bestMatch.range.lowerBound,
+                       tokenCount <= bestMatch.tokenCount
+                    {
+                        continue
+                    }
+                }
+
+                bestMatch = (range, normalizedTokens.joined(separator: " "), tokenCount)
+                break
+            }
+
+            if let bestMatch,
+               bestMatch.range.lowerBound == transcript.startIndex,
+               bestMatch.tokenCount >= tokenCount
+            {
+                // Earlier matches take precedence, so once we match from the
+                // start there is no need to scan later triggers with fewer
+                // tokens at the same offset.
+                if bestMatch.tokenCount > tokenCount {
+                    continue
+                }
+            }
+        }
+
+        return bestMatch.map { (range: $0.range, normalizedTrigger: $0.normalizedTrigger) }
+    }
+
     static func startsWithTrigger(transcript: String, triggers: [String]) -> Bool {
         let tokens = transcript
             .split(whereSeparator: { $0.isWhitespace })
@@ -19,10 +122,7 @@ enum VoiceWakeTextUtils {
             .filter { !$0.isEmpty }
         guard !tokens.isEmpty else { return false }
         for trigger in triggers {
-            let triggerTokens = trigger
-                .split(whereSeparator: { $0.isWhitespace })
-                .map { self.normalizeToken(String($0)) }
-                .filter { !$0.isEmpty }
+            let triggerTokens = self.normalizedTriggerTokens(trigger)
             guard !triggerTokens.isEmpty, tokens.count >= triggerTokens.count else { continue }
             if zip(triggerTokens, tokens.prefix(triggerTokens.count)).allSatisfy({ $0 == $1 }) {
                 return true
@@ -40,9 +140,55 @@ enum VoiceWakeTextUtils {
         guard !transcript.isEmpty else { return nil }
         guard !self.normalizeToken(transcript).isEmpty else { return nil }
         guard WakeWordGate.matchesTextOnly(text: transcript, triggers: triggers) else { return nil }
-        guard self.startsWithTrigger(transcript: transcript, triggers: triggers) else { return nil }
+        guard
+            self.startsWithTrigger(transcript: transcript, triggers: triggers)
+            || self.hasOnlyFillerBeforeTrigger(transcript: transcript, triggers: triggers)
+        else { return nil }
         let trimmed = trimWake(transcript, triggers)
         guard trimmed.count >= minCommandLength else { return nil }
         return trimmed
     }
+
+    static func hasOnlyFillerBeforeTrigger(transcript: String, triggers: [String]) -> Bool {
+        guard let match = self.bestRawTriggerMatch(transcript: transcript, triggers: triggers) else { return false }
+        let prefixTokens = transcript[..<match.range.lowerBound]
+            .split(whereSeparator: {
+                $0.isWhitespace || self.whitespaceAndPunctuation.contains($0.unicodeScalars.first!)
+            })
+            .map { self.normalizeToken(String($0)) }
+            .filter { !$0.isEmpty }
+        return prefixTokens.allSatisfy { self.wakePrefixFillers.contains($0) }
+    }
+
+    static func matchedTriggerWord(transcript: String, triggers: [String]) -> String? {
+        if let rawMatch = self.bestRawTriggerMatch(transcript: transcript, triggers: triggers) {
+            return rawMatch.normalizedTrigger
+        }
+
+        let transcriptTokens = transcript
+            .split(whereSeparator: { $0.isWhitespace })
+            .map { self.normalizeToken(String($0)) }
+            .filter { !$0.isEmpty }
+        guard !transcriptTokens.isEmpty else { return nil }
+
+        var bestStartIndex = Int.max
+        var bestTokenCount = -1
+        var bestTokens: [String]?
+
+        for trigger in triggers {
+            let triggerTokens = self.normalizedTriggerTokens(trigger)
+            guard !triggerTokens.isEmpty, transcriptTokens.count >= triggerTokens.count else { continue }
+            for index in 0...(transcriptTokens.count - triggerTokens.count) {
+                let candidate = transcriptTokens[index..<(index + triggerTokens.count)]
+                guard zip(triggerTokens, candidate).allSatisfy({ $0 == $1 }) else { continue }
+                if index < bestStartIndex || (index == bestStartIndex && triggerTokens.count > bestTokenCount) {
+                    bestStartIndex = index
+                    bestTokenCount = triggerTokens.count
+                    bestTokens = triggerTokens
+                }
+            }
+        }
+
+        return bestTokens?.joined(separator: " ")
+    }
 }

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -595,11 +595,14 @@ public struct AgentParams: Codable, Sendable {
     public let besteffortdeliver: Bool?
     public let lane: String?
     public let cleanupbundlemcponrunend: Bool?
+    public let modelrun: Bool?
+    public let promptmode: AnyCodable?
     public let extrasystemprompt: String?
     public let bootstrapcontextmode: AnyCodable?
     public let bootstrapcontextrunkind: AnyCodable?
     public let internalevents: [[String: AnyCodable]]?
     public let inputprovenance: [String: AnyCodable]?
+    public let voicewaketrigger: String?
     public let idempotencykey: String
     public let label: String?
 
@@ -627,11 +630,14 @@ public struct AgentParams: Codable, Sendable {
         besteffortdeliver: Bool?,
         lane: String?,
         cleanupbundlemcponrunend: Bool?,
+        modelrun: Bool?,
+        promptmode: AnyCodable?,
         extrasystemprompt: String?,
         bootstrapcontextmode: AnyCodable?,
         bootstrapcontextrunkind: AnyCodable?,
         internalevents: [[String: AnyCodable]]?,
         inputprovenance: [String: AnyCodable]?,
+        voicewaketrigger: String?,
         idempotencykey: String,
         label: String?)
     {
@@ -658,11 +664,14 @@ public struct AgentParams: Codable, Sendable {
         self.besteffortdeliver = besteffortdeliver
         self.lane = lane
         self.cleanupbundlemcponrunend = cleanupbundlemcponrunend
+        self.modelrun = modelrun
+        self.promptmode = promptmode
         self.extrasystemprompt = extrasystemprompt
         self.bootstrapcontextmode = bootstrapcontextmode
         self.bootstrapcontextrunkind = bootstrapcontextrunkind
         self.internalevents = internalevents
         self.inputprovenance = inputprovenance
+        self.voicewaketrigger = voicewaketrigger
         self.idempotencykey = idempotencykey
         self.label = label
     }
@@ -691,11 +700,14 @@ public struct AgentParams: Codable, Sendable {
         case besteffortdeliver = "bestEffortDeliver"
         case lane
         case cleanupbundlemcponrunend = "cleanupBundleMcpOnRunEnd"
+        case modelrun = "modelRun"
+        case promptmode = "promptMode"
         case extrasystemprompt = "extraSystemPrompt"
         case bootstrapcontextmode = "bootstrapContextMode"
         case bootstrapcontextrunkind = "bootstrapContextRunKind"
         case internalevents = "internalEvents"
         case inputprovenance = "inputProvenance"
+        case voicewaketrigger = "voiceWakeTrigger"
         case idempotencykey = "idempotencyKey"
         case label
     }

apps/macos/Tests/OpenClawIPCTests/AppStateRemoteConfigTests.swift

@@ -1,3 +1,4 @@
+import Foundation
 import Testing
 @testable import OpenClaw
 
@@ -36,6 +37,130 @@ struct AppStateRemoteConfigTests {
         #expect((remote["token"] as? String) == nil)
     }
 
+    @Test
+    func updatedRemoteGatewayConfigPinsLoopbackUrlForSshTransport() {
+        let remote = AppState._testUpdatedRemoteGatewayConfig(
+            current: ["url": "ws://gateway.example:18789"],
+            draft: .init(
+                transport: .ssh,
+                remoteUrl: "",
+                remoteHost: "gateway.example",
+                remoteTarget: "alice@gateway.example",
+                remoteIdentity: "",
+                remoteToken: "",
+                remoteTokenDirty: false))
+
+        #expect(remote["url"] as? String == "ws://127.0.0.1:18789")
+        #expect((remote["transport"] as? String) == nil)
+        #expect(remote["sshTarget"] as? String == "alice@gateway.example")
+    }
+
+    @Test
+    func updatedRemoteGatewayConfigPreservesCustomLoopbackTunnelPort() {
+        let remote = AppState._testUpdatedRemoteGatewayConfig(
+            current: ["url": "ws://localhost.:29876"],
+            draft: .init(
+                transport: .ssh,
+                remoteUrl: "",
+                remoteHost: "gateway.example",
+                remoteTarget: "alice@gateway.example",
+                remoteIdentity: "",
+                remoteToken: "",
+                remoteTokenDirty: false))
+
+        #expect(remote["url"] as? String == "ws://127.0.0.1:29876")
+    }
+
+    @Test
+    func updatedRemoteGatewayConfigPreservesCustomPortWhenExistingHostMatchesSshTarget() {
+        let remote = AppState._testUpdatedRemoteGatewayConfig(
+            current: ["url": "ws://gateway.example:19999"],
+            draft: .init(
+                transport: .ssh,
+                remoteUrl: "",
+                remoteHost: nil,
+                remoteTarget: "alice@gateway.example",
+                remoteIdentity: "",
+                remoteToken: "",
+                remoteTokenDirty: false))
+
+        #expect(remote["url"] as? String == "ws://127.0.0.1:19999")
+    }
+
+    @Test
+    func updatedRemoteGatewayConfigDropsCustomPortWhenExistingHostDoesNotMatchSshTarget() {
+        let remote = AppState._testUpdatedRemoteGatewayConfig(
+            current: ["url": "ws://other-host.example:19999"],
+            draft: .init(
+                transport: .ssh,
+                remoteUrl: "",
+                remoteHost: "gateway.example",
+                remoteTarget: "alice@gateway.example",
+                remoteIdentity: "",
+                remoteToken: "",
+                remoteTokenDirty: false))
+
+        #expect(remote["url"] as? String == "ws://127.0.0.1:18789")
+    }
+
+    @Test
+    func updatedRemoteGatewayConfigDoesNotPreservePortForHostnamePrefixCollision() {
+        let remote = AppState._testUpdatedRemoteGatewayConfig(
+            current: ["url": "ws://example.attacker.tld:19999"],
+            draft: .init(
+                transport: .ssh,
+                remoteUrl: "",
+                remoteHost: nil,
+                remoteTarget: "alice@example.com",
+                remoteIdentity: "",
+                remoteToken: "",
+                remoteTokenDirty: false))
+
+        #expect(remote["url"] as? String == "ws://127.0.0.1:18789")
+    }
+
+    @Test
+    func appStateInitDoesNotInferLoopbackHostIntoRemoteTarget() async {
+        let configPath = TestIsolation.tempConfigPath()
+        await TestIsolation.withIsolatedState(
+            env: ["OPENCLAW_CONFIG_PATH": configPath],
+            defaults: [remoteTargetKey: nil])
+        {
+            OpenClawConfigFile.saveDict([
+                "gateway": [
+                    "mode": "remote",
+                    "remote": [
+                        "url": "ws://127.0.0.1:19999",
+                    ],
+                ],
+            ])
+
+            let state = AppState(preview: true)
+            #expect(state.remoteTarget == "")
+        }
+    }
+
+    @Test
+    func appStateInitPreservesExistingRemoteTargetWhenRemoteUrlIsLoopback() async {
+        let configPath = TestIsolation.tempConfigPath()
+        await TestIsolation.withIsolatedState(
+            env: ["OPENCLAW_CONFIG_PATH": configPath],
+            defaults: [remoteTargetKey: "alice@gateway.example"])
+        {
+            OpenClawConfigFile.saveDict([
+                "gateway": [
+                    "mode": "remote",
+                    "remote": [
+                        "url": "ws://127.0.0.1:19999",
+                    ],
+                ],
+            ])
+
+            let state = AppState(preview: true)
+            #expect(state.remoteTarget == "alice@gateway.example")
+        }
+    }
+
     @Test
     func syncedGatewayRootPreservesObjectTokenAcrossModeAndTransportChangesWhenUntouched() {
         let initialRoot: [String: Any] = [

apps/macos/Tests/OpenClawIPCTests/GatewayConnectionControlTests.swift

@@ -6,6 +6,10 @@ import Testing
 
 private final class FakeWebSocketTask: WebSocketTasking, @unchecked Sendable {
     var state: URLSessionTask.State = .running
+    var autoRespond = false
+    private(set) var sentMessages: [URLSessionWebSocketTask.Message] = []
+    private var sentChallenge = false
+    private var respondedRequestIds = Set<String>()
 
     func resume() {}
 
@@ -13,41 +17,90 @@ private final class FakeWebSocketTask: WebSocketTasking, @unchecked Sendable {
         self.state = .canceling
     }
 
-    func send(_: URLSessionWebSocketTask.Message) async throws {}
+    func send(_ message: URLSessionWebSocketTask.Message) async throws {
+        self.sentMessages.append(message)
+    }
 
     func receive() async throws -> URLSessionWebSocketTask.Message {
+        if self.autoRespond {
+            if !self.sentChallenge {
+                self.sentChallenge = true
+                return .string("""
+                {"type":"event","event":"connect.challenge","payload":{"nonce":"test-nonce"}}
+                """)
+            }
+            if let request = self.latestUnrespondedRequest() {
+                self.respondedRequestIds.insert(request.id)
+                if request.method == "connect" {
+                    return .string("""
+                    {"type":"res","id":"\(request.id)","ok":true,"payload":{"type":"hello","protocol":3,"server":{},"features":{},"snapshot":{"presence":[],"health":{},"stateVersion":{"presence":0,"health":0},"uptimeMs":0},"policy":{}}}
+                    """)
+                }
+                return .string("""
+                {"type":"res","id":"\(request.id)","ok":true,"payload":{}}
+                """)
+            }
+        }
         throw URLError(.cannotConnectToHost)
     }
 
     func receive(completionHandler: @escaping @Sendable (Result<URLSessionWebSocketTask.Message, Error>) -> Void) {
         completionHandler(.failure(URLError(.cannotConnectToHost)))
     }
-}
 
-private final class FakeWebSocketSession: WebSocketSessioning, @unchecked Sendable {
-    func makeWebSocketTask(url _: URL) -> WebSocketTaskBox {
-        WebSocketTaskBox(task: FakeWebSocketTask())
+    private func latestUnrespondedRequest() -> (id: String, method: String)? {
+        for message in self.sentMessages.reversed() {
+            let data: Data?
+            switch message {
+            case .string(let text):
+                data = Data(text.utf8)
+            case .data(let raw):
+                data = raw
+            @unknown default:
+                data = nil
+            }
+            guard let data,
+                  let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+                  let id = json["id"] as? String,
+                  let method = json["method"] as? String,
+                  !self.respondedRequestIds.contains(id)
+            else {
+                continue
+            }
+            return (id, method)
+        }
+        return nil
     }
 }
 
-private func makeTestGatewayConnection() -> GatewayConnection {
-    GatewayConnection(
+private final class FakeWebSocketSession: WebSocketSessioning, @unchecked Sendable {
+    let task = FakeWebSocketTask()
+
+    func makeWebSocketTask(url _: URL) -> WebSocketTaskBox {
+        WebSocketTaskBox(task: self.task)
+    }
+}
+
+private func makeTestGatewayConnection() -> (GatewayConnection, FakeWebSocketSession) {
+    let session = FakeWebSocketSession()
+    let connection = GatewayConnection(
         configProvider: {
             (url: URL(string: "ws://127.0.0.1:1")!, token: nil, password: nil)
         },
-        sessionBox: WebSocketSessionBox(session: FakeWebSocketSession()))
+        sessionBox: WebSocketSessionBox(session: session))
+    return (connection, session)
 }
 
 @Suite(.serialized) struct GatewayConnectionControlTests {
     @Test func `status fails when process missing`() async {
-        let connection = makeTestGatewayConnection()
+        let (connection, _) = makeTestGatewayConnection()
         let result = await connection.status()
         #expect(result.ok == false)
         #expect(result.error != nil)
     }
 
     @Test func `reject empty message`() async {
-        let connection = makeTestGatewayConnection()
+        let (connection, _) = makeTestGatewayConnection()
         let result = await connection.sendAgent(
             message: "",
             thinking: nil,
@@ -56,4 +109,38 @@ private func makeTestGatewayConnection() -> GatewayConnection {
             to: nil)
         #expect(result.ok == false)
     }
+
+    @Test func `send agent keeps empty voice wake trigger field`() async throws {
+        let (connection, session) = makeTestGatewayConnection()
+        session.task.autoRespond = true
+        _ = await connection.sendAgent(GatewayAgentInvocation(
+            message: "test",
+            sessionKey: "main",
+            thinking: nil,
+            deliver: false,
+            to: nil,
+            channel: .last,
+            timeoutSeconds: nil,
+            idempotencyKey: "idem-1",
+            voiceWakeTrigger: "   "))
+
+        guard let lastMessage = session.task.sentMessages.last else {
+            Issue.record("expected websocket send payload")
+            return
+        }
+        let payloadData: Data
+        switch lastMessage {
+        case .string(let text):
+            payloadData = Data(text.utf8)
+        case .data(let data):
+            payloadData = data
+        @unknown default:
+            Issue.record("unexpected websocket message type")
+            return
+        }
+
+        let json = try JSONSerialization.jsonObject(with: payloadData) as? [String: Any]
+        let params = json?["params"] as? [String: Any]
+        #expect(params?["voiceWakeTrigger"] as? String == "")
+    }
 }

apps/macos/Tests/OpenClawIPCTests/GatewayDiscoverySelectionSupportTests.swift

@@ -84,7 +84,35 @@ struct GatewayDiscoverySelectionSupportTests {
                 state: state)
 
             #expect(state.remoteTransport == .ssh)
+            #expect(state.remoteUrl == "ws://127.0.0.1:18789")
             #expect(CommandResolver.parseSSHTarget(state.remoteTarget)?.host == "nearby-gateway.local")
+
+            let configRoot = OpenClawConfigFile.loadDict()
+            let remote = ((configRoot["gateway"] as? [String: Any])?["remote"] as? [String: Any]) ?? [:]
+            #expect(remote["url"] as? String == "ws://127.0.0.1:18789")
+        }
+    }
+
+    @Test func `selecting nearby lan gateway preserves existing ssh tunnel port`() async {
+        let configPath = TestIsolation.tempConfigPath()
+        await TestIsolation.withEnvValues(["OPENCLAW_CONFIG_PATH": configPath]) {
+            let state = AppState(preview: true)
+            state.remoteTransport = .ssh
+            state.remoteUrl = "ws://localhost:29876"
+
+            GatewayDiscoverySelectionSupport.applyRemoteSelection(
+                gateway: self.makeGateway(
+                    serviceHost: "nearby-gateway.local",
+                    servicePort: 19999,
+                    stableID: "bonjour|nearby-gateway-custom"),
+                state: state)
+
+            #expect(state.remoteTransport == .ssh)
+            #expect(state.remoteUrl == "ws://127.0.0.1:29876")
+
+            let configRoot = OpenClawConfigFile.loadDict()
+            let remote = ((configRoot["gateway"] as? [String: Any])?["remote"] as? [String: Any]) ?? [:]
+            #expect(remote["url"] as? String == "ws://127.0.0.1:29876")
         }
     }
 }

apps/macos/Tests/OpenClawIPCTests/MacNodeBrowserProxyTests.swift

@@ -83,4 +83,28 @@ struct MacNodeBrowserProxyTests {
         let arr = try #require(parsed["arr"] as? [Any])
         #expect(arr.count == 2)
     }
+
+    @Test func requestReportsActionableUnavailableWhenControlServiceIsMissing() async throws {
+        let proxy = MacNodeBrowserProxy(
+            endpointProvider: {
+                MacNodeBrowserProxy.Endpoint(
+                    baseURL: URL(string: "http://127.0.0.1:18791")!,
+                    token: nil,
+                    password: nil)
+            },
+            performRequest: { _ in
+                throw URLError(.cannotConnectToHost)
+            })
+
+        do {
+            _ = try await proxy.request(paramsJSON: #"{"method":"GET","path":"/"}"#)
+            Issue.record("request should fail when browser control is unreachable")
+        } catch {
+            let message = error.localizedDescription
+            #expect(message.contains("UNAVAILABLE: macOS app node could not reach the local browser control service"))
+            #expect(message.contains("http://127.0.0.1:18791"))
+            #expect(message.contains("browser control is owned by the CLI node-host"))
+            #expect(message.contains("openclaw node start"))
+        }
+    }
 }

apps/macos/Tests/OpenClawIPCTests/MacNodeModeCoordinatorTests.swift

@@ -0,0 +1,32 @@
+import Foundation
+import OpenClawKit
+import Testing
+@testable import OpenClaw
+
+struct MacNodeModeCoordinatorTests {
+    @Test func remoteModeDoesNotAdvertiseBrowserProxy() {
+        let caps = MacNodeModeCoordinator.resolvedCaps(
+            browserControlEnabled: true,
+            cameraEnabled: false,
+            locationMode: .off,
+            connectionMode: .remote)
+        let commands = MacNodeModeCoordinator.resolvedCommands(caps: caps)
+
+        #expect(!caps.contains(OpenClawCapability.browser.rawValue))
+        #expect(!commands.contains(OpenClawBrowserCommand.proxy.rawValue))
+        #expect(commands.contains(OpenClawCanvasCommand.present.rawValue))
+        #expect(commands.contains(OpenClawSystemCommand.notify.rawValue))
+    }
+
+    @Test func localModeAdvertisesBrowserProxyWhenEnabled() {
+        let caps = MacNodeModeCoordinator.resolvedCaps(
+            browserControlEnabled: true,
+            cameraEnabled: false,
+            locationMode: .off,
+            connectionMode: .local)
+        let commands = MacNodeModeCoordinator.resolvedCommands(caps: caps)
+
+        #expect(caps.contains(OpenClawCapability.browser.rawValue))
+        #expect(commands.contains(OpenClawBrowserCommand.proxy.rawValue))
+    }
+}

apps/macos/Tests/OpenClawIPCTests/OpenClawConfigFileTests.swift

@@ -35,8 +35,30 @@ struct OpenClawConfigFileTests {
             ])
             #expect(OpenClawConfigFile.remoteGatewayPort() == 19999)
             #expect(OpenClawConfigFile.remoteGatewayPort(matchingHost: "gateway.ts.net") == 19999)
-            #expect(OpenClawConfigFile.remoteGatewayPort(matchingHost: "gateway") == 19999)
+            #expect(OpenClawConfigFile.remoteGatewayPort(matchingHost: "GATEWAY.ts.net.") == 19999)
+            #expect(OpenClawConfigFile.remoteGatewayPort(matchingHost: "gateway") == nil)
             #expect(OpenClawConfigFile.remoteGatewayPort(matchingHost: "other.ts.net") == nil)
+            #expect(OpenClawConfigFile.remoteGatewayPort(matchingHost: "gateway.attacker.tld") == nil)
+        }
+    }
+
+    @MainActor
+    @Test
+    func `set remote gateway url string replaces scheme`() async {
+        let override = self.makeConfigOverridePath()
+
+        await TestIsolation.withEnvValues(["OPENCLAW_CONFIG_PATH": override]) {
+            OpenClawConfigFile.saveDict([
+                "gateway": [
+                    "remote": [
+                        "url": "wss://old-host:111",
+                    ],
+                ],
+            ])
+            OpenClawConfigFile.setRemoteGatewayUrlString("ws://127.0.0.1:18789")
+            let root = OpenClawConfigFile.loadDict()
+            let url = ((root["gateway"] as? [String: Any])?["remote"] as? [String: Any])?["url"] as? String
+            #expect(url == "ws://127.0.0.1:18789")
         }
     }
 

apps/macos/Tests/OpenClawIPCTests/VoiceWakeRuntimeTests.swift

@@ -35,6 +35,80 @@ struct VoiceWakeRuntimeTests {
         #expect(VoiceWakeRuntime._testHasContentAfterTrigger(text, triggers: triggers))
     }
 
+    @Test func `trigger only allows filler before trigger`() {
+        let triggers = ["openclaw"]
+        let text = "uh openclaw"
+        #expect(VoiceWakeRuntime._testIsTriggerOnly(text, triggers: triggers))
+    }
+
+    @Test func `trigger only rejects trailing wake word mentions in ordinary speech`() {
+        let triggers = ["openclaw"]
+        let text = "tell me about openclaw"
+        #expect(!VoiceWakeRuntime._testIsTriggerOnly(text, triggers: triggers))
+    }
+
+    @Test func `matched trigger finds trigger not at transcript start`() {
+        let triggers = ["openclaw"]
+        let text = "uh openclaw"
+        #expect(VoiceWakeRuntime._testMatchedTriggerWord(text, triggers: triggers) == "openclaw")
+    }
+
+    @Test func `matched trigger rejects larger word suffix matches`() {
+        let triggers = ["computer"]
+        let text = "uh computers"
+        #expect(VoiceWakeRuntime._testMatchedTriggerWord(text, triggers: triggers) == nil)
+    }
+
+    @Test func `matched trigger prefers most specific overlapping phrase`() {
+        let triggers = ["openclaw", "hey openclaw"]
+        let text = "hey openclaw"
+        #expect(VoiceWakeRuntime._testMatchedTriggerWord(text, triggers: triggers) == "hey openclaw")
+    }
+
+    @Test func `matched trigger handles width insensitive forms without whitespace tokens`() {
+        let triggers = ["openclaw"]
+        let text = "ＯｐｅｎＣｌａｗ"
+        #expect(VoiceWakeRuntime._testMatchedTriggerWord(text, triggers: triggers) == "openclaw")
+    }
+
+    @Test func `matched trigger handles chinese forms without whitespace tokens`() {
+        let triggers = ["小爪"]
+        let text = "嘿小爪"
+        #expect(VoiceWakeRuntime._testMatchedTriggerWord(text, triggers: triggers) == "小爪")
+    }
+
+    @Test func `text only fallback populates matched trigger`() {
+        let transcript = "hey openclaw do thing"
+        let config = WakeWordGateConfig(triggers: ["openclaw"], minCommandLength: 1)
+        let match = VoiceWakeRecognitionDebugSupport.textOnlyFallbackMatch(
+            transcript: transcript,
+            triggers: ["openclaw"],
+            config: config,
+            trimWake: VoiceWakeRuntime._testTrimmedAfterTrigger)
+        #expect(match?.trigger == "openclaw")
+    }
+
+    @Test func `text only fallback keeps the first trigger phrase when later words match another trigger`() {
+        let transcript = "openclaw tell me about computer vision"
+        let config = WakeWordGateConfig(triggers: ["openclaw", "computer"], minCommandLength: 1)
+        let match = VoiceWakeRecognitionDebugSupport.textOnlyFallbackMatch(
+            transcript: transcript,
+            triggers: ["openclaw", "computer"],
+            config: config,
+            trimWake: VoiceWakeRuntime._testTrimmedAfterTrigger)
+        #expect(match?.trigger == "openclaw")
+    }
+
+    @Test func `text only fallback rejects filler prefixed larger word suffix matches`() {
+        let transcript = "uh computers"
+        let config = WakeWordGateConfig(triggers: ["computer"], minCommandLength: 1)
+        let match = VoiceWakeRecognitionDebugSupport.textOnlyFallbackMatch(
+            transcript: transcript,
+            triggers: ["computer"],
+            config: config,
+            trimWake: VoiceWakeRuntime._testTrimmedAfterTrigger)
+        #expect(match == nil)
+    }
     @Test func `trims after chinese trigger keeps post speech`() {
         let triggers = ["小爪", "openclaw"]
         let text = "嘿 小爪 帮我打开设置"

apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

@@ -595,11 +595,14 @@ public struct AgentParams: Codable, Sendable {
     public let besteffortdeliver: Bool?
     public let lane: String?
     public let cleanupbundlemcponrunend: Bool?
+    public let modelrun: Bool?
+    public let promptmode: AnyCodable?
     public let extrasystemprompt: String?
     public let bootstrapcontextmode: AnyCodable?
     public let bootstrapcontextrunkind: AnyCodable?
     public let internalevents: [[String: AnyCodable]]?
     public let inputprovenance: [String: AnyCodable]?
+    public let voicewaketrigger: String?
     public let idempotencykey: String
     public let label: String?
 
@@ -627,11 +630,14 @@ public struct AgentParams: Codable, Sendable {
         besteffortdeliver: Bool?,
         lane: String?,
         cleanupbundlemcponrunend: Bool?,
+        modelrun: Bool?,
+        promptmode: AnyCodable?,
         extrasystemprompt: String?,
         bootstrapcontextmode: AnyCodable?,
         bootstrapcontextrunkind: AnyCodable?,
         internalevents: [[String: AnyCodable]]?,
         inputprovenance: [String: AnyCodable]?,
+        voicewaketrigger: String?,
         idempotencykey: String,
         label: String?)
     {
@@ -658,11 +664,14 @@ public struct AgentParams: Codable, Sendable {
         self.besteffortdeliver = besteffortdeliver
         self.lane = lane
         self.cleanupbundlemcponrunend = cleanupbundlemcponrunend
+        self.modelrun = modelrun
+        self.promptmode = promptmode
         self.extrasystemprompt = extrasystemprompt
         self.bootstrapcontextmode = bootstrapcontextmode
         self.bootstrapcontextrunkind = bootstrapcontextrunkind
         self.internalevents = internalevents
         self.inputprovenance = inputprovenance
+        self.voicewaketrigger = voicewaketrigger
         self.idempotencykey = idempotencykey
         self.label = label
     }
@@ -691,11 +700,14 @@ public struct AgentParams: Codable, Sendable {
         case besteffortdeliver = "bestEffortDeliver"
         case lane
         case cleanupbundlemcponrunend = "cleanupBundleMcpOnRunEnd"
+        case modelrun = "modelRun"
+        case promptmode = "promptMode"
         case extrasystemprompt = "extraSystemPrompt"
         case bootstrapcontextmode = "bootstrapContextMode"
         case bootstrapcontextrunkind = "bootstrapContextRunKind"
         case internalevents = "internalEvents"
         case inputprovenance = "inputProvenance"
+        case voicewaketrigger = "voiceWakeTrigger"
         case idempotencykey = "idempotencyKey"
         case label
     }

docker-compose.yml

@@ -6,6 +6,9 @@ services:
       TERM: xterm-256color
       OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
       OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}
+      # Docker bridge networks usually do not carry mDNS multicast reliably.
+      # Set OPENCLAW_DISABLE_BONJOUR=0 only on host/macvlan/mDNS-capable networks.
+      OPENCLAW_DISABLE_BONJOUR: ${OPENCLAW_DISABLE_BONJOUR:-1}
       CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
       CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
       CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-211e9d4cdb309e7fe0c1ed91d060201240a9287f8c5cb3c893aba3f904a20d30  config-baseline.json
-ffda2d2911adc03148a368f3b40b17cbdcb7af0066bccdc555e8d596cdea8cda  config-baseline.core.json
+f1eefb91a486188915373b09199959f0f1a7cd01dc75ef923832741f72a12543  config-baseline.json
+9f0e386d5118cbca785a2e8e9c8b170d844faf1b7ef5e82e6b15d9e1c39f3796  config-baseline.core.json
 7cd9c908f066c143eab2a201efbc9640f483ab28bba92ddeca1d18cc2b528bc3  config-baseline.channel.json
-9e131d7734f8b9cc9e7f8af6cc6b6dc81c9971dc551fadbe66fb0d682173f32d  config-baseline.plugin.json
+a5479c182ec987bb21e814b8a4e7b3bda7190ae5c2b35fd5ca403dfa48afa115  config-baseline.plugin.json

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

@@ -1,2 +1,2 @@
-c911117176b41eebf26470618274a7e093910e9b36855bc045bc8a92f6856745  plugin-sdk-api-baseline.json
-ff360635f95beb217b9dd207a87eaf331319a7671aea03acfe05911756741b21  plugin-sdk-api-baseline.jsonl
+947221d62a0eb0b66250fba2b011ca28a11cb1058bc542b9c155d55479f15935  plugin-sdk-api-baseline.json
+0d750f785adbe4d90f209842ed9297476669dd62f7be81fa41e06b6736cc2aaf  plugin-sdk-api-baseline.jsonl

docs/automation/cron-jobs.md

@@ -5,29 +5,37 @@ read_when:
   - Wiring external triggers (webhooks, Gmail) into OpenClaw
   - Deciding between heartbeat and cron for scheduled tasks
 title: "Scheduled tasks"
+sidebarTitle: "Scheduled tasks"
 ---
 
 Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can deliver output back to a chat channel or webhook endpoint.
 
 ## Quick start
 
-```bash
-# Add a one-shot reminder
-openclaw cron add \
-  --name "Reminder" \
-  --at "2026-02-01T16:00:00Z" \
-  --session main \
-  --system-event "Reminder: check the cron docs draft" \
-  --wake now \
-  --delete-after-run
-
-# Check your jobs
-openclaw cron list
-openclaw cron show <job-id>
-
-# See run history
-openclaw cron runs --id <job-id>
-```
+<Steps>
+  <Step title="Add a one-shot reminder">
+    ```bash
+    openclaw cron add \
+      --name "Reminder" \
+      --at "2026-02-01T16:00:00Z" \
+      --session main \
+      --system-event "Reminder: check the cron docs draft" \
+      --wake now \
+      --delete-after-run
+    ```
+  </Step>
+  <Step title="Check your jobs">
+    ```bash
+    openclaw cron list
+    openclaw cron show <job-id>
+    ```
+  </Step>
+  <Step title="See run history">
+    ```bash
+    openclaw cron runs --id <job-id>
+    ```
+  </Step>
+</Steps>
 
 ## How cron works
 
@@ -38,18 +46,13 @@ openclaw cron runs --id <job-id>
 - All cron executions create [background task](/automation/tasks) records.
 - One-shot jobs (`--at`) auto-delete after success by default.
 - Isolated cron runs best-effort close tracked browser tabs/processes for their `cron:<jobId>` session when the run completes, so detached browser automation does not leave orphaned processes behind.
-- Isolated cron runs also guard against stale acknowledgement replies. If the
-  first result is just an interim status update (`on it`, `pulling everything
-together`, and similar hints) and no descendant subagent run is still
-  responsible for the final answer, OpenClaw re-prompts once for the actual
-  result before delivery.
+- Isolated cron runs also guard against stale acknowledgement replies. If the first result is just an interim status update (`on it`, `pulling everything together`, and similar hints) and no descendant subagent run is still responsible for the final answer, OpenClaw re-prompts once for the actual result before delivery.
 
 <a id="maintenance"></a>
 
-Task reconciliation for cron is runtime-owned: an active cron task stays live while the
-cron runtime still tracks that job as running, even if an old child session row still exists.
-Once the runtime stops owning the job and the 5-minute grace window expires, maintenance can
-mark the task `lost`.
+<Note>
+Task reconciliation for cron is runtime-owned first, durable-history-backed second: an active cron task stays live while the cron runtime still tracks that job as running, even if an old child session row still exists. Once the runtime stops owning the job and the 5-minute grace window expires, maintenance checks persisted run logs and job state for the matching `cron:<jobId>:<startedAt>` run. If that durable history shows a terminal result, the task ledger is finalized from it; otherwise Gateway-owned maintenance can mark the task `lost`. Offline CLI audit can recover from durable history, but it does not treat its own empty in-process active-job set as proof that a Gateway-owned cron run is gone.
+</Note>
 
 ## Schedule types
 
@@ -84,35 +87,46 @@ This fires ~5–6 times per month instead of 0–1 times per month. OpenClaw use
 | Current session | `current`           | Bound at creation time   | Context-aware recurring work    |
 | Custom session  | `session:custom-id` | Persistent named session | Workflows that build on history |
 
-**Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). Those system events do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
+<AccordionGroup>
+  <Accordion title="Main session vs isolated vs custom">
+    **Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). Those system events do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
+  </Accordion>
+  <Accordion title="What 'fresh session' means for isolated jobs">
+    For isolated jobs, "fresh session" means a new transcript/session id for each run. OpenClaw may carry safe preferences such as thinking/fast/verbose settings, labels, and explicit user-selected model/auth overrides, but it does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.
+  </Accordion>
+  <Accordion title="Runtime cleanup">
+    For isolated jobs, runtime teardown now includes best-effort browser cleanup for that cron session. Cleanup failures are ignored so the actual cron result still wins.
 
-For isolated jobs, “fresh session” means a new transcript/session id for each run. OpenClaw may carry safe preferences such as thinking/fast/verbose settings, labels, and explicit user-selected model/auth overrides, but it does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.
+    Isolated cron runs also dispose any bundled MCP runtime instances created for the job through the shared runtime-cleanup path. This matches how main-session and custom-session MCP clients are torn down, so isolated cron jobs do not leak stdio child processes or long-lived MCP connections across runs.
 
-For isolated jobs, runtime teardown now includes best-effort browser cleanup for that cron session. Cleanup failures are ignored so the actual cron result still wins.
+  </Accordion>
+  <Accordion title="Subagent and Discord delivery">
+    When isolated cron runs orchestrate subagents, delivery also prefers the final descendant output over stale parent interim text. If descendants are still running, OpenClaw suppresses that partial parent update instead of announcing it.
 
-Isolated cron runs also dispose any bundled MCP runtime instances created for the job through the shared runtime-cleanup path. This matches how main-session and custom-session MCP clients are torn down, so isolated cron jobs do not leak stdio child processes or long-lived MCP connections across runs.
+    For text-only Discord announce targets, OpenClaw sends the canonical final assistant text once instead of replaying both streamed/intermediate text payloads and the final answer. Media and structured Discord payloads are still delivered as separate payloads so attachments and components are not dropped.
 
-When isolated cron runs orchestrate subagents, delivery also prefers the final
-descendant output over stale parent interim text. If descendants are still
-running, OpenClaw suppresses that partial parent update instead of announcing it.
-
-For text-only Discord announce targets, OpenClaw sends the canonical final
-assistant text once instead of replaying both streamed/intermediate text payloads
-and the final answer. Media and structured Discord payloads are still delivered
-as separate payloads so attachments and components are not dropped.
+  </Accordion>
+</AccordionGroup>
 
 ### Payload options for isolated jobs
 
-- `--message`: prompt text (required for isolated)
-- `--model` / `--thinking`: model and thinking level overrides
-- `--light-context`: skip workspace bootstrap file injection
-- `--tools exec,read`: restrict which tools the job can use
+<ParamField path="--message" type="string" required>
+  Prompt text (required for isolated).
+</ParamField>
+<ParamField path="--model" type="string">
+  Model override; uses the selected allowed model for the job.
+</ParamField>
+<ParamField path="--thinking" type="string">
+  Thinking level override.
+</ParamField>
+<ParamField path="--light-context" type="boolean">
+  Skip workspace bootstrap file injection.
+</ParamField>
+<ParamField path="--tools" type="string">
+  Restrict which tools the job can use, for example `--tools exec,read`.
+</ParamField>
 
-`--model` uses the selected allowed model for that job. If the requested model
-is not allowed, cron logs a warning and falls back to the job's agent/default
-model selection instead. Configured fallback chains still apply, but a plain
-model override with no explicit per-job fallback list no longer appends the
-agent primary as a hidden extra retry target.
+`--model` uses the selected allowed model for that job. If the requested model is not allowed, cron logs a warning and falls back to the job's agent/default model selection instead. Configured fallback chains still apply, but a plain model override with no explicit per-job fallback list no longer appends the agent primary as a hidden extra retry target.
 
 Model-selection precedence for isolated jobs is:
 
@@ -121,16 +135,9 @@ Model-selection precedence for isolated jobs is:
 3. User-selected stored cron session model override
 4. Agent/default model selection
 
-Fast mode follows the resolved live selection too. If the selected model config
-has `params.fastMode`, isolated cron uses that by default. A stored session
-`fastMode` override still wins over config in either direction.
+Fast mode follows the resolved live selection too. If the selected model config has `params.fastMode`, isolated cron uses that by default. A stored session `fastMode` override still wins over config in either direction.
 
-If an isolated run hits a live model-switch handoff, cron retries with the
-switched provider/model and persists that live selection for the active run
-before retrying. When the switch also carries a new auth profile, cron persists
-that auth profile override for the active run too. Retries are bounded: after
-the initial attempt plus 2 switch retries, cron aborts instead of looping
-forever.
+If an isolated run hits a live model-switch handoff, cron retries with the switched provider/model and persists that live selection for the active run before retrying. When the switch also carries a new auth profile, cron persists that auth profile override for the active run too. Retries are bounded: after the initial attempt plus 2 switch retries, cron aborts instead of looping forever.
 
 ## Delivery and output
 
@@ -142,16 +149,9 @@ forever.
 
 Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`. Slack/Discord/Mattermost targets should use explicit prefixes (`channel:<id>`, `user:<id>`). Matrix room IDs are case-sensitive; use the exact room ID or `room:!room:server` form from Matrix.
 
-For isolated jobs, chat delivery is shared. If a chat route is available, the
-agent can use the `message` tool even when the job uses `--no-deliver`. If the
-agent sends to the configured/current target, OpenClaw skips the fallback
-announce. Otherwise `announce`, `webhook`, and `none` only control what the
-runner does with the final reply after the agent turn.
+For isolated jobs, chat delivery is shared. If a chat route is available, the agent can use the `message` tool even when the job uses `--no-deliver`. If the agent sends to the configured/current target, OpenClaw skips the fallback announce. Otherwise `announce`, `webhook`, and `none` only control what the runner does with the final reply after the agent turn.
 
-When an agent creates an isolated reminder from an active chat, OpenClaw stores
-the preserved live delivery target for the fallback announce route. Internal
-session keys may be lowercase; provider delivery targets are not reconstructed
-from those keys when current chat context is available.
+When an agent creates an isolated reminder from an active chat, OpenClaw stores the preserved live delivery target for the fallback announce route. Internal session keys may be lowercase; provider delivery targets are not reconstructed from those keys when current chat context is available.
 
 Failure notifications follow a separate destination path:
 
@@ -162,44 +162,44 @@ Failure notifications follow a separate destination path:
 
 ## CLI examples
 
-One-shot reminder (main session):
-
-```bash
-openclaw cron add \
-  --name "Calendar check" \
-  --at "20m" \
-  --session main \
-  --system-event "Next heartbeat: check calendar." \
-  --wake now
-```
-
-Recurring isolated job with delivery:
-
-```bash
-openclaw cron add \
-  --name "Morning brief" \
-  --cron "0 7 * * *" \
-  --tz "America/Los_Angeles" \
-  --session isolated \
-  --message "Summarize overnight updates." \
-  --announce \
-  --channel slack \
-  --to "channel:C1234567890"
-```
-
-Isolated job with model and thinking override:
-
-```bash
-openclaw cron add \
-  --name "Deep analysis" \
-  --cron "0 6 * * 1" \
-  --tz "America/Los_Angeles" \
-  --session isolated \
-  --message "Weekly deep analysis of project progress." \
-  --model "opus" \
-  --thinking high \
-  --announce
-```
+<Tabs>
+  <Tab title="One-shot reminder">
+    ```bash
+    openclaw cron add \
+      --name "Calendar check" \
+      --at "20m" \
+      --session main \
+      --system-event "Next heartbeat: check calendar." \
+      --wake now
+    ```
+  </Tab>
+  <Tab title="Recurring isolated job">
+    ```bash
+    openclaw cron add \
+      --name "Morning brief" \
+      --cron "0 7 * * *" \
+      --tz "America/Los_Angeles" \
+      --session isolated \
+      --message "Summarize overnight updates." \
+      --announce \
+      --channel slack \
+      --to "channel:C1234567890"
+    ```
+  </Tab>
+  <Tab title="Model and thinking override">
+    ```bash
+    openclaw cron add \
+      --name "Deep analysis" \
+      --cron "0 6 * * 1" \
+      --tz "America/Los_Angeles" \
+      --session isolated \
+      --message "Weekly deep analysis of project progress." \
+      --model "opus" \
+      --thinking high \
+      --announce
+    ```
+  </Tab>
+</Tabs>
 
 ## Webhooks
 
@@ -224,52 +224,61 @@ Every request must include the hook token via header:
 
 Query-string tokens are rejected.
 
-### POST /hooks/wake
+<AccordionGroup>
+  <Accordion title="POST /hooks/wake">
+    Enqueue a system event for the main session:
 
-Enqueue a system event for the main session:
+    ```bash
+    curl -X POST http://127.0.0.1:18789/hooks/wake \
+      -H 'Authorization: Bearer SECRET' \
+      -H 'Content-Type: application/json' \
+      -d '{"text":"New email received","mode":"now"}'
+    ```
 
-```bash
-curl -X POST http://127.0.0.1:18789/hooks/wake \
-  -H 'Authorization: Bearer SECRET' \
-  -H 'Content-Type: application/json' \
-  -d '{"text":"New email received","mode":"now"}'
-```
+    <ParamField path="text" type="string" required>
+      Event description.
+    </ParamField>
+    <ParamField path="mode" type="string" default="now">
+      `now` or `next-heartbeat`.
+    </ParamField>
 
-- `text` (required): event description
-- `mode` (optional): `now` (default) or `next-heartbeat`
+  </Accordion>
+  <Accordion title="POST /hooks/agent">
+    Run an isolated agent turn:
 
-### POST /hooks/agent
+    ```bash
+    curl -X POST http://127.0.0.1:18789/hooks/agent \
+      -H 'Authorization: Bearer SECRET' \
+      -H 'Content-Type: application/json' \
+      -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'
+    ```
 
-Run an isolated agent turn:
+    Fields: `message` (required), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`.
 
-```bash
-curl -X POST http://127.0.0.1:18789/hooks/agent \
-  -H 'Authorization: Bearer SECRET' \
-  -H 'Content-Type: application/json' \
-  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'
-```
+  </Accordion>
+  <Accordion title="Mapped hooks (POST /hooks/<name>)">
+    Custom hook names are resolved via `hooks.mappings` in config. Mappings can transform arbitrary payloads into `wake` or `agent` actions with templates or code transforms.
+  </Accordion>
+</AccordionGroup>
 
-Fields: `message` (required), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`.
+<Warning>
+Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
 
-### Mapped hooks (POST /hooks/\<name\>)
-
-Custom hook names are resolved via `hooks.mappings` in config. Mappings can transform arbitrary payloads into `wake` or `agent` actions with templates or code transforms.
-
-### Security
-
-- Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
 - Use a dedicated hook token; do not reuse gateway auth tokens.
 - Keep `hooks.path` on a dedicated subpath; `/` is rejected.
 - Set `hooks.allowedAgentIds` to limit explicit `agentId` routing.
 - Keep `hooks.allowRequestSessionKey=false` unless you require caller-selected sessions.
 - If you enable `hooks.allowRequestSessionKey`, also set `hooks.allowedSessionKeyPrefixes` to constrain allowed session key shapes.
 - Hook payloads are wrapped with safety boundaries by default.
+  </Warning>
 
 ## Gmail PubSub integration
 
 Wire Gmail inbox triggers to OpenClaw via Google PubSub.
 
-**Prerequisites**: `gcloud` CLI, `gog` (gogcli), OpenClaw hooks enabled, Tailscale for the public HTTPS endpoint.
+<Note>
+**Prerequisites:** `gcloud` CLI, `gog` (gogcli), OpenClaw hooks enabled, Tailscale for the public HTTPS endpoint.
+</Note>
 
 ### Wizard setup (recommended)
 
@@ -285,31 +294,34 @@ When `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts `
 
 ### Manual one-time setup
 
-1. Select the GCP project that owns the OAuth client used by `gog`:
+<Steps>
+  <Step title="Select the GCP project">
+    Select the GCP project that owns the OAuth client used by `gog`:
 
-```bash
-gcloud auth login
-gcloud config set project <project-id>
-gcloud services enable gmail.googleapis.com pubsub.googleapis.com
-```
+    ```bash
+    gcloud auth login
+    gcloud config set project <project-id>
+    gcloud services enable gmail.googleapis.com pubsub.googleapis.com
+    ```
 
-2. Create topic and grant Gmail push access:
-
-```bash
-gcloud pubsub topics create gog-gmail-watch
-gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
-  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
-  --role=roles/pubsub.publisher
-```
-
-3. Start the watch:
-
-```bash
-gog gmail watch start \
-  --account openclaw@gmail.com \
-  --label INBOX \
-  --topic projects/<project-id>/topics/gog-gmail-watch
-```
+  </Step>
+  <Step title="Create topic and grant Gmail push access">
+    ```bash
+    gcloud pubsub topics create gog-gmail-watch
+    gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
+      --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
+      --role=roles/pubsub.publisher
+    ```
+  </Step>
+  <Step title="Start the watch">
+    ```bash
+    gog gmail watch start \
+      --account openclaw@gmail.com \
+      --label INBOX \
+      --topic projects/<project-id>/topics/gog-gmail-watch
+    ```
+  </Step>
+</Steps>
 
 ### Gmail model override
 
@@ -353,16 +365,14 @@ openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --mes
 openclaw cron edit <jobId> --clear-agent
 ```
 
+<Note>
 Model override note:
 
 - `openclaw cron add|edit --model ...` changes the job's selected model.
-- If the model is allowed, that exact provider/model reaches the isolated agent
-  run.
-- If it is not allowed, cron warns and falls back to the job's agent/default
-  model selection.
-- Configured fallback chains still apply, but a plain `--model` override with
-  no explicit per-job fallback list no longer falls through to the agent
-  primary as a silent extra retry target.
+- If the model is allowed, that exact provider/model reaches the isolated agent run.
+- If it is not allowed, cron warns and falls back to the job's agent/default model selection.
+- Configured fallback chains still apply, but a plain `--model` override with no explicit per-job fallback list no longer falls through to the agent primary as a silent extra retry target.
+  </Note>
 
 ## Configuration
 
@@ -384,17 +394,21 @@ Model override note:
 }
 ```
 
-The runtime state sidecar is derived from `cron.store`: a `.json` store such as
-`~/clawd/cron/jobs.json` uses `~/clawd/cron/jobs-state.json`, while a store path
-without a `.json` suffix appends `-state.json`.
+The runtime state sidecar is derived from `cron.store`: a `.json` store such as `~/clawd/cron/jobs.json` uses `~/clawd/cron/jobs-state.json`, while a store path without a `.json` suffix appends `-state.json`.
 
 Disable cron: `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1`.
 
-**One-shot retry**: transient errors (rate limit, overload, network, server error) retry up to 3 times with exponential backoff. Permanent errors disable immediately.
+<AccordionGroup>
+  <Accordion title="Retry behavior">
+    **One-shot retry**: transient errors (rate limit, overload, network, server error) retry up to 3 times with exponential backoff. Permanent errors disable immediately.
 
-**Recurring retry**: exponential backoff (30s to 60m) between retries. Backoff resets after the next successful run.
+    **Recurring retry**: exponential backoff (30s to 60m) between retries. Backoff resets after the next successful run.
 
-**Maintenance**: `cron.sessionRetention` (default `24h`) prunes isolated run-session entries. `cron.runLog.maxBytes` / `cron.runLog.keepLines` auto-prune run-log files.
+  </Accordion>
+  <Accordion title="Maintenance">
+    `cron.sessionRetention` (default `24h`) prunes isolated run-session entries. `cron.runLog.maxBytes` / `cron.runLog.keepLines` auto-prune run-log files.
+  </Accordion>
+</AccordionGroup>
 
 ## Troubleshooting
 
@@ -411,45 +425,32 @@ openclaw logs --follow
 openclaw doctor
 ```
 
-### Cron not firing
-
-- Check `cron.enabled` and `OPENCLAW_SKIP_CRON` env var.
-- Confirm the Gateway is running continuously.
-- For `cron` schedules, verify timezone (`--tz`) vs the host timezone.
-- `reason: not-due` in run output means manual run was checked with `openclaw cron run <jobId> --due` and the job was not due yet.
-
-### Cron fired but no delivery
-
-- Delivery mode `none` means no runner fallback send is expected. The agent can
-  still send directly with the `message` tool when a chat route is available.
-- Delivery target missing/invalid (`channel`/`to`) means outbound was skipped.
-- For Matrix, copied or legacy jobs with lowercased `delivery.to` room IDs can
-  fail because Matrix room IDs are case-sensitive. Edit the job to the exact
-  `!room:server` or `room:!room:server` value from Matrix.
-- Channel auth errors (`unauthorized`, `Forbidden`) mean delivery was blocked by credentials.
-- If the isolated run returns only the silent token (`NO_REPLY` / `no_reply`),
-  OpenClaw suppresses direct outbound delivery and also suppresses the fallback
-  queued summary path, so nothing is posted back to chat.
-- If the agent should message the user itself, check that the job has a usable
-  route (`channel: "last"` with a previous chat, or an explicit channel/target).
-
-### Cron or heartbeat appears to prevent `/new`-style rollover
-
-- Daily and idle reset freshness is not based on `updatedAt`; see
-  [Session management](/concepts/session#session-lifecycle).
-- Cron wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may
-  update the session row for routing/status, but they do not extend
-  `sessionStartedAt` or `lastInteractionAt`.
-- For legacy rows created before those fields existed, OpenClaw can recover
-  `sessionStartedAt` from the transcript JSONL session header when the file is
-  still available. Legacy idle rows without `lastInteractionAt` use that
-  recovered start time as their idle baseline.
-
-### Timezone gotchas
-
-- Cron without `--tz` uses the gateway host timezone.
-- `at` schedules without timezone are treated as UTC.
-- Heartbeat `activeHours` uses configured timezone resolution.
+<AccordionGroup>
+  <Accordion title="Cron not firing">
+    - Check `cron.enabled` and `OPENCLAW_SKIP_CRON` env var.
+    - Confirm the Gateway is running continuously.
+    - For `cron` schedules, verify timezone (`--tz`) vs the host timezone.
+    - `reason: not-due` in run output means manual run was checked with `openclaw cron run <jobId> --due` and the job was not due yet.
+  </Accordion>
+  <Accordion title="Cron fired but no delivery">
+    - Delivery mode `none` means no runner fallback send is expected. The agent can still send directly with the `message` tool when a chat route is available.
+    - Delivery target missing/invalid (`channel`/`to`) means outbound was skipped.
+    - For Matrix, copied or legacy jobs with lowercased `delivery.to` room IDs can fail because Matrix room IDs are case-sensitive. Edit the job to the exact `!room:server` or `room:!room:server` value from Matrix.
+    - Channel auth errors (`unauthorized`, `Forbidden`) mean delivery was blocked by credentials.
+    - If the isolated run returns only the silent token (`NO_REPLY` / `no_reply`), OpenClaw suppresses direct outbound delivery and also suppresses the fallback queued summary path, so nothing is posted back to chat.
+    - If the agent should message the user itself, check that the job has a usable route (`channel: "last"` with a previous chat, or an explicit channel/target).
+  </Accordion>
+  <Accordion title="Cron or heartbeat appears to prevent /new-style rollover">
+    - Daily and idle reset freshness is not based on `updatedAt`; see [Session management](/concepts/session#session-lifecycle).
+    - Cron wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may update the session row for routing/status, but they do not extend `sessionStartedAt` or `lastInteractionAt`.
+    - For legacy rows created before those fields existed, OpenClaw can recover `sessionStartedAt` from the transcript JSONL session header when the file is still available. Legacy idle rows without `lastInteractionAt` use that recovered start time as their idle baseline.
+  </Accordion>
+  <Accordion title="Timezone gotchas">
+    - Cron without `--tz` uses the gateway host timezone.
+    - `at` schedules without timezone are treated as UTC.
+    - Heartbeat `activeHours` uses configured timezone resolution.
+  </Accordion>
+</AccordionGroup>
 
 ## Related
 

docs/automation/tasks.md

@@ -5,12 +5,14 @@ read_when:
   - Debugging delivery failures for detached agent runs
   - Understanding how background runs relate to sessions, cron, and heartbeat
 title: "Background tasks"
+sidebarTitle: "Background tasks"
 ---
 
-> **Looking for scheduling?** See [Automation & Tasks](/automation) for choosing the right mechanism. This page covers **tracking** background work, not scheduling it.
+<Note>
+Looking for scheduling? See [Automation & Tasks](/automation) for choosing the right mechanism. This page covers **tracking** background work, not scheduling it.
+</Note>
 
-Background tasks track work that runs **outside your main conversation session**:
-ACP runs, subagent spawns, isolated cron job executions, and CLI-initiated operations.
+Background tasks track work that runs **outside your main conversation session**: ACP runs, subagent spawns, isolated cron job executions, and CLI-initiated operations.
 
 Tasks do **not** replace sessions, cron jobs, or heartbeats — they are the **activity ledger** that records what detached work happened, when, and whether it succeeded.
 
@@ -23,49 +25,68 @@ Not every agent run creates a task. Heartbeat turns and normal interactive chat
 - Tasks are **records**, not schedulers — cron and heartbeat decide _when_ work runs, tasks track _what happened_.
 - ACP, subagents, all cron jobs, and CLI operations create tasks. Heartbeat turns do not.
 - Each task moves through `queued → running → terminal` (succeeded, failed, timed_out, cancelled, or lost).
-- Cron tasks stay live while the cron runtime still owns the job; chat-backed CLI tasks stay live only while their owning run context is still active.
+- Cron tasks stay live while the cron runtime still owns the job; if the
+  in-memory runtime state is gone, task maintenance first checks durable cron
+  run history before marking a task lost.
 - Completion is push-driven: detached work can notify directly or wake the
   requester session/heartbeat when it finishes, so status polling loops are
   usually the wrong shape.
 - Isolated cron runs and subagent completions best-effort clean up tracked browser tabs/processes for their child session before final cleanup bookkeeping.
-- Isolated cron delivery suppresses stale interim parent replies while
-  descendant subagent work is still draining, and it prefers final descendant
-  output when that arrives before delivery.
+- Isolated cron delivery suppresses stale interim parent replies while descendant subagent work is still draining, and it prefers final descendant output when that arrives before delivery.
 - Completion notifications are delivered directly to a channel or queued for the next heartbeat.
 - `openclaw tasks list` shows all tasks; `openclaw tasks audit` surfaces issues.
 - Terminal records are kept for 7 days, then automatically pruned.
 
 ## Quick start
 
-```bash
-# List all tasks (newest first)
-openclaw tasks list
+<Tabs>
+  <Tab title="List and filter">
+    ```bash
+    # List all tasks (newest first)
+    openclaw tasks list
 
-# Filter by runtime or status
-openclaw tasks list --runtime acp
-openclaw tasks list --status running
+    # Filter by runtime or status
+    openclaw tasks list --runtime acp
+    openclaw tasks list --status running
+    ```
 
-# Show details for a specific task (by ID, run ID, or session key)
-openclaw tasks show <lookup>
+  </Tab>
+  <Tab title="Inspect">
+    ```bash
+    # Show details for a specific task (by ID, run ID, or session key)
+    openclaw tasks show <lookup>
+    ```
+  </Tab>
+  <Tab title="Cancel and notify">
+    ```bash
+    # Cancel a running task (kills the child session)
+    openclaw tasks cancel <lookup>
 
-# Cancel a running task (kills the child session)
-openclaw tasks cancel <lookup>
+    # Change notification policy for a task
+    openclaw tasks notify <lookup> state_changes
+    ```
 
-# Change notification policy for a task
-openclaw tasks notify <lookup> state_changes
+  </Tab>
+  <Tab title="Audit and maintenance">
+    ```bash
+    # Run a health audit
+    openclaw tasks audit
 
-# Run a health audit
-openclaw tasks audit
+    # Preview or apply maintenance
+    openclaw tasks maintenance
+    openclaw tasks maintenance --apply
+    ```
 
-# Preview or apply maintenance
-openclaw tasks maintenance
-openclaw tasks maintenance --apply
-
-# Inspect TaskFlow state
-openclaw tasks flow list
-openclaw tasks flow show <lookup>
-openclaw tasks flow cancel <lookup>
-```
+  </Tab>
+  <Tab title="Task flow">
+    ```bash
+    # Inspect TaskFlow state
+    openclaw tasks flow list
+    openclaw tasks flow show <lookup>
+    openclaw tasks flow cancel <lookup>
+    ```
+  </Tab>
+</Tabs>
 
 ## What creates a task
 
@@ -77,17 +98,22 @@ openclaw tasks flow cancel <lookup>
 | CLI operations         | `cli`        | `openclaw agent` commands that run through the gateway | `silent`              |
 | Agent media jobs       | `cli`        | Session-backed `video_generate` runs                   | `silent`              |
 
-Main-session cron tasks use `silent` notify policy by default — they create records for tracking but do not generate notifications. Isolated cron tasks also default to `silent` but are more visible because they run in their own session.
+<AccordionGroup>
+  <Accordion title="Notify defaults for cron and media">
+    Main-session cron tasks use `silent` notify policy by default — they create records for tracking but do not generate notifications. Isolated cron tasks also default to `silent` but are more visible because they run in their own session.
 
-Session-backed `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished video itself. If you opt into `tools.media.asyncCompletion.directSend`, async `music_generate` and `video_generate` completions try direct channel delivery first before falling back to the requester-session wake path.
+    Session-backed `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished video itself. If you opt into `tools.media.asyncCompletion.directSend`, async `music_generate` and `video_generate` completions try direct channel delivery first before falling back to the requester-session wake path.
 
-While a session-backed `video_generate` task is still active, the tool also acts as a guardrail: repeated `video_generate` calls in that same session return the active task status instead of starting a second concurrent generation. Use `action: "status"` when you want an explicit progress/status lookup from the agent side.
-
-**What does not create tasks:**
-
-- Heartbeat turns — main-session; see [Heartbeat](/gateway/heartbeat)
-- Normal interactive chat turns
-- Direct `/command` responses
+  </Accordion>
+  <Accordion title="Concurrent video_generate guardrail">
+    While a session-backed `video_generate` task is still active, the tool also acts as a guardrail: repeated `video_generate` calls in that same session return the active task status instead of starting a second concurrent generation. Use `action: "status"` when you want an explicit progress/status lookup from the agent side.
+  </Accordion>
+  <Accordion title="What does not create tasks">
+    - Heartbeat turns — main-session; see [Heartbeat](/gateway/heartbeat)
+    - Normal interactive chat turns
+    - Direct `/command` responses
+  </Accordion>
+</AccordionGroup>
 
 ## Task lifecycle
 
@@ -115,12 +141,20 @@ stateDiagram-v2
 
 Transitions happen automatically — when the associated agent run ends, the task status updates to match.
 
+Agent run completion is authoritative for active task records. A successful detached run finalizes as `succeeded`, ordinary run errors finalize as `failed`, and timeout or abort outcomes finalize as `timed_out`. If an operator already cancelled the task, or the runtime already recorded a stronger terminal state such as `failed`, `timed_out`, or `lost`, a later success signal does not downgrade that terminal status.
+
 `lost` is runtime-aware:
 
 - ACP tasks: backing ACP child session metadata disappeared.
 - Subagent tasks: backing child session disappeared from the target agent store.
-- Cron tasks: the cron runtime no longer tracks the job as active.
-- CLI tasks: isolated child-session tasks use the child session; chat-backed CLI tasks use the live run context instead, so lingering channel/group/direct session rows do not keep them alive.
+- Cron tasks: the cron runtime no longer tracks the job as active and durable
+  cron run history does not show a terminal result for that run. Offline CLI
+  audit does not treat its own empty in-process cron runtime state as authority.
+- CLI tasks: isolated child-session tasks use the child session; chat-backed
+  CLI tasks use the live run context instead, so lingering
+  channel/group/direct session rows do not keep them alive. Gateway-backed
+  `openclaw agent` runs also finalize from their run result, so completed runs
+  do not sit active until the sweeper marks them `lost`.
 
 ## Delivery and notifications
 
@@ -134,9 +168,7 @@ When a task reaches a terminal state, OpenClaw notifies you. There are two deliv
 Task completion triggers an immediate heartbeat wake so you see the result quickly — you do not have to wait for the next scheduled heartbeat tick.
 </Tip>
 
-That means the usual workflow is push-based: start detached work once, then let
-the runtime wake or notify you on completion. Poll task state only when you
-need debugging, intervention, or an explicit audit.
+That means the usual workflow is push-based: start detached work once, then let the runtime wake or notify you on completion. Poll task state only when you need debugging, intervention, or an explicit audit.
 
 ### Notification policies
 
@@ -156,96 +188,93 @@ openclaw tasks notify <lookup> state_changes
 
 ## CLI reference
 
-### `tasks list`
+<AccordionGroup>
+  <Accordion title="tasks list">
+    ```bash
+    openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
+    ```
 
-```bash
-openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
-```
+    Output columns: Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary.
 
-Output columns: Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary.
+  </Accordion>
+  <Accordion title="tasks show">
+    ```bash
+    openclaw tasks show <lookup>
+    ```
 
-### `tasks show`
+    The lookup token accepts a task ID, run ID, or session key. Shows the full record including timing, delivery state, error, and terminal summary.
 
-```bash
-openclaw tasks show <lookup>
-```
+  </Accordion>
+  <Accordion title="tasks cancel">
+    ```bash
+    openclaw tasks cancel <lookup>
+    ```
 
-The lookup token accepts a task ID, run ID, or session key. Shows the full record including timing, delivery state, error, and terminal summary.
+    For ACP and subagent tasks, this kills the child session. For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable.
 
-### `tasks cancel`
+  </Accordion>
+  <Accordion title="tasks notify">
+    ```bash
+    openclaw tasks notify <lookup> <done_only|state_changes|silent>
+    ```
+  </Accordion>
+  <Accordion title="tasks audit">
+    ```bash
+    openclaw tasks audit [--json]
+    ```
 
-```bash
-openclaw tasks cancel <lookup>
-```
+    Surfaces operational issues. Findings also appear in `openclaw status` when issues are detected.
 
-For ACP and subagent tasks, this kills the child session. For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable.
+    | Finding                   | Severity   | Trigger                                                                                                      |
+    | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
+    | `stale_queued`            | warn       | Queued for more than 10 minutes                                                                              |
+    | `stale_running`           | error      | Running for more than 30 minutes                                                                             |
+    | `lost`                    | warn/error | Runtime-backed task ownership disappeared; retained lost tasks warn until `cleanupAfter`, then become errors |
+    | `delivery_failed`         | warn       | Delivery failed and notify policy is not `silent`                                                            |
+    | `missing_cleanup`         | warn       | Terminal task with no cleanup timestamp                                                                      |
+    | `inconsistent_timestamps` | warn       | Timeline violation (for example ended before started)                                                        |
 
-### `tasks notify`
+  </Accordion>
+  <Accordion title="tasks maintenance">
+    ```bash
+    openclaw tasks maintenance [--json]
+    openclaw tasks maintenance --apply [--json]
+    ```
 
-```bash
-openclaw tasks notify <lookup> <done_only|state_changes|silent>
-```
+    Use this to preview or apply reconciliation, cleanup stamping, and pruning for tasks and Task Flow state.
 
-### `tasks audit`
+    Reconciliation is runtime-aware:
 
-```bash
-openclaw tasks audit [--json]
-```
+    - ACP/subagent tasks check their backing child session.
+    - Cron tasks check whether the cron runtime still owns the job, then recover terminal status from persisted cron run logs/job state before falling back to `lost`. Only the Gateway process is authoritative for the in-memory cron active-job set; offline CLI audit uses durable history but does not mark a cron task lost solely because that local Set is empty.
+    - Chat-backed CLI tasks check the owning live run context, not just the chat session row.
 
-Surfaces operational issues. Findings also appear in `openclaw status` when issues are detected.
+    Completion cleanup is also runtime-aware:
 
-| Finding                   | Severity | Trigger                                               |
-| ------------------------- | -------- | ----------------------------------------------------- |
-| `stale_queued`            | warn     | Queued for more than 10 minutes                       |
-| `stale_running`           | error    | Running for more than 30 minutes                      |
-| `lost`                    | error    | Runtime-backed task ownership disappeared             |
-| `delivery_failed`         | warn     | Delivery failed and notify policy is not `silent`     |
-| `missing_cleanup`         | warn     | Terminal task with no cleanup timestamp               |
-| `inconsistent_timestamps` | warn     | Timeline violation (for example ended before started) |
+    - Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
+    - Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
+    - Isolated cron delivery waits out descendant subagent follow-up when needed and suppresses stale parent acknowledgement text instead of announcing it.
+    - Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary. Terminal failed runs announce failure status without replaying captured reply text.
+    - Cleanup failures do not mask the real task outcome.
 
-### `tasks maintenance`
+  </Accordion>
+  <Accordion title="tasks flow list | show | cancel">
+    ```bash
+    openclaw tasks flow list [--status <status>] [--json]
+    openclaw tasks flow show <lookup> [--json]
+    openclaw tasks flow cancel <lookup>
+    ```
 
-```bash
-openclaw tasks maintenance [--json]
-openclaw tasks maintenance --apply [--json]
-```
+    Use these when the orchestrating Task Flow is the thing you care about rather than one individual background task record.
 
-Use this to preview or apply reconciliation, cleanup stamping, and pruning for
-tasks and Task Flow state.
-
-Reconciliation is runtime-aware:
-
-- ACP/subagent tasks check their backing child session.
-- Cron tasks check whether the cron runtime still owns the job.
-- Chat-backed CLI tasks check the owning live run context, not just the chat session row.
-
-Completion cleanup is also runtime-aware:
-
-- Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
-- Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
-- Isolated cron delivery waits out descendant subagent follow-up when needed and
-  suppresses stale parent acknowledgement text instead of announcing it.
-- Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary. Terminal failed runs announce failure status without replaying captured reply text.
-- Cleanup failures do not mask the real task outcome.
-
-### `tasks flow list|show|cancel`
-
-```bash
-openclaw tasks flow list [--status <status>] [--json]
-openclaw tasks flow show <lookup> [--json]
-openclaw tasks flow cancel <lookup>
-```
-
-Use these when the orchestrating Task Flow is the thing you care about rather
-than one individual background task record.
+  </Accordion>
+</AccordionGroup>
 
 ## Chat task board (`/tasks`)
 
-Use `/tasks` in any chat session to see background tasks linked to that session. The board shows
-active and recently completed tasks with runtime, status, timing, and progress or error detail.
+Use `/tasks` in any chat session to see background tasks linked to that session. The board shows active and recently completed tasks with runtime, status, timing, and progress or error detail.
 
-When the current session has no visible linked tasks, `/tasks` falls back to agent-local task counts
-so you still get an overview without leaking other-session details.
+When the current session has no visible linked tasks, `/tasks` falls back to agent-local task counts so you still get an overview without leaking other-session details.
 
 For the full operator ledger, use the CLI: `openclaw tasks list`.
 
@@ -263,9 +292,7 @@ The summary reports:
 - **failures** — count of `failed` + `timed_out` + `lost`
 - **byRuntime** — breakdown by `acp`, `subagent`, `cron`, `cli`
 
-Both `/status` and the `session_status` tool use a cleanup-aware task snapshot: active tasks are
-preferred, stale completed rows are hidden, and recent failures only surface when no active work
-remains. This keeps the status card focused on what matters right now.
+Both `/status` and the `session_status` tool use a cleanup-aware task snapshot: active tasks are preferred, stale completed rows are hidden, and recent failures only surface when no active work remains. This keeps the status card focused on what matters right now.
 
 ## Storage and maintenance
 
@@ -283,44 +310,55 @@ The registry loads into memory at gateway start and syncs writes to SQLite for d
 
 A sweeper runs every **60 seconds** and handles three things:
 
-1. **Reconciliation** — checks whether active tasks still have authoritative runtime backing. ACP/subagent tasks use child-session state, cron tasks use active-job ownership, and chat-backed CLI tasks use the owning run context. If that backing state is gone for more than 5 minutes, the task is marked `lost`.
-2. **Cleanup stamping** — sets a `cleanupAfter` timestamp on terminal tasks (endedAt + 7 days).
-3. **Pruning** — deletes records past their `cleanupAfter` date.
+<Steps>
+  <Step title="Reconciliation">
+    Checks whether active tasks still have authoritative runtime backing. ACP/subagent tasks use child-session state, cron tasks use active-job ownership, and chat-backed CLI tasks use the owning run context. If that backing state is gone for more than 5 minutes, the task is marked `lost`.
+  </Step>
+  <Step title="Cleanup stamping">
+    Sets a `cleanupAfter` timestamp on terminal tasks (endedAt + 7 days). During retention, lost tasks still appear in audit as warnings; after `cleanupAfter` expires or when cleanup metadata is missing, they are errors.
+  </Step>
+  <Step title="Pruning">
+    Deletes records past their `cleanupAfter` date.
+  </Step>
+</Steps>
 
-**Retention**: terminal task records are kept for **7 days**, then automatically pruned. No configuration needed.
+<Note>
+**Retention:** terminal task records are kept for **7 days**, then automatically pruned. No configuration needed.
+</Note>
 
 ## How tasks relate to other systems
 
-### Tasks and Task Flow
+<AccordionGroup>
+  <Accordion title="Tasks and Task Flow">
+    [Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
 
-[Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
+    See [Task Flow](/automation/taskflow) for details.
 
-See [Task Flow](/automation/taskflow) for details.
+  </Accordion>
+  <Accordion title="Tasks and cron">
+    A cron job **definition** lives in `~/.openclaw/cron/jobs.json`; runtime execution state lives beside it in `~/.openclaw/cron/jobs-state.json`. **Every** cron execution creates a task record — both main-session and isolated. Main-session cron tasks default to `silent` notify policy so they track without generating notifications.
 
-### Tasks and cron
+    See [Cron Jobs](/automation/cron-jobs).
 
-A cron job **definition** lives in `~/.openclaw/cron/jobs.json`; runtime execution state lives beside it in `~/.openclaw/cron/jobs-state.json`. **Every** cron execution creates a task record — both main-session and isolated. Main-session cron tasks default to `silent` notify policy so they track without generating notifications.
+  </Accordion>
+  <Accordion title="Tasks and heartbeat">
+    Heartbeat runs are main-session turns — they do not create task records. When a task completes, it can trigger a heartbeat wake so you see the result promptly.
 
-See [Cron Jobs](/automation/cron-jobs).
+    See [Heartbeat](/gateway/heartbeat).
 
-### Tasks and heartbeat
-
-Heartbeat runs are main-session turns — they do not create task records. When a task completes, it can trigger a heartbeat wake so you see the result promptly.
-
-See [Heartbeat](/gateway/heartbeat).
-
-### Tasks and sessions
-
-A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Sessions are conversation context; tasks are activity tracking on top of that.
-
-### Tasks and agent runs
-
-A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status — you do not need to manage the lifecycle manually.
+  </Accordion>
+  <Accordion title="Tasks and sessions">
+    A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Sessions are conversation context; tasks are activity tracking on top of that.
+  </Accordion>
+  <Accordion title="Tasks and agent runs">
+    A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status — you do not need to manage the lifecycle manually.
+  </Accordion>
+</AccordionGroup>
 
 ## Related
 
 - [Automation & Tasks](/automation) — all automation mechanisms at a glance
-- [Task Flow](/automation/taskflow) — flow orchestration above tasks
-- [Scheduled Tasks](/automation/cron-jobs) — scheduling background work
-- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
 - [CLI: Tasks](/cli/tasks) — CLI command reference
+- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
+- [Scheduled Tasks](/automation/cron-jobs) — scheduling background work
+- [Task Flow](/automation/taskflow) — flow orchestration above tasks

docs/channels/bluebubbles.md

@@ -5,14 +5,14 @@ read_when:
   - Troubleshooting webhook pairing
   - Configuring iMessage on macOS
 title: "BlueBubbles"
+sidebarTitle: "BlueBubbles"
 ---
 
 Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **Recommended for iMessage integration** due to its richer API and easier setup compared to the legacy imsg channel.
 
-## Bundled plugin
-
-Current OpenClaw releases bundle BlueBubbles, so normal packaged builds do not
-need a separate `openclaw plugins install` step.
+<Note>
+Current OpenClaw releases bundle BlueBubbles, so normal packaged builds do not need a separate `openclaw plugins install` step.
+</Note>
 
 ## Overview
 
@@ -21,111 +21,119 @@ need a separate `openclaw plugins install` step.
 - OpenClaw talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
 - Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls.
 - Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible).
+- Auto-TTS replies that synthesize MP3 or CAF audio are delivered as iMessage voice memo bubbles instead of plain file attachments.
 - Pairing/allowlist works the same way as other channels (`/channels/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
 - Reactions are surfaced as system events just like Slack/Telegram so agents can "mention" them before replying.
 - Advanced features: edit, unsend, reply threading, message effects, group management.
 
 ## Quick start
 
-1. Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install)).
-2. In the BlueBubbles config, enable the web API and set a password.
-3. Run `openclaw onboard` and select BlueBubbles, or configure manually:
+<Steps>
+  <Step title="Install BlueBubbles">
+    Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install)).
+  </Step>
+  <Step title="Enable the web API">
+    In the BlueBubbles config, enable the web API and set a password.
+  </Step>
+  <Step title="Configure OpenClaw">
+    Run `openclaw onboard` and select BlueBubbles, or configure manually:
 
-   ```json5
-   {
-     channels: {
-       bluebubbles: {
-         enabled: true,
-         serverUrl: "http://192.168.1.100:1234",
-         password: "example-password",
-         webhookPath: "/bluebubbles-webhook",
-       },
-     },
-   }
-   ```
+    ```json5
+    {
+      channels: {
+        bluebubbles: {
+          enabled: true,
+          serverUrl: "http://192.168.1.100:1234",
+          password: "example-password",
+          webhookPath: "/bluebubbles-webhook",
+        },
+      },
+    }
+    ```
 
-4. Point BlueBubbles webhooks to your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
-5. Start the gateway; it will register the webhook handler and start pairing.
+  </Step>
+  <Step title="Point webhooks at the gateway">
+    Point BlueBubbles webhooks to your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
+  </Step>
+  <Step title="Start the gateway">
+    Start the gateway; it will register the webhook handler and start pairing.
+  </Step>
+</Steps>
 
-Security note:
+<Warning>
+**Security**
 
 - Always set a webhook password.
 - Webhook authentication is always required. OpenClaw rejects BlueBubbles webhook requests unless they include a password/guid that matches `channels.bluebubbles.password` (for example `?password=<password>` or `x-password`), regardless of loopback/proxy topology.
 - Password authentication is checked before reading/parsing full webhook bodies.
+  </Warning>
 
 ## Keeping Messages.app alive (VM / headless setups)
 
-Some macOS VM / always-on setups can end up with Messages.app going “idle” (incoming events stop until the app is opened/foregrounded). A simple workaround is to **poke Messages every 5 minutes** using an AppleScript + LaunchAgent.
+Some macOS VM / always-on setups can end up with Messages.app going "idle" (incoming events stop until the app is opened/foregrounded). A simple workaround is to **poke Messages every 5 minutes** using an AppleScript + LaunchAgent.
 
-### 1) Save the AppleScript
+<Steps>
+  <Step title="Save the AppleScript">
+    Save this as `~/Scripts/poke-messages.scpt`:
 
-Save this as:
+    ```applescript
+    try
+      tell application "Messages"
+        if not running then
+          launch
+        end if
 
-- `~/Scripts/poke-messages.scpt`
+        -- Touch the scripting interface to keep the process responsive.
+        set _chatCount to (count of chats)
+      end tell
+    on error
+      -- Ignore transient failures (first-run prompts, locked session, etc).
+    end try
+    ```
 
-Example script (non-interactive; does not steal focus):
+  </Step>
+  <Step title="Install a LaunchAgent">
+    Save this as `~/Library/LaunchAgents/com.user.poke-messages.plist`:
 
-```applescript
-try
-  tell application "Messages"
-    if not running then
-      launch
-    end if
+    ```xml
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+    <plist version="1.0">
+      <dict>
+        <key>Label</key>
+        <string>com.user.poke-messages</string>
 
-    -- Touch the scripting interface to keep the process responsive.
-    set _chatCount to (count of chats)
-  end tell
-on error
-  -- Ignore transient failures (first-run prompts, locked session, etc).
-end try
-```
+        <key>ProgramArguments</key>
+        <array>
+          <string>/bin/bash</string>
+          <string>-lc</string>
+          <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
+        </array>
 
-### 2) Install a LaunchAgent
+        <key>RunAtLoad</key>
+        <true/>
 
-Save this as:
+        <key>StartInterval</key>
+        <integer>300</integer>
 
-- `~/Library/LaunchAgents/com.user.poke-messages.plist`
+        <key>StandardOutPath</key>
+        <string>/tmp/poke-messages.log</string>
+        <key>StandardErrorPath</key>
+        <string>/tmp/poke-messages.err</string>
+      </dict>
+    </plist>
+    ```
 
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-  <dict>
-    <key>Label</key>
-    <string>com.user.poke-messages</string>
+    This runs **every 300 seconds** and **on login**. The first run may trigger macOS **Automation** prompts (`osascript` → Messages). Approve them in the same user session that runs the LaunchAgent.
 
-    <key>ProgramArguments</key>
-    <array>
-      <string>/bin/bash</string>
-      <string>-lc</string>
-      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
-    </array>
-
-    <key>RunAtLoad</key>
-    <true/>
-
-    <key>StartInterval</key>
-    <integer>300</integer>
-
-    <key>StandardOutPath</key>
-    <string>/tmp/poke-messages.log</string>
-    <key>StandardErrorPath</key>
-    <string>/tmp/poke-messages.err</string>
-  </dict>
-</plist>
-```
-
-Notes:
-
-- This runs **every 300 seconds** and **on login**.
-- The first run may trigger macOS **Automation** prompts (`osascript` → Messages). Approve them in the same user session that runs the LaunchAgent.
-
-Load it:
-
-```bash
-launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
-launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
-```
+  </Step>
+  <Step title="Load it">
+    ```bash
+    launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
+    launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
+    ```
+  </Step>
+</Steps>
 
 ## Onboarding
 
@@ -137,11 +145,21 @@ openclaw onboard
 
 The wizard prompts for:
 
-- **Server URL** (required): BlueBubbles server address (e.g., `http://192.168.1.100:1234`)
-- **Password** (required): API password from BlueBubbles Server settings
-- **Webhook path** (optional): Defaults to `/bluebubbles-webhook`
-- **DM policy**: pairing, allowlist, open, or disabled
-- **Allow list**: Phone numbers, emails, or chat targets
+<ParamField path="Server URL" type="string" required>
+  BlueBubbles server address (e.g., `http://192.168.1.100:1234`).
+</ParamField>
+<ParamField path="Password" type="string" required>
+  API password from BlueBubbles Server settings.
+</ParamField>
+<ParamField path="Webhook path" type="string" default="/bluebubbles-webhook">
+  Webhook endpoint path.
+</ParamField>
+<ParamField path="DM policy" type="string">
+  `pairing`, `allowlist`, `open`, or `disabled`.
+</ParamField>
+<ParamField path="Allow list" type="string[]">
+  Phone numbers, emails, or chat targets.
+</ParamField>
 
 You can also add BlueBubbles via CLI:
 
@@ -151,19 +169,20 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
 
 ## Access control (DMs + groups)
 
-DMs:
-
-- Default: `channels.bluebubbles.dmPolicy = "pairing"`.
-- Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
-- Approve via:
-  - `openclaw pairing list bluebubbles`
-  - `openclaw pairing approve bluebubbles <CODE>`
-- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
-
-Groups:
-
-- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (default: `allowlist`).
-- `channels.bluebubbles.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+<Tabs>
+  <Tab title="DMs">
+    - Default: `channels.bluebubbles.dmPolicy = "pairing"`.
+    - Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+    - Approve via:
+      - `openclaw pairing list bluebubbles`
+      - `openclaw pairing approve bluebubbles <CODE>`
+    - Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
+  </Tab>
+  <Tab title="Groups">
+    - `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (default: `allowlist`).
+    - `channels.bluebubbles.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+  </Tab>
+</Tabs>
 
 ### Contact name enrichment (macOS, optional)
 
@@ -359,21 +378,23 @@ BlueBubbles supports advanced message actions when enabled in config:
 }
 ```
 
-Available actions:
-
-- **react**: Add/remove tapback reactions (`messageId`, `emoji`, `remove`). iMessage's native tapback set is `love`, `like`, `dislike`, `laugh`, `emphasize`, and `question`. When an agent picks an emoji outside that set (for example `👀`), the reaction tool falls back to `love` so the tapback still renders instead of failing the whole request. Configured ack reactions still validate strictly and error on unknown values.
-- **edit**: Edit a sent message (`messageId`, `text`)
-- **unsend**: Unsend a message (`messageId`)
-- **reply**: Reply to a specific message (`messageId`, `text`, `to`)
-- **sendWithEffect**: Send with iMessage effect (`text`, `to`, `effectId`)
-- **renameGroup**: Rename a group chat (`chatGuid`, `displayName`)
-- **setGroupIcon**: Set a group chat's icon/photo (`chatGuid`, `media`) — flaky on macOS 26 Tahoe (API may return success but the icon does not sync).
-- **addParticipant**: Add someone to a group (`chatGuid`, `address`)
-- **removeParticipant**: Remove someone from a group (`chatGuid`, `address`)
-- **leaveGroup**: Leave a group chat (`chatGuid`)
-- **upload-file**: Send media/files (`to`, `buffer`, `filename`, `asVoice`)
-  - Voice memos: set `asVoice: true` with **MP3** or **CAF** audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.
-- Legacy alias: `sendAttachment` still works, but `upload-file` is the canonical action name.
+<AccordionGroup>
+  <Accordion title="Available actions">
+    - **react**: Add/remove tapback reactions (`messageId`, `emoji`, `remove`). iMessage's native tapback set is `love`, `like`, `dislike`, `laugh`, `emphasize`, and `question`. When an agent picks an emoji outside that set (for example `👀`), the reaction tool falls back to `love` so the tapback still renders instead of failing the whole request. Configured ack reactions still validate strictly and error on unknown values.
+    - **edit**: Edit a sent message (`messageId`, `text`).
+    - **unsend**: Unsend a message (`messageId`).
+    - **reply**: Reply to a specific message (`messageId`, `text`, `to`).
+    - **sendWithEffect**: Send with iMessage effect (`text`, `to`, `effectId`).
+    - **renameGroup**: Rename a group chat (`chatGuid`, `displayName`).
+    - **setGroupIcon**: Set a group chat's icon/photo (`chatGuid`, `media`) — flaky on macOS 26 Tahoe (API may return success but the icon does not sync).
+    - **addParticipant**: Add someone to a group (`chatGuid`, `address`).
+    - **removeParticipant**: Remove someone from a group (`chatGuid`, `address`).
+    - **leaveGroup**: Leave a group chat (`chatGuid`).
+    - **upload-file**: Send media/files (`to`, `buffer`, `filename`, `asVoice`).
+      - Voice memos: set `asVoice: true` with **MP3** or **CAF** audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.
+    - Legacy alias: `sendAttachment` still works, but `upload-file` is the canonical action name.
+  </Accordion>
+</AccordionGroup>
 
 ### Message IDs (short vs full)
 
@@ -404,54 +425,56 @@ The two webhooks arrive at OpenClaw ~0.8-2.0 s apart on most setups. Without coa
 
 `channels.bluebubbles.coalesceSameSenderDms` opts a DM into merging consecutive same-sender webhooks into a single agent turn. Group chats continue to key per-message so multi-user turn structure is preserved.
 
-### When to enable
+<Tabs>
+  <Tab title="When to enable">
+    Enable when:
 
-Enable when:
+    - You ship skills that expect `command + payload` in one message (dump, paste, save, queue, etc.).
+    - Your users paste URLs, images, or long content alongside commands.
+    - You can accept the added DM turn latency (see below).
 
-- You ship skills that expect `command + payload` in one message (dump, paste, save, queue, etc.).
-- Your users paste URLs, images, or long content alongside commands.
-- You can accept the added DM turn latency (see below).
+    Leave disabled when:
 
-Leave disabled when:
+    - You need minimum command latency for single-word DM triggers.
+    - All your flows are one-shot commands without payload follow-ups.
 
-- You need minimum command latency for single-word DM triggers.
-- All your flows are one-shot commands without payload follow-ups.
-
-### Enabling
-
-```json5
-{
-  channels: {
-    bluebubbles: {
-      coalesceSameSenderDms: true, // opt in (default: false)
-    },
-  },
-}
-```
-
-With the flag on and no explicit `messages.inbound.byChannel.bluebubbles`, the debounce window widens to **2500 ms** (the default for non-coalescing is 500 ms). The wider window is required — Apple's split-send cadence of 0.8-2.0 s does not fit in the tighter default.
-
-To tune the window yourself:
-
-```json5
-{
-  messages: {
-    inbound: {
-      byChannel: {
-        // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
-        // or under memory pressure (observed gap can stretch past 2 s then).
-        bluebubbles: 2500,
+  </Tab>
+  <Tab title="Enabling">
+    ```json5
+    {
+      channels: {
+        bluebubbles: {
+          coalesceSameSenderDms: true, // opt in (default: false)
+        },
       },
-    },
-  },
-}
-```
+    }
+    ```
 
-### Trade-offs
+    With the flag on and no explicit `messages.inbound.byChannel.bluebubbles`, the debounce window widens to **2500 ms** (the default for non-coalescing is 500 ms). The wider window is required — Apple's split-send cadence of 0.8-2.0 s does not fit in the tighter default.
 
-- **Added latency for DM control commands.** With the flag on, DM control-command messages (like `Dump`, `Save`, etc.) now wait up to the debounce window before dispatching, in case a payload webhook is coming. Group-chat commands keep instant dispatch.
-- **Merged output is bounded** — merged text caps at 4000 chars with an explicit `…[truncated]` marker; attachments cap at 20; source entries cap at 10 (first-plus-latest retained beyond that). Every source `messageId` still reaches inbound-dedupe so a later MessagePoller replay of any individual event is recognized as a duplicate.
-- **Opt-in, per-channel.** Other channels (Telegram, WhatsApp, Slack, …) are unaffected.
+    To tune the window yourself:
+
+    ```json5
+    {
+      messages: {
+        inbound: {
+          byChannel: {
+            // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
+            // or under memory pressure (observed gap can stretch past 2 s then).
+            bluebubbles: 2500,
+          },
+        },
+      },
+    }
+    ```
+
+  </Tab>
+  <Tab title="Trade-offs">
+    - **Added latency for DM control commands.** With the flag on, DM control-command messages (like `Dump`, `Save`, etc.) now wait up to the debounce window before dispatching, in case a payload webhook is coming. Group-chat commands keep instant dispatch.
+    - **Merged output is bounded** — merged text caps at 4000 chars with an explicit `…[truncated]` marker; attachments cap at 20; source entries cap at 10 (first-plus-latest retained beyond that). Every source `messageId` still reaches inbound-dedupe so a later MessagePoller replay of any individual event is recognized as a duplicate.
+    - **Opt-in, per-channel.** Other channels (Telegram, WhatsApp, Slack, …) are unaffected.
+  </Tab>
+</Tabs>
 
 ### Scenarios and what the agent sees
 
@@ -468,27 +491,35 @@ To tune the window yourself:
 
 If the flag is on and split-sends still arrive as two turns, check each layer:
 
-1. **Config actually loaded.**
+<AccordionGroup>
+  <Accordion title="Config actually loaded">
+    ```
+    grep coalesceSameSenderDms ~/.openclaw/openclaw.json
+    ```
 
-   ```
-   grep coalesceSameSenderDms ~/.openclaw/openclaw.json
-   ```
+    Then `openclaw gateway restart` — the flag is read at debouncer-registry creation.
 
-   Then `openclaw gateway restart` — the flag is read at debouncer-registry creation.
+  </Accordion>
+  <Accordion title="Debounce window wide enough for your setup">
+    Look at the BlueBubbles server log under `~/Library/Logs/bluebubbles-server/main.log`:
 
-2. **Debounce window wide enough for your setup.** Look at the BlueBubbles server log under `~/Library/Logs/bluebubbles-server/main.log`:
+    ```
+    grep -E "Dispatching event to webhook" main.log | tail -20
+    ```
 
-   ```
-   grep -E "Dispatching event to webhook" main.log | tail -20
-   ```
+    Measure the gap between the `"Dump"`-style text dispatch and the `"https://..."; Attachments:` dispatch that follows. Raise `messages.inbound.byChannel.bluebubbles` to comfortably cover that gap.
 
-   Measure the gap between the `"Dump"`-style text dispatch and the `"https://..."; Attachments:` dispatch that follows. Raise `messages.inbound.byChannel.bluebubbles` to comfortably cover that gap.
-
-3. **Session JSONL timestamps ≠ webhook arrival.** Session event timestamps (`~/.openclaw/agents/<id>/sessions/*.jsonl`) reflect when the gateway hands a message to the agent, **not** when the webhook arrived. A queued-second message tagged `[Queued messages while agent was busy]` means the first turn was still running when the second webhook arrived — the coalesce bucket had already flushed. Tune the window against the BB server log, not the session log.
-
-4. **Memory pressure slowing reply dispatch.** On smaller machines (8 GB), agent turns can take long enough that the coalesce bucket flushes before the reply completes, and the URL lands as a queued second turn. Check `memory_pressure` and `ps -o rss -p $(pgrep openclaw-gateway)`; if the gateway is over ~500 MB RSS and the compressor is active, close other heavy processes or bump to a larger host.
-
-5. **Reply-quote sends are a different path.** If the user tapped `Dump` as a **reply** to an existing URL-balloon (iMessage shows a "1 Reply" badge on the Dump bubble), the URL lives in `replyToBody`, not in a second webhook. Coalescing does not apply — that's a skill/prompt concern, not a debouncer concern.
+  </Accordion>
+  <Accordion title="Session JSONL timestamps ≠ webhook arrival">
+    Session event timestamps (`~/.openclaw/agents/<id>/sessions/*.jsonl`) reflect when the gateway hands a message to the agent, **not** when the webhook arrived. A queued-second message tagged `[Queued messages while agent was busy]` means the first turn was still running when the second webhook arrived — the coalesce bucket had already flushed. Tune the window against the BB server log, not the session log.
+  </Accordion>
+  <Accordion title="Memory pressure slowing reply dispatch">
+    On smaller machines (8 GB), agent turns can take long enough that the coalesce bucket flushes before the reply completes, and the URL lands as a queued second turn. Check `memory_pressure` and `ps -o rss -p $(pgrep openclaw-gateway)`; if the gateway is over ~500 MB RSS and the compressor is active, close other heavy processes or bump to a larger host.
+  </Accordion>
+  <Accordion title="Reply-quote sends are a different path">
+    If the user tapped `Dump` as a **reply** to an existing URL-balloon (iMessage shows a "1 Reply" badge on the Dump bubble), the URL lives in `replyToBody`, not in a second webhook. Coalescing does not apply — that's a skill/prompt concern, not a debouncer concern.
+  </Accordion>
+</AccordionGroup>
 
 ## Block streaming
 
@@ -514,30 +545,40 @@ Control whether responses are sent as a single message or streamed in blocks:
 
 Full configuration: [Configuration](/gateway/configuration)
 
-Provider options:
-
-- `channels.bluebubbles.enabled`: Enable/disable the channel.
-- `channels.bluebubbles.serverUrl`: BlueBubbles REST API base URL.
-- `channels.bluebubbles.password`: API password.
-- `channels.bluebubbles.webhookPath`: Webhook endpoint path (default: `/bluebubbles-webhook`).
-- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (default: `pairing`).
-- `channels.bluebubbles.allowFrom`: DM allowlist (handles, emails, E.164 numbers, `chat_id:*`, `chat_guid:*`).
-- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (default: `allowlist`).
-- `channels.bluebubbles.groupAllowFrom`: Group sender allowlist.
-- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: On macOS, optionally enrich unnamed group participants from local Contacts after gating passes. Default: `false`.
-- `channels.bluebubbles.groups`: Per-group config (`requireMention`, etc.).
-- `channels.bluebubbles.sendReadReceipts`: Send read receipts (default: `true`).
-- `channels.bluebubbles.blockStreaming`: Enable block streaming (default: `false`; required for streaming replies).
-- `channels.bluebubbles.textChunkLimit`: Outbound chunk size in chars (default: 4000).
-- `channels.bluebubbles.sendTimeoutMs`: Per-request timeout in ms for outbound text sends via `/api/v1/message/text` (default: 30000). Raise on macOS 26 setups where Private API iMessage sends can stall for 60+ seconds inside the iMessage framework; for example `45000` or `60000`. Probes, chat lookups, reactions, edits, and health checks currently keep the shorter 10s default; broadening coverage to reactions and edits is planned as a follow-up. Per-account override: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
-- `channels.bluebubbles.chunkMode`: `length` (default) splits only when exceeding `textChunkLimit`; `newline` splits on blank lines (paragraph boundaries) before length chunking.
-- `channels.bluebubbles.mediaMaxMb`: Inbound/outbound media cap in MB (default: 8).
-- `channels.bluebubbles.mediaLocalRoots`: Explicit allowlist of absolute local directories permitted for outbound local media paths. Local path sends are denied by default unless this is configured. Per-account override: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
-- `channels.bluebubbles.coalesceSameSenderDms`: Merge consecutive same-sender DM webhooks into one agent turn so Apple's text+URL split-send arrives as a single message (default: `false`). See [Coalescing split-send DMs](#coalescing-split-send-dms-command--url-in-one-composition) for scenarios, window tuning, and trade-offs. Widens the default inbound debounce window from 500 ms to 2500 ms when enabled without an explicit `messages.inbound.byChannel.bluebubbles`.
-- `channels.bluebubbles.historyLimit`: Max group messages for context (0 disables).
-- `channels.bluebubbles.dmHistoryLimit`: DM history limit.
-- `channels.bluebubbles.actions`: Enable/disable specific actions.
-- `channels.bluebubbles.accounts`: Multi-account configuration.
+<AccordionGroup>
+  <Accordion title="Connection and webhook">
+    - `channels.bluebubbles.enabled`: Enable/disable the channel.
+    - `channels.bluebubbles.serverUrl`: BlueBubbles REST API base URL.
+    - `channels.bluebubbles.password`: API password.
+    - `channels.bluebubbles.webhookPath`: Webhook endpoint path (default: `/bluebubbles-webhook`).
+  </Accordion>
+  <Accordion title="Access policy">
+    - `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (default: `pairing`).
+    - `channels.bluebubbles.allowFrom`: DM allowlist (handles, emails, E.164 numbers, `chat_id:*`, `chat_guid:*`).
+    - `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (default: `allowlist`).
+    - `channels.bluebubbles.groupAllowFrom`: Group sender allowlist.
+    - `channels.bluebubbles.enrichGroupParticipantsFromContacts`: On macOS, optionally enrich unnamed group participants from local Contacts after gating passes. Default: `false`.
+    - `channels.bluebubbles.groups`: Per-group config (`requireMention`, etc.).
+  </Accordion>
+  <Accordion title="Delivery and chunking">
+    - `channels.bluebubbles.sendReadReceipts`: Send read receipts (default: `true`).
+    - `channels.bluebubbles.blockStreaming`: Enable block streaming (default: `false`; required for streaming replies).
+    - `channels.bluebubbles.textChunkLimit`: Outbound chunk size in chars (default: 4000).
+    - `channels.bluebubbles.sendTimeoutMs`: Per-request timeout in ms for outbound text sends via `/api/v1/message/text` (default: 30000). Raise on macOS 26 setups where Private API iMessage sends can stall for 60+ seconds inside the iMessage framework; for example `45000` or `60000`. Probes, chat lookups, reactions, edits, and health checks currently keep the shorter 10s default; broadening coverage to reactions and edits is planned as a follow-up. Per-account override: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
+    - `channels.bluebubbles.chunkMode`: `length` (default) splits only when exceeding `textChunkLimit`; `newline` splits on blank lines (paragraph boundaries) before length chunking.
+  </Accordion>
+  <Accordion title="Media and history">
+    - `channels.bluebubbles.mediaMaxMb`: Inbound/outbound media cap in MB (default: 8).
+    - `channels.bluebubbles.mediaLocalRoots`: Explicit allowlist of absolute local directories permitted for outbound local media paths. Local path sends are denied by default unless this is configured. Per-account override: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
+    - `channels.bluebubbles.coalesceSameSenderDms`: Merge consecutive same-sender DM webhooks into one agent turn so Apple's text+URL split-send arrives as a single message (default: `false`). See [Coalescing split-send DMs](#coalescing-split-send-dms-command--url-in-one-composition) for scenarios, window tuning, and trade-offs. Widens the default inbound debounce window from 500 ms to 2500 ms when enabled without an explicit `messages.inbound.byChannel.bluebubbles`.
+    - `channels.bluebubbles.historyLimit`: Max group messages for context (0 disables).
+    - `channels.bluebubbles.dmHistoryLimit`: DM history limit.
+  </Accordion>
+  <Accordion title="Actions and accounts">
+    - `channels.bluebubbles.actions`: Enable/disable specific actions.
+    - `channels.bluebubbles.accounts`: Multi-account configuration.
+  </Accordion>
+</AccordionGroup>
 
 Related global options:
 
@@ -580,8 +621,8 @@ For general channel workflow reference, see [Channels](/channels) and the [Plugi
 
 ## Related
 
-- [Channels Overview](/channels) — all supported channels
-- [Pairing](/channels/pairing) — DM authentication and pairing flow
-- [Groups](/channels/groups) — group chat behavior and mention gating
 - [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Channels Overview](/channels) — all supported channels
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
 - [Security](/gateway/security) — access model and hardening

docs/channels/discord.md

@@ -263,6 +263,10 @@ Now create some channels on your Discord server and start chatting. Your agent c
 
 - Gateway owns the Discord connection.
 - Reply routing is deterministic: Discord inbound replies back to Discord.
+- Discord guild/channel metadata is added to the model prompt as untrusted
+  context, not as a user-visible reply prefix. If a model copies that envelope
+  back, OpenClaw strips the copied metadata from outbound replies and from
+  future replay context.
 - By default (`session.dmScope=main`), direct chats share the agent main session (`agent:main:main`).
 - Guild channels are isolated session keys (`agent:<agentId>:discord:channel:<channelId>`).
 - Group DMs are ignored by default (`channels.discord.dm.groupEnabled=false`).

docs/channels/feishu.md

@@ -414,6 +414,15 @@ Full configuration: [Gateway configuration](/gateway/configuration)
 - ✅ Video/media
 - ✅ Stickers
 
+Inbound Feishu/Lark audio messages are normalized as media placeholders instead
+of raw `file_key` JSON. When `tools.media.audio` is configured, OpenClaw
+downloads the voice-note resource and runs shared audio transcription before the
+agent turn, so the agent receives the spoken transcript. If Feishu includes
+transcript text directly in the audio payload, that text is used without another
+ASR call. Without an audio transcription provider, the agent still receives a
+`<media:audio>` placeholder plus the saved attachment, not the raw Feishu
+resource payload.
+
 ### Send
 
 - ✅ Text

docs/channels/groups.md

@@ -272,6 +272,7 @@ Notes:
 - Surfaces that provide explicit mentions still pass; patterns are a fallback.
 - Per-agent override: `agents.list[].groupChat.mentionPatterns` (useful when multiple agents share a group).
 - Mention gating is only enforced when mention detection is possible (native mentions or `mentionPatterns` are configured).
+- Groups where silent replies are allowed treat clean empty or reasoning-only model turns as silent, equivalent to `NO_REPLY`. Direct chats still treat empty replies as a failed agent turn.
 - Discord defaults live in `channels.discord.guilds."*"` (overridable per guild/channel).
 - Group history context is wrapped uniformly across channels and is **pending-only** (messages skipped due to mention gating); use `messages.groupChat.historyLimit` for the global default and `channels.<channel>.historyLimit` (or `channels.<channel>.accounts.*.historyLimit`) for overrides. Set `0` to disable.
 

docs/channels/pairing.md

@@ -83,6 +83,8 @@ That bootstrap token carries the built-in pairing bootstrap profile:
 - bootstrap scope checks are role-prefixed, not one flat scope pool:
   operator scope entries only satisfy operator requests, and non-operator roles
   must still request scopes under their own role prefix
+- later token rotation/revocation remains bounded by both the device's approved
+  role contract and the caller session's operator scopes
 
 Treat the setup code like a password while it is valid.
 

docs/channels/qqbot.md

@@ -209,6 +209,10 @@ Approval prompts generated by the bot itself (for example, "allow this action?"
 - **Bot replies "gone to Mars":** credentials not configured or Gateway not started.
 - **No inbound messages:** verify `appId` and `clientSecret` are correct, and the
   bot is enabled on the QQ Open Platform.
+- **Repeated self-replies:** OpenClaw records QQ outbound ref indexes as
+  bot-authored and ignores inbound events whose current `msgIdx` matches that
+  same bot account. This prevents platform echo loops while still allowing users
+  to quote or reply to previous bot messages.
 - **Setup with `--token-file` still shows unconfigured:** `--token-file` only sets
   the AppSecret. You still need `appId` in config or `QQBOT_APP_ID`.
 - **Proactive messages not arriving:** QQ may intercept bot-initiated messages if

docs/channels/telegram.md

@@ -489,6 +489,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     - `first`
     - `all`
 
+    When reply threading is enabled and the original Telegram text or caption is available, OpenClaw includes a native Telegram quote excerpt automatically. Telegram caps native quote text at 1024 UTF-16 code units, so longer messages are quoted from the start and fall back to a plain reply if Telegram rejects the quote.
+
     Note: `off` disables implicit reply threading. Explicit `[[reply_to_*]]` tags are still honored.
 
   </Accordion>

docs/channels/whatsapp.md

@@ -151,6 +151,7 @@ OpenClaw recommends running WhatsApp on a separate number when possible. (The ch
 - 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.
+- When `messages.removeAckAfterReply` is enabled, OpenClaw clears the WhatsApp ack reaction after a visible reply is delivered.
 
 ## Plugin hooks and privacy
 
@@ -243,6 +244,7 @@ content and identifiers.
 
     - explicit WhatsApp mentions of the bot identity
     - configured mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
+    - inbound voice-note transcripts for authorized group messages
     - implicit reply-to-bot detection (reply sender matches bot identity)
 
     Security note:
@@ -295,6 +297,11 @@ When the linked self number is also present in `allowFrom`, WhatsApp self-chat s
     - `<media:document>`
     - `<media:sticker>`
 
+    Authorized group voice notes are transcribed before mention gating when the
+    body is only `<media:audio>`, so saying the bot mention in the voice note can
+    trigger the reply. If the transcript still does not mention the bot, the
+    transcript is kept in pending group history instead of the raw placeholder.
+
     Location bodies use terse coordinate text. Location labels/comments and contact/vCard details are rendered as fenced untrusted metadata, not inline prompt text.
 
   </Accordion>
@@ -361,9 +368,11 @@ When the linked self number is also present in `allowFrom`, WhatsApp self-chat s
 
   <Accordion title="Outbound media behavior">
     - supports image, video, audio (PTT voice-note), and document payloads
-    - reply payloads preserve `audioAsVoice`; WhatsApp sends audio media as Baileys PTT voice notes
-    - non-Ogg audio, including Microsoft Edge TTS MP3/WebM output, is transcoded to Ogg/Opus before PTT delivery
-    - native Ogg/Opus audio is sent with `audio/ogg; codecs=opus` for voice-note compatibility
+    - audio media is sent through the Baileys `audio` payload with `ptt: true`, so WhatsApp clients render it as a push-to-talk voice note
+    - reply payloads preserve `audioAsVoice`; TTS voice-note output for WhatsApp stays on this PTT path even when the provider returns MP3 or WebM
+    - native Ogg/Opus audio is sent as `audio/ogg; codecs=opus` for voice-note compatibility
+    - non-Ogg audio, including Microsoft Edge TTS MP3/WebM output, is transcoded with `ffmpeg` to 48 kHz mono Ogg/Opus before PTT delivery
+    - `/tts latest` sends the latest assistant reply as one voice note and suppresses repeat sends for the same reply; `/tts chat on|off|default` controls auto-TTS for the current WhatsApp chat
     - animated GIF playback is supported via `gifPlayback: true` on video sends
     - captions are applied to the first media item when sending multi-media reply payloads, except PTT voice notes send the audio first and visible text separately because WhatsApp clients do not render voice-note captions consistently
     - media source can be HTTP(S), `file://`, or local paths

docs/cli/browser.md

@@ -55,6 +55,7 @@ Detailed guidance: [Browser troubleshooting](/tools/browser#cdp-startup-failure-
 ```bash
 openclaw browser status
 openclaw browser doctor
+openclaw browser doctor --deep
 openclaw browser start
 openclaw browser start --headless
 openclaw browser stop
@@ -63,6 +64,8 @@ openclaw browser --browser-profile openclaw reset-profile
 
 Notes:
 
+- `doctor --deep` adds a live snapshot probe. It is useful when basic CDP
+  readiness is green but you want proof that the current tab can be inspected.
 - For `attachOnly` and remote CDP profiles, `openclaw browser stop` closes the
   active control session and clears temporary emulation overrides even when
   OpenClaw did not launch the browser process itself.

docs/cli/devices.md

@@ -95,9 +95,9 @@ If you omit `--scope`, later reconnects with the stored rotated token reuse that
 token's cached approved scopes. If you pass explicit `--scope` values, those
 become the stored scope set for future cached-token reconnects.
 Non-admin paired-device callers can rotate only their **own** device token.
-Also, any explicit `--scope` values must stay within the caller session's own
-operator scopes; rotation cannot mint a broader operator token than the caller
-already has.
+The target token scope set must stay within the caller session's own operator
+scopes; rotation cannot mint or preserve a broader operator token than the
+caller already has.
 
 ```
 openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
@@ -111,6 +111,8 @@ Revoke a device token for a specific role.
 
 Non-admin paired-device callers can revoke only their **own** device token.
 Revoking some other device's token requires `operator.admin`.
+The target token scope set must also fit within the caller session's own
+operator scopes; pairing-only callers cannot revoke admin/write operator tokens.
 
 ```
 openclaw devices revoke --device <deviceId> --role node
@@ -135,12 +137,15 @@ Pass `--token` or `--password` explicitly. Missing explicit credentials is an er
 - These commands require `operator.pairing` (or `operator.admin`) scope.
 - `gateway.nodes.pairing.autoApproveCidrs` is an opt-in Gateway policy for
   fresh node device pairing only; it does not change CLI approval authority.
-- Token rotation stays inside the approved pairing role set and approved scope
-  baseline for that device. A stray cached token entry does not grant a new
-  rotate target.
+- Token rotation and revocation stay inside the approved pairing role set and
+  approved scope baseline for that device. A stray cached token entry does not
+  grant a token-management target.
 - For paired-device token sessions, cross-device management is admin-only:
   `remove`, `rotate`, and `revoke` are self-only unless the caller has
   `operator.admin`.
+- Token mutation is also caller-scope contained: a pairing-only session cannot
+  rotate or revoke a token that currently carries `operator.admin` or
+  `operator.write`.
 - `devices clear` is intentionally gated by `--yes`.
 - If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
 - `devices approve` requires an explicit request ID before minting tokens; omitting `requestId` or passing `--latest` only previews the newest pending request.

docs/cli/gateway.md

@@ -324,6 +324,7 @@ Command options:
 Notes:
 
 - `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.
+- Use `gateway restart` to restart a managed service. Do not chain `gateway stop` and `gateway start` as a restart substitute; on macOS, `gateway stop` intentionally disables the LaunchAgent before stopping it.
 - When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `gateway install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
 - If token auth requires a token and the configured token SecretRef is unresolved, install fails closed instead of persisting fallback plaintext.
 - For password auth on `gateway run`, prefer `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, or a SecretRef-backed `gateway.auth.password` over inline `--password`.

docs/cli/infer.md

@@ -159,6 +159,7 @@ openclaw infer image generate --prompt "cinematic product photo of headphones" -
 openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json
 openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json
 openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json
+openclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --json
 openclaw infer image describe --file ./photo.jpg --json
 openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-4.1-mini --json
 openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json
@@ -167,6 +168,8 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j
 Notes:
 
 - Use `image edit` when starting from existing input files.
+- Use `--size`, `--aspect-ratio`, or `--resolution` with `image edit` for
+  providers/models that support geometry hints on reference-image edits.
 - Use `--output-format png --background transparent` with
   `--model openai/gpt-image-1.5` for transparent-background OpenAI PNG output;
   `--openai-background` remains available as an OpenAI-specific alias. Providers

docs/cli/models.md

@@ -47,9 +47,10 @@ Notes:
 - `models list` is read-only: it reads config, auth profiles, existing catalog
   state, and provider-owned catalog rows, but it does not rewrite
   `models.json`.
-- `models list --all` includes bundled provider-owned static catalog rows even
-  when you have not authenticated with that provider yet. Those rows still show
-  as unavailable until matching auth is configured.
+- `models list --all --provider <id>` can include provider-owned static catalog
+  rows from plugin manifests or bundled provider catalog metadata even when you
+  have not authenticated with that provider yet. Those rows still show as
+  unavailable until matching auth is configured.
 - `models list` keeps native model metadata and runtime caps distinct. In table
   output, `Ctx` shows `contextTokens/contextWindow` when an effective runtime
   cap differs from the native context window; JSON rows include `contextTokens`
@@ -153,6 +154,9 @@ provider you choose.
 
 `models auth login` runs a provider plugin’s auth flow (OAuth/API key). Use
 `openclaw plugins list` to see which providers are installed.
+Use `openclaw models auth --agent <id> <subcommand>` to write auth results to a
+specific configured agent store. The parent `--agent` flag is honored by
+`add`, `login`, `setup-token`, `paste-token`, and `login-github-copilot`.
 
 Examples:
 

docs/cli/node.md

@@ -104,6 +104,7 @@ Manage the service:
 
 ```bash
 openclaw node status
+openclaw node start
 openclaw node stop
 openclaw node restart
 openclaw node uninstall

docs/cli/plugins.md

@@ -122,6 +122,9 @@ installs the bundled plugin directly. To install an npm package with the same
 name, use an explicit scoped spec (for example `@scope/diffs`).
 
 Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
+Native OpenClaw plugin archives must contain a valid `openclaw.plugin.json` at
+the extracted plugin root; archives that only contain `package.json` are
+rejected before OpenClaw writes install records.
 
 Claude marketplace installs are also supported.
 
@@ -244,6 +247,9 @@ metadata, including records for broken or missing plugin manifests. The
 `plugins` array is the manifest-derived cold registry cache. The file includes a
 do-not-edit warning and is used by `openclaw plugins update`, uninstall,
 diagnostics, and the cold plugin registry.
+When OpenClaw sees shipped legacy `plugins.installs` records in config, it moves
+them into the plugin index and removes the config key; if either write fails,
+the config records are kept so the install metadata is not lost.
 
 ### Uninstall
 
@@ -255,13 +261,10 @@ openclaw plugins uninstall <id> --keep-files
 
 `uninstall` removes plugin records from `plugins.entries`, the persisted plugin
 index, the plugin allowlist, and linked `plugins.load.paths` entries when
-applicable.
+applicable. Unless `--keep-files` is set, uninstall also removes the tracked
+managed install directory when it is inside OpenClaw's plugin extensions root.
 For active memory plugins, the memory slot resets to `memory-core`.
 
-By default, uninstall also removes the plugin install directory under the active
-state-dir plugin root. Use
-`--keep-files` to keep files on disk.
-
 `--keep-config` is supported as a deprecated alias for `--keep-files`.
 
 ### Update

docs/cli/tasks.md

@@ -75,7 +75,7 @@ Cancels a running background task.
 openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--json]
 ```
 
-Surfaces stale, lost, delivery-failed, or otherwise inconsistent task and Task Flow records.
+Surfaces stale, lost, delivery-failed, or otherwise inconsistent task and Task Flow records. Lost tasks retained until `cleanupAfter` are warnings; expired or unstamped lost tasks are errors.
 
 ### `maintenance`
 
@@ -84,6 +84,10 @@ openclaw tasks maintenance [--apply] [--json]
 ```
 
 Previews or applies task and Task Flow reconciliation, cleanup stamping, and pruning.
+For cron tasks, reconciliation uses persisted run logs/job state before marking an
+old active task `lost`, so completed cron runs do not become false audit errors
+just because the in-memory Gateway runtime state is gone. Offline CLI audit is
+not authoritative for the Gateway's process-local cron active-job set.
 
 ### `flow`
 

docs/cli/update.md

@@ -32,7 +32,7 @@ openclaw --update
 
 ## Options
 
-- `--no-restart`: skip restarting the Gateway service after a successful update.
+- `--no-restart`: skip restarting the Gateway service after a successful update. Package-manager updates that do restart the Gateway verify the restarted service reports the expected updated version before the command succeeds.
 - `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
 - `--tag <dist-tag|version|spec>`: override the package target for this update only. For package installs, `main` maps to `github:openclaw/openclaw#main`.
 - `--dry-run`: preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.

docs/concepts/agent-runtimes.md

@@ -27,6 +27,24 @@ harness implements the `codex` runtime. The config key is still named
 `embeddedHarness` for compatibility, but user-facing docs and status output
 should generally say runtime.
 
+## Three things named Codex
+
+Most confusion comes from three different surfaces sharing the Codex name:
+
+| Surface                                              | OpenClaw name/config                 | What it does                                                                                        |
+| ---------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Codex OAuth provider route                           | `openai-codex/*` model refs          | Uses ChatGPT/Codex subscription OAuth through the normal OpenClaw PI runner.                        |
+| Native Codex app-server runtime                      | `embeddedHarness.runtime: "codex"`   | Runs the embedded agent turn through the bundled Codex app-server harness.                          |
+| Codex ACP adapter                                    | `runtime: "acp"`, `agentId: "codex"` | Runs Codex through the external ACP/acpx control plane. Use only when ACP/acpx is explicitly asked. |
+| Native Codex chat-control command set                | `/codex ...`                         | Binds, resumes, steers, stops, and inspects Codex app-server threads from chat.                     |
+| OpenAI Platform API route for GPT/Codex-style models | `openai/*` model refs                | Uses OpenAI API-key auth unless a runtime override, such as `runtime: "codex"`, runs the turn.      |
+
+Those surfaces are intentionally independent. Enabling the `codex` plugin makes
+the native app-server features available; it does not rewrite
+`openai-codex/*` into `openai/*`, does not change existing sessions, and does
+not make ACP the Codex default. Selecting `openai-codex/*` means "use the Codex
+OAuth provider route" unless you separately force a runtime.
+
 The common Codex setup uses the `openai` provider with the `codex` runtime:
 
 ```json5
@@ -53,6 +71,19 @@ Codex only when the user explicitly asks for ACP/acpx or is testing the ACP
 adapter path. Claude Code, Gemini CLI, OpenCode, Cursor, and similar external
 harnesses still use ACP.
 
+This is the agent-facing decision tree:
+
+1. If the user asks for **Codex bind/control/thread/resume/steer/stop**, use the
+   native `/codex` command surface when the bundled `codex` plugin is enabled.
+2. If the user asks for **Codex as the embedded runtime**, use
+   `openai/<model>` with `embeddedHarness.runtime: "codex"`.
+3. If the user asks for **Codex OAuth/subscription auth on the normal OpenClaw
+   runner**, use `openai-codex/<model>` and leave the runtime as PI.
+4. If the user explicitly says **ACP**, **acpx**, or **Codex ACP adapter**, use
+   ACP with `runtime: "acp"` and `agentId: "codex"`.
+5. If the request is for **Claude Code, Gemini CLI, OpenCode, Cursor, Droid, or
+   another external harness**, use ACP/acpx, not the native sub-agent runtime.
+
 | You mean...                             | Use...                                       |
 | --------------------------------------- | -------------------------------------------- |
 | Codex app-server chat/thread control    | `/codex ...` from the bundled `codex` plugin |
@@ -106,6 +137,18 @@ Explicit plugin runtimes fail closed by default. For example,
 a broader fallback setting, so an agent-level `runtime: "codex"` is not silently
 routed back to PI just because defaults used `fallback: "pi"`.
 
+`auto` mode is intentionally conservative. Plugin runtimes can claim
+provider/model pairs they understand, but the Codex plugin does not claim the
+`openai-codex` provider in `auto` mode. That keeps
+`openai-codex/*` as the explicit PI Codex OAuth route and avoids silently
+moving subscription-auth configs onto the native app-server harness.
+
+If `openclaw doctor` warns that the `codex` plugin is enabled while
+`openai-codex/*` still routes through PI, treat that as a diagnosis, not a
+migration. Keep the config unchanged when PI Codex OAuth is what you want.
+Switch to `openai/<model>` plus `runtime: "codex"` only when you want native
+Codex app-server execution.
+
 ## Compatibility contract
 
 When a runtime is not PI, it should document what OpenClaw surfaces it supports.

docs/concepts/context-engine.md

@@ -5,115 +5,114 @@ read_when:
   - You are switching between the legacy engine and a plugin engine
   - You are building a context engine plugin
 title: "Context engine"
+sidebarTitle: "Context engine"
 ---
 
-A **context engine** controls how OpenClaw builds model context for each run:
-which messages to include, how to summarize older history, and how to manage
-context across subagent boundaries.
+A **context engine** controls how OpenClaw builds model context for each run: which messages to include, how to summarize older history, and how to manage context across subagent boundaries.
 
-OpenClaw ships with a built-in `legacy` engine and uses it by default — most
-users never need to change this. Install and select a plugin engine only when
-you want different assembly, compaction, or cross-session recall behavior.
+OpenClaw ships with a built-in `legacy` engine and uses it by default — most users never need to change this. Install and select a plugin engine only when you want different assembly, compaction, or cross-session recall behavior.
 
 ## Quick start
 
-Check which engine is active:
+<Steps>
+  <Step title="Check which engine is active">
+    ```bash
+    openclaw doctor
+    # or inspect config directly:
+    cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
+    ```
+  </Step>
+  <Step title="Install a plugin engine">
+    Context engine plugins are installed like any other OpenClaw plugin.
 
-```bash
-openclaw doctor
-# or inspect config directly:
-cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
-```
+    <Tabs>
+      <Tab title="From npm">
+        ```bash
+        openclaw plugins install @martian-engineering/lossless-claw
+        ```
+      </Tab>
+      <Tab title="From a local path">
+        ```bash
+        openclaw plugins install -l ./my-context-engine
+        ```
+      </Tab>
+    </Tabs>
 
-### Installing a context engine plugin
-
-Context engine plugins are installed like any other OpenClaw plugin. Install
-first, then select the engine in the slot:
-
-```bash
-# Install from npm
-openclaw plugins install @martian-engineering/lossless-claw
-
-# Or install from a local path (for development)
-openclaw plugins install -l ./my-context-engine
-```
-
-Then enable the plugin and select it as the active engine in your config:
-
-```json5
-// openclaw.json
-{
-  plugins: {
-    slots: {
-      contextEngine: "lossless-claw", // must match the plugin's registered engine id
-    },
-    entries: {
-      "lossless-claw": {
-        enabled: true,
-        // Plugin-specific config goes here (see the plugin's docs)
+  </Step>
+  <Step title="Enable and select the engine">
+    ```json5
+    // openclaw.json
+    {
+      plugins: {
+        slots: {
+          contextEngine: "lossless-claw", // must match the plugin's registered engine id
+        },
+        entries: {
+          "lossless-claw": {
+            enabled: true,
+            // Plugin-specific config goes here (see the plugin's docs)
+          },
+        },
       },
-    },
-  },
-}
-```
+    }
+    ```
 
-Restart the gateway after installing and configuring.
+    Restart the gateway after installing and configuring.
 
-To switch back to the built-in engine, set `contextEngine` to `"legacy"` (or
-remove the key entirely — `"legacy"` is the default).
+  </Step>
+  <Step title="Switch back to legacy (optional)">
+    Set `contextEngine` to `"legacy"` (or remove the key entirely — `"legacy"` is the default).
+  </Step>
+</Steps>
 
 ## How it works
 
-Every time OpenClaw runs a model prompt, the context engine participates at
-four lifecycle points:
+Every time OpenClaw runs a model prompt, the context engine participates at four lifecycle points:
 
-1. **Ingest** — called when a new message is added to the session. The engine
-   can store or index the message in its own data store.
-2. **Assemble** — called before each model run. The engine returns an ordered
-   set of messages (and an optional `systemPromptAddition`) that fit within
-   the token budget.
-3. **Compact** — called when the context window is full, or when the user runs
-   `/compact`. The engine summarizes older history to free space.
-4. **After turn** — called after a run completes. The engine can persist state,
-   trigger background compaction, or update indexes.
+<AccordionGroup>
+  <Accordion title="1. Ingest">
+    Called when a new message is added to the session. The engine can store or index the message in its own data store.
+  </Accordion>
+  <Accordion title="2. Assemble">
+    Called before each model run. The engine returns an ordered set of messages (and an optional `systemPromptAddition`) that fit within the token budget.
+  </Accordion>
+  <Accordion title="3. Compact">
+    Called when the context window is full, or when the user runs `/compact`. The engine summarizes older history to free space.
+  </Accordion>
+  <Accordion title="4. After turn">
+    Called after a run completes. The engine can persist state, trigger background compaction, or update indexes.
+  </Accordion>
+</AccordionGroup>
 
-For the bundled non-ACP Codex harness, OpenClaw applies the same lifecycle by
-projecting assembled context into Codex developer instructions and the current
-turn prompt. Codex still owns its native thread history and native compactor.
+For the bundled non-ACP Codex harness, OpenClaw applies the same lifecycle by projecting assembled context into Codex developer instructions and the current turn prompt. Codex still owns its native thread history and native compactor.
 
 ### Subagent lifecycle (optional)
 
 OpenClaw calls two optional subagent lifecycle hooks:
 
-- **prepareSubagentSpawn** — prepare shared context state before a child run
-  starts. The hook receives parent/child session keys, `contextMode`
-  (`isolated` or `fork`), available transcript ids/files, and optional TTL.
-  If it returns a rollback handle, OpenClaw calls it when spawn fails after
-  preparation succeeds.
-- **onSubagentEnded** — clean up when a subagent session completes or is swept.
+<ParamField path="prepareSubagentSpawn" type="method">
+  Prepare shared context state before a child run starts. The hook receives parent/child session keys, `contextMode` (`isolated` or `fork`), available transcript ids/files, and optional TTL. If it returns a rollback handle, OpenClaw calls it when spawn fails after preparation succeeds.
+</ParamField>
+<ParamField path="onSubagentEnded" type="method">
+  Clean up when a subagent session completes or is swept.
+</ParamField>
 
 ### System prompt addition
 
-The `assemble` method can return a `systemPromptAddition` string. OpenClaw
-prepends this to the system prompt for the run. This lets engines inject
-dynamic recall guidance, retrieval instructions, or context-aware hints
-without requiring static workspace files.
+The `assemble` method can return a `systemPromptAddition` string. OpenClaw prepends this to the system prompt for the run. This lets engines inject dynamic recall guidance, retrieval instructions, or context-aware hints without requiring static workspace files.
 
 ## The legacy engine
 
 The built-in `legacy` engine preserves OpenClaw's original behavior:
 
 - **Ingest**: no-op (the session manager handles message persistence directly).
-- **Assemble**: pass-through (the existing sanitize → validate → limit pipeline
-  in the runtime handles context assembly).
-- **Compact**: delegates to the built-in summarization compaction, which creates
-  a single summary of older messages and keeps recent messages intact.
+- **Assemble**: pass-through (the existing sanitize → validate → limit pipeline in the runtime handles context assembly).
+- **Compact**: delegates to the built-in summarization compaction, which creates a single summary of older messages and keeps recent messages intact.
 - **After turn**: no-op.
 
 The legacy engine does not register tools or provide a `systemPromptAddition`.
 
-When no `plugins.slots.contextEngine` is set (or it's set to `"legacy"`), this
-engine is used automatically.
+When no `plugins.slots.contextEngine` is set (or it's set to `"legacy"`), this engine is used automatically.
 
 ## Plugin engines
 
@@ -185,11 +184,15 @@ Required members:
 
 `assemble` returns an `AssembleResult` with:
 
-- `messages` — the ordered messages to send to the model.
-- `estimatedTokens` (required, `number`) — the engine's estimate of total
-  tokens in the assembled context. OpenClaw uses this for compaction threshold
-  decisions and diagnostic reporting.
-- `systemPromptAddition` (optional, `string`) — prepended to the system prompt.
+<ParamField path="messages" type="Message[]" required>
+  The ordered messages to send to the model.
+</ParamField>
+<ParamField path="estimatedTokens" type="number" required>
+  The engine's estimate of total tokens in the assembled context. OpenClaw uses this for compaction threshold decisions and diagnostic reporting.
+</ParamField>
+<ParamField path="systemPromptAddition" type="string">
+  Prepended to the system prompt.
+</ParamField>
 
 Optional members:
 
@@ -204,34 +207,33 @@ Optional members:
 
 ### ownsCompaction
 
-`ownsCompaction` controls whether Pi's built-in in-attempt auto-compaction stays
-enabled for the run:
+`ownsCompaction` controls whether Pi's built-in in-attempt auto-compaction stays enabled for the run:
 
-- `true` — the engine owns compaction behavior. OpenClaw disables Pi's built-in
-  auto-compaction for that run, and the engine's `compact()` implementation is
-  responsible for `/compact`, overflow recovery compaction, and any proactive
-  compaction it wants to do in `afterTurn()`. OpenClaw may still run the
-  pre-prompt overflow safeguard; when it predicts the full transcript will
-  overflow, the recovery path calls the active engine's `compact()` before
-  submitting another prompt.
-- `false` or unset — Pi's built-in auto-compaction may still run during prompt
-  execution, but the active engine's `compact()` method is still called for
-  `/compact` and overflow recovery.
+<AccordionGroup>
+  <Accordion title="ownsCompaction: true">
+    The engine owns compaction behavior. OpenClaw disables Pi's built-in auto-compaction for that run, and the engine's `compact()` implementation is responsible for `/compact`, overflow recovery compaction, and any proactive compaction it wants to do in `afterTurn()`. OpenClaw may still run the pre-prompt overflow safeguard; when it predicts the full transcript will overflow, the recovery path calls the active engine's `compact()` before submitting another prompt.
+  </Accordion>
+  <Accordion title="ownsCompaction: false or unset">
+    Pi's built-in auto-compaction may still run during prompt execution, but the active engine's `compact()` method is still called for `/compact` and overflow recovery.
+  </Accordion>
+</AccordionGroup>
 
-`ownsCompaction: false` does **not** mean OpenClaw automatically falls back to
-the legacy engine's compaction path.
+<Warning>
+`ownsCompaction: false` does **not** mean OpenClaw automatically falls back to the legacy engine's compaction path.
+</Warning>
 
 That means there are two valid plugin patterns:
 
-- **Owning mode** — implement your own compaction algorithm and set
-  `ownsCompaction: true`.
-- **Delegating mode** — set `ownsCompaction: false` and have `compact()` call
-  `delegateCompactionToRuntime(...)` from `openclaw/plugin-sdk/core` to use
-  OpenClaw's built-in compaction behavior.
+<Tabs>
+  <Tab title="Owning mode">
+    Implement your own compaction algorithm and set `ownsCompaction: true`.
+  </Tab>
+  <Tab title="Delegating mode">
+    Set `ownsCompaction: false` and have `compact()` call `delegateCompactionToRuntime(...)` from `openclaw/plugin-sdk/core` to use OpenClaw's built-in compaction behavior.
+  </Tab>
+</Tabs>
 
-A no-op `compact()` is unsafe for an active non-owning engine because it
-disables the normal `/compact` and overflow-recovery compaction path for that
-engine slot.
+A no-op `compact()` is unsafe for an active non-owning engine because it disables the normal `/compact` and overflow-recovery compaction path for that engine slot.
 
 ## Configuration reference
 
@@ -247,47 +249,35 @@ engine slot.
 }
 ```
 
-The slot is exclusive at run time — only one registered context engine is
-resolved for a given run or compaction operation. Other enabled
-`kind: "context-engine"` plugins can still load and run their registration
-code; `plugins.slots.contextEngine` only selects which registered engine id
-OpenClaw resolves when it needs a context engine.
+<Note>
+The slot is exclusive at run time — only one registered context engine is resolved for a given run or compaction operation. Other enabled `kind: "context-engine"` plugins can still load and run their registration code; `plugins.slots.contextEngine` only selects which registered engine id OpenClaw resolves when it needs a context engine.
+</Note>
 
 ## Relationship to compaction and memory
 
-- **Compaction** is one responsibility of the context engine. The legacy engine
-  delegates to OpenClaw's built-in summarization. Plugin engines can implement
-  any compaction strategy (DAG summaries, vector retrieval, etc.).
-- **Memory plugins** (`plugins.slots.memory`) are separate from context engines.
-  Memory plugins provide search/retrieval; context engines control what the
-  model sees. They can work together — a context engine might use memory
-  plugin data during assembly. Plugin engines that want the active memory
-  prompt path should prefer `buildMemorySystemPromptAddition(...)` from
-  `openclaw/plugin-sdk/core`, which converts the active memory prompt sections
-  into a ready-to-prepend `systemPromptAddition`. If an engine needs lower-level
-  control, it can still pull raw lines from
-  `openclaw/plugin-sdk/memory-host-core` via
-  `buildActiveMemoryPromptSection(...)`.
-- **Session pruning** (trimming old tool results in-memory) still runs
-  regardless of which context engine is active.
+<AccordionGroup>
+  <Accordion title="Compaction">
+    Compaction is one responsibility of the context engine. The legacy engine delegates to OpenClaw's built-in summarization. Plugin engines can implement any compaction strategy (DAG summaries, vector retrieval, etc.).
+  </Accordion>
+  <Accordion title="Memory plugins">
+    Memory plugins (`plugins.slots.memory`) are separate from context engines. Memory plugins provide search/retrieval; context engines control what the model sees. They can work together — a context engine might use memory plugin data during assembly. Plugin engines that want the active memory prompt path should prefer `buildMemorySystemPromptAddition(...)` from `openclaw/plugin-sdk/core`, which converts the active memory prompt sections into a ready-to-prepend `systemPromptAddition`. If an engine needs lower-level control, it can still pull raw lines from `openclaw/plugin-sdk/memory-host-core` via `buildActiveMemoryPromptSection(...)`.
+  </Accordion>
+  <Accordion title="Session pruning">
+    Trimming old tool results in-memory still runs regardless of which context engine is active.
+  </Accordion>
+</AccordionGroup>
 
 ## Tips
 
 - Use `openclaw doctor` to verify your engine is loading correctly.
-- If switching engines, existing sessions continue with their current history.
-  The new engine takes over for future runs.
-- Engine errors are logged and surfaced in diagnostics. If a plugin engine
-  fails to register or the selected engine id cannot be resolved, OpenClaw
-  does not fall back automatically; runs fail until you fix the plugin or
-  switch `plugins.slots.contextEngine` back to `"legacy"`.
-- For development, use `openclaw plugins install -l ./my-engine` to link a
-  local plugin directory without copying.
-
-See also: [Compaction](/concepts/compaction), [Context](/concepts/context),
-[Plugins](/tools/plugin), [Plugin manifest](/plugins/manifest).
+- If switching engines, existing sessions continue with their current history. The new engine takes over for future runs.
+- Engine errors are logged and surfaced in diagnostics. If a plugin engine fails to register or the selected engine id cannot be resolved, OpenClaw does not fall back automatically; runs fail until you fix the plugin or switch `plugins.slots.contextEngine` back to `"legacy"`.
+- For development, use `openclaw plugins install -l ./my-engine` to link a local plugin directory without copying.
 
 ## Related
 
+- [Compaction](/concepts/compaction) — summarizing long conversations
 - [Context](/concepts/context) — how context is built for agent turns
 - [Plugin Architecture](/plugins/architecture) — registering context engine plugins
-- [Compaction](/concepts/compaction) — summarizing long conversations
+- [Plugin manifest](/plugins/manifest) — plugin manifest fields
+- [Plugins](/tools/plugin) — plugin overview

docs/concepts/model-providers.md

@@ -4,35 +4,42 @@ read_when:
   - You need a provider-by-provider model setup reference
   - You want example configs or CLI onboarding commands for model providers
 title: "Model providers"
+sidebarTitle: "Model providers"
 ---
 
 Reference for **LLM/model providers** (not chat channels like WhatsApp/Telegram). For model selection rules, see [Models](/concepts/models).
 
 ## Quick rules
 
-- Model refs use `provider/model` (example: `opencode/claude-opus-4-6`).
-- `agents.defaults.models` acts as an allowlist when set.
-- CLI helpers: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
-- `models.providers.*.models[].contextWindow` is native model metadata; `contextTokens` is the effective runtime cap.
-- Fallback rules, cooldown probes, and session-override persistence: [Model failover](/concepts/model-failover).
-- OpenAI-family routes are prefix-specific: `openai/<model>` uses the direct
-  OpenAI API-key provider in PI, `openai-codex/<model>` uses Codex OAuth in PI,
-  and `openai/<model>` plus `agents.defaults.embeddedHarness.runtime: "codex"`
-  uses the native Codex app-server harness. See [OpenAI](/providers/openai)
-  and [Codex harness](/plugins/codex-harness). If the provider/runtime split is
-  confusing, read [Agent runtimes](/concepts/agent-runtimes) first.
-- Plugin auto-enable follows that same boundary: `openai-codex/<model>` belongs
-  to the OpenAI plugin, while the Codex plugin is enabled by
-  `embeddedHarness.runtime: "codex"` or legacy `codex/<model>` refs.
-- CLI runtimes use the same split: choose canonical model refs such as
-  `anthropic/claude-*`, `google/gemini-*`, or `openai/gpt-*`, then set
-  `agents.defaults.embeddedHarness.runtime` to `claude-cli`,
-  `google-gemini-cli`, or `codex-cli` when you want a local CLI backend.
-  Legacy `claude-cli/*`, `google-gemini-cli/*`, and `codex-cli/*` refs migrate
-  back to canonical provider refs with the runtime recorded separately.
-- GPT-5.5 is available through `openai/gpt-5.5` for direct API-key traffic,
-  `openai-codex/gpt-5.5` in PI for Codex OAuth, and the native Codex
-  app-server harness when `embeddedHarness.runtime: "codex"` is set.
+<AccordionGroup>
+  <Accordion title="Model refs and CLI helpers">
+    - Model refs use `provider/model` (example: `opencode/claude-opus-4-6`).
+    - `agents.defaults.models` acts as an allowlist when set.
+    - CLI helpers: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
+    - `models.providers.*.models[].contextWindow` is native model metadata; `contextTokens` is the effective runtime cap.
+    - Fallback rules, cooldown probes, and session-override persistence: [Model failover](/concepts/model-failover).
+  </Accordion>
+  <Accordion title="OpenAI provider/runtime split">
+    OpenAI-family routes are prefix-specific:
+
+    - `openai/<model>` uses the direct OpenAI API-key provider in PI.
+    - `openai-codex/<model>` uses Codex OAuth in PI.
+    - `openai/<model>` plus `agents.defaults.embeddedHarness.runtime: "codex"` uses the native Codex app-server harness.
+
+    See [OpenAI](/providers/openai) and [Codex harness](/plugins/codex-harness). If the provider/runtime split is confusing, read [Agent runtimes](/concepts/agent-runtimes) first.
+
+    Plugin auto-enable follows the same boundary: `openai-codex/<model>` belongs to the OpenAI plugin, while the Codex plugin is enabled by `embeddedHarness.runtime: "codex"` or legacy `codex/<model>` refs.
+
+    GPT-5.5 is available through `openai/gpt-5.5` for direct API-key traffic, `openai-codex/gpt-5.5` in PI for Codex OAuth, and the native Codex app-server harness when `embeddedHarness.runtime: "codex"` is set.
+
+  </Accordion>
+  <Accordion title="CLI runtimes">
+    CLI runtimes use the same split: choose canonical model refs such as `anthropic/claude-*`, `google/gemini-*`, or `openai/gpt-*`, then set `agents.defaults.embeddedHarness.runtime` to `claude-cli`, `google-gemini-cli`, or `codex-cli` when you want a local CLI backend.
+
+    Legacy `claude-cli/*`, `google-gemini-cli/*`, and `codex-cli/*` refs migrate back to canonical provider refs with the runtime recorded separately.
+
+  </Accordion>
+</AccordionGroup>
 
 ## Plugin-owned provider behavior
 
@@ -46,25 +53,28 @@ Provider runtime `capabilities` is shared runner metadata (provider family, tran
 
 ## API key rotation
 
-- Supports generic provider rotation for selected providers.
-- Configure multiple keys via:
-  - `OPENCLAW_LIVE_<PROVIDER>_KEY` (single live override, highest priority)
-  - `<PROVIDER>_API_KEYS` (comma or semicolon list)
-  - `<PROVIDER>_API_KEY` (primary key)
-  - `<PROVIDER>_API_KEY_*` (numbered list, e.g. `<PROVIDER>_API_KEY_1`)
-- For Google providers, `GOOGLE_API_KEY` is also included as fallback.
-- Key selection order preserves priority and deduplicates values.
-- Requests are retried with the next key only on rate-limit responses (for
-  example `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many
-concurrent requests`, `ThrottlingException`, `concurrency limit reached`,
-  `workers_ai ... quota limit exceeded`, or periodic usage-limit messages).
-- Non-rate-limit failures fail immediately; no key rotation is attempted.
-- When all candidate keys fail, the final error is returned from the last attempt.
+<AccordionGroup>
+  <Accordion title="Key sources and priority">
+    Configure multiple keys via:
+
+    - `OPENCLAW_LIVE_<PROVIDER>_KEY` (single live override, highest priority)
+    - `<PROVIDER>_API_KEYS` (comma or semicolon list)
+    - `<PROVIDER>_API_KEY` (primary key)
+    - `<PROVIDER>_API_KEY_*` (numbered list, e.g. `<PROVIDER>_API_KEY_1`)
+
+    For Google providers, `GOOGLE_API_KEY` is also included as fallback. Key selection order preserves priority and deduplicates values.
+
+  </Accordion>
+  <Accordion title="When rotation kicks in">
+    - Requests are retried with the next key only on rate-limit responses (for example `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, or periodic usage-limit messages).
+    - Non-rate-limit failures fail immediately; no key rotation is attempted.
+    - When all candidate keys fail, the final error is returned from the last attempt.
+  </Accordion>
+</AccordionGroup>
 
 ## Built-in providers (pi-ai catalog)
 
-OpenClaw ships with the pi‑ai catalog. These providers require **no**
-`models.providers` config; just set auth + pick a model.
+OpenClaw ships with the pi‑ai catalog. These providers require **no** `models.providers` config; just set auth + pick a model.
 
 ### OpenAI
 
@@ -72,8 +82,7 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Auth: `OPENAI_API_KEY`
 - Optional rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (single override)
 - Example models: `openai/gpt-5.5`, `openai/gpt-5.4-mini`
-- Verify account/model availability with `openclaw models list --provider openai`
-  if a specific install or API key behaves differently.
+- Verify account/model availability with `openclaw models list --provider openai` if a specific install or API key behaves differently.
 - CLI: `openclaw onboard --auth-choice openai-api-key`
 - Default transport is `auto` (WebSocket-first, SSE fallback)
 - Override per model via `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`)
@@ -81,11 +90,8 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - OpenAI priority processing can be enabled via `agents.defaults.models["openai/<model>"].params.serviceTier`
 - `/fast` and `params.fastMode` map direct `openai/*` Responses requests to `service_tier=priority` on `api.openai.com`
 - Use `params.serviceTier` when you want an explicit tier instead of the shared `/fast` toggle
-- Hidden OpenClaw attribution headers (`originator`, `version`,
-  `User-Agent`) apply only on native OpenAI traffic to `api.openai.com`, not
-  generic OpenAI-compatible proxies
-- Native OpenAI routes also keep Responses `store`, prompt-cache hints, and
-  OpenAI reasoning-compat payload shaping; proxy routes do not
+- Hidden OpenClaw attribution headers (`originator`, `version`, `User-Agent`) apply only on native OpenAI traffic to `api.openai.com`, not generic OpenAI-compatible proxies
+- Native OpenAI routes also keep Responses `store`, prompt-cache hints, and OpenAI reasoning-compat payload shaping; proxy routes do not
 - `openai/gpt-5.3-codex-spark` is intentionally suppressed in OpenClaw because live OpenAI API requests reject it and the current Codex catalog does not expose it
 
 ```json5
@@ -102,8 +108,10 @@ 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`)
-- 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.
+
+<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.
+</Note>
 
 ```json5
 {
@@ -119,16 +127,12 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Native Codex app-server harness ref: `openai/gpt-5.5` with `agents.defaults.embeddedHarness.runtime: "codex"`
 - Native Codex app-server harness docs: [Codex harness](/plugins/codex-harness)
 - Legacy model refs: `codex/gpt-*`
-- Plugin boundary: `openai-codex/*` loads the OpenAI plugin; the native Codex
-  app-server plugin is selected only by the Codex harness runtime or legacy
-  `codex/*` refs.
+- Plugin boundary: `openai-codex/*` loads the OpenAI plugin; the native Codex app-server plugin is selected only by the Codex harness runtime or legacy `codex/*` refs.
 - CLI: `openclaw onboard --auth-choice openai-codex` or `openclaw models auth login --provider openai-codex`
 - Default transport is `auto` (WebSocket-first, SSE fallback)
 - Override per PI model via `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`)
 - `params.serviceTier` is also forwarded on native Codex Responses requests (`chatgpt.com/backend-api`)
-- Hidden OpenClaw attribution headers (`originator`, `version`,
-  `User-Agent`) are only attached on native Codex traffic to
-  `chatgpt.com/backend-api`, not generic OpenAI-compatible proxies
+- Hidden OpenClaw attribution headers (`originator`, `version`, `User-Agent`) are only attached on native Codex traffic to `chatgpt.com/backend-api`, not generic OpenAI-compatible proxies
 - Shares the same `/fast` toggle and `params.fastMode` config as direct `openai/*`; OpenClaw maps that to `service_tier=priority`
 - `openai-codex/gpt-5.5` uses the Codex catalog native `contextWindow = 400000` and default runtime `contextTokens = 272000`; override the runtime cap with `models.providers.openai-codex.models[].contextTokens`
 - Policy note: OpenAI Codex OAuth is explicitly supported for external tools/workflows like OpenClaw.
@@ -154,9 +158,17 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 ### Other subscription-style hosted options
 
-- [Qwen Cloud](/providers/qwen): Qwen Cloud provider surface plus Alibaba DashScope and Coding Plan endpoint mapping
-- [MiniMax](/providers/minimax): MiniMax Coding Plan OAuth or API key access
-- [GLM models](/providers/glm): Z.AI Coding Plan or general API endpoints
+<CardGroup cols={3}>
+  <Card title="GLM models" href="/providers/glm">
+    Z.AI Coding Plan or general API endpoints.
+  </Card>
+  <Card title="MiniMax" href="/providers/minimax">
+    MiniMax Coding Plan OAuth or API key access.
+  </Card>
+  <Card title="Qwen Cloud" href="/providers/qwen">
+    Qwen Cloud provider surface plus Alibaba DashScope and Coding Plan endpoint mapping.
+  </Card>
+</CardGroup>
 
 ### OpenCode
 
@@ -180,29 +192,54 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Example models: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
 - Compatibility: legacy OpenClaw config using `google/gemini-3.1-flash-preview` is normalized to `google/gemini-3-flash-preview`
 - CLI: `openclaw onboard --auth-choice gemini-api-key`
-- Thinking: `/think adaptive` uses Google dynamic thinking. Gemini 3/3.1 omit a fixed
-  `thinkingLevel`; Gemini 2.5 sends `thinkingBudget: -1`.
-- Direct Gemini runs also accept `agents.defaults.models["google/<model>"].params.cachedContent`
-  (or legacy `cached_content`) to forward a provider-native
-  `cachedContents/...` handle; Gemini cache hits surface as OpenClaw `cacheRead`
+- Thinking: `/think adaptive` uses Google dynamic thinking. Gemini 3/3.1 omit a fixed `thinkingLevel`; Gemini 2.5 sends `thinkingBudget: -1`.
+- Direct Gemini runs also accept `agents.defaults.models["google/<model>"].params.cachedContent` (or legacy `cached_content`) to forward a provider-native `cachedContents/...` handle; Gemini cache hits surface as OpenClaw `cacheRead`
 
 ### Google Vertex and Gemini CLI
 
 - 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-flash-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`.
+
+<Warning>
+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.
+</Warning>
+
+Gemini CLI OAuth is shipped as part of the bundled `google` plugin.
+
+<Steps>
+  <Step title="Install Gemini CLI">
+    <Tabs>
+      <Tab title="brew">
+        ```bash
+        brew install gemini-cli
+        ```
+      </Tab>
+      <Tab title="npm">
+        ```bash
+        npm install -g @google/gemini-cli
+        ```
+      </Tab>
+    </Tabs>
+  </Step>
+  <Step title="Enable plugin">
+    ```bash
+    openclaw plugins enable google
+    ```
+  </Step>
+  <Step title="Login">
+    ```bash
+    openclaw models auth login --provider google-gemini-cli --set-default
+    ```
+
+    Default model: `google-gemini-cli/gemini-3-flash-preview`. 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.
+
+  </Step>
+  <Step title="Set project (if needed)">
+    If requests fail after login, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host.
+  </Step>
+</Steps>
+
+Gemini CLI JSON replies are parsed from `response`; usage falls back to `stats`, with `stats.cached` normalized into OpenClaw `cacheRead`.
 
 ### Z.AI (GLM)
 
@@ -217,8 +254,7 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `vercel-ai-gateway`
 - Auth: `AI_GATEWAY_API_KEY`
-- Example models: `vercel-ai-gateway/anthropic/claude-opus-4.6`,
-  `vercel-ai-gateway/moonshotai/kimi-k2.6`
+- Example models: `vercel-ai-gateway/anthropic/claude-opus-4.6`, `vercel-ai-gateway/moonshotai/kimi-k2.6`
 - CLI: `openclaw onboard --auth-choice ai-gateway-api-key`
 
 ### Kilo Gateway
@@ -228,11 +264,8 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Example model: `kilocode/kilo/auto`
 - CLI: `openclaw onboard --auth-choice kilocode-api-key`
 - Base URL: `https://api.kilo.ai/api/gateway/`
-- Static fallback catalog ships `kilocode/kilo/auto`; live
-  `https://api.kilo.ai/api/gateway/models` discovery can expand the runtime
-  catalog further.
-- Exact upstream routing behind `kilocode/kilo/auto` is owned by Kilo Gateway,
-  not hard-coded in OpenClaw.
+- Static fallback catalog ships `kilocode/kilo/auto`; live `https://api.kilo.ai/api/gateway/models` discovery can expand the runtime catalog further.
+- Exact upstream routing behind `kilocode/kilo/auto` is owned by Kilo Gateway, not hard-coded in OpenClaw.
 
 See [/providers/kilocode](/providers/kilocode) for setup details.
 
@@ -264,28 +297,35 @@ See [/providers/kilocode](/providers/kilocode) for setup details.
 | xAI                     | `xai`                            | `XAI_API_KEY`                                                | `xai/grok-4`                                    |
 | Xiaomi                  | `xiaomi`                         | `XIAOMI_API_KEY`                                             | `xiaomi/mimo-v2-flash`                          |
 
-Quirks worth knowing:
+#### Quirks worth knowing
 
-- **OpenRouter** applies its app-attribution headers and Anthropic `cache_control` markers only on verified `openrouter.ai` routes. DeepSeek, Moonshot, and ZAI refs are cache-TTL eligible for OpenRouter-managed prompt caching but do not receive Anthropic cache markers. As a proxy-style OpenAI-compatible path, it skips native-OpenAI-only shaping (`serviceTier`, Responses `store`, prompt-cache hints, OpenAI reasoning-compat). Gemini-backed refs keep proxy-Gemini thought-signature sanitation only.
-- **Kilo Gateway** Gemini-backed refs follow the same proxy-Gemini sanitation path; `kilocode/kilo/auto` and other proxy-reasoning-unsupported refs skip proxy reasoning injection.
-- **MiniMax** API-key onboarding writes explicit text-only M2.7 chat model definitions; image understanding stays on the plugin-owned `MiniMax-VL-01` media provider.
-- **xAI** uses the xAI Responses path. `/fast` or `params.fastMode: true` rewrites `grok-3`, `grok-3-mini`, `grok-4`, and `grok-4-0709` to their `*-fast` variants. `tool_stream` defaults on; disable via `agents.defaults.models["xai/<model>"].params.tool_stream=false`.
-- **Cerebras** GLM models use `zai-glm-4.7` / `zai-glm-4.6`; OpenAI-compatible base URL is `https://api.cerebras.ai/v1`.
+<AccordionGroup>
+  <Accordion title="OpenRouter">
+    Applies its app-attribution headers and Anthropic `cache_control` markers only on verified `openrouter.ai` routes. DeepSeek, Moonshot, and ZAI refs are cache-TTL eligible for OpenRouter-managed prompt caching but do not receive Anthropic cache markers. As a proxy-style OpenAI-compatible path, it skips native-OpenAI-only shaping (`serviceTier`, Responses `store`, prompt-cache hints, OpenAI reasoning-compat). Gemini-backed refs keep proxy-Gemini thought-signature sanitation only.
+  </Accordion>
+  <Accordion title="Kilo Gateway">
+    Gemini-backed refs follow the same proxy-Gemini sanitation path; `kilocode/kilo/auto` and other proxy-reasoning-unsupported refs skip proxy reasoning injection.
+  </Accordion>
+  <Accordion title="MiniMax">
+    API-key onboarding writes explicit text-only M2.7 chat model definitions; image understanding stays on the plugin-owned `MiniMax-VL-01` media provider.
+  </Accordion>
+  <Accordion title="xAI">
+    Uses the xAI Responses path. `/fast` or `params.fastMode: true` rewrites `grok-3`, `grok-3-mini`, `grok-4`, and `grok-4-0709` to their `*-fast` variants. `tool_stream` defaults on; disable via `agents.defaults.models["xai/<model>"].params.tool_stream=false`.
+  </Accordion>
+  <Accordion title="Cerebras">
+    GLM models use `zai-glm-4.7` / `zai-glm-4.6`; OpenAI-compatible base URL is `https://api.cerebras.ai/v1`.
+  </Accordion>
+</AccordionGroup>
 
 ## Providers via `models.providers` (custom/base URL)
 
-Use `models.providers` (or `models.json`) to add **custom** providers or
-OpenAI/Anthropic‑compatible proxies.
+Use `models.providers` (or `models.json`) to add **custom** providers or OpenAI/Anthropic‑compatible proxies.
 
-Many of the bundled provider plugins below already publish a default catalog.
-Use explicit `models.providers.<id>` entries only when you want to override the
-default base URL, headers, or model list.
+Many of the bundled provider plugins below already publish a default catalog. Use explicit `models.providers.<id>` entries only when you want to override the default base URL, headers, or model list.
 
 ### Moonshot AI (Kimi)
 
-Moonshot ships as a bundled provider plugin. Use the built-in provider by
-default, and add an explicit `models.providers.moonshot` entry only when you
-need to override the base URL or model metadata:
+Moonshot ships as a bundled provider plugin. Use the built-in provider by default, and add an explicit `models.providers.moonshot` entry only when you need to override the base URL or model metadata:
 
 - Provider: `moonshot`
 - Auth: `MOONSHOT_API_KEY`
@@ -359,29 +399,26 @@ Volcano Engine (火山引擎) provides access to Doubao and other models in Chin
 }
 ```
 
-Onboarding defaults to the coding surface, but the general `volcengine/*`
-catalog is registered at the same time.
+Onboarding defaults to the coding surface, but the general `volcengine/*` catalog is registered at the same time.
 
-In onboarding/configure model pickers, the Volcengine auth choice prefers both
-`volcengine/*` and `volcengine-plan/*` rows. If those models are not loaded yet,
-OpenClaw falls back to the unfiltered catalog instead of showing an empty
-provider-scoped picker.
+In onboarding/configure model pickers, the Volcengine auth choice prefers both `volcengine/*` and `volcengine-plan/*` rows. If those models are not loaded yet, OpenClaw falls back to the unfiltered catalog instead of showing an empty provider-scoped picker.
 
-Available models:
-
-- `volcengine/doubao-seed-1-8-251228` (Doubao Seed 1.8)
-- `volcengine/doubao-seed-code-preview-251028`
-- `volcengine/kimi-k2-5-260127` (Kimi K2.5)
-- `volcengine/glm-4-7-251222` (GLM 4.7)
-- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
-
-Coding models (`volcengine-plan`):
-
-- `volcengine-plan/ark-code-latest`
-- `volcengine-plan/doubao-seed-code`
-- `volcengine-plan/kimi-k2.5`
-- `volcengine-plan/kimi-k2-thinking`
-- `volcengine-plan/glm-4.7`
+<Tabs>
+  <Tab title="Standard models">
+    - `volcengine/doubao-seed-1-8-251228` (Doubao Seed 1.8)
+    - `volcengine/doubao-seed-code-preview-251028`
+    - `volcengine/kimi-k2-5-260127` (Kimi K2.5)
+    - `volcengine/glm-4-7-251222` (GLM 4.7)
+    - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
+  </Tab>
+  <Tab title="Coding models (volcengine-plan)">
+    - `volcengine-plan/ark-code-latest`
+    - `volcengine-plan/doubao-seed-code`
+    - `volcengine-plan/kimi-k2.5`
+    - `volcengine-plan/kimi-k2-thinking`
+    - `volcengine-plan/glm-4.7`
+  </Tab>
+</Tabs>
 
 ### BytePlus (International)
 
@@ -400,27 +437,24 @@ BytePlus ARK provides access to the same models as Volcano Engine for internatio
 }
 ```
 
-Onboarding defaults to the coding surface, but the general `byteplus/*`
-catalog is registered at the same time.
+Onboarding defaults to the coding surface, but the general `byteplus/*` catalog is registered at the same time.
 
-In onboarding/configure model pickers, the BytePlus auth choice prefers both
-`byteplus/*` and `byteplus-plan/*` rows. If those models are not loaded yet,
-OpenClaw falls back to the unfiltered catalog instead of showing an empty
-provider-scoped picker.
+In onboarding/configure model pickers, the BytePlus auth choice prefers both `byteplus/*` and `byteplus-plan/*` rows. If those models are not loaded yet, OpenClaw falls back to the unfiltered catalog instead of showing an empty provider-scoped picker.
 
-Available models:
-
-- `byteplus/seed-1-8-251228` (Seed 1.8)
-- `byteplus/kimi-k2-5-260127` (Kimi K2.5)
-- `byteplus/glm-4-7-251222` (GLM 4.7)
-
-Coding models (`byteplus-plan`):
-
-- `byteplus-plan/ark-code-latest`
-- `byteplus-plan/doubao-seed-code`
-- `byteplus-plan/kimi-k2.5`
-- `byteplus-plan/kimi-k2-thinking`
-- `byteplus-plan/glm-4.7`
+<Tabs>
+  <Tab title="Standard models">
+    - `byteplus/seed-1-8-251228` (Seed 1.8)
+    - `byteplus/kimi-k2-5-260127` (Kimi K2.5)
+    - `byteplus/glm-4-7-251222` (GLM 4.7)
+  </Tab>
+  <Tab title="Coding models (byteplus-plan)">
+    - `byteplus-plan/ark-code-latest`
+    - `byteplus-plan/doubao-seed-code`
+    - `byteplus-plan/kimi-k2.5`
+    - `byteplus-plan/kimi-k2-thinking`
+    - `byteplus-plan/glm-4.7`
+  </Tab>
+</Tabs>
 
 ### Synthetic
 
@@ -458,14 +492,13 @@ MiniMax is configured via `models.providers` because it uses custom endpoints:
 - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
 - MiniMax API key (Global): `--auth-choice minimax-global-api`
 - MiniMax API key (CN): `--auth-choice minimax-cn-api`
-- Auth: `MINIMAX_API_KEY` for `minimax`; `MINIMAX_OAUTH_TOKEN` or
-  `MINIMAX_API_KEY` for `minimax-portal`
+- Auth: `MINIMAX_API_KEY` for `minimax`; `MINIMAX_OAUTH_TOKEN` or `MINIMAX_API_KEY` for `minimax-portal`
 
 See [/providers/minimax](/providers/minimax) for setup details, model options, and config snippets.
 
-On MiniMax's Anthropic-compatible streaming path, OpenClaw disables thinking by
-default unless you explicitly set it, and `/fast on` rewrites
-`MiniMax-M2.7` to `MiniMax-M2.7-highspeed`.
+<Note>
+On MiniMax's Anthropic-compatible streaming path, OpenClaw disables thinking by default unless you explicitly set it, and `/fast on` rewrites `MiniMax-M2.7` to `MiniMax-M2.7-highspeed`.
+</Note>
 
 Plugin-owned capability split:
 
@@ -492,9 +525,7 @@ Then set a model (replace with one of the IDs returned by `http://localhost:1234
 }
 ```
 
-OpenClaw uses LM Studio's native `/api/v1/models` and `/api/v1/models/load`
-for discovery + auto-load, with `/v1/chat/completions` for inference by default.
-See [/providers/lmstudio](/providers/lmstudio) for setup and troubleshooting.
+OpenClaw uses LM Studio's native `/api/v1/models` and `/api/v1/models/load` for discovery + auto-load, with `/v1/chat/completions` for inference by default. See [/providers/lmstudio](/providers/lmstudio) for setup and troubleshooting.
 
 ### Ollama
 
@@ -518,21 +549,17 @@ ollama pull llama3.3
 }
 ```
 
-Ollama is detected locally at `http://127.0.0.1:11434` when you opt in with
-`OLLAMA_API_KEY`, and the bundled provider plugin adds Ollama directly to
-`openclaw onboard` and the model picker. See [/providers/ollama](/providers/ollama)
-for onboarding, cloud/local mode, and custom configuration.
+Ollama is detected locally at `http://127.0.0.1:11434` when you opt in with `OLLAMA_API_KEY`, and the bundled provider plugin adds Ollama directly to `openclaw onboard` and the model picker. See [/providers/ollama](/providers/ollama) for onboarding, cloud/local mode, and custom configuration.
 
 ### vLLM
 
-vLLM ships as a bundled provider plugin for local/self-hosted OpenAI-compatible
-servers:
+vLLM ships as a bundled provider plugin for local/self-hosted OpenAI-compatible servers:
 
 - Provider: `vllm`
 - Auth: Optional (depends on your server)
 - Default base URL: `http://127.0.0.1:8000/v1`
 
-To opt in to auto-discovery locally (any value works if your server doesn’t enforce auth):
+To opt in to auto-discovery locally (any value works if your server doesn't enforce auth):
 
 ```bash
 export VLLM_API_KEY="vllm-local"
@@ -552,15 +579,13 @@ See [/providers/vllm](/providers/vllm) for details.
 
 ### SGLang
 
-SGLang ships as a bundled provider plugin for fast self-hosted
-OpenAI-compatible servers:
+SGLang ships as a bundled provider plugin for fast self-hosted OpenAI-compatible servers:
 
 - Provider: `sglang`
 - Auth: Optional (depends on your server)
 - Default base URL: `http://127.0.0.1:30000/v1`
 
-To opt in to auto-discovery locally (any value works if your server does not
-enforce auth):
+To opt in to auto-discovery locally (any value works if your server does not enforce auth):
 
 ```bash
 export SGLANG_API_KEY="sglang-local"
@@ -613,26 +638,28 @@ Example (OpenAI‑compatible):
 }
 ```
 
-Notes:
+<AccordionGroup>
+  <Accordion title="Default optional fields">
+    For custom providers, `reasoning`, `input`, `cost`, `contextWindow`, and `maxTokens` are optional. When omitted, OpenClaw defaults to:
 
-- For custom providers, `reasoning`, `input`, `cost`, `contextWindow`, and `maxTokens` are optional.
-  When omitted, OpenClaw defaults to:
-  - `reasoning: false`
-  - `input: ["text"]`
-  - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
-  - `contextWindow: 200000`
-  - `maxTokens: 8192`
-- Recommended: set explicit values that match your proxy/model limits.
-- For `api: "openai-completions"` on non-native endpoints (any non-empty `baseUrl` whose host is not `api.openai.com`), OpenClaw forces `compat.supportsDeveloperRole: false` to avoid provider 400 errors for unsupported `developer` roles.
-- Proxy-style OpenAI-compatible routes also skip native OpenAI-only request
-  shaping: no `service_tier`, no Responses `store`, no Completions `store`, no
-  prompt-cache hints, no OpenAI reasoning-compat payload shaping, and no hidden
-  OpenClaw attribution headers.
-- For OpenAI-compatible Completions proxies that need vendor-specific fields,
-  set `agents.defaults.models["provider/model"].params.extra_body` (or
-  `extraBody`) to merge extra JSON into the outbound request body.
-- If `baseUrl` is empty/omitted, OpenClaw keeps the default OpenAI behavior (which resolves to `api.openai.com`).
-- For safety, an explicit `compat.supportsDeveloperRole: true` is still overridden on non-native `openai-completions` endpoints.
+    - `reasoning: false`
+    - `input: ["text"]`
+    - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
+    - `contextWindow: 200000`
+    - `maxTokens: 8192`
+
+    Recommended: set explicit values that match your proxy/model limits.
+
+  </Accordion>
+  <Accordion title="Proxy-route shaping rules">
+    - For `api: "openai-completions"` on non-native endpoints (any non-empty `baseUrl` whose host is not `api.openai.com`), OpenClaw forces `compat.supportsDeveloperRole: false` to avoid provider 400 errors for unsupported `developer` roles.
+    - Proxy-style OpenAI-compatible routes also skip native OpenAI-only request shaping: no `service_tier`, no Responses `store`, no Completions `store`, no prompt-cache hints, no OpenAI reasoning-compat payload shaping, and no hidden OpenClaw attribution headers.
+    - For OpenAI-compatible Completions proxies that need vendor-specific fields, set `agents.defaults.models["provider/model"].params.extra_body` (or `extraBody`) to merge extra JSON into the outbound request body.
+    - For vLLM chat-template controls, set `agents.defaults.models["provider/model"].params.chat_template_kwargs`. OpenClaw automatically sends `enable_thinking: false` and `force_nonempty_content: true` for `vllm/nemotron-3-*` when the session thinking level is off.
+    - If `baseUrl` is empty/omitted, OpenClaw keeps the default OpenAI behavior (which resolves to `api.openai.com`).
+    - For safety, an explicit `compat.supportsDeveloperRole: true` is still overridden on non-native `openai-completions` endpoints.
+  </Accordion>
+</AccordionGroup>
 
 ## CLI examples
 
@@ -646,7 +673,7 @@ See also: [Configuration](/gateway/configuration) for full configuration example
 
 ## Related
 
-- [Models](/concepts/models) — model configuration and aliases
-- [Model failover](/concepts/model-failover) — fallback chains and retry behavior
 - [Configuration reference](/gateway/config-agents#agent-defaults) — model config keys
+- [Model failover](/concepts/model-failover) — fallback chains and retry behavior
+- [Models](/concepts/models) — model configuration and aliases
 - [Providers](/providers) — per-provider setup guides

docs/concepts/qa-e2e-automation.md

@@ -50,6 +50,21 @@ pnpm qa:lab:watch
 rebuilds that bundle on change, and the browser auto-reloads when the QA Lab
 asset hash changes.
 
+For a local OpenTelemetry trace smoke, run:
+
+```bash
+pnpm qa:otel:smoke
+```
+
+That script starts a local OTLP/HTTP trace receiver, runs the
+`otel-trace-smoke` QA scenario with the `diagnostics-otel` plugin enabled, then
+decodes the exported protobuf spans and asserts the release-critical shape:
+`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
+`openclaw.context.assembled`, and `openclaw.message.delivery` must be present;
+model calls must not export `StreamAbandoned` on successful turns; raw diagnostic IDs and
+`openclaw.content.*` attributes must stay out of the trace. It writes
+`otel-smoke-summary.json` next to the QA suite artifacts.
+
 For a transport-real Matrix smoke lane, run:
 
 ```bash

docs/concepts/session-pruning.md

@@ -35,15 +35,23 @@ cache-write size, directly lowering cost.
 
 ## Legacy image cleanup
 
-OpenClaw also runs a separate idempotent cleanup for older legacy sessions that
-persisted raw image blocks in history.
+OpenClaw also builds a separate idempotent replay view for sessions that
+persist raw image blocks or prompt-hydration media markers in history.
 
 - It preserves the **3 most recent completed turns** byte-for-byte so prompt
   cache prefixes for recent follow-ups stay stable.
-- Older already-processed image blocks in `user` or `toolResult` history can be
-  replaced with `[image data removed - already processed by model]`.
+- In the replay view, older already-processed image blocks from `user` or
+  `toolResult` history can be replaced with
+  `[image data removed - already processed by model]`.
+- Older textual media references such as `[media attached: ...]`,
+  `[Image: source: ...]`, and `media://inbound/...` can be replaced with
+  `[media reference removed - already processed by model]`. Current-turn
+  attachment markers stay intact so vision models can still hydrate fresh
+  images.
+- The raw session transcript is not rewritten, so history viewers can still
+  render the original message entries and their images.
 - This is separate from normal cache-TTL pruning. It exists to stop repeated
-  image payloads from busting prompt caches on later turns.
+  image payloads or stale media refs from busting prompt caches on later turns.
 
 ## Smart defaults
 

docs/concepts/session.md

@@ -71,7 +71,10 @@ Sessions are reused until they expire:
 
 When both daily and idle resets are configured, whichever expires first wins.
 Heartbeat, cron, exec, and other system-event turns may write session metadata,
-but those writes do not extend daily or idle reset freshness.
+but those writes do not extend daily or idle reset freshness. When a reset
+rolls the session, queued system-event notices for the old session are
+discarded so stale background updates are not prepended to the first prompt in
+the new session.
 
 Sessions with an active provider-owned CLI session are not cut by the implicit
 daily default. Use `/reset` or configure `session.reset` explicitly when those

docs/concepts/system-prompt.md

@@ -214,6 +214,10 @@ stale. The prompt also notes the public docs mirror, community Discord, and Claw
 ([https://clawhub.ai](https://clawhub.ai)) for skills discovery. It tells the model to
 consult docs first for OpenClaw behavior, commands, configuration, or architecture, and to
 run `openclaw status` itself when possible (asking the user only when it lacks access).
+For configuration specifically, it points agents to the `gateway` tool action
+`config.schema.lookup` for exact field-level docs and constraints, then to
+`docs/gateway/configuration.md` and `docs/gateway/configuration-reference.md`
+for broader guidance.
 
 ## Related
 

docs/docs.json

@@ -1238,6 +1238,7 @@
                   "tools/tokenjuice",
                   "tools/loop-detection",
                   "tools/trajectory",
+                  "tools/tts",
                   "tools/video-generation",
                   {
                     "group": "Web browser",

docs/gateway/bonjour.md

@@ -152,6 +152,85 @@ To capture logs:
 
 The log includes browser state transitions and result‑set changes.
 
+## When to disable Bonjour
+
+Disable Bonjour only when LAN multicast advertising is unavailable or harmful.
+The common case is a Gateway running behind Docker bridge networking, WSL, or a
+network policy that drops mDNS multicast. In those environments the Gateway is
+still reachable through its published URL, SSH, Tailnet, or wide-area DNS-SD,
+but LAN auto-discovery is not reliable.
+
+Prefer the existing environment override when the problem is deployment-scoped:
+
+```bash
+OPENCLAW_DISABLE_BONJOUR=1
+```
+
+That disables LAN multicast advertising without changing plugin configuration.
+It is safe for Docker images, service files, launch scripts, and one-off
+debugging because the setting disappears when the environment does.
+
+Use plugin configuration only when you intentionally want to turn off the
+bundled LAN discovery plugin for that OpenClaw config:
+
+```bash
+openclaw plugins disable bonjour
+```
+
+## Docker gotchas
+
+Bundled Docker Compose sets `OPENCLAW_DISABLE_BONJOUR=1` for the Gateway service
+by default. Docker bridge networks usually do not forward mDNS multicast
+(`224.0.0.251:5353`) between the container and the LAN, so leaving Bonjour on can
+produce repeated ciao `probing` or `announcing` failures without making discovery
+work.
+
+Important gotchas:
+
+- Disabling Bonjour does not stop the Gateway. It only stops LAN multicast
+  advertising.
+- Disabling Bonjour does not change `gateway.bind`; Docker still defaults to
+  `OPENCLAW_GATEWAY_BIND=lan` so the published host port can work.
+- Disabling Bonjour does not disable wide-area DNS-SD. Use wide-area discovery
+  or Tailnet when the Gateway and node are not on the same LAN.
+- Reusing the same `OPENCLAW_CONFIG_DIR` outside Docker does not inherit the
+  Compose default unless the environment still sets `OPENCLAW_DISABLE_BONJOUR`.
+- Set `OPENCLAW_DISABLE_BONJOUR=0` only for host networking, macvlan, or another
+  network where mDNS multicast is known to pass.
+
+## Troubleshooting disabled Bonjour
+
+If a node no longer auto-discovers the Gateway after Docker setup:
+
+1. Confirm whether the Gateway is intentionally suppressing LAN advertising:
+
+   ```bash
+   docker compose config | grep OPENCLAW_DISABLE_BONJOUR
+   ```
+
+2. Confirm the Gateway itself is reachable through the published port:
+
+   ```bash
+   curl -fsS http://127.0.0.1:18789/healthz
+   ```
+
+3. Use a direct target when Bonjour is disabled:
+   - Control UI or local tools: `http://127.0.0.1:18789`
+   - LAN clients: `http://<gateway-host>:18789`
+   - Cross-network clients: Tailnet MagicDNS, Tailnet IP, SSH tunnel, or
+     wide-area DNS-SD
+
+4. If you deliberately enabled Bonjour in Docker with
+   `OPENCLAW_DISABLE_BONJOUR=0`, test multicast from the host:
+
+   ```bash
+   dns-sd -B _openclaw-gw._tcp local.
+   ```
+
+   If browsing is empty or the Gateway logs show repeated ciao watchdog
+   cancellations, restore `OPENCLAW_DISABLE_BONJOUR=1` and use a direct or
+   Tailnet route.
+
 ## Common failure modes
 
 - **Bonjour doesn’t cross networks**: use Tailnet or SSH.
@@ -160,6 +239,9 @@ The log includes browser state transitions and result‑set changes.
   container bridges, WSL, or interface churn can leave the ciao advertiser in a
   non-announced state. OpenClaw retries a few times and then disables Bonjour
   for the current Gateway process instead of restarting the advertiser forever.
+- **Docker bridge networking**: bundled Docker Compose disables Bonjour by
+  default with `OPENCLAW_DISABLE_BONJOUR=1`. Set it to `0` only for host,
+  macvlan, or another mDNS-capable network.
 - **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
 - **Browse works but resolve fails**: keep machine names simple (avoid emojis or
   punctuation), then restart the Gateway. The service instance name derives from
@@ -178,6 +260,7 @@ sequences (e.g. spaces become `\032`).
 - `openclaw plugins disable bonjour` disables LAN multicast advertising by disabling the bundled plugin.
 - `openclaw plugins enable bonjour` restores the default LAN discovery plugin.
 - `OPENCLAW_DISABLE_BONJOUR=1` disables LAN multicast advertising without changing plugin config; accepted truthy values are `1`, `true`, `yes`, and `on` (legacy: `OPENCLAW_DISABLE_BONJOUR`).
+- Docker Compose sets `OPENCLAW_DISABLE_BONJOUR=1` by default for bridge networking; override with `OPENCLAW_DISABLE_BONJOUR=0` only when mDNS multicast is available.
 - `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
 - `OPENCLAW_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `OPENCLAW_SSH_PORT`).
 - `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT when mDNS full mode is enabled (legacy: `OPENCLAW_TAILNET_DNS`).

docs/gateway/config-agents.md

@@ -364,13 +364,15 @@ Time format in system prompt. Default: `auto` (OS preference).
 - `verboseDefault`: default verbose level for agents. Values: `"off"`, `"on"`, `"full"`. Default: `"off"`.
 - `elevatedDefault`: default elevated-output level for agents. Values: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`.
 - `model.primary`: format `provider/model` (e.g. `openai/gpt-5.5` for API-key access or `openai-codex/gpt-5.5` for Codex OAuth). If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider (deprecated compatibility behavior, so prefer explicit `provider/model`). If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.
-- `models`: the configured model catalog and allowlist for `/model`. Each entry can include `alias` (shortcut) and `params` (provider-specific, for example `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `extra_body`/`extraBody`).
+- `models`: the configured model catalog and allowlist for `/model`. Each entry can include `alias` (shortcut) and `params` (provider-specific, for example `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
   - Safe edits: use `openclaw config set agents.defaults.models '<json>' --strict-json --merge` to add entries. `config set` refuses replacements that would remove existing allowlist entries unless you pass `--replace`.
   - Provider-scoped configure/onboarding flows merge selected provider models into this map and preserve unrelated providers already configured.
   - For direct OpenAI Responses models, server-side compaction is enabled automatically. Use `params.responsesServerCompaction: false` to stop injecting `context_management`, or `params.responsesCompactThreshold` to override the threshold. See [OpenAI server-side compaction](/providers/openai#server-side-compaction-responses-api).
 - `params`: global default provider parameters applied to all models. Set at `agents.defaults.params` (e.g. `{ cacheRetention: "long" }`).
 - `params` merge precedence (config): `agents.defaults.params` (global base) is overridden by `agents.defaults.models["provider/model"].params` (per-model), then `agents.list[].params` (matching agent id) overrides by key. See [Prompt Caching](/reference/prompt-caching) for details.
 - `params.extra_body`/`params.extraBody`: advanced pass-through JSON merged into `api: "openai-completions"` request bodies for OpenAI-compatible proxies. If it collides with generated request keys, the extra body wins; non-native completions routes still strip OpenAI-only `store` afterward.
+- `params.chat_template_kwargs`: vLLM/OpenAI-compatible chat-template arguments merged into top-level `api: "openai-completions"` request bodies. For `vllm/nemotron-3-*` with thinking off, OpenClaw automatically sends `enable_thinking: false` and `force_nonempty_content: true`; explicit `chat_template_kwargs` override those defaults, and `extra_body.chat_template_kwargs` still has final precedence.
+- `params.preserveThinking`: Z.AI-only opt-in for preserved thinking. When enabled and thinking is on, OpenClaw sends `thinking.clear_thinking: false` and replays prior `reasoning_content`; see [Z.AI thinking and preserved thinking](/providers/zai#thinking-and-preserved-thinking).
 - `embeddedHarness`: default low-level embedded agent runtime policy. Omitted runtime defaults to OpenClaw Pi. Use `runtime: "pi"` to force the built-in PI harness, `runtime: "auto"` to let registered plugin harnesses claim supported models, or a registered harness id such as `runtime: "codex"`. Set `fallback: "none"` to disable automatic PI fallback. Explicit plugin runtimes such as `codex` fail closed by default unless you set `fallback: "pi"` in the same override scope. Keep model refs canonical as `provider/model`; select Codex, Claude CLI, Gemini CLI, and other execution backends through runtime config instead of legacy runtime provider prefixes. See [Agent runtimes](/concepts/agent-runtimes) for how this differs from provider/model selection.
 - Config writers that mutate these fields (for example `/models set`, `/models set-image`, and fallback add/remove commands) save canonical object form and preserve existing fallback lists when possible.
 - `maxConcurrent`: max parallel agent runs across sessions (each session still serialized). Default: 4.
@@ -899,6 +901,14 @@ scripts/sandbox-browser-setup.sh   # optional browser image
 
 ### `agents.list` (per-agent overrides)
 
+Use `agents.list[].tts` to give an agent its own TTS provider, voice, model,
+style, or auto-TTS mode. The agent block deep-merges over global
+`messages.tts`, so shared credentials can stay in one place while individual
+agents override only the voice or provider fields they need. The active agent's
+override applies to automatic spoken replies, `/tts audio`, `/tts status`, and
+the `tts` agent tool. See [Text-to-speech](/tools/tts#per-agent-voice-overrides)
+for provider examples and precedence.
+
 ```json5
 {
   agents: {
@@ -915,6 +925,11 @@ scripts/sandbox-browser-setup.sh   # optional browser image
         fastModeDefault: false, // per-agent fast mode override
         embeddedHarness: { runtime: "auto", fallback: "pi" },
         params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
+        tts: {
+          providers: {
+            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
+          },
+        },
         skills: ["docs-search"], // replaces agents.defaults.skills when set
         identity: {
           name: "Samantha",
@@ -950,6 +965,7 @@ scripts/sandbox-browser-setup.sh   # optional browser image
 - `default`: when multiple are set, first wins (warning logged). If none set, first list entry is default.
 - `model`: string form overrides `primary` only; object form `{ primary, fallbacks }` overrides both (`[]` disables global fallbacks). Cron jobs that only override `primary` still inherit default fallbacks unless you set `fallbacks: []`.
 - `params`: per-agent stream params merged over the selected model entry in `agents.defaults.models`. Use this for agent-specific overrides like `cacheRetention`, `temperature`, or `maxTokens` without duplicating the whole model catalog.
+- `tts`: optional per-agent text-to-speech overrides. The block deep-merges over `messages.tts`, so keep shared provider credentials and fallback policy in `messages.tts` and set only persona-specific values such as provider, voice, model, style, or auto mode here.
 - `skills`: optional per-agent skill allowlist. If omitted, the agent inherits `agents.defaults.skills` when set; an explicit list replaces defaults instead of merging, and `[]` means no skills.
 - `thinkingDefault`: optional per-agent default thinking level (`off | minimal | low | medium | high | xhigh | adaptive | max`). Overrides `agents.defaults.thinkingDefault` for this agent when no per-message or session override is set. The selected provider/model profile controls which values are valid; for Google Gemini, `adaptive` keeps provider-owned dynamic thinking (`thinkingLevel` omitted on Gemini 3/3.1, `thinkingBudget: -1` on Gemini 2.5).
 - `reasoningDefault`: optional per-agent default reasoning visibility (`on | off | stream`). Applies when no per-message or session reasoning override is set.
@@ -1241,7 +1257,7 @@ Variables are case-insensitive. `{think}` is an alias for `{thinkingLevel}`.
 - Per-channel overrides: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
 - Resolution order: account → channel → `messages.ackReaction` → identity fallback.
 - Scope: `group-mentions` (default), `group-all`, `direct`, `all`.
-- `removeAckAfterReply`: removes ack after reply on Slack, Discord, and Telegram.
+- `removeAckAfterReply`: removes ack after reply on reaction-capable channels such as Slack, Discord, Telegram, WhatsApp, and BlueBubbles.
 - `messages.statusReactions.enabled`: enables lifecycle status reactions on Slack, Discord, and Telegram.
   On Slack and Discord, unset keeps status reactions enabled when ack reactions are active.
   On Telegram, set it explicitly to `true` to enable lifecycle status reactions.

docs/gateway/configuration-reference.md

@@ -16,6 +16,11 @@ Code truth:
 - `config.schema.lookup` returns one path-scoped schema node for drill-down tooling
 - `pnpm config:docs:check` / `pnpm config:docs:gen` validate the config-doc baseline hash against the current schema surface
 
+Agent lookup path: use the `gateway` tool action `config.schema.lookup` for
+exact field-level docs and constraints before edits. Use
+[Configuration](/gateway/configuration) for task-oriented guidance and this page
+for the broader field map, defaults, and links to subsystem references.
+
 Dedicated deep references:
 
 - [Memory configuration reference](/reference/memory-config) for `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, and dreaming config under `plugins.entries.memory-core.config.dreaming`
@@ -853,7 +858,7 @@ Notes:
 - Default log file: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
 - Set `logging.file` for a stable path.
 - `consoleLevel` bumps to `debug` when `--verbose`.
-- `maxFileBytes`: maximum log file size in bytes before writes are suppressed (positive integer; default: `524288000` = 500 MB). Use external log rotation for production deployments.
+- `maxFileBytes`: maximum active log file size in bytes before rotation (positive integer; default: `104857600` = 100 MB). OpenClaw keeps up to five numbered archives beside the active file.
 
 ---
 

docs/gateway/configuration.md

@@ -21,6 +21,11 @@ If the file is missing, OpenClaw uses safe defaults. Common reasons to add a con
 
 See the [full reference](/gateway/configuration-reference) for every available field.
 
+Agents and automation should use `config.schema.lookup` for exact field-level
+docs before editing config. Use this page for task-oriented guidance and
+[Configuration reference](/gateway/configuration-reference) for the broader
+field map and defaults.
+
 <Tip>
 **New to configuration?** Start with `openclaw onboard` for interactive setup, or check out the [Configuration Examples](/gateway/configuration-examples) guide for complete copy-paste configs.
 </Tip>
@@ -575,6 +580,11 @@ For tooling that writes config over the gateway API, prefer this flow:
 - `config.apply` only when you intend to replace the entire config
 - `update.run` for explicit self-update plus restart
 
+Agents should treat `config.schema.lookup` as the first stop for exact
+field-level docs and constraints. Use [Configuration reference](/gateway/configuration-reference)
+when they need the broader config map, defaults, or links to dedicated
+subsystem references.
+
 <Note>
 Control-plane writes (`config.apply`, `config.patch`, `update.run`) are
 rate-limited to 3 requests per 60 seconds per `deviceId+clientIp`. Restart

docs/gateway/discovery.md

@@ -86,6 +86,9 @@ Security notes:
 Disable/override:
 
 - `OPENCLAW_DISABLE_BONJOUR=1` disables advertising.
+- Docker Compose defaults `OPENCLAW_DISABLE_BONJOUR=1` because bridge networks
+  usually do not carry mDNS multicast reliably; use `0` only on host, macvlan,
+  or another mDNS-capable network.
 - `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
 - `OPENCLAW_SSH_PORT` overrides the SSH port advertised when `sshPort` is emitted.
 - `OPENCLAW_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).

docs/gateway/doctor.md

@@ -4,10 +4,10 @@ read_when:
   - Adding or modifying doctor migrations
   - Introducing breaking config changes
 title: "Doctor"
+sidebarTitle: "Doctor"
 ---
 
-`openclaw doctor` is the repair + migration tool for OpenClaw. It fixes stale
-config/state, checks health, and provides actionable repair steps.
+`openclaw doctor` is the repair + migration tool for OpenClaw. It fixes stale config/state, checks health, and provides actionable repair steps.
 
 ## Quick start
 
@@ -15,38 +15,50 @@ config/state, checks health, and provides actionable repair steps.
 openclaw doctor
 ```
 
-### Headless / automation
+### Headless and automation modes
 
-```bash
-openclaw doctor --yes
-```
+<Tabs>
+  <Tab title="--yes">
+    ```bash
+    openclaw doctor --yes
+    ```
 
-Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
+    Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
 
-```bash
-openclaw doctor --repair
-```
+  </Tab>
+  <Tab title="--repair">
+    ```bash
+    openclaw doctor --repair
+    ```
 
-Apply recommended repairs without prompting (repairs + restarts where safe).
+    Apply recommended repairs without prompting (repairs + restarts where safe).
 
-```bash
-openclaw doctor --repair --force
-```
+  </Tab>
+  <Tab title="--repair --force">
+    ```bash
+    openclaw doctor --repair --force
+    ```
 
-Apply aggressive repairs too (overwrites custom supervisor configs).
+    Apply aggressive repairs too (overwrites custom supervisor configs).
 
-```bash
-openclaw doctor --non-interactive
-```
+  </Tab>
+  <Tab title="--non-interactive">
+    ```bash
+    openclaw doctor --non-interactive
+    ```
 
-Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.
-Legacy state migrations run automatically when detected.
+    Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation. Legacy state migrations run automatically when detected.
 
-```bash
-openclaw doctor --deep
-```
+  </Tab>
+  <Tab title="--deep">
+    ```bash
+    openclaw doctor --deep
+    ```
 
-Scan system services for extra gateway installs (launchd/systemd/schtasks).
+    Scan system services for extra gateway installs (launchd/systemd/schtasks).
+
+  </Tab>
+</Tabs>
 
 If you want to review changes before writing, open the config file first:
 
@@ -56,543 +68,393 @@ cat ~/.openclaw/openclaw.json
 
 ## What it does (summary)
 
-- Optional pre-flight update for git installs (interactive only).
-- UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
-- Health check + restart prompt.
-- Skills status summary (eligible/missing/blocked) and plugin status.
-- Config normalization for legacy values.
-- Talk config migration from legacy flat `talk.*` fields into `talk.provider` + `talk.providers.<provider>`.
-- Browser migration checks for legacy Chrome extension configs and Chrome MCP readiness.
-- OpenCode provider override warnings (`models.providers.opencode` / `models.providers.opencode-go`).
-- Codex OAuth shadowing warnings (`models.providers.openai-codex`).
-- OAuth TLS prerequisites check for OpenAI Codex OAuth profiles.
-- Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
-- Legacy plugin manifest contract key migration (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
-- Legacy cron store migration (`jobId`, `schedule.cron`, top-level delivery/payload fields, payload `provider`, simple `notify: true` webhook fallback jobs).
-- Session lock file inspection and stale lock cleanup.
-- Session transcript repair for duplicated prompt-rewrite branches created by affected 2026.4.24 builds.
-- State integrity and permissions checks (sessions, transcripts, state dir).
-- Config file permission checks (chmod 600) when running locally.
-- Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
-- Extra workspace dir detection (`~/openclaw`).
-- Sandbox image repair when sandboxing is enabled.
-- Legacy service migration and extra gateway detection.
-- Matrix channel legacy state migration (in `--fix` / `--repair` mode).
-- Gateway runtime checks (service installed but not running; cached launchd label).
-- Channel status warnings (probed from the running gateway).
-- Supervisor config audit (launchd/systemd/schtasks) with optional repair.
-- Gateway runtime best-practice checks (Node vs Bun, version-manager paths).
-- Gateway port collision diagnostics (default `18789`).
-- Security warnings for open DM policies.
-- Gateway auth checks for local token mode (offers token generation when no token source exists; does not overwrite token SecretRef configs).
-- Device pairing trouble detection (pending first-time pair requests, pending role/scope upgrades, stale local device-token cache drift, and paired-record auth drift).
-- systemd linger check on Linux.
-- Workspace bootstrap file size check (truncation/near-limit warnings for context files).
-- Shell completion status check and auto-install/upgrade.
-- Memory search embedding provider readiness check (local model, remote API key, or QMD binary).
-- Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).
-- Writes updated config + wizard metadata.
+<AccordionGroup>
+  <Accordion title="Health, UI, and updates">
+    - Optional pre-flight update for git installs (interactive only).
+    - UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
+    - Health check + restart prompt.
+    - Skills status summary (eligible/missing/blocked) and plugin status.
+  </Accordion>
+  <Accordion title="Config and migrations">
+    - Config normalization for legacy values.
+    - Talk config migration from legacy flat `talk.*` fields into `talk.provider` + `talk.providers.<provider>`.
+    - Browser migration checks for legacy Chrome extension configs and Chrome MCP readiness.
+    - OpenCode provider override warnings (`models.providers.opencode` / `models.providers.opencode-go`).
+    - Codex OAuth shadowing warnings (`models.providers.openai-codex`).
+    - OAuth TLS prerequisites check for OpenAI Codex OAuth profiles.
+    - Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
+    - Legacy plugin manifest contract key migration (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
+    - Legacy cron store migration (`jobId`, `schedule.cron`, top-level delivery/payload fields, payload `provider`, simple `notify: true` webhook fallback jobs).
+  </Accordion>
+  <Accordion title="State and integrity">
+    - Session lock file inspection and stale lock cleanup.
+    - Session transcript repair for duplicated prompt-rewrite branches created by affected 2026.4.24 builds.
+    - State integrity and permissions checks (sessions, transcripts, state dir).
+    - Config file permission checks (chmod 600) when running locally.
+    - Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
+    - Extra workspace dir detection (`~/openclaw`).
+  </Accordion>
+  <Accordion title="Gateway, services, and supervisors">
+    - Sandbox image repair when sandboxing is enabled.
+    - Legacy service migration and extra gateway detection.
+    - Matrix channel legacy state migration (in `--fix` / `--repair` mode).
+    - Gateway runtime checks (service installed but not running; cached launchd label).
+    - Channel status warnings (probed from the running gateway).
+    - Supervisor config audit (launchd/systemd/schtasks) with optional repair.
+    - Gateway runtime best-practice checks (Node vs Bun, version-manager paths).
+    - Gateway port collision diagnostics (default `18789`).
+  </Accordion>
+  <Accordion title="Auth, security, and pairing">
+    - Security warnings for open DM policies.
+    - Gateway auth checks for local token mode (offers token generation when no token source exists; does not overwrite token SecretRef configs).
+    - Device pairing trouble detection (pending first-time pair requests, pending role/scope upgrades, stale local device-token cache drift, and paired-record auth drift).
+  </Accordion>
+  <Accordion title="Workspace and shell">
+    - systemd linger check on Linux.
+    - Workspace bootstrap file size check (truncation/near-limit warnings for context files).
+    - Shell completion status check and auto-install/upgrade.
+    - Memory search embedding provider readiness check (local model, remote API key, or QMD binary).
+    - Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).
+    - Writes updated config + wizard metadata.
+  </Accordion>
+</AccordionGroup>
 
 ## Dreams UI backfill and reset
 
-The Control UI Dreams scene includes **Backfill**, **Reset**, and **Clear Grounded**
-actions for the grounded dreaming workflow. These actions use gateway
-doctor-style RPC methods, but they are **not** part of `openclaw doctor` CLI
-repair/migration.
+The Control UI Dreams scene includes **Backfill**, **Reset**, and **Clear Grounded** actions for the grounded dreaming workflow. These actions use gateway doctor-style RPC methods, but they are **not** part of `openclaw doctor` CLI repair/migration.
 
 What they do:
 
-- **Backfill** scans historical `memory/YYYY-MM-DD.md` files in the active
-  workspace, runs the grounded REM diary pass, and writes reversible backfill
-  entries into `DREAMS.md`.
+- **Backfill** scans historical `memory/YYYY-MM-DD.md` files in the active workspace, runs the grounded REM diary pass, and writes reversible backfill entries into `DREAMS.md`.
 - **Reset** removes only those marked backfill diary entries from `DREAMS.md`.
-- **Clear Grounded** removes only staged grounded-only short-term entries that
-  came from historical replay and have not accumulated live recall or daily
-  support yet.
+- **Clear Grounded** removes only staged grounded-only short-term entries that came from historical replay and have not accumulated live recall or daily support yet.
 
 What they do **not** do by themselves:
 
 - they do not edit `MEMORY.md`
 - they do not run full doctor migrations
-- they do not automatically stage grounded candidates into the live short-term
-  promotion store unless you explicitly run the staged CLI path first
+- they do not automatically stage grounded candidates into the live short-term promotion store unless you explicitly run the staged CLI path first
 
-If you want grounded historical replay to influence the normal deep promotion
-lane, use the CLI flow instead:
+If you want grounded historical replay to influence the normal deep promotion lane, use the CLI flow instead:
 
 ```bash
 openclaw memory rem-backfill --path ./memory --stage-short-term
 ```
 
-That stages grounded durable candidates into the short-term dreaming store while
-keeping `DREAMS.md` as the review surface.
+That stages grounded durable candidates into the short-term dreaming store while keeping `DREAMS.md` as the review surface.
 
 ## Detailed behavior and rationale
 
-### 0) Optional update (git installs)
-
-If this is a git checkout and doctor is running interactively, it offers to
-update (fetch/rebase/build) before running doctor.
-
-### 1) Config normalization
-
-If the config contains legacy value shapes (for example `messages.ackReaction`
-without a channel-specific override), doctor normalizes them into the current
-schema.
-
-That includes legacy Talk flat fields. Current public Talk config is
-`talk.provider` + `talk.providers.<provider>`. Doctor rewrites old
-`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
-`talk.apiKey` shapes into the provider map.
-
-### 2) Legacy config key migrations
-
-When the config contains deprecated keys, other commands refuse to run and ask
-you to run `openclaw doctor`.
-
-Doctor will:
-
-- Explain which legacy keys were found.
-- Show the migration it applied.
-- Rewrite `~/.openclaw/openclaw.json` with the updated schema.
-
-The Gateway also auto-runs doctor migrations on startup when it detects a
-legacy config format, so stale configs are repaired without manual intervention.
-Cron job store migrations are handled by `openclaw doctor --fix`.
-
-Current migrations:
-
-- `routing.allowFrom` → `channels.whatsapp.allowFrom`
-- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
-- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
-- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
-- `routing.queue` → `messages.queue`
-- `routing.bindings` → top-level `bindings`
-- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
-- legacy `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
-- `routing.agentToAgent` → `tools.agentToAgent`
-- `routing.transcribeAudio` → `tools.media.audio.models`
-- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
-- `messages.tts.provider: "edge"` and `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` and `messages.tts.providers.microsoft`
-- `channels.discord.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.<provider>`
-- `channels.discord.accounts.<id>.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
-- `plugins.entries.voice-call.config.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.<provider>`
-- `plugins.entries.voice-call.config.tts.provider: "edge"` and `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` and `providers.microsoft`
-- `plugins.entries.voice-call.config.provider: "log"` → `"mock"`
-- `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber`
-- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
-- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
-  → `plugins.entries.voice-call.config.streaming.providers.openai.*`
-- `bindings[].match.accountID` → `bindings[].match.accountId`
-- For channels with named `accounts` but lingering single-account top-level channel values, move those account-scoped values into the promoted account chosen for that channel (`accounts.default` for most channels; Matrix can preserve an existing matching named/default target)
-- `identity` → `agents.list[].identity`
-- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
-- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
-  → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
-- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
-- `browser.profiles.*.driver: "extension"` → `"existing-session"`
-- remove `browser.relayBindHost` (legacy extension relay setting)
-
-Doctor warnings also include account-default guidance for multi-account channels:
-
-- If two or more `channels.<channel>.accounts` entries are configured without `channels.<channel>.defaultAccount` or `accounts.default`, doctor warns that fallback routing can pick an unexpected account.
-- If `channels.<channel>.defaultAccount` is set to an unknown account ID, doctor warns and lists configured account IDs.
-
-### 2b) OpenCode provider overrides
-
-If you’ve added `models.providers.opencode`, `opencode-zen`, or `opencode-go`
-manually, it overrides the built-in OpenCode catalog from `@mariozechner/pi-ai`.
-That can force models onto the wrong API or zero out costs. Doctor warns so you
-can remove the override and restore per-model API routing + costs.
-
-### 2c) Browser migration and Chrome MCP readiness
-
-If your browser config still points at the removed Chrome extension path, doctor
-normalizes it to the current host-local Chrome MCP attach model:
-
-- `browser.profiles.*.driver: "extension"` becomes `"existing-session"`
-- `browser.relayBindHost` is removed
-
-Doctor also audits the host-local Chrome MCP path when you use `defaultProfile:
-"user"` or a configured `existing-session` profile:
-
-- checks whether Google Chrome is installed on the same host for default
-  auto-connect profiles
-- checks the detected Chrome version and warns when it is below Chrome 144
-- reminds you to enable remote debugging in the browser inspect page (for
-  example `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
-  or `edge://inspect/#remote-debugging`)
-
-Doctor cannot enable the Chrome-side setting for you. Host-local Chrome MCP
-still requires:
-
-- a Chromium-based browser 144+ on the gateway/node host
-- the browser running locally
-- remote debugging enabled in that browser
-- approving the first attach consent prompt in the browser
-
-Readiness here is only about local attach prerequisites. Existing-session keeps
-the current Chrome MCP route limits; advanced routes like `responsebody`, PDF
-export, download interception, and batch actions still require a managed
-browser or raw CDP profile.
-
-This check does **not** apply to Docker, sandbox, remote-browser, or other
-headless flows. Those continue to use raw CDP.
-
-### 2d) OAuth TLS prerequisites
-
-When an OpenAI Codex OAuth profile is configured, doctor probes the OpenAI
-authorization endpoint to verify that the local Node/OpenSSL TLS stack can
-validate the certificate chain. If the probe fails with a certificate error (for
-example `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, expired cert, or self-signed cert),
-doctor prints platform-specific fix guidance. On macOS with a Homebrew Node, the
-fix is usually `brew postinstall ca-certificates`. With `--deep`, the probe runs
-even if the gateway is healthy.
-
-### 2c) Codex OAuth provider overrides
-
-If you previously added legacy OpenAI transport settings under
-`models.providers.openai-codex`, they can shadow the built-in Codex OAuth
-provider path that newer releases use automatically. Doctor warns when it sees
-those old transport settings alongside Codex OAuth so you can remove or rewrite
-the stale transport override and get the built-in routing/fallback behavior
-back. Custom proxies and header-only overrides are still supported and do not
-trigger this warning.
-
-### 3) Legacy state migrations (disk layout)
-
-Doctor can migrate older on-disk layouts into the current structure:
-
-- Sessions store + transcripts:
-  - from `~/.openclaw/sessions/` to `~/.openclaw/agents/<agentId>/sessions/`
-- Agent dir:
-  - from `~/.openclaw/agent/` to `~/.openclaw/agents/<agentId>/agent/`
-- WhatsApp auth state (Baileys):
-  - from legacy `~/.openclaw/credentials/*.json` (except `oauth.json`)
-  - to `~/.openclaw/credentials/whatsapp/<accountId>/...` (default account id: `default`)
-
-These migrations are best-effort and idempotent; doctor will emit warnings when
-it leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates
-the legacy sessions + agent dir on startup so history/auth/models land in the
-per-agent path without a manual doctor run. WhatsApp auth is intentionally only
-migrated via `openclaw doctor`. Talk provider/provider-map normalization now
-compares by structural equality, so key-order-only diffs no longer trigger
-repeat no-op `doctor --fix` changes.
-
-### 3a) Legacy plugin manifest migrations
-
-Doctor scans all installed plugin manifests for deprecated top-level capability
-keys (`speechProviders`, `realtimeTranscriptionProviders`,
-`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
-`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
-`webSearchProviders`). When found, it offers to move them into the `contracts`
-object and rewrite the manifest file in-place. This migration is idempotent;
-if the `contracts` key already has the same values, the legacy key is removed
-without duplicating the data.
-
-### 3b) Legacy cron store migrations
-
-Doctor also checks the cron job store (`~/.openclaw/cron/jobs.json` by default,
-or `cron.store` when overridden) for old job shapes that the scheduler still
-accepts for compatibility.
-
-Current cron cleanups include:
-
-- `jobId` → `id`
-- `schedule.cron` → `schedule.expr`
-- top-level payload fields (`message`, `model`, `thinking`, ...) → `payload`
-- top-level delivery fields (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
-- payload `provider` delivery aliases → explicit `delivery.channel`
-- simple legacy `notify: true` webhook fallback jobs → explicit `delivery.mode="webhook"` with `delivery.to=cron.webhook`
-
-Doctor only auto-migrates `notify: true` jobs when it can do so without
-changing behavior. If a job combines legacy notify fallback with an existing
-non-webhook delivery mode, doctor warns and leaves that job for manual review.
-
-### 3c) Session lock cleanup
-
-Doctor scans every agent session directory for stale write-lock files — files left
-behind when a session exited abnormally. For each lock file found it reports:
-the path, PID, whether the PID is still alive, lock age, and whether it is
-considered stale (dead PID or older than 30 minutes). In `--fix` / `--repair`
-mode it removes stale lock files automatically; otherwise it prints a note and
-instructs you to rerun with `--fix`.
-
-### 3d) Session transcript branch repair
-
-Doctor scans agent session JSONL files for the duplicated branch shape created
-by the 2026.4.24 prompt transcript rewrite bug: an abandoned user turn with
-OpenClaw internal runtime context plus an active sibling containing the same
-visible user prompt. In `--fix` / `--repair` mode, doctor backs up each affected
-file next to the original and rewrites the transcript to the active branch so
-gateway history and memory readers no longer see duplicate turns.
-
-### 4) State integrity checks (session persistence, routing, and safety)
-
-The state directory is the operational brainstem. If it vanishes, you lose
-sessions, credentials, logs, and config (unless you have backups elsewhere).
-
-Doctor checks:
-
-- **State dir missing**: warns about catastrophic state loss, prompts to recreate
-  the directory, and reminds you that it cannot recover missing data.
-- **State dir permissions**: verifies writability; offers to repair permissions
-  (and emits a `chown` hint when owner/group mismatch is detected).
-- **macOS cloud-synced state dir**: warns when state resolves under iCloud Drive
-  (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) or
-  `~/Library/CloudStorage/...` because sync-backed paths can cause slower I/O
-  and lock/sync races.
-- **Linux SD or eMMC state dir**: warns when state resolves to an `mmcblk*`
-  mount source, because SD or eMMC-backed random I/O can be slower and wear
-  faster under session and credential writes.
-- **Session dirs missing**: `sessions/` and the session store directory are
-  required to persist history and avoid `ENOENT` crashes.
-- **Transcript mismatch**: warns when recent session entries have missing
-  transcript files.
-- **Main session “1-line JSONL”**: flags when the main transcript has only one
-  line (history is not accumulating).
-- **Multiple state dirs**: warns when multiple `~/.openclaw` folders exist across
-  home directories or when `OPENCLAW_STATE_DIR` points elsewhere (history can
-  split between installs).
-- **Remote mode reminder**: if `gateway.mode=remote`, doctor reminds you to run
-  it on the remote host (the state lives there).
-- **Config file permissions**: warns if `~/.openclaw/openclaw.json` is
-  group/world readable and offers to tighten to `600`.
-
-### 5) Model auth health (OAuth expiry)
-
-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
-Anthropic setup-token path.
-Refresh prompts only appear when running interactively (TTY); `--non-interactive`
-skips refresh attempts.
-
-When an OAuth refresh fails permanently (for example `refresh_token_reused`,
-`invalid_grant`, or a provider telling you to sign in again), doctor reports
-that re-auth is required and prints the exact `openclaw models auth login --provider ...`
-command to run.
-
-Doctor also reports auth profiles that are temporarily unusable due to:
-
-- short cooldowns (rate limits/timeouts/auth failures)
-- longer disables (billing/credit failures)
-
-### 6) Hooks model validation
-
-If `hooks.gmail.model` is set, doctor validates the model reference against the
-catalog and allowlist and warns when it won’t resolve or is disallowed.
-
-### 7) Sandbox image repair
-
-When sandboxing is enabled, doctor checks Docker images and offers to build or
-switch to legacy names if the current image is missing.
-
-### 7b) Bundled plugin runtime deps
-
-Doctor verifies runtime dependencies only for bundled plugins that are active in
-the current config or enabled by their bundled manifest default, for example
-`plugins.entries.discord.enabled: true`, legacy
-`channels.discord.enabled: true`, or a default-enabled bundled provider. If any
-are missing, doctor reports the packages and installs them in
-`openclaw doctor --fix` / `openclaw doctor --repair` mode. External plugins still
-use `openclaw plugins install` / `openclaw plugins update`; doctor does not
-install dependencies for arbitrary plugin paths.
-
-The Gateway and local CLI can also repair active bundled plugin runtime
-dependencies on demand before importing a bundled plugin. These installs are
-scoped to the plugin runtime install root, run with scripts disabled, do not
-write a package lock, and are guarded by an install-root lock so concurrent CLI
-or Gateway starts do not mutate the same `node_modules` tree at the same time.
-
-### 8) Gateway service migrations and cleanup hints
-
-Doctor detects legacy gateway services (launchd/systemd/schtasks) and
-offers to remove them and install the OpenClaw service using the current gateway
-port. It can also scan for extra gateway-like services and print cleanup hints.
-Profile-named OpenClaw gateway services are considered first-class and are not
-flagged as "extra."
-
-### 8b) Startup Matrix migration
-
-When a Matrix channel account has a pending or actionable legacy state migration,
-doctor (in `--fix` / `--repair` mode) creates a pre-migration snapshot and then
-runs the best-effort migration steps: legacy Matrix state migration and legacy
-encrypted-state preparation. Both steps are non-fatal; errors are logged and
-startup continues. In read-only mode (`openclaw doctor` without `--fix`) this check
-is skipped entirely.
-
-### 8c) Device pairing and auth drift
-
-Doctor now inspects device-pairing state as part of the normal health pass.
-
-What it reports:
-
-- pending first-time pairing requests
-- pending role upgrades for already paired devices
-- pending scope upgrades for already paired devices
-- public-key mismatch repairs where the device id still matches but the device
-  identity no longer matches the approved record
-- paired records missing an active token for an approved role
-- paired tokens whose scopes drift outside the approved pairing baseline
-- local cached device-token entries for the current machine that predate a
-  gateway-side token rotation or carry stale scope metadata
-
-Doctor does not auto-approve pair requests or auto-rotate device tokens. It
-prints the exact next steps instead:
-
-- inspect pending requests with `openclaw devices list`
-- approve the exact request with `openclaw devices approve <requestId>`
-- rotate a fresh token with `openclaw devices rotate --device <deviceId> --role <role>`
-- remove and re-approve a stale record with `openclaw devices remove <deviceId>`
-
-This closes the common "already paired but still getting pairing required"
-hole: doctor now distinguishes first-time pairing from pending role/scope
-upgrades and from stale token/device-identity drift.
-
-### 9) Security warnings
-
-Doctor emits warnings when a provider is open to DMs without an allowlist, or
-when a policy is configured in a dangerous way.
-
-### 10) systemd linger (Linux)
-
-If running as a systemd user service, doctor ensures lingering is enabled so the
-gateway stays alive after logout.
-
-### 11) Workspace status (skills, plugins, and legacy dirs)
-
-Doctor prints a summary of the workspace state for the default agent:
-
-- **Skills status**: counts eligible, missing-requirements, and allowlist-blocked skills.
-- **Legacy workspace dirs**: warns when `~/openclaw` or other legacy workspace directories
-  exist alongside the current workspace.
-- **Plugin status**: counts enabled/disabled/errored plugins; lists plugin IDs for any
-  errors; reports bundle plugin capabilities.
-- **Plugin compatibility warnings**: flags plugins that have compatibility issues with
-  the current runtime.
-- **Plugin diagnostics**: surfaces any load-time warnings or errors emitted by the
-  plugin registry.
-
-### 11b) Bootstrap file size
-
-Doctor checks whether workspace bootstrap files (for example `AGENTS.md`,
-`CLAUDE.md`, or other injected context files) are near or over the configured
-character budget. It reports per-file raw vs. injected character counts, truncation
-percentage, truncation cause (`max/file` or `max/total`), and total injected
-characters as a fraction of the total budget. When files are truncated or near
-the limit, doctor prints tips for tuning `agents.defaults.bootstrapMaxChars`
-and `agents.defaults.bootstrapTotalMaxChars`.
-
-### 11c) Shell completion
-
-Doctor checks whether tab completion is installed for the current shell
-(zsh, bash, fish, or PowerShell):
-
-- If the shell profile uses a slow dynamic completion pattern
-  (`source <(openclaw completion ...)`), doctor upgrades it to the faster
-  cached file variant.
-- If completion is configured in the profile but the cache file is missing,
-  doctor regenerates the cache automatically.
-- If no completion is configured at all, doctor prompts to install it
-  (interactive mode only; skipped with `--non-interactive`).
-
-Run `openclaw completion --write-state` to regenerate the cache manually.
-
-### 12) Gateway auth checks (local token)
-
-Doctor checks local gateway token auth readiness.
-
-- If token mode needs a token and no token source exists, doctor offers to generate one.
-- If `gateway.auth.token` is SecretRef-managed but unavailable, doctor warns and does not overwrite it with plaintext.
-- `openclaw doctor --generate-gateway-token` forces generation only when no token SecretRef is configured.
-
-### 12b) Read-only SecretRef-aware repairs
-
-Some repair flows need to inspect configured credentials without weakening runtime fail-fast behavior.
-
-- `openclaw doctor --fix` now uses the same read-only SecretRef summary model as status-family commands for targeted config repairs.
-- Example: Telegram `allowFrom` / `groupAllowFrom` `@username` repair tries to use configured bot credentials when available.
-- If the Telegram bot token is configured via SecretRef but unavailable in the current command path, doctor reports that the credential is configured-but-unavailable and skips auto-resolution instead of crashing or misreporting the token as missing.
-
-### 13) Gateway health check + restart
-
-Doctor runs a health check and offers to restart the gateway when it looks
-unhealthy.
-
-### 13b) Memory search readiness
-
-Doctor checks whether the configured memory search embedding provider is ready
-for the default agent. The behavior depends on the configured backend and provider:
-
-- **QMD backend**: probes whether the `qmd` binary is available and startable.
-  If not, prints fix guidance including the npm package and a manual binary path option.
-- **Explicit local provider**: checks for a local model file or a recognized
-  remote/downloadable model URL. If missing, suggests switching to a remote provider.
-- **Explicit remote provider** (`openai`, `voyage`, etc.): verifies an API key is
-  present in the environment or auth store. Prints actionable fix hints if missing.
-- **Auto provider**: checks local model availability first, then tries each remote
-  provider in auto-selection order.
-
-When a gateway probe result is available (gateway was healthy at the time of the
-check), doctor cross-references its result with the CLI-visible config and notes
-any discrepancy.
-
-Use `openclaw memory status --deep` to verify embedding readiness at runtime.
-
-### 14) Channel status warnings
-
-If the gateway is healthy, doctor runs a channel status probe and reports
-warnings with suggested fixes.
-
-### 15) Supervisor config audit + repair
-
-Doctor checks the installed supervisor config (launchd/systemd/schtasks) for
-missing or outdated defaults (e.g., systemd network-online dependencies and
-restart delay). When it finds a mismatch, it recommends an update and can
-rewrite the service file/task to the current defaults.
-
-Notes:
-
-- `openclaw doctor` prompts before rewriting supervisor config.
-- `openclaw doctor --yes` accepts the default repair prompts.
-- `openclaw doctor --repair` applies recommended fixes without prompts.
-- `openclaw doctor --repair --force` overwrites custom supervisor configs.
-- If token auth requires a token and `gateway.auth.token` is SecretRef-managed, doctor service install/repair validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
-- If token auth requires a token and the configured token SecretRef is unresolved, doctor blocks the install/repair path with actionable guidance.
-- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, doctor blocks install/repair until mode is set explicitly.
-- For Linux user-systemd units, doctor token drift checks now include both `Environment=` and `EnvironmentFile=` sources when comparing service auth metadata.
-- You can always force a full rewrite via `openclaw gateway install --force`.
-
-### 16) Gateway runtime + port diagnostics
-
-Doctor inspects the service runtime (PID, last exit status) and warns when the
-service is installed but not actually running. It also checks for port collisions
-on the gateway port (default `18789`) and reports likely causes (gateway already
-running, SSH tunnel).
-
-### 17) Gateway runtime best practices
-
-Doctor warns when the gateway service runs on Bun or a version-managed Node path
-(`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram channels require Node,
-and version-manager paths can break after upgrades because the service does not
-load your shell init. Doctor offers to migrate to a system Node install when
-available (Homebrew/apt/choco).
-
-### 18) Config write + wizard metadata
-
-Doctor persists any config changes and stamps wizard metadata to record the
-doctor run.
-
-### 19) Workspace tips (backup + memory system)
-
-Doctor suggests a workspace memory system when missing and prints a backup tip
-if the workspace is not already under git.
-
-See [/concepts/agent-workspace](/concepts/agent-workspace) for a full guide to
-workspace structure and git backup (recommended private GitHub or GitLab).
+<AccordionGroup>
+  <Accordion title="0. Optional update (git installs)">
+    If this is a git checkout and doctor is running interactively, it offers to update (fetch/rebase/build) before running doctor.
+  </Accordion>
+  <Accordion title="1. Config normalization">
+    If the config contains legacy value shapes (for example `messages.ackReaction` without a channel-specific override), doctor normalizes them into the current schema.
+
+    That includes legacy Talk flat fields. Current public Talk config is `talk.provider` + `talk.providers.<provider>`. Doctor rewrites old `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` shapes into the provider map.
+
+  </Accordion>
+  <Accordion title="2. Legacy config key migrations">
+    When the config contains deprecated keys, other commands refuse to run and ask you to run `openclaw doctor`.
+
+    Doctor will:
+
+    - Explain which legacy keys were found.
+    - Show the migration it applied.
+    - Rewrite `~/.openclaw/openclaw.json` with the updated schema.
+
+    The Gateway also auto-runs doctor migrations on startup when it detects a legacy config format, so stale configs are repaired without manual intervention. Cron job store migrations are handled by `openclaw doctor --fix`.
+
+    Current migrations:
+
+    - `routing.allowFrom` → `channels.whatsapp.allowFrom`
+    - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
+    - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
+    - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
+    - `routing.queue` → `messages.queue`
+    - `routing.bindings` → top-level `bindings`
+    - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
+    - legacy `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
+    - `routing.agentToAgent` → `tools.agentToAgent`
+    - `routing.transcribeAudio` → `tools.media.audio.models`
+    - `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
+    - `messages.tts.provider: "edge"` and `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` and `messages.tts.providers.microsoft`
+    - `channels.discord.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.<provider>`
+    - `channels.discord.accounts.<id>.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
+    - `plugins.entries.voice-call.config.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.<provider>`
+    - `plugins.entries.voice-call.config.tts.provider: "edge"` and `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` and `providers.microsoft`
+    - `plugins.entries.voice-call.config.provider: "log"` → `"mock"`
+    - `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber`
+    - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
+    - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
+    - `bindings[].match.accountID` → `bindings[].match.accountId`
+    - For channels with named `accounts` but lingering single-account top-level channel values, move those account-scoped values into the promoted account chosen for that channel (`accounts.default` for most channels; Matrix can preserve an existing matching named/default target)
+    - `identity` → `agents.list[].identity`
+    - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
+    - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
+    - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
+    - `browser.profiles.*.driver: "extension"` → `"existing-session"`
+    - remove `browser.relayBindHost` (legacy extension relay setting)
+
+    Doctor warnings also include account-default guidance for multi-account channels:
+
+    - If two or more `channels.<channel>.accounts` entries are configured without `channels.<channel>.defaultAccount` or `accounts.default`, doctor warns that fallback routing can pick an unexpected account.
+    - If `channels.<channel>.defaultAccount` is set to an unknown account ID, doctor warns and lists configured account IDs.
+
+  </Accordion>
+  <Accordion title="2b. OpenCode provider overrides">
+    If you've added `models.providers.opencode`, `opencode-zen`, or `opencode-go` manually, it overrides the built-in OpenCode catalog from `@mariozechner/pi-ai`. That can force models onto the wrong API or zero out costs. Doctor warns so you can remove the override and restore per-model API routing + costs.
+  </Accordion>
+  <Accordion title="2c. Browser migration and Chrome MCP readiness">
+    If your browser config still points at the removed Chrome extension path, doctor normalizes it to the current host-local Chrome MCP attach model:
+
+    - `browser.profiles.*.driver: "extension"` becomes `"existing-session"`
+    - `browser.relayBindHost` is removed
+
+    Doctor also audits the host-local Chrome MCP path when you use `defaultProfile: "user"` or a configured `existing-session` profile:
+
+    - checks whether Google Chrome is installed on the same host for default auto-connect profiles
+    - checks the detected Chrome version and warns when it is below Chrome 144
+    - reminds you to enable remote debugging in the browser inspect page (for example `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, or `edge://inspect/#remote-debugging`)
+
+    Doctor cannot enable the Chrome-side setting for you. Host-local Chrome MCP still requires:
+
+    - a Chromium-based browser 144+ on the gateway/node host
+    - the browser running locally
+    - remote debugging enabled in that browser
+    - approving the first attach consent prompt in the browser
+
+    Readiness here is only about local attach prerequisites. Existing-session keeps the current Chrome MCP route limits; advanced routes like `responsebody`, PDF export, download interception, and batch actions still require a managed browser or raw CDP profile.
+
+    This check does **not** apply to Docker, sandbox, remote-browser, or other headless flows. Those continue to use raw CDP.
+
+  </Accordion>
+  <Accordion title="2d. OAuth TLS prerequisites">
+    When an OpenAI Codex OAuth profile is configured, doctor probes the OpenAI authorization endpoint to verify that the local Node/OpenSSL TLS stack can validate the certificate chain. If the probe fails with a certificate error (for example `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, expired cert, or self-signed cert), doctor prints platform-specific fix guidance. On macOS with a Homebrew Node, the fix is usually `brew postinstall ca-certificates`. With `--deep`, the probe runs even if the gateway is healthy.
+  </Accordion>
+  <Accordion title="2e. Codex OAuth provider overrides">
+    If you previously added legacy OpenAI transport settings under `models.providers.openai-codex`, they can shadow the built-in Codex OAuth provider path that newer releases use automatically. Doctor warns when it sees those old transport settings alongside Codex OAuth so you can remove or rewrite the stale transport override and get the built-in routing/fallback behavior back. Custom proxies and header-only overrides are still supported and do not trigger this warning.
+  </Accordion>
+  <Accordion title="2f. Codex plugin route warnings">
+    When the bundled Codex plugin is enabled, doctor also checks whether `openai-codex/*` primary model refs still resolve through the default PI runner. That combination is valid when you want Codex OAuth/subscription auth through PI, but it is easy to confuse with the native Codex app-server harness. Doctor warns and points to the explicit app-server shape: `openai/*` plus `embeddedHarness.runtime: "codex"` or `OPENCLAW_AGENT_RUNTIME=codex`.
+
+    Doctor does not repair this automatically because both routes are valid:
+
+    - `openai-codex/*` + PI means "use Codex OAuth/subscription auth through the normal OpenClaw runner."
+    - `openai/*` + `runtime: "codex"` means "run the embedded turn through native Codex app-server."
+    - `/codex ...` means "control or bind a native Codex conversation from chat."
+    - `/acp ...` or `runtime: "acp"` means "use the external ACP/acpx adapter."
+
+    If the warning appears, choose the route you intended and edit config manually. Keep the warning as-is when PI Codex OAuth is intentional.
+
+  </Accordion>
+  <Accordion title="3. Legacy state migrations (disk layout)">
+    Doctor can migrate older on-disk layouts into the current structure:
+
+    - Sessions store + transcripts:
+      - from `~/.openclaw/sessions/` to `~/.openclaw/agents/<agentId>/sessions/`
+    - Agent dir:
+      - from `~/.openclaw/agent/` to `~/.openclaw/agents/<agentId>/agent/`
+    - WhatsApp auth state (Baileys):
+      - from legacy `~/.openclaw/credentials/*.json` (except `oauth.json`)
+      - to `~/.openclaw/credentials/whatsapp/<accountId>/...` (default account id: `default`)
+
+    These migrations are best-effort and idempotent; doctor will emit warnings when it leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates the legacy sessions + agent dir on startup so history/auth/models land in the per-agent path without a manual doctor run. WhatsApp auth is intentionally only migrated via `openclaw doctor`. Talk provider/provider-map normalization now compares by structural equality, so key-order-only diffs no longer trigger repeat no-op `doctor --fix` changes.
+
+  </Accordion>
+  <Accordion title="3a. Legacy plugin manifest migrations">
+    Doctor scans all installed plugin manifests for deprecated top-level capability keys (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). When found, it offers to move them into the `contracts` object and rewrite the manifest file in-place. This migration is idempotent; if the `contracts` key already has the same values, the legacy key is removed without duplicating the data.
+  </Accordion>
+  <Accordion title="3b. Legacy cron store migrations">
+    Doctor also checks the cron job store (`~/.openclaw/cron/jobs.json` by default, or `cron.store` when overridden) for old job shapes that the scheduler still accepts for compatibility.
+
+    Current cron cleanups include:
+
+    - `jobId` → `id`
+    - `schedule.cron` → `schedule.expr`
+    - top-level payload fields (`message`, `model`, `thinking`, ...) → `payload`
+    - top-level delivery fields (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
+    - payload `provider` delivery aliases → explicit `delivery.channel`
+    - simple legacy `notify: true` webhook fallback jobs → explicit `delivery.mode="webhook"` with `delivery.to=cron.webhook`
+
+    Doctor only auto-migrates `notify: true` jobs when it can do so without changing behavior. If a job combines legacy notify fallback with an existing non-webhook delivery mode, doctor warns and leaves that job for manual review.
+
+  </Accordion>
+  <Accordion title="3c. Session lock cleanup">
+    Doctor scans every agent session directory for stale write-lock files — files left behind when a session exited abnormally. For each lock file found it reports: the path, PID, whether the PID is still alive, lock age, and whether it is considered stale (dead PID or older than 30 minutes). In `--fix` / `--repair` mode it removes stale lock files automatically; otherwise it prints a note and instructs you to rerun with `--fix`.
+  </Accordion>
+  <Accordion title="3d. Session transcript branch repair">
+    Doctor scans agent session JSONL files for the duplicated branch shape created by the 2026.4.24 prompt transcript rewrite bug: an abandoned user turn with OpenClaw internal runtime context plus an active sibling containing the same visible user prompt. In `--fix` / `--repair` mode, doctor backs up each affected file next to the original and rewrites the transcript to the active branch so gateway history and memory readers no longer see duplicate turns.
+  </Accordion>
+  <Accordion title="4. State integrity checks (session persistence, routing, and safety)">
+    The state directory is the operational brainstem. If it vanishes, you lose sessions, credentials, logs, and config (unless you have backups elsewhere).
+
+    Doctor checks:
+
+    - **State dir missing**: warns about catastrophic state loss, prompts to recreate the directory, and reminds you that it cannot recover missing data.
+    - **State dir permissions**: verifies writability; offers to repair permissions (and emits a `chown` hint when owner/group mismatch is detected).
+    - **macOS cloud-synced state dir**: warns when state resolves under iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) or `~/Library/CloudStorage/...` because sync-backed paths can cause slower I/O and lock/sync races.
+    - **Linux SD or eMMC state dir**: warns when state resolves to an `mmcblk*` mount source, because SD or eMMC-backed random I/O can be slower and wear faster under session and credential writes.
+    - **Session dirs missing**: `sessions/` and the session store directory are required to persist history and avoid `ENOENT` crashes.
+    - **Transcript mismatch**: warns when recent session entries have missing transcript files.
+    - **Main session "1-line JSONL"**: flags when the main transcript has only one line (history is not accumulating).
+    - **Multiple state dirs**: warns when multiple `~/.openclaw` folders exist across home directories or when `OPENCLAW_STATE_DIR` points elsewhere (history can split between installs).
+    - **Remote mode reminder**: if `gateway.mode=remote`, doctor reminds you to run it on the remote host (the state lives there).
+    - **Config file permissions**: warns if `~/.openclaw/openclaw.json` is group/world readable and offers to tighten to `600`.
+
+  </Accordion>
+  <Accordion title="5. Model auth health (OAuth expiry)">
+    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 Anthropic setup-token path. Refresh prompts only appear when running interactively (TTY); `--non-interactive` skips refresh attempts.
+
+    When an OAuth refresh fails permanently (for example `refresh_token_reused`, `invalid_grant`, or a provider telling you to sign in again), doctor reports that re-auth is required and prints the exact `openclaw models auth login --provider ...` command to run.
+
+    Doctor also reports auth profiles that are temporarily unusable due to:
+
+    - short cooldowns (rate limits/timeouts/auth failures)
+    - longer disables (billing/credit failures)
+
+  </Accordion>
+  <Accordion title="6. Hooks model validation">
+    If `hooks.gmail.model` is set, doctor validates the model reference against the catalog and allowlist and warns when it won't resolve or is disallowed.
+  </Accordion>
+  <Accordion title="7. Sandbox image repair">
+    When sandboxing is enabled, doctor checks Docker images and offers to build or switch to legacy names if the current image is missing.
+  </Accordion>
+  <Accordion title="7b. Bundled plugin runtime deps">
+    Doctor verifies runtime dependencies only for bundled plugins that are active in the current config or enabled by their bundled manifest default, for example `plugins.entries.discord.enabled: true`, legacy `channels.discord.enabled: true`, or a default-enabled bundled provider. If any are missing, doctor reports the packages and installs them in `openclaw doctor --fix` / `openclaw doctor --repair` mode. External plugins still use `openclaw plugins install` / `openclaw plugins update`; doctor does not install dependencies for arbitrary plugin paths.
+
+    The Gateway and local CLI can also repair active bundled plugin runtime dependencies on demand before importing a bundled plugin. These installs are scoped to the plugin runtime install root, run with scripts disabled, do not write a package lock, and are guarded by an install-root lock so concurrent CLI or Gateway starts do not mutate the same `node_modules` tree at the same time.
+
+  </Accordion>
+  <Accordion title="8. Gateway service migrations and cleanup hints">
+    Doctor detects legacy gateway services (launchd/systemd/schtasks) and offers to remove them and install the OpenClaw service using the current gateway port. It can also scan for extra gateway-like services and print cleanup hints. Profile-named OpenClaw gateway services are considered first-class and are not flagged as "extra."
+  </Accordion>
+  <Accordion title="8b. Startup Matrix migration">
+    When a Matrix channel account has a pending or actionable legacy state migration, doctor (in `--fix` / `--repair` mode) creates a pre-migration snapshot and then runs the best-effort migration steps: legacy Matrix state migration and legacy encrypted-state preparation. Both steps are non-fatal; errors are logged and startup continues. In read-only mode (`openclaw doctor` without `--fix`) this check is skipped entirely.
+  </Accordion>
+  <Accordion title="8c. Device pairing and auth drift">
+    Doctor now inspects device-pairing state as part of the normal health pass.
+
+    What it reports:
+
+    - pending first-time pairing requests
+    - pending role upgrades for already paired devices
+    - pending scope upgrades for already paired devices
+    - public-key mismatch repairs where the device id still matches but the device identity no longer matches the approved record
+    - paired records missing an active token for an approved role
+    - paired tokens whose scopes drift outside the approved pairing baseline
+    - local cached device-token entries for the current machine that predate a gateway-side token rotation or carry stale scope metadata
+
+    Doctor does not auto-approve pair requests or auto-rotate device tokens. It prints the exact next steps instead:
+
+    - inspect pending requests with `openclaw devices list`
+    - approve the exact request with `openclaw devices approve <requestId>`
+    - rotate a fresh token with `openclaw devices rotate --device <deviceId> --role <role>`
+    - remove and re-approve a stale record with `openclaw devices remove <deviceId>`
+
+    This closes the common "already paired but still getting pairing required" hole: doctor now distinguishes first-time pairing from pending role/scope upgrades and from stale token/device-identity drift.
+
+  </Accordion>
+  <Accordion title="9. Security warnings">
+    Doctor emits warnings when a provider is open to DMs without an allowlist, or when a policy is configured in a dangerous way.
+  </Accordion>
+  <Accordion title="10. systemd linger (Linux)">
+    If running as a systemd user service, doctor ensures lingering is enabled so the gateway stays alive after logout.
+  </Accordion>
+  <Accordion title="11. Workspace status (skills, plugins, and legacy dirs)">
+    Doctor prints a summary of the workspace state for the default agent:
+
+    - **Skills status**: counts eligible, missing-requirements, and allowlist-blocked skills.
+    - **Legacy workspace dirs**: warns when `~/openclaw` or other legacy workspace directories exist alongside the current workspace.
+    - **Plugin status**: counts enabled/disabled/errored plugins; lists plugin IDs for any errors; reports bundle plugin capabilities.
+    - **Plugin compatibility warnings**: flags plugins that have compatibility issues with the current runtime.
+    - **Plugin diagnostics**: surfaces any load-time warnings or errors emitted by the plugin registry.
+
+  </Accordion>
+  <Accordion title="11b. Bootstrap file size">
+    Doctor checks whether workspace bootstrap files (for example `AGENTS.md`, `CLAUDE.md`, or other injected context files) are near or over the configured character budget. It reports per-file raw vs. injected character counts, truncation percentage, truncation cause (`max/file` or `max/total`), and total injected characters as a fraction of the total budget. When files are truncated or near the limit, doctor prints tips for tuning `agents.defaults.bootstrapMaxChars` and `agents.defaults.bootstrapTotalMaxChars`.
+  </Accordion>
+  <Accordion title="11c. Shell completion">
+    Doctor checks whether tab completion is installed for the current shell (zsh, bash, fish, or PowerShell):
+
+    - If the shell profile uses a slow dynamic completion pattern (`source <(openclaw completion ...)`), doctor upgrades it to the faster cached file variant.
+    - If completion is configured in the profile but the cache file is missing, doctor regenerates the cache automatically.
+    - If no completion is configured at all, doctor prompts to install it (interactive mode only; skipped with `--non-interactive`).
+
+    Run `openclaw completion --write-state` to regenerate the cache manually.
+
+  </Accordion>
+  <Accordion title="12. Gateway auth checks (local token)">
+    Doctor checks local gateway token auth readiness.
+
+    - If token mode needs a token and no token source exists, doctor offers to generate one.
+    - If `gateway.auth.token` is SecretRef-managed but unavailable, doctor warns and does not overwrite it with plaintext.
+    - `openclaw doctor --generate-gateway-token` forces generation only when no token SecretRef is configured.
+
+  </Accordion>
+  <Accordion title="12b. Read-only SecretRef-aware repairs">
+    Some repair flows need to inspect configured credentials without weakening runtime fail-fast behavior.
+
+    - `openclaw doctor --fix` now uses the same read-only SecretRef summary model as status-family commands for targeted config repairs.
+    - Example: Telegram `allowFrom` / `groupAllowFrom` `@username` repair tries to use configured bot credentials when available.
+    - If the Telegram bot token is configured via SecretRef but unavailable in the current command path, doctor reports that the credential is configured-but-unavailable and skips auto-resolution instead of crashing or misreporting the token as missing.
+
+  </Accordion>
+  <Accordion title="13. Gateway health check + restart">
+    Doctor runs a health check and offers to restart the gateway when it looks unhealthy.
+  </Accordion>
+  <Accordion title="13b. Memory search readiness">
+    Doctor checks whether the configured memory search embedding provider is ready for the default agent. The behavior depends on the configured backend and provider:
+
+    - **QMD backend**: probes whether the `qmd` binary is available and startable. If not, prints fix guidance including the npm package and a manual binary path option.
+    - **Explicit local provider**: checks for a local model file or a recognized remote/downloadable model URL. If missing, suggests switching to a remote provider.
+    - **Explicit remote provider** (`openai`, `voyage`, etc.): verifies an API key is present in the environment or auth store. Prints actionable fix hints if missing.
+    - **Auto provider**: checks local model availability first, then tries each remote provider in auto-selection order.
+
+    When a gateway probe result is available (gateway was healthy at the time of the check), doctor cross-references its result with the CLI-visible config and notes any discrepancy.
+
+    Use `openclaw memory status --deep` to verify embedding readiness at runtime.
+
+  </Accordion>
+  <Accordion title="14. Channel status warnings">
+    If the gateway is healthy, doctor runs a channel status probe and reports warnings with suggested fixes.
+  </Accordion>
+  <Accordion title="15. Supervisor config audit + repair">
+    Doctor checks the installed supervisor config (launchd/systemd/schtasks) for missing or outdated defaults (e.g., systemd network-online dependencies and restart delay). When it finds a mismatch, it recommends an update and can rewrite the service file/task to the current defaults.
+
+    Notes:
+
+    - `openclaw doctor` prompts before rewriting supervisor config.
+    - `openclaw doctor --yes` accepts the default repair prompts.
+    - `openclaw doctor --repair` applies recommended fixes without prompts.
+    - `openclaw doctor --repair --force` overwrites custom supervisor configs.
+    - If token auth requires a token and `gateway.auth.token` is SecretRef-managed, doctor service install/repair validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
+    - If token auth requires a token and the configured token SecretRef is unresolved, doctor blocks the install/repair path with actionable guidance.
+    - If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, doctor blocks install/repair until mode is set explicitly.
+    - For Linux user-systemd units, doctor token drift checks now include both `Environment=` and `EnvironmentFile=` sources when comparing service auth metadata.
+    - Doctor service repairs refuse to rewrite, stop, or restart a gateway service from an older OpenClaw binary when the config was last written by a newer version. See [Gateway troubleshooting](/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
+    - You can always force a full rewrite via `openclaw gateway install --force`.
+
+  </Accordion>
+  <Accordion title="16. Gateway runtime + port diagnostics">
+    Doctor inspects the service runtime (PID, last exit status) and warns when the service is installed but not actually running. It also checks for port collisions on the gateway port (default `18789`) and reports likely causes (gateway already running, SSH tunnel).
+  </Accordion>
+  <Accordion title="17. Gateway runtime best practices">
+    Doctor warns when the gateway service runs on Bun or a version-managed Node path (`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram channels require Node, and version-manager paths can break after upgrades because the service does not load your shell init. Doctor offers to migrate to a system Node install when available (Homebrew/apt/choco).
+  </Accordion>
+  <Accordion title="18. Config write + wizard metadata">
+    Doctor persists any config changes and stamps wizard metadata to record the doctor run.
+  </Accordion>
+  <Accordion title="19. Workspace tips (backup + memory system)">
+    Doctor suggests a workspace memory system when missing and prints a backup tip if the workspace is not already under git.
+
+    See [/concepts/agent-workspace](/concepts/agent-workspace) for a full guide to workspace structure and git backup (recommended private GitHub or GitLab).
+
+  </Accordion>
+</AccordionGroup>
 
 ## Related
 
-- [Gateway troubleshooting](/gateway/troubleshooting)
 - [Gateway runbook](/gateway)
+- [Gateway troubleshooting](/gateway/troubleshooting)

docs/gateway/index.md

@@ -251,6 +251,8 @@ openclaw gateway restart
 openclaw gateway stop
 ```
 
+Use `openclaw gateway restart` for restarts. Do not chain `openclaw gateway stop` and `openclaw gateway start`; on macOS, `gateway stop` intentionally disables the LaunchAgent before stopping it.
+
 LaunchAgent labels are `ai.openclaw.gateway` (default) or `ai.openclaw.<profile>` (named profile). `openclaw doctor` audits and repairs service config drift.
 
   </Tab>

docs/gateway/logging.md

@@ -19,6 +19,8 @@ OpenClaw has two log “surfaces”:
 
 - Default rolling log file is under `/tmp/openclaw/` (one file per day): `openclaw-YYYY-MM-DD.log`
   - Date uses the gateway host's local timezone.
+- Active log files rotate at `logging.maxFileBytes` (default: 100 MB), keeping
+  up to five numbered archives and continuing to write a fresh active file.
 - The log file path and level can be configured via `~/.openclaw/openclaw.json`:
   - `logging.file`
   - `logging.level`

docs/gateway/opentelemetry.md

@@ -147,7 +147,7 @@ When any subkey is enabled, model and tool spans get bounded, redacted
 
 ### Model usage
 
-- `openclaw.tokens` (counter, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
+- `openclaw.tokens` (counter, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`)
 - `openclaw.cost.usd` (counter, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
 - `openclaw.run.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
 - `openclaw.context.tokens` (histogram, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`)

docs/gateway/protocol.md

@@ -360,8 +360,8 @@ enumeration of `src/gateway/server-methods/*.ts`.
   <Accordion title="Device pairing and device tokens">
     - `device.pair.list` returns pending and approved paired devices.
     - `device.pair.approve`, `device.pair.reject`, and `device.pair.remove` manage device-pairing records.
-    - `device.token.rotate` rotates a paired device token within its approved role and scope bounds.
-    - `device.token.revoke` revokes a paired device token.
+    - `device.token.rotate` rotates a paired device token within its approved role and caller scope bounds.
+    - `device.token.revoke` revokes a paired device token within its approved role and caller scope bounds.
   </Accordion>
 
   <Accordion title="Node pairing, invoke, and pending work">
@@ -549,15 +549,15 @@ rather than the pre-handshake defaults.
   reused when the client is reusing the stored per-device token.
 - Device tokens can be rotated/revoked via `device.token.rotate` and
   `device.token.revoke` (requires `operator.pairing` scope).
-- Token issuance/rotation stays bounded to the approved role set recorded in
-  that device's pairing entry; rotating a token cannot expand the device into a
-  role that pairing approval never granted.
+- Token issuance, rotation, and revocation stay bounded to the approved role set
+  recorded in that device's pairing entry; token mutation cannot expand or
+  target a device role that pairing approval never granted.
 - For paired-device token sessions, device management is self-scoped unless the
   caller also has `operator.admin`: non-admin callers can remove/revoke/rotate
   only their **own** device entry.
-- `device.token.rotate` also checks the requested operator scope set against the
-  caller's current session scopes. Non-admin callers cannot rotate a token into
-  a broader operator scope set than they already hold.
+- `device.token.rotate` and `device.token.revoke` also check the target operator
+  token scope set against the caller's current session scopes. Non-admin callers
+  cannot rotate or revoke a broader operator token than they already hold.
 - Auth failures include `error.details.code` plus recovery hints:
   - `error.details.canRetryWithDeviceToken` (boolean)
   - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)

docs/gateway/remote.md

@@ -98,6 +98,8 @@ You can persist a remote target so CLI commands use it by default:
 ```
 
 When the gateway is loopback-only, keep the URL at `ws://127.0.0.1:18789` and open the SSH tunnel first.
+In the macOS app’s SSH tunnel transport, discovered gateway hostnames belong in
+`gateway.remote.sshTarget`; `gateway.remote.url` remains the local tunnel URL.
 
 ## Credential precedence
 

docs/gateway/troubleshooting.md

@@ -4,12 +4,10 @@ read_when:
   - The troubleshooting hub pointed you here for deeper diagnosis
   - You need stable symptom based runbook sections with exact commands
 title: "Troubleshooting"
+sidebarTitle: "Troubleshooting"
 ---
 
-# Gateway troubleshooting
-
-This page is the deep runbook.
-Start at [/help/troubleshooting](/help/troubleshooting) if you want the fast triage flow first.
+This page is the deep runbook. Start at [/help/troubleshooting](/help/troubleshooting) if you want the fast triage flow first.
 
 ## Command ladder
 
@@ -27,13 +25,46 @@ Expected healthy signals:
 
 - `openclaw gateway status` shows `Runtime: running`, `Connectivity probe: ok`, and a `Capability: ...` line.
 - `openclaw doctor` reports no blocking config/service issues.
-- `openclaw channels status --probe` shows live per-account transport status and,
-  where supported, probe/audit results such as `works` or `audit ok`.
+- `openclaw channels status --probe` shows live per-account transport status and, where supported, probe/audit results such as `works` or `audit ok`.
+
+## Split brain installs and newer config guard
+
+Use this when a gateway service unexpectedly stops after an update, or logs show that one `openclaw` binary is older than the version that last wrote `openclaw.json`.
+
+OpenClaw stamps config writes with `meta.lastTouchedVersion`. Read-only commands can still inspect a config written by a newer OpenClaw, but process and service mutations refuse to continue from an older binary. Blocked actions include gateway service start, stop, restart, uninstall, forced service reinstall, service-mode gateway startup, and `gateway --force` port cleanup.
+
+```bash
+which openclaw
+openclaw --version
+openclaw gateway status --deep
+openclaw config get meta.lastTouchedVersion
+```
+
+<Steps>
+  <Step title="Fix PATH">
+    Fix `PATH` so `openclaw` resolves to the newer install, then rerun the action.
+  </Step>
+  <Step title="Reinstall the gateway service">
+    Reinstall the intended gateway service from the newer install:
+
+    ```bash
+    openclaw gateway install --force
+    openclaw gateway restart
+    ```
+
+  </Step>
+  <Step title="Remove stale wrappers">
+    Remove stale system package or old wrapper entries that still point at an old `openclaw` binary.
+  </Step>
+</Steps>
+
+<Warning>
+For intentional downgrade or emergency recovery only, set `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` for the single command. Leave it unset for normal operation.
+</Warning>
 
 ## Anthropic 429 extra usage required for long context
 
-Use this when logs/errors include:
-`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
+Use this when logs/errors include: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
 
 ```bash
 openclaw logs --follow
@@ -49,9 +80,17 @@ Look for:
 
 Fix options:
 
-1. Disable `context1m` for that model to fall back to the normal context window.
-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.
+<Steps>
+  <Step title="Disable context1m">
+    Disable `context1m` for that model to fall back to the normal context window.
+  </Step>
+  <Step title="Use an eligible credential">
+    Use an Anthropic credential that is eligible for long-context requests, or switch to an Anthropic API key.
+  </Step>
+  <Step title="Configure fallback models">
+    Configure fallback models so runs continue when Anthropic long-context requests are rejected.
+  </Step>
+</Steps>
 
 Related:
 
@@ -80,38 +119,26 @@ Look for:
 
 - direct tiny calls succeed, but OpenClaw runs fail only on larger prompts
 - backend errors about `messages[].content` expecting a string
-- backend crashes that appear only with larger prompt-token counts or full agent
-  runtime prompts
+- backend crashes that appear only with larger prompt-token counts or full agent runtime prompts
 
-Common signatures:
-
-- `messages[...].content: invalid type: sequence, expected a string` → backend
-  rejects structured Chat Completions content parts. Fix: set
-  `models.providers.<provider>.models[].compat.requiresStringContent: true`.
-- direct tiny requests succeed, but OpenClaw agent runs fail with backend/model
-  crashes (for example Gemma on some `inferrs` builds) → OpenClaw transport is
-  likely already correct; the backend is failing on the larger agent-runtime
-  prompt shape.
-- failures shrink after disabling tools but do not disappear → tool schemas were
-  part of the pressure, but the remaining issue is still upstream model/server
-  capacity or a backend bug.
-
-Fix options:
-
-1. Set `compat.requiresStringContent: true` for string-only Chat Completions backends.
-2. Set `compat.supportsTools: false` for models/backends that cannot handle
-   OpenClaw's tool schema surface reliably.
-3. Lower prompt pressure where possible: smaller workspace bootstrap, shorter
-   session history, lighter local model, or a backend with stronger long-context
-   support.
-4. If tiny direct requests keep passing while OpenClaw agent turns still crash
-   inside the backend, treat it as an upstream server/model limitation and file
-   a repro there with the accepted payload shape.
+<AccordionGroup>
+  <Accordion title="Common signatures">
+    - `messages[...].content: invalid type: sequence, expected a string` → backend rejects structured Chat Completions content parts. Fix: set `models.providers.<provider>.models[].compat.requiresStringContent: true`.
+    - direct tiny requests succeed, but OpenClaw agent runs fail with backend/model crashes (for example Gemma on some `inferrs` builds) → OpenClaw transport is likely already correct; the backend is failing on the larger agent-runtime prompt shape.
+    - failures shrink after disabling tools but do not disappear → tool schemas were part of the pressure, but the remaining issue is still upstream model/server capacity or a backend bug.
+  </Accordion>
+  <Accordion title="Fix options">
+    1. Set `compat.requiresStringContent: true` for string-only Chat Completions backends.
+    2. Set `compat.supportsTools: false` for models/backends that cannot handle OpenClaw's tool schema surface reliably.
+    3. Lower prompt pressure where possible: smaller workspace bootstrap, shorter session history, lighter local model, or a backend with stronger long-context support.
+    4. If tiny direct requests keep passing while OpenClaw agent turns still crash inside the backend, treat it as an upstream server/model limitation and file a repro there with the accepted payload shape.
+  </Accordion>
+</AccordionGroup>
 
 Related:
 
-- [Local models](/gateway/local-models)
 - [Configuration](/gateway/configuration)
+- [Local models](/gateway/local-models)
 - [OpenAI-compatible endpoints](/gateway/configuration-reference#openai-compatible-endpoints)
 
 ## No replies
@@ -141,10 +168,10 @@ Common signatures:
 Related:
 
 - [Channel troubleshooting](/channels/troubleshooting)
-- [Pairing](/channels/pairing)
 - [Groups](/channels/groups)
+- [Pairing](/channels/pairing)
 
-## Dashboard control ui connectivity
+## Dashboard control UI connectivity
 
 When dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions.
 
@@ -162,32 +189,21 @@ Look for:
 - Auth mode/token mismatch between client and gateway.
 - HTTP usage where device identity is required.
 
-Common signatures:
-
-- `device identity required` → non-secure context or missing device auth.
-- `origin not allowed` → browser `Origin` is not in `gateway.controlUi.allowedOrigins`
-  (or you are connecting from a non-loopback browser origin without an explicit
-  allowlist).
-- `device nonce required` / `device nonce mismatch` → client is not completing the
-  challenge-based device auth flow (`connect.challenge` + `device.nonce`).
-- `device signature invalid` / `device signature expired` → client signed the wrong
-  payload (or stale timestamp) for the current handshake.
-- `AUTH_TOKEN_MISMATCH` with `canRetryWithDeviceToken=true` → client can do one trusted retry with cached device token.
-- That cached-token retry reuses the cached scope set stored with the paired
-  device token. Explicit `deviceToken` / explicit `scopes` callers keep their
-  requested scope set instead.
-- Outside that retry path, connect auth precedence is explicit shared
-  token/password first, then explicit `deviceToken`, then stored device token,
-  then bootstrap token.
-- On the async Tailscale Serve Control UI path, failed attempts for the same
-  `{scope, ip}` are serialized before the limiter records the failure. Two bad
-  concurrent retries from the same client can therefore surface `retry later`
-  on the second attempt instead of two plain mismatches.
-- `too many failed authentication attempts (retry later)` from a browser-origin
-  loopback client → repeated failures from that same normalized `Origin` are
-  locked out temporarily; another localhost origin uses a separate bucket.
-- repeated `unauthorized` after that retry → shared token/device token drift; refresh token config and re-approve/rotate device token if needed.
-- `gateway connect failed:` → wrong host/port/url target.
+<AccordionGroup>
+  <Accordion title="Connect / auth signatures">
+    - `device identity required` → non-secure context or missing device auth.
+    - `origin not allowed` → browser `Origin` is not in `gateway.controlUi.allowedOrigins` (or you are connecting from a non-loopback browser origin without an explicit allowlist).
+    - `device nonce required` / `device nonce mismatch` → client is not completing the challenge-based device auth flow (`connect.challenge` + `device.nonce`).
+    - `device signature invalid` / `device signature expired` → client signed the wrong payload (or stale timestamp) for the current handshake.
+    - `AUTH_TOKEN_MISMATCH` with `canRetryWithDeviceToken=true` → client can do one trusted retry with cached device token.
+    - That cached-token retry reuses the cached scope set stored with the paired device token. Explicit `deviceToken` / explicit `scopes` callers keep their requested scope set instead.
+    - Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
+    - On the async Tailscale Serve Control UI path, failed attempts for the same `{scope, ip}` are serialized before the limiter records the failure. Two bad concurrent retries from the same client can therefore surface `retry later` on the second attempt instead of two plain mismatches.
+    - `too many failed authentication attempts (retry later)` from a browser-origin loopback client → repeated failures from that same normalized `Origin` are locked out temporarily; another localhost origin uses a separate bucket.
+    - repeated `unauthorized` after that retry → shared token/device token drift; refresh token config and re-approve/rotate device token if needed.
+    - `gateway connect failed:` → wrong host/port/url target.
+  </Accordion>
+</AccordionGroup>
 
 ### Auth detail codes quick map
 
@@ -200,11 +216,9 @@ Use `error.details.code` from the failed `connect` response to pick the next act
 | `AUTH_DEVICE_TOKEN_MISMATCH` | Cached per-device token is stale or revoked.                                                                                                                                                 | Rotate/re-approve device token using [devices CLI](/cli/devices), then reconnect.                                                                                                                                                                                                        |
 | `PAIRING_REQUIRED`           | Device identity needs approval. Check `error.details.reason` for `not-paired`, `scope-upgrade`, `role-upgrade`, or `metadata-upgrade`, and use `requestId` / `remediationHint` when present. | Approve pending request: `openclaw devices list` then `openclaw devices approve <requestId>`. Scope/role upgrades use the same flow after you review the requested access.                                                                                                               |
 
-Direct loopback backend RPCs authenticated with the shared gateway
-token/password should not depend on the CLI's paired-device scope baseline. If
-subagents or other internal calls still fail with `scope-upgrade`, verify the
-caller is using `client.id: "gateway-client"` and `client.mode: "backend"` and
-is not forcing an explicit `deviceIdentity` or device token.
+<Note>
+Direct loopback backend RPCs authenticated with the shared gateway token/password should not depend on the CLI's paired-device scope baseline. If subagents or other internal calls still fail with `scope-upgrade`, verify the caller is using `client.id: "gateway-client"` and `client.mode: "backend"` and is not forcing an explicit `deviceIdentity` or device token.
+</Note>
 
 Device auth v2 migration check:
 
@@ -216,24 +230,30 @@ openclaw gateway status
 
 If logs show nonce/signature errors, update the connecting client and verify it:
 
-1. waits for `connect.challenge`
-2. signs the challenge-bound payload
-3. sends `connect.params.device.nonce` with the same challenge nonce
+<Steps>
+  <Step title="Wait for connect.challenge">
+    Client waits for the gateway-issued `connect.challenge`.
+  </Step>
+  <Step title="Sign the payload">
+    Client signs the challenge-bound payload.
+  </Step>
+  <Step title="Send the device nonce">
+    Client sends `connect.params.device.nonce` with the same challenge nonce.
+  </Step>
+</Steps>
 
 If `openclaw devices rotate` / `revoke` / `remove` is denied unexpectedly:
 
-- paired-device token sessions can manage only **their own** device unless the
-  caller also has `operator.admin`
-- `openclaw devices rotate --scope ...` can only request operator scopes that
-  the caller session already holds
+- paired-device token sessions can manage only **their own** device unless the caller also has `operator.admin`
+- `openclaw devices rotate --scope ...` can only request operator scopes that the caller session already holds
 
 Related:
 
-- [Control UI](/web/control-ui)
 - [Configuration](/gateway/configuration) (gateway auth modes)
-- [Trusted proxy auth](/gateway/trusted-proxy-auth)
-- [Remote access](/gateway/remote)
+- [Control UI](/web/control-ui)
 - [Devices](/cli/devices)
+- [Remote access](/gateway/remote)
+- [Trusted proxy auth](/gateway/trusted-proxy-auth)
 
 ## Gateway service not running
 
@@ -255,12 +275,14 @@ Look for:
 - Extra launchd/systemd/schtasks installs when `--deep` is used.
 - `Other gateway-like services detected (best effort)` cleanup hints.
 
-Common signatures:
-
-- `Gateway start blocked: set gateway.mode=local` or `existing config is missing gateway.mode` → local gateway mode is not enabled, or the config file was clobbered and lost `gateway.mode`. Fix: set `gateway.mode="local"` in your config, or re-run `openclaw onboard --mode local` / `openclaw setup` to restamp the expected local-mode config. If you are running OpenClaw via Podman, the default config path is `~/.openclaw/openclaw.json`.
-- `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
-- `another gateway instance is already listening` / `EADDRINUSE` → port conflict.
-- `Other gateway-like services detected (best effort)` → stale or parallel launchd/systemd/schtasks units exist. Most setups should keep one gateway per machine; if you do need more than one, isolate ports + config/state/workspace. See [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
+<AccordionGroup>
+  <Accordion title="Common signatures">
+    - `Gateway start blocked: set gateway.mode=local` or `existing config is missing gateway.mode` → local gateway mode is not enabled, or the config file was clobbered and lost `gateway.mode`. Fix: set `gateway.mode="local"` in your config, or re-run `openclaw onboard --mode local` / `openclaw setup` to restamp the expected local-mode config. If you are running OpenClaw via Podman, the default config path is `~/.openclaw/openclaw.json`.
+    - `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
+    - `another gateway instance is already listening` / `EADDRINUSE` → port conflict.
+    - `Other gateway-like services detected (best effort)` → stale or parallel launchd/systemd/schtasks units exist. Most setups should keep one gateway per machine; if you do need more than one, isolate ports + config/state/workspace. See [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
+  </Accordion>
+</AccordionGroup>
 
 Related:
 
@@ -287,46 +309,43 @@ Look for:
 - A timestamped `openclaw.json.clobbered.*` file beside the active config
 - A main-agent system event that starts with `Config recovery warning`
 
-What happened:
-
-- The rejected config did not validate during startup or hot reload.
-- OpenClaw preserved the rejected payload as `.clobbered.*`.
-- The active config was restored from the last validated last-known-good copy.
-- The next main-agent turn is warned not to blindly rewrite the rejected config.
-- If all validation issues were under `plugins.entries.<id>...`, OpenClaw would
-  not restore the whole file. Plugin-local failures stay loud while unrelated
-  user settings remain in the active config.
-
-Inspect and repair:
-
-```bash
-CONFIG="$(openclaw config file)"
-ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
-diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
-openclaw config validate
-openclaw doctor
-```
-
-Common signatures:
-
-- `.clobbered.*` exists → an external direct edit or startup read was restored.
-- `.rejected.*` exists → an OpenClaw-owned config write failed schema or clobber checks before commit.
-- `Config write rejected:` → the write tried to drop required shape, shrink the file sharply, or persist invalid config.
-- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good`, or `size-drop-vs-last-good:*` → startup treated the current file as clobbered because it lost fields or size compared with the last-known-good backup.
-- `Config last-known-good promotion skipped` → the candidate contained redacted secret placeholders such as `***`.
-
-Fix options:
-
-1. Keep the restored active config if it is correct.
-2. Copy only the intended keys from `.clobbered.*` or `.rejected.*`, then apply them with `openclaw config set` or `config.patch`.
-3. Run `openclaw config validate` before restarting.
-4. If you edit by hand, keep the full JSON5 config, not just the partial object you wanted to change.
+<AccordionGroup>
+  <Accordion title="What happened">
+    - The rejected config did not validate during startup or hot reload.
+    - OpenClaw preserved the rejected payload as `.clobbered.*`.
+    - The active config was restored from the last validated last-known-good copy.
+    - The next main-agent turn is warned not to blindly rewrite the rejected config.
+    - If all validation issues were under `plugins.entries.<id>...`, OpenClaw would not restore the whole file. Plugin-local failures stay loud while unrelated user settings remain in the active config.
+  </Accordion>
+  <Accordion title="Inspect and repair">
+    ```bash
+    CONFIG="$(openclaw config file)"
+    ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
+    diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
+    openclaw config validate
+    openclaw doctor
+    ```
+  </Accordion>
+  <Accordion title="Common signatures">
+    - `.clobbered.*` exists → an external direct edit or startup read was restored.
+    - `.rejected.*` exists → an OpenClaw-owned config write failed schema or clobber checks before commit.
+    - `Config write rejected:` → the write tried to drop required shape, shrink the file sharply, or persist invalid config.
+    - `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good`, or `size-drop-vs-last-good:*` → startup treated the current file as clobbered because it lost fields or size compared with the last-known-good backup.
+    - `Config last-known-good promotion skipped` → the candidate contained redacted secret placeholders such as `***`.
+  </Accordion>
+  <Accordion title="Fix options">
+    1. Keep the restored active config if it is correct.
+    2. Copy only the intended keys from `.clobbered.*` or `.rejected.*`, then apply them with `openclaw config set` or `config.patch`.
+    3. Run `openclaw config validate` before restarting.
+    4. If you edit by hand, keep the full JSON5 config, not just the partial object you wanted to change.
+  </Accordion>
+</AccordionGroup>
 
 Related:
 
-- [Configuration: strict validation](/gateway/configuration#strict-validation)
-- [Configuration: hot reload](/gateway/configuration#config-hot-reload)
 - [Config](/cli/config)
+- [Configuration: hot reload](/gateway/configuration#config-hot-reload)
+- [Configuration: strict validation](/gateway/configuration#strict-validation)
 - [Doctor](/gateway/doctor)
 
 ## Gateway probe warnings
@@ -358,7 +377,7 @@ Related:
 - [Multiple gateways on the same host](/gateway#multiple-gateways-same-host)
 - [Remote access](/gateway/remote)
 
-## Channel connected messages not flowing
+## Channel connected, messages not flowing
 
 If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules.
 
@@ -385,9 +404,9 @@ Common signatures:
 Related:
 
 - [Channel troubleshooting](/channels/troubleshooting)
-- [WhatsApp](/channels/whatsapp)
-- [Telegram](/channels/telegram)
 - [Discord](/channels/discord)
+- [Telegram](/channels/telegram)
+- [WhatsApp](/channels/whatsapp)
 
 ## Cron and heartbeat delivery
 
@@ -407,23 +426,25 @@ Look for:
 - Job run history status (`ok`, `skipped`, `error`).
 - Heartbeat skip reasons (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
 
-Common signatures:
-
-- `cron: scheduler disabled; jobs will not run automatically` → cron disabled.
-- `cron: timer tick failed` → scheduler tick failed; check file/log/runtime errors.
-- `heartbeat skipped` with `reason=quiet-hours` → outside active hours window.
-- `heartbeat skipped` with `reason=empty-heartbeat-file` → `HEARTBEAT.md` exists but only contains blank lines / markdown headers, so OpenClaw skips the model call.
-- `heartbeat skipped` with `reason=no-tasks-due` → `HEARTBEAT.md` contains a `tasks:` block, but none of the tasks are due on this tick.
-- `heartbeat: unknown accountId` → invalid account id for heartbeat delivery target.
-- `heartbeat skipped` with `reason=dm-blocked` → heartbeat target resolved to a DM-style destination while `agents.defaults.heartbeat.directPolicy` (or per-agent override) is set to `block`.
+<AccordionGroup>
+  <Accordion title="Common signatures">
+    - `cron: scheduler disabled; jobs will not run automatically` → cron disabled.
+    - `cron: timer tick failed` → scheduler tick failed; check file/log/runtime errors.
+    - `heartbeat skipped` with `reason=quiet-hours` → outside active hours window.
+    - `heartbeat skipped` with `reason=empty-heartbeat-file` → `HEARTBEAT.md` exists but only contains blank lines / markdown headers, so OpenClaw skips the model call.
+    - `heartbeat skipped` with `reason=no-tasks-due` → `HEARTBEAT.md` contains a `tasks:` block, but none of the tasks are due on this tick.
+    - `heartbeat: unknown accountId` → invalid account id for heartbeat delivery target.
+    - `heartbeat skipped` with `reason=dm-blocked` → heartbeat target resolved to a DM-style destination while `agents.defaults.heartbeat.directPolicy` (or per-agent override) is set to `block`.
+  </Accordion>
+</AccordionGroup>
 
 Related:
 
-- [Scheduled tasks: troubleshooting](/automation/cron-jobs#troubleshooting)
-- [Scheduled tasks](/automation/cron-jobs)
 - [Heartbeat](/gateway/heartbeat)
+- [Scheduled tasks](/automation/cron-jobs)
+- [Scheduled tasks: troubleshooting](/automation/cron-jobs#troubleshooting)
 
-## Node paired tool fails
+## Node paired, tool fails
 
 If a node is paired but tools fail, isolate foreground, permission, and approval state.
 
@@ -450,9 +471,9 @@ Common signatures:
 
 Related:
 
+- [Exec approvals](/tools/exec-approvals)
 - [Node troubleshooting](/nodes/troubleshooting)
 - [Nodes](/nodes/index)
-- [Exec approvals](/tools/exec-approvals)
 
 ## Browser tool fails
 
@@ -473,95 +494,104 @@ Look for:
 - CDP profile reachability.
 - Local Chrome availability for `existing-session` / `user` profiles.
 
-Common signatures:
-
-- `unknown command "browser"` or `unknown command 'browser'` → the bundled browser plugin is excluded by `plugins.allow`.
-- browser tool missing / unavailable while `browser.enabled=true` → `plugins.allow` excludes `browser`, so the plugin never loaded.
-- `Failed to start Chrome CDP on port` → browser process failed to launch.
-- `browser.executablePath not found` → configured path is invalid.
-- `browser.cdpUrl must be http(s) or ws(s)` → the configured CDP URL uses an unsupported scheme such as `file:` or `ftp:`.
-- `browser.cdpUrl has invalid port` → the configured CDP URL has a bad or out-of-range port.
-- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session could not attach to the selected browser data dir yet. Open the browser inspect page, enable remote debugging, keep the browser open, approve the first attach prompt, then retry. If signed-in state is not required, prefer the managed `openclaw` profile.
-- `No Chrome tabs found for profile="user"` → the Chrome MCP attach profile has no open local Chrome tabs.
-- `Remote CDP for profile "<name>" is not reachable` → the configured remote CDP endpoint is not reachable from the gateway host.
-- `Browser attachOnly is enabled ... not reachable` or `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile has no reachable target, or the HTTP endpoint answered but the CDP WebSocket still could not be opened.
-- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → the current gateway install lacks the bundled browser plugin's `playwright-core` runtime dependency; run `openclaw doctor --fix`, then restart the gateway. ARIA snapshots and basic page screenshots can still work, but navigation, AI snapshots, CSS-selector element screenshots, and PDF export stay unavailable.
-- `fullPage is not supported for element screenshots` → screenshot request mixed `--full-page` with `--ref` or `--element`.
-- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` screenshot calls must use page capture or a snapshot `--ref`, not CSS `--element`.
-- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP upload hooks need snapshot refs, not CSS selectors.
-- `existing-session file uploads currently support one file at a time.` → send one upload per call on Chrome MCP profiles.
-- `existing-session dialog handling does not support timeoutMs.` → dialog hooks on Chrome MCP profiles do not support timeout overrides.
-- `existing-session type does not support timeoutMs overrides.` → omit `timeoutMs` for `act:type` on `profile="user"` / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
-- `existing-session evaluate does not support timeoutMs overrides.` → omit `timeoutMs` for `act:evaluate` on `profile="user"` / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
-- `response body is not supported for existing-session profiles yet.` → `responsebody` still requires a managed browser or raw CDP profile.
-- stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run `openclaw browser stop --browser-profile <name>` to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway.
+<AccordionGroup>
+  <Accordion title="Plugin / executable signatures">
+    - `unknown command "browser"` or `unknown command 'browser'` → the bundled browser plugin is excluded by `plugins.allow`.
+    - browser tool missing / unavailable while `browser.enabled=true` → `plugins.allow` excludes `browser`, so the plugin never loaded.
+    - `Failed to start Chrome CDP on port` → browser process failed to launch.
+    - `browser.executablePath not found` → configured path is invalid.
+    - `browser.cdpUrl must be http(s) or ws(s)` → the configured CDP URL uses an unsupported scheme such as `file:` or `ftp:`.
+    - `browser.cdpUrl has invalid port` → the configured CDP URL has a bad or out-of-range port.
+    - `Playwright is not available in this gateway build; '<feature>' is unsupported.` → the current gateway install lacks the bundled browser plugin's `playwright-core` runtime dependency; run `openclaw doctor --fix`, then restart the gateway. ARIA snapshots and basic page screenshots can still work, but navigation, AI snapshots, CSS-selector element screenshots, and PDF export stay unavailable.
+  </Accordion>
+  <Accordion title="Chrome MCP / existing-session signatures">
+    - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session could not attach to the selected browser data dir yet. Open the browser inspect page, enable remote debugging, keep the browser open, approve the first attach prompt, then retry. If signed-in state is not required, prefer the managed `openclaw` profile.
+    - `No Chrome tabs found for profile="user"` → the Chrome MCP attach profile has no open local Chrome tabs.
+    - `Remote CDP for profile "<name>" is not reachable` → the configured remote CDP endpoint is not reachable from the gateway host.
+    - `Browser attachOnly is enabled ... not reachable` or `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile has no reachable target, or the HTTP endpoint answered but the CDP WebSocket still could not be opened.
+  </Accordion>
+  <Accordion title="Element / screenshot / upload signatures">
+    - `fullPage is not supported for element screenshots` → screenshot request mixed `--full-page` with `--ref` or `--element`.
+    - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` screenshot calls must use page capture or a snapshot `--ref`, not CSS `--element`.
+    - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP upload hooks need snapshot refs, not CSS selectors.
+    - `existing-session file uploads currently support one file at a time.` → send one upload per call on Chrome MCP profiles.
+    - `existing-session dialog handling does not support timeoutMs.` → dialog hooks on Chrome MCP profiles do not support timeout overrides.
+    - `existing-session type does not support timeoutMs overrides.` → omit `timeoutMs` for `act:type` on `profile="user"` / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
+    - `existing-session evaluate does not support timeoutMs overrides.` → omit `timeoutMs` for `act:evaluate` on `profile="user"` / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
+    - `response body is not supported for existing-session profiles yet.` → `responsebody` still requires a managed browser or raw CDP profile.
+    - stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run `openclaw browser stop --browser-profile <name>` to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway.
+  </Accordion>
+</AccordionGroup>
 
 Related:
 
-- [Browser troubleshooting](/tools/browser-linux-troubleshooting)
 - [Browser (OpenClaw-managed)](/tools/browser)
+- [Browser troubleshooting](/tools/browser-linux-troubleshooting)
 
 ## If you upgraded and something suddenly broke
 
 Most post-upgrade breakage is config drift or stricter defaults now being enforced.
 
-### 1) Auth and URL override behavior changed
+<AccordionGroup>
+  <Accordion title="1. Auth and URL override behavior changed">
+    ```bash
+    openclaw gateway status
+    openclaw config get gateway.mode
+    openclaw config get gateway.remote.url
+    openclaw config get gateway.auth.mode
+    ```
 
-```bash
-openclaw gateway status
-openclaw config get gateway.mode
-openclaw config get gateway.remote.url
-openclaw config get gateway.auth.mode
-```
+    What to check:
 
-What to check:
+    - If `gateway.mode=remote`, CLI calls may be targeting remote while your local service is fine.
+    - Explicit `--url` calls do not fall back to stored credentials.
 
-- If `gateway.mode=remote`, CLI calls may be targeting remote while your local service is fine.
-- Explicit `--url` calls do not fall back to stored credentials.
+    Common signatures:
 
-Common signatures:
+    - `gateway connect failed:` → wrong URL target.
+    - `unauthorized` → endpoint reachable but wrong auth.
 
-- `gateway connect failed:` → wrong URL target.
-- `unauthorized` → endpoint reachable but wrong auth.
+  </Accordion>
+  <Accordion title="2. Bind and auth guardrails are stricter">
+    ```bash
+    openclaw config get gateway.bind
+    openclaw config get gateway.auth.mode
+    openclaw config get gateway.auth.token
+    openclaw gateway status
+    openclaw logs --follow
+    ```
 
-### 2) Bind and auth guardrails are stricter
+    What to check:
 
-```bash
-openclaw config get gateway.bind
-openclaw config get gateway.auth.mode
-openclaw config get gateway.auth.token
-openclaw gateway status
-openclaw logs --follow
-```
+    - Non-loopback binds (`lan`, `tailnet`, `custom`) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopback `trusted-proxy` deployment.
+    - Old keys like `gateway.token` do not replace `gateway.auth.token`.
 
-What to check:
+    Common signatures:
 
-- Non-loopback binds (`lan`, `tailnet`, `custom`) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopback `trusted-proxy` deployment.
-- Old keys like `gateway.token` do not replace `gateway.auth.token`.
+    - `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path.
+    - `Connectivity probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url.
 
-Common signatures:
+  </Accordion>
+  <Accordion title="3. Pairing and device identity state changed">
+    ```bash
+    openclaw devices list
+    openclaw pairing list --channel <channel> [--account <id>]
+    openclaw logs --follow
+    openclaw doctor
+    ```
 
-- `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path.
-- `Connectivity probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url.
+    What to check:
 
-### 3) Pairing and device identity state changed
+    - Pending device approvals for dashboard/nodes.
+    - Pending DM pairing approvals after policy or identity changes.
 
-```bash
-openclaw devices list
-openclaw pairing list --channel <channel> [--account <id>]
-openclaw logs --follow
-openclaw doctor
-```
+    Common signatures:
 
-What to check:
+    - `device identity required` → device auth not satisfied.
+    - `pairing required` → sender/device must be approved.
 
-- Pending device approvals for dashboard/nodes.
-- Pending DM pairing approvals after policy or identity changes.
-
-Common signatures:
-
-- `device identity required` → device auth not satisfied.
-- `pairing required` → sender/device must be approved.
+  </Accordion>
+</AccordionGroup>
 
 If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory:
 
@@ -572,12 +602,12 @@ openclaw gateway restart
 
 Related:
 
-- [Gateway-owned pairing](/gateway/pairing)
 - [Authentication](/gateway/authentication)
 - [Background exec and process tool](/gateway/background-process)
+- [Gateway-owned pairing](/gateway/pairing)
 
 ## Related
 
-- [Gateway runbook](/gateway)
 - [Doctor](/gateway/doctor)
 - [FAQ](/help/faq)
+- [Gateway runbook](/gateway)

docs/help/testing.md

@@ -55,6 +55,15 @@ When debugging real providers/models (requires real creds):
     Slack DM with `/codex bind`, exercises `/codex fast` and
     `/codex permissions`, then verifies a plain reply and an image attachment
     route through the native plugin binding instead of ACP.
+- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness`
+  - Runs gateway agent turns through the plugin-owned Codex app-server harness,
+    verifies `/codex status` and `/codex models`, and by default exercises image,
+    cron MCP, sub-agent, and Guardian probes. Disable the sub-agent probe with
+    `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` when isolating other Codex
+    app-server failures. For a focused sub-agent check, disable the other probes:
+    `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`.
+    This exits after the sub-agent probe unless
+    `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` is set.
 - Crestodian rescue command smoke: `pnpm test:live:crestodian-rescue-channel`
   - Opt-in belt-and-suspenders check for the message-channel rescue command
     surface. It exercises `/crestodian status`, queues a persistent model
@@ -594,7 +603,7 @@ These Docker runners split into two buckets:
   `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Override those env vars when you
   explicitly want the larger exhaustive scan.
 - `test:docker:all` builds the live Docker image once via `test:docker:live-build`, then reuses it for the live Docker lanes. It also builds one shared `scripts/e2e/Dockerfile` image via `test:docker:e2e-build` and reuses it for the E2E container smoke runners that exercise the built app. The aggregate uses a weighted local scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` controls process slots, while resource caps keep heavy live, npm-install, and multi-service lanes from all starting at once. Defaults are 10 slots, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8`, and `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; tune `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` or `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` only when the Docker host has more headroom. The runner performs a Docker preflight by default, removes stale OpenClaw E2E containers, prints status every 30 seconds, stores successful lane timings in `.artifacts/docker-tests/lane-timings.json`, and uses those timings to start longer lanes first on later runs. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` to print the weighted lane manifest without building or running Docker.
-- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, and `test:docker:config-reload` boot one or more real containers and verify higher-level integration paths.
+- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, and `test:docker:config-reload` boot one or more real containers and verify higher-level integration paths.
 
 The live-model Docker runners also bind-mount only the needed CLI auth homes (or all supported ones when the run is not narrowed), then copy them into the container home before the run so external-CLI OAuth can refresh tokens without mutating the host auth store:
 
@@ -612,6 +621,7 @@ The live-model Docker runners also bind-mount only the needed CLI auth homes (or
 - Install Smoke CI skips the duplicate direct-npm global update with `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; run the script locally without that env when direct `npm install -g` coverage is needed.
 - Agents delete shared workspace CLI smoke: `pnpm test:docker:agents-delete-shared-workspace` (script: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) builds the root Dockerfile image by default, seeds two agents with one workspace in an isolated container home, runs `agents delete --json`, and verifies valid JSON plus retained workspace behavior. Reuse the install-smoke image with `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`.
 - Gateway networking (two containers, WS auth + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`)
+- Browser CDP snapshot smoke: `pnpm test:docker:browser-cdp-snapshot` (script: `scripts/e2e/browser-cdp-snapshot-docker.sh`) builds the source E2E image plus a Chromium layer, starts Chromium with raw CDP, runs `browser doctor --deep`, and verifies CDP role snapshots cover link URLs, cursor-promoted clickables, iframe refs, and frame metadata.
 - OpenAI Responses web_search minimal reasoning regression: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) runs a mocked OpenAI server through Gateway, verifies `web_search` raises `reasoning.effort` from `minimal` to `low`, then forces the provider schema reject and checks the raw detail appears in Gateway logs.
 - MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`)
 - Pi bundle MCP tools (real stdio MCP server + embedded Pi profile allow/deny smoke): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`)

docs/install/docker.md

@@ -131,6 +131,7 @@ The setup script accepts these optional environment variables:
 | `OPENCLAW_HOME_VOLUME`         | Persist `/home/node` in a named Docker volume                   |
 | `OPENCLAW_SANDBOX`             | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`)          |
 | `OPENCLAW_DOCKER_SOCKET`       | Override Docker socket path                                     |
+| `OPENCLAW_DISABLE_BONJOUR`     | Disable Bonjour/mDNS advertising (defaults to `1` for Docker)   |
 
 ### Health checks
 
@@ -165,6 +166,19 @@ Use bind mode values in `gateway.bind` (`lan` / `loopback` / `custom` /
 `tailnet` / `auto`), not host aliases like `0.0.0.0` or `127.0.0.1`.
 </Note>
 
+### Bonjour / mDNS
+
+Docker bridge networking usually does not forward Bonjour/mDNS multicast
+(`224.0.0.251:5353`) reliably. The bundled Compose setup therefore defaults
+`OPENCLAW_DISABLE_BONJOUR=1` so the Gateway does not crash-loop or repeatedly
+restart advertising when the bridge drops multicast traffic.
+
+Use the published Gateway URL, Tailscale, or wide-area DNS-SD for Docker hosts.
+Set `OPENCLAW_DISABLE_BONJOUR=0` only when running with host networking, macvlan,
+or another network where mDNS multicast is known to work.
+
+For gotchas and troubleshooting, see [Bonjour discovery](/gateway/bonjour).
+
 ### Storage and persistence
 
 Docker Compose bind-mounts `OPENCLAW_CONFIG_DIR` to `/home/node/.openclaw` and

docs/install/installer.md

@@ -292,6 +292,9 @@ by default, plus git-checkout installs under the same prefix flow.
     - Refreshes a loaded gateway service best-effort (`openclaw gateway install --force`, then restart)
     - Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort)
   </Step>
+  <Step title="Handle failures">
+    `iwr ... | iex` and scriptblock installs report a terminating error without closing the current PowerShell session. Direct `powershell -File` / `pwsh -File` installs still exit non-zero for automation.
+  </Step>
 </Steps>
 
 ### Examples (install.ps1)

docs/install/updating.md

@@ -79,12 +79,20 @@ ignores user npm prefix/global settings, so global-install npm config does not
 redirect bundled plugin dependencies into `~/node_modules` or the global package
 tree.
 
+Before package updates and bundled runtime-dependency repairs, OpenClaw tries a
+best-effort disk-space check for the target volume. Low space produces a warning
+with the checked path, but does not block the update because filesystem quotas,
+snapshots, and network volumes can change after the check. The actual npm
+install, copy, and post-install verification remain authoritative.
+
 ### Bundled plugin runtime dependencies
 
 Packaged installs keep bundled plugin runtime dependencies out of the read-only
 package tree. On startup and during `openclaw doctor --fix`, OpenClaw repairs
 runtime dependencies only for bundled plugins that are active in config, active
 through legacy channel config, or enabled by their bundled manifest default.
+Persisted channel auth state alone does not trigger Gateway startup
+runtime-dependency repair.
 
 Explicit disablement wins. A disabled plugin or channel does not get its
 runtime dependencies repaired just because it exists in the package. External

docs/logging.md

@@ -23,6 +23,11 @@ By default, the Gateway writes a rolling log file under:
 
 The date uses the gateway host's local timezone.
 
+Each file rotates when it reaches `logging.maxFileBytes` (default: 100 MB).
+OpenClaw keeps up to five numbered archives beside the active file, such as
+`openclaw-YYYY-MM-DD.1.log`, and keeps writing to a fresh active log instead of
+suppressing diagnostics.
+
 You can override this in `~/.openclaw/openclaw.json`:
 
 ```json
@@ -167,7 +172,9 @@ Tool summaries can redact sensitive tokens before they hit the console:
 - `logging.redactSensitive`: `off` | `tools` (default: `tools`)
 - `logging.redactPatterns`: list of regex strings to override the default set
 
-Redaction affects **console output only** and does not alter file logs.
+Redaction applies at the logging sinks for **console output**, **stderr-routed
+console diagnostics**, and **file logs**. File logs stay JSONL, but matching
+secret values are masked before the line is written to disk.
 
 ## Diagnostics and OpenTelemetry
 

docs/nodes/index.md

@@ -12,7 +12,11 @@ A **node** is a companion device (macOS/iOS/Android/headless) that connects to t
 Legacy transport: [Bridge protocol](/gateway/bridge-protocol) (TCP JSONL;
 historical only for current nodes).
 
-macOS can also run in **node mode**: the menubar app connects to the Gateway’s WS server and exposes its local canvas/camera commands as a node (so `openclaw nodes …` works against this Mac).
+macOS can also run in **node mode**: the menubar app connects to the Gateway’s
+WS server and exposes its local canvas/camera commands as a node (so
+`openclaw nodes …` works against this Mac). In remote gateway mode, browser
+automation is handled by the CLI node host (`openclaw node run` or the
+installed node service), not by the native app node.
 
 Notes:
 
@@ -112,6 +116,7 @@ Notes:
 
 ```bash
 openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
+openclaw node start
 openclaw node restart
 ```
 

docs/nodes/media-understanding.md

@@ -130,7 +130,7 @@ Recommended defaults:
 Rules:
 
 - If media exceeds `maxBytes`, that model is skipped and the **next model is tried**.
-- Audio files smaller than **1024 bytes** are treated as empty/corrupt and skipped before provider/CLI transcription.
+- Audio files smaller than **1024 bytes** are treated as empty/corrupt and skipped before provider/CLI transcription; inbound reply context receives a deterministic placeholder transcript so the agent knows the note was too small.
 - If the model returns more than `maxChars`, output is trimmed.
 - `prompt` defaults to simple “Describe the {media}.” plus the `maxChars` guidance (image/video only).
 - If the active primary image model already supports vision natively, OpenClaw

docs/nodes/voicewake.md

@@ -37,9 +37,32 @@ Notes:
 - Triggers are normalized (trimmed, empties dropped). Empty lists fall back to defaults.
 - Limits are enforced for safety (count/length caps).
 
+### Routing methods (trigger → target)
+
+- `voicewake.routing.get` → `{ config: VoiceWakeRoutingConfig }`
+- `voicewake.routing.set` with params `{ config: VoiceWakeRoutingConfig }` → `{ config: VoiceWakeRoutingConfig }`
+
+`VoiceWakeRoutingConfig` shape:
+
+```json
+{
+  "version": 1,
+  "defaultTarget": { "mode": "current" },
+  "routes": [{ "trigger": "robot wake", "target": { "sessionKey": "agent:main:main" } }],
+  "updatedAtMs": 1730000000000
+}
+```
+
+Route targets support exactly one of:
+
+- `{ "mode": "current" }`
+- `{ "agentId": "main" }`
+- `{ "sessionKey": "agent:main:main" }`
+
 ### Events
 
 - `voicewake.changed` payload `{ triggers: string[] }`
+- `voicewake.routing.changed` payload `{ config: VoiceWakeRoutingConfig }`
 
 Who receives it:
 

docs/platforms/mac/remote.md

@@ -22,6 +22,18 @@ Remote mode supports two transports:
 - **SSH tunnel** (default): Uses `ssh -N -L ...` to forward the gateway port to localhost. The gateway will see the node’s IP as `127.0.0.1` because the tunnel is loopback.
 - **Direct (ws/wss)**: Connects straight to the gateway URL. The gateway sees the real client IP.
 
+In SSH tunnel mode, discovered LAN/tailnet hostnames are saved as
+`gateway.remote.sshTarget`. The app keeps `gateway.remote.url` on the local
+tunnel endpoint, for example `ws://127.0.0.1:18789`, so CLI, Web Chat, and
+the local node-host service all use the same safe loopback transport.
+
+Browser automation in remote mode is owned by the CLI node host, not by the
+native macOS app node. The app starts the installed node host service when
+possible; if you need browser control from that Mac, install/start it with
+`openclaw node install ...` and `openclaw node start` (or run
+`openclaw node run ...` in the foreground), then target that browser-capable
+node.
+
 ## Prereqs on the remote host
 
 1. Install Node + pnpm and build/install the OpenClaw CLI (`pnpm install && pnpm build && pnpm link --global`).

docs/plugins/architecture-internals.md

@@ -72,8 +72,8 @@ or fallback behavior without changing runtime loading semantics.
 Setup discovery now prefers descriptor-owned ids such as `setup.providers` and
 `setup.cliBackends` to narrow candidate plugins before it falls back to
 `setup-api` for plugins that still need setup-time runtime hooks. Provider
-setup flow uses manifest `providerAuthChoices` first, then falls back to
-runtime wizard choices and install-catalog choices for compatibility. Explicit
+setup lists use manifest `providerAuthChoices`, descriptor-derived setup
+choices, and install-catalog metadata without loading provider runtime. Explicit
 `setup.requiresRuntime: false` is a descriptor-only cutoff; omitted
 `requiresRuntime` keeps the legacy setup-api fallback for compatibility. If more
 than one discovered plugin claims the same normalized setup provider or CLI

docs/plugins/codex-harness.md

@@ -20,6 +20,27 @@ If you are trying to orient yourself, start with
 `openai/gpt-5.5` is the model ref, `codex` is the runtime, and Telegram,
 Discord, Slack, or another channel remains the communication surface.
 
+## What this plugin changes
+
+The bundled `codex` plugin contributes several separate capabilities:
+
+| Capability                        | How you use it                                      | What it does                                                                  |
+| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Native embedded runtime           | `embeddedHarness.runtime: "codex"`                  | Runs OpenClaw embedded agent turns through Codex app-server.                  |
+| Native chat-control commands      | `/codex bind`, `/codex resume`, `/codex steer`, ... | Binds and controls Codex app-server threads from a messaging conversation.    |
+| Codex app-server provider/catalog | `codex` internals, surfaced through the harness     | Lets the runtime discover and validate app-server models.                     |
+| Codex media-understanding path    | `codex/*` image-model compatibility paths           | Runs bounded Codex app-server turns for supported image understanding models. |
+| Native hook relay                 | Plugin hooks around Codex-native events             | Lets OpenClaw observe/block supported Codex-native tool/finalization events.  |
+
+Enabling the plugin makes those capabilities available. It does **not**:
+
+- start using Codex for every OpenAI model
+- convert `openai-codex/*` model refs into the native runtime
+- make ACP/acpx the default Codex path
+- hot-switch existing sessions that already recorded a PI runtime
+- replace OpenClaw channel delivery, session files, auth-profile storage, or
+  message routing
+
 The same plugin also owns the native `/codex` chat-control command surface. If
 the plugin is enabled and the user asks to bind, resume, steer, stop, or inspect
 Codex threads from chat, agents should prefer `/codex ...` over ACP. ACP remains
@@ -53,6 +74,32 @@ want native app-server execution. Legacy `codex/*` model refs still auto-select
 the harness for compatibility, but runtime-backed legacy provider prefixes are
 not shown as normal model/provider choices.
 
+If the `codex` plugin is enabled but the primary model is still
+`openai-codex/*`, `openclaw doctor` warns instead of changing the route. That is
+intentional: `openai-codex/*` remains the PI Codex OAuth/subscription path, and
+native app-server execution stays an explicit runtime choice.
+
+## Route map
+
+Use this table before changing config:
+
+| Desired behavior                            | Model ref                  | Runtime config                         | Plugin requirement          | Expected status label          |
+| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ |
+| OpenAI API through normal OpenClaw runner   | `openai/gpt-*`             | omitted or `runtime: "pi"`             | OpenAI provider             | `Runtime: OpenClaw Pi Default` |
+| Codex OAuth/subscription through PI         | `openai-codex/gpt-*`       | omitted or `runtime: "pi"`             | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` |
+| Native Codex app-server embedded turns      | `openai/gpt-*`             | `embeddedHarness.runtime: "codex"`     | `codex` plugin              | `Runtime: OpenAI Codex`        |
+| Mixed providers with conservative auto mode | provider-specific refs     | `runtime: "auto", fallback: "pi"`      | Optional plugin runtimes    | Depends on selected runtime    |
+| Explicit Codex ACP adapter session          | ACP prompt/model dependent | `sessions_spawn` with `runtime: "acp"` | healthy `acpx` backend      | ACP task/session status        |
+
+The important split is provider versus runtime:
+
+- `openai-codex/*` answers "which provider/auth route should PI use?"
+- `embeddedHarness.runtime: "codex"` answers "which loop should execute this
+  embedded turn?"
+- `/codex ...` answers "which native Codex conversation should this chat bind
+  or control?"
+- ACP answers "which external harness process should acpx launch?"
+
 ## Pick the right model prefix
 
 OpenAI-family routes are prefix-specific. Use `openai-codex/*` when you want
@@ -91,6 +138,25 @@ and inspect the gateway's structured `agent harness selected` record. It
 includes the selected harness id, selection reason, runtime/fallback policy, and,
 in `auto` mode, each plugin candidate's support result.
 
+### What doctor warnings mean
+
+`openclaw doctor` warns when all of these are true:
+
+- the bundled `codex` plugin is enabled or allowed
+- an agent's primary model is `openai-codex/*`
+- that agent's effective runtime is not `codex`
+
+That warning exists because users often expect "Codex plugin enabled" to imply
+"native Codex app-server runtime." OpenClaw does not make that leap. The warning
+means:
+
+- **No change is required** if you intended ChatGPT/Codex OAuth through PI.
+- Change the model to `openai/<model>` and set
+  `embeddedHarness.runtime: "codex"` if you intended native app-server
+  execution.
+- Existing sessions still need `/new` or `/reset` after a runtime change,
+  because session runtime pins are sticky.
+
 Harness selection is not a live session control. When an embedded turn runs,
 OpenClaw records the selected harness id on that session and keeps using it for
 later turns in the same session id. Change `embeddedHarness` config or
@@ -227,6 +293,25 @@ With this shape:
 - If Codex is missing or unsupported for the `codex` agent, the turn fails
   instead of quietly using PI.
 
+## Agent command routing
+
+Agents should route user requests by intent, not by the word "Codex" alone:
+
+| User asks for...                                         | Agent should use...                              |
+| -------------------------------------------------------- | ------------------------------------------------ |
+| "Bind this chat to Codex"                                | `/codex bind`                                    |
+| "Resume Codex thread `<id>` here"                        | `/codex resume <id>`                             |
+| "Show Codex threads"                                     | `/codex threads`                                 |
+| "Use Codex as the runtime for this agent"                | config change to `embeddedHarness.runtime`       |
+| "Use my ChatGPT/Codex subscription with normal OpenClaw" | `openai-codex/*` model refs                      |
+| "Run Codex through ACP/acpx"                             | ACP `sessions_spawn({ runtime: "acp", ... })`    |
+| "Start Claude Code/Gemini/OpenCode/Cursor in a thread"   | ACP/acpx, not `/codex` and not native sub-agents |
+
+OpenClaw only advertises ACP spawn guidance to agents when ACP is enabled,
+dispatchable, and backed by a loaded runtime backend. If ACP is not available,
+the system prompt and plugin skills should not teach the agent about ACP
+routing.
+
 ## Codex-only deployments
 
 Force the Codex harness when you need to prove that every embedded agent turn

docs/plugins/hooks.md

@@ -112,8 +112,8 @@ observation-only.
 - `event.params`
 - optional `event.runId`
 - optional `event.toolCallId`
-- context fields such as `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, and
-  diagnostic `ctx.trace`
+- context fields such as `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`,
+  `ctx.runId`, `ctx.jobId` (set on cron-driven runs), and diagnostic `ctx.trace`
 
 It can return:
 
@@ -178,6 +178,9 @@ so your plugin does not depend on a legacy combined phase.
 
 `before_agent_start` and `agent_end` include `event.runId` when OpenClaw can
 identify the active run. The same value is also available on `ctx.runId`.
+Cron-driven runs also expose `ctx.jobId` (the originating cron job id) so
+plugin hooks can scope metrics, side effects, or state to a specific scheduled
+job.
 
 Use `model_call_started` and `model_call_ended` for provider-call telemetry
 that should not receive raw prompts, history, responses, headers, request

docs/plugins/manifest.md

@@ -169,8 +169,8 @@ or npm install metadata. Those belong in your plugin code and `package.json`.
 
 Each `providerAuthChoices` entry describes one onboarding or auth choice.
 OpenClaw reads this before provider runtime loads.
-Provider setup flow prefers these manifest choices, then falls back to runtime
-wizard metadata and install-catalog choices for compatibility.
+Provider setup lists use these manifest choices, descriptor-derived setup
+choices, and install-catalog metadata without loading provider runtime.
 
 | Field                 | Required | Type                                            | What it means                                                                                            |
 | --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
@@ -708,7 +708,7 @@ Model fields:
 | `api`           | `ModelApi`                                                     | Optional per-model API override.                                            |
 | `baseUrl`       | `string`                                                       | Optional per-model base URL override.                                       |
 | `headers`       | `Record<string, string>`                                       | Optional per-model static headers.                                          |
-| `input`         | `Array<"text" \| "image" \| "document">`                       | Modalities the model accepts.                                               |
+| `input`         | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Modalities the model accepts.                                               |
 | `reasoning`     | `boolean`                                                      | Whether the model exposes reasoning behavior.                               |
 | `contextWindow` | `number`                                                       | Native provider context window.                                             |
 | `contextTokens` | `number`                                                       | Optional effective runtime context cap when different from `contextWindow`. |
@@ -725,6 +725,37 @@ Do not put runtime-only data in `modelCatalog`. If a provider needs account
 state, an API request, or local process discovery to know the complete model
 set, declare that provider as `refreshable` or `runtime` in `discovery`.
 
+### OpenClaw Provider Index
+
+The OpenClaw Provider Index is OpenClaw-owned preview metadata for providers
+whose plugins may not be installed yet. It is not part of a plugin manifest.
+Plugin manifests remain the installed-plugin authority. The Provider Index is
+the internal fallback contract that future installable-provider and pre-install
+model picker surfaces will consume when a provider plugin is not installed.
+
+Catalog authority order:
+
+1. User config.
+2. Installed plugin manifest `modelCatalog`.
+3. Model catalog cache from explicit refresh.
+4. OpenClaw Provider Index preview rows.
+
+The Provider Index must not contain secrets, enabled state, runtime hooks, or
+live account-specific model data. Its preview catalogs use the same
+`modelCatalog` provider row shape as plugin manifests, but should stay limited
+to stable display metadata unless runtime adapter fields such as `api`,
+`baseUrl`, pricing, or compatibility flags are intentionally kept aligned with
+the installed plugin manifest. Providers with live `/models` discovery should
+write refreshed rows through the explicit model catalog cache path instead of
+making normal listing or onboarding call provider APIs.
+
+Provider Index entries may also carry installable-plugin metadata for providers
+whose plugin has moved out of core or is otherwise not installed yet. This
+metadata mirrors the channel catalog pattern: package name, npm install spec,
+expected integrity, and cheap auth-choice labels are enough to show an
+installable setup option. Once the plugin is installed, its manifest wins and
+the Provider Index entry is ignored for that provider.
+
 Legacy top-level capability keys are deprecated. Use `openclaw doctor --fix` to
 move `speechProviders`, `realtimeTranscriptionProviders`,
 `realtimeVoiceProviders`, `mediaUnderstandingProviders`,

docs/plugins/voice-call.md

@@ -1,63 +1,95 @@
 ---
-summary: "Voice Call plugin: outbound + inbound calls via Twilio/Telnyx/Plivo (plugin install + config + CLI)"
+summary: "Place outbound and accept inbound voice calls via Twilio, Telnyx, or Plivo, with optional realtime voice and streaming transcription"
 read_when:
   - You want to place an outbound voice call from OpenClaw
   - You are configuring or developing the voice-call plugin
+  - You need realtime voice or streaming transcription on telephony
 title: "Voice call plugin"
+sidebarTitle: "Voice call"
 ---
 
-Voice calls for OpenClaw via a plugin. Supports outbound notifications and
-multi-turn conversations with inbound policies.
+Voice calls for OpenClaw via a plugin. Supports outbound notifications,
+multi-turn conversations, full-duplex realtime voice, streaming
+transcription, and inbound calls with allowlist policies.
 
-Current providers:
+**Current providers:** `twilio` (Programmable Voice + Media Streams),
+`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
+speech), `mock` (dev/no network).
 
-- `twilio` (Programmable Voice + Media Streams)
-- `telnyx` (Call Control v2)
-- `plivo` (Voice API + XML transfer + GetInput speech)
-- `mock` (dev/no network)
+<Note>
+The Voice Call plugin runs **inside the Gateway process**. If you use a
+remote Gateway, install and configure the plugin on the machine running
+the Gateway, then restart the Gateway to load it.
+</Note>
 
-Quick mental model:
+## Quick start
 
-- Install plugin
-- Restart Gateway
-- Configure under `plugins.entries.voice-call.config`
-- Use `openclaw voicecall ...` or the `voice_call` tool
+<Steps>
+  <Step title="Install the plugin">
+    <Tabs>
+      <Tab title="From npm (recommended)">
+        ```bash
+        openclaw plugins install @openclaw/voice-call
+        ```
+      </Tab>
+      <Tab title="From a local folder (dev)">
+        ```bash
+        PLUGIN_SRC=./path/to/local/voice-call-plugin
+        openclaw plugins install "$PLUGIN_SRC"
+        cd "$PLUGIN_SRC" && pnpm install
+        ```
+      </Tab>
+    </Tabs>
 
-## Where it runs (local vs remote)
+    Restart the Gateway afterwards so the plugin loads.
 
-The Voice Call plugin runs **inside the Gateway process**.
+  </Step>
+  <Step title="Configure provider and webhook">
+    Set config under `plugins.entries.voice-call.config` (see
+    [Configuration](#configuration) below for the full shape). At minimum:
+    `provider`, provider credentials, `fromNumber`, and a publicly
+    reachable webhook URL.
+  </Step>
+  <Step title="Verify setup">
+    ```bash
+    openclaw voicecall setup
+    ```
 
-If you use a remote Gateway, install/configure the plugin on the **machine running the Gateway**, then restart the Gateway to load it.
+    The default output is readable in chat logs and terminals. It checks
+    plugin enablement, provider credentials, webhook exposure, and that
+    only one audio mode (`streaming` or `realtime`) is active. Use
+    `--json` for scripts.
 
-## Install
+  </Step>
+  <Step title="Smoke test">
+    ```bash
+    openclaw voicecall smoke
+    openclaw voicecall smoke --to "+15555550123"
+    ```
 
-### Option A: install from npm (recommended)
+    Both are dry runs by default. Add `--yes` to actually place a short
+    outbound notify call:
 
-```bash
-openclaw plugins install @openclaw/voice-call
-```
+    ```bash
+    openclaw voicecall smoke --to "+15555550123" --yes
+    ```
 
-Restart the Gateway afterwards.
+  </Step>
+</Steps>
 
-### Option B: install from a local folder (dev, no copying)
+<Warning>
+For Twilio, Telnyx, and Plivo, setup must resolve to a **public webhook URL**.
+If `publicUrl`, the tunnel URL, the Tailscale URL, or the serve fallback
+resolves to loopback or private network space, setup fails instead of
+starting a provider that cannot receive carrier webhooks.
+</Warning>
 
-```bash
-PLUGIN_SRC=./path/to/local/voice-call-plugin
-openclaw plugins install "$PLUGIN_SRC"
-cd "$PLUGIN_SRC" && pnpm install
-```
+## Configuration
 
-Restart the Gateway afterwards.
-
-## Config
-
-Set config under `plugins.entries.voice-call.config`:
-
-If `enabled` is true but the selected provider is missing credentials, Gateway
-startup logs a setup-incomplete warning with the missing keys and skips starting
-the runtime. Run `openclaw voicecall setup` to see the same readiness details.
-Commands, RPC calls, and agent tools still return the exact missing provider
-configuration when used.
+If `enabled: true` but the selected provider is missing credentials,
+Gateway startup logs a setup-incomplete warning with the missing keys and
+skips starting the runtime. Commands, RPC calls, and agent tools still
+return the exact missing provider configuration when used.
 
 ```json5
 {
@@ -74,15 +106,13 @@ configuration when used.
             accountSid: "ACxxxxxxxx",
             authToken: "...",
           },
-
           telnyx: {
             apiKey: "...",
             connectionId: "...",
-            // Telnyx webhook public key from the Telnyx Mission Control Portal
-            // (Base64 string; can also be set via TELNYX_PUBLIC_KEY).
+            // Telnyx webhook public key from the Mission Control Portal
+            // (Base64; can also be set via TELNYX_PUBLIC_KEY).
             publicKey: "...",
           },
-
           plivo: {
             authId: "MAxxxxxxxxxxxxxxxxxxxx",
             authToken: "...",
@@ -103,41 +133,14 @@ configuration when used.
           // Public exposure (pick one)
           // publicUrl: "https://example.ngrok.app/voice/webhook",
           // tunnel: { provider: "ngrok" },
-          // tailscale: { mode: "funnel", path: "/voice/webhook" }
+          // tailscale: { mode: "funnel", path: "/voice/webhook" },
 
           outbound: {
             defaultMode: "notify", // notify | conversation
           },
 
-          streaming: {
-            enabled: true,
-            provider: "openai", // optional; first registered realtime transcription provider when unset
-            streamPath: "/voice/stream",
-            providers: {
-              openai: {
-                apiKey: "sk-...", // optional if OPENAI_API_KEY is set
-                model: "gpt-4o-transcribe",
-                silenceDurationMs: 800,
-                vadThreshold: 0.5,
-              },
-            },
-            preStartTimeoutMs: 5000,
-            maxPendingConnections: 32,
-            maxPendingConnectionsPerIp: 4,
-            maxConnections: 128,
-          },
-
-          realtime: {
-            enabled: false,
-            provider: "google", // optional; first registered realtime voice provider when unset
-            toolPolicy: "safe-read-only",
-            providers: {
-              google: {
-                model: "gemini-2.5-flash-native-audio-preview-12-2025",
-                voice: "Kore",
-              },
-            },
-          },
+          streaming: { enabled: true /* see Streaming transcription */ },
+          realtime: { enabled: false /* see Realtime voice */ },
         },
       },
     },
@@ -145,152 +148,135 @@ configuration when used.
 }
 ```
 
-Check setup before testing with a real provider:
+<AccordionGroup>
+  <Accordion title="Provider exposure and security notes">
+    - Twilio, Telnyx, and Plivo all require a **publicly reachable** webhook URL.
+    - `mock` is a local dev provider (no network calls).
+    - Telnyx requires `telnyx.publicKey` (or `TELNYX_PUBLIC_KEY`) unless `skipSignatureVerification` is true.
+    - `skipSignatureVerification` is for local testing only.
+    - On ngrok free tier, set `publicUrl` to the exact ngrok URL; signature verification is always enforced.
+    - `tunnel.allowNgrokFreeTierLoopbackBypass: true` allows Twilio webhooks with invalid signatures **only** when `tunnel.provider="ngrok"` and `serve.bind` is loopback (ngrok local agent). Local dev only.
+    - Ngrok free-tier URLs can change or add interstitial behaviour; if `publicUrl` drifts, Twilio signatures fail. Production: prefer a stable domain or a Tailscale funnel.
+  </Accordion>
+  <Accordion title="Streaming connection caps">
+    - `streaming.preStartTimeoutMs` closes sockets that never send a valid `start` frame.
+    - `streaming.maxPendingConnections` caps total unauthenticated pre-start sockets.
+    - `streaming.maxPendingConnectionsPerIp` caps unauthenticated pre-start sockets per source IP.
+    - `streaming.maxConnections` caps total open media stream sockets (pending + active).
+  </Accordion>
+  <Accordion title="Legacy config migrations">
+    Older configs using `provider: "log"`, `twilio.from`, or legacy
+    `streaming.*` OpenAI keys are rewritten by `openclaw doctor --fix`.
+    Runtime fallback still accepts the old voice-call keys for now, but
+    the rewrite path is `openclaw doctor --fix` and the compat shim is
+    temporary.
 
-```bash
-openclaw voicecall setup
-```
+    Auto-migrated streaming keys:
 
-The default output is readable in chat logs and terminal sessions. It checks
-whether the plugin is enabled, the provider and credentials are present, webhook
-exposure is configured, and only one audio mode is active. Use
-`openclaw voicecall setup --json` for scripts.
+    - `streaming.sttProvider` → `streaming.provider`
+    - `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
+    - `streaming.sttModel` → `streaming.providers.openai.model`
+    - `streaming.silenceDurationMs` → `streaming.providers.openai.silenceDurationMs`
+    - `streaming.vadThreshold` → `streaming.providers.openai.vadThreshold`
 
-For Twilio, Telnyx, and Plivo, setup must resolve to a public webhook URL. If the
-configured `publicUrl`, tunnel URL, Tailscale URL, or serve fallback resolves to
-loopback or private network space, setup fails instead of starting a provider
-that cannot receive real carrier webhooks.
-
-For a no-surprises smoke test, run:
-
-```bash
-openclaw voicecall smoke
-openclaw voicecall smoke --to "+15555550123"
-```
-
-The second command is still a dry run. Add `--yes` to place a short outbound
-notify call:
-
-```bash
-openclaw voicecall smoke --to "+15555550123" --yes
-```
-
-Notes:
-
-- Twilio/Telnyx require a **publicly reachable** webhook URL.
-- Plivo requires a **publicly reachable** webhook URL.
-- `mock` is a local dev provider (no network calls).
-- If older configs still use `provider: "log"`, `twilio.from`, or legacy `streaming.*` OpenAI keys, run `openclaw doctor --fix` to rewrite them.
-- Telnyx requires `telnyx.publicKey` (or `TELNYX_PUBLIC_KEY`) unless `skipSignatureVerification` is true.
-- `skipSignatureVerification` is for local testing only.
-- If you use ngrok free tier, set `publicUrl` to the exact ngrok URL; signature verification is always enforced.
-- `tunnel.allowNgrokFreeTierLoopbackBypass: true` allows Twilio webhooks with invalid signatures **only** when `tunnel.provider="ngrok"` and `serve.bind` is loopback (ngrok local agent). Use for local dev only.
-- Ngrok free tier URLs can change or add interstitial behavior; if `publicUrl` drifts, Twilio signatures will fail. For production, prefer a stable domain or Tailscale funnel.
-- `realtime.enabled` starts full voice-to-voice conversations; do not enable it together with `streaming.enabled`.
-- Streaming security defaults:
-  - `streaming.preStartTimeoutMs` closes sockets that never send a valid `start` frame.
-- `streaming.maxPendingConnections` caps total unauthenticated pre-start sockets.
-- `streaming.maxPendingConnectionsPerIp` caps unauthenticated pre-start sockets per source IP.
-- `streaming.maxConnections` caps total open media stream sockets (pending + active).
-- Runtime fallback still accepts those old voice-call keys for now, but the rewrite path is `openclaw doctor --fix` and the compat shim is temporary.
+  </Accordion>
+</AccordionGroup>
 
 ## Realtime voice conversations
 
-`realtime` selects a full duplex realtime voice provider for live call audio.
-It is separate from `streaming`, which only forwards audio to realtime
-transcription providers.
+`realtime` selects a full-duplex realtime voice provider for live call
+audio. It is separate from `streaming`, which only forwards audio to
+realtime transcription providers.
 
-Current runtime behavior:
+<Warning>
+`realtime.enabled` cannot be combined with `streaming.enabled`. Pick one
+audio mode per call.
+</Warning>
+
+Current runtime behaviour:
 
 - `realtime.enabled` is supported for Twilio Media Streams.
-- `realtime.enabled` cannot be combined with `streaming.enabled`.
-- `realtime.provider` is optional. If unset, Voice Call uses the first
-  registered realtime voice provider.
-- Bundled realtime voice providers include Google Gemini Live (`google`) and
-  OpenAI (`openai`), registered by their provider plugins.
+- `realtime.provider` is optional. If unset, Voice Call uses the first registered realtime voice provider.
+- Bundled realtime voice providers: Google Gemini Live (`google`) and OpenAI (`openai`), registered by their provider plugins.
 - Provider-owned raw config lives under `realtime.providers.<providerId>`.
-- Voice Call exposes the shared `openclaw_agent_consult` realtime tool by
-  default. The realtime model can call it when the caller asks for deeper
-  reasoning, current information, or normal OpenClaw tools.
-- `realtime.toolPolicy` controls the consult run:
-  - `safe-read-only`: expose the consult tool and limit the regular agent to
-    `read`, `web_search`, `web_fetch`, `x_search`, `memory_search`, and
-    `memory_get`.
-  - `owner`: expose the consult tool and let the regular agent use the normal
-    agent tool policy.
-  - `none`: do not expose the consult tool. Custom `realtime.tools` are still
-    passed through to the realtime provider.
-- Consult session keys reuse the existing voice session when available, then
-  fall back to the caller/callee phone number so follow-up consult calls keep
-  context during the call.
-- If `realtime.provider` points at an unregistered provider, or no realtime
-  voice provider is registered at all, Voice Call logs a warning and skips
-  realtime media instead of failing the whole plugin.
+- Voice Call exposes the shared `openclaw_agent_consult` realtime tool by default. The realtime model can call it when the caller asks for deeper reasoning, current information, or normal OpenClaw tools.
+- If `realtime.provider` points at an unregistered provider, or no realtime voice provider is registered at all, Voice Call logs a warning and skips realtime media instead of failing the whole plugin.
+- Consult session keys reuse the existing voice session when available, then fall back to the caller/callee phone number so follow-up consult calls keep context during the call.
 
-Google Gemini Live realtime defaults:
+### Tool policy
 
-- API key: `realtime.providers.google.apiKey`, `GEMINI_API_KEY`, or
-  `GOOGLE_GENERATIVE_AI_API_KEY`
-- model: `gemini-2.5-flash-native-audio-preview-12-2025`
-- voice: `Kore`
+`realtime.toolPolicy` controls the consult run:
 
-Example:
+| Policy           | Behavior                                                                                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `safe-read-only` | Expose the consult tool and limit the regular agent to `read`, `web_search`, `web_fetch`, `x_search`, `memory_search`, and `memory_get`. |
+| `owner`          | Expose the consult tool and let the regular agent use the normal agent tool policy.                                                      |
+| `none`           | Do not expose the consult tool. Custom `realtime.tools` are still passed through to the realtime provider.                               |
 
-```json5
-{
-  plugins: {
-    entries: {
-      "voice-call": {
-        config: {
-          provider: "twilio",
-          inboundPolicy: "allowlist",
-          allowFrom: ["+15550005678"],
-          realtime: {
-            enabled: true,
-            provider: "google",
-            instructions: "Speak briefly. Call openclaw_agent_consult before using deeper tools.",
-            toolPolicy: "safe-read-only",
-            providers: {
-              google: {
-                apiKey: "${GEMINI_API_KEY}",
-                model: "gemini-2.5-flash-native-audio-preview-12-2025",
-                voice: "Kore",
+### Realtime provider examples
+
+<Tabs>
+  <Tab title="Google Gemini Live">
+    Defaults: API key from `realtime.providers.google.apiKey`,
+    `GEMINI_API_KEY`, or `GOOGLE_GENERATIVE_AI_API_KEY`; model
+    `gemini-2.5-flash-native-audio-preview-12-2025`; voice `Kore`.
+
+    ```json5
+    {
+      plugins: {
+        entries: {
+          "voice-call": {
+            config: {
+              provider: "twilio",
+              inboundPolicy: "allowlist",
+              allowFrom: ["+15550005678"],
+              realtime: {
+                enabled: true,
+                provider: "google",
+                instructions: "Speak briefly. Call openclaw_agent_consult before using deeper tools.",
+                toolPolicy: "safe-read-only",
+                providers: {
+                  google: {
+                    apiKey: "${GEMINI_API_KEY}",
+                    model: "gemini-2.5-flash-native-audio-preview-12-2025",
+                    voice: "Kore",
+                  },
+                },
               },
             },
           },
         },
       },
-    },
-  },
-}
-```
+    }
+    ```
 
-Use OpenAI instead:
-
-```json5
-{
-  plugins: {
-    entries: {
-      "voice-call": {
-        config: {
-          realtime: {
-            enabled: true,
-            provider: "openai",
-            providers: {
-              openai: {
-                apiKey: "${OPENAI_API_KEY}",
+  </Tab>
+  <Tab title="OpenAI">
+    ```json5
+    {
+      plugins: {
+        entries: {
+          "voice-call": {
+            config: {
+              realtime: {
+                enabled: true,
+                provider: "openai",
+                providers: {
+                  openai: { apiKey: "${OPENAI_API_KEY}" },
+                },
               },
             },
           },
         },
       },
-    },
-  },
-}
-```
+    }
+    ```
+  </Tab>
+</Tabs>
 
-See [Google provider](/providers/google) and [OpenAI provider](/providers/openai)
-for provider-specific realtime voice options.
+See [Google provider](/providers/google) and
+[OpenAI provider](/providers/openai) for provider-specific realtime voice
+options.
 
 ## Streaming transcription
 
@@ -298,173 +284,84 @@ for provider-specific realtime voice options.
 
 Current runtime behavior:
 
-- `streaming.provider` is optional. If unset, Voice Call uses the first
-  registered realtime transcription provider.
-- Bundled realtime transcription providers include Deepgram (`deepgram`),
-  ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`), and xAI
-  (`xai`), registered by their provider plugins.
+- `streaming.provider` is optional. If unset, Voice Call uses the first registered realtime transcription provider.
+- Bundled realtime transcription providers: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`), and xAI (`xai`), registered by their provider plugins.
 - Provider-owned raw config lives under `streaming.providers.<providerId>`.
-- If `streaming.provider` points at an unregistered provider, or no realtime
-  transcription provider is registered at all, Voice Call logs a warning and
-  skips media streaming instead of failing the whole plugin.
+- If `streaming.provider` points at an unregistered provider, or none is registered, Voice Call logs a warning and skips media streaming instead of failing the whole plugin.
 
-OpenAI streaming transcription defaults:
+### Streaming provider examples
 
-- API key: `streaming.providers.openai.apiKey` or `OPENAI_API_KEY`
-- model: `gpt-4o-transcribe`
-- `silenceDurationMs`: `800`
-- `vadThreshold`: `0.5`
+<Tabs>
+  <Tab title="OpenAI">
+    Defaults: API key `streaming.providers.openai.apiKey` or
+    `OPENAI_API_KEY`; model `gpt-4o-transcribe`; `silenceDurationMs: 800`;
+    `vadThreshold: 0.5`.
 
-xAI streaming transcription defaults:
-
-- API key: `streaming.providers.xai.apiKey` or `XAI_API_KEY`
-- endpoint: `wss://api.x.ai/v1/stt`
-- `encoding`: `mulaw`
-- `sampleRate`: `8000`
-- `endpointingMs`: `800`
-- `interimResults`: `true`
-
-Example:
-
-```json5
-{
-  plugins: {
-    entries: {
-      "voice-call": {
-        config: {
-          streaming: {
-            enabled: true,
-            provider: "openai",
-            streamPath: "/voice/stream",
-            providers: {
-              openai: {
-                apiKey: "sk-...", // optional if OPENAI_API_KEY is set
-                model: "gpt-4o-transcribe",
-                silenceDurationMs: 800,
-                vadThreshold: 0.5,
+    ```json5
+    {
+      plugins: {
+        entries: {
+          "voice-call": {
+            config: {
+              streaming: {
+                enabled: true,
+                provider: "openai",
+                streamPath: "/voice/stream",
+                providers: {
+                  openai: {
+                    apiKey: "sk-...", // optional if OPENAI_API_KEY is set
+                    model: "gpt-4o-transcribe",
+                    silenceDurationMs: 800,
+                    vadThreshold: 0.5,
+                  },
+                },
               },
             },
           },
         },
       },
-    },
-  },
-}
-```
+    }
+    ```
 
-Use xAI instead:
+  </Tab>
+  <Tab title="xAI">
+    Defaults: API key `streaming.providers.xai.apiKey` or `XAI_API_KEY`;
+    endpoint `wss://api.x.ai/v1/stt`; encoding `mulaw`; sample rate `8000`;
+    `endpointingMs: 800`; `interimResults: true`.
 
-```json5
-{
-  plugins: {
-    entries: {
-      "voice-call": {
-        config: {
-          streaming: {
-            enabled: true,
-            provider: "xai",
-            streamPath: "/voice/stream",
-            providers: {
-              xai: {
-                apiKey: "${XAI_API_KEY}", // optional if XAI_API_KEY is set
-                endpointingMs: 800,
-                language: "en",
+    ```json5
+    {
+      plugins: {
+        entries: {
+          "voice-call": {
+            config: {
+              streaming: {
+                enabled: true,
+                provider: "xai",
+                streamPath: "/voice/stream",
+                providers: {
+                  xai: {
+                    apiKey: "${XAI_API_KEY}", // optional if XAI_API_KEY is set
+                    endpointingMs: 800,
+                    language: "en",
+                  },
+                },
               },
             },
           },
         },
       },
-    },
-  },
-}
-```
+    }
+    ```
 
-Legacy keys are still auto-migrated by `openclaw doctor --fix`:
-
-- `streaming.sttProvider` → `streaming.provider`
-- `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
-- `streaming.sttModel` → `streaming.providers.openai.model`
-- `streaming.silenceDurationMs` → `streaming.providers.openai.silenceDurationMs`
-- `streaming.vadThreshold` → `streaming.providers.openai.vadThreshold`
-
-## Stale call reaper
-
-Use `staleCallReaperSeconds` to end calls that never receive a terminal webhook
-(for example, notify-mode calls that never complete). The default is `0`
-(disabled).
-
-Recommended ranges:
-
-- **Production:** `120`–`300` seconds for notify-style flows.
-- Keep this value **higher than `maxDurationSeconds`** so normal calls can
-  finish. A good starting point is `maxDurationSeconds + 30–60` seconds.
-
-Example:
-
-```json5
-{
-  plugins: {
-    entries: {
-      "voice-call": {
-        config: {
-          maxDurationSeconds: 300,
-          staleCallReaperSeconds: 360,
-        },
-      },
-    },
-  },
-}
-```
-
-## Webhook Security
-
-When a proxy or tunnel sits in front of the Gateway, the plugin reconstructs the
-public URL for signature verification. These options control which forwarded
-headers are trusted.
-
-`webhookSecurity.allowedHosts` allowlists hosts from forwarding headers.
-
-`webhookSecurity.trustForwardingHeaders` trusts forwarded headers without an allowlist.
-
-`webhookSecurity.trustedProxyIPs` only trusts forwarded headers when the request
-remote IP matches the list.
-
-Webhook replay protection is enabled for Twilio and Plivo. Replayed valid webhook
-requests are acknowledged but skipped for side effects.
-
-Twilio conversation turns include a per-turn token in `<Gather>` callbacks, so
-stale/replayed speech callbacks cannot satisfy a newer pending transcript turn.
-
-Unauthenticated webhook requests are rejected before body reads when the
-provider's required signature headers are missing.
-
-The voice-call webhook uses the shared pre-auth body profile (64 KB / 5 seconds)
-plus a per-IP in-flight cap before signature verification.
-
-Example with a stable public host:
-
-```json5
-{
-  plugins: {
-    entries: {
-      "voice-call": {
-        config: {
-          publicUrl: "https://voice.example.com/voice/webhook",
-          webhookSecurity: {
-            allowedHosts: ["voice.example.com"],
-          },
-        },
-      },
-    },
-  },
-}
-```
+  </Tab>
+</Tabs>
 
 ## TTS for calls
 
-Voice Call uses the core `messages.tts` configuration for
-streaming speech on calls. You can override it under the plugin config with the
-**same shape** — it deep‑merges with `messages.tts`.
+Voice Call uses the core `messages.tts` configuration for streaming
+speech on calls. You can override it under the plugin config with the
+**same shape** — it deep-merges with `messages.tts`.
 
 ```json5
 {
@@ -480,21 +377,23 @@ streaming speech on calls. You can override it under the plugin config with the
 }
 ```
 
-Notes:
+<Warning>
+**Microsoft speech is ignored for voice calls.** Telephony audio needs PCM;
+the current Microsoft transport does not expose telephony PCM output.
+</Warning>
+
+Behavior notes:
 
 - Legacy `tts.<provider>` keys inside plugin config (`openai`, `elevenlabs`, `microsoft`, `edge`) are repaired by `openclaw doctor --fix`; committed config should use `tts.providers.<provider>`.
-- **Microsoft speech is ignored for voice calls** (telephony audio needs PCM; the current Microsoft transport does not expose telephony PCM output).
-- Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider native voices.
+- Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider-native voices.
 - If a Twilio media stream is already active, Voice Call does not fall back to TwiML `<Say>`. If telephony TTS is unavailable in that state, the playback request fails instead of mixing two playback paths.
 - When telephony TTS falls back to a secondary provider, Voice Call logs a warning with the provider chain (`from`, `to`, `attempts`) for debugging.
-- When Twilio barge-in or stream teardown clears the pending TTS queue, queued
-  playback requests settle instead of hanging callers that are awaiting playback
-  completion.
+- When Twilio barge-in or stream teardown clears the pending TTS queue, queued playback requests settle instead of hanging callers awaiting playback completion.
 
-### More examples
-
-Use core TTS only (no override):
+### TTS examples
 
+<Tabs>
+  <Tab title="Core TTS only">
 ```json5
 {
   messages: {
@@ -507,9 +406,8 @@ Use core TTS only (no override):
   },
 }
 ```
-
-Override to ElevenLabs just for calls (keep core default elsewhere):
-
+  </Tab>
+  <Tab title="Override to ElevenLabs (calls only)">
 ```json5
 {
   plugins: {
@@ -532,9 +430,8 @@ Override to ElevenLabs just for calls (keep core default elsewhere):
   },
 }
 ```
-
-Override only the OpenAI model for calls (deep‑merge example):
-
+  </Tab>
+  <Tab title="OpenAI model override (deep-merge)">
 ```json5
 {
   plugins: {
@@ -555,6 +452,8 @@ Override only the OpenAI model for calls (deep‑merge example):
   },
 }
 ```
+  </Tab>
+</Tabs>
 
 ## Inbound calls
 
@@ -568,50 +467,122 @@ Inbound policy defaults to `disabled`. To enable inbound calls, set:
 }
 ```
 
-`inboundPolicy: "allowlist"` is a low-assurance caller-ID screen. The plugin
-normalizes the provider-supplied `From` value and compares it to `allowFrom`.
-Webhook verification authenticates provider delivery and payload integrity, but
-it does not prove PSTN/VoIP caller-number ownership. Treat `allowFrom` as
-caller-ID filtering, not strong caller identity.
+<Warning>
+`inboundPolicy: "allowlist"` is a low-assurance caller-ID screen. The
+plugin normalizes the provider-supplied `From` value and compares it to
+`allowFrom`. Webhook verification authenticates provider delivery and
+payload integrity, but it does **not** prove PSTN/VoIP caller-number
+ownership. Treat `allowFrom` as caller-ID filtering, not strong caller
+identity.
+</Warning>
 
-Auto-responses use the agent system. Tune with:
-
-- `responseModel`
-- `responseSystemPrompt`
-- `responseTimeoutMs`
+Auto-responses use the agent system. Tune with `responseModel`,
+`responseSystemPrompt`, and `responseTimeoutMs`.
 
 ### Spoken output contract
 
-For auto-responses, Voice Call appends a strict spoken-output contract to the system prompt:
+For auto-responses, Voice Call appends a strict spoken-output contract to
+the system prompt:
 
-- `{"spoken":"..."}`
+```text
+{"spoken":"..."}
+```
 
-Voice Call then extracts speech text defensively:
+Voice Call extracts speech text defensively:
 
 - Ignores payloads marked as reasoning/error content.
 - Parses direct JSON, fenced JSON, or inline `"spoken"` keys.
 - Falls back to plain text and removes likely planning/meta lead-in paragraphs.
 
-This keeps spoken playback focused on caller-facing text and avoids leaking planning text into audio.
+This keeps spoken playback focused on caller-facing text and avoids
+leaking planning text into audio.
 
 ### Conversation startup behavior
 
-For outbound `conversation` calls, first-message handling is tied to live playback state:
+For outbound `conversation` calls, first-message handling is tied to live
+playback state:
 
 - Barge-in queue clear and auto-response are suppressed only while the initial greeting is actively speaking.
 - If initial playback fails, the call returns to `listening` and the initial message remains queued for retry.
 - Initial playback for Twilio streaming starts on stream connect without extra delay.
-- Barge-in aborts active playback and clears queued-but-not-yet-playing Twilio
-  TTS entries. Cleared entries resolve as skipped, so follow-up response logic
-  can continue without waiting on audio that will never play.
-- Realtime voice conversations use the realtime stream's own opening turn. Voice Call does not post a legacy `<Say>` TwiML update for that initial message, so outbound `<Connect><Stream>` sessions stay attached.
+- Barge-in aborts active playback and clears queued-but-not-yet-playing Twilio TTS entries. Cleared entries resolve as skipped, so follow-up response logic can continue without waiting on audio that will never play.
+- Realtime voice conversations use the realtime stream's own opening turn. Voice Call does **not** post a legacy `<Say>` TwiML update for that initial message, so outbound `<Connect><Stream>` sessions stay attached.
 
 ### Twilio stream disconnect grace
 
-When a Twilio media stream disconnects, Voice Call waits `2000ms` before auto-ending the call:
+When a Twilio media stream disconnects, Voice Call waits **2000 ms** before
+auto-ending the call:
 
 - If the stream reconnects during that window, auto-end is canceled.
-- If no stream is re-registered after the grace period, the call is ended to prevent stuck active calls.
+- If no stream re-registers after the grace period, the call is ended to prevent stuck active calls.
+
+## Stale call reaper
+
+Use `staleCallReaperSeconds` to end calls that never receive a terminal
+webhook (for example, notify-mode calls that never complete). The default
+is `0` (disabled).
+
+Recommended ranges:
+
+- **Production:** `120`–`300` seconds for notify-style flows.
+- Keep this value **higher than `maxDurationSeconds`** so normal calls can finish. A good starting point is `maxDurationSeconds + 30–60` seconds.
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          maxDurationSeconds: 300,
+          staleCallReaperSeconds: 360,
+        },
+      },
+    },
+  },
+}
+```
+
+## Webhook security
+
+When a proxy or tunnel sits in front of the Gateway, the plugin
+reconstructs the public URL for signature verification. These options
+control which forwarded headers are trusted:
+
+<ParamField path="webhookSecurity.allowedHosts" type="string[]">
+  Allowlist hosts from forwarding headers.
+</ParamField>
+<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
+  Trust forwarded headers without an allowlist.
+</ParamField>
+<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
+  Only trust forwarded headers when the request remote IP matches the list.
+</ParamField>
+
+Additional protections:
+
+- Webhook **replay protection** is enabled for Twilio and Plivo. Replayed valid webhook requests are acknowledged but skipped for side effects.
+- Twilio conversation turns include a per-turn token in `<Gather>` callbacks, so stale/replayed speech callbacks cannot satisfy a newer pending transcript turn.
+- Unauthenticated webhook requests are rejected before body reads when the provider's required signature headers are missing.
+- The voice-call webhook uses the shared pre-auth body profile (64 KB / 5 seconds) plus a per-IP in-flight cap before signature verification.
+
+Example with a stable public host:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          publicUrl: "https://voice.example.com/voice/webhook",
+          webhookSecurity: {
+            allowedHosts: ["voice.example.com"],
+          },
+        },
+      },
+    },
+  },
+}
+```
 
 ## CLI
 
@@ -624,41 +595,43 @@ openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
 openclaw voicecall end --call-id <id>
 openclaw voicecall status --call-id <id>
 openclaw voicecall tail
-openclaw voicecall latency                     # summarize turn latency from logs
+openclaw voicecall latency                      # summarize turn latency from logs
 openclaw voicecall expose --mode funnel
 ```
 
-`latency` reads `calls.jsonl` from the default voice-call storage path. Use
-`--file <path>` to point at a different log and `--last <n>` to limit analysis
-to the last N records (default 200). Output includes p50/p90/p99 for turn
-latency and listen-wait times.
+`latency` reads `calls.jsonl` from the default voice-call storage path.
+Use `--file <path>` to point at a different log and `--last <n>` to limit
+analysis to the last N records (default 200). Output includes p50/p90/p99
+for turn latency and listen-wait times.
 
 ## Agent tool
 
-Tool name: `voice_call`
+Tool name: `voice_call`.
 
-Actions:
-
-- `initiate_call` (message, to?, mode?)
-- `continue_call` (callId, message)
-- `speak_to_user` (callId, message)
-- `send_dtmf` (callId, digits)
-- `end_call` (callId)
-- `get_status` (callId)
+| Action          | Args                      |
+| --------------- | ------------------------- |
+| `initiate_call` | `message`, `to?`, `mode?` |
+| `continue_call` | `callId`, `message`       |
+| `speak_to_user` | `callId`, `message`       |
+| `send_dtmf`     | `callId`, `digits`        |
+| `end_call`      | `callId`                  |
+| `get_status`    | `callId`                  |
 
 This repo ships a matching skill doc at `skills/voice-call/SKILL.md`.
 
 ## Gateway RPC
 
-- `voicecall.initiate` (`to?`, `message`, `mode?`)
-- `voicecall.continue` (`callId`, `message`)
-- `voicecall.speak` (`callId`, `message`)
-- `voicecall.dtmf` (`callId`, `digits`)
-- `voicecall.end` (`callId`)
-- `voicecall.status` (`callId`)
+| Method               | Args                      |
+| -------------------- | ------------------------- |
+| `voicecall.initiate` | `to?`, `message`, `mode?` |
+| `voicecall.continue` | `callId`, `message`       |
+| `voicecall.speak`    | `callId`, `message`       |
+| `voicecall.dtmf`     | `callId`, `digits`        |
+| `voicecall.end`      | `callId`                  |
+| `voicecall.status`   | `callId`                  |
 
 ## Related
 
-- [Text-to-speech](/tools/tts)
 - [Talk mode](/nodes/talk)
+- [Text-to-speech](/tools/tts)
 - [Voice wake](/nodes/voicewake)

docs/providers/anthropic.md

@@ -260,6 +260,10 @@ OpenClaw supports Anthropic's prompt caching feature for API-key auth.
 
     OpenClaw maps this to `anthropic-beta: context-1m-2025-08-07` on requests.
 
+    `params.context1m: true` also applies to the Claude CLI backend
+    (`claude-cli/*`) for eligible Opus and Sonnet models, expanding the runtime
+    context window for those CLI sessions to match the direct-API behavior.
+
     <Warning>
     Requires long-context access on your Anthropic credential. Legacy token auth (`sk-ant-oat-*`) is rejected for 1M context requests — OpenClaw logs a warning and falls back to the standard context window.
     </Warning>

docs/providers/openai.md

@@ -7,7 +7,13 @@ read_when:
 title: "OpenAI"
 ---
 
-OpenAI provides developer APIs for GPT models. OpenClaw supports three OpenAI-family routes. The model prefix selects the route:
+OpenAI provides developer APIs for GPT models, and Codex is also available as a
+ChatGPT-plan coding agent through OpenAI's Codex clients. OpenClaw keeps those
+surfaces separate so config stays predictable.
+
+OpenClaw supports three OpenAI-family routes. The model prefix selects the
+provider/auth route; a separate runtime setting selects who executes the
+embedded agent loop:
 
 - **API key** — direct OpenAI Platform access with usage-based billing (`openai/*` models)
 - **Codex subscription through PI** — ChatGPT/Codex sign-in with subscription access (`openai-codex/*` models)
@@ -29,6 +35,24 @@ changing config.
 | Image generation or editing                   | `openai/gpt-image-2`                                     | Works with either `OPENAI_API_KEY` or OpenAI Codex OAuth.                    |
 | Transparent-background images                 | `openai/gpt-image-1.5`                                   | Use `outputFormat=png` or `webp` and `openai.background=transparent`.        |
 
+## Naming map
+
+The names are similar but not interchangeable:
+
+| Name you see                       | Layer             | Meaning                                                                                           |
+| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
+| `openai`                           | Provider prefix   | Direct OpenAI Platform API route.                                                                 |
+| `openai-codex`                     | Provider prefix   | OpenAI Codex OAuth/subscription route through the normal OpenClaw PI runner.                      |
+| `codex` plugin                     | Plugin            | Bundled OpenClaw plugin that provides native Codex app-server runtime and `/codex` chat controls. |
+| `embeddedHarness.runtime: codex`   | Agent runtime     | Force the native Codex app-server harness for embedded turns.                                     |
+| `/codex ...`                       | Chat command set  | Bind/control Codex app-server threads from a conversation.                                        |
+| `runtime: "acp", agentId: "codex"` | ACP session route | Explicit fallback path that runs Codex through ACP/acpx.                                          |
+
+This means a config can intentionally contain both `openai-codex/*` and the
+`codex` plugin. That is valid when you want Codex OAuth through PI and also want
+native `/codex` chat controls available. `openclaw doctor` warns about that
+combination so you can confirm it is intentional; it does not rewrite it.
+
 <Note>
 GPT-5.5 is available through both direct OpenAI Platform API-key access and
 subscription/OAuth routes. Use `openai/gpt-5.5` for direct `OPENAI_API_KEY`
@@ -42,6 +66,8 @@ Enabling the OpenAI plugin, or selecting an `openai-codex/*` model, does not
 enable the bundled Codex app-server plugin. OpenClaw enables that plugin only
 when you explicitly select the native Codex harness with
 `embeddedHarness.runtime: "codex"` or use a legacy `codex/*` model ref.
+If the bundled `codex` plugin is enabled but `openai-codex/*` still resolves
+through PI, `openclaw doctor` warns and leaves the route unchanged.
 </Note>
 
 ## OpenClaw feature coverage
@@ -92,10 +118,11 @@ Choose your preferred auth method and follow the setup steps.
 
     ### Route summary
 
-    | Model ref | Route | Auth |
-    |-----------|-------|------|
-    | `openai/gpt-5.5` | Direct OpenAI Platform API | `OPENAI_API_KEY` |
-    | `openai/gpt-5.4-mini` | Direct OpenAI Platform API | `OPENAI_API_KEY` |
+    | Model ref              | Runtime config             | Route                       | Auth             |
+    | ---------------------- | -------------------------- | --------------------------- | ---------------- |
+    | `openai/gpt-5.5`       | omitted / `runtime: "pi"`  | Direct OpenAI Platform API  | `OPENAI_API_KEY` |
+    | `openai/gpt-5.4-mini`  | omitted / `runtime: "pi"`  | Direct OpenAI Platform API  | `OPENAI_API_KEY` |
+    | `openai/gpt-5.5`       | `runtime: "codex"`         | Codex app-server harness    | Codex app-server |
 
     <Note>
     `openai/*` is the direct OpenAI API-key route unless you explicitly force
@@ -154,10 +181,11 @@ Choose your preferred auth method and follow the setup steps.
 
     ### Route summary
 
-    | Model ref | Route | Auth |
-    |-----------|-------|------|
-    | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth through PI | Codex sign-in |
-    | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | Codex app-server auth |
+    | Model ref | Runtime config | Route | Auth |
+    |-----------|----------------|-------|------|
+    | `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | ChatGPT/Codex OAuth through PI | Codex sign-in |
+    | `openai-codex/gpt-5.5` | `runtime: "auto"` | Still PI unless a plugin explicitly claims `openai-codex` | Codex sign-in |
+    | `openai/gpt-5.5` | `embeddedHarness.runtime: "codex"` | Codex app-server harness | Codex app-server auth |
 
     <Note>
     Keep using the `openai-codex` provider id for auth/profile commands. The
@@ -186,6 +214,15 @@ Choose your preferred auth method and follow the setup steps.
     `/new` or `/reset` after changing `embeddedHarness` if you want `/status` to
     reflect a new PI/Codex choice.
 
+    ### Doctor warning
+
+    If the bundled `codex` plugin is enabled while this tab's
+    `openai-codex/*` route is selected, `openclaw doctor` warns that the model
+    still resolves through PI. Keep the config unchanged when that is the
+    intended subscription-auth route. Switch to `openai/<model>` plus
+    `embeddedHarness.runtime: "codex"` only when you want native Codex
+    app-server execution.
+
     ### Context window cap
 
     OpenClaw treats model metadata and the runtime context cap as separate values.
@@ -829,6 +866,7 @@ the Server-side compaction accordion below.
     - Use looser compat behavior
     - Strip Completions `store` from non-native `openai-completions` payloads
     - Accept advanced `params.extra_body`/`params.extraBody` pass-through JSON for OpenAI-compatible Completions proxies
+    - Accept `params.chat_template_kwargs` for OpenAI-compatible Completions proxies such as vLLM
     - Do not force strict tool schemas or native-only headers
 
     Azure OpenAI uses native transport and compat behavior but does not receive the hidden attribution headers.

docs/providers/vllm.md

@@ -82,6 +82,7 @@ Use explicit config when:
 - vLLM runs on a different host or port
 - You want to pin `contextWindow` or `maxTokens` values
 - Your server requires a real API key (or you want to control headers)
+- You connect to a trusted loopback, LAN, or Tailscale vLLM endpoint
 
 ```json5
 {
@@ -91,6 +92,7 @@ Use explicit config when:
         baseUrl: "http://127.0.0.1:8000/v1",
         apiKey: "${VLLM_API_KEY}",
         api: "openai-completions",
+        request: { allowPrivateNetwork: true },
         models: [
           {
             id: "your-model-id",
@@ -126,6 +128,45 @@ Use explicit config when:
 
   </Accordion>
 
+  <Accordion title="Nemotron 3 thinking controls">
+    vLLM/Nemotron 3 can use chat-template kwargs to control whether reasoning is
+    returned as hidden reasoning or visible answer text. When an OpenClaw session
+    uses `vllm/nemotron-3-*` with thinking off, OpenClaw sends:
+
+    ```json
+    {
+      "chat_template_kwargs": {
+        "enable_thinking": false,
+        "force_nonempty_content": true
+      }
+    }
+    ```
+
+    To customize these values, set `chat_template_kwargs` under the model params.
+    If you also set `params.extra_body.chat_template_kwargs`, that value has
+    final precedence because `extra_body` is the last request-body override.
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "vllm/nemotron-3-super": {
+              params: {
+                chat_template_kwargs: {
+                  enable_thinking: false,
+                  force_nonempty_content: true,
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+  </Accordion>
+
   <Accordion title="Custom base URL">
     If your vLLM server runs on a non-default host or port, set `baseUrl` in the explicit provider config:
 
@@ -137,6 +178,7 @@ Use explicit config when:
             baseUrl: "http://192.168.1.50:9000/v1",
             apiKey: "${VLLM_API_KEY}",
             api: "openai-completions",
+            request: { allowPrivateNetwork: true },
             models: [
               {
                 id: "my-custom-model",
@@ -167,6 +209,10 @@ Use explicit config when:
     ```
 
     If you see a connection error, verify the host, port, and that vLLM started with the OpenAI-compatible server mode.
+    For explicit loopback, LAN, or Tailscale endpoints, also set
+    `models.providers.vllm.request.allowPrivateNetwork: true`; provider
+    requests block private-network URLs by default unless the provider is
+    explicitly trusted.
 
   </Accordion>
 

docs/providers/zai.md

@@ -132,6 +132,38 @@ GLM models are available as `zai/<model>` (example: `zai/glm-5`). The default bu
 
   </Accordion>
 
+  <Accordion title="Thinking and preserved thinking">
+    Z.AI thinking follows OpenClaw's `/think` controls. With thinking off,
+    OpenClaw sends `thinking: { type: "disabled" }` to avoid responses that
+    spend the output budget on `reasoning_content` before visible text.
+
+    Preserved thinking is opt-in because Z.AI requires the full historical
+    `reasoning_content` to be replayed, which increases prompt tokens. Enable it
+    per model:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "zai/glm-5.1": {
+              params: { preserveThinking: true },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    When enabled and thinking is on, OpenClaw sends
+    `thinking: { type: "enabled", clear_thinking: false }` and replays prior
+    `reasoning_content` for the same OpenAI-compatible transcript.
+
+    Advanced users can still override the exact provider payload with
+    `params.extra_body.thinking`.
+
+  </Accordion>
+
   <Accordion title="Image understanding">
     The bundled Z.AI plugin registers image understanding.
 

docs/reference/RELEASING.md

@@ -49,6 +49,10 @@ OpenClaw has three public release lanes:
 - Run `pnpm build && pnpm ui:build` before `pnpm release:check` so the expected
   `dist/*` release artifacts and Control UI bundle exist for the pack
   validation step
+- Run `pnpm qa:otel:smoke` when validating release telemetry. It exercises
+  QA-lab through a local OTLP/HTTP receiver and verifies the exported trace
+  span names, bounded attributes, and content/identifier redaction without
+  requiring Opik, Langfuse, or another external collector.
 - Run `pnpm release:check` before every tagged release
 - Release checks now run in a separate manual workflow:
   `OpenClaw Release Checks`

docs/reference/secretref-credential-surface.md

@@ -35,6 +35,7 @@ Scope intent:
 - `models.providers.*.request.tls.passphrase`
 - `skills.entries.*.apiKey`
 - `agents.defaults.memorySearch.remote.apiKey`
+- `agents.list[].tts.providers.*.apiKey`
 - `agents.list[].memorySearch.remote.apiKey`
 - `talk.providers.*.apiKey`
 - `messages.tts.providers.*.apiKey`

docs/reference/secretref-user-supplied-credentials-matrix.json

@@ -29,6 +29,13 @@
       "secretShape": "secret_input",
       "optIn": true
     },
+    {
+      "id": "agents.list[].tts.providers.*.apiKey",
+      "configFile": "openclaw.json",
+      "path": "agents.list[].tts.providers.*.apiKey",
+      "secretShape": "secret_input",
+      "optIn": true
+    },
     {
       "id": "auth-profiles.api_key.key",
       "configFile": "auth-profiles.json",

docs/reference/session-management-compaction.md

@@ -136,7 +136,7 @@ Rules of thumb:
 - **Reset** (`/new`, `/reset`) creates a new `sessionId` for that `sessionKey`.
 - **Daily reset** (default 4:00 AM local time on the gateway host) creates a new `sessionId` on the next message after the reset boundary.
 - **Idle expiry** (`session.reset.idleMinutes` or legacy `session.idleMinutes`) creates a new `sessionId` when a message arrives after the idle window. When daily + idle are both configured, whichever expires first wins.
-- **System events** (heartbeat, cron wakeups, exec notifications, gateway bookkeeping) may mutate the session row but do not extend daily/idle reset freshness.
+- **System events** (heartbeat, cron wakeups, exec notifications, gateway bookkeeping) may mutate the session row but do not extend daily/idle reset freshness. Reset rollover discards queued system-event notices for the previous session before the fresh prompt is built.
 - **Thread parent fork guard** (`session.parentForkMaxTokens`, default `100000`) skips parent transcript forking when the parent session is already too large; the new thread starts fresh. Set `0` to disable.
 
 Implementation detail: the decision happens in `initSessionState()` in `src/auto-reply/reply/session.ts`.

docs/reference/test.md

@@ -33,6 +33,7 @@ title: "Tests"
 - `pnpm test:e2e`: Runs gateway end-to-end smoke tests (multi-instance WS/HTTP/node pairing). Defaults to `threads` + `isolate: false` with adaptive workers in `vitest.e2e.config.ts`; tune with `OPENCLAW_E2E_WORKERS=<n>` and set `OPENCLAW_E2E_VERBOSE=1` for verbose logs.
 - `pnpm test:live`: Runs provider live tests (minimax/zai). Requires API keys and `LIVE=1` (or provider-specific `*_LIVE_TEST=1`) to unskip.
 - `pnpm test:docker:all`: Builds the shared live-test image and Docker E2E image once, then runs the Docker smoke lanes with `OPENCLAW_SKIP_DOCKER_BUILD=1` through a weighted scheduler. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` controls process slots and defaults to 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` controls the provider-sensitive tail pool and defaults to 10. Heavy lane caps default to `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`, and `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; provider caps default to one heavy lane per provider via `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4`, and `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Use `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` or `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` for larger hosts. Lane starts are staggered by 2 seconds by default to avoid local Docker daemon create storms; override with `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. The runner preflights Docker by default, cleans stale OpenClaw E2E containers, emits active-lane status every 30 seconds, shares provider CLI tool caches between compatible lanes, retries transient live-provider failures once by default (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`), and stores lane timings in `.artifacts/docker-tests/lane-timings.json` for longest-first ordering on later runs. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` to print the lane manifest without running Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` to tune status output, or `OPENCLAW_DOCKER_ALL_TIMINGS=0` to disable timing reuse. Use `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` for deterministic/local lanes only or `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` for live-provider lanes only; package aliases are `pnpm test:docker:local:all` and `pnpm test:docker:live:all`. Live-only mode merges main and tail live lanes into one longest-first pool so provider buckets can pack Claude, Codex, and Gemini work together. The runner stops scheduling new pooled lanes after the first failure unless `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` is set, and each lane has a 120-minute fallback timeout overrideable with `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; selected live/tail lanes use tighter per-lane caps. CLI backend Docker setup commands have their own timeout via `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (default 180). Per-lane logs are written under `.artifacts/docker-tests/<run-id>/`.
+- `pnpm test:docker:browser-cdp-snapshot`: Builds a Chromium-backed source E2E container, starts raw CDP plus an isolated Gateway, runs `browser doctor --deep`, and verifies CDP role snapshots include link URLs, cursor-promoted clickables, iframe refs, and frame metadata.
 - CLI backend live Docker probes can be run as focused lanes, for example `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume`, or `pnpm test:docker:live-cli-backend:codex:mcp`. Claude and Gemini have matching `:resume` and `:mcp` aliases.
 - `pnpm test:docker:openwebui`: Starts Dockerized OpenClaw + Open WebUI, signs in through Open WebUI, checks `/api/models`, then runs a real proxied chat through `/api/chat/completions`. Requires a usable live model key (for example OpenAI in `~/.profile`), pulls an external Open WebUI image, and is not expected to be CI-stable like the normal unit/e2e suites.
 - `pnpm test:docker:mcp-channels`: Starts a seeded Gateway container and a second client container that spawns `openclaw mcp serve`, then verifies routed conversation discovery, transcript reads, attachment metadata, live event queue behavior, outbound send routing, and Claude-style channel + permission notifications over the real stdio bridge. The Claude notification assertion reads the raw stdio MCP frames directly so the smoke reflects what the bridge actually emits.

docs/tools/acp-agents-setup.md

@@ -11,6 +11,20 @@ For the overview, operator runbook, and concepts, see [ACP agents](/tools/acp-ag
 
 The sections below cover acpx harness config, plugin setup for the MCP bridges, and permission configuration.
 
+Use this page only when you are setting up the ACP/acpx route. For native Codex
+app-server runtime config, use [Codex harness](/plugins/codex-harness). For
+OpenAI API keys or Codex OAuth model-provider config, use
+[OpenAI](/providers/openai).
+
+Codex has two OpenClaw routes:
+
+| Route                      | Config/command                                         | Setup page                              |
+| -------------------------- | ------------------------------------------------------ | --------------------------------------- |
+| Native Codex app-server    | `/codex ...`, `embeddedHarness.runtime: "codex"`       | [Codex harness](/plugins/codex-harness) |
+| Explicit Codex ACP adapter | `/acp spawn codex`, `runtime: "acp", agentId: "codex"` | This page                               |
+
+Prefer the native route unless you explicitly need ACP/acpx behavior.
+
 ## acpx harness support (current)
 
 Current acpx built-in harness aliases:
@@ -143,7 +157,10 @@ Then verify backend health:
 
 ### acpx command and version configuration
 
-By default, the bundled `acpx` plugin uses its plugin-local pinned binary (`node_modules/.bin/acpx` inside the plugin package). Startup registers the backend as not-ready and a background job verifies `acpx --version`; if the binary is missing or mismatched, it runs `npm install --omit=dev --no-save acpx@<pinned>` and re-verifies. The gateway stays non-blocking throughout.
+By default, the bundled `acpx` plugin registers the embedded ACP backend without
+spawning an ACP agent during Gateway startup. Run `/acp doctor` for an explicit
+live probe. Set `OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=1` only when you need the
+Gateway to probe the configured agent at startup.
 
 Override the command or version in plugin config:
 
@@ -239,10 +256,11 @@ Restart the gateway after changing this value.
 
 ### Health probe agent configuration
 
-The bundled `acpx` plugin probes one harness agent while deciding whether the
-embedded runtime backend is ready. If `acp.allowedAgents` is set, it defaults to
-the first allowed agent; otherwise it defaults to `codex`. If your deployment
-needs a different ACP agent for health checks, set the probe agent explicitly:
+When `/acp doctor` or the opt-in startup probe checks the backend, the bundled
+`acpx` plugin probes one harness agent. If `acp.allowedAgents` is set, it
+defaults to the first allowed agent; otherwise it defaults to `codex`. If your
+deployment needs a different ACP agent for health checks, set the probe agent
+explicitly:
 
 ```bash
 openclaw config set plugins.entries.acpx.config.probeAgent claude