chore: polish qa lab follow-ups

* plugins: include resolved workspaceDir in provider hook cache keys

resolveProviderPluginsForHooks, resolveProviderPluginsForCatalogHooks, and
resolveProviderRuntimePlugin used the raw params.workspaceDir for cache keys
and plugin-id discovery while resolvePluginProviders already fell back to
the active registry workspace. Resolve workspaceDir once at the top of each
function so cache keys, candidate filtering, and loading all use the same
workspace root.

* fix(plugins): inherit runtime workspace for snapshot loads

* test(gateway): stub runtime registry seam

* fix(plugins): restore workspace fallback after rebase

---------

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

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

@@ -30,6 +30,7 @@ Use this skill for Parallels guest workflows and smoke interpretation. Do not lo
 - Flow: fresh snapshot -> install npm package baseline -> smoke -> install current main tgz on the same guest -> smoke again.
 - Same-guest update verification should set the default model explicitly to `openai/gpt-5.4` before the agent turn and use a fresh explicit `--session-id` so old session model state does not leak into the check.
 - The aggregate npm-update wrapper must resolve the Linux VM with the same Ubuntu fallback policy as `parallels-linux-smoke.sh` before both fresh and update lanes. Treat any Ubuntu guest with major version `>= 24` as acceptable when the exact default VM is missing, preferring the closest version match. On Peter's current host today, missing `Ubuntu 24.04.3 ARM64` should fall back to `Ubuntu 25.10`.
+- On macOS same-guest update checks, restart the gateway after the npm upgrade before `gateway status` / `agent`; launchd can otherwise report a loaded service while the old process has exited and the fresh process is not RPC-ready yet.
 - On Windows same-guest update checks, restart the gateway after the npm upgrade before `gateway status` / `agent`; in-place global npm updates can otherwise leave stale hashed `dist/*` module imports alive in the running service.
 - For Windows same-guest update checks, prefer the done-file/log-drain PowerShell runner pattern over one long-lived `prlctl exec ... powershell -EncodedCommand ...` transport. The guest can finish successfully while the outer `prlctl exec` still hangs.
 - The Windows same-guest update helper should write stage markers to its log before long steps like tgz download and `npm install -g` so the outer progress monitor does not sit on `waiting for first log line` during healthy but quiet installs.
@@ -46,6 +47,7 @@ Use this skill for Parallels guest workflows and smoke interpretation. Do not lo
 - Preferred entrypoint: `pnpm test:parallels:macos`
 - Default to the snapshot closest to `macOS 26.3.1 latest`.
 - On Peter's Tahoe VM, `fresh-latest-march-2026` can hang in `prlctl snapshot-switch`; if restore times out there, rerun with `--snapshot-hint 'macOS 26.3.1 latest'` before blaming auth or the harness.
+- `parallels-macos-smoke.sh` now retries `snapshot-switch` once after force-stopping a stuck running/suspended guest. If Tahoe still times out after that recovery path, then treat it as a real Parallels/host issue and rerun manually.
 - The macOS smoke should include a dashboard load phase after gateway health: resolve the tokenized URL with `openclaw dashboard --no-open`, verify the served HTML contains the Control UI title/root shell, then open Safari and require an established localhost TCP connection from Safari to the gateway port.
 - If a packaged install regresses with `500` on `/`, `/healthz`, or `__openclaw/control-ui-config.json` after `fresh.install-main` or `upgrade.install-main`, suspect bundled plugin runtime deps resolving from the package root `node_modules` rather than `dist/extensions/*/node_modules`. Repro quickly with a real `npm pack`/global install lane before blaming dashboard auth or Safari.
 - `prlctl exec` is fine for deterministic repo commands, but use the guest Terminal or `prlctl enter` when installer parity or shell-sensitive behavior matters.
@@ -64,6 +66,7 @@ Use this skill for Parallels guest workflows and smoke interpretation. Do not lo
 - Use PowerShell only as the transport with `-ExecutionPolicy Bypass`, then call the `.cmd` shims from inside it.
 - Multi-word `openclaw agent --message ...` checks should call `& $openclaw ...` inside PowerShell, not `Start-Process ... -ArgumentList` against `openclaw.cmd`, or Commander can see split argv and throw `too many arguments for 'agent'`.
 - Windows installer/tgz phases now retry once after guest-ready recheck; keep new Windows smoke steps idempotent so a transport-flake retry is safe.
+- If a Windows retry sees the VM become `suspended` or `stopped`, resume/start it before the next `prlctl exec`; otherwise the second attempt just repeats the same `rc=255`.
 - Windows global `npm install -g` phases can stay quiet for a minute or more even when healthy; inspect the phase log before calling it hung, and only treat it as a regression once the retry wrapper or timeout trips.
 - Fresh Windows ref-mode onboard should use the same background PowerShell runner plus done-file/log-drain pattern as the npm-update helper, including startup materialization checks, host-side timeouts on short poll `prlctl exec` calls, and retry-on-poll-failure behavior for transient transport flakes.
 - Fresh Windows ref-mode agent verification should set `OPENAI_API_KEY` in the PowerShell environment before invoking `openclaw.cmd agent`, for the same pairing-required fallback reason as macOS.
@@ -82,6 +85,7 @@ Use this skill for Parallels guest workflows and smoke interpretation. Do not lo
 - Fresh `main` tgz smoke still needs the latest-release installer first because the snapshot has no Node or npm before bootstrap.
 - This snapshot does not have a usable `systemd --user` session; managed daemon install is unsupported.
 - The Linux smoke now falls back to a manual `setsid openclaw gateway run --bind loopback --port 18789 --force` launch with `HOME=/root` and the provider secret exported, then verifies `gateway status --deep --require-rpc` when available.
+- The Linux manual gateway launch should wait for `gateway status --deep --require-rpc` inside the `gateway-start` phase; otherwise the first status probe can race the background bind and fail a healthy lane.
 - If Linux gateway bring-up fails, inspect `/tmp/openclaw-parallels-linux-gateway.log` in the guest phase logs first; the common failure mode is a missing provider secret in the launched gateway environment.
 
 ## Discord roundtrip

.github/labeler.yml

@@ -64,6 +64,17 @@
       - any-glob-to-any-file:
           - "extensions/qqbot/**"
           - "docs/channels/qqbot.md"
+"channel: qa-channel":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/qa-channel/**"
+          - "docs/channels/qa-channel.md"
+"extensions: qa-lab":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/qa-lab/**"
+          - "docs/concepts/qa-e2e-automation.md"
+          - "docs/channels/qa-channel.md"
 "channel: signal":
   - changed-files:
       - any-glob-to-any-file:

.github/workflows/auto-response.yml

@@ -407,8 +407,12 @@ jobs:
               "Closing this PR because it looks dirty (too many unrelated or unexpected changes). This usually happens when a branch picks up unrelated commits or a merge went sideways. Please recreate the PR from a clean branch.";
 
             if (pullRequest) {
-              // `bad-barnacle` exempts PRs that Barnacle incorrectly marked dirty.
-              if (labelSet.has(dirtyLabel) && !labelSet.has(badBarnacleLabel)) {
+              if (labelSet.has(badBarnacleLabel)) {
+                core.info(`Skipping PR auto-response checks for #${pullRequest.number} because ${badBarnacleLabel} is present.`);
+                return;
+              }
+
+              if (labelSet.has(dirtyLabel)) {
                 await github.rest.issues.createComment({
                   owner: context.repo.owner,
                   repo: context.repo.repo,

.gitignore

@@ -147,3 +147,5 @@ changelog/fragments/
 .tmp/
 test/fixtures/openclaw-vitest-unit-report.json
 analysis/
+.artifacts/qa-e2e/
+extensions/qa-lab/web/dist/

CHANGELOG.md

@@ -14,33 +14,44 @@ Docs: https://docs.openclaw.ai
 - Channels/context visibility: add configurable `contextVisibility` per channel (`all`, `allowlist`, `allowlist_quote`) so supplemental quote, thread, and fetched history context can be filtered by sender allowlists instead of always passing through as received.
 - Matrix/exec approvals: add Matrix-native exec approval prompts with account-scoped approvers, channel-or-DM delivery, and room-thread aware resolution handling. (#58635) Thanks @gumadeiras.
 - Providers/StepFun: add the bundled StepFun provider plugin with standard and Step Plan endpoints, China/global onboarding choices, `step-3.5-flash` on both catalogs, and `step-3.5-flash-2603` currently exposed on Step Plan. (#60032) Thanks @hengm3467.
+- Providers/Fireworks: add a bundled Fireworks AI provider plugin with `FIREWORKS_API_KEY` onboarding, Fire Pass Kimi defaults, and dynamic Fireworks model-id support.
 - Providers/config: add `models.providers.*.request` overrides for headers and auth on model-provider paths, and full request transport overrides for media provider HTTP paths.
 - MiniMax/TTS: add a bundled MiniMax speech provider backed by the T2A v2 API so speech synthesis can run through MiniMax-native voices and auth. (#55921) Thanks @duncanita.
 - Control UI/skills: add ClawHub search, detail, and install flows directly in the Skills panel. (#60134) Thanks @samzong.
-- Providers/StepFun: add the bundled StepFun provider plugin with standard and Step Plan endpoints, China/global onboarding choices, `step-3.5-flash` on both catalogs, and `step-3.5-flash-2603` currently exposed on Step Plan. (#60032) Thanks @hengm3467.
 - Providers/Ollama: add a bundled Ollama Web Search provider for key-free `web_search` via your configured Ollama host and `ollama signin`. (#59318) Thanks @BruceMacD.
 - Plugins/onboarding: add plugin config TUI prompts to onboard and configure wizards so more plugin setup can stay in the guided flow. (#60590)
 - Plugins/install: add `openclaw plugins install --force` to overwrite existing plugin and hook-pack install targets without using the dangerous-code override flag. (#60544) Thanks @gumadeiras.
 - Providers/Anthropic: remove setup-token from new onboarding and auth-command setup paths, keep existing configured legacy token profiles runnable, and steer new Anthropic setup to Claude CLI or API keys.
 - Providers/OpenAI Codex: add forward-compat `openai-codex/gpt-5.4-mini` synthesis across provider runtime, model catalog, and model listing so Codex mini works before bundled Pi catalog updates land.
+- Tools/web_search: add a bundled MiniMax Search provider backed by the Coding Plan search API, with region reuse from `MINIMAX_API_HOST` and plugin-owned credential config. (#54648) Thanks @fengmk2.
 - Channels/context visibility: add configurable `contextVisibility` per channel (`all`, `allowlist`, `allowlist_quote`) so quoted, threaded, and fetched history context can be filtered by sender allowlists instead of always passing through as received.
 - Providers/request overrides: add shared model and media request transport overrides across OpenAI-, Anthropic-, Google-, and compatible provider paths, including headers, auth, proxy, and TLS controls. (#60200)
 - Matrix/exec approvals: add Matrix-native exec approval prompts with account-scoped approvers, channel-or-DM delivery, and room-thread aware resolution handling. (#58635) Thanks @gumadeiras.
 - Agents/Claude CLI: expose OpenClaw tools to background Claude CLI runs through a loopback MCP bridge that reuses gateway tool policy, honors session/account/channel scoping, and only advertises the bridge when the local runtime is actually live. (#35676) Thanks @mylukin.
+- Agents/Claude CLI: switch bundled Claude CLI runs to stdin + `stream-json` partial-message streaming so prompts stop riding argv, long replies show live progress, and final session/usage metadata still land cleanly.
 - Prompt caching: keep prompt prefixes more reusable across transport fallback, deterministic MCP tool ordering, compaction, and embedded image history so follow-up turns hit cache more reliably. (#58036, #58037, #58038, #59054, #60603, #60691) Thanks @bcherny.
 - Agents/cache: diagnostics: add prompt-cache break diagnostics, trace live cache scenarios through embedded runner paths, and show cache reuse explicitly in `openclaw status --verbose`. Thanks @vincentkoc.
 - Agents/cache: stabilize cache-relevant system prompt fingerprints by normalizing equivalent structured prompt whitespace, line endings, hook-added system context, and runtime capability ordering so semantically unchanged prompts reuse KV/cache more reliably. Thanks @vincentkoc.
+- Config/schema: enrich the exported `openclaw config schema` JSON Schema with field titles and descriptions so editors, agents, and other schema consumers receive the same config help metadata. (#60067) Thanks @solavrc.
+- Providers/StepFun: add the bundled StepFun provider plugin with standard and Step Plan endpoints, China/global onboarding choices, `step-3.5-flash` on both catalogs, and `step-3.5-flash-2603` currently exposed on Step Plan. (#60032) Thanks @hengm3467.
 
 ### Fixes
 
+- Gateway/macOS: let launchd `KeepAlive` own in-process gateway restarts again, adding a short supervised-exit delay so rapid restarts avoid launchd crash-loop unloads while `openclaw gateway restart` still reports real LaunchAgent errors synchronously.
+- Synology Chat/security: route webhook token comparison through the shared constant-time secret helper for consistency with other bundled plugins.
+- Models/MiniMax: honor `MINIMAX_API_HOST` for implicit bundled MiniMax provider catalogs so China-hosted API-key setups pick `api.minimaxi.com/anthropic` without manual provider config. (#34524) Thanks @caiqinghua.
+- Usage/MiniMax: invert remaining-style `usage_percent` fields when MiniMax reports only remaining percentage data, so usage bars stop showing nearly-full remaining quota as nearly-exhausted usage. (#60254) Thanks @jwchmodx.
 - MiniMax: advertise image input on bundled `MiniMax-M2.7` and `MiniMax-M2.7-highspeed` model definitions so image-capable flows can route through the M2.7 family correctly. (#54843) Thanks @MerlinMiao88888888.
-- MiniMax/usage: treat `coding_plan` interval and weekly `*_usage_count` fields as remaining quota, not consumed usage, so remaining-percent displays stop inverting in usage surfaces. (#60222) Thanks @YangManBOBO.
-- Agents/exec approvals: let `exec-approvals.json` agent security override stricter gateway tool defaults so approved subagents can use `security: "full"` without falling back to allowlist enforcement again. (#60310) Thanks @lml2468.
-- Tasks/maintenance: mark stale cron runs and CLI tasks backed only by long-lived chat sessions as lost again so task cleanup does not keep dead work alive indefinitely. (#60310) Thanks @lml2468.
+- Media understanding: auto-register image-capable config providers for vision routing, so custom GLM-style provider ids with image models stop failing with “no media-understanding provider registered”. (#51418) Thanks @xydt-610.
 - Providers/OpenAI: preserve native `reasoning.effort: "none"` and strict tool schemas on direct OpenAI-family endpoints, keep compat routes on compat shaping, fix Responses WebSocket warm-up behavior, keep stable session and turn metadata, and fall back more gracefully after early WebSocket failures.
 - Providers/OpenAI Codex: split native `contextWindow` from runtime `contextTokens`, keep the default effective cap at `272000`, and expose a per-model `contextTokens` override on `models.providers.*.models[]`.
 - Providers/compat: stop forcing OpenAI-only defaults on proxy and custom OpenAI-compatible routes, preserve native vendor-specific reasoning/tool/streaming behavior across Anthropic-compatible, Moonshot, Mistral, ModelStudio, OpenRouter, xAI, and Z.ai endpoints, and route GitHub Copilot Claude models through Anthropic Messages instead of OpenAI Responses.
 - Providers/Model Studio: preserve native streaming usage reporting for DashScope-compatible endpoints even when they are configured under a generic provider key, so streamed token totals stop sticking at zero. (#52395) Thanks @IVY-AI-gif.
+- Providers/OpenAI-compatible WS: compute fallback token totals from normalized usage when providers omit or zero `total_tokens`, so DashScope-compatible sessions stop storing zero totals after alias normalization. (#54940) Thanks @lyfuci.
+- Status/usage: let `/status` and `session_status` fall back to transcript token totals when the session meta store stayed at zero, so LM Studio, Ollama, DashScope, and similar OpenAI-compatible providers stop showing `Context: 0/...`. (#55041) Thanks @jjjojoj.
+- Providers/Z.AI: preserve explicitly registered `glm-5-*` variants like `glm-5-turbo` instead of intercepting them with the generic GLM-5 forward-compat shim. (#48185) Thanks @haoyu-haoyu.
+- Live model switching: only treat explicit user-driven model changes as pending live switches, so fallback rotation, heartbeat overrides, and compaction no longer trip `LiveSessionModelSwitchError` before making an API call. (#60266) Thanks @kiranvk-2011.
+- Voice-call/OpenAI: pass full plugin config into realtime transcription provider resolution so streaming calls can discover the bundled OpenAI realtime transcription provider again. Fixes #60936. Thanks @sliekens and @vincentkoc.
 - Plugins/OpenAI: enable `gpt-image-1` reference-image edits through `/images/edits` multipart uploads, and stop inferring unsupported resolution overrides when no explicit `size` or `resolution` is provided.
 - Gateway/startup: default `gateway.mode` to `local` when unset, detect PID recycling in gateway lock files on Windows and macOS, and show startup progress so healthy restarts stop getting blocked by stale locks. (#54801, #60085, #59843)
 - Mobile pairing/Android: tighten secure endpoint handling so Tailscale and public remote setup reject cleartext endpoints, private LAN pairing still works, merged-role approvals mint both node and operator device tokens, and bootstrap tokens survive node auto-pair until operator approval finishes. (#60128, #60208, #60221)
@@ -55,6 +66,9 @@ Docs: https://docs.openclaw.ai
 - WhatsApp: restore `channels.whatsapp.blockStreaming` and reset watchdog timeouts after reconnect so quiet chats stop falling into reconnect loops. (#60007, #60069)
 - Control UI: keep Stop visible during tool-only execution, preserve pending-send busy state, and clear stale ClawHub search results as soon as the query changes. (#54528, #59800, #60267)
 - MS Teams: download inline DM images via Graph API and preserve channel reply threading in proactive fallback. (#52212, #55198)
+- Agents/Claude CLI: persist explicit `openclaw agent --session-id` runs under a stable session key so follow-ups can reuse the stored CLI binding and resume the same underlying Claude session.
+- Agents/CLI backends: invalidate stored CLI session reuse when local CLI login state or the selected auth profile credential changes, so relogin and token rotation stop resuming stale sessions.
+- Gateway/macOS: recover installed-but-unloaded LaunchAgents during `openclaw gateway start` and `restart`, while still preferring live unmanaged gateways during restart recovery. (#43766) Thanks @HenryC-3.
 - Auth/failover: persist selected fallback overrides before retrying, shorten `auth_permanent` lockouts, and refresh websocket/shared-auth sessions only when real auth changes occur so retries and secret rotations behave predictably. (#60404, #60323, #60387)
 - Cron: replay interrupted recurring jobs on the first gateway restart instead of waiting for a second restart. (#60583) Thanks @joelnishanth.
 - Plugins/media understanding: enable bundled Groq and Deepgram providers by default so configured transcription models work without extra plugin activation config. (#59982) Thanks @yxjsxy.
@@ -71,7 +85,52 @@ Docs: https://docs.openclaw.ai
 - Agents/exec approvals: let `exec-approvals.json` agent security override stricter gateway tool defaults so approved subagents can use `security: "full"` without falling back to allowlist enforcement again. (#60310) Thanks @lml2468.
 - Tasks/maintenance: reconcile stale cron and chat-backed CLI task rows against live cron-job and agent-run ownership instead of treating any persisted session key as proof that the task is still running. (#60310) Thanks @lml2468.
 - Providers/GitHub Copilot: send IDE identity headers on runtime model requests and GitHub token exchange so IDE-authenticated Copilot runs stop failing with missing `Editor-Version`. (#60641) Thanks @VACInc and @vincentkoc.
+- Model picker/providers: treat bundled BytePlus and Volcengine plan aliases as their native providers during setup, and expose their bundled standard/coding catalogs before auth so setup can suggest the right models. (#58819) Thanks @Luckymingxuan.
 - Prompt caching: route Codex Responses and Anthropic Vertex through boundary-aware cache shaping, and report the actual outbound system prompt in cache traces so cache reuse and misses line up with what providers really receive. Thanks @vincentkoc.
+- Prompt caching: order stable workspace project-context files before `HEARTBEAT.md` and keep `HEARTBEAT.md` below the system-prompt cache boundary so heartbeat churn does not invalidate the stable project-context prefix. (#58979) Thanks @yozu and @vincentkoc.
+- Plugins/cache: inherit the active gateway workspace for provider, web-search, and web-fetch snapshot loads when callers omit `workspaceDir`, so compatible plugin registries and snapshot caches stop missing on gateway-owned runtime paths. (#61138) Thanks @jzakirov.
+- Agents/Kimi tool-call repair: preserve tool arguments that were already present on streamed tool calls when later malformed deltas fail reevaluation, while still dropping stale repair-only state before `toolcall_end`.
+- MiniMax/pricing: keep bundled MiniMax highspeed pricing distinct in provider catalogs and preserve the lower M2.5 cache-read pricing when onboarding older MiniMax models. (#54214) Thanks @octo-patch.
+- Agents/cache: preserve the full 3-turn prompt-cache image window across tool loops, keep colliding bundled MCP tool definitions deterministic, and reapply Anthropic Vertex cache shaping after payload hook replacements so KV/cache reuse stays stable. Thanks @vincentkoc.
+- Device pairing: reject rotating device tokens into roles that were never approved during pairing, and keep reconnect role checks bounded to the paired device's approved role set. (#60462) Thanks @eleqtrizit.
+- Mobile pairing/security: fail closed for internal `/pair` setup-code issuance, cleanup, and approval paths when gateway pairing scopes are missing, and keep approval-time requested-scope enforcement on the internal command path. (#55996) Thanks @coygeek.
+- Status/cache: restore `cacheRead` and `cacheWrite` in transcript fallback so `/status` keeps showing cache hit percentages when session logs are the only complete usage source. (#59247) Thanks @stuartsy.
+- Exec approvals/node host: forward prepared `system.run` approval plans on the async node invoke path so mutable script operands keep their approval-time binding and drift revalidation instead of dropping back to unbound execution.
+- Synology Chat/security: default low-level HTTPS helper TLS verification to on so helper/API defaults match the shipped safe account default, and only explicit `allowInsecureSsl: true` opts out.
+- Android/canvas security: require exact normalized A2UI URL matches before forwarding canvas bridge actions, rejecting query mismatches and descendant paths while still allowing fragment-only A2UI navigation.
+- Cron: send failure notifications through the job's primary delivery channel using the same session context as successful delivery when no explicit `failureDestination` is configured. (#60622) Thanks @artwalker.
+- Mobile pairing/bootstrap: keep QR bootstrap handoff tokens bounded to the mobile-safe contract so node handoff stays unscoped and operator handoff drops mixed `node.*`, `operator.admin`, and `operator.pairing` scopes.
+- Gateway/auth: serialize async shared-secret auth attempts per client so concurrent Tailscale-capable failures cannot overrun the intended auth rate-limit budget. Thanks @Telecaster2147.
+- Doctor/config: compare normalized `talk` configs by deep structural equality instead of key-order-sensitive serialization so `openclaw doctor --fix` stops repeatedly reporting/applying no-op `talk.provider/providers` normalization. (#59911) Thanks @ejames-dev.
+- Providers/Anthropic Vertex: honor `cacheRetention: "long"` with the real 1-hour prompt-cache TTL on Vertex AI endpoints, and default `anthropic-vertex` cache retention like direct Anthropic. (#60888) Thanks @affsantos.
+- Gateway/device auth: reuse cached device-token scopes only for cached-token reconnects, while keeping explicit `deviceToken` scope requests and empty-cache fallbacks intact so reconnects preserve `operator.read` without breaking explicit auth flows. (#46032) Thanks @caicongyang.
+- Agents/scheduling: steer background-now work toward automatic completion wake and treat `process` polling as on-demand inspection or intervention instead of default completion handling. (#60877) Thanks @vincentkoc.
+- Google Gemini CLI auth: improve OAuth credential discovery across Windows nvm and Homebrew libexec installs, and align Code Assist metadata so Gemini login stops failing on packaged CLI layouts. (#40729) Thanks @hughcube.
+- Google Gemini CLI auth: detect bundled npm installs by scanning packaged bundle files for the Gemini OAuth client config, so `npm install -g @google/gemini-cli` layouts work again. (#60486) Thanks @wzfmini01.
+- Mattermost/config schema: accept `groups.*.requireMention` again so existing Mattermost configs no longer fail strict validation after upgrade. (#58271) Thanks @MoerAI.
+- Agents/failover: scope Anthropic `An unknown error occurred` failover matching by provider so generic internal unknown-error text no longer triggers retryable timeout fallback. (#59325) Thanks @aaron-he-zhu.
+- Providers/OpenRouter failover: classify `403 "Key limit exceeded"` spending-limit responses as billing so model fallback continues instead of stopping on generic auth. (#59892) Thanks @rockcent.
+- Device pairing/security: keep non-operator device scope checks bound to the requested role prefix so bootstrap verification cannot redeem `operator.*` scopes through `node` auth. (#57258) Thanks @jlapenna.
+- Gateway/device pairing: require non-admin paired-device sessions to manage only their own device for token rotate/revoke and paired-device removal, blocking cross-device token theft inside pairing-scoped sessions. (#50627) Thanks @coygeek.
+- CLI/skills JSON: route `skills list --json`, `skills info --json`, and `skills check --json` output to stdout instead of stderr so machine-readable consumers receive JSON on the expected stream again. (#60914; fixes #57599; landed from contributor PR #57611 by @Aftabbs) Thanks @Aftabbs.
+- Agents/subagents: honor allowlist validation, auth-profile handoff, and session override state when a subagent retries after `LiveSessionModelSwitchError`. (#58178) Thanks @openperf.
+- Google image generation: disable pinned DNS for Gemini image requests and honor explicit `pinDns` overrides in shared provider HTTP helpers so proxy-backed image generation works again. (#59873) Thanks @luoyanglang.
+- Agents/exec: restore `host=node` routing for node-pinned and `host=auto` sessions, while still blocking sandboxed `auto` sessions from jumping to gateway. (#60788) Thanks @openperf.
+- Agents/compaction: keep assistant tool calls and displaced tool results in the same compaction chunk so strict summarization providers stop rejecting orphaned tool pairs. (#58849) Thanks @openperf.
+- Outbound/sanitizer: strip leaked `<tool_call>`, `<function_calls>`, and model special tokens from shared user-visible assistant text, including truncated tool-call streams, so internal scaffolding no longer bleeds into replies across surfaces. (#60619) Thanks @oliviareid-svg.
+- Telegram: restore DM voice-note preflight transcription so direct-message audio stops arriving as raw `<media:audio>` placeholders. (#61008) Thanks @manueltarouca.
+- Control UI/avatar: honor `ui.assistant.avatar` when serving `/avatar/:agentId` so Appearance UI avatar paths stop falling back to initials placeholders. (#60778) Thanks @hannasdev.
+- Control UI/Overview: prevent gateway access token/password visibility toggle buttons from overlapping their inputs at narrow widths. (#56924) Thanks @bbddbb1.
+- Control UI/cron: highlight the Cron refresh button while refresh is in flight so the page's loading state stays visible even when prior data remains on screen. (#60394) Thanks @coder-zhuzm.
+- MS Teams: replace the deprecated Teams SDK HttpPlugin stub with `httpServerAdapter` so recurring gateway deprecation warnings stop firing and the Express 5 compatibility workaround stays on the supported SDK path. (#60939) Thanks @coolramukaka-sys.
+- CLI/Commander: preserve Commander-computed exit codes for argument and help-error paths, and cover the user-argv parse mode in the regression tests so invalid CLI invocations no longer report success when exits are intercepted. (#60923) Thanks @Linux2010.
+- Telegram/native command menu: trim long menu descriptions before dropping commands so sub-100 command sets can still fit Telegram's payload budget and keep more `/` entries visible. (#61129) Thanks @neeravmakwana.
+- Agents/Claude CLI: keep non-interactive `--permission-mode bypassPermissions` when custom `cliBackends.claude-cli.args` override defaults, including fallback resolution before the runtime plugin registry is active, so cron and heartbeat Claude CLI runs do not regress to interactive approval mode. (#61114) Thanks @cathrynlavery and @thewilloftheshadow.
+- Agents/skills: skip `.git` and `node_modules` when mirroring skills into sandbox workspaces so read-only sandboxes do not copy repo history or dependency trees. (#61090) Thanks @joelnishanth.
+- Android/Talk Mode: cancel in-flight `talk.speak` playback when speech is explicitly stopped, so stale replies stop starting after barge-in or manual stop. (#61164) Thanks @obviyus.
+- Plugins/onboarding: write dotted plugin uiHint paths like Brave `webSearch.mode` as nested plugin config so `llm-context` setup stops failing validation. (#61159) Thanks @obviyus.
+- Android/Talk Mode: restore voice replies on gateway-backed talk mode sessions by updating embedded runner transport overrides to the current agent transport API. (#61214) Thanks @obviyus.
+- Amazon Bedrock/aws-sdk auth: stop injecting the fake `AWS_PROFILE` apiKey marker when no AWS auth env vars exist, so instance-role and other default-chain setups keep working without poisoning provider config. (#61194) Thanks @wirjo.
 
 ## 2026.4.2
 
@@ -103,6 +162,8 @@ Docs: https://docs.openclaw.ai
 
 - Sandbox/security: block credential-path binds even when sandbox home paths resolve through canonical aliases, so agent containers cannot mount user secret stores through alternate home-directory paths. (#59157) Thanks @eleqtrizit.
 - Gateway/Windows scheduled tasks: preserve Task Scheduler settings on reinstall, fail loud when Scheduled Task `/Run` does not start, and report fast failed restarts with the actual elapsed time instead of a fake 60s timeout. (#59335) Thanks @tmimmanuel.
+- Control UI/model picker: preserve already-qualified `provider/model` refs from the server so models whose ids already contain slashes stop being double-prefixed and remapped to the wrong provider. (#49874) Thanks @ShionEria.
+- Models/selection: resolve bare model ids in session model switches against the configured allowlist before falling back to the current session provider, so Control UI model picks stop drifting into `google/k2p5` and similar wrong-provider refs. (#51580) Thanks @honwee.
 
 ## 2026.4.1-beta.1
 
@@ -133,6 +194,7 @@ Docs: https://docs.openclaw.ai
 - Image generation/providers: stop inferring private-network access from configured OpenAI, MiniMax, and fal image base URLs, and cap shared HTTP error-body reads so hostile or misconfigured endpoints fail closed without relaxing SSRF policy or buffering unbounded error payloads. Thanks @vincentkoc.
 - Browser/host inspection: keep static Chrome inspection helpers out of the activated browser runtime so `openclaw doctor browser` and related checks do not eagerly load the bundled browser plugin. (#59471) Thanks @vincentkoc.
 - Browser/CDP: normalize trailing-dot localhost absolute-form hosts before loopback checks so remote CDP websocket URLs like `ws://localhost.:...` rewrite back to the configured remote host. (#59236) Thanks @mappel-nv.
+- Browser/attach-only profiles: disconnect cached Playwright CDP sessions when stopping attach-only or remote CDP profiles, while still reporting never-started local managed profiles as not stopped. (#60097) Thanks @pedh.
 - Agents/output sanitization: strip namespaced `antml:thinking` blocks from user-visible text so Anthropic-style internal monologue tags do not leak into replies. (#59550) Thanks @obviyus.
 - Kimi Coding/tools: normalize Anthropic tool payloads into the OpenAI-compatible function shape Kimi Coding expects so tool calls stop losing required arguments. (#59440) Thanks @obviyus.
 - Image tool/paths: resolve relative local media paths against the agent `workspaceDir` instead of `process.cwd()` so inputs like `inbox/receipt.png` pass the local-path allowlist reliably. (#57222) Thanks Priyansh Gupta.
@@ -159,6 +221,15 @@ Docs: https://docs.openclaw.ai
 - TUI/chat: keep pending local sends visible and reconciled across history reloads, make busy/error recovery clearer through fallback and terminal-error paths, and reclaim transcript width for long links and paths. (#59800) Thanks @vincentkoc.
 - Exec approvals/channels: decouple initiating-surface approval availability from native delivery enablement so Telegram, Slack, and Discord still expose approvals when approvers exist and native target routing is configured separately. (#59776) Thanks @joelnishanth.
 - Agents/logging: keep orphaned-user transcript repair warnings focused on interactive runs, and downgrade background-trigger repairs (`heartbeat`, `cron`, `memory`, `overflow`) to debug logs to reduce false-alarm gateway noise.
+- Gateway/node pairing: require `operator.pairing` for node approvals end-to-end, while still requiring `operator.write` or `operator.admin` when the pending node commands need those higher scopes. (#60461) Thanks @eleqtrizit.
+- Providers/OpenRouter: gate Anthropic prompt-cache `cache_control` markers to native/default OpenRouter routes and preserve them for native OpenRouter hosts behind custom provider ids. Thanks @vincentkoc.
+- Browser/CDP: validate both initial and discovered CDP websocket endpoints before connect so strict SSRF policy blocks cross-host pivots and direct websocket targets. (#60469) Thanks @eleqtrizit.
+- Browser/profiles: reject remote browser profile `cdpUrl` values that violate strict SSRF policy before saving config, with clearer validation errors for blocked endpoints. (#60477) Thanks @eleqtrizit.
+- Browser/screenshots: stop sending `fromSurface: false` on CDP screenshots so managed Chrome 146+ browsers can capture images again. (#60682) Thanks @mvanhorn.
+- Mattermost/slash commands: harden native slash-command callback token validation to use constant-time secret comparison, matching the existing interaction-token path.
+- Control UI/mobile chat: reduce narrow-screen overflow by shrinking the chat pane minimum width, removing extra mobile padding, widening message groups, and hiding avatars on very small screens. (#60220) Thanks @macdao.
+- Android/Talk Mode: route spoken replies through `talk.speak`, keep compressed playback cleanup deterministic, and fall back to local TTS for legacy gateways that omit Talk error reasons. (#60954) Thanks @obviyus.
+- Android/Talk Mode: keep reply-speaker routing and teardown behavior aligned with the new remote playback path. (#60954) Thanks @MKV21.
 
 ## 2026.4.1
 

CONTRIBUTING.md

@@ -85,6 +85,12 @@ Welcome to the lobster tank! 🦞
 4. **Test/CI-only PRs for known `main` failures** → Don't open a PR. The Maintainer team is already tracking those failures, and PRs that only tweak tests or CI to chase them will be closed unless they are required to validate a new fix.
 5. **Questions** → Discord [#help](https://discord.com/channels/1456350064065904867/1459642797895319552) / [#users-helping-users](https://discord.com/channels/1456350064065904867/1459007081603403828)
 
+## PR Limits
+
+We cap at **10 open PRs per author**. If you exceed this, the `r: too-many-prs` label is added and your PR is auto-closed. This is a hard limit.
+
+For coordinated change sets that genuinely need more than 10 PRs, join the **#clawtributors** channel in Discord and talk to maintainers first.
+
 ## Before You PR
 
 - Test locally with your OpenClaw instance

apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt

@@ -381,11 +381,10 @@ class NodeRuntime(
         parseChatSendRunId(response) ?: idempotencyKey
       },
       speakAssistantReply = { text ->
-        // Skip if TalkModeManager is handling TTS (ttsOnAllResponses) to avoid
-        // double-speaking the same assistant reply from both pipelines.
-        if (!talkMode.ttsOnAllResponses) {
-          voiceReplySpeaker.speakAssistantReply(text)
-        }
+        // Voice-tab replies should speak through the dedicated reply speaker.
+        // Relying on talkMode.ttsOnAllResponses here can drop playback if the
+        // chat-event path misses the terminal event for this turn.
+        voiceReplySpeaker.speakAssistantReply(text)
       },
     )
   }
@@ -596,12 +595,11 @@ class NodeRuntime(
 
     scope.launch {
       prefs.talkEnabled.collect { enabled ->
-        // MicCaptureManager handles STT + send to gateway.
-        // TalkModeManager plays TTS on assistant responses.
+        // MicCaptureManager handles STT + send to gateway, while the dedicated
+        // reply speaker handles TTS for assistant replies in the voice tab.
         micCapture.setMicEnabled(enabled)
         if (enabled) {
-          // Mic on = user is on voice screen and wants TTS responses.
-          talkMode.ttsOnAllResponses = true
+          talkMode.ttsOnAllResponses = false
           scope.launch { talkMode.ensureChatSubscribed() }
         }
         externalAudioCaptureActive.value = enabled
@@ -762,8 +760,8 @@ class NodeRuntime(
     prefs.setTalkEnabled(value)
     if (value) {
       // Tapping mic on interrupts any active TTS (barge-in)
-      talkMode.stopTts()
-      talkMode.ttsOnAllResponses = true
+      stopVoicePlayback()
+      talkMode.ttsOnAllResponses = false
       scope.launch { talkMode.ensureChatSubscribed() }
     }
     micCapture.setMicEnabled(value)
@@ -778,18 +776,25 @@ class NodeRuntime(
     if (voiceReplySpeakerLazy.isInitialized()) {
       voiceReplySpeaker.setPlaybackEnabled(value)
     }
-    // Keep TalkMode in sync so speaker mute works when ttsOnAllResponses is active.
+    // Keep TalkMode in sync so any active Talk playback also respects speaker mute.
     talkMode.setPlaybackEnabled(value)
   }
 
   private fun stopActiveVoiceSession() {
     talkMode.ttsOnAllResponses = false
-    talkMode.stopTts()
+    stopVoicePlayback()
     micCapture.setMicEnabled(false)
     prefs.setTalkEnabled(false)
     externalAudioCaptureActive.value = false
   }
 
+  private fun stopVoicePlayback() {
+    talkMode.stopTts()
+    if (voiceReplySpeakerLazy.isInitialized()) {
+      voiceReplySpeaker.stopTts()
+    }
+  }
+
   fun refreshGatewayConnection() {
     val endpoint =
       connectedEndpoint ?: run {

apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt

@@ -64,6 +64,7 @@ data class GatewayConnectErrorDetails(
   val code: String?,
   val canRetryWithDeviceToken: Boolean,
   val recommendedNextStep: String?,
+  val reason: String? = null,
 )
 
 private data class SelectedConnectAuth(
@@ -116,6 +117,8 @@ class GatewaySession(
     val details: GatewayConnectErrorDetails? = null,
   )
 
+  data class RpcResult(val ok: Boolean, val payloadJson: String?, val error: ErrorShape?)
+
   private val json = Json { ignoreUnknownKeys = true }
   private val writeLock = Mutex()
   private val pending = ConcurrentHashMap<String, CompletableDeferred<RpcResponse>>()
@@ -196,6 +199,13 @@ class GatewaySession(
   }
 
   suspend fun request(method: String, paramsJson: String?, timeoutMs: Long = 15_000): String {
+    val res = requestDetailed(method = method, paramsJson = paramsJson, timeoutMs = timeoutMs)
+    if (res.ok) return res.payloadJson ?: ""
+    val err = res.error
+    throw IllegalStateException("${err?.code ?: "UNAVAILABLE"}: ${err?.message ?: "request failed"}")
+  }
+
+  suspend fun requestDetailed(method: String, paramsJson: String?, timeoutMs: Long = 15_000): RpcResult {
     val conn = currentConnection ?: throw IllegalStateException("not connected")
     val params =
       if (paramsJson.isNullOrBlank()) {
@@ -204,9 +214,7 @@ class GatewaySession(
         json.parseToJsonElement(paramsJson)
       }
     val res = conn.request(method, params, timeoutMs)
-    if (res.ok) return res.payloadJson ?: ""
-    val err = res.error
-    throw IllegalStateException("${err?.code ?: "UNAVAILABLE"}: ${err?.message ?: "request failed"}")
+    return RpcResult(ok = res.ok, payloadJson = res.payloadJson, error = res.error)
   }
 
   suspend fun refreshNodeCanvasCapability(timeoutMs: Long = 8_000): Boolean {
@@ -631,6 +639,7 @@ class GatewaySession(
                 code = it["code"].asStringOrNull(),
                 canRetryWithDeviceToken = it["canRetryWithDeviceToken"].asBooleanOrNull() == true,
                 recommendedNextStep = it["recommendedNextStep"].asStringOrNull(),
+                reason = it["reason"].asStringOrNull(),
               )
             }
           ErrorShape(code, msg, details)

apps/android/app/src/main/java/ai/openclaw/app/node/CanvasActionTrust.kt

@@ -14,30 +14,31 @@ object CanvasActionTrust {
     if (candidateUri.scheme.equals("file", ignoreCase = true)) {
       return false
     }
+    val normalizedCandidate = normalizeTrustedRemoteA2uiUri(candidateUri) ?: return false
 
     return trustedA2uiUrls.any { trusted ->
-      isTrustedA2uiPage(candidateUri, trusted)
+      matchesTrustedRemoteA2uiUrlExact(normalizedCandidate, trusted)
     }
   }
 
-  private fun isTrustedA2uiPage(candidateUri: URI, trustedUrl: String): Boolean {
+  private fun matchesTrustedRemoteA2uiUrlExact(candidateUri: URI, trustedUrl: String): Boolean {
     val trustedUri = parseUri(trustedUrl) ?: return false
-    if (!candidateUri.scheme.equals(trustedUri.scheme, ignoreCase = true)) return false
-    if (candidateUri.host?.equals(trustedUri.host, ignoreCase = true) != true) return false
-    if (effectivePort(candidateUri) != effectivePort(trustedUri)) return false
-
-    val trustedPath = trustedUri.rawPath?.takeIf { it.isNotBlank() } ?: return false
-    val candidatePath = candidateUri.rawPath?.takeIf { it.isNotBlank() } ?: return false
-    val trustedPrefix = if (trustedPath.endsWith("/")) trustedPath else "$trustedPath/"
-    return candidatePath == trustedPath || candidatePath.startsWith(trustedPrefix)
+    val normalizedTrusted = normalizeTrustedRemoteA2uiUri(trustedUri) ?: return false
+    return candidateUri == normalizedTrusted
   }
 
-  private fun effectivePort(uri: URI): Int {
-    if (uri.port >= 0) return uri.port
-    return when (uri.scheme?.lowercase()) {
-      "https" -> 443
-      "http" -> 80
-      else -> -1
+  private fun normalizeTrustedRemoteA2uiUri(uri: URI): URI? {
+    // Keep Android trust normalization aligned with iOS ScreenController:
+    // exact remote URL match, scheme/host normalized, fragment ignored.
+    val scheme = uri.scheme?.lowercase() ?: return null
+    if (scheme != "http" && scheme != "https") return null
+
+    val host = uri.host?.trim()?.takeIf { it.isNotEmpty() }?.lowercase() ?: return null
+
+    return try {
+      URI(scheme, uri.userInfo, host, uri.port, uri.rawPath, uri.rawQuery, null)
+    } catch (_: Throwable) {
+      null
     }
   }
 

apps/android/app/src/main/java/ai/openclaw/app/ui/CanvasScreen.kt

@@ -163,7 +163,7 @@ private fun disableForceDarkIfSupported(settings: WebSettings) {
   WebSettingsCompat.setForceDark(settings, WebSettingsCompat.FORCE_DARK_OFF)
 }
 
-private class CanvasA2UIActionBridge(
+internal class CanvasA2UIActionBridge(
   private val isTrustedPage: () -> Boolean,
   private val onMessage: (String) -> Unit,
 ) {

apps/android/app/src/main/java/ai/openclaw/app/voice/MicCaptureManager.kt

@@ -90,6 +90,7 @@ class MicCaptureManager(
   val isSending: StateFlow<Boolean> = _isSending
 
   private val messageQueue = ArrayDeque<String>()
+  private val messageQueueLock = Any()
   private var flushedPartialTranscript: String? = null
   private var pendingRunId: String? = null
   private var pendingAssistantEntryId: String? = null
@@ -105,6 +106,42 @@ class MicCaptureManager(
   private var ttsPauseDepth = 0
   private var resumeMicAfterTts = false
 
+  private fun enqueueMessage(message: String) {
+    synchronized(messageQueueLock) {
+      messageQueue.addLast(message)
+    }
+  }
+
+  private fun snapshotMessageQueue(): List<String> {
+    return synchronized(messageQueueLock) {
+      messageQueue.toList()
+    }
+  }
+
+  private fun hasQueuedMessages(): Boolean {
+    return synchronized(messageQueueLock) {
+      messageQueue.isNotEmpty()
+    }
+  }
+
+  private fun firstQueuedMessage(): String? {
+    return synchronized(messageQueueLock) {
+      messageQueue.firstOrNull()
+    }
+  }
+
+  private fun removeFirstQueuedMessage(): String? {
+    return synchronized(messageQueueLock) {
+      if (messageQueue.isEmpty()) null else messageQueue.removeFirst()
+    }
+  }
+
+  private fun queuedMessageCount(): Int {
+    return synchronized(messageQueueLock) {
+      messageQueue.size
+    }
+  }
+
   fun setMicEnabled(enabled: Boolean) {
     if (_micEnabled.value == enabled) return
     _micEnabled.value = enabled
@@ -207,7 +244,7 @@ class MicCaptureManager(
     pendingRunId = null
     pendingAssistantEntryId = null
     _isSending.value = false
-    if (messageQueue.isNotEmpty()) {
+    if (hasQueuedMessages()) {
       _statusText.value = queuedWaitingStatus()
     }
   }
@@ -315,7 +352,7 @@ class MicCaptureManager(
     _statusText.value =
       when {
         _isSending.value -> "Listening · sending queued voice"
-        messageQueue.isNotEmpty() -> "Listening · ${messageQueue.size} queued"
+        hasQueuedMessages() -> "Listening · ${queuedMessageCount()} queued"
         else -> "Listening"
       }
     _isListening.value = true
@@ -348,7 +385,7 @@ class MicCaptureManager(
       role = VoiceConversationRole.User,
       text = message,
     )
-    messageQueue.addLast(message)
+    enqueueMessage(message)
     publishQueue()
   }
 
@@ -367,12 +404,12 @@ class MicCaptureManager(
   }
 
   private fun publishQueue() {
-    _queuedMessages.value = messageQueue.toList()
+    _queuedMessages.value = snapshotMessageQueue()
   }
 
   private fun sendQueuedIfIdle() {
     if (_isSending.value) return
-    if (messageQueue.isEmpty()) {
+    if (!hasQueuedMessages()) {
       if (_micEnabled.value) {
         _statusText.value = "Listening"
       } else {
@@ -385,7 +422,7 @@ class MicCaptureManager(
       return
     }
 
-    val next = messageQueue.first()
+    val next = firstQueuedMessage() ?: return
     _isSending.value = true
     pendingRunTimeoutJob?.cancel()
     pendingRunTimeoutJob = null
@@ -403,7 +440,7 @@ class MicCaptureManager(
         if (runId == null) {
           pendingRunTimeoutJob?.cancel()
           pendingRunTimeoutJob = null
-          messageQueue.removeFirst()
+          removeFirstQueuedMessage()
           publishQueue()
           _isSending.value = false
           pendingAssistantEntryId = null
@@ -449,8 +486,7 @@ class MicCaptureManager(
   private fun completePendingTurn() {
     pendingRunTimeoutJob?.cancel()
     pendingRunTimeoutJob = null
-    if (messageQueue.isNotEmpty()) {
-      messageQueue.removeFirst()
+    if (removeFirstQueuedMessage() != null) {
       publishQueue()
     }
     pendingRunId = null
@@ -460,7 +496,7 @@ class MicCaptureManager(
   }
 
   private fun queuedWaitingStatus(): String {
-    return "${messageQueue.size} queued · waiting for gateway"
+    return "${queuedMessageCount()} queued · waiting for gateway"
   }
 
   private fun appendConversation(

apps/android/app/src/main/java/ai/openclaw/app/voice/TalkAudioPlayer.kt

@@ -0,0 +1,242 @@
+package ai.openclaw.app.voice
+
+import android.content.Context
+import android.media.AudioAttributes
+import android.media.AudioFormat
+import android.media.AudioTrack
+import android.media.MediaPlayer
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.withContext
+import java.io.File
+
+internal class TalkAudioPlayer(
+  private val context: Context,
+) {
+  private val lock = Any()
+  private var active: ActivePlayback? = null
+
+  suspend fun play(audio: TalkSpeakAudio) {
+    when (val mode = resolvePlaybackMode(audio)) {
+      is TalkPlaybackMode.Pcm -> playPcm(audio.bytes, mode.sampleRate)
+      is TalkPlaybackMode.Compressed -> playCompressed(audio.bytes, mode.fileExtension)
+    }
+  }
+
+  fun stop() {
+    synchronized(lock) {
+      active?.cancel()
+      active = null
+    }
+  }
+
+  internal fun resolvePlaybackMode(audio: TalkSpeakAudio): TalkPlaybackMode {
+    return resolvePlaybackMode(
+      outputFormat = audio.outputFormat,
+      mimeType = audio.mimeType,
+      fileExtension = audio.fileExtension,
+    )
+  }
+
+  companion object {
+    internal fun resolvePlaybackMode(
+      outputFormat: String?,
+      mimeType: String?,
+      fileExtension: String?,
+    ): TalkPlaybackMode {
+      val normalizedOutputFormat = outputFormat?.trim()?.lowercase()
+      if (normalizedOutputFormat != null) {
+        val pcmSampleRate = parsePcmSampleRate(normalizedOutputFormat)
+        if (pcmSampleRate != null) {
+          return TalkPlaybackMode.Pcm(sampleRate = pcmSampleRate)
+        }
+      }
+      val normalizedMimeType = mimeType?.trim()?.lowercase()
+      val extension =
+        normalizeExtension(
+          fileExtension ?: inferExtension(outputFormat = normalizedOutputFormat, mimeType = normalizedMimeType),
+        )
+      if (extension != null) {
+        return TalkPlaybackMode.Compressed(fileExtension = extension)
+      }
+      throw IllegalStateException("Unsupported talk audio format")
+    }
+
+    private fun parsePcmSampleRate(outputFormat: String): Int? {
+      return when (outputFormat) {
+        "pcm_16000" -> 16_000
+        "pcm_22050" -> 22_050
+        "pcm_24000" -> 24_000
+        "pcm_44100" -> 44_100
+        else -> null
+      }
+    }
+
+    private fun inferExtension(outputFormat: String?, mimeType: String?): String? {
+      return when {
+        outputFormat == "mp3" || outputFormat?.startsWith("mp3_") == true || mimeType == "audio/mpeg" -> ".mp3"
+        outputFormat == "opus" || outputFormat?.startsWith("opus_") == true || mimeType == "audio/ogg" -> ".ogg"
+        outputFormat?.endsWith("-wav") == true || mimeType == "audio/wav" -> ".wav"
+        outputFormat?.endsWith("-webm") == true || mimeType == "audio/webm" -> ".webm"
+        else -> null
+      }
+    }
+
+    private fun normalizeExtension(value: String?): String? {
+      val trimmed = value?.trim()?.lowercase().orEmpty()
+      if (trimmed.isEmpty()) return null
+      return if (trimmed.startsWith(".")) trimmed else ".$trimmed"
+    }
+  }
+
+  private suspend fun playPcm(bytes: ByteArray, sampleRate: Int) {
+    withContext(Dispatchers.IO) {
+      val minBufferSize =
+        AudioTrack.getMinBufferSize(
+          sampleRate,
+          AudioFormat.CHANNEL_OUT_MONO,
+          AudioFormat.ENCODING_PCM_16BIT,
+        )
+      if (minBufferSize <= 0) {
+        throw IllegalStateException("AudioTrack buffer unavailable")
+      }
+      val track =
+        AudioTrack.Builder()
+          .setAudioAttributes(
+            AudioAttributes.Builder()
+              .setUsage(AudioAttributes.USAGE_MEDIA)
+              .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+              .build(),
+          )
+          .setAudioFormat(
+            AudioFormat.Builder()
+              .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
+              .setSampleRate(sampleRate)
+              .setChannelMask(AudioFormat.CHANNEL_OUT_MONO)
+              .build(),
+          )
+          .setTransferMode(AudioTrack.MODE_STATIC)
+          .setBufferSizeInBytes(maxOf(minBufferSize, bytes.size))
+          .build()
+      val finished = CompletableDeferred<Unit>()
+      val playback =
+        ActivePlayback(
+          cancel = {
+            finished.completeExceptionally(CancellationException("assistant speech cancelled"))
+            runCatching { track.pause() }
+            runCatching { track.flush() }
+            runCatching { track.stop() }
+          },
+        )
+      register(playback)
+      try {
+        val written = track.write(bytes, 0, bytes.size)
+        if (written != bytes.size) {
+          throw IllegalStateException("AudioTrack write failed")
+        }
+        val totalFrames = bytes.size / 2
+        track.play()
+        while (track.playState == AudioTrack.PLAYSTATE_PLAYING) {
+          if (track.playbackHeadPosition >= totalFrames) {
+            finished.complete(Unit)
+            break
+          }
+          delay(20)
+        }
+        if (!finished.isCompleted) {
+          finished.complete(Unit)
+        }
+        finished.await()
+      } finally {
+        clear(playback)
+        runCatching { track.pause() }
+        runCatching { track.flush() }
+        runCatching { track.stop() }
+        track.release()
+      }
+    }
+  }
+
+  private suspend fun playCompressed(bytes: ByteArray, fileExtension: String) {
+    val tempFile = withContext(Dispatchers.IO) {
+      File.createTempFile("talk-audio-", fileExtension, context.cacheDir).apply {
+        writeBytes(bytes)
+      }
+    }
+    try {
+      val finished = CompletableDeferred<Unit>()
+      val player =
+        withContext(Dispatchers.Main) {
+          MediaPlayer().apply {
+            setAudioAttributes(
+              AudioAttributes.Builder()
+                .setUsage(AudioAttributes.USAGE_MEDIA)
+                .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                .build(),
+            )
+            setDataSource(tempFile.absolutePath)
+            setOnCompletionListener {
+              finished.complete(Unit)
+            }
+            setOnErrorListener { _, what, extra ->
+              finished.completeExceptionally(IllegalStateException("MediaPlayer error ($what/$extra)"))
+              true
+            }
+            prepare()
+          }
+        }
+      val playback =
+        ActivePlayback(
+          cancel = {
+            finished.completeExceptionally(CancellationException("assistant speech cancelled"))
+            runCatching { player.stop() }
+          },
+        )
+      register(playback)
+      try {
+        withContext(Dispatchers.Main) {
+          player.start()
+        }
+        finished.await()
+      } finally {
+        clear(playback)
+        withContext(Dispatchers.Main) {
+          runCatching { player.stop() }
+          player.release()
+        }
+      }
+    } finally {
+      withContext(Dispatchers.IO) {
+        tempFile.delete()
+      }
+    }
+  }
+
+  private fun register(playback: ActivePlayback) {
+    synchronized(lock) {
+      active?.cancel()
+      active = playback
+    }
+  }
+
+  private fun clear(playback: ActivePlayback) {
+    synchronized(lock) {
+      if (active === playback) {
+        active = null
+      }
+    }
+  }
+
+}
+
+internal sealed interface TalkPlaybackMode {
+  data class Pcm(val sampleRate: Int) : TalkPlaybackMode
+
+  data class Compressed(val fileExtension: String) : TalkPlaybackMode
+}
+
+private class ActivePlayback(
+  val cancel: () -> Unit,
+)

apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeManager.kt

@@ -14,9 +14,9 @@ import android.os.SystemClock
 import android.speech.RecognitionListener
 import android.speech.RecognizerIntent
 import android.speech.SpeechRecognizer
-import android.util.Log
 import android.speech.tts.TextToSpeech
 import android.speech.tts.UtteranceProgressListener
+import android.util.Log
 import androidx.core.content.ContextCompat
 import ai.openclaw.app.gateway.GatewaySession
 import java.util.Locale
@@ -61,6 +61,8 @@ class TalkModeManager(
 
   private val mainHandler = Handler(Looper.getMainLooper())
   private val json = Json { ignoreUnknownKeys = true }
+  private val talkSpeakClient = TalkSpeakClient(session = session, json = json)
+  private val talkAudioPlayer = TalkAudioPlayer(context)
 
   private val _isEnabled = MutableStateFlow(false)
   val isEnabled: StateFlow<Boolean> = _isEnabled
@@ -264,7 +266,6 @@ class TalkModeManager(
     if (playbackEnabled == enabled) return
     playbackEnabled = enabled
     if (!enabled) {
-      playbackGeneration.incrementAndGet()
       stopSpeaking()
     }
   }
@@ -663,16 +664,32 @@ class TalkModeManager(
     requestAudioFocusForTts()
 
     try {
-      val ttsStarted = SystemClock.elapsedRealtime()
-      speakWithSystemTts(cleaned, directive, playbackToken)
-      Log.d(tag, "system tts ok durMs=${SystemClock.elapsedRealtime() - ttsStarted}")
+      val started = SystemClock.elapsedRealtime()
+      when (val result = talkSpeakClient.synthesize(text = cleaned, directive = directive)) {
+        is TalkSpeakResult.Success -> {
+          ensurePlaybackActive(playbackToken)
+          talkAudioPlayer.play(result.audio)
+          ensurePlaybackActive(playbackToken)
+          Log.d(tag, "talk.speak ok durMs=${SystemClock.elapsedRealtime() - started}")
+        }
+        is TalkSpeakResult.FallbackToLocal -> {
+          Log.d(tag, "talk.speak unavailable; using local TTS: ${result.message}")
+          speakWithSystemTts(cleaned, directive, playbackToken)
+          Log.d(tag, "system tts ok durMs=${SystemClock.elapsedRealtime() - started}")
+        }
+        is TalkSpeakResult.Failure -> {
+          throw IllegalStateException(result.message)
+        }
+      }
     } catch (err: Throwable) {
       if (isPlaybackCancelled(err, playbackToken)) {
         Log.d(tag, "assistant speech cancelled")
         return
       }
       _statusText.value = "Speak failed: ${err.message ?: err::class.simpleName}"
-      Log.w(tag, "system tts failed: ${err.message ?: err::class.simpleName}")
+      Log.w(tag, "talk playback failed: ${err.message ?: err::class.simpleName}")
+    } finally {
+      _isSpeaking.value = false
     }
   }
 
@@ -724,6 +741,7 @@ class TalkModeManager(
         ttsJob
       }
     activeJob?.cancel()
+    talkAudioPlayer.stop()
     stopTextToSpeechPlayback()
   }
 
@@ -811,15 +829,16 @@ class TalkModeManager(
   }
 
   private fun stopSpeaking(resetInterrupt: Boolean = true) {
+    playbackGeneration.incrementAndGet()
     if (!_isSpeaking.value) {
-      stopTextToSpeechPlayback()
+      cancelActivePlayback()
       abandonAudioFocus()
       return
     }
     if (resetInterrupt) {
       lastInterruptedAtSeconds = null
     }
-    stopTextToSpeechPlayback()
+    cancelActivePlayback()
     _isSpeaking.value = false
     abandonAudioFocus()
   }

apps/android/app/src/main/java/ai/openclaw/app/voice/TalkSpeakClient.kt

@@ -0,0 +1,143 @@
+package ai.openclaw.app.voice
+
+import ai.openclaw.app.gateway.GatewaySession
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+
+internal data class TalkSpeakAudio(
+  val bytes: ByteArray,
+  val provider: String,
+  val outputFormat: String?,
+  val voiceCompatible: Boolean?,
+  val mimeType: String?,
+  val fileExtension: String?,
+)
+
+internal sealed interface TalkSpeakResult {
+  data class Success(val audio: TalkSpeakAudio) : TalkSpeakResult
+
+  data class FallbackToLocal(val message: String) : TalkSpeakResult
+
+  data class Failure(val message: String) : TalkSpeakResult
+}
+
+internal class TalkSpeakClient(
+  private val session: GatewaySession? = null,
+  private val json: Json = Json { ignoreUnknownKeys = true },
+  private val requestDetailed: (suspend (String, String, Long) -> GatewaySession.RpcResult)? = null,
+) {
+  suspend fun synthesize(text: String, directive: TalkDirective?): TalkSpeakResult {
+    val response =
+      try {
+        performRequest(
+          method = "talk.speak",
+          paramsJson = json.encodeToString(TalkSpeakRequest.from(text = text, directive = directive)),
+          timeoutMs = 45_000,
+        )
+      } catch (err: Throwable) {
+        return TalkSpeakResult.Failure(err.message ?: "talk.speak request failed")
+      }
+    if (!response.ok) {
+      val error = response.error
+      val message = error?.message ?: "talk.speak request failed"
+      return if (isFallbackEligible(error)) {
+        TalkSpeakResult.FallbackToLocal(message)
+      } else {
+        TalkSpeakResult.Failure(message)
+      }
+    }
+    val payload =
+      try {
+        json.decodeFromString<TalkSpeakResponse>(response.payloadJson ?: "")
+      } catch (err: Throwable) {
+        return TalkSpeakResult.Failure(err.message ?: "talk.speak payload invalid")
+      }
+    val bytes =
+      try {
+        android.util.Base64.decode(payload.audioBase64, android.util.Base64.DEFAULT)
+      } catch (err: Throwable) {
+        return TalkSpeakResult.Failure(err.message ?: "talk.speak audio decode failed")
+      }
+    if (bytes.isEmpty()) {
+      return TalkSpeakResult.Failure("talk.speak returned empty audio")
+    }
+    return TalkSpeakResult.Success(
+      TalkSpeakAudio(
+        bytes = bytes,
+        provider = payload.provider,
+        outputFormat = payload.outputFormat,
+        voiceCompatible = payload.voiceCompatible,
+        mimeType = payload.mimeType,
+        fileExtension = payload.fileExtension,
+      ),
+    )
+  }
+
+  private fun isFallbackEligible(error: GatewaySession.ErrorShape?): Boolean {
+    val reason = error?.details?.reason
+    if (reason == null) return true
+    return reason == "talk_unconfigured" ||
+      reason == "talk_provider_unsupported" ||
+      reason == "method_unavailable"
+  }
+
+  private suspend fun performRequest(
+    method: String,
+    paramsJson: String,
+    timeoutMs: Long,
+  ): GatewaySession.RpcResult {
+    requestDetailed?.let { return it(method, paramsJson, timeoutMs) }
+    val activeSession = session ?: throw IllegalStateException("session missing")
+    return activeSession.requestDetailed(method = method, paramsJson = paramsJson, timeoutMs = timeoutMs)
+  }
+}
+
+@Serializable
+internal data class TalkSpeakRequest(
+  val text: String,
+  val voiceId: String? = null,
+  val modelId: String? = null,
+  val outputFormat: String? = null,
+  val speed: Double? = null,
+  val rateWpm: Int? = null,
+  val stability: Double? = null,
+  val similarity: Double? = null,
+  val style: Double? = null,
+  val speakerBoost: Boolean? = null,
+  val seed: Long? = null,
+  val normalize: String? = null,
+  val language: String? = null,
+  val latencyTier: Int? = null,
+) {
+  companion object {
+    fun from(text: String, directive: TalkDirective?): TalkSpeakRequest {
+      return TalkSpeakRequest(
+        text = text,
+        voiceId = directive?.voiceId,
+        modelId = directive?.modelId,
+        outputFormat = directive?.outputFormat,
+        speed = directive?.speed,
+        rateWpm = directive?.rateWpm,
+        stability = directive?.stability,
+        similarity = directive?.similarity,
+        style = directive?.style,
+        speakerBoost = directive?.speakerBoost,
+        seed = directive?.seed,
+        normalize = directive?.normalize,
+        language = directive?.language,
+        latencyTier = directive?.latencyTier,
+      )
+    }
+  }
+}
+
+@Serializable
+private data class TalkSpeakResponse(
+  val audioBase64: String,
+  val provider: String,
+  val outputFormat: String? = null,
+  val voiceCompatible: Boolean? = null,
+  val mimeType: String? = null,
+  val fileExtension: String? = null,
+)

apps/android/app/src/test/java/ai/openclaw/app/node/CanvasActionTrustTest.kt

@@ -39,4 +39,34 @@ class CanvasActionTrustTest {
       ),
     )
   }
+
+  @Test
+  fun acceptsFragmentOnlyDifferenceForTrustedA2uiPage() {
+    assertTrue(
+      CanvasActionTrust.isTrustedCanvasActionUrl(
+        rawUrl = "https://canvas.example.com:9443/__openclaw__/cap/token/__openclaw__/a2ui/?platform=android#step2",
+        trustedA2uiUrls = listOf("https://canvas.example.com:9443/__openclaw__/cap/token/__openclaw__/a2ui/?platform=android"),
+      ),
+    )
+  }
+
+  @Test
+  fun rejectsQueryMismatchOnTrustedOriginAndPath() {
+    assertFalse(
+      CanvasActionTrust.isTrustedCanvasActionUrl(
+        rawUrl = "https://canvas.example.com:9443/__openclaw__/cap/token/__openclaw__/a2ui/?platform=ios",
+        trustedA2uiUrls = listOf("https://canvas.example.com:9443/__openclaw__/cap/token/__openclaw__/a2ui/?platform=android"),
+      ),
+    )
+  }
+
+  @Test
+  fun rejectsDescendantPathUnderTrustedA2uiRoot() {
+    assertFalse(
+      CanvasActionTrust.isTrustedCanvasActionUrl(
+        rawUrl = "https://canvas.example.com:9443/__openclaw__/cap/token/__openclaw__/a2ui/child/index.html?platform=android",
+        trustedA2uiUrls = listOf("https://canvas.example.com:9443/__openclaw__/cap/token/__openclaw__/a2ui/?platform=android"),
+      ),
+    )
+  }
 }

apps/android/app/src/test/java/ai/openclaw/app/ui/CanvasA2UIActionBridgeTest.kt

@@ -0,0 +1,50 @@
+package ai.openclaw.app.ui
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class CanvasA2UIActionBridgeTest {
+  @Test
+  fun forwardsTrimmedPayloadFromTrustedPage() {
+    val forwarded = mutableListOf<String>()
+    val bridge =
+      CanvasA2UIActionBridge(
+        isTrustedPage = { true },
+        onMessage = { forwarded += it },
+      )
+
+    bridge.postMessage("  {\"ok\":true}  ")
+
+    assertEquals(listOf("{\"ok\":true}"), forwarded)
+  }
+
+  @Test
+  fun rejectsPayloadFromUntrustedPage() {
+    val forwarded = mutableListOf<String>()
+    val bridge =
+      CanvasA2UIActionBridge(
+        isTrustedPage = { false },
+        onMessage = { forwarded += it },
+      )
+
+    bridge.postMessage("{\"ok\":true}")
+
+    assertTrue(forwarded.isEmpty())
+  }
+
+  @Test
+  fun rejectsBlankPayloadBeforeForwarding() {
+    val forwarded = mutableListOf<String>()
+    val bridge =
+      CanvasA2UIActionBridge(
+        isTrustedPage = { true },
+        onMessage = { forwarded += it },
+      )
+
+    bridge.postMessage("   ")
+    bridge.postMessage(null)
+
+    assertTrue(forwarded.isEmpty())
+  }
+}

apps/android/app/src/test/java/ai/openclaw/app/voice/TalkAudioPlayerTest.kt

@@ -0,0 +1,44 @@
+package ai.openclaw.app.voice
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class TalkAudioPlayerTest {
+  @Test
+  fun resolvesPcmPlaybackFromOutputFormat() {
+    val mode =
+      TalkAudioPlayer.resolvePlaybackMode(
+        outputFormat = "pcm_24000",
+        mimeType = null,
+        fileExtension = null,
+      )
+
+    assertEquals(TalkPlaybackMode.Pcm(sampleRate = 24_000), mode)
+  }
+
+  @Test
+  fun resolvesCompressedPlaybackFromMimeType() {
+    val mode =
+      TalkAudioPlayer.resolvePlaybackMode(
+        outputFormat = null,
+        mimeType = "audio/mpeg",
+        fileExtension = null,
+      )
+
+    assertEquals(TalkPlaybackMode.Compressed(fileExtension = ".mp3"), mode)
+  }
+
+  @Test
+  fun preservesProvidedExtensionForCompressedPlayback() {
+    val mode =
+      TalkAudioPlayer.resolvePlaybackMode(
+        outputFormat = null,
+        mimeType = "audio/webm",
+        fileExtension = "webm",
+      )
+
+    assertTrue(mode is TalkPlaybackMode.Compressed)
+    assertEquals(".webm", (mode as TalkPlaybackMode.Compressed).fileExtension)
+  }
+}

apps/android/app/src/test/java/ai/openclaw/app/voice/TalkModeManagerTest.kt

@@ -0,0 +1,97 @@
+package ai.openclaw.app.voice
+
+import ai.openclaw.app.gateway.DeviceAuthEntry
+import ai.openclaw.app.gateway.DeviceAuthTokenStore
+import ai.openclaw.app.gateway.DeviceIdentityStore
+import ai.openclaw.app.gateway.GatewaySession
+import java.util.concurrent.atomic.AtomicLong
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class TalkModeManagerTest {
+  @Test
+  fun stopTtsCancelsTrackedPlaybackJob() {
+    val manager = createManager()
+    val playbackJob = Job()
+
+    setPrivateField(manager, "ttsJob", playbackJob)
+    playbackGeneration(manager).set(7L)
+
+    manager.stopTts()
+
+    assertTrue(playbackJob.isCancelled)
+    assertEquals(8L, playbackGeneration(manager).get())
+  }
+
+  @Test
+  fun disablingPlaybackCancelsTrackedJobOnce() {
+    val manager = createManager()
+    val playbackJob = Job()
+
+    setPrivateField(manager, "ttsJob", playbackJob)
+    playbackGeneration(manager).set(11L)
+
+    manager.setPlaybackEnabled(false)
+    manager.setPlaybackEnabled(false)
+
+    assertTrue(playbackJob.isCancelled)
+    assertEquals(12L, playbackGeneration(manager).get())
+  }
+
+  private fun createManager(): TalkModeManager {
+    val app = RuntimeEnvironment.getApplication()
+    val sessionJob = SupervisorJob()
+    val session =
+      GatewaySession(
+        scope = CoroutineScope(sessionJob + Dispatchers.Default),
+        identityStore = DeviceIdentityStore(app),
+        deviceAuthStore = InMemoryDeviceAuthStore(),
+        onConnected = { _, _, _ -> },
+        onDisconnected = {},
+        onEvent = { _, _ -> },
+      )
+    return TalkModeManager(
+      context = app,
+      scope = CoroutineScope(SupervisorJob() + Dispatchers.Default),
+      session = session,
+      supportsChatSubscribe = false,
+      isConnected = { true },
+    )
+  }
+
+  @Suppress("UNCHECKED_CAST")
+  private fun playbackGeneration(manager: TalkModeManager): AtomicLong {
+    return readPrivateField(manager, "playbackGeneration") as AtomicLong
+  }
+
+  private fun setPrivateField(target: Any, name: String, value: Any?) {
+    val field = target.javaClass.getDeclaredField(name)
+    field.isAccessible = true
+    field.set(target, value)
+  }
+
+  private fun readPrivateField(target: Any, name: String): Any? {
+    val field = target.javaClass.getDeclaredField(name)
+    field.isAccessible = true
+    return field.get(target)
+  }
+}
+
+private class InMemoryDeviceAuthStore : DeviceAuthTokenStore {
+  override fun loadEntry(deviceId: String, role: String): DeviceAuthEntry? = null
+
+  override fun saveToken(deviceId: String, role: String, token: String, scopes: List<String>) = Unit
+
+  override fun clearToken(deviceId: String, role: String) = Unit
+}

apps/android/app/src/test/java/ai/openclaw/app/voice/TalkSpeakClientTest.kt

@@ -0,0 +1,128 @@
+package ai.openclaw.app.voice
+
+import ai.openclaw.app.gateway.GatewayConnectErrorDetails
+import ai.openclaw.app.gateway.GatewaySession
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class TalkSpeakClientTest {
+  @Test
+  fun buildsRequestFromDirective() {
+    val request =
+      TalkSpeakRequest.from(
+        text = "Hello from talk mode.",
+        directive =
+          TalkDirective(
+            voiceId = "voice-123",
+            modelId = "model-abc",
+            speed = 1.1,
+            rateWpm = 190,
+            stability = 0.5,
+            similarity = 0.7,
+            style = 0.2,
+            speakerBoost = true,
+            seed = 42,
+            normalize = "auto",
+            language = "en",
+            outputFormat = "pcm_24000",
+            latencyTier = 3,
+            once = true,
+          ),
+      )
+
+    assertEquals("Hello from talk mode.", request.text)
+    assertEquals("voice-123", request.voiceId)
+    assertEquals("model-abc", request.modelId)
+    assertEquals(1.1, request.speed)
+    assertEquals(190, request.rateWpm)
+    assertEquals(0.5, request.stability)
+    assertEquals(0.7, request.similarity)
+    assertEquals(0.2, request.style)
+    assertEquals(true, request.speakerBoost)
+    assertEquals(42L, request.seed)
+    assertEquals("auto", request.normalize)
+    assertEquals("en", request.language)
+    assertEquals("pcm_24000", request.outputFormat)
+    assertEquals(3, request.latencyTier)
+  }
+
+  @Test
+  fun fallsBackOnlyForUnavailableReasons() = runTest {
+    val client =
+      TalkSpeakClient(
+        requestDetailed = { _, _, _ ->
+          GatewaySession.RpcResult(
+            ok = false,
+            payloadJson = null,
+            error =
+              GatewaySession.ErrorShape(
+                code = "UNAVAILABLE",
+                message = "talk unavailable",
+                details =
+                  GatewayConnectErrorDetails(
+                    code = null,
+                    canRetryWithDeviceToken = false,
+                    recommendedNextStep = null,
+                    reason = "talk_unconfigured",
+                  ),
+              ),
+          )
+        },
+      )
+
+    val result = client.synthesize(text = "Hello", directive = null)
+    assertTrue(result is TalkSpeakResult.FallbackToLocal)
+  }
+
+  @Test
+  fun doesNotFallBackForSynthesisFailure() = runTest {
+    val client =
+      TalkSpeakClient(
+        requestDetailed = { _, _, _ ->
+          GatewaySession.RpcResult(
+            ok = false,
+            payloadJson = null,
+            error =
+              GatewaySession.ErrorShape(
+                code = "UNAVAILABLE",
+                message = "provider failed",
+                details =
+                  GatewayConnectErrorDetails(
+                    code = null,
+                    canRetryWithDeviceToken = false,
+                    recommendedNextStep = null,
+                    reason = "synthesis_failed",
+                  ),
+              ),
+          )
+        },
+      )
+
+    val result = client.synthesize(text = "Hello", directive = null)
+    assertTrue(result is TalkSpeakResult.Failure)
+  }
+
+  @Test
+  fun fallsBackWhenGatewayOmitsReason() = runTest {
+    val client =
+      TalkSpeakClient(
+        requestDetailed = { _, _, _ ->
+          GatewaySession.RpcResult(
+            ok = false,
+            payloadJson = null,
+            error =
+              GatewaySession.ErrorShape(
+                code = "INVALID_REQUEST",
+                message = "unknown method: talk.speak",
+                details = null,
+              ),
+          )
+        },
+      )
+
+    val result = client.synthesize(text = "Hello", directive = null)
+    assertTrue(result is TalkSpeakResult.FallbackToLocal)
+  }
+}

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2019,6 +2019,7 @@ public struct TalkSpeakParams: Codable, Sendable {
     public let modelid: String?
     public let outputformat: String?
     public let speed: Double?
+    public let ratewpm: Int?
     public let stability: Double?
     public let similarity: Double?
     public let style: Double?
@@ -2026,6 +2027,7 @@ public struct TalkSpeakParams: Codable, Sendable {
     public let seed: Int?
     public let normalize: String?
     public let language: String?
+    public let latencytier: Int?
 
     public init(
         text: String,
@@ -2033,19 +2035,22 @@ public struct TalkSpeakParams: Codable, Sendable {
         modelid: String?,
         outputformat: String?,
         speed: Double?,
+        ratewpm: Int?,
         stability: Double?,
         similarity: Double?,
         style: Double?,
         speakerboost: Bool?,
         seed: Int?,
         normalize: String?,
-        language: String?)
+        language: String?,
+        latencytier: Int?)
     {
         self.text = text
         self.voiceid = voiceid
         self.modelid = modelid
         self.outputformat = outputformat
         self.speed = speed
+        self.ratewpm = ratewpm
         self.stability = stability
         self.similarity = similarity
         self.style = style
@@ -2053,6 +2058,7 @@ public struct TalkSpeakParams: Codable, Sendable {
         self.seed = seed
         self.normalize = normalize
         self.language = language
+        self.latencytier = latencytier
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -2061,6 +2067,7 @@ public struct TalkSpeakParams: Codable, Sendable {
         case modelid = "modelId"
         case outputformat = "outputFormat"
         case speed
+        case ratewpm = "rateWpm"
         case stability
         case similarity
         case style
@@ -2068,6 +2075,7 @@ public struct TalkSpeakParams: Codable, Sendable {
         case seed
         case normalize
         case language
+        case latencytier = "latencyTier"
     }
 }
 

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

@@ -2019,6 +2019,7 @@ public struct TalkSpeakParams: Codable, Sendable {
     public let modelid: String?
     public let outputformat: String?
     public let speed: Double?
+    public let ratewpm: Int?
     public let stability: Double?
     public let similarity: Double?
     public let style: Double?
@@ -2026,6 +2027,7 @@ public struct TalkSpeakParams: Codable, Sendable {
     public let seed: Int?
     public let normalize: String?
     public let language: String?
+    public let latencytier: Int?
 
     public init(
         text: String,
@@ -2033,19 +2035,22 @@ public struct TalkSpeakParams: Codable, Sendable {
         modelid: String?,
         outputformat: String?,
         speed: Double?,
+        ratewpm: Int?,
         stability: Double?,
         similarity: Double?,
         style: Double?,
         speakerboost: Bool?,
         seed: Int?,
         normalize: String?,
-        language: String?)
+        language: String?,
+        latencytier: Int?)
     {
         self.text = text
         self.voiceid = voiceid
         self.modelid = modelid
         self.outputformat = outputformat
         self.speed = speed
+        self.ratewpm = ratewpm
         self.stability = stability
         self.similarity = similarity
         self.style = style
@@ -2053,6 +2058,7 @@ public struct TalkSpeakParams: Codable, Sendable {
         self.seed = seed
         self.normalize = normalize
         self.language = language
+        self.latencytier = latencytier
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -2061,6 +2067,7 @@ public struct TalkSpeakParams: Codable, Sendable {
         case modelid = "modelId"
         case outputformat = "outputFormat"
         case speed
+        case ratewpm = "rateWpm"
         case stability
         case similarity
         case style
@@ -2068,6 +2075,7 @@ public struct TalkSpeakParams: Codable, Sendable {
         case seed
         case normalize
         case language
+        case latencytier = "latencyTier"
     }
 }
 

apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayNodeSessionTests.swift

@@ -275,8 +275,10 @@ struct GatewayNodeSessionTests {
                     "deviceToken": "operator-device-token",
                     "role": "operator",
                     "scopes": [
+                        "node.exec",
                         "operator.admin",
                         "operator.approvals",
+                        "operator.pairing",
                         "operator.read",
                         "operator.talk.secrets",
                         "operator.write",
@@ -315,8 +317,12 @@ struct GatewayNodeSessionTests {
         #expect(nodeEntry.token == "node-device-token")
         #expect(nodeEntry.scopes == [])
         #expect(operatorEntry.token == "operator-device-token")
-        #expect(operatorEntry.scopes.contains("operator.approvals"))
-        #expect(!operatorEntry.scopes.contains("operator.admin"))
+        #expect(operatorEntry.scopes == [
+            "operator.approvals",
+            "operator.read",
+            "operator.talk.secrets",
+            "operator.write",
+        ])
 
         await gateway.disconnect()
     }

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-ad87e3ff267b151ae163402f3cb52503e10641e332bcfbb6a574bbd7087a2484  config-baseline.json
-03ff4a3e314f17dd8851aed3653269294bc62412bee05a6804dce840bd3d7551  config-baseline.core.json
-73b57f395a2ad983f1660112d0b2b998342f1ddbe3089b440d7f73d0665de739  config-baseline.channel.json
-9d5cb864e70768b66c1ecd881a9a584b7696ef2e5b32df686cfdc3fa21ddabbe  config-baseline.plugin.json
+20a882f9991e17310013471756ac7ec62c272e29490daeede9c0901bd51c0e69  config-baseline.json
+8ba6e5c959d5fc3eee9e6c5d1d8f764f164052f4207c0352bb39e2a7dbad64a8  config-baseline.core.json
+ca6d1fa8a3507566979ea2da2b88a6a7ae49d650f3ebd3eee14a22ed18e5be89  config-baseline.channel.json
+17fd37605bf6cb087932ec2ebcfa9dd22e669fa6b8b93081ab2deac9d24821c5  config-baseline.plugin.json

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

@@ -1,2 +1,2 @@
-80a8238588cca3c6e0f89115f4271834b6e18f3497f70bc91dccc9203539cdd9  plugin-sdk-api-baseline.json
-68ed97a285d82f995f377db7823104976e8ebab5c6d0750332acb1d3d79288ef  plugin-sdk-api-baseline.jsonl
+cbffdf76d6a7254d8b2d3a601e1206d7b6c835bc44f170d4038bc711a35ef756  plugin-sdk-api-baseline.json
+fe026bf3ba1e3b55f6c0b560d76940f3c301d8f593d6f0f6dcc4625745c76d31  plugin-sdk-api-baseline.jsonl

docs/.i18n/glossary.zh-CN.json

@@ -55,10 +55,22 @@
     "source": "Qwen",
     "target": "Qwen"
   },
+  {
+    "source": "Feishu",
+    "target": "Feishu"
+  },
+  {
+    "source": "Mattermost",
+    "target": "Mattermost"
+  },
   {
     "source": "BytePlus (International)",
     "target": "BytePlus（国际版）"
   },
+  {
+    "source": "Anthropic (API + Claude CLI)",
+    "target": "Anthropic（API + Claude CLI）"
+  },
   {
     "source": "Moonshot AI",
     "target": "Moonshot AI"
@@ -163,6 +175,10 @@
     "source": "Network model",
     "target": "网络模型"
   },
+  {
+    "source": "Bridge protocol (legacy nodes, historical)",
+    "target": "Bridge protocol（旧版节点，历史参考）"
+  },
   {
     "source": "Doctor",
     "target": "Doctor"
@@ -171,6 +187,10 @@
     "source": "Polls",
     "target": "投票"
   },
+  {
+    "source": "QQ Bot",
+    "target": "QQ Bot"
+  },
   {
     "source": "Release Policy",
     "target": "发布策略"
@@ -219,6 +239,14 @@
     "source": "CLI",
     "target": "CLI"
   },
+  {
+    "source": "/cli/gateway",
+    "target": "/cli/gateway"
+  },
+  {
+    "source": "/gateway#multiple-gateways-same-host",
+    "target": "/gateway#multiple-gateways-same-host"
+  },
   {
     "source": "install sanity",
     "target": "安装完整性检查"

docs/auth-credential-semantics.md

@@ -17,13 +17,15 @@ This document defines the canonical credential eligibility and resolution semant
 
 The goal is to keep selection-time and runtime behavior aligned.
 
-## Stable Reason Codes
+## Stable Probe Reason Codes
 
 - `ok`
+- `excluded_by_auth_order`
 - `missing_credential`
 - `invalid_expires`
 - `expired`
 - `unresolved_ref`
+- `no_model`
 
 ## Token Credentials
 
@@ -44,6 +46,24 @@ Token credentials (`type: "token"`) support inline `token` and/or `tokenRef`.
 2. For eligible profiles, token material may be resolved from inline value or `tokenRef`.
 3. Unresolvable refs produce `unresolved_ref` in `models status --probe` output.
 
+## Explicit Auth Order Filtering
+
+- When `auth.order.<provider>` or the auth-store order override is set for a
+  provider, `models status --probe` only probes profile ids that remain in the
+  resolved auth order for that provider.
+- A stored profile for that provider that is omitted from the explicit order is
+  not silently tried later. Probe output reports it with
+  `reasonCode: excluded_by_auth_order` and the detail
+  `Excluded by auth.order for this provider.`
+
+## Probe Target Resolution
+
+- Probe targets can come from auth profiles, environment credentials, or
+  `models.json`.
+- If a provider has credentials but OpenClaw cannot resolve a probeable model
+  candidate for it, `models status --probe` reports `status: no_model` with
+  `reasonCode: no_model`.
+
 ## OAuth SecretRef Policy Guard
 
 - SecretRef input is for static credentials only.

docs/automation/cron-jobs.md

@@ -36,6 +36,12 @@ openclaw cron runs --id <job-id>
 - Jobs persist at `~/.openclaw/cron/jobs.json` so restarts do not lose schedules.
 - 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.
 
 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.
@@ -65,6 +71,12 @@ Recurring top-of-hour expressions are automatically staggered by up to 5 minutes
 
 **Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). **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.
 
+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.
+
+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.
+
 ### Payload options for isolated jobs
 
 - `--message`: prompt text (required for isolated)
@@ -72,6 +84,29 @@ Recurring top-of-hour expressions are automatically staggered by up to 5 minutes
 - `--light-context`: skip workspace bootstrap file injection
 - `--tools exec,read`: restrict which tools the job can use
 
+`--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:
+
+1. Gmail hook model override (when the run came from Gmail and that override is allowed)
+2. Per-job payload `model`
+3. 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.
+
+If an isolated run hits a live model-switch handoff, cron retries with the
+switched provider/model and persists that live selection before retrying. When
+the switch also carries a new auth profile, cron persists that auth profile
+override too. Retries are bounded: after the initial attempt plus 2 switch
+retries, cron aborts instead of looping forever.
+
 ## Delivery and output
 
 | Mode       | What happens                                             |
@@ -82,6 +117,22 @@ Recurring top-of-hour expressions are automatically staggered by up to 5 minutes
 
 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>`).
 
+For cron-owned isolated jobs, the runner owns the final delivery path. The
+agent is prompted to return a plain-text summary, and that summary is then sent
+through `announce`, `webhook`, or kept internal for `none`. `--no-deliver`
+does not hand delivery back to the agent; it keeps the run internal.
+
+If the original task explicitly says to message some external recipient, the
+agent should note who/where that message should go in its output instead of
+trying to send it directly.
+
+Failure notifications follow a separate destination path:
+
+- `cron.failureDestination` sets a global default for failure notifications.
+- `job.delivery.failureDestination` overrides that per job.
+- If neither is set and the job already delivers via `announce`, failure notifications now fall back to that primary announce target.
+- `delivery.failureDestination` is only supported on `sessionTarget="isolated"` jobs unless the primary delivery mode is `webhook`.
+
 ## CLI examples
 
 One-shot reminder (main session):
@@ -181,8 +232,10 @@ Custom hook names are resolved via `hooks.mappings` in config. Mappings can tran
 
 - 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.
 
 ## Gmail PubSub integration
@@ -270,6 +323,17 @@ openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --mes
 openclaw cron edit <jobId> --clear-agent
 ```
 
+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.
+
 ## Configuration
 
 ```json5
@@ -325,6 +389,12 @@ openclaw doctor
 - Delivery mode is `none` means no external message is expected.
 - Delivery target missing/invalid (`channel`/`to`) means outbound was skipped.
 - 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.
+- For cron-owned isolated jobs, do not expect the agent to use the message tool
+  as a fallback. The runner owns final delivery; `--no-deliver` keeps it
+  internal instead of allowing a direct send.
 
 ### Timezone gotchas
 

docs/automation/index.md

@@ -91,7 +91,7 @@ See [Hooks](/automation/hooks).
 
 ### Heartbeat
 
-Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records. Use `HEARTBEAT.md` to define what the agent checks.
+Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records. Use `HEARTBEAT.md` for a small checklist, or a `tasks:` block when you want due-only periodic checks inside heartbeat itself. Empty heartbeat files skip as `empty-heartbeat-file`; due-only task mode skips as `no-tasks-due`.
 
 See [Heartbeat](/gateway/heartbeat).
 

docs/automation/tasks.md

@@ -26,6 +26,13 @@ Not every agent run creates a task. Heartbeat turns and normal interactive chat
 - 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.
+- 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.
 - 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.
@@ -116,7 +123,7 @@ Transitions happen automatically — when the associated agent run ends, the tas
 
 When a task reaches a terminal state, OpenClaw notifies you. There are two delivery paths:
 
-**Direct delivery** — if the task has a channel target (the `requesterOrigin`), the completion message goes straight to that channel (Telegram, Discord, Slack, etc.).
+**Direct delivery** — if the task has a channel target (the `requesterOrigin`), the completion message goes straight to that channel (Telegram, Discord, Slack, etc.). For subagent completions, OpenClaw also preserves bound thread/topic routing when available and can fill a missing `to` / account from the requester session's stored route (`lastChannel` / `lastTo` / `lastAccountId`) before giving up on direct delivery.
 
 **Session-queued delivery** — if direct delivery fails or no origin is set, the update is queued as a system event in the requester's session and surfaces on the next heartbeat.
 
@@ -124,6 +131,10 @@ 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.
+
 ### Notification policies
 
 Control how much you hear about each task:
@@ -205,6 +216,15 @@ Reconciliation is runtime-aware:
 - 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.
+- Cleanup failures do not mask the real task outcome.
+
 ### `tasks flow list|show|cancel`
 
 ```bash

docs/brave-search.md

@@ -26,6 +26,7 @@ OpenClaw supports Brave Search API as a `web_search` provider.
         config: {
           webSearch: {
             apiKey: "BRAVE_API_KEY_HERE",
+            mode: "web", // or "llm-context"
           },
         },
       },
@@ -46,6 +47,11 @@ OpenClaw supports Brave Search API as a `web_search` provider.
 Provider-specific Brave search settings now live under `plugins.entries.brave.config.webSearch.*`.
 Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but it is no longer the canonical config path.
 
+`webSearch.mode` controls the Brave transport:
+
+- `web` (default): normal Brave web search with titles, URLs, and snippets
+- `llm-context`: Brave LLM Context API with pre-extracted text chunks and sources for grounding
+
 ## Tool parameters
 
 | Parameter     | Description                                                         |
@@ -54,6 +60,7 @@ Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but
 | `count`       | Number of results to return (1-10, default: 5)                      |
 | `country`     | 2-letter ISO country code (e.g., "US", "DE")                        |
 | `language`    | ISO 639-1 language code for search results (e.g., "en", "de", "fr") |
+| `search_lang` | Brave search-language code (e.g., `en`, `en-gb`, `zh-hans`)         |
 | `ui_lang`     | ISO language code for UI elements                                   |
 | `freshness`   | Time filter: `day` (24h), `week`, `month`, or `year`                |
 | `date_after`  | Only results published after this date (YYYY-MM-DD)                 |
@@ -88,6 +95,9 @@ await web_search({
 - OpenClaw uses the Brave **Search** plan. If you have a legacy subscription (e.g. the original Free plan with 2,000 queries/month), it remains valid but does not include newer features like LLM Context or higher rate limits.
 - Each Brave plan includes **\$5/month in free credit** (renewing). The Search plan costs \$5 per 1,000 requests, so the credit covers 1,000 queries/month. Set your usage limit in the Brave dashboard to avoid unexpected charges. See the [Brave API portal](https://brave.com/search/api/) for current plans.
 - The Search plan includes the LLM Context endpoint and AI inference rights. Storing results to train or tune models requires a plan with explicit storage rights. See the Brave [Terms of Service](https://api-dashboard.search.brave.com/terms-of-service).
+- `llm-context` mode returns grounded source entries instead of the normal web-search snippet shape.
+- `llm-context` mode does not support `ui_lang`, `freshness`, `date_after`, or `date_before`.
+- `ui_lang` must include a region subtag like `en-US`.
 - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`).
 
 See [Web tools](/tools/web) for the full web_search configuration.

docs/channels/bluebubbles.md

@@ -11,6 +11,11 @@ title: "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.
+
 ## Overview
 
 - Runs on macOS via the BlueBubbles helper app ([bluebubbles.app](https://bluebubbles.app)).
@@ -404,9 +409,9 @@ Prefer `chat_guid` for stable routing:
 
 ## Security
 
-- Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. Requests from `localhost` are also accepted.
+- Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`.
 - Keep the API password and webhook endpoint secret (treat them like credentials).
-- Localhost trust means a same-host reverse proxy can unintentionally bypass the password. If you proxy the gateway, require auth at the proxy and configure `gateway.trustedProxies`. See [Gateway security](/gateway/security#reverse-proxy-configuration).
+- There is no localhost bypass for BlueBubbles webhook auth. If you proxy webhook traffic, keep the BlueBubbles password on the request end-to-end. `gateway.trustedProxies` does not replace `channels.bluebubbles.password` here. See [Gateway security](/gateway/security#reverse-proxy-configuration).
 - Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN.
 
 ## Troubleshooting

docs/channels/discord.md

@@ -944,21 +944,24 @@ Default slash command settings:
 
   </Accordion>
 
-  <Accordion title="Exec approvals in Discord">
-    Discord supports button-based exec approvals in DMs and can optionally post approval prompts in the originating channel.
+  <Accordion title="Approvals in Discord">
+    Discord supports button-based approval handling in DMs and can optionally post approval prompts in the originating channel.
 
     Config path:
 
     - `channels.discord.execApprovals.enabled`
-    - `channels.discord.execApprovals.approvers` (optional; falls back to owner IDs inferred from `allowFrom` and explicit DM `defaultTo` when possible)
+    - `channels.discord.execApprovals.approvers` (optional; falls back to `commands.ownerAllowFrom` when possible)
     - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`)
     - `agentFilter`, `sessionFilter`, `cleanupAfterResolve`
 
-    Discord auto-enables native exec approvals when `enabled` is unset or `"auto"` and at least one approver can be resolved, either from `execApprovals.approvers` or from the account's existing owner config (`allowFrom`, legacy `dm.allowFrom`, or explicit DM `defaultTo`). Set `enabled: false` to disable Discord as a native approval client explicitly.
+    Discord auto-enables native exec approvals when `enabled` is unset or `"auto"` and at least one approver can be resolved, either from `execApprovals.approvers` or from `commands.ownerAllowFrom`. Discord does not infer exec approvers from channel `allowFrom`, legacy `dm.allowFrom`, or direct-message `defaultTo`. Set `enabled: false` to disable Discord as a native approval client explicitly.
 
     When `target` is `channel` or `both`, the approval prompt is visible in the channel. Only resolved approvers can use the buttons; other users receive an ephemeral denial. Approval prompts include the command text, so only enable channel delivery in trusted channels. If the channel ID cannot be derived from the session key, OpenClaw falls back to DM delivery.
 
     Discord also renders the shared approval buttons used by other chat channels. The native Discord adapter mainly adds approver DM routing and channel fanout.
+    When those buttons are present, they are the primary approval UX; OpenClaw
+    should only include a manual `/approve` command when the tool result says
+    chat approvals are unavailable or manual approval is the only path.
 
     Gateway auth for this handler uses the same shared credential resolution contract as other Gateway clients:
 
@@ -967,7 +970,16 @@ Default slash command settings:
     - remote-mode support via `gateway.remote.*` when applicable
     - URL overrides are override-safe: CLI overrides do not reuse implicit credentials, and env overrides use env credentials only
 
-    Exec approvals expire after 30 minutes by default. If approvals fail with unknown approval IDs, verify approver resolution and feature enablement.
+    Approval resolution behavior:
+
+    - IDs prefixed with `plugin:` resolve through `plugin.approval.resolve`.
+    - Other IDs resolve through `exec.approval.resolve`.
+    - Discord does not do an extra exec-to-plugin fallback hop here; the id
+      prefix decides which gateway method it calls.
+
+    Exec approvals expire after 30 minutes by default. If approvals fail with
+    unknown approval IDs, verify approver resolution, feature enablement, and
+    that the delivered approval id kind matches the pending request.
 
     Related docs: [Exec approvals](/tools/exec-approvals)
 

docs/channels/feishu.md

@@ -764,7 +764,8 @@ When the agent handles a Drive comment event, it receives:
 - the comment thread context for in-thread replies
 
 After making document edits, the agent is guided to use `feishu_drive.reply_comment` to notify the
-commenter and then output `NO_REPLY` to avoid duplicate sends.
+commenter and then output the exact silent token `NO_REPLY` / `no_reply` to
+avoid duplicate sends.
 
 ## Runtime action surface
 

docs/channels/group-messages.md

@@ -13,7 +13,7 @@ Note: `agents.list[].groupChat.mentionPatterns` is now used by Telegram/Discord/
 
 ## Current implementation (2025-12-03)
 
-- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, safe regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the silent token `NO_REPLY`. Defaults can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
+- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, safe regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the exact silent token `NO_REPLY` / `no_reply`. Defaults can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
 - Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders).
 - Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on` or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
 - Context injection: **pending-only** group messages (default 50) that _did not_ trigger a run are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`. Messages already in the session are not re-injected.

docs/channels/index.md

@@ -13,31 +13,31 @@ Text is supported everywhere; media and reactions vary by channel.
 
 ## Supported channels
 
-- [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).
+- [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (bundled plugin; edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).
 - [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
-- [Feishu](/channels/feishu) — Feishu/Lark bot via WebSocket (plugin, installed separately).
+- [Feishu](/channels/feishu) — Feishu/Lark bot via WebSocket (bundled plugin).
 - [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook.
 - [iMessage (legacy)](/channels/imessage) — Legacy macOS integration via imsg CLI (deprecated, use BlueBubbles for new setups).
 - [IRC](/channels/irc) — Classic IRC servers; channels + DMs with pairing/allowlist controls.
-- [LINE](/channels/line) — LINE Messaging API bot (plugin, installed separately).
-- [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
-- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately).
-- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately).
-- [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (plugin, installed separately).
-- [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (plugin, installed separately).
-- [QQ Bot](/channels/qqbot) — QQ Bot API; private chat, group chat, and rich media.
+- [LINE](/channels/line) — LINE Messaging API bot (bundled plugin).
+- [Matrix](/channels/matrix) — Matrix protocol (bundled plugin).
+- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (bundled plugin).
+- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (bundled plugin).
+- [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (bundled plugin).
+- [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (bundled plugin).
+- [QQ Bot](/channels/qqbot) — QQ Bot API; private chat, group chat, and rich media (bundled plugin).
 - [Signal](/channels/signal) — signal-cli; privacy-focused.
 - [Slack](/channels/slack) — Bolt SDK; workspace apps.
-- [Synology Chat](/channels/synology-chat) — Synology NAS Chat via outgoing+incoming webhooks (plugin, installed separately).
+- [Synology Chat](/channels/synology-chat) — Synology NAS Chat via outgoing+incoming webhooks (bundled plugin).
 - [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
-- [Tlon](/channels/tlon) — Urbit-based messenger (plugin, installed separately).
-- [Twitch](/channels/twitch) — Twitch chat via IRC connection (plugin, installed separately).
+- [Tlon](/channels/tlon) — Urbit-based messenger (bundled plugin).
+- [Twitch](/channels/twitch) — Twitch chat via IRC connection (bundled plugin).
 - [Voice Call](/plugins/voice-call) — Telephony via Plivo or Twilio (plugin, installed separately).
 - [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
 - [WeChat](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — Tencent iLink Bot plugin via QR login; private chats only.
 - [WhatsApp](/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing.
-- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).
-- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (plugin, installed separately).
+- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (bundled plugin).
+- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (bundled plugin).
 
 ## Notes
 

docs/channels/line.md

@@ -7,19 +7,23 @@ read_when:
 title: LINE
 ---
 
-# LINE (plugin)
+# LINE
 
 LINE connects to OpenClaw via the LINE Messaging API. The plugin runs as a webhook
 receiver on the gateway and uses your channel access token + channel secret for
 authentication.
 
-Status: supported via plugin. Direct messages, group chats, media, locations, Flex
+Status: bundled plugin. Direct messages, group chats, media, locations, Flex
 messages, template messages, and quick replies are supported. Reactions and threads
 are not supported.
 
-## Plugin required
+## Bundled plugin
 
-Install the LINE plugin:
+LINE ships as a bundled plugin in current OpenClaw releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes LINE, install it
+manually:
 
 ```bash
 openclaw plugins install @openclaw/line

docs/channels/matrix.md

@@ -6,14 +6,18 @@ read_when:
 title: "Matrix"
 ---
 
-# Matrix (plugin)
+# Matrix
 
-Matrix is the Matrix channel plugin for OpenClaw.
+Matrix is the Matrix bundled channel plugin for OpenClaw.
 It uses the official `matrix-js-sdk` and supports DMs, rooms, threads, media, reactions, polls, location, and E2EE.
 
-## Plugin required
+## Bundled plugin
 
-Matrix is a plugin and is not bundled with core OpenClaw.
+Matrix ships as a bundled plugin in current OpenClaw releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Matrix, install
+it manually:
 
 Install from npm:
 
@@ -31,7 +35,9 @@ See [Plugins](/tools/plugin) for plugin behavior and install rules.
 
 ## Setup
 
-1. Install the plugin.
+1. Ensure the Matrix plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
 2. Create a Matrix account on your homeserver.
 3. Configure `channels.matrix` with either:
    - `homeserver` + `accessToken`, or
@@ -661,6 +667,12 @@ Matrix can act as an exec approval client for a Matrix account.
 
 Approvers must be Matrix user IDs such as `@owner:example.org`. Matrix auto-enables native exec approvals when `enabled` is unset or `"auto"` and at least one approver can be resolved, either from `execApprovals.approvers` or from `channels.matrix.dm.allowFrom`. Set `enabled: false` to disable Matrix as a native approval client explicitly. Approval requests otherwise fall back to other configured approval routes or the exec approval fallback policy.
 
+Native Matrix routing is exec-only today:
+
+- `channels.matrix.execApprovals.*` controls native DM/channel routing for exec approvals only.
+- Plugin approvals still use shared same-chat `/approve` plus any configured `approvals.plugin` forwarding.
+- Matrix can still reuse `channels.matrix.dm.allowFrom` for plugin-approval authorization when it can infer approvers safely, but it does not expose a separate native plugin-approval DM/channel fanout path.
+
 Delivery rules:
 
 - `target: "dm"` sends approval prompts to approver DMs
@@ -671,7 +683,7 @@ Matrix uses text approval prompts today. Approvers resolve them with `/approve <
 
 Only resolved approvers can approve or deny. Channel delivery includes the command text, so only enable `channel` or `both` in trusted rooms.
 
-Matrix approval prompts reuse the shared core approval planner. The Matrix-specific surface is transport only: room/DM routing and message send/update/delete behavior.
+Matrix approval prompts reuse the shared core approval planner. The Matrix-specific native surface is transport only for exec approvals: room/DM routing and message send/update/delete behavior.
 
 Per-account override:
 
@@ -713,6 +725,7 @@ Top-level `channels.matrix` values act as defaults for named accounts unless an
 You can scope inherited room entries to one Matrix account with `groups.<room>.account` (or legacy `rooms.<room>.account`).
 Entries without `account` stay shared across all Matrix accounts, and entries with `account: "default"` still work when the default account is configured directly on top-level `channels.matrix.*`.
 Partial shared auth defaults do not create a separate implicit default account by themselves. OpenClaw only synthesizes the top-level `default` account when that default has fresh auth (`homeserver` plus `accessToken`, or `homeserver` plus `userId` and `password`); named accounts can still stay discoverable from `homeserver` plus `userId` when cached credentials satisfy auth later.
+If Matrix already has exactly one named account, or `defaultAccount` points at an existing named account key, single-account-to-multi-account repair/setup promotion preserves that account instead of creating a fresh `accounts.default` entry. Only Matrix auth/bootstrap keys move into that promoted account; shared delivery-policy keys stay at the top level.
 Set `defaultAccount` when you want OpenClaw to prefer one named Matrix account for implicit routing, probing, and CLI operations.
 If you configure multiple named accounts, set `defaultAccount` or pass `--account <id>` for CLI commands that rely on implicit account selection.
 Pass `--account <id>` to `openclaw matrix verify ...` and `openclaw matrix devices ...` when you want to override that implicit selection for one command.

docs/channels/mattermost.md

@@ -6,15 +6,19 @@ read_when:
 title: "Mattermost"
 ---
 
-# Mattermost (plugin)
+# Mattermost
 
-Status: supported via plugin (bot token + WebSocket events). Channels, groups, and DMs are supported.
+Status: bundled plugin (bot token + WebSocket events). Channels, groups, and DMs are supported.
 Mattermost is a self-hostable team messaging platform; see the official site at
 [mattermost.com](https://mattermost.com) for product details and downloads.
 
-## Plugin required
+## Bundled plugin
 
-Mattermost ships as a plugin and is not bundled with the core install.
+Mattermost ships as a bundled plugin in current OpenClaw releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Mattermost,
+install it manually:
 
 Install via CLI (npm registry):
 
@@ -28,14 +32,13 @@ Local checkout (when running from a git repo):
 openclaw plugins install ./path/to/local/mattermost-plugin
 ```
 
-If you choose Mattermost during setup and a git checkout is detected,
-OpenClaw will offer the local install path automatically.
-
 Details: [Plugins](/tools/plugin)
 
 ## Quick setup
 
-1. Install the Mattermost plugin.
+1. Ensure the Mattermost plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
 2. Create a Mattermost bot account and copy the **bot token**.
 3. Copy the Mattermost **base URL** (e.g., `https://chat.example.com`).
 4. Configure OpenClaw and start the gateway.
@@ -82,7 +85,10 @@ Notes:
 - If `callbackUrl` is omitted, OpenClaw derives one from gateway host/port + `callbackPath`.
 - For multi-account setups, `commands` can be set at the top level or under
   `channels.mattermost.accounts.<id>.commands` (account values override top-level fields).
-- Command callbacks are validated with per-command tokens and fail closed when token checks fail.
+- Command callbacks are validated with the per-command tokens returned by
+  Mattermost when OpenClaw registers `oc_*` commands.
+- Slash callbacks fail closed when registration failed, startup was partial, or
+  the callback token does not match one of the registered commands.
 - Reachability requirement: the callback endpoint must be reachable from the Mattermost server.
   - Do not set `callbackUrl` to `localhost` unless Mattermost runs on the same host/network namespace as OpenClaw.
   - Do not set `callbackUrl` to your Mattermost base URL unless that URL reverse-proxies `/api/channels/mattermost/command` to OpenClaw.
@@ -170,10 +176,28 @@ Notes:
 
 - Default: `channels.mattermost.groupPolicy = "allowlist"` (mention-gated).
 - Allowlist senders with `channels.mattermost.groupAllowFrom` (user IDs recommended).
+- Per-channel mention overrides live under `channels.mattermost.groups.<channelId>.requireMention`
+  or `channels.mattermost.groups["*"].requireMention` for a default.
 - `@username` matching is mutable and only enabled when `channels.mattermost.dangerouslyAllowNameMatching: true`.
 - Open channels: `channels.mattermost.groupPolicy="open"` (mention-gated).
 - Runtime note: if `channels.mattermost` is completely missing, runtime falls back to `groupPolicy="allowlist"` for group checks (even if `channels.defaults.groupPolicy` is set).
 
+Example:
+
+```json5
+{
+  channels: {
+    mattermost: {
+      groupPolicy: "open",
+      groups: {
+        "*": { requireMention: true },
+        "team-channel-id": { requireMention: false },
+      },
+    },
+  },
+}
+```
+
 ## Targets for outbound delivery
 
 Use these target formats with `openclaw message send` or cron/webhooks:
@@ -418,6 +442,19 @@ Mattermost supports multiple accounts under `channels.mattermost.accounts`:
 - No replies in channels: ensure the bot is in the channel and mention it (oncall), use a trigger prefix (onchar), or set `chatmode: "onmessage"`.
 - Auth errors: check the bot token, base URL, and whether the account is enabled.
 - Multi-account issues: env vars only apply to the `default` account.
+- Native slash commands return `Unauthorized: invalid command token.`: OpenClaw
+  did not accept the callback token. Typical causes:
+  - slash command registration failed or only partially completed at startup
+  - the callback is hitting the wrong gateway/account
+  - Mattermost still has old commands pointing at a previous callback target
+  - the gateway restarted without reactivating slash commands
+- If native slash commands stop working, check logs for
+  `mattermost: failed to register slash commands` or
+  `mattermost: native slash commands enabled but no commands could be registered`.
+- If `callbackUrl` is omitted and logs warn that the callback resolved to
+  `http://127.0.0.1:18789/...`, that URL is probably only reachable when
+  Mattermost runs on the same host/network namespace as OpenClaw. Set an
+  explicit externally reachable `commands.callbackUrl` instead.
 - Buttons appear as white boxes: the agent may be sending malformed button data. Check that each button has both `text` and `callback_data` fields.
 - Buttons render but clicks do nothing: verify `AllowedUntrustedInternalConnections` in Mattermost server config includes `127.0.0.1 localhost`, and that `EnablePostActionIntegration` is `true` in ServiceSettings.
 - Buttons return 404 on click: the button `id` likely contains hyphens or underscores. Mattermost's action router breaks on non-alphanumeric IDs. Use `[a-zA-Z0-9]` only.

docs/channels/msteams.md

@@ -5,7 +5,7 @@ read_when:
 title: "Microsoft Teams"
 ---
 
-# Microsoft Teams (plugin)
+# Microsoft Teams
 
 > "Abandon all hope, ye who enter here."
 
@@ -13,15 +13,13 @@ Updated: 2026-01-21
 
 Status: text + DM attachments are supported; channel/group file sending requires `sharePointSiteId` + Graph permissions (see [Sending files in group chats](#sending-files-in-group-chats)). Polls are sent via Adaptive Cards. Message actions expose explicit `upload-file` for file-first sends.
 
-## Plugin required
+## Bundled plugin
 
-Microsoft Teams ships as a plugin and is not bundled with the core install.
+Microsoft Teams ships as a bundled plugin in current OpenClaw releases, so no
+separate install is required in the normal packaged build.
 
-**Breaking change (2026.1.15):** Microsoft Teams moved out of core. If you use it, you must install the plugin.
-
-Explainable: keeps core installs lighter and lets Microsoft Teams dependencies update independently.
-
-Install via CLI (npm registry):
+If you are on an older build or a custom install that excludes bundled Teams,
+install it manually:
 
 ```bash
 openclaw plugins install @openclaw/msteams
@@ -33,14 +31,13 @@ Local checkout (when running from a git repo):
 openclaw plugins install ./path/to/local/msteams-plugin
 ```
 
-If you choose Teams during setup and a git checkout is detected,
-OpenClaw will offer the local install path automatically.
-
 Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 
-1. Install the Microsoft Teams plugin.
+1. Ensure the Microsoft Teams plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
 2. Create an **Azure Bot** (App ID + client secret + tenant ID).
 3. Configure OpenClaw with those credentials.
 4. Expose `/api/messages` (port 3978 by default) via a public URL or tunnel.
@@ -141,7 +138,9 @@ Example:
 
 ## How it works
 
-1. Install the Microsoft Teams plugin.
+1. Ensure the Microsoft Teams plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
 2. Create an **Azure Bot** (App ID + secret + tenant ID).
 3. Build a **Teams app package** that references the bot and includes the RSC permissions below.
 4. Upload/install the Teams app into a team (or personal scope for DMs).
@@ -240,9 +239,11 @@ This is often easier than hand-editing JSON manifests.
 
 ## Setup (minimal text-only)
 
-1. **Install the Microsoft Teams plugin**
-   - From npm: `openclaw plugins install @openclaw/msteams`
-   - From a local checkout: `openclaw plugins install ./path/to/local/msteams-plugin`
+1. **Ensure the Microsoft Teams plugin is available**
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually:
+     - From npm: `openclaw plugins install @openclaw/msteams`
+     - From a local checkout: `openclaw plugins install ./path/to/local/msteams-plugin`
 
 2. **Bot registration**
    - Create an Azure Bot (see above) and note:
@@ -284,7 +285,7 @@ This is often easier than hand-editing JSON manifests.
      - `https://<host>:3978/api/messages` (or your chosen path/port).
 
 6. **Run the gateway**
-   - The Teams channel starts automatically when the plugin is installed and `msteams` config exists with credentials.
+   - The Teams channel starts automatically when the bundled or manually installed plugin is available and `msteams` config exists with credentials.
 
 ## Member info action
 

docs/channels/nextcloud-talk.md

@@ -5,13 +5,17 @@ read_when:
 title: "Nextcloud Talk"
 ---
 
-# Nextcloud Talk (plugin)
+# Nextcloud Talk
 
-Status: supported via plugin (webhook bot). Direct messages, rooms, reactions, and markdown messages are supported.
+Status: bundled plugin (webhook bot). Direct messages, rooms, reactions, and markdown messages are supported.
 
-## Plugin required
+## Bundled plugin
 
-Nextcloud Talk ships as a plugin and is not bundled with the core install.
+Nextcloud Talk ships as a bundled plugin in current OpenClaw releases, so
+normal packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Nextcloud Talk,
+install it manually:
 
 Install via CLI (npm registry):
 
@@ -25,14 +29,13 @@ Local checkout (when running from a git repo):
 openclaw plugins install ./path/to/local/nextcloud-talk-plugin
 ```
 
-If you choose Nextcloud Talk during setup and a git checkout is detected,
-OpenClaw will offer the local install path automatically.
-
 Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 
-1. Install the Nextcloud Talk plugin.
+1. Ensure the Nextcloud Talk plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
 2. On your Nextcloud server, create a bot:
 
    ```bash

docs/channels/nostr.md

@@ -8,25 +8,20 @@ title: "Nostr"
 
 # Nostr
 
-**Status:** Optional plugin (disabled by default).
+**Status:** Optional bundled plugin (disabled by default until configured).
 
 Nostr is a decentralized protocol for social networking. This channel enables OpenClaw to receive and respond to encrypted direct messages (DMs) via NIP-04.
 
-## Install (on demand)
+## Bundled plugin
 
-### Onboarding (recommended)
+Current OpenClaw releases ship Nostr as a bundled plugin, so normal packaged
+builds do not need a separate install.
 
-- Onboarding (`openclaw onboard`) and `openclaw channels add` list optional channel plugins.
-- Selecting Nostr prompts you to install the plugin on demand.
+### Older/custom installs
 
-Install defaults:
-
-- **Dev channel + git checkout available:** uses the local plugin path.
-- **Stable/Beta:** downloads from npm.
-
-You can always override the choice in the prompt.
-
-### Manual install
+- Onboarding (`openclaw onboard`) and `openclaw channels add` still surface
+  Nostr from the shared channel catalog.
+- If your build excludes bundled Nostr, install it manually.
 
 ```bash
 openclaw plugins install @openclaw/nostr

docs/channels/pairing.md

@@ -77,6 +77,15 @@ The setup code is a base64-encoded JSON payload that contains:
 - `url`: the Gateway WebSocket URL (`ws://...` or `wss://...`)
 - `bootstrapToken`: a short-lived single-device bootstrap token used for the initial pairing handshake
 
+That bootstrap token carries the built-in pairing bootstrap profile:
+
+- primary handed-off `node` token stays `scopes: []`
+- any handed-off `operator` token stays bounded to the bootstrap allowlist:
+  `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
+- 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
+
 Treat the setup code like a password while it is valid.
 
 ### Approve a node device
@@ -102,6 +111,9 @@ Stored under `~/.openclaw/devices/`:
 
 - The legacy `node.pair.*` API (CLI: `openclaw nodes pending|approve|reject|rename`) is a
   separate gateway-owned pairing store. WS nodes still require device pairing.
+- The pairing record is the durable source of truth for approved roles. Active
+  device tokens stay bounded to that approved role set; a stray token entry
+  outside the approved roles does not create new access.
 
 ## Related docs
 

docs/channels/qa-channel.md

@@ -0,0 +1,99 @@
+---
+title: "QA Channel"
+summary: "Synthetic Slack-class channel plugin for deterministic OpenClaw QA scenarios"
+read_when:
+  - You are wiring the synthetic QA transport into a local or CI test run
+  - You need the bundled qa-channel config surface
+  - You are iterating on end-to-end QA automation
+---
+
+# QA Channel
+
+`qa-channel` is a bundled synthetic message transport for automated OpenClaw QA.
+
+It is not a production channel. It exists to exercise the same channel plugin
+boundary used by real transports while keeping state deterministic and fully
+inspectable.
+
+## What it does today
+
+- Slack-class target grammar:
+  - `dm:<user>`
+  - `channel:<room>`
+  - `thread:<room>/<thread>`
+- HTTP-backed synthetic bus for:
+  - inbound message injection
+  - outbound transcript capture
+  - thread creation
+  - reactions
+  - edits
+  - deletes
+  - search and read actions
+- Bundled host-side self-check runner that writes a Markdown report
+
+## Config
+
+```json
+{
+  "channels": {
+    "qa-channel": {
+      "baseUrl": "http://127.0.0.1:43123",
+      "botUserId": "openclaw",
+      "botDisplayName": "OpenClaw QA",
+      "allowFrom": ["*"],
+      "pollTimeoutMs": 1000
+    }
+  }
+}
+```
+
+Supported account keys:
+
+- `baseUrl`
+- `botUserId`
+- `botDisplayName`
+- `pollTimeoutMs`
+- `allowFrom`
+- `defaultTo`
+- `actions.messages`
+- `actions.reactions`
+- `actions.search`
+- `actions.threads`
+
+## Runner
+
+Current vertical slice:
+
+```bash
+pnpm qa:e2e
+```
+
+This now routes through the bundled `qa-lab` extension. It starts the in-repo
+QA bus, boots the bundled `qa-channel` runtime slice, runs a deterministic
+self-check, and writes a Markdown report under `.artifacts/qa-e2e/`.
+
+Private debugger UI:
+
+```bash
+pnpm qa:lab:build
+pnpm openclaw qa ui
+```
+
+That launches the private QA debugger at a local URL, separate from the
+shipped Control UI bundle.
+
+## Scope
+
+Current scope is intentionally narrow:
+
+- bus + plugin transport
+- threaded routing grammar
+- channel-owned message actions
+- Markdown reporting
+
+Follow-up work will add:
+
+- Dockerized OpenClaw orchestration
+- provider/model matrix execution
+- richer scenario discovery
+- OpenClaw-native orchestration later

docs/channels/qqbot.md

@@ -13,13 +13,13 @@ QQ Bot connects to OpenClaw via the official QQ Bot API (WebSocket gateway). The
 plugin supports C2C private chat, group @messages, and guild channel messages with
 rich media (images, voice, video, files).
 
-Status: bundled channel plugin. Direct messages, group chats, guild channels, and
+Status: bundled plugin. Direct messages, group chats, guild channels, and
 media are supported. Reactions and threads are not supported.
 
-## Bundled with OpenClaw
+## Bundled plugin
 
-Current OpenClaw installs bundle QQ Bot. You do not need a separate
-`openclaw plugins install` step for normal setup.
+Current OpenClaw releases bundle QQ Bot, so normal packaged builds do not need
+a separate `openclaw plugins install` step.
 
 ## Setup
 

docs/channels/signal.md

@@ -142,7 +142,7 @@ signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
 
 ```bash
 # If you run the gateway as a user systemd service:
-systemctl --user restart openclaw-gateway
+systemctl --user restart openclaw-gateway.service
 
 # Then verify:
 openclaw doctor

docs/channels/slack.md

@@ -120,275 +120,6 @@ openclaw gateway
   </Tab>
 </Tabs>
 
-## Token model
-
-- `botToken` + `appToken` are required for Socket Mode.
-- HTTP mode requires `botToken` + `signingSecret`.
-- Config tokens override env fallback.
-- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback applies only to the default account.
-- `userToken` (`xoxp-...`) is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`).
-- Optional: add `chat:write.customize` if you want outgoing messages to use the active agent identity (custom `username` and icon). `icon_emoji` uses `:emoji_name:` syntax.
-
-<Tip>
-For actions/directory reads, user token can be preferred when configured. For writes, bot token remains preferred; user-token writes are only allowed when `userTokenReadOnly: false` and bot token is unavailable.
-</Tip>
-
-## Access control and routing
-
-<Tabs>
-  <Tab title="DM policy">
-    `channels.slack.dmPolicy` controls DM access (legacy: `channels.slack.dm.policy`):
-
-    - `pairing` (default)
-    - `allowlist`
-    - `open` (requires `channels.slack.allowFrom` to include `"*"`; legacy: `channels.slack.dm.allowFrom`)
-    - `disabled`
-
-    DM flags:
-
-    - `dm.enabled` (default true)
-    - `channels.slack.allowFrom` (preferred)
-    - `dm.allowFrom` (legacy)
-    - `dm.groupEnabled` (group DMs default false)
-    - `dm.groupChannels` (optional MPIM allowlist)
-
-    Multi-account precedence:
-
-    - `channels.slack.accounts.default.allowFrom` applies only to the `default` account.
-    - Named accounts inherit `channels.slack.allowFrom` when their own `allowFrom` is unset.
-    - Named accounts do not inherit `channels.slack.accounts.default.allowFrom`.
-
-    Pairing in DMs uses `openclaw pairing approve slack <code>`.
-
-  </Tab>
-
-  <Tab title="Channel policy">
-    `channels.slack.groupPolicy` controls channel handling:
-
-    - `open`
-    - `allowlist`
-    - `disabled`
-
-    Channel allowlist lives under `channels.slack.channels` and should use stable channel IDs.
-
-    Runtime note: if `channels.slack` is completely missing (env-only setup), runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).
-
-    Name/ID resolution:
-
-    - channel allowlist entries and DM allowlist entries are resolved at startup when token access allows
-    - unresolved channel-name entries are kept as configured but ignored for routing by default
-    - inbound authorization and channel routing are ID-first by default; direct username/slug matching requires `channels.slack.dangerouslyAllowNameMatching: true`
-
-  </Tab>
-
-  <Tab title="Mentions and channel users">
-    Channel messages are mention-gated by default.
-
-    Mention sources:
-
-    - explicit app mention (`<@botId>`)
-    - mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
-    - implicit reply-to-bot thread behavior
-
-    Per-channel controls (`channels.slack.channels.<id>`; names only via startup resolution or `dangerouslyAllowNameMatching`):
-
-    - `requireMention`
-    - `users` (allowlist)
-    - `allowBots`
-    - `skills`
-    - `systemPrompt`
-    - `tools`, `toolsBySender`
-    - `toolsBySender` key format: `id:`, `e164:`, `username:`, `name:`, or `"*"` wildcard
-      (legacy unprefixed keys still map to `id:` only)
-
-  </Tab>
-</Tabs>
-
-## Commands and slash behavior
-
-- Native command auto-mode is **off** for Slack (`commands.native: "auto"` does not enable Slack native commands).
-- Enable native Slack command handlers with `channels.slack.commands.native: true` (or global `commands.native: true`).
-- When native commands are enabled, register matching slash commands in Slack (`/<command>` names), with one exception:
-  - register `/agentstatus` for the status command (Slack reserves `/status`)
-- If native commands are not enabled, you can run a single configured slash command via `channels.slack.slashCommand`.
-- Native arg menus now adapt their rendering strategy:
-  - up to 5 options: button blocks
-  - 6-100 options: static select menu
-  - more than 100 options: external select with async option filtering when interactivity options handlers are available
-  - if encoded option values exceed Slack limits, the flow falls back to buttons
-- For long option payloads, Slash command argument menus use a confirm dialog before dispatching a selected value.
-
-Default slash command settings:
-
-- `enabled: false`
-- `name: "openclaw"`
-- `sessionPrefix: "slack:slash"`
-- `ephemeral: true`
-
-Slash sessions use isolated keys:
-
-- `agent:<agentId>:slack:slash:<userId>`
-
-and still route command execution against the target conversation session (`CommandTargetSessionKey`).
-
-## Interactive replies
-
-Slack can render agent-authored interactive reply controls, but this feature is disabled by default.
-
-Enable it globally:
-
-```json5
-{
-  channels: {
-    slack: {
-      capabilities: {
-        interactiveReplies: true,
-      },
-    },
-  },
-}
-```
-
-Or enable it for one Slack account only:
-
-```json5
-{
-  channels: {
-    slack: {
-      accounts: {
-        ops: {
-          capabilities: {
-            interactiveReplies: true,
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-When enabled, agents can emit Slack-only reply directives:
-
-- `[[slack_buttons: Approve:approve, Reject:reject]]`
-- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
-
-These directives compile into Slack Block Kit and route clicks or selections back through the existing Slack interaction event path.
-
-Notes:
-
-- This is Slack-specific UI. Other channels do not translate Slack Block Kit directives into their own button systems.
-- The interactive callback values are OpenClaw-generated opaque tokens, not raw agent-authored values.
-- If generated interactive blocks would exceed Slack Block Kit limits, OpenClaw falls back to the original text reply instead of sending an invalid blocks payload.
-
-## Threading, sessions, and reply tags
-
-- DMs route as `direct`; channels as `channel`; MPIMs as `group`.
-- With default `session.dmScope=main`, Slack DMs collapse to agent main session.
-- Channel sessions: `agent:<agentId>:slack:channel:<channelId>`.
-- Thread replies can create thread session suffixes (`:thread:<threadTs>`) when applicable.
-- `channels.slack.thread.historyScope` default is `thread`; `thread.inheritParent` default is `false`.
-- `channels.slack.thread.initialHistoryLimit` controls how many existing thread messages are fetched when a new thread session starts (default `20`; set `0` to disable).
-
-Reply threading controls:
-
-- `channels.slack.replyToMode`: `off|first|all` (default `off`)
-- `channels.slack.replyToModeByChatType`: per `direct|group|channel`
-- legacy fallback for direct chats: `channels.slack.dm.replyToMode`
-
-Manual reply tags are supported:
-
-- `[[reply_to_current]]`
-- `[[reply_to:<id>]]`
-
-Note: `replyToMode="off"` disables **all** reply threading in Slack, including explicit `[[reply_to_*]]` tags. This differs from Telegram, where explicit tags are still honored in `"off"` mode. The difference reflects the platform threading models: Slack threads hide messages from the channel, while Telegram replies remain visible in the main chat flow.
-
-## Media, chunking, and delivery
-
-<AccordionGroup>
-  <Accordion title="Inbound attachments">
-    Slack file attachments are downloaded from Slack-hosted private URLs (token-authenticated request flow) and written to the media store when fetch succeeds and size limits permit.
-
-    Runtime inbound size cap defaults to `20MB` unless overridden by `channels.slack.mediaMaxMb`.
-
-  </Accordion>
-
-  <Accordion title="Outbound text and files">
-    - text chunks use `channels.slack.textChunkLimit` (default 4000)
-    - `channels.slack.chunkMode="newline"` enables paragraph-first splitting
-    - file sends use Slack upload APIs and can include thread replies (`thread_ts`)
-    - outbound media cap follows `channels.slack.mediaMaxMb` when configured; otherwise channel sends use MIME-kind defaults from media pipeline
-  </Accordion>
-
-  <Accordion title="Delivery targets">
-    Preferred explicit targets:
-
-    - `user:<id>` for DMs
-    - `channel:<id>` for channels
-
-    Slack DMs are opened via Slack conversation APIs when sending to user targets.
-
-  </Accordion>
-</AccordionGroup>
-
-## Actions and gates
-
-Slack actions are controlled by `channels.slack.actions.*`.
-
-Available action groups in current Slack tooling:
-
-| Group      | Default |
-| ---------- | ------- |
-| messages   | enabled |
-| reactions  | enabled |
-| pins       | enabled |
-| memberInfo | enabled |
-| emojiList  | enabled |
-
-Current Slack message actions include `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, and `emoji-list`.
-
-## Events and operational behavior
-
-- Message edits/deletes/thread broadcasts are mapped into system events.
-- Reaction add/remove events are mapped into system events.
-- Member join/leave, channel created/renamed, and pin add/remove events are mapped into system events.
-- Assistant thread status updates (for "is typing..." indicators in threads) use `assistant.threads.setStatus` and require bot scope `assistant:write`.
-- `channel_id_changed` can migrate channel config keys when `configWrites` is enabled.
-- Channel topic/purpose metadata is treated as untrusted context and can be injected into routing context.
-- Thread starter and initial thread-history context seeding are filtered by configured sender allowlists when applicable.
-- Block actions and modal interactions emit structured `Slack interaction: ...` system events with rich payload fields:
-  - block actions: selected values, labels, picker values, and `workflow_*` metadata
-  - modal `view_submission` and `view_closed` events with routed channel metadata and form inputs
-
-## Ack reactions
-
-`ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message.
-
-Resolution order:
-
-- `channels.slack.accounts.<accountId>.ackReaction`
-- `channels.slack.ackReaction`
-- `messages.ackReaction`
-- agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
-
-Notes:
-
-- Slack expects shortcodes (for example `"eyes"`).
-- Use `""` to disable the reaction for the Slack account or globally.
-
-## Typing reaction fallback
-
-`typingReaction` adds a temporary reaction to the inbound Slack message while OpenClaw is processing a reply, then removes it when the run finishes. This is a useful fallback when Slack native assistant typing is unavailable, especially in DMs.
-
-Resolution order:
-
-- `channels.slack.accounts.<accountId>.typingReaction`
-- `channels.slack.typingReaction`
-
-Notes:
-
-- Slack expects shortcodes (for example `"hourglass_flowing_sand"`).
-- The reaction is best-effort and cleanup is attempted automatically after the reply or failure path completes.
-
 ## Manifest and scope checklist
 
 <AccordionGroup>
@@ -483,11 +214,320 @@ Notes:
   </Accordion>
 </AccordionGroup>
 
+## Token model
+
+- `botToken` + `appToken` are required for Socket Mode.
+- HTTP mode requires `botToken` + `signingSecret`.
+- `botToken`, `appToken`, `signingSecret`, and `userToken` accept plaintext
+  strings or SecretRef objects.
+- Config tokens override env fallback.
+- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback applies only to the default account.
+- `userToken` (`xoxp-...`) is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`).
+- Optional: add `chat:write.customize` if you want outgoing messages to use the active agent identity (custom `username` and icon). `icon_emoji` uses `:emoji_name:` syntax.
+
+Status snapshot behavior:
+
+- Slack account inspection tracks per-credential `*Source` and `*Status`
+  fields (`botToken`, `appToken`, `signingSecret`, `userToken`).
+- Status is `available`, `configured_unavailable`, or `missing`.
+- `configured_unavailable` means the account is configured through SecretRef
+  or another non-inline secret source, but the current command/runtime path
+  could not resolve the actual value.
+- In HTTP mode, `signingSecretStatus` is included; in Socket Mode, the
+  required pair is `botTokenStatus` + `appTokenStatus`.
+
+<Tip>
+For actions/directory reads, user token can be preferred when configured. For writes, bot token remains preferred; user-token writes are only allowed when `userTokenReadOnly: false` and bot token is unavailable.
+</Tip>
+
+## Actions and gates
+
+Slack actions are controlled by `channels.slack.actions.*`.
+
+Available action groups in current Slack tooling:
+
+| Group      | Default |
+| ---------- | ------- |
+| messages   | enabled |
+| reactions  | enabled |
+| pins       | enabled |
+| memberInfo | enabled |
+| emojiList  | enabled |
+
+Current Slack message actions include `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, and `emoji-list`.
+
+## Access control and routing
+
+<Tabs>
+  <Tab title="DM policy">
+    `channels.slack.dmPolicy` controls DM access (legacy: `channels.slack.dm.policy`):
+
+    - `pairing` (default)
+    - `allowlist`
+    - `open` (requires `channels.slack.allowFrom` to include `"*"`; legacy: `channels.slack.dm.allowFrom`)
+    - `disabled`
+
+    DM flags:
+
+    - `dm.enabled` (default true)
+    - `channels.slack.allowFrom` (preferred)
+    - `dm.allowFrom` (legacy)
+    - `dm.groupEnabled` (group DMs default false)
+    - `dm.groupChannels` (optional MPIM allowlist)
+
+    Multi-account precedence:
+
+    - `channels.slack.accounts.default.allowFrom` applies only to the `default` account.
+    - Named accounts inherit `channels.slack.allowFrom` when their own `allowFrom` is unset.
+    - Named accounts do not inherit `channels.slack.accounts.default.allowFrom`.
+
+    Pairing in DMs uses `openclaw pairing approve slack <code>`.
+
+  </Tab>
+
+  <Tab title="Channel policy">
+    `channels.slack.groupPolicy` controls channel handling:
+
+    - `open`
+    - `allowlist`
+    - `disabled`
+
+    Channel allowlist lives under `channels.slack.channels` and should use stable channel IDs.
+
+    Runtime note: if `channels.slack` is completely missing (env-only setup), runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).
+
+    Name/ID resolution:
+
+    - channel allowlist entries and DM allowlist entries are resolved at startup when token access allows
+    - unresolved channel-name entries are kept as configured but ignored for routing by default
+    - inbound authorization and channel routing are ID-first by default; direct username/slug matching requires `channels.slack.dangerouslyAllowNameMatching: true`
+
+  </Tab>
+
+  <Tab title="Mentions and channel users">
+    Channel messages are mention-gated by default.
+
+    Mention sources:
+
+    - explicit app mention (`<@botId>`)
+    - mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
+    - implicit reply-to-bot thread behavior
+
+    Per-channel controls (`channels.slack.channels.<id>`; names only via startup resolution or `dangerouslyAllowNameMatching`):
+
+    - `requireMention`
+    - `users` (allowlist)
+    - `allowBots`
+    - `skills`
+    - `systemPrompt`
+    - `tools`, `toolsBySender`
+    - `toolsBySender` key format: `id:`, `e164:`, `username:`, `name:`, or `"*"` wildcard
+      (legacy unprefixed keys still map to `id:` only)
+
+  </Tab>
+</Tabs>
+
+## Threading, sessions, and reply tags
+
+- DMs route as `direct`; channels as `channel`; MPIMs as `group`.
+- With default `session.dmScope=main`, Slack DMs collapse to agent main session.
+- Channel sessions: `agent:<agentId>:slack:channel:<channelId>`.
+- Thread replies can create thread session suffixes (`:thread:<threadTs>`) when applicable.
+- `channels.slack.thread.historyScope` default is `thread`; `thread.inheritParent` default is `false`.
+- `channels.slack.thread.initialHistoryLimit` controls how many existing thread messages are fetched when a new thread session starts (default `20`; set `0` to disable).
+
+Reply threading controls:
+
+- `channels.slack.replyToMode`: `off|first|all` (default `off`)
+- `channels.slack.replyToModeByChatType`: per `direct|group|channel`
+- legacy fallback for direct chats: `channels.slack.dm.replyToMode`
+
+Manual reply tags are supported:
+
+- `[[reply_to_current]]`
+- `[[reply_to:<id>]]`
+
+Note: `replyToMode="off"` disables **all** reply threading in Slack, including explicit `[[reply_to_*]]` tags. This differs from Telegram, where explicit tags are still honored in `"off"` mode. The difference reflects the platform threading models: Slack threads hide messages from the channel, while Telegram replies remain visible in the main chat flow.
+
+## Ack reactions
+
+`ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message.
+
+Resolution order:
+
+- `channels.slack.accounts.<accountId>.ackReaction`
+- `channels.slack.ackReaction`
+- `messages.ackReaction`
+- agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
+
+Notes:
+
+- Slack expects shortcodes (for example `"eyes"`).
+- Use `""` to disable the reaction for the Slack account or globally.
+
+## Text streaming
+
+`channels.slack.streaming` controls live preview behavior:
+
+- `off`: disable live preview streaming.
+- `partial` (default): replace preview text with the latest partial output.
+- `block`: append chunked preview updates.
+- `progress`: show progress status text while generating, then send final text.
+
+`channels.slack.nativeStreaming` controls Slack native text streaming when `streaming` is `partial` (default: `true`).
+
+- A reply thread must be available for native text streaming to appear. Thread selection still follows `replyToMode`. Without one, the normal draft preview is used.
+- Media and non-text payloads fall back to normal delivery.
+- If streaming fails mid-reply, OpenClaw falls back to normal delivery for remaining payloads.
+
+Use draft preview instead of Slack native text streaming:
+
+```json5
+{
+  channels: {
+    slack: {
+      streaming: "partial",
+      nativeStreaming: false,
+    },
+  },
+}
+```
+
+Legacy keys:
+
+- `channels.slack.streamMode` (`replace | status_final | append`) is auto-migrated to `channels.slack.streaming`.
+- boolean `channels.slack.streaming` is auto-migrated to `channels.slack.nativeStreaming`.
+
+## Typing reaction fallback
+
+`typingReaction` adds a temporary reaction to the inbound Slack message while OpenClaw is processing a reply, then removes it when the run finishes. This is most useful outside of thread replies, which use a default "is typing..." status indicator.
+
+Resolution order:
+
+- `channels.slack.accounts.<accountId>.typingReaction`
+- `channels.slack.typingReaction`
+
+Notes:
+
+- Slack expects shortcodes (for example `"hourglass_flowing_sand"`).
+- The reaction is best-effort and cleanup is attempted automatically after the reply or failure path completes.
+
+## Media, chunking, and delivery
+
+<AccordionGroup>
+  <Accordion title="Inbound attachments">
+    Slack file attachments are downloaded from Slack-hosted private URLs (token-authenticated request flow) and written to the media store when fetch succeeds and size limits permit.
+
+    Runtime inbound size cap defaults to `20MB` unless overridden by `channels.slack.mediaMaxMb`.
+
+  </Accordion>
+
+  <Accordion title="Outbound text and files">
+    - text chunks use `channels.slack.textChunkLimit` (default 4000)
+    - `channels.slack.chunkMode="newline"` enables paragraph-first splitting
+    - file sends use Slack upload APIs and can include thread replies (`thread_ts`)
+    - outbound media cap follows `channels.slack.mediaMaxMb` when configured; otherwise channel sends use MIME-kind defaults from media pipeline
+  </Accordion>
+
+  <Accordion title="Delivery targets">
+    Preferred explicit targets:
+
+    - `user:<id>` for DMs
+    - `channel:<id>` for channels
+
+    Slack DMs are opened via Slack conversation APIs when sending to user targets.
+
+  </Accordion>
+</AccordionGroup>
+
+## Commands and slash behavior
+
+- Native command auto-mode is **off** for Slack (`commands.native: "auto"` does not enable Slack native commands).
+- Enable native Slack command handlers with `channels.slack.commands.native: true` (or global `commands.native: true`).
+- When native commands are enabled, register matching slash commands in Slack (`/<command>` names), with one exception:
+  - register `/agentstatus` for the status command (Slack reserves `/status`)
+- If native commands are not enabled, you can run a single configured slash command via `channels.slack.slashCommand`.
+- Native arg menus now adapt their rendering strategy:
+  - up to 5 options: button blocks
+  - 6-100 options: static select menu
+  - more than 100 options: external select with async option filtering when interactivity options handlers are available
+  - if encoded option values exceed Slack limits, the flow falls back to buttons
+- For long option payloads, Slash command argument menus use a confirm dialog before dispatching a selected value.
+
+Default slash command settings:
+
+- `enabled: false`
+- `name: "openclaw"`
+- `sessionPrefix: "slack:slash"`
+- `ephemeral: true`
+
+Slash sessions use isolated keys:
+
+- `agent:<agentId>:slack:slash:<userId>`
+
+and still route command execution against the target conversation session (`CommandTargetSessionKey`).
+
+## Interactive replies
+
+Slack can render agent-authored interactive reply controls, but this feature is disabled by default.
+
+Enable it globally:
+
+```json5
+{
+  channels: {
+    slack: {
+      capabilities: {
+        interactiveReplies: true,
+      },
+    },
+  },
+}
+```
+
+Or enable it for one Slack account only:
+
+```json5
+{
+  channels: {
+    slack: {
+      accounts: {
+        ops: {
+          capabilities: {
+            interactiveReplies: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+When enabled, agents can emit Slack-only reply directives:
+
+- `[[slack_buttons: Approve:approve, Reject:reject]]`
+- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
+
+These directives compile into Slack Block Kit and route clicks or selections back through the existing Slack interaction event path.
+
+Notes:
+
+- This is Slack-specific UI. Other channels do not translate Slack Block Kit directives into their own button systems.
+- The interactive callback values are OpenClaw-generated opaque tokens, not raw agent-authored values.
+- If generated interactive blocks would exceed Slack Block Kit limits, OpenClaw falls back to the original text reply instead of sending an invalid blocks payload.
+
 ## Exec approvals in Slack
 
-Exec approval prompts can route natively through Slack using interactive buttons and interactions, instead of falling back to the Web UI or terminal. Approver authorization is enforced: only users identified as approvers can approve or deny requests through Slack.
+Slack can act as a native approval client with interactive buttons and interactions, instead of falling back to the Web UI or terminal.
+
+- Exec approvals use `channels.slack.execApprovals.*` for native DM/channel routing.
+- Plugin approvals can still resolve through the same Slack-native button surface when the request already lands in Slack and the approval id kind is `plugin:`.
+- Approver authorization is still enforced: only users identified as approvers can approve or deny requests through Slack.
 
 This uses the same shared approval button surface as other channels. When `interactivity` is enabled in your Slack app settings, approval prompts render as Block Kit buttons directly in the conversation.
+When those buttons are present, they are the primary approval UX; OpenClaw
+should only include a manual `/approve` command when the tool result says chat
+approvals are unavailable or manual approval is the only path.
 
 Config path:
 
@@ -527,11 +567,40 @@ opt into origin-chat delivery:
 }
 ```
 
-Shared `approvals.exec` forwarding is separate. Use it only when approval prompts must also route
-to other chats or explicit out-of-band targets.
+Shared `approvals.exec` forwarding is separate. Use it only when exec approval prompts must also
+route to other chats or explicit out-of-band targets. Shared `approvals.plugin` forwarding is also
+separate; Slack-native buttons can still resolve plugin approvals when those requests already land
+in Slack.
 
 Same-chat `/approve` also works in Slack channels and DMs that already support commands. See [Exec approvals](/tools/exec-approvals) for the full approval forwarding model.
 
+## Events and operational behavior
+
+- Message edits/deletes/thread broadcasts are mapped into system events.
+- Reaction add/remove events are mapped into system events.
+- Member join/leave, channel created/renamed, and pin add/remove events are mapped into system events.
+- `channel_id_changed` can migrate channel config keys when `configWrites` is enabled.
+- Channel topic/purpose metadata is treated as untrusted context and can be injected into routing context.
+- Thread starter and initial thread-history context seeding are filtered by configured sender allowlists when applicable.
+- Block actions and modal interactions emit structured `Slack interaction: ...` system events with rich payload fields:
+  - block actions: selected values, labels, picker values, and `workflow_*` metadata
+  - modal `view_submission` and `view_closed` events with routed channel metadata and form inputs
+
+## Configuration reference pointers
+
+Primary reference:
+
+- [Configuration reference - Slack](/gateway/configuration-reference#slack)
+
+  High-signal Slack fields:
+  - mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
+  - DM access: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
+  - compatibility toggle: `dangerouslyAllowNameMatching` (break-glass; keep off unless needed)
+  - channel access: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
+  - threading/history: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
+  - delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming`
+  - ops/features: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
+
 ## Troubleshooting
 
 <AccordionGroup>
@@ -568,6 +637,12 @@ openclaw pairing list slack
 
   <Accordion title="Socket mode not connecting">
     Validate bot + app tokens and Socket Mode enablement in Slack app settings.
+
+    If `openclaw channels status --probe --json` shows `botTokenStatus` or
+    `appTokenStatus: "configured_unavailable"`, the Slack account is
+    configured but the current runtime could not resolve the SecretRef-backed
+    value.
+
   </Accordion>
 
   <Accordion title="HTTP mode not receiving events">
@@ -578,6 +653,10 @@ openclaw pairing list slack
     - Slack Request URLs (Events + Interactivity + Slash Commands)
     - unique `webhookPath` per HTTP account
 
+    If `signingSecretStatus: "configured_unavailable"` appears in account
+    snapshots, the HTTP account is configured but the current runtime could not
+    resolve the SecretRef-backed signing secret.
+
   </Accordion>
 
   <Accordion title="Native/slash commands not firing">
@@ -591,62 +670,6 @@ openclaw pairing list slack
   </Accordion>
 </AccordionGroup>
 
-## Text streaming
-
-OpenClaw supports Slack native text streaming via the Agents and AI Apps API.
-
-`channels.slack.streaming` controls live preview behavior:
-
-- `off`: disable live preview streaming.
-- `partial` (default): replace preview text with the latest partial output.
-- `block`: append chunked preview updates.
-- `progress`: show progress status text while generating, then send final text.
-
-`channels.slack.nativeStreaming` controls Slack's native streaming API (`chat.startStream` / `chat.appendStream` / `chat.stopStream`) when `streaming` is `partial` (default: `true`).
-
-Disable native Slack streaming (keep draft preview behavior):
-
-```yaml
-channels:
-  slack:
-    streaming: partial
-    nativeStreaming: false
-```
-
-Legacy keys:
-
-- `channels.slack.streamMode` (`replace | status_final | append`) is auto-migrated to `channels.slack.streaming`.
-- boolean `channels.slack.streaming` is auto-migrated to `channels.slack.nativeStreaming`.
-
-### Requirements
-
-1. Enable **Agents and AI Apps** in your Slack app settings.
-2. Ensure the app has the `assistant:write` scope.
-3. A reply thread must be available for that message. Thread selection still follows `replyToMode`.
-
-### Behavior
-
-- First text chunk starts a stream (`chat.startStream`).
-- Later text chunks append to the same stream (`chat.appendStream`).
-- End of reply finalizes stream (`chat.stopStream`).
-- Media and non-text payloads fall back to normal delivery.
-- If streaming fails mid-reply, OpenClaw falls back to normal delivery for remaining payloads.
-
-## Configuration reference pointers
-
-Primary reference:
-
-- [Configuration reference - Slack](/gateway/configuration-reference#slack)
-
-  High-signal Slack fields:
-  - mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
-  - DM access: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
-  - compatibility toggle: `dangerouslyAllowNameMatching` (break-glass; keep off unless needed)
-  - channel access: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
-  - threading/history: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
-  - delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming`
-  - ops/features: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
-
 ## Related
 
 - [Pairing](/channels/pairing)

docs/channels/synology-chat.md

@@ -6,15 +6,19 @@ read_when:
 title: "Synology Chat"
 ---
 
-# Synology Chat (plugin)
+# Synology Chat
 
-Status: supported via plugin as a direct-message channel using Synology Chat webhooks.
+Status: bundled plugin direct-message channel using Synology Chat webhooks.
 The plugin accepts inbound messages from Synology Chat outgoing webhooks and sends replies
 through a Synology Chat incoming webhook.
 
-## Plugin required
+## Bundled plugin
 
-Synology Chat is plugin-based and not part of the default core channel install.
+Synology Chat ships as a bundled plugin in current OpenClaw releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Synology Chat,
+install it manually:
 
 Install from a local checkout:
 
@@ -26,7 +30,9 @@ Details: [Plugins](/tools/plugin)
 
 ## Quick setup
 
-1. Install and enable the Synology Chat plugin.
+1. Ensure the Synology Chat plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually from a source checkout with the command above.
    - `openclaw onboard` now shows Synology Chat in the same channel setup list as `openclaw channels add`.
    - Non-interactive setup: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
 2. In Synology Chat integrations:
@@ -40,6 +46,17 @@ Details: [Plugins](/tools/plugin)
    - Direct: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
 5. Restart gateway and send a DM to the Synology Chat bot.
 
+Webhook auth details:
+
+- OpenClaw accepts the outgoing webhook token from `body.token`, then
+  `?token=...`, then headers.
+- Accepted header forms:
+  - `x-synology-token`
+  - `x-webhook-token`
+  - `x-openclaw-token`
+  - `Authorization: Bearer <token>`
+- Empty or missing tokens fail closed.
+
 Minimal config:
 
 ```json5
@@ -137,10 +154,28 @@ but duplicate exact paths are still rejected fail-closed. Prefer explicit per-ac
 - Keep `token` secret and rotate it if leaked.
 - Keep `allowInsecureSsl: false` unless you explicitly trust a self-signed local NAS cert.
 - Inbound webhook requests are token-verified and rate-limited per sender.
+- Invalid token checks use constant-time secret comparison and fail closed.
 - Prefer `dmPolicy: "allowlist"` for production.
 - Keep `dangerouslyAllowNameMatching` off unless you explicitly need legacy username-based reply delivery.
 - Keep `dangerouslyAllowInheritedWebhookPath` off unless you explicitly accept shared-path routing risk in a multi-account setup.
 
+## Troubleshooting
+
+- `Missing required fields (token, user_id, text)`:
+  - the outgoing webhook payload is missing one of the required fields
+  - if Synology sends the token in headers, make sure the gateway/proxy preserves those headers
+- `Invalid token`:
+  - the outgoing webhook secret does not match `channels.synology-chat.token`
+  - the request is hitting the wrong account/webhook path
+  - a reverse proxy stripped the token header before the request reached OpenClaw
+- `Rate limit exceeded`:
+  - too many invalid token attempts from the same source can temporarily lock that source out
+  - authenticated senders also have a separate per-user message rate limit
+- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`:
+  - `dmPolicy="allowlist"` is enabled but no users are configured
+- `User not authorized`:
+  - the sender's numeric `user_id` is not in `allowedUserIds`
+
 ## Related
 
 - [Channels Overview](/channels) — all supported channels

docs/channels/telegram.md

@@ -358,6 +358,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
        - `/pair approve` when there is only one pending request
        - `/pair approve latest` for most recent
 
+    The setup code carries a short-lived bootstrap token. Built-in bootstrap handoff keeps the primary node token at `scopes: []`; any handed-off operator token stays bounded to `operator.approvals`, `operator.read`, `operator.talk.secrets`, and `operator.write`. Bootstrap scope checks are role-prefixed, so that operator allowlist only satisfies operator requests; non-operator roles still need scopes under their own role prefix.
+
     If a device retries with changed auth details (for example role/scopes/public key), the previous pending request is superseded and the new request uses a different `requestId`. Re-run `/pair pending` before approving.
 
     More details: [Pairing](/channels/pairing#pair-via-telegram-recommended-for-ios).
@@ -821,6 +823,9 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
     Approvers must be numeric Telegram user IDs. Telegram auto-enables native exec approvals when `enabled` is unset or `"auto"` and at least one approver can be resolved, either from `execApprovals.approvers` or from the account's numeric owner config (`allowFrom` and direct-message `defaultTo`). Set `enabled: false` to disable Telegram as a native approval client explicitly. Approval requests otherwise fall back to other configured approval routes or the exec approval fallback policy.
 
     Telegram also renders the shared approval buttons used by other chat channels. The native Telegram adapter mainly adds approver DM routing, channel/topic fanout, and typing hints before delivery.
+    When those buttons are present, they are the primary approval UX; OpenClaw
+    should only include a manual `/approve` command when the tool result says
+    chat approvals are unavailable or manual approval is the only path.
 
     Delivery rules:
 
@@ -830,6 +835,16 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
 
     Only resolved approvers can approve or deny. Non-approvers cannot use `/approve` and cannot use Telegram approval buttons.
 
+    Approval resolution behavior:
+
+    - IDs prefixed with `plugin:` always resolve through plugin approvals.
+    - Other approval IDs try `exec.approval.resolve` first.
+    - If Telegram is also authorized for plugin approvals and the gateway says
+      the exec approval is unknown/expired, Telegram retries once through
+      `plugin.approval.resolve`.
+    - Real exec approval denials/errors do not silently fall through to plugin
+      approval resolution.
+
     Channel delivery shows the command text in the chat, so only enable `channel` or `both` in trusted groups/topics. When the prompt lands in a forum topic, OpenClaw preserves the topic for both the approval prompt and the post-approval follow-up. Exec approvals expire after 30 minutes by default.
 
     Inline approval buttons also depend on `channels.telegram.capabilities.inlineButtons` allowing the target surface (`dm`, `group`, or `all`).

docs/channels/tlon.md

@@ -5,18 +5,22 @@ read_when:
 title: "Tlon"
 ---
 
-# Tlon (plugin)
+# Tlon
 
 Tlon is a decentralized messenger built on Urbit. OpenClaw connects to your Urbit ship and can
 respond to DMs and group chat messages. Group replies require an @ mention by default and can
 be further restricted via allowlists.
 
-Status: supported via plugin. DMs, group mentions, thread replies, rich text formatting, and
+Status: bundled plugin. DMs, group mentions, thread replies, rich text formatting, and
 image uploads are supported. Reactions and polls are not yet supported.
 
-## Plugin required
+## Bundled plugin
 
-Tlon ships as a plugin and is not bundled with the core install.
+Tlon ships as a bundled plugin in current OpenClaw releases, so normal packaged
+builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Tlon, install it
+manually:
 
 Install via CLI (npm registry):
 
@@ -34,7 +38,9 @@ Details: [Plugins](/tools/plugin)
 
 ## Setup
 
-1. Install the Tlon plugin.
+1. Ensure the Tlon plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
 2. Gather your ship URL and login code.
 3. Configure `channels.tlon`.
 4. Restart the gateway.

docs/channels/troubleshooting.md

@@ -26,7 +26,7 @@ Healthy baseline:
 
 - `Runtime: running`
 - `RPC probe: ok`
-- Channel probe shows connected/ready
+- Channel probe shows transport connected and, where supported, `works` or `audit ok`
 
 ## WhatsApp
 
@@ -70,11 +70,11 @@ Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#trou
 
 ### Slack failure signatures
 
-| Symptom                                | Fastest check                             | Fix                                               |
-| -------------------------------------- | ----------------------------------------- | ------------------------------------------------- |
-| Socket mode connected but no responses | `openclaw channels status --probe`        | Verify app token + bot token and required scopes. |
-| DMs blocked                            | `openclaw pairing list slack`             | Approve pairing or relax DM policy.               |
-| Channel message ignored                | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`.     |
+| Symptom                                | Fastest check                             | Fix                                                                                                                                                  |
+| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Socket mode connected but no responses | `openclaw channels status --probe`        | Verify app token + bot token and required scopes; watch for `botTokenStatus` / `appTokenStatus = configured_unavailable` on SecretRef-backed setups. |
+| DMs blocked                            | `openclaw pairing list slack`             | Approve pairing or relax DM policy.                                                                                                                  |
+| Channel message ignored                | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`.                                                                                                        |
 
 Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
 

docs/channels/twitch.md

@@ -5,13 +5,17 @@ read_when:
 title: "Twitch"
 ---
 
-# Twitch (plugin)
+# Twitch
 
 Twitch chat support via IRC connection. OpenClaw connects as a Twitch user (bot account) to receive and send messages in channels.
 
-## Plugin required
+## Bundled plugin
 
-Twitch ships as a plugin and is not bundled with the core install.
+Twitch ships as a bundled plugin in current OpenClaw releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Twitch, install
+it manually:
 
 Install via CLI (npm registry):
 
@@ -29,17 +33,20 @@ Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 
-1. Create a dedicated Twitch account for the bot (or use an existing account).
-2. Generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/)
+1. Ensure the Twitch plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
+2. Create a dedicated Twitch account for the bot (or use an existing account).
+3. Generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/)
    - Select **Bot Token**
    - Verify scopes `chat:read` and `chat:write` are selected
    - Copy the **Client ID** and **Access Token**
-3. Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
-4. Configure the token:
+4. Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
+5. Configure the token:
    - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (default account only)
    - Or config: `channels.twitch.accessToken`
    - If both are set, config takes precedence (env fallback is default-account only).
-5. Start the gateway.
+6. Start the gateway.
 
 **⚠️ Important:** Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot. `requireMention` defaults to `true`.
 

docs/channels/zalo.md

@@ -9,20 +9,23 @@ title: "Zalo"
 
 Status: experimental. DMs are supported. The [Capabilities](#capabilities) section below reflects current Marketplace-bot behavior.
 
-## Plugin required
+## Bundled plugin
 
-Zalo ships as a plugin and is not bundled with the core install.
+Zalo ships as a bundled plugin in current OpenClaw releases, so normal packaged
+builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Zalo, install it
+manually:
 
 - Install via CLI: `openclaw plugins install @openclaw/zalo`
-- Or select **Zalo** during setup and confirm the install prompt
+- Or from a source checkout: `openclaw plugins install ./path/to/local/zalo-plugin`
 - Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 
-1. Install the Zalo plugin:
-   - From a source checkout: `openclaw plugins install ./path/to/local/zalo-plugin`
-   - From npm (if published): `openclaw plugins install @openclaw/zalo`
-   - Or pick **Zalo** in setup and confirm the install prompt
+1. Ensure the Zalo plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
 2. Set the token:
    - Env: `ZALO_BOT_TOKEN=...`
    - Or config: `channels.zalo.accounts.default.botToken: "..."`.

docs/channels/zalouser.md

@@ -12,9 +12,13 @@ Status: experimental. This integration automates a **personal Zalo account** via
 
 > **Warning:** This is an unofficial integration and may result in account suspension/ban. Use at your own risk.
 
-## Plugin required
+## Bundled plugin
 
-Zalo Personal ships as a plugin and is not bundled with the core install.
+Zalo Personal ships as a bundled plugin in current OpenClaw releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Zalo Personal,
+install it manually:
 
 - Install via CLI: `openclaw plugins install @openclaw/zalouser`
 - Or from a source checkout: `openclaw plugins install ./path/to/local/zalouser-plugin`
@@ -24,7 +28,9 @@ No external `zca`/`openzca` CLI binary is required.
 
 ## Quick setup (beginner)
 
-1. Install the plugin (see above).
+1. Ensure the Zalo Personal plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
 2. Login (QR, on the Gateway machine):
    - `openclaw channels login --channel zalouser`
    - Scan the QR code with the Zalo mobile app.

docs/ci.md

@@ -12,46 +12,55 @@ The CI runs on every push to `main` and every pull request. It uses smart scopin
 
 ## Job Overview
 
-| Job               | Purpose                                                                   | When it runs                                     |
-| ----------------- | ------------------------------------------------------------------------- | ------------------------------------------------ |
-| `preflight`       | Docs scope, change scope, key scan, workflow audit, prod dependency audit | Always; node-based audit only on non-doc changes |
-| `docs-scope`      | Detect docs-only changes                                                  | Always                                           |
-| `changed-scope`   | Detect which areas changed (node/macos/android/windows)                   | Non-doc changes                                  |
-| `check`           | TypeScript types, lint, format                                            | Non-docs, node changes                           |
-| `check-docs`      | Markdown lint + broken link check                                         | Docs changed                                     |
-| `secrets`         | Detect leaked secrets                                                     | Always                                           |
-| `build-artifacts` | Build dist once, share with `release-check`                               | Pushes to `main`, node changes                   |
-| `release-check`   | Validate npm pack contents                                                | Pushes to `main` after build                     |
-| `checks`          | Node tests + protocol check on PRs; Bun compat on push                    | Non-docs, node changes                           |
-| `compat-node22`   | Minimum supported Node runtime compatibility                              | Pushes to `main`, node changes                   |
-| `checks-windows`  | Windows-specific tests                                                    | Non-docs, windows-relevant changes               |
-| `macos`           | Swift lint/build/test + TS tests                                          | PRs with macos changes                           |
-| `android`         | Gradle build + tests                                                      | Non-docs, android changes                        |
+| Job                      | Purpose                                                                                  | When it runs                        |
+| ------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
+| `preflight`              | Detect docs-only changes, changed scopes, changed extensions, and build the CI manifest  | Always on non-draft pushes and PRs  |
+| `security-fast`          | Private key detection, workflow audit via `zizmor`, production dependency audit          | Always on non-draft pushes and PRs  |
+| `build-artifacts`        | Build `dist/` and the Control UI once, upload reusable artifacts for downstream jobs     | Node-relevant changes               |
+| `checks-fast-core`       | Fast Linux correctness lanes such as bundled/plugin-contract/protocol checks             | Node-relevant changes               |
+| `checks-fast-extensions` | Aggregate the extension shard lanes after `checks-fast-extensions-shard` completes       | Node-relevant changes               |
+| `extension-fast`         | Focused tests for only the changed bundled plugins                                       | When extension changes are detected |
+| `check`                  | Main local gate in CI: `pnpm check` plus `pnpm build:strict-smoke`                       | Node-relevant changes               |
+| `check-additional`       | Architecture and boundary guards plus the gateway watch regression harness               | Node-relevant changes               |
+| `build-smoke`            | Built-CLI smoke tests and startup-memory smoke                                           | Node-relevant changes               |
+| `checks`                 | Heavier Linux Node lanes: full tests, channel tests, and push-only Node 22 compatibility | Node-relevant changes               |
+| `check-docs`             | Docs formatting, lint, and broken-link checks                                            | Docs changed                        |
+| `skills-python`          | Ruff + pytest for Python-backed skills                                                   | Python-skill-relevant changes       |
+| `checks-windows`         | Windows-specific test lanes                                                              | Windows-relevant changes            |
+| `macos-node`             | macOS TypeScript test lane using the shared built artifacts                              | macOS-relevant changes              |
+| `macos-swift`            | Swift lint, build, and tests for the macOS app                                           | macOS-relevant changes              |
+| `android`                | Android build and test matrix                                                            | Android-relevant changes            |
 
 ## Fail-Fast Order
 
 Jobs are ordered so cheap checks fail before expensive ones run:
 
-1. `docs-scope` + `changed-scope` + `check` + `secrets` (parallel, cheap gates first)
-2. PRs: `checks` (Linux Node test split into 2 shards), `checks-windows`, `macos`, `android`
-3. Pushes to `main`: `build-artifacts` + `release-check` + Bun compat + `compat-node22`
+1. `preflight` decides which lanes exist at all. The `docs-scope` and `changed-scope` logic are steps inside this job, not standalone jobs.
+2. `security-fast`, `check`, `check-additional`, `check-docs`, and `skills-python` fail quickly without waiting on the heavier artifact and platform matrix jobs.
+3. `build-artifacts` overlaps with the fast Linux lanes so downstream consumers can start as soon as the shared build is ready.
+4. Heavier platform and runtime lanes fan out after that: `checks-fast-core`, `checks-fast-extensions`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, and `android`.
 
 Scope logic lives in `scripts/ci-changed-scope.mjs` and is covered by unit tests in `src/scripts/ci-changed-scope.test.ts`.
-The same shared scope module also drives the separate `install-smoke` workflow through a narrower `changed-smoke` gate, so Docker/install smoke only runs for install, packaging, and container-relevant changes.
+The separate `install-smoke` workflow reuses the same scope script through its own `preflight` job. It computes `run_install_smoke` from the narrower changed-smoke signal, so Docker/install smoke only runs for install, packaging, and container-relevant changes.
+
+On pushes, the `checks` matrix adds the push-only `compat-node22` lane. On pull requests, that lane is skipped and the matrix stays focused on the normal test/channel lanes.
 
 ## Runners
 
-| Runner                           | Jobs                                       |
-| -------------------------------- | ------------------------------------------ |
-| `blacksmith-16vcpu-ubuntu-2404`  | Most Linux jobs, including scope detection |
-| `blacksmith-32vcpu-windows-2025` | `checks-windows`                           |
-| `macos-latest`                   | `macos`, `ios`                             |
+| Runner                           | Jobs                                                                                                 |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `blacksmith-16vcpu-ubuntu-2404`  | `preflight`, `security-fast`, `build-artifacts`, Linux checks, docs checks, Python skills, `android` |
+| `blacksmith-32vcpu-windows-2025` | `checks-windows`                                                                                     |
+| `macos-latest`                   | `macos-node`, `macos-swift`                                                                          |
 
 ## Local Equivalents
 
 ```bash
 pnpm check          # types + lint + format
+pnpm build:strict-smoke
+pnpm test:gateway:watch-regression
 pnpm test           # vitest tests
+pnpm test:channels
 pnpm check:docs     # docs format + lint + broken links
-pnpm release:check  # validate npm pack
+pnpm build          # build dist when CI artifact/build-smoke lanes matter
 ```

docs/cli/backup.md

@@ -8,7 +8,7 @@ title: "backup"
 
 # `openclaw backup`
 
-Create a local backup archive for OpenClaw state, config, credentials, sessions, and optionally workspaces.
+Create a local backup archive for OpenClaw state, config, auth profiles, channel/provider credentials, sessions, and optionally workspaces.
 
 ```bash
 openclaw backup create
@@ -37,12 +37,19 @@ openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz
 
 - The state directory returned by OpenClaw's local state resolver, usually `~/.openclaw`
 - The active config file path
-- The OAuth / credentials directory
+- The resolved `credentials/` directory when it exists outside the state directory
 - Workspace directories discovered from the current config, unless you pass `--no-include-workspace`
 
-If you use `--only-config`, OpenClaw skips state, credentials, and workspace discovery and archives only the active config file path.
+Model auth profiles are already part of the state directory under
+`agents/<agentId>/agent/auth-profiles.json`, so they are normally covered by the
+state backup entry.
 
-OpenClaw canonicalizes paths before building the archive. If config, credentials, or a workspace already live inside the state directory, they are not duplicated as separate top-level backup sources. Missing paths are skipped.
+If you use `--only-config`, OpenClaw skips state, credentials-directory, and workspace discovery and archives only the active config file path.
+
+OpenClaw canonicalizes paths before building the archive. If config, the
+credentials directory, or a workspace already live inside the state directory,
+they are not duplicated as separate top-level backup sources. Missing paths are
+skipped.
 
 The archive payload stores file contents from those source trees, and the embedded `manifest.json` records the resolved absolute source paths plus the archive layout used for each asset.
 
@@ -56,7 +63,8 @@ If you still want a partial backup in that situation, rerun:
 openclaw backup create --no-include-workspace
 ```
 
-That keeps state, config, and credentials in scope while skipping workspace discovery entirely.
+That keeps state, config, and the external credentials directory in scope while
+skipping workspace discovery entirely.
 
 If you only need a copy of the config file itself, `--only-config` also works when the config is malformed because it does not rely on parsing the config for workspace discovery.
 

docs/cli/browser.md

@@ -42,6 +42,14 @@ openclaw browser stop
 openclaw browser --browser-profile openclaw reset-profile
 ```
 
+Notes:
+
+- 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.
+- For local managed profiles, `openclaw browser stop` stops the spawned browser
+  process.
+
 ## If the command is missing
 
 If `openclaw browser` is an unknown command, check `plugins.allow` in
@@ -109,8 +117,17 @@ Screenshot:
 
 ```bash
 openclaw browser screenshot
+openclaw browser screenshot --full-page
+openclaw browser screenshot --ref e12
 ```
 
+Notes:
+
+- `--full-page` is for page captures only; it cannot be combined with `--ref`
+  or `--element`.
+- `existing-session` / `user` profiles support page screenshots and `--ref`
+  screenshots from snapshot output, but not CSS `--element` screenshots.
+
 Navigate/click/type (ref-based UI automation):
 
 ```bash
@@ -190,6 +207,23 @@ openclaw browser --browser-profile chrome-live tabs
 
 This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead.
 
+Current existing-session limits:
+
+- snapshot-driven actions use refs, not CSS selectors
+- `click` is left-click only
+- `type` does not support `slowly=true`
+- `press` does not support `delayMs`
+- `hover`, `scrollintoview`, `drag`, `select`, `fill`, and `evaluate` reject
+  per-call timeout overrides
+- `select` supports one value only
+- `wait --load networkidle` is not supported
+- file uploads require `--ref` / `--input-ref`, do not support CSS
+  `--element`, and currently support one file at a time
+- dialog hooks do not support `--timeout`
+- screenshots support page captures and `--ref`, but not CSS `--element`
+- `responsebody`, download interception, PDF export, and batch actions still
+  require a managed browser or raw CDP profile
+
 ## Remote browser control (node host proxy)
 
 If the Gateway runs on a different machine than the browser, run a **node host** on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required).

docs/cli/channels.md

@@ -33,6 +33,12 @@ openclaw channels logs --channel all
 - `channels resolve`: `<entries...>`, `--channel <name>`, `--account <id>`, `--kind <auto|user|group>`, `--json`
 - `channels logs`: `--channel <name|all>`, `--lines <n>`, `--json`
 
+`channels status --probe` is the live path: on a reachable gateway it runs per-account
+`probeAccount` and optional `auditAccount` checks, so output can include transport
+state plus probe results such as `works`, `probe failed`, `audit ok`, or `audit failed`.
+If the gateway is unreachable, `channels status` falls back to config-only summaries
+instead of live probe output.
+
 ## Add / remove accounts
 
 ```bash
@@ -63,7 +69,7 @@ If you confirm bind now, the wizard asks which agent should own each configured
 
 You can also manage the same routing rules later with `openclaw agents bindings`, `openclaw agents bind`, and `openclaw agents unbind` (see [agents](/cli/agents)).
 
-When you add a non-default account to a channel that is still using single-account top-level settings (no `channels.<channel>.accounts` entries yet), OpenClaw moves account-scoped single-account top-level values into `channels.<channel>.accounts.default`, then writes the new account. This preserves the original account behavior while moving to the multi-account shape.
+When you add a non-default account to a channel that is still using single-account top-level settings, OpenClaw promotes account-scoped top-level values into the channel's account map before writing the new account. Most channels land those values in `channels.<channel>.accounts.default`, but bundled channels can preserve an existing matching promoted account instead. Matrix is the current example: if one named account already exists, or `defaultAccount` points at an existing named account, promotion preserves that account instead of creating a new `accounts.default`.
 
 Routing behavior stays consistent:
 
@@ -71,7 +77,7 @@ Routing behavior stays consistent:
 - `channels add` does not auto-create or rewrite bindings in non-interactive mode.
 - Interactive setup can optionally add account-scoped bindings.
 
-If your config was already in a mixed state (named accounts present, missing `default`, and top-level single-account values still set), run `openclaw doctor --fix` to move account-scoped values into `accounts.default`.
+If your config was already in a mixed state (named accounts present and top-level single-account values still set), run `openclaw doctor --fix` to move account-scoped values into the promoted account chosen for that channel. Most channels promote into `accounts.default`; Matrix can preserve an existing named/default target instead.
 
 ## Login / logout (interactive)
 
@@ -89,7 +95,7 @@ Notes:
 
 - Run `openclaw status --deep` for a broad probe.
 - Use `openclaw doctor` for guided fixes.
-- `openclaw channels list` prints `Claude: HTTP 403 ... user:profile` → usage snapshot needs the `user:profile` scope. Use `--no-usage`, or provide a claude.ai session key (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), or re-auth via Claude Code CLI.
+- `openclaw channels list` prints `Claude: HTTP 403 ... user:profile` → usage snapshot needs the `user:profile` scope. Use `--no-usage`, or provide a claude.ai session key (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), or re-auth via Claude CLI.
 - `openclaw channels status` falls back to config-only summaries when the gateway is unreachable. If a supported channel credential is configured via SecretRef but unavailable in the current command path, it reports that account as configured with degraded notes instead of showing it as not configured.
 
 ## Capabilities probe

docs/cli/config.md

@@ -48,7 +48,23 @@ openclaw config validate --json
 
 ### `config schema`
 
-Print the generated JSON schema for `openclaw.json` to stdout as plain text.
+Print the generated JSON schema for `openclaw.json` to stdout as JSON.
+
+What it includes:
+
+- The current root config schema, plus a root `$schema` string field for editor tooling
+- Field `title` and `description` docs metadata used by the Control UI
+- Nested object, wildcard (`*`), and array-item (`[]`) nodes inherit the same `title` / `description` metadata when matching field documentation exists
+- `anyOf` / `oneOf` / `allOf` branches inherit the same docs metadata too when matching field documentation exists
+- Best-effort live plugin + channel schema metadata when runtime manifests can be loaded
+- A clean fallback schema even when the current config is invalid
+
+Related runtime RPC:
+
+- `config.schema.lookup` returns one normalized config path with a shallow
+  schema node (`title`, `description`, `type`, `enum`, `const`, common bounds),
+  matched UI hint metadata, and immediate child summaries. Use it for
+  path-scoped drill-down in Control UI or custom clients.
 
 ```bash
 openclaw config schema

docs/cli/configure.md

@@ -12,6 +12,13 @@ Interactive prompt to set up credentials, devices, and agent defaults.
 Note: The **Model** section now includes a multi-select for the
 `agents.defaults.models` allowlist (what shows up in `/model` and the model picker).
 
+When configure starts from a provider auth choice, the default-model and
+allowlist pickers prefer that provider automatically. For paired providers such
+as Volcengine/BytePlus, the same preference also matches their coding-plan
+variants (`volcengine-plan/*`, `byteplus-plan/*`). If the preferred-provider
+filter would produce an empty list, configure falls back to the unfiltered
+catalog instead of showing a blank picker.
+
 Tip: `openclaw config` without a subcommand opens the same wizard. Use
 `openclaw config get|set|unset` for non-interactive edits.
 

docs/cli/cron.md

@@ -19,6 +19,10 @@ Tip: run `openclaw cron --help` for the full command surface.
 Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
 output internal. `--deliver` remains as a deprecated alias for `--announce`.
 
+Note: cron-owned isolated runs expect a plain-text summary and the runner owns
+the final send path. `--no-deliver` keeps the run internal; it does not hand
+delivery back to the agent's message tool.
+
 Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
 
 Note: `--session` supports `main`, `isolated`, `current`, and `session:<id>`.
@@ -35,6 +39,38 @@ Note: `openclaw cron run` now returns as soon as the manual run is queued for ex
 Note: `openclaw cron run <job-id>` force-runs by default. Use `--due` to keep the
 older "only run if due" behavior.
 
+Note: isolated cron turns suppress stale acknowledgement-only replies. If the
+first result is just an interim status update and no descendant subagent run is
+responsible for the eventual answer, cron re-prompts once for the real result
+before delivery.
+
+Note: if an isolated cron run returns only the silent token (`NO_REPLY` /
+`no_reply`), cron suppresses direct outbound delivery and the fallback queued
+summary path as well, so nothing is posted back to chat.
+
+Note: `cron add|edit --model ...` uses that selected allowed model for the job.
+If the model is not allowed, cron warns 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.
+
+Note: isolated cron model precedence is Gmail-hook override first, then per-job
+`--model`, then any stored cron-session model override, then the normal
+agent/default selection.
+
+Note: isolated cron fast mode follows the resolved live model selection. Model
+config `params.fastMode` applies by default, but a stored session `fastMode`
+override still wins over config.
+
+Note: if an isolated run throws `LiveSessionModelSwitchError`, cron persists the
+switched provider/model (and switched auth profile override when present) before
+retrying. The outer retry loop is bounded to 2 switch retries after the initial
+attempt, then aborts instead of looping forever.
+
+Note: failure notifications use `delivery.failureDestination` first, then
+global `cron.failureDestination`, and finally fall back to the job's primary
+announce target when no explicit failure destination is configured.
+
 Note: retention/pruning is controlled in config:
 
 - `cron.sessionRetention` (default `24h`) prunes completed isolated run sessions.
@@ -86,6 +122,14 @@ openclaw cron add \
 
 `--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.
 
+Delivery ownership note:
+
+- Cron-owned isolated jobs always route final user-visible delivery through the
+  cron runner (`announce`, `webhook`, or internal-only `none`).
+- If the task mentions messaging some external recipient, the agent should
+  describe the intended destination in its result instead of trying to send it
+  directly.
+
 ## Common admin commands
 
 Manual run:
@@ -113,3 +157,11 @@ openclaw cron edit <job-id> --best-effort-deliver
 openclaw cron edit <job-id> --no-best-effort-deliver
 openclaw cron edit <job-id> --no-deliver
 ```
+
+Failure-delivery note:
+
+- `delivery.failureDestination` is supported for isolated jobs.
+- Main-session jobs may only use `delivery.failureDestination` when primary
+  delivery mode is `webhook`.
+- If you do not set any failure destination and the job already announces to a
+  channel, failure notifications reuse that same announce target.

docs/cli/daemon.md

@@ -43,12 +43,14 @@ Notes:
 - `status` resolves configured auth SecretRefs for probe auth when possible.
 - If a required auth SecretRef is unresolved in this command path, `daemon status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
 - If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
+- `status --deep` adds a best-effort system-level service scan. When it finds other gateway-like services, human output prints cleanup hints and warns that one gateway per machine is still the normal recommendation.
 - On Linux systemd installs, `status` token-drift checks include both `Environment=` and `EnvironmentFile=` unit sources.
 - Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
 - If token auth is not effectively active (explicit `gateway.auth.mode` of `password`/`none`/`trusted-proxy`, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.
 - When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `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.
 - If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
+- If you intentionally run multiple gateways on one host, isolate ports, config/state, and workspaces; see [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
 
 ## Prefer
 

docs/cli/devices.md

@@ -28,6 +28,10 @@ be reviewed before you approve.
 
 Remove one paired device entry.
 
+When you are authenticated with a paired device token, non-admin callers can
+remove only **their own** device entry. Removing some other device requires
+`operator.admin`.
+
 ```
 openclaw devices remove <deviceId>
 openclaw devices remove <deviceId> --json
@@ -70,6 +74,15 @@ openclaw devices reject <requestId>
 ### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
 
 Rotate a device token for a specific role (optionally updating scopes).
+The target role must already exist in that device's approved pairing contract;
+rotation cannot mint a new unapproved role.
+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.
 
 ```
 openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
@@ -81,6 +94,9 @@ Returns the new token payload as JSON.
 
 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`.
+
 ```
 openclaw devices revoke --device <deviceId> --role node
 ```
@@ -102,6 +118,12 @@ Pass `--token` or `--password` explicitly. Missing explicit credentials is an er
 
 - Token rotation returns a new token (sensitive). Treat it like a secret.
 - These commands require `operator.pairing` (or `operator.admin`) scope.
+- 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.
+- For paired-device token sessions, cross-device management is admin-only:
+  `remove`, `rotate`, and `revoke` are self-only unless the caller has
+  `operator.admin`.
 - `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` picks the newest pending request automatically when you omit `requestId` or pass `--latest`.
@@ -138,6 +160,11 @@ openclaw devices approve <requestId>
 
 5. Retry client connection with the current shared token/password.
 
+Notes:
+
+- Normal reconnect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
+- Trusted `AUTH_TOKEN_MISMATCH` recovery can temporarily send both the shared token and the stored device token together for the one bounded retry.
+
 Related:
 
 - [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)

docs/cli/doctor.md

@@ -42,6 +42,8 @@ Notes:
 - `--fix` (alias for `--repair`) writes a backup to `~/.openclaw/openclaw.json.bak` and drops unknown config keys, listing each removal.
 - State integrity checks now detect orphan transcript files in the sessions directory and can archive them as `.deleted.<timestamp>` to reclaim space safely.
 - Doctor also scans `~/.openclaw/cron/jobs.json` (or `cron.store`) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.
+- Doctor auto-migrates legacy flat Talk config (`talk.voiceId`, `talk.modelId`, and friends) into `talk.provider` + `talk.providers.<provider>`.
+- Repeat `doctor --fix` runs no longer report/apply Talk normalization when the only difference is object key order.
 - Doctor includes a memory-search readiness check and can recommend `openclaw configure --section model` when embedding credentials are missing.
 - If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (`install Docker` or `openclaw config set agents.defaults.sandbox.mode off`).
 - If `gateway.auth.token`/`gateway.auth.password` are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials.

docs/cli/gateway.md

@@ -3,7 +3,7 @@ summary: "OpenClaw Gateway CLI (`openclaw gateway`) — run, query, and discover
 read_when:
   - Running the Gateway from the CLI (dev or servers)
   - Debugging Gateway auth, bind modes, and connectivity
-  - Discovering gateways via Bonjour (LAN + tailnet)
+  - Discovering gateways via Bonjour (local + wide-area DNS-SD)
 title: "gateway"
 ---
 
@@ -117,7 +117,7 @@ openclaw gateway status --require-rpc
 
 Options:
 
-- `--url <url>`: override the probe URL.
+- `--url <url>`: add an explicit probe target. Configured remote + localhost are still probed.
 - `--token <token>`: token auth for the probe.
 - `--password <password>`: password auth for the probe.
 - `--timeout <ms>`: probe timeout (default `10000`).
@@ -132,6 +132,7 @@ Notes:
 - If a required auth SecretRef is unresolved in this command path, `gateway status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
 - If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
 - Use `--require-rpc` in scripts and automation when a listening service is not enough and you need the Gateway RPC itself to be healthy.
+- `--deep` adds a best-effort scan for extra launchd/systemd/schtasks installs. When multiple gateway-like services are detected, human output prints cleanup hints and warns that most setups should run one gateway per machine.
 - Human output includes the resolved file log path plus the CLI-vs-service config paths/validity snapshot to help diagnose profile or state-dir drift.
 - On Linux systemd installs, service auth drift checks read both `Environment=` and `EnvironmentFile=` values from the unit (including `%h`, quoted paths, multiple files, and optional `-` files).
 - Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
@@ -144,6 +145,13 @@ Notes:
 - your configured remote gateway (if set), and
 - localhost (loopback) **even if remote is configured**.
 
+If you pass `--url`, that explicit target is added ahead of both. Human output labels the
+targets as:
+
+- `URL (explicit)`
+- `Remote (configured)` or `Remote (configured, inactive)`
+- `Local loopback`
+
 If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.
 
 ```bash
@@ -163,11 +171,22 @@ JSON notes (`--json`):
 - Top level:
   - `ok`: at least one target is reachable.
   - `degraded`: at least one target had scope-limited detail RPC.
+  - `primaryTargetId`: best target to treat as the active winner in this order: explicit URL, SSH tunnel, configured remote, then local loopback.
+  - `warnings[]`: best-effort warning records with `code`, `message`, and optional `targetIds`.
+  - `network`: local loopback/tailnet URL hints derived from current config and host networking.
+  - `discovery.timeoutMs` and `discovery.count`: the actual discovery budget/result count used for this probe pass.
 - Per target (`targets[].connect`):
   - `ok`: reachability after connect + degraded classification.
   - `rpcOk`: full detail RPC success.
   - `scopeLimited`: detail RPC failed due to missing operator scope.
 
+Common warning codes:
+
+- `ssh_tunnel_failed`: SSH tunnel setup failed; the command fell back to direct probes.
+- `multiple_gateways`: more than one target was reachable; this is unusual unless you intentionally run isolated profiles, such as a rescue bot.
+- `auth_secretref_unresolved`: a configured auth SecretRef could not be resolved for a failed target.
+- `probe_scope_limited`: WebSocket connect succeeded, but detail RPC was limited by missing `operator.read`.
+
 #### Remote over SSH (Mac app parity)
 
 The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.
@@ -182,7 +201,9 @@ Options:
 
 - `--ssh <target>`: `user@host` or `user@host:port` (port defaults to `22`).
 - `--ssh-identity <path>`: identity file.
-- `--ssh-auto`: pick the first discovered gateway host as SSH target (LAN/WAB only).
+- `--ssh-auto`: pick the first discovered gateway host as SSH target from the resolved
+  discovery endpoint (`local.` plus the configured wide-area domain, if any). TXT-only
+  hints are ignored.
 
 Config (optional, used as defaults):
 
@@ -253,10 +274,10 @@ Wide-Area discovery records include (TXT):
 - `role` (gateway role hint)
 - `transport` (transport hint, e.g. `gateway`)
 - `gatewayPort` (WebSocket port, usually `18789`)
-- `sshPort` (SSH port; defaults to `22` if not present)
+- `sshPort` (optional; clients default SSH targets to `22` when it is absent)
 - `tailnetDns` (MagicDNS hostname, when available)
 - `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint)
-- `cliPath` (optional hint for remote installs)
+- `cliPath` (remote-install hint written to the wide-area zone)
 
 ### `gateway discover`
 
@@ -275,3 +296,12 @@ Examples:
 openclaw gateway discover --timeout 4000
 openclaw gateway discover --json | jq '.beacons[].wsUrl'
 ```
+
+Notes:
+
+- The CLI scans `local.` plus the configured wide-area domain when one is enabled.
+- `wsUrl` in JSON output is derived from the resolved service endpoint, not from TXT-only
+  hints such as `lanHost` or `tailnetDns`.
+- On `local.` mDNS, `sshPort` and `cliPath` are only broadcast when
+  `discovery.mdns.mode` is `full`. Wide-area DNS-SD still writes `cliPath`; `sshPort`
+  stays optional there too.

docs/cli/health.md

@@ -1,5 +1,5 @@
 ---
-summary: "CLI reference for `openclaw health` (gateway health endpoint via RPC)"
+summary: "CLI reference for `openclaw health` (gateway health snapshot via RPC)"
 read_when:
   - You want to quickly check the running Gateway’s health
 title: "health"
@@ -28,5 +28,9 @@ openclaw health --debug
 
 Notes:
 
-- `--verbose` runs live probes and prints per-account timings when multiple accounts are configured.
+- Default `openclaw health` asks the running gateway for its health snapshot. When the
+  gateway already has a fresh cached snapshot, it can return that cached payload and
+  refresh in the background.
+- `--verbose` forces a live probe, prints gateway connection details, and expands the
+  human-readable output across all configured accounts and agents.
 - Output includes per-agent session stores when multiple agents are configured.

docs/cli/index.md

@@ -356,7 +356,7 @@ Note: plugins can add additional top-level commands (for example `openclaw voice
 
 - `openclaw security audit` — audit config + local state for common security foot-guns.
 - `openclaw security audit --deep` — best-effort live Gateway probe.
-- `openclaw security audit --fix` — tighten safe defaults and chmod state/config.
+- `openclaw security audit --fix` — tighten safe defaults and state/config permissions.
 
 ## Secrets
 
@@ -421,7 +421,7 @@ Most plugin changes require a gateway restart. See [/plugin](/tools/plugin).
 
 Vector search over `MEMORY.md` + `memory/*.md`:
 
-- `openclaw memory status` — show index stats; use `--deep` for provider probes or `--fix` to repair stale recall/promotion artifacts.
+- `openclaw memory status` — show index stats; use `--deep` for vector + embedding readiness checks or `--fix` to repair stale recall/promotion artifacts.
 - `openclaw memory index` — reindex memory files.
 - `openclaw memory search "<query>"` (or `--query "<query>"`) — semantic search over memory.
 - `openclaw memory promote` — rank short-term recalls and optionally append top entries into `MEMORY.md`.
@@ -506,8 +506,11 @@ Options:
   `minimax-global-oauth`, `minimax-global-api`, `minimax-cn-oauth`, `minimax-cn-api`,
   `opencode-zen`, `opencode-go`, `github-copilot`, `copilot-proxy`, `xai-api-key`,
   `mistral-api-key`, `volcengine-api-key`, `byteplus-api-key`, `qianfan-api-key`,
+  `qwen-standard-api-key-cn`, `qwen-standard-api-key`, `qwen-api-key-cn`, `qwen-api-key`,
   `modelstudio-standard-api-key-cn`, `modelstudio-standard-api-key`,
   `modelstudio-api-key-cn`, `modelstudio-api-key`, `custom-api-key`, `skip`
+- Qwen note: `qwen-*` is the canonical auth-choice family. `modelstudio-*`
+  ids remain accepted as legacy compatibility aliases only.
 - `--secret-input-mode <plaintext|ref>` (default `plaintext`; use `ref` to store provider default env refs instead of plaintext keys)
 - `--anthropic-api-key <key>`
 - `--openai-api-key <key>`
@@ -546,7 +549,7 @@ Options:
 - `--skip-ui`
 - `--cloudflare-ai-gateway-account-id <id>`
 - `--cloudflare-ai-gateway-gateway-id <id>`
-- `--node-manager <npm|pnpm|bun>` (pnpm recommended; bun not recommended for Gateway runtime)
+- `--node-manager <npm|pnpm|bun>` (setup/onboarding node manager for skills; pnpm recommended, bun also supported)
 - `--json`
 
 ### `configure`
@@ -576,7 +579,7 @@ Subcommands:
 - `config set --strict-json`: require JSON5 parsing for path/value input. `--json` remains a legacy alias for strict parsing outside dry-run output mode.
 - `config unset <path>`: remove a value.
 - `config file`: print the active config file path.
-- `config schema`: print the generated JSON schema for `openclaw.json`.
+- `config schema`: print the generated JSON schema for `openclaw.json`, including propagated field `title` / `description` docs metadata across nested object, wildcard, array-item, and composition branches, plus best-effort live plugin/channel schema metadata.
 - `config validate`: validate the current config against the schema without starting the gateway.
 - `config validate --json`: emit machine-readable JSON output.
 
@@ -669,11 +672,11 @@ Manage chat channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Matter
 Subcommands:
 
 - `channels list`: show configured channels and auth profiles.
-- `channels status`: check gateway reachability and channel health (`--probe` runs extra checks; use `openclaw health` or `openclaw status --deep` for gateway health probes).
+- `channels status`: check gateway reachability and channel health (`--probe` runs live per-account probe/audit checks when the gateway is reachable; if not, it falls back to config-only channel summaries. Use `openclaw health` or `openclaw status --deep` for broader gateway health probes).
 - Tip: `channels status` prints warnings with suggested fixes when it can detect common misconfigurations (then points you to `openclaw doctor`).
 - `channels logs`: show recent channel logs from the gateway log file.
 - `channels add`: wizard-style setup when no flags are passed; flags switch to non-interactive mode.
-  - When adding a non-default account to a channel still using single-account top-level config, OpenClaw moves account-scoped values into `channels.<channel>.accounts.default` before writing the new account.
+  - When adding a non-default account to a channel still using single-account top-level config, OpenClaw promotes account-scoped values into the channel account map before writing the new account. Most channels use `accounts.default`; Matrix can preserve an existing matching named/default target instead.
   - Non-interactive `channels add` does not auto-create/upgrade bindings; channel-only bindings continue to match the default account.
 - `channels remove`: disable by default; pass `--delete` to remove config entries without prompts.
 - `channels login`: interactive channel login (WhatsApp Web only).
@@ -733,6 +736,7 @@ Notes:
 
 - `channels login` supports `--verbose`.
 - `channels capabilities --account` only applies when `--channel` is set.
+- `channels status --probe` can show transport state plus probe/audit results such as `works`, `probe failed`, `audit ok`, or `audit failed`, depending on channel support.
 
 More detail: [/concepts/oauth](/concepts/oauth)
 
@@ -770,11 +774,18 @@ List and inspect available skills plus readiness info.
 Subcommands:
 
 - `skills search [query...]`: search ClawHub skills.
+- `skills search --limit <n> --json`: cap search results or emit machine-readable output.
 - `skills install <slug>`: install a skill from ClawHub into the active workspace.
+- `skills install <slug> --version <version>`: install a specific ClawHub version.
+- `skills install <slug> --force`: overwrite an existing workspace skill folder.
 - `skills update <slug|--all>`: update tracked ClawHub skills.
 - `skills list`: list skills (default when no subcommand).
+- `skills list --json`: emit machine-readable skill inventory on stdout.
+- `skills list --verbose`: include missing requirements in the table.
 - `skills info <name>`: show details for one skill.
+- `skills info <name> --json`: emit machine-readable details on stdout.
 - `skills check`: summary of ready vs missing requirements.
+- `skills check --json`: emit machine-readable readiness output on stdout.
 
 Options:
 
@@ -817,6 +828,9 @@ Notes:
 
 - `devices list` and `devices approve` can fall back to local pairing files on local loopback when direct pairing scope is unavailable.
 - `devices approve` auto-selects the newest pending request when no `requestId` is passed or `--latest` is set.
+- Stored-token reconnects reuse the token's cached approved scopes; explicit
+  `devices rotate --scope ...` updates that stored scope set for future
+  cached-token reconnects.
 - `devices rotate` and `devices revoke` return JSON payloads.
 
 ### `qr`
@@ -838,6 +852,10 @@ Notes:
 
 - `--token` and `--password` are mutually exclusive.
 - The setup code carries a short-lived bootstrap token, not the shared gateway token/password.
+- Built-in bootstrap handoff keeps the primary node token at `scopes: []`.
+- Any handed-off operator bootstrap token stays bounded to `operator.approvals`, `operator.read`, `operator.talk.secrets`, and `operator.write`.
+- Bootstrap scope checks are role-prefixed, so that operator allowlist only satisfies operator requests; non-operator roles still need scopes under their own role prefix.
+- `--remote` can use `gateway.remote.url` or the active Tailscale Serve/Funnel URL.
 - After scanning, approve the request with `openclaw devices list` / `openclaw devices approve <requestId>`.
 
 ### `clawbot`
@@ -1188,7 +1206,7 @@ Options:
 
 - `--json`
 - `--all` (full diagnosis; read-only, pasteable)
-- `--deep` (probe channels)
+- `--deep` (ask the gateway for a live health probe, including channel probes when supported)
 - `--usage` (show model provider usage/quota)
 - `--timeout <ms>`
 - `--verbose`
@@ -1197,6 +1215,7 @@ Options:
 Notes:
 
 - Overview includes Gateway + node host service status when available.
+- `--usage` prints normalized provider usage windows as `X% left`.
 
 ### Usage tracking
 
@@ -1211,8 +1230,10 @@ Surfaces:
 Notes:
 
 - Data comes directly from provider usage endpoints (no estimates).
-- Providers: Anthropic, GitHub Copilot, OpenAI Codex OAuth, plus Gemini CLI via the bundled `google` plugin and Antigravity where configured.
-- If no matching credentials exist, usage is hidden.
+- Human-readable output is normalized to `X% left` across providers.
+- Providers with current usage windows: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi, and z.ai.
+- MiniMax note: raw `usage_percent` / `usagePercent` means remaining quota, so OpenClaw inverts it before display; count-based fields still win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label.
+- Usage auth comes from provider-specific hooks when available; otherwise OpenClaw falls back to matching OAuth/API-key credentials from auth profiles, env, or config. If none resolve, usage is hidden.
 - Details: see [Usage tracking](/concepts/usage-tracking).
 
 ### `health`
@@ -1223,9 +1244,14 @@ Options:
 
 - `--json`
 - `--timeout <ms>`
-- `--verbose`
+- `--verbose` (force a live probe and print gateway connection details)
 - `--debug` (alias for `--verbose`)
 
+Notes:
+
+- Default `health` can return a fresh cached gateway snapshot.
+- `health --verbose` forces a live probe and expands human-readable output across all configured accounts and agents.
+
 ### `sessions`
 
 List stored conversation sessions.
@@ -1429,8 +1455,15 @@ Subcommands:
 - `gateway install|uninstall|start|stop|restart`
 - `gateway run`
 
+Notes:
+
+- `gateway status --deep` adds a system-level service scan. Use `gateway probe`,
+  `health --verbose`, or top-level `status --deep` for deeper runtime probe detail.
+
 Common RPCs:
 
+- `config.schema.lookup` (inspect one config subtree with a shallow schema node, matched hint metadata, and immediate child summaries)
+- `config.get` (read current config snapshot + hash)
 - `config.set` (validate + write full config; use `baseHash` for optimistic concurrency)
 - `config.apply` (validate + write config + restart + wake)
 - `config.patch` (merge a partial update + restart + wake)
@@ -1438,19 +1471,22 @@ Common RPCs:
 
 Tip: when calling `config.set`/`config.apply`/`config.patch` directly, pass `baseHash` from
 `config.get` if a config already exists.
+Tip: for partial edits, inspect with `config.schema.lookup` first and prefer `config.patch`.
 Tip: these config write RPCs preflight active SecretRef resolution for refs in the submitted config payload and reject writes when an effectively active submitted ref is unresolved.
+Tip: the owner-only `gateway` runtime tool still refuses to rewrite `tools.exec.ask` or `tools.exec.security`; legacy `tools.bash.*` aliases normalize to the same protected exec paths.
 
 ## Models
 
 See [/concepts/models](/concepts/models) for fallback behavior and scanning strategy.
 
-Billing note: Anthropic changed third-party harness billing on **April 4, 2026
-at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no
-longer cover OpenClaw, and Claude CLI usage in OpenClaw now requires **Extra
-Usage** billed separately from the subscription. For production, prefer an
-Anthropic API key or another supported subscription-style provider such as
-OpenAI Codex, Alibaba Cloud Model Studio Coding Plan, MiniMax Coding Plan, or
-Z.AI / GLM Coding Plan.
+Billing note: Anthropic's public Claude Code docs still include direct Claude
+Code terminal usage in Claude plan limits. Separately, Anthropic notified
+OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the
+**OpenClaw** Claude-login path counts as third-party harness usage and
+requires **Extra Usage** billed separately from the subscription. For
+production, prefer an Anthropic API key or another supported
+subscription-style provider such as OpenAI Codex, Alibaba Cloud Model Studio
+Coding Plan, MiniMax Coding Plan, or Z.AI / GLM Coding Plan.
 
 Anthropic Claude CLI migration:
 
@@ -1460,8 +1496,9 @@ openclaw models auth login --provider anthropic --method cli --set-default
 
 Onboarding shortcut: `openclaw onboard --auth-choice anthropic-cli`
 
-Existing legacy Anthropic token profiles still run if already configured, but
-OpenClaw no longer offers Anthropic setup-token as a new auth path.
+Anthropic setup-token is also available again as a legacy/manual auth path.
+Use it only with the expectation that Anthropic told OpenClaw users the
+OpenClaw Claude-login path requires **Extra Usage**.
 
 Legacy alias note: `claude-cli` is the deprecated onboarding auth-choice alias.
 Use `anthropic-cli` for onboarding, or use `models auth login` directly.
@@ -1498,9 +1535,15 @@ Options:
 - `--probe-timeout <ms>`
 - `--probe-concurrency <n>`
 - `--probe-max-tokens <n>`
+- `--agent <id>`
 
 Always includes the auth overview and OAuth expiry status for profiles in the auth store.
 `--probe` runs live requests (may consume tokens and trigger rate limits).
+Probe rows can come from auth profiles, env credentials, or `models.json`.
+Expect probe statuses like `ok`, `auth`, `rate_limit`, `billing`, `timeout`,
+`format`, `unknown`, and `no_model`.
+When an explicit `auth.order.<provider>` omits a stored profile, probe reports
+`excluded_by_auth_order` instead of silently trying that profile.
 
 ### `models set <model>`
 
@@ -1566,7 +1609,9 @@ Options:
 Notes:
 
 - `setup-token` and `paste-token` are generic token commands for providers that expose token auth methods.
-- Anthropic legacy token profiles still run if already configured, but Anthropic no longer supports `setup-token` or `paste-token` as a new OpenClaw auth path.
+- `setup-token` requires an interactive TTY and runs the provider's token-auth method.
+- `paste-token` prompts for the token value and defaults to auth profile id `<provider>:manual` when `--profile-id` is omitted.
+- Anthropic `setup-token` / `paste-token` are available again as a legacy/manual OpenClaw path. Anthropic told OpenClaw users this path requires **Extra Usage** on the Claude account.
 
 ### `models auth order get|set|clear`
 
@@ -1628,6 +1673,12 @@ Subcommands:
 
 All `cron` commands accept `--url`, `--token`, `--timeout`, `--expect-final`.
 
+`cron add|edit --model ...` uses that selected allowed model for the job. If
+the model is not allowed, cron warns 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.
+
 ## Node host
 
 ### `node`

docs/cli/mcp.md

@@ -432,11 +432,11 @@ Launches a local child process and communicates over stdin/stdout.
 
 Connects to a remote MCP server over HTTP Server-Sent Events.
 
-| Field               | Description                                                      |
-| ------------------- | ---------------------------------------------------------------- |
-| `url`               | HTTP or HTTPS URL of the remote server (required)                |
-| `headers`           | Optional key-value map of HTTP headers (for example auth tokens) |
-| `connectionTimeout` | Per-server connection timeout in ms (optional)                   |
+| Field                 | Description                                                      |
+| --------------------- | ---------------------------------------------------------------- |
+| `url`                 | HTTP or HTTPS URL of the remote server (required)                |
+| `headers`             | Optional key-value map of HTTP headers (for example auth tokens) |
+| `connectionTimeoutMs` | Per-server connection timeout in ms (optional)                   |
 
 Example:
 
@@ -462,12 +462,12 @@ status output.
 
 `streamable-http` is an additional transport option alongside `sse` and `stdio`. It uses HTTP streaming for bidirectional communication with remote MCP servers.
 
-| Field               | Description                                                      |
-| ------------------- | ---------------------------------------------------------------- |
-| `url`               | HTTP or HTTPS URL of the remote server (required)                |
-| `transport`         | Set to `"streamable-http"` to select this transport              |
-| `headers`           | Optional key-value map of HTTP headers (for example auth tokens) |
-| `connectionTimeout` | Per-server connection timeout in ms (optional)                   |
+| Field                 | Description                                                                            |
+| --------------------- | -------------------------------------------------------------------------------------- |
+| `url`                 | HTTP or HTTPS URL of the remote server (required)                                      |
+| `transport`           | Set to `"streamable-http"` to select this transport; when omitted, OpenClaw uses `sse` |
+| `headers`             | Optional key-value map of HTTP headers (for example auth tokens)                       |
+| `connectionTimeoutMs` | Per-server connection timeout in ms (optional)                                         |
 
 Example:
 
@@ -478,7 +478,7 @@ Example:
       "streaming-tools": {
         "url": "https://mcp.example.com/stream",
         "transport": "streamable-http",
-        "connectionTimeout": 10000,
+        "connectionTimeoutMs": 10000,
         "headers": {
           "Authorization": "Bearer <token>"
         }

docs/cli/models.md

@@ -25,19 +25,29 @@ openclaw models scan
 ```
 
 `openclaw models status` shows the resolved default/fallbacks plus an auth overview.
-When provider usage snapshots are available, the OAuth/token status section includes
+When provider usage snapshots are available, the OAuth/API-key status section includes
 provider usage windows and quota snapshots.
+Current usage-window providers: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
+Codex, MiniMax, Xiaomi, and z.ai. Usage auth comes from provider-specific hooks
+when available; otherwise OpenClaw falls back to matching OAuth/API-key
+credentials from auth profiles, env, or config.
 Add `--probe` to run live auth probes against each configured provider profile.
 Probes are real requests (may consume tokens and trigger rate limits).
 Use `--agent <id>` to inspect a configured agent’s model/auth state. When omitted,
 the command uses `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` if set, otherwise the
 configured default agent.
+Probe rows can come from auth profiles, env credentials, or `models.json`.
 
 Notes:
 
 - `models set <model-or-alias>` accepts `provider/model` or an alias.
 - Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
-- If you omit the provider, OpenClaw treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
+- If you omit the provider, OpenClaw resolves the input as an alias first, then
+  as a unique configured-provider match for that exact model id, and only then
+  falls back to the configured default provider with a deprecation warning.
+  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 status` may show `marker(<value>)` in auth output for non-secret placeholders (for example `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) instead of masking them as secrets.
 
 ### `models status`
@@ -55,6 +65,27 @@ Options:
 - `--probe-max-tokens <n>`
 - `--agent <id>` (configured agent id; overrides `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
 
+Probe status buckets:
+
+- `ok`
+- `auth`
+- `rate_limit`
+- `billing`
+- `timeout`
+- `format`
+- `unknown`
+- `no_model`
+
+Probe detail/reason-code cases to expect:
+
+- `excluded_by_auth_order`: a stored profile exists, but explicit
+  `auth.order.<provider>` omitted it, so probe reports the exclusion instead of
+  trying it.
+- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
+  profile is present but not eligible/resolvable.
+- `no_model`: provider auth exists, but OpenClaw could not resolve a probeable
+  model candidate for that provider.
+
 ## Aliases + fallbacks
 
 ```bash
@@ -88,9 +119,18 @@ openclaw models auth login --provider openai-codex --set-default
 Notes:
 
 - `login --provider anthropic --method cli --set-default` reuses a local Claude
-  CLI login and rewrites the main Anthropic default-model path to `claude-cli/...`.
+  CLI login and rewrites the main Anthropic default-model path to a canonical
+  `claude-cli/claude-*` ref.
 - `setup-token` and `paste-token` remain generic token commands for providers
   that expose token auth methods.
+- `setup-token` requires an interactive TTY and runs the provider's token-auth
+  method (defaulting to that provider's `setup-token` method when it exposes
+  one).
 - `paste-token` accepts a token string generated elsewhere or from automation.
-- Anthropic billing note: Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover OpenClaw, and Claude CLI traffic in OpenClaw now requires **Extra Usage** billed separately from the subscription.
-- Existing legacy Anthropic token profiles still run if already configured, but Anthropic no longer supports `setup-token` or `paste-token` as a new OpenClaw auth path.
+- `paste-token` requires `--provider`, prompts for the token value, and writes
+  it to the default profile id `<provider>:manual` unless you pass
+  `--profile-id`.
+- `paste-token --expires-in <duration>` stores an absolute token expiry from a
+  relative duration such as `365d` or `12h`.
+- Anthropic billing note: Anthropic's public Claude Code docs still include direct Claude Code terminal usage in Claude plan limits. Separately, Anthropic notified OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription.
+- Anthropic `setup-token` / `paste-token` are available again as a legacy/manual OpenClaw path. Use them with the expectation that Anthropic told OpenClaw users this path requires **Extra Usage**.

docs/cli/node.md

@@ -130,3 +130,8 @@ The node host stores its node id, token, display name, and gateway connection in
 - `~/.openclaw/exec-approvals.json`
 - [Exec approvals](/tools/exec-approvals)
 - `openclaw approvals --node <id|name|ip>` (edit from the Gateway)
+
+For approved async node exec, OpenClaw prepares a canonical `systemRunPlan`
+before prompting. The later approved `system.run` forward reuses that stored
+plan, so edits to command/cwd/session fields after the approval request was
+created are rejected instead of changing what the node executes.

docs/cli/nodes.md

@@ -39,6 +39,15 @@ openclaw nodes status --last-connected 24h
 Use `--connected` to only show currently-connected nodes. Use `--last-connected <duration>` to
 filter to nodes that connected within a duration (e.g. `24h`, `7d`).
 
+Approval note:
+
+- `openclaw nodes pending` only needs pairing scope.
+- `openclaw nodes approve <requestId>` inherits extra scope requirements from the
+  pending request:
+  - commandless request: pairing only
+  - non-exec node commands: pairing + write
+  - `system.run` / `system.run.prepare` / `system.which`: pairing + admin
+
 ## Invoke
 
 ```bash

docs/cli/onboard.md

@@ -142,6 +142,12 @@ Flow notes:
 
 - `quickstart`: minimal prompts, auto-generates a gateway token.
 - `manual`: full prompts for port/bind/auth (alias of `advanced`).
+- When an auth choice implies a preferred provider, onboarding prefilters the
+  default-model and allowlist pickers to that provider. For Volcengine and
+  BytePlus, this also matches the coding-plan variants
+  (`volcengine-plan/*`, `byteplus-plan/*`).
+- If the preferred-provider filter yields no loaded models yet, onboarding
+  falls back to the unfiltered catalog instead of leaving the picker empty.
 - In the web-search step, some providers can trigger provider-specific
   follow-up prompts:
   - **Grok** can offer optional `x_search` setup with the same `XAI_API_KEY`

docs/cli/plugins.md

@@ -21,8 +21,14 @@ Related:
 
 ```bash
 openclaw plugins list
+openclaw plugins list --enabled
+openclaw plugins list --verbose
+openclaw plugins list --json
 openclaw plugins install <path-or-spec>
 openclaw plugins inspect <id>
+openclaw plugins inspect <id> --json
+openclaw plugins inspect --all
+openclaw plugins info <id>
 openclaw plugins enable <id>
 openclaw plugins disable <id>
 openclaw plugins uninstall <id>
@@ -30,6 +36,7 @@ openclaw plugins doctor
 openclaw plugins update <id>
 openclaw plugins update --all
 openclaw plugins marketplace list <marketplace>
+openclaw plugins marketplace list <marketplace> --json
 ```
 
 Bundled plugins ship with OpenClaw. Some are enabled by default (for example
@@ -55,15 +62,25 @@ openclaw plugins install <package> --dangerously-force-unsafe-install
 openclaw plugins install <path>                         # local path
 openclaw plugins install <plugin>@<marketplace>         # marketplace
 openclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)
+openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
 ```
 
 Bare package names are checked against ClawHub first, then npm. Security note:
 treat plugin installs like running code. Prefer pinned versions.
 
+If config is invalid, `plugins install` normally fails closed and tells you to
+run `openclaw doctor --fix` first. The only documented exception is a narrow
+bundled-plugin recovery path for plugins that explicitly opt into
+`openclaw.install.allowInvalidConfigRecovery`.
+
 `--force` reuses the existing install target and overwrites an already-installed
 plugin or hook pack in place. Use it when you are intentionally reinstalling
 the same id from a new local path, archive, ClawHub package, or npm artifact.
 
+`--pin` applies to npm installs only. It is not supported with `--marketplace`,
+because marketplace installs persist marketplace source metadata instead of an
+npm spec.
+
 `--dangerously-force-unsafe-install` is a break-glass option for false positives
 in the built-in dangerous-code scanner. It allows the install to continue even
 when the built-in scanner reports `critical` findings, but it does **not**
@@ -128,6 +145,7 @@ Use `--marketplace` when you want to pass the marketplace source explicitly:
 ```bash
 openclaw plugins install <plugin-name> --marketplace <marketplace-name>
 openclaw plugins install <plugin-name> --marketplace <owner/repo>
+openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
 openclaw plugins install <plugin-name> --marketplace ./my-marketplace
 ```
 
@@ -136,11 +154,12 @@ Marketplace sources can be:
 - a Claude known-marketplace name from `~/.claude/plugins/known_marketplaces.json`
 - a local marketplace root or `marketplace.json` path
 - a GitHub repo shorthand such as `owner/repo`
+- a GitHub repo URL such as `https://github.com/owner/repo`
 - a git URL
 
 For remote marketplaces loaded from GitHub or git, plugin entries must stay
 inside the cloned marketplace repo. OpenClaw accepts relative path sources from
-that repo and rejects external git, GitHub, URL/archive, and absolute-path
+that repo and rejects HTTP(S), absolute-path, git, GitHub, and other non-path
 plugin sources from remote manifests.
 
 For local paths and archives, OpenClaw auto-detects:
@@ -153,9 +172,24 @@ For local paths and archives, OpenClaw auto-detects:
 
 Compatible bundles install into the normal extensions root and participate in
 the same list/info/enable/disable flow. Today, bundle skills, Claude
-command-skills, Claude `settings.json` defaults, Cursor command-skills, and compatible Codex hook
-directories are supported; other detected bundle capabilities are shown in
-diagnostics/info but are not yet wired into runtime execution.
+command-skills, Claude `settings.json` defaults, Claude `.lsp.json` /
+manifest-declared `lspServers` defaults, Cursor command-skills, and compatible
+Codex hook directories are supported; other detected bundle capabilities are
+shown in diagnostics/info but are not yet wired into runtime execution.
+
+### List
+
+```bash
+openclaw plugins list
+openclaw plugins list --enabled
+openclaw plugins list --verbose
+openclaw plugins list --json
+```
+
+Use `--enabled` to show only loaded plugins. Use `--verbose` to switch from the
+table view to per-plugin detail lines with source/origin/version/activation
+metadata. Use `--json` for machine-readable inventory plus registry
+diagnostics.
 
 Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
 
@@ -228,7 +262,8 @@ openclaw plugins inspect <id> --json
 
 Deep introspection for a single plugin. Shows identity, load status, source,
 registered capabilities, hooks, tools, commands, services, gateway methods,
-HTTP routes, policy flags, diagnostics, and install metadata.
+HTTP routes, policy flags, diagnostics, install metadata, bundle capabilities,
+and any detected MCP or LSP server support.
 
 Each plugin is classified by what it actually registers at runtime:
 
@@ -242,4 +277,29 @@ See [Plugin shapes](/plugins/architecture#plugin-shapes) for more on the capabil
 The `--json` flag outputs a machine-readable report suitable for scripting and
 auditing.
 
+`inspect --all` renders a fleet-wide table with shape, capability kinds,
+compatibility notices, bundle capabilities, and hook summary columns.
+
 `info` is an alias for `inspect`.
+
+### Doctor
+
+```bash
+openclaw plugins doctor
+```
+
+`doctor` reports plugin load errors, manifest/discovery diagnostics, and
+compatibility notices. When everything is clean it prints `No plugin issues
+detected.`
+
+### Marketplace
+
+```bash
+openclaw plugins marketplace list <source>
+openclaw plugins marketplace list <source> --json
+```
+
+Marketplace list accepts a local marketplace path, a `marketplace.json` path, a
+GitHub shorthand like `owner/repo`, a GitHub repo URL, or a git URL. `--json`
+prints the resolved source label plus the parsed marketplace manifest and
+plugin entries.

docs/cli/qr.md

@@ -22,7 +22,7 @@ openclaw qr --url wss://gateway.example/ws
 
 ## Options
 
-- `--remote`: use `gateway.remote.url` plus remote token/password from config
+- `--remote`: prefer `gateway.remote.url`; if it is unset, `gateway.tailscale.mode=serve|funnel` can still provide the remote public URL
 - `--url <url>`: override gateway URL used in payload
 - `--public-url <url>`: override public URL used in payload
 - `--token <token>`: override which gateway token the bootstrap flow authenticates against
@@ -35,7 +35,12 @@ openclaw qr --url wss://gateway.example/ws
 
 - `--token` and `--password` are mutually exclusive.
 - The setup code itself now carries an opaque short-lived `bootstrapToken`, not the shared gateway token/password.
+- In the built-in node/operator bootstrap flow, the primary node token still lands with `scopes: []`.
+- If bootstrap handoff also issues an operator token, it stays bounded to the bootstrap allowlist: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`.
+- Bootstrap scope checks are role-prefixed. That operator allowlist only satisfies operator requests; non-operator roles still need scopes under their own role prefix.
 - Mobile pairing fails closed for Tailscale/public `ws://` gateway URLs. Private LAN `ws://` remains supported, but Tailscale/public mobile routes should use Tailscale Serve/Funnel or a `wss://` gateway URL.
+- With `--remote`, OpenClaw requires either `gateway.remote.url` or
+  `gateway.tailscale.mode=serve|funnel`.
 - With `--remote`, if effectively active remote credentials are configured as SecretRefs and you do not pass `--token` or `--password`, the command resolves them from the active gateway snapshot. If gateway is unavailable, the command fails fast.
 - Without `--remote`, local gateway auth SecretRefs are resolved when no CLI auth override is passed:
   - `gateway.auth.token` resolves when token auth can win (explicit `gateway.auth.mode="token"` or inferred mode where no password source wins).

docs/cli/security.md

@@ -2,7 +2,7 @@
 summary: "CLI reference for `openclaw security` (audit and fix common security footguns)"
 read_when:
   - You want to run a quick security audit on config/state
-  - You want to apply safe “fix” suggestions (chmod, tighten defaults)
+  - You want to apply safe “fix” suggestions (permissions, tighten defaults)
 title: "security"
 ---
 
@@ -30,7 +30,7 @@ This is for cooperative/shared inbox hardening. A single Gateway shared by mutua
 It also emits `security.trust_model.multi_user_heuristic` when config suggests likely shared-user ingress (for example open DM/group policy, configured group targets, or wildcard sender rules), and reminds you that OpenClaw is a personal-assistant trust model by default.
 For intentional shared-user setups, the audit guidance is to sandbox all sessions, keep filesystem access workspace-scoped, and keep personal/private identities or credentials off that runtime.
 It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
-For webhook ingress, it warns when `hooks.token` reuses the Gateway token, when `hooks.defaultSessionKey` is unset, when `hooks.allowedAgentIds` is unrestricted, when request `sessionKey` overrides are enabled, and when overrides are enabled without `hooks.allowedSessionKeyPrefixes`.
+For webhook ingress, it warns when `hooks.token` reuses the Gateway token, when `hooks.token` is short, when `hooks.path="/"`, when `hooks.defaultSessionKey` is unset, when `hooks.allowedAgentIds` is unrestricted, when request `sessionKey` overrides are enabled, and when overrides are enabled without `hooks.allowedSessionKeyPrefixes`.
 It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed extension plugin tools may be reachable under permissive tool policy.
 It also flags `gateway.allowRealIpFallback=true` (header-spoofing risk if proxies are misconfigured) and `discovery.mdns.mode="full"` (metadata leakage via mDNS TXT records).
 It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`.
@@ -68,8 +68,15 @@ openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summa
 `--fix` applies safe, deterministic remediations:
 
 - flips common `groupPolicy="open"` to `groupPolicy="allowlist"` (including account variants in supported channels)
+- when WhatsApp group policy flips to `allowlist`, seeds `groupAllowFrom` from
+  the stored `allowFrom` file when that list exists and config does not already
+  define `allowFrom`
 - sets `logging.redactSensitive` from `"off"` to `"tools"`
-- tightens permissions for state/config and common sensitive files (`credentials/*.json`, `auth-profiles.json`, `sessions.json`, session `*.jsonl`)
+- tightens permissions for state/config and common sensitive files
+  (`credentials/*.json`, `auth-profiles.json`, `sessions.json`, session
+  `*.jsonl`)
+- also tightens config include files referenced from `openclaw.json`
+- uses `chmod` on POSIX hosts and `icacls` resets on Windows
 
 `--fix` does **not**:
 

docs/cli/skills.md

@@ -21,14 +21,20 @@ Related:
 
 ```bash
 openclaw skills search "calendar"
+openclaw skills search --limit 20 --json
 openclaw skills install <slug>
 openclaw skills install <slug> --version <version>
+openclaw skills install <slug> --force
 openclaw skills update <slug>
 openclaw skills update --all
 openclaw skills list
 openclaw skills list --eligible
+openclaw skills list --json
+openclaw skills list --verbose
 openclaw skills info <name>
+openclaw skills info <name> --json
 openclaw skills check
+openclaw skills check --json
 ```
 
 `search`/`install`/`update` use ClawHub directly and install into the active
@@ -38,3 +44,16 @@ skills visible to the current workspace and config.
 This CLI `install` command downloads skill folders from ClawHub. Gateway-backed
 skill dependency installs triggered from onboarding or Skills settings use the
 separate `skills.install` request path instead.
+
+Notes:
+
+- `search [query...]` accepts an optional query; omit it to browse the default
+  ClawHub search feed.
+- `search --limit <n>` caps returned results.
+- `install --force` overwrites an existing workspace skill folder for the same
+  slug.
+- `update --all` only updates tracked ClawHub installs in the active workspace.
+- `list` is the default action when no subcommand is provided.
+- `list`, `info`, and `check` write their rendered output to stdout. With
+  `--json`, that means the machine-readable payload stays on stdout for pipes
+  and scripts.

docs/cli/status.md

@@ -20,6 +20,11 @@ openclaw status --usage
 Notes:
 
 - `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
+- `--usage` prints normalized provider usage windows as `X% left`.
+- MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so OpenClaw inverts them before display; count-based fields win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label.
+- When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values.
+- Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one.
+- For prompt-size accounting, transcript fallback prefers the larger prompt-oriented total when session metadata is missing or smaller, so custom-provider sessions do not collapse to `0` token displays.
 - Output includes per-agent session stores when multiple agents are configured.
 - Overview includes Gateway + node host service install/runtime status when available.
 - Overview includes update channel + git SHA (for source checkouts).

docs/cli/update.md

@@ -10,7 +10,8 @@ title: "update"
 
 Safely update OpenClaw and switch between stable/beta/dev channels.
 
-If you installed via **npm/pnpm** (global install, no git metadata), updates happen via the package manager flow in [Updating](/install/updating).
+If you installed via **npm/pnpm/bun** (global install, no git metadata),
+updates happen via the package-manager flow in [Updating](/install/updating).
 
 ## Usage
 
@@ -73,7 +74,9 @@ install method aligned:
 
 - `dev` → ensures a git checkout (default: `~/openclaw`, override with `OPENCLAW_GIT_DIR`),
   updates it, and installs the global CLI from that checkout.
-- `stable`/`beta` → installs from npm using the matching dist-tag.
+- `stable` → installs from npm using `latest`.
+- `beta` → prefers npm dist-tag `beta`, but falls back to `latest` when beta is
+  missing or older than the current stable release.
 
 The Gateway core auto-updater (when enabled via config) reuses this same update path.
 
@@ -82,7 +85,8 @@ The Gateway core auto-updater (when enabled via config) reuses this same update
 Channels:
 
 - `stable`: checkout the latest non-beta tag, then build + doctor.
-- `beta`: checkout the latest `-beta` tag, then build + doctor.
+- `beta`: prefer the latest `-beta` tag, but fall back to the latest stable tag
+  when beta is missing or older.
 - `dev`: checkout `main`, then fetch + rebase.
 
 High-level:
@@ -92,7 +96,7 @@ High-level:
 3. Fetches upstream (dev only).
 4. Dev only: preflight lint + TypeScript build in a temp worktree; if the tip fails, walks back up to 10 commits to find the newest clean build.
 5. Rebases onto the selected commit (dev only).
-6. Installs deps (pnpm preferred; npm fallback).
+6. Installs deps (pnpm preferred; npm fallback; bun remains available as a secondary compatibility fallback).
 7. Builds + builds the Control UI.
 8. Runs `openclaw doctor` as the final “safe update” check.
 9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.

docs/concepts/agent-loop.md

@@ -38,7 +38,7 @@ wired end-to-end.
    - tool events => `stream: "tool"`
    - assistant deltas => `stream: "assistant"`
    - lifecycle events => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
-5. `agent.wait` uses `waitForAgentJob`:
+5. `agent.wait` uses `waitForAgentRun`:
    - waits for **lifecycle end/error** for `runId`
    - returns `{ status: ok|error|timeout, startedAt, endedAt, error? }`
 
@@ -124,7 +124,8 @@ See [Plugin hooks](/plugins/architecture#provider-runtime-hooks) for the hook AP
   - assistant text (and optional reasoning)
   - inline tool summaries (when verbose + allowed)
   - assistant error text when the model errors
-- `NO_REPLY` is treated as a silent token and filtered from outgoing payloads.
+- The exact silent token `NO_REPLY` / `no_reply` is filtered from outgoing
+  payloads.
 - Messaging tool duplicates are removed from the final payload list.
 - If no renderable payloads remain and a tool errored, a fallback tool error reply is emitted
   (unless a messaging tool already sent a user-visible reply).

docs/concepts/agent-workspace.md

@@ -130,7 +130,8 @@ files.
 These live under `~/.openclaw/` and should NOT be committed to the workspace repo:
 
 - `~/.openclaw/openclaw.json` (config)
-- `~/.openclaw/credentials/` (OAuth tokens, API keys)
+- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (model auth profiles: OAuth + API keys)
+- `~/.openclaw/credentials/` (channel/provider state plus legacy OAuth import data)
 - `~/.openclaw/agents/<agentId>/sessions/` (session transcripts + metadata)
 - `~/.openclaw/skills/` (managed skills)
 

docs/concepts/agent.md

@@ -111,7 +111,11 @@ Model refs in config (for example `agents.defaults.model` and `agents.defaults.m
 
 - Use `provider/model` when configuring models.
 - If the model ID itself contains `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
-- If you omit the provider, OpenClaw treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
+- 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. 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.
 
 ## Configuration (minimal)
 

docs/concepts/architecture.md

@@ -82,8 +82,16 @@ sequenceDiagram
 - After handshake:
   - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
   - Events: `{type:"event", event, payload, seq?, stateVersion?}`
-- If `OPENCLAW_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token`
-  must match or the socket closes.
+- `hello-ok.features.methods` / `events` are discovery metadata, not a
+  generated dump of every callable helper route.
+- Shared-secret auth uses `connect.params.auth.token` or
+  `connect.params.auth.password`, depending on the configured gateway auth mode.
+- Identity-bearing modes such as Tailscale Serve
+  (`gateway.auth.allowTailscale: true`) or non-loopback
+  `gateway.auth.mode: "trusted-proxy"` satisfy auth from request headers
+  instead of `connect.params.auth.*`.
+- Private-ingress `gateway.auth.mode: "none"` disables shared-secret auth
+  entirely; keep that mode off public/untrusted ingress.
 - Idempotency keys are required for side‑effecting methods (`send`, `agent`) to
   safely retry; the server keeps a short‑lived dedupe cache.
 - Nodes must include `role: "node"` plus caps/commands/permissions in `connect`.
@@ -93,8 +101,12 @@ sequenceDiagram
 - All WS clients (operators + nodes) include a **device identity** on `connect`.
 - New device IDs require pairing approval; the Gateway issues a **device token**
   for subsequent connects.
-- **Local** connects (loopback or the gateway host’s own tailnet address) can be
-  auto‑approved to keep same‑host UX smooth.
+- Direct local loopback connects can be auto-approved to keep same-host UX
+  smooth.
+- OpenClaw also has a narrow backend/container-local self-connect path for
+  trusted shared-secret helper flows.
+- Tailnet and LAN connects, including same-host tailnet binds, still require
+  explicit pairing approval.
 - All connects must sign the `connect.challenge` nonce.
 - Signature payload `v3` also binds `platform` + `deviceFamily`; the gateway
   pins paired metadata on reconnect and requires repair pairing for metadata

docs/concepts/compaction.md

@@ -18,6 +18,11 @@ into a summary so the chat can continue.
 2. The summary is saved in the session transcript.
 3. Recent messages are kept intact.
 
+When OpenClaw splits history into compaction chunks, it keeps assistant tool
+calls paired with their matching `toolResult` entries. If a split point lands
+inside a tool block, OpenClaw moves the boundary so the pair stays together and
+the current unsummarized tail is preserved.
+
 The full conversation history stays on disk. Compaction only changes what the
 model sees on the next turn.
 
@@ -25,7 +30,11 @@ model sees on the next turn.
 
 Auto-compaction is on by default. It runs when the session nears the context
 limit, or when the model returns a context-overflow error (in which case
-OpenClaw compacts and retries).
+OpenClaw compacts and retries). Typical overflow signatures include
+`request_too_large`, `context length exceeded`, `input exceeds the maximum
+number of tokens`, `input token count exceeds the maximum number of input
+tokens`, `input is too long for the model`, and `ollama error: context length
+exceeded`.
 
 <Info>
 Before compacting, OpenClaw automatically reminds the agent to save important

docs/concepts/delegate-architecture.md

@@ -282,6 +282,17 @@ A complete delegate configuration for an organizational assistant that handles e
 
 The delegate's `AGENTS.md` defines its autonomous authority — what it may do without asking, what requires approval, and what is forbidden. [Cron Jobs](/automation/cron-jobs) drive its daily schedule.
 
+If you grant `sessions_history`, remember it is a bounded, safety-filtered
+recall view. OpenClaw redacts credential/token-like text, truncates long
+content, strips thinking tags / `<relevant-memories>` scaffolding / plain-text
+tool-call XML payloads (including `<tool_call>...</tool_call>`,
+`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
+`<function_calls>...</function_calls>`, and truncated tool-call blocks) /
+downgraded tool-call scaffolding / leaked ASCII/full-width model control
+tokens / malformed MiniMax tool-call XML from assistant recall, and can
+replace oversized rows with `[sessions_history omitted: message too large]`
+instead of returning a raw transcript dump.
+
 ## Scaling pattern
 
 The delegate model works for any small organization:

docs/concepts/features.md

@@ -14,13 +14,13 @@ title: "Features"
     Discord, iMessage, Signal, Slack, Telegram, WhatsApp, WebChat, and more with a single Gateway.
   </Card>
   <Card title="Plugins" icon="plug">
-    Add Matrix, Microsoft Teams, Nextcloud Talk, Nostr, Twitch, Zalo, and more with plugins.
+    Bundled plugins add Matrix, Nextcloud Talk, Nostr, Twitch, Zalo, and more without separate installs in normal current releases.
   </Card>
   <Card title="Routing" icon="route">
     Multi-agent routing with isolated sessions.
   </Card>
   <Card title="Media" icon="image">
-    Images, audio, and documents in and out.
+    Images, audio, video, documents, and image/video generation.
   </Card>
   <Card title="Apps and UI" icon="monitor">
     Web Control UI and macOS companion app.
@@ -34,8 +34,9 @@ title: "Features"
 
 **Channels:**
 
-- Built-in and bundled channels include BlueBubbles for iMessage, Discord, Google Chat, IRC, QQ Bot, Signal, Slack, Telegram, WebChat, and WhatsApp
-- Optional plugin channels include Feishu, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Voice Call, Zalo, and Zalo Personal
+- Built-in channels include Discord, Google Chat, iMessage (legacy), IRC, Signal, Slack, Telegram, WebChat, and WhatsApp
+- Bundled plugin channels include BlueBubbles for iMessage, Feishu, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Synology Chat, Tlon, Twitch, Zalo, and Zalo Personal
+- Optional separately installed channel plugins include Voice Call and third-party packages such as WeChat
 - Third-party channel plugins can extend the Gateway further, such as WeChat
 - Group chat support with mention-based activation
 - DM safety with allowlists and pairing
@@ -56,6 +57,7 @@ title: "Features"
 **Media:**
 
 - Images, audio, video, and documents in and out
+- Shared image generation and video generation capability surfaces
 - Voice note transcription
 - Text-to-speech with multiple providers
 
@@ -69,6 +71,6 @@ title: "Features"
 **Tools and automation:**
 
 - Browser automation, exec, sandboxing
-- Web search (Brave, Perplexity, Gemini, Grok, Kimi, Firecrawl)
+- Web search (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily)
 - Cron jobs and heartbeat scheduling
 - Skills, plugins, and workflow pipelines (Lobster)

docs/concepts/model-failover.md

@@ -120,11 +120,33 @@ If you have both an OAuth profile and an API key profile for the same provider,
 
 When a profile fails due to auth/rate‑limit errors (or a timeout that looks
 like rate limiting), OpenClaw marks it in cooldown and moves to the next profile.
+That rate-limit bucket is broader than plain `429`: it also includes provider
+messages such as `Too many concurrent requests`, `ThrottlingException`,
+`concurrency limit reached`, `workers_ai ... quota limit exceeded`,
+`throttled`, `resource exhausted`, and periodic usage-window limits such as
+`weekly/monthly limit reached`.
 Format/invalid‑request errors (for example Cloud Code Assist tool call ID
 validation failures) are treated as failover‑worthy and use the same cooldowns.
 OpenAI-compatible stop-reason errors such as `Unhandled stop reason: error`,
 `stop reason: error`, and `reason: error` are classified as timeout/failover
 signals.
+Provider-scoped generic server text can also land in that timeout bucket when
+the source matches a known transient pattern. For example, Anthropic bare
+`An unknown error occurred` and JSON `api_error` payloads with transient server
+text such as `internal server error`, `unknown error, 520`, `upstream error`,
+or `backend error` are treated as failover-worthy timeouts. OpenRouter-specific
+generic upstream text such as bare `Provider returned error` is also treated as
+timeout only when the provider context is actually OpenRouter. Generic internal
+fallback text such as `LLM request failed with an unknown error.` stays
+conservative and does not trigger failover by itself.
+
+Rate-limit cooldowns can also be model-scoped:
+
+- OpenClaw records `cooldownModel` for rate-limit failures when the failing
+  model id is known.
+- A sibling model on the same provider can still be tried when the cooldown is
+  scoped to a different model.
+- Billing/disabled windows still block the whole profile across models.
 
 Cooldowns use exponential backoff:
 
@@ -151,6 +173,17 @@ State is stored in `auth-profiles.json` under `usageStats`:
 
 Billing/credit failures (for example “insufficient credits” / “credit balance too low”) are treated as failover‑worthy, but they’re usually not transient. Instead of a short cooldown, OpenClaw marks the profile as **disabled** (with a longer backoff) and rotates to the next profile/provider.
 
+Not every billing-shaped response is `402`, and not every HTTP `402` lands
+here. OpenClaw keeps explicit billing text in the billing lane even when a
+provider returns `401` or `403` instead, but provider-specific matchers stay
+scoped to the provider that owns them (for example OpenRouter `403 Key limit
+exceeded`). Meanwhile temporary `402` usage-window and
+organization/workspace spend-limit errors are classified as `rate_limit` when
+the message looks retryable (for example `weekly usage limit exhausted`, `daily
+limit reached, resets tomorrow`, or `organization spending limit exceeded`).
+Those stay on the short cooldown/failover path instead of the long
+billing-disable path.
+
 State is stored in `auth-profiles.json`:
 
 ```json
@@ -179,8 +212,9 @@ timeouts that exhausted profile rotation (other errors do not advance fallback).
 
 Overloaded and rate-limit errors are handled more aggressively than billing
 cooldowns. By default, OpenClaw allows one same-provider auth-profile retry,
-then switches to the next configured model fallback without waiting. Tune this
-with `auth.cooldowns.overloadedProfileRotations`,
+then switches to the next configured model fallback without waiting.
+Provider-busy signals such as `ModelNotReadyException` land in that overloaded
+bucket. Tune this with `auth.cooldowns.overloadedProfileRotations`,
 `auth.cooldowns.overloadedBackoffMs`, and
 `auth.cooldowns.rateLimitedProfileRotations`.
 
@@ -223,6 +257,10 @@ Model fallback does not continue on:
 
 - explicit aborts that are not timeout/failover-shaped
 - context overflow errors that should stay inside compaction/retry logic
+  (for example `request_too_large`, `INVALID_ARGUMENT: input exceeds the maximum
+number of tokens`, `input token count exceeds the maximum number of input
+tokens`, `The input is too long for the model`, or `ollama error: context
+length exceeded`)
 - a final unknown error when there are no candidates left
 
 ### Cooldown skip vs probe behavior
@@ -236,7 +274,9 @@ not automatically skip that provider forever. It makes a per-candidate decision:
 - The primary candidate may be probed near cooldown expiry, with a per-provider
   throttle.
 - Same-provider fallback siblings can be attempted despite cooldown when the
-  failure looks transient (`rate_limit`, `overloaded`, or unknown).
+  failure looks transient (`rate_limit`, `overloaded`, or unknown). This is
+  especially relevant when a rate limit is model-scoped and a sibling model may
+  still recover immediately.
 - Transient cooldown probes are limited to one per provider per fallback run so
   a single provider does not stall cross-provider fallback.
 
@@ -248,6 +288,10 @@ parts of the same session entry.
 
 That means fallback retries have to coordinate with live model switching:
 
+- Only explicit user-driven model changes mark a pending live switch. That
+  includes `/model`, `session_status(model=...)`, and `sessions.patch`.
+- System-driven model changes such as fallback rotation, heartbeat overrides,
+  or compaction never mark a pending live switch on their own.
 - Before a fallback retry starts, the reply runner persists the selected
   fallback override fields to the session entry.
 - Live-session reconciliation prefers persisted session overrides over stale
@@ -283,6 +327,13 @@ reply runner can use that to build a more specific message such as "all models
 are temporarily rate-limited" and include the soonest cooldown expiry when one
 is known.
 
+That cooldown summary is model-aware:
+
+- unrelated model-scoped rate limits are ignored for the attempted
+  provider/model chain
+- if the remaining block is a matching model-scoped rate limit, OpenClaw
+  reports the last matching expiry that still blocks that model
+
 ## Related config
 
 See [Gateway configuration](/gateway/configuration) for:

docs/concepts/model-providers.md

@@ -28,14 +28,23 @@ For model selection rules, see [/concepts/models](/concepts/models).
   map is now just for non-plugin/core providers and a few generic-precedence
   cases such as Anthropic API-key-first onboarding.
 - Provider plugins can also own provider runtime behavior via
-  `normalizeConfig`, `resolveDynamicModel`, `prepareDynamicModel`,
-  `normalizeResolvedModel`, `capabilities`, `prepareExtraParams`,
-  `wrapStreamFn`, `formatApiKey`, `refreshOAuth`, `buildAuthDoctorHint`,
+  `normalizeModelId`, `normalizeTransport`, `normalizeConfig`,
+  `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
+  `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`,
+  `resolveDynamicModel`, `prepareDynamicModel`,
+  `normalizeResolvedModel`, `contributeResolvedModelCompat`,
+  `capabilities`, `normalizeToolSchemas`,
+  `inspectToolSchemas`, `resolveReasoningOutputMode`,
+  `prepareExtraParams`, `createStreamFn`, `wrapStreamFn`,
+  `resolveTransportTurnState`, `resolveWebSocketSessionPolicy`,
+  `createEmbeddingProvider`, `formatApiKey`, `refreshOAuth`,
+  `buildAuthDoctorHint`,
   `matchesContextOverflowError`, `classifyFailoverReason`,
   `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`,
   `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`,
   `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`,
-  `prepareRuntimeAuth`, `resolveUsageAuth`, and `fetchUsageSnapshot`.
+  `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and
+  `onModelSelected`.
 - Note: provider runtime `capabilities` is shared runner metadata (provider
   family, transcript/tooling quirks, transport/cache hints). It is not the
   same as the [public capability model](/plugins/architecture#public-capability-model)
@@ -53,15 +62,50 @@ Typical split:
 - `wizard.setup` / `wizard.modelPicker`: provider owns auth-choice labels,
   legacy aliases, onboarding allowlist hints, and setup entries in onboarding/model pickers
 - `catalog`: provider appears in `models.providers`
-- `normalizeConfig`: provider normalizes `models.providers.<id>` config before runtime uses it
+- `normalizeModelId`: provider normalizes legacy/preview model ids before
+  lookup or canonicalization
+- `normalizeTransport`: provider normalizes transport-family `api` / `baseUrl`
+  before generic model assembly; OpenClaw checks the matched provider first,
+  then other hook-capable provider plugins until one actually changes the
+  transport
+- `normalizeConfig`: provider normalizes `models.providers.<id>` config before
+  runtime uses it; OpenClaw checks the matched provider first, then other
+  hook-capable provider plugins until one actually changes the config. If no
+  provider hook rewrites the config, bundled Google-family helpers still
+  normalize supported Google provider entries.
+- `applyNativeStreamingUsageCompat`: provider applies endpoint-driven native streaming-usage compat rewrites for config providers
+- `resolveConfigApiKey`: provider resolves env-marker auth for config providers
+  without forcing full runtime auth loading. `amazon-bedrock` also has a
+  built-in AWS env-marker resolver here, even though Bedrock runtime auth uses
+  the AWS SDK default chain.
+- `resolveSyntheticAuth`: provider can expose local/self-hosted or other
+  config-backed auth availability without persisting plaintext secrets
+- `shouldDeferSyntheticProfileAuth`: provider can mark stored synthetic profile
+  placeholders as lower precedence than env/config-backed auth
 - `resolveDynamicModel`: provider accepts model ids not present in the local
   static catalog yet
 - `prepareDynamicModel`: provider needs a metadata refresh before retrying
   dynamic resolution
 - `normalizeResolvedModel`: provider needs transport or base URL rewrites
+- `contributeResolvedModelCompat`: provider contributes compat flags for its
+  vendor models even when they arrive through another compatible transport
 - `capabilities`: provider publishes transcript/tooling/provider-family quirks
+- `normalizeToolSchemas`: provider cleans tool schemas before the embedded
+  runner sees them
+- `inspectToolSchemas`: provider surfaces transport-specific schema warnings
+  after normalization
+- `resolveReasoningOutputMode`: provider chooses native vs tagged
+  reasoning-output contracts
 - `prepareExtraParams`: provider defaults or normalizes per-model request params
+- `createStreamFn`: provider replaces the normal stream path with a fully
+  custom transport
 - `wrapStreamFn`: provider applies request headers/body/model compat wrappers
+- `resolveTransportTurnState`: provider supplies per-turn native transport
+  headers or metadata
+- `resolveWebSocketSessionPolicy`: provider supplies native WebSocket session
+  headers or session cool-down policy
+- `createEmbeddingProvider`: provider owns memory embedding behavior when it
+  belongs with the provider plugin instead of the core embedding switchboard
 - `formatApiKey`: provider formats stored auth profiles into the runtime
   `apiKey` string expected by the transport
 - `refreshOAuth`: provider owns OAuth refresh when the shared `pi-ai`
@@ -92,6 +136,8 @@ Typical split:
   and related status/reporting surfaces
 - `fetchUsageSnapshot`: provider owns the usage endpoint fetch/parsing while
   core still owns the summary shell and formatting
+- `onModelSelected`: provider runs post-selection side effects such as
+  telemetry or provider-owned session bookkeeping
 
 Current bundled examples:
 
@@ -99,30 +145,52 @@ Current bundled examples:
   endpoint fetching, cache-TTL/provider-family metadata, and auth-aware global
   config defaults
 - `amazon-bedrock`: provider-owned context-overflow matching and failover
-  reason classification for Bedrock-specific throttle/not-ready errors
+  reason classification for Bedrock-specific throttle/not-ready errors, plus
+  the shared `anthropic-by-model` replay family for Claude-only replay-policy
+  guards on Anthropic traffic
+- `anthropic-vertex`: Claude-only replay-policy guards on Anthropic-message
+  traffic
 - `openrouter`: pass-through model ids, request wrappers, provider capability
-  hints, and cache-TTL policy
+  hints, Gemini thought-signature sanitation on proxy Gemini traffic, proxy
+  reasoning injection through the `openrouter-thinking` stream family, routing
+  metadata forwarding, and cache-TTL policy
 - `github-copilot`: onboarding/device login, forward-compat model fallback,
   Claude-thinking transcript hints, runtime token exchange, and usage endpoint
   fetching
 - `openai`: GPT-5.4 forward-compat fallback, direct OpenAI transport
   normalization, Codex-aware missing-auth hints, Spark suppression, synthetic
-  OpenAI/Codex catalog rows, thinking/live-model policy, and
-  provider-family metadata
-- `google` and `google-gemini-cli`: Gemini 3.1 forward-compat fallback and
-  modern-model matching; Gemini CLI OAuth also owns auth-profile token
-  formatting, usage-token parsing, and quota endpoint fetching for usage
-  surfaces
+  OpenAI/Codex catalog rows, thinking/live-model policy, usage-token alias
+  normalization (`input` / `output` and `prompt` / `completion` families), the
+  shared `openai-responses-defaults` stream family for native OpenAI/Codex
+  wrappers, and provider-family metadata
+- `google` and `google-gemini-cli`: Gemini 3.1 forward-compat fallback,
+  native Gemini replay validation, bootstrap replay sanitation, tagged
+  reasoning-output mode, and modern-model matching; Gemini CLI OAuth also owns
+  auth-profile token formatting, usage-token parsing, and quota endpoint
+  fetching for usage surfaces
 - `moonshot`: shared transport, plugin-owned thinking payload normalization
 - `kilocode`: shared transport, plugin-owned request headers, reasoning payload
-  normalization, Gemini transcript hints, and cache-TTL policy
+  normalization, proxy-Gemini thought-signature sanitation, and cache-TTL
+  policy
 - `zai`: GLM-5 forward-compat fallback, `tool_stream` defaults, cache-TTL
-  policy, binary-thinking/live-model policy, and usage auth + quota fetching
-- `mistral`, `opencode`, and `opencode-go`: plugin-owned capability metadata
+  policy, binary-thinking/live-model policy, and usage auth + quota fetching;
+  unknown `glm-5*` ids synthesize from the bundled `glm-4.7` template
+- `xai`: native Responses transport normalization, `/fast` alias rewrites for
+  Grok fast variants, default `tool_stream`, and xAI-specific tool-schema /
+  reasoning-payload cleanup
+- `mistral`: plugin-owned capability metadata
+- `opencode` and `opencode-go`: plugin-owned capability metadata plus
+  proxy-Gemini thought-signature sanitation
 - `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi`,
-  `modelstudio`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `together`, `venice`,
+  `nvidia`, `qianfan`, `stepfun`, `synthetic`, `together`, `venice`,
   `vercel-ai-gateway`, and `volcengine`: plugin-owned catalogs only
-- `minimax` and `xiaomi`: plugin-owned catalogs plus usage auth/snapshot logic
+- `qwen`: plugin-owned catalogs for text models plus shared
+  media-understanding and video-generation provider registrations for its
+  multimodal surfaces; Qwen video generation uses the Standard DashScope video
+  endpoints with bundled Wan models such as `wan2.6-t2v` and `wan2.7-r2v`
+- `minimax`: plugin-owned catalogs, hybrid Anthropic/OpenAI replay-policy
+  selection, and usage auth/snapshot logic
+- `xiaomi`: plugin-owned catalogs plus usage auth/snapshot logic
 
 The bundled `openai` plugin now owns both provider ids: `openai` and
 `openai-codex`.
@@ -141,7 +209,10 @@ surface.
   - `<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`).
+- 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.
 
@@ -163,6 +234,11 @@ 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
 - `openai/gpt-5.3-codex-spark` is intentionally suppressed in OpenClaw because the live OpenAI API rejects it; Spark is treated as Codex-only
 
 ```json5
@@ -179,8 +255,8 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Example model: `anthropic/claude-opus-4-6`
 - CLI: `openclaw onboard --auth-choice apiKey` or `openclaw onboard --auth-choice anthropic-cli`
 - Direct public Anthropic requests support the shared `/fast` toggle and `params.fastMode`, including API-key and OAuth-authenticated traffic sent to `api.anthropic.com`; OpenClaw maps that to Anthropic `service_tier` (`auto` vs `standard_only`)
-- Billing note: Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover OpenClaw, and Claude CLI traffic now requires **Extra Usage** billed separately from the subscription.
-- Existing legacy Anthropic token profiles still run if already configured, but new setup is no longer offered through onboarding or auth commands.
+- Billing note: Anthropic's public Claude Code docs still include direct Claude Code terminal usage in Claude plan limits. Separately, Anthropic notified OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription.
+- Anthropic setup-token is available again as a legacy/manual OpenClaw path. Use it with the expectation that Anthropic told OpenClaw users this path requires **Extra Usage**.
 
 ```json5
 {
@@ -197,6 +273,9 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Default transport is `auto` (WebSocket-first, SSE fallback)
 - Override per 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
 - Shares the same `/fast` toggle and `params.fastMode` config as direct `openai/*`; OpenClaw maps that to `service_tier=priority`
 - `openai-codex/gpt-5.3-codex-spark` remains available when the Codex OAuth catalog exposes it; entitlement-dependent
 - `openai-codex/gpt-5.4` keeps native `contextWindow = 1050000` and a default runtime `contextTokens = 272000`; override the runtime cap with `models.providers.openai-codex.models[].contextTokens`
@@ -222,7 +301,7 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 ### Other subscription-style hosted options
 
-- [Qwen / Model Studio](/providers/qwen_modelstudio): Alibaba Cloud Standard pay-as-you-go and Coding Plan subscription endpoints
+- [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
 
@@ -248,6 +327,9 @@ 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`
+- 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
 
@@ -255,10 +337,17 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Auth: Vertex uses gcloud ADC; Gemini CLI uses its OAuth flow
 - Caution: Gemini CLI OAuth in OpenClaw is an unofficial integration. Some users have reported Google account restrictions after using third-party clients. Review Google terms and use a non-critical account if you choose to proceed.
 - Gemini CLI OAuth is shipped as part of the bundled `google` plugin.
+  - Install Gemini CLI first:
+    - `brew install gemini-cli`
+    - or `npm install -g @google/gemini-cli`
   - Enable: `openclaw plugins enable google`
   - Login: `openclaw models auth login --provider google-gemini-cli --set-default`
+  - Default model: `google-gemini-cli/gemini-3.1-pro-preview`
   - Note: you do **not** paste a client id or secret into `openclaw.json`. The CLI login flow stores
     tokens in auth profiles on the gateway host.
+  - If requests fail after login, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host.
+  - Gemini CLI JSON replies are parsed from `response`; usage falls back to
+    `stats`, with `stats.cached` normalized into OpenClaw `cacheRead`.
 
 ### Z.AI (GLM)
 
@@ -267,6 +356,7 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Example model: `zai/glm-5`
 - CLI: `openclaw onboard --auth-choice zai-api-key`
   - Aliases: `z.ai/*` and `z-ai/*` normalize to `zai/*`
+  - `zai-api-key` auto-detects the matching Z.AI endpoint; `zai-coding-global`, `zai-coding-cn`, `zai-global`, and `zai-cn` force a specific surface
 
 ### Vercel AI Gateway
 
@@ -279,10 +369,14 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `kilocode`
 - Auth: `KILOCODE_API_KEY`
-- Example model: `kilocode/anthropic/claude-opus-4.6`
+- Example model: `kilocode/kilo/auto`
 - CLI: `openclaw onboard --auth-choice kilocode-api-key`
 - Base URL: `https://api.kilo.ai/api/gateway/`
-- Expanded built-in catalog includes GLM-5 Free, MiniMax M2.7 Free, GPT-5.2, Gemini 3 Pro Preview, Gemini 3 Flash Preview, Grok Code Fast 1, and Kimi K2.5.
+- 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.
 
@@ -290,25 +384,57 @@ See [/providers/kilocode](/providers/kilocode) for setup details.
 
 - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)
 - Example model: `openrouter/auto`
+- OpenClaw applies OpenRouter's documented app-attribution headers only when
+  the request actually targets `openrouter.ai`
+- OpenRouter-specific Anthropic `cache_control` markers are likewise gated to
+  verified OpenRouter routes, not arbitrary proxy URLs
+- OpenRouter remains on the proxy-style OpenAI-compatible path, so native
+  OpenAI-only request shaping (`serviceTier`, Responses `store`,
+  prompt-cache hints, OpenAI reasoning-compat payloads) is not forwarded
+- Gemini-backed OpenRouter refs keep proxy-Gemini thought-signature sanitation
+  only; native Gemini replay validation and bootstrap rewrites stay off
 - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`)
-- Example model: `kilocode/anthropic/claude-opus-4.6`
-- MiniMax: `minimax` (`MINIMAX_API_KEY`)
+- Example model: `kilocode/kilo/auto`
+- Gemini-backed Kilo refs keep the same proxy-Gemini thought-signature
+  sanitation path; `kilocode/kilo/auto` and other proxy-reasoning-unsupported
+  hints skip proxy reasoning injection
+- MiniMax: `minimax` (API key) and `minimax-portal` (OAuth)
+- Auth: `MINIMAX_API_KEY` for `minimax`; `MINIMAX_OAUTH_TOKEN` or `MINIMAX_API_KEY` for `minimax-portal`
+- Example model: `minimax/MiniMax-M2.7` or `minimax-portal/MiniMax-M2.7`
+- MiniMax onboarding/API-key setup writes explicit M2.7 model definitions with
+  `input: ["text", "image"]`; the bundled provider catalog keeps the chat refs
+  text-only until that provider config is materialized
 - Moonshot: `moonshot` (`MOONSHOT_API_KEY`)
+- Example model: `moonshot/kimi-k2.5`
 - Kimi Coding: `kimi` (`KIMI_API_KEY` or `KIMICODE_API_KEY`)
+- Example model: `kimi/kimi-code`
 - Qianfan: `qianfan` (`QIANFAN_API_KEY`)
-- Model Studio: `modelstudio` (`MODELSTUDIO_API_KEY`)
+- Example model: `qianfan/deepseek-v3.2`
+- Qwen Cloud: `qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, or `DASHSCOPE_API_KEY`)
+- Example model: `qwen/qwen3.5-plus`
 - NVIDIA: `nvidia` (`NVIDIA_API_KEY`)
+- Example model: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct`
 - StepFun: `stepfun` / `stepfun-plan` (`STEPFUN_API_KEY`)
 - Example models: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603`
 - Together: `together` (`TOGETHER_API_KEY`)
+- Example model: `together/moonshotai/Kimi-K2.5`
 - Venice: `venice` (`VENICE_API_KEY`)
 - Xiaomi: `xiaomi` (`XIAOMI_API_KEY`)
+- Example model: `xiaomi/mimo-v2-flash`
 - Vercel AI Gateway: `vercel-ai-gateway` (`AI_GATEWAY_API_KEY`)
 - Hugging Face Inference: `huggingface` (`HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN`)
 - Cloudflare AI Gateway: `cloudflare-ai-gateway` (`CLOUDFLARE_AI_GATEWAY_API_KEY`)
 - Volcengine: `volcengine` (`VOLCANO_ENGINE_API_KEY`)
+- Example model: `volcengine-plan/ark-code-latest`
 - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`)
+- Example model: `byteplus-plan/ark-code-latest`
 - xAI: `xai` (`XAI_API_KEY`)
+  - Native bundled xAI requests use 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; set
+    `agents.defaults.models["xai/<model>"].params.tool_stream` to `false` to
+    disable it
 - Mistral: `mistral` (`MISTRAL_API_KEY`)
 - Example model: `mistral/mistral-large-latest`
 - CLI: `openclaw onboard --auth-choice mistral-api-key`
@@ -330,21 +456,23 @@ default base URL, headers, or model list.
 
 ### Moonshot AI (Kimi)
 
-Moonshot uses OpenAI-compatible endpoints, so configure it as a custom provider:
+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`
 - Example model: `moonshot/kimi-k2.5`
+- CLI: `openclaw onboard --auth-choice moonshot-api-key` or `openclaw onboard --auth-choice moonshot-api-key-cn`
 
 Kimi K2 model IDs:
 
 [//]: # "moonshot-kimi-k2-model-refs:start"
 
 - `moonshot/kimi-k2.5`
-- `moonshot/kimi-k2-0905-preview`
-- `moonshot/kimi-k2-turbo-preview`
 - `moonshot/kimi-k2-thinking`
 - `moonshot/kimi-k2-thinking-turbo`
+- `moonshot/kimi-k2-turbo`
 
 [//]: # "moonshot-kimi-k2-model-refs:end"
 
@@ -392,17 +520,25 @@ Volcano Engine (火山引擎) provides access to Doubao and other models in Chin
 
 - Provider: `volcengine` (coding: `volcengine-plan`)
 - Auth: `VOLCANO_ENGINE_API_KEY`
-- Example model: `volcengine/doubao-seed-1-8-251228`
+- Example model: `volcengine-plan/ark-code-latest`
 - CLI: `openclaw onboard --auth-choice volcengine-api-key`
 
 ```json5
 {
   agents: {
-    defaults: { model: { primary: "volcengine/doubao-seed-1-8-251228" } },
+    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
   },
 }
 ```
 
+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.
+
 Available models:
 
 - `volcengine/doubao-seed-1-8-251228` (Doubao Seed 1.8)
@@ -425,17 +561,25 @@ BytePlus ARK provides access to the same models as Volcano Engine for internatio
 
 - Provider: `byteplus` (coding: `byteplus-plan`)
 - Auth: `BYTEPLUS_API_KEY`
-- Example model: `byteplus/seed-1-8-251228`
+- Example model: `byteplus-plan/ark-code-latest`
 - CLI: `openclaw onboard --auth-choice byteplus-api-key`
 
 ```json5
 {
   agents: {
-    defaults: { model: { primary: "byteplus/seed-1-8-251228" } },
+    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
   },
 }
 ```
 
+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.
+
 Available models:
 
 - `byteplus/seed-1-8-251228` (Seed 1.8)
@@ -482,11 +626,26 @@ Synthetic provides Anthropic-compatible models behind the `synthetic` provider:
 
 MiniMax is configured via `models.providers` because it uses custom endpoints:
 
-- MiniMax (Anthropic‑compatible): `--auth-choice minimax-api`
-- Auth: `MINIMAX_API_KEY`
+- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth`
+- 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`
 
 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`.
+
+Plugin-owned capability split:
+
+- Text/chat defaults stay on `minimax/MiniMax-M2.7`
+- Image generation is `minimax/image-01` or `minimax-portal/image-01`
+- Image understanding is plugin-owned `MiniMax-VL-01` on both MiniMax auth paths
+- Web search stays on provider id `minimax`
+
 ### Ollama
 
 Ollama ships as a bundled provider plugin and uses Ollama's native API:
@@ -615,6 +774,10 @@ Notes:
   - `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 prompt-cache hints, no
+  OpenAI reasoning-compat payload shaping, and no hidden OpenClaw attribution
+  headers.
 - 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.
 

docs/concepts/models.md

@@ -26,7 +26,11 @@ Related:
 
 - `agents.defaults.models` is the allowlist/catalog of models OpenClaw can use (plus aliases).
 - `agents.defaults.imageModel` is used **only when** the primary model can’t accept images.
-- `agents.defaults.imageGenerationModel` is used by the shared image-generation capability. If omitted, `image_generate` can still infer a provider default from compatible auth-backed image-generation plugins. If you set a specific provider/model, also configure that provider's auth/API key.
+- `agents.defaults.pdfModel` is used by the `pdf` tool. If omitted, the tool
+  falls back to `agents.defaults.imageModel`, then the resolved session/default
+  model.
+- `agents.defaults.imageGenerationModel` is used by the shared image-generation capability. If omitted, `image_generate` can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered image-generation providers in provider-id order. If you set a specific provider/model, also configure that provider's auth/API key.
+- `agents.defaults.videoGenerationModel` is used by the shared video-generation capability. Unlike image generation, this does not infer a provider default today. Set an explicit `provider/model` such as `qwen/wan2.6-t2v`, and configure that provider's auth/API key too.
 - Per-agent defaults can override `agents.defaults.model` via `agents.list[].model` plus bindings (see [/concepts/multi-agent](/concepts/multi-agent)).
 
 ## Quick model policy
@@ -50,7 +54,9 @@ subscription** (OAuth) and **Anthropic** (API key or Claude CLI).
 
 - `agents.defaults.model.primary` and `agents.defaults.model.fallbacks`
 - `agents.defaults.imageModel.primary` and `agents.defaults.imageModel.fallbacks`
+- `agents.defaults.pdfModel.primary` and `agents.defaults.pdfModel.fallbacks`
 - `agents.defaults.imageGenerationModel.primary` and `agents.defaults.imageGenerationModel.fallbacks`
+- `agents.defaults.videoGenerationModel.primary` and `agents.defaults.videoGenerationModel.fallbacks`
 - `agents.defaults.models` (allowlist + aliases + provider params)
 - `models.providers` (custom providers written into `models.json`)
 
@@ -108,11 +114,20 @@ Notes:
 - `/model` (and `/model list`) is a compact, numbered picker (model family + available providers).
 - On Discord, `/model` and `/models` open an interactive picker with provider and model dropdowns plus a Submit step.
 - `/model <#>` selects from that picker.
-- `/model` updates the session selection immediately. If the agent is idle, the next run uses the new model right away. If the agent is busy, the in-flight run finishes first and queued/future work uses the new model after that.
+- `/model` persists the new session selection immediately.
+- If the agent is idle, the next run uses the new model right away.
+- If a run is already active, OpenClaw marks a live switch as pending and only restarts into the new model at a clean retry point.
+- If tool activity or reply output has already started, the pending switch can stay queued until a later retry opportunity or the next user turn.
 - `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
 - Model refs are parsed by splitting on the **first** `/`. Use `provider/model` when typing `/model <ref>`.
 - If the model ID itself contains `/` (OpenRouter-style), you must include the provider prefix (example: `/model openrouter/moonshotai/kimi-k2`).
-- If you omit the provider, OpenClaw treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
+- If you omit the provider, OpenClaw resolves the input in this order:
+  1. alias match
+  2. unique configured-provider match for that exact unprefixed model id
+  3. deprecated fallback to the configured default provider
+     If that provider no longer exposes the configured default model, OpenClaw
+     instead falls back to the first configured provider/model to avoid
+     surfacing a stale removed-provider default.
 
 Full command behavior/config: [Slash commands](/tools/slash-commands).
 
@@ -162,10 +177,15 @@ provider has no credentials, `models status` prints a **Missing auth** section.
 JSON includes `auth.oauth` (warn window + profiles) and `auth.providers`
 (effective auth per provider).
 Use `--check` for automation (exit `1` when missing/expired, `2` when expiring).
+Use `--probe` for live auth checks; probe rows can come from auth profiles, env
+credentials, or `models.json`.
+If explicit `auth.order.<provider>` omits a stored profile, probe reports
+`excluded_by_auth_order` instead of trying it. If auth exists but no probeable
+model can be resolved for that provider, probe reports `status: no_model`.
 
 Auth choice is provider/account dependent. For always-on gateway hosts, API
-keys are usually the most predictable; Claude CLI reuse and existing legacy
-Anthropic token profiles are also supported.
+keys are usually the most predictable; Claude CLI reuse and existing Anthropic
+OAuth/token profiles are also supported.
 
 Example (Claude CLI):
 

docs/concepts/multi-agent.md

@@ -23,6 +23,15 @@ Auth profiles are **per-agent**. Each agent reads from its own:
 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
 ```
 
+`sessions_history` is the safer cross-session recall path here too: it returns
+a bounded, sanitized view, not a raw transcript dump. Assistant recall strips
+thinking tags, `<relevant-memories>` scaffolding, plain-text tool-call XML
+payloads (including `<tool_call>...</tool_call>`,
+`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
+`<function_calls>...</function_calls>`, and truncated tool-call blocks),
+downgraded tool-call scaffolding, leaked ASCII/full-width model control
+tokens, and malformed MiniMax tool-call XML before redaction/truncation.
+
 Main agent credentials are **not** shared automatically. Never reuse `agentDir`
 across agents (it causes auth/session collisions). If you want to share creds,
 copy `auth-profiles.json` into the other agent's `agentDir`.

docs/concepts/oauth.md

@@ -13,11 +13,13 @@ title: "OAuth"
 OpenClaw supports “subscription auth” via OAuth for providers that offer it
 (notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic subscriptions, new
 setup should use the local **Claude CLI** login path on the gateway host, but
-Anthropic changed third-party harness billing on
-**April 4, 2026 at 12:00 PM PT / 8:00 PM BST**: Anthropic says Claude
-subscription limits no longer cover OpenClaw and Anthropic now requires **Extra
-Usage** for that traffic. OpenAI Codex OAuth is explicitly supported for use in
-external tools like OpenClaw. This page explains:
+Anthropic distinguishes between direct Claude Code usage and OpenClaw's reuse
+path. Anthropic's public Claude Code docs say direct Claude Code use stays
+inside Claude subscription limits. Separately, Anthropic notified OpenClaw
+users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that OpenClaw counts as
+a third-party harness and now requires **Extra Usage** for that traffic.
+OpenAI Codex OAuth is explicitly supported for use in external tools like
+OpenClaw. This page explains:
 
 For Anthropic in production, API key auth is the safer recommended path.
 
@@ -67,22 +69,30 @@ For static secret refs and runtime snapshot activation behavior, see [Secrets Ma
 ## Anthropic legacy token compatibility
 
 <Warning>
-Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM
-PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover
-OpenClaw or other third-party harnesses. Existing Anthropic token profiles
-remain technically usable in OpenClaw, but Anthropic now requires **Extra
+Anthropic's public Claude Code docs say direct Claude Code use stays within
+Claude subscription limits. Separately, Anthropic told OpenClaw users on
+**April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that **OpenClaw counts as a
+third-party harness**. Existing Anthropic token profiles remain technically
+usable in OpenClaw, but Anthropic says the OpenClaw path now requires **Extra
 Usage** (pay-as-you-go billed separately from the subscription) for that
 traffic.
 
+For Anthropic's current direct-Claude-Code plan docs, see [Using Claude Code
+with your Pro or Max
+plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
+and [Using Claude Code with your Team or Enterprise
+plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/).
+
 If you want other subscription-style options in OpenClaw, see [OpenAI
-Codex](/providers/openai), [Alibaba Cloud Model Studio Coding
-Plan](/providers/qwen_modelstudio), [MiniMax Coding Plan](/providers/minimax),
+Codex](/providers/openai), [Qwen Cloud Coding
+Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax),
 and [Z.AI / GLM Coding Plan](/providers/glm).
 </Warning>
 
-OpenClaw no longer offers Anthropic setup-token onboarding or auth commands for
-new setup. Existing legacy Anthropic token profiles are still honored at
-runtime if they are already configured.
+OpenClaw now exposes Anthropic setup-token again as a legacy/manual path.
+Anthropic's OpenClaw-specific billing notice still applies to that path, so
+use it with the expectation that Anthropic requires **Extra Usage** for
+OpenClaw-driven Claude-login traffic.
 
 ## Anthropic Claude CLI migration
 
@@ -134,6 +144,11 @@ Claude CLI path:
 3. store no new auth profile; switch model selection to `claude-cli/...`
 4. keep existing Anthropic auth profiles for rollback
 
+Anthropic's public Claude Code docs describe this direct Claude subscription
+login flow for `claude` itself. OpenClaw can reuse that local login, but
+Anthropic separately classifies the OpenClaw-controlled path as third-party
+harness usage for billing purposes.
+
 Interactive assistant path:
 
 - `openclaw onboard` / `openclaw configure` → auth choice `anthropic-cli`

docs/concepts/qa-e2e-automation.md

@@ -0,0 +1,865 @@
+---
+title: "QA E2E Automation"
+summary: "Design note for a full end-to-end QA system built on a synthetic message-channel plugin, Dockerized OpenClaw, and subagent-driven scenario execution"
+read_when:
+  - You are designing a true end-to-end QA harness for OpenClaw
+  - You want a synthetic message channel for automated feature verification
+  - You want subagents to discover features, run scenarios, and propose fixes
+---
+
+# QA E2E Automation
+
+This note proposes a true end-to-end QA system for OpenClaw built around a
+real channel plugin dedicated to testing.
+
+The core idea:
+
+- run OpenClaw inside Docker in a realistic gateway configuration
+- expose a synthetic but full-featured message channel as a normal plugin
+- let a QA harness inject inbound traffic and inspect outbound state
+- let OpenClaw agents and subagents explore, verify, and report on behavior
+- optionally escalate failing scenarios into host-side fix workflows that open PRs
+
+This is not a unit-test replacement. It is a product-level system test layer.
+
+## Chosen direction
+
+The initial direction for this project is:
+
+- build the full system inside this repo
+- test against a matrix, not a single model/provider pair
+- use Markdown reports as the first output artifact
+- defer auto-PR and auto-fix work until later
+- treat Slack-class semantics as the MVP transport target
+- keep orchestration simple in v1, with a host-side controller that exercises
+  the moving parts directly
+- evolve toward OpenClaw becoming the orchestration layer later, once the
+  transport, scenario, and reporting model are proven
+
+## Goals
+
+- Test OpenClaw through a real messaging-channel boundary, not only `chat.send`
+  or embedded mocks.
+- Verify channel semantics that matter for real use:
+  - DMs
+  - channels/groups
+  - threads
+  - edits
+  - deletes
+  - reactions
+  - polls
+  - attachments
+- Verify agent behavior across realistic user flows:
+  - memory
+  - thread binding
+  - model switching
+  - cron jobs
+  - subagents
+  - approvals
+  - routing
+  - channel-specific `message` actions
+- Make the QA runner capable of feature discovery:
+  - read docs
+  - inspect plugin capability discovery
+  - inspect code and config
+  - generate a scenario protocol
+- Support deterministic protocol tests and best-effort real-model tests as
+  separate lanes.
+- Allow automated bug triage artifacts that can feed a host-side fix worker.
+
+## Non-goals
+
+- Not a replacement for existing unit, contract, or live tests.
+- Not a production channel.
+- Not a requirement that all bug fixing happen from inside the Dockerized
+  OpenClaw runtime.
+- Not a reason to add test-only core branches for one channel.
+
+## Why a channel plugin
+
+OpenClaw already has the right boundary:
+
+- core owns the shared `message` tool, prompt wiring, outer session
+  bookkeeping, and dispatch
+- channel plugins own:
+  - config
+  - pairing
+  - security
+  - session grammar
+  - threading
+  - outbound delivery
+  - channel-owned actions and capability discovery
+
+That means the cleanest design is:
+
+- a real channel plugin for QA transport semantics
+- a separate QA control plane for injection and inspection
+
+This keeps the test transport inside the same architecture used by Slack,
+Discord, Teams, and similar channels.
+
+## System overview
+
+The system has six pieces.
+
+1. `qa-channel` plugin
+
+- Bundled extension under `extensions/qa-channel`
+- Normal `ChannelPlugin`
+- Behaves like a Slack/Discord/Teams-class channel
+- Registers channel-owned message actions through the shared `message` tool
+
+2. `qa-bus` sidecar
+
+- Small HTTP and/or WS service
+- Canonical state store for synthetic conversations, messages, threads,
+  reactions, edits, and event history
+- Accepts inbound events from the harness
+- Exposes inspection and wait APIs for assertions
+
+3. Dockerized OpenClaw gateway
+
+- Runs as close to real deployment as practical
+- Loads `qa-channel`
+- Uses normal config, routing, session, cron, and plugin loading
+
+4. QA orchestrator
+
+- Host-side runner or dedicated OpenClaw-driven controller
+- Provisions scenario environments
+- Seeds config
+- Resets state
+- Executes test matrix
+- Collects structured outcomes
+
+5. Auto-fix worker
+
+- Host-side workflow
+- Creates a worktree
+- launches a coding agent
+- runs scoped verification
+- opens a PR
+
+The auto-fix worker should start outside the container. It needs direct repo
+and GitHub access, clean worktree control, and better isolation from the
+runtime under test.
+
+6. `qa-lab` extension
+
+- Bundled extension under `extensions/qa-lab`
+- Owns the QA harness, Markdown report flow, and private debugger UI
+- Registers hidden CLI entrypoints such as `openclaw qa run` and
+  `openclaw qa ui`
+- Stays separate from the shipped Control UI bundle
+
+## High-level flow
+
+1. Start `qa-bus`.
+2. Start OpenClaw in Docker with `qa-channel` enabled.
+3. QA orchestrator injects inbound messages into `qa-bus`.
+4. `qa-channel` receives them as normal inbound traffic.
+5. OpenClaw runs the agent loop normally.
+6. Outbound replies and channel actions flow back through `qa-channel` into
+   `qa-bus`.
+7. QA orchestrator inspects state or waits on events.
+8. Orchestrator records pass/fail/flaky/unknown plus artifacts.
+9. Severe failures optionally emit a bug packet for the host-side fix worker.
+
+## Lanes
+
+The system should have two distinct lanes.
+
+### Lane A: deterministic protocol lane
+
+Use a deterministic or tightly controlled model setup.
+
+Preferred options:
+
+- a canned provider fixture
+- the bundled `synthetic` provider when useful
+- fixed prompts with exact assertions
+
+Purpose:
+
+- verify transport and product semantics
+- keep flakiness low
+- catch regressions in routing, memory plumbing, thread binding, cron, and tool
+  invocation
+
+### Lane B: quality lane
+
+Use real providers and real models in a matrix.
+
+Purpose:
+
+- verify that the agent can still do good work end to end
+- evaluate feature discoverability and instruction following
+- surface model-specific breakage or degraded behavior
+
+Expected result type:
+
+- best-effort
+- rubric-based
+- more tolerant of wording variation
+
+Matrix guidance for v1:
+
+- start with a small curated matrix, not "everything configured"
+- keep deterministic protocol runs separate from quality runs
+- report matrix cells independently so one provider/model failure does not hide
+  transport correctness
+
+Do not mix these lanes. Protocol correctness and model quality should fail
+independently.
+
+## Use existing bootstrap seam first
+
+Before the custom channel exists, OpenClaw already has a useful bootstrap path:
+
+- admin-scoped synthetic originating-route fields on `chat.send`
+- synthetic message-channel headers for HTTP flows
+
+That is enough to build a first QA controller for:
+
+- thread/session routing
+- ACP bind flows
+- subagent delivery
+- cron wake paths
+- memory persistence checks
+
+This should be Phase 0 because it de-risks the scenario protocol before the
+full channel lands.
+
+## `qa-lab` extension design
+
+`qa-lab` is the private operator-facing half of this system.
+
+Suggested package:
+
+- `extensions/qa-lab/`
+
+Suggested responsibilities:
+
+- host the synthetic bus state machine
+- host the scenario runner
+- write Markdown reports
+- serve a private debugger UI on a separate local server
+- keep that UI entirely outside the shipped Control UI bundle
+
+Suggested UI shape:
+
+- left rail for conversations and threads
+- center transcript pane
+- right rail for event stream and report inspection
+- bottom inject-composer for inbound QA traffic
+
+## `qa-channel` plugin design
+
+## Package layout
+
+Suggested package:
+
+- `extensions/qa-channel/`
+
+Suggested file layout:
+
+- `package.json`
+- `openclaw.plugin.json`
+- `index.ts`
+- `setup-entry.ts`
+- `api.ts`
+- `runtime-api.ts`
+- `src/channel.ts`
+- `src/channel-api.ts`
+- `src/config-schema.ts`
+- `src/setup-core.ts`
+- `src/setup-surface.ts`
+- `src/runtime.ts`
+- `src/channel.runtime.ts`
+- `src/inbound.ts`
+- `src/outbound.ts`
+- `src/state-client.ts`
+- `src/targets.ts`
+- `src/threading.ts`
+- `src/message-actions.ts`
+- `src/probe.ts`
+- `src/doctor.ts`
+- `src/*.test.ts`
+
+Model it after Slack, Discord, Teams, or Google Chat packaging, not as a one-off
+test helper.
+
+## Capabilities
+
+MVP capabilities:
+
+- one account
+- DMs
+- channels
+- threads
+- send text
+- reply in thread
+- read
+- edit
+- delete
+- react
+- search
+- upload-file
+- download-file
+
+Phase 2 capabilities:
+
+- polls
+- member-info
+- channel-info
+- channel-list
+- pin and unpin
+- permissions
+- topic create and edit
+
+These map naturally onto the shared `message` tool action model already used by
+channel plugins.
+
+## Conversation model
+
+Use a stable synthetic grammar that supports both simplicity and realistic
+coverage.
+
+Suggested ids:
+
+- DM conversation: `dm:<user-id>`
+- channel: `chan:<space-id>`
+- thread: `thread:<space-id>:<thread-id>`
+- message id: `msg:<ulid>`
+
+Suggested target forms:
+
+- `qa:dm:<user-id>`
+- `qa:chan:<space-id>`
+- `qa:thread:<space-id>:<thread-id>`
+
+The plugin should own translation between external target strings and canonical
+conversation ids.
+
+## Pairing and security
+
+Even though this is a QA channel, it should still implement real policy
+surfaces:
+
+- DM allowlist / pairing flow
+- group policy
+- mention gating where relevant
+- trusted sender ids
+
+Reason:
+
+- these are product features and should be testable through the QA transport
+- the QA lane should be able to verify policy failures, not only happy paths
+
+## Threading model
+
+Threading is one of the main reasons to build this channel.
+
+Required semantics:
+
+- create thread from a top-level message
+- reply inside an existing thread
+- list thread messages
+- preserve parent message linkage
+- let OpenClaw thread binding attach a session to a thread
+
+The QA bus must preserve:
+
+- conversation id
+- thread id
+- parent message id
+- sender id
+- timestamps
+
+## Channel-owned message actions
+
+The plugin should implement `actions.describeMessageTool(...)` and
+`actions.handleAction(...)`.
+
+MVP action list:
+
+- `send`
+- `read`
+- `reply`
+- `react`
+- `edit`
+- `delete`
+- `thread-create`
+- `thread-reply`
+- `search`
+- `upload-file`
+- `download-file`
+
+This is enough to test the shared `message` tool end to end with real channel
+semantics.
+
+## `qa-bus` design
+
+`qa-bus` is the transport simulator and assertion backend.
+
+It should not know OpenClaw internals. It should know channel state.
+
+For v1, keep `qa-bus` in this repo so:
+
+- fixtures and scenarios evolve with product code
+- the transport contract can change in lock-step with the plugin
+- CI and local dev do not need another repo checkout
+
+## Responsibilities
+
+- accept inbound user/platform events
+- persist canonical conversation state
+- persist append-only event log
+- expose inspection APIs
+- expose blocking wait APIs
+- support reset per scenario or per suite
+
+## Transport
+
+HTTP is enough for MVP.
+
+Suggested endpoints:
+
+- `POST /reset`
+- `POST /inbound/message`
+- `POST /inbound/edit`
+- `POST /inbound/delete`
+- `POST /inbound/reaction`
+- `POST /inbound/thread/create`
+- `GET /state/conversations`
+- `GET /state/messages`
+- `GET /state/threads`
+- `GET /events`
+- `POST /wait`
+
+Optional WS stream:
+
+- `/stream`
+
+Useful for live event taps and debugging.
+
+## State model
+
+Persist three layers.
+
+1. Conversation snapshot
+
+- participants
+- type
+- thread topology
+- latest message pointers
+
+2. Message snapshot
+
+- sender
+- content
+- attachments
+- edit history
+- reactions
+- parent and thread linkage
+
+3. Append-only event log
+
+- canonical timestamp
+- causal ordering
+- source: inbound, outbound, action, system
+- payload
+
+The append-only log matters because many QA assertions are event-oriented, not
+just state-oriented.
+
+## Assertion API
+
+The harness needs waiters, not just snapshots.
+
+Suggested `POST /wait` contract:
+
+- `kind`
+- `match`
+- `timeoutMs`
+
+Examples:
+
+- wait for outbound message matching text regex
+- wait for thread creation
+- wait for reaction added
+- wait for message edit
+- wait for no event of type X within Y ms
+
+This gives stable tests without custom polling code in every scenario.
+
+## QA orchestrator design
+
+The orchestrator should own scenario planning and artifact collection.
+
+Start host-side. Later, OpenClaw can orchestrate parts of it.
+
+This is the chosen v1 direction.
+
+Why:
+
+- simpler to iterate while the transport and scenario protocol are still moving
+- easier access to the repo, logs, Docker, and test fixtures
+- easier artifact collection and report generation
+- avoids over-coupling the first version to subagent behavior before the QA
+  protocol itself is stable
+
+## Inputs
+
+- docs pages
+- channel capability discovery
+- configured provider/model lane
+- scenario catalog
+- repo/test metadata
+
+## Outputs
+
+- structured protocol report
+- scenario transcript
+- captured channel state
+- gateway logs
+- failure packets
+
+For v1, the primary output is a Markdown report.
+
+Suggested report sections:
+
+- suite summary
+- environment
+- provider/model matrix
+- scenarios passed
+- scenarios failed
+- flaky or inconclusive scenarios
+- captured evidence links or inline excerpts
+- suspected ownership or file hints
+- follow-up recommendations
+
+## Scenario format
+
+Use a data-driven scenario spec.
+
+Suggested shape:
+
+```json
+{
+  "id": "thread-memory-recall",
+  "lane": "deterministic",
+  "preconditions": ["qa-channel", "memory-enabled"],
+  "steps": [
+    {
+      "type": "injectMessage",
+      "to": "qa:dm:user-a",
+      "text": "Remember that the deploy key is kiwi."
+    },
+    { "type": "waitForOutbound", "match": { "textIncludes": "kiwi" } },
+    { "type": "injectMessage", "to": "qa:dm:user-a", "text": "What was the deploy key?" },
+    { "type": "waitForOutbound", "match": { "textIncludes": "kiwi" } }
+  ],
+  "assertions": [{ "type": "outboundTextIncludes", "value": "kiwi" }]
+}
+```
+
+Keep the execution engine generic and the scenario catalog declarative.
+
+## Feature discovery
+
+The orchestrator can discover candidate scenarios from three sources.
+
+1. Docs
+
+- channel docs
+- testing docs
+- gateway docs
+- subagents docs
+- cron docs
+
+2. Runtime capability discovery
+
+- channel `message` action discovery
+- plugin status and channel capabilities
+- configured providers/models
+
+3. Code hints
+
+- known action names
+- channel-specific feature flags
+- config schema
+
+This should produce a proposed protocol with:
+
+- must-test
+- can-test
+- blocked
+- unsupported
+
+## Scenario classes
+
+Recommended catalog:
+
+- transport basics
+  - DM send and reply
+  - channel send
+  - thread create and reply
+  - reaction add and read
+  - edit and delete
+- policy
+  - allowlist
+  - pairing
+  - group mention gating
+- shared `message` tool
+  - read
+  - search
+  - reply
+  - react
+  - upload and download
+- agent quality
+  - follows channel context
+  - obeys thread semantics
+  - uses memory across turns
+  - switches model when instructed
+- automation
+  - cron add and run
+  - cron delivery into channel
+  - scheduled reminders
+- subagents
+  - spawn
+  - announce
+  - threaded follow-up
+  - nested orchestration when enabled
+- failure handling
+  - unsupported action
+  - timeout
+  - malformed target
+  - policy denial
+
+## OpenClaw as orchestrator
+
+Longer-term, OpenClaw itself can coordinate the QA run.
+
+Suggested architecture:
+
+- one controller session
+- N worker subagents
+- each worker owns one scenario or scenario shard
+- workers report structured results back to controller
+
+Good fits for existing OpenClaw primitives:
+
+- `sessions_spawn`
+- `subagents`
+- cron-based wakeups for long-running suites
+- thread-bound sessions for scenario-local follow-up
+
+Best near-term use:
+
+- controller generates the plan
+- workers execute scenarios in parallel
+- controller synthesizes report
+
+Avoid making the controller also own host Git operations in the first version.
+
+Chosen direction:
+
+- v1: host-side controller
+- v2+: OpenClaw-native orchestration once the scenario protocol and transport
+  model are stable
+
+## Auto-fix workflow
+
+The system should emit a structured bug packet when a scenario fails.
+
+Suggested bug packet:
+
+- scenario id
+- lane
+- failure kind
+- minimal repro steps
+- channel event transcript
+- gateway transcript
+- logs
+- suspected files
+- confidence
+
+Host-side fix worker flow:
+
+1. receive bug packet
+2. create detached worktree
+3. launch coding agent in worktree
+4. write failing regression first when practical
+5. implement fix
+6. run scoped verification
+7. open PR
+
+This should remain host-side at first because it needs:
+
+- repo write access
+- worktree hygiene
+- git credentials
+- GitHub auth
+
+Chosen direction:
+
+- do not auto-open PRs in v1
+- emit Markdown reports and structured failure packets first
+- add host-side worktree + PR automation later
+
+## Rollout plan
+
+## Phase 0: bootstrap on existing synthetic ingress
+
+Build a first QA runner without a new channel:
+
+- use `chat.send` with admin-scoped synthetic originating-route fields
+- run deterministic scenarios against routing, memory, cron, subagents, and ACP
+- validate protocol format and artifact collection
+
+Exit criteria:
+
+- scenario runner exists
+- structured protocol report exists
+- failure artifacts exist
+
+## Phase 1: MVP `qa-channel`
+
+Build the plugin and bus with:
+
+- DM
+- channels
+- threads
+- read
+- reply
+- react
+- edit
+- delete
+- search
+
+Target semantics:
+
+- Slack-class transport behavior
+- not full Teams-class parity yet
+
+Exit criteria:
+
+- OpenClaw in Docker can talk to `qa-bus`
+- harness can inject + inspect
+- one green end-to-end suite across message transport and agent behavior
+
+## Phase 2: protocol expansion
+
+Add:
+
+- attachments
+- polls
+- pins
+- richer policy tests
+- quality lane with real provider/model matrix
+
+Exit criteria:
+
+- scenario matrix covers major built-in features
+- deterministic and quality lanes are separated
+
+## Phase 3: subagent-driven QA
+
+Add:
+
+- controller agent
+- worker subagents
+- scenario discovery from docs + capability discovery
+- parallel execution
+
+Exit criteria:
+
+- one controller can fan out and synthesize a suite report
+
+## Phase 4: auto-fix loop
+
+Add:
+
+- bug packet emission
+- host-side worktree runner
+- PR creation
+
+Exit criteria:
+
+- selected failures can auto-produce draft PRs
+
+## Risks
+
+## Risk: too much magic in one layer
+
+If the QA channel, bus, and orchestrator all become smart at once, debugging
+will be painful.
+
+Mitigation:
+
+- keep `qa-channel` transport-focused
+- keep `qa-bus` state-focused
+- keep orchestrator separate
+
+## Risk: flaky assertions from model variance
+
+Mitigation:
+
+- deterministic lane
+- quality lane
+- different pass criteria
+
+## Risk: test-only branches leaking into core
+
+Mitigation:
+
+- no core special cases for `qa-channel`
+- use normal plugin seams
+- use admin synthetic ingress only as bootstrap
+
+## Risk: auto-fix overreach
+
+Mitigation:
+
+- keep fix worker host-side
+- require explicit policy for when PRs can open automatically
+- gate with scoped tests
+
+## Risk: building a fake platform nobody uses
+
+Mitigation:
+
+- emulate Slack/Discord/Teams semantics, not an abstract transport
+- prioritize features that stress shared OpenClaw boundaries
+
+## MVP recommendation
+
+If building this now, start with this exact order.
+
+1. Host-side scenario runner using existing synthetic originating-route support.
+2. `qa-bus` sidecar with state, events, reset, and wait APIs.
+3. `extensions/qa-channel` MVP with DMs, channels, threads, reply, read, react,
+   edit, delete, and search.
+4. Markdown report generator for suite + matrix output.
+5. One deterministic end-to-end suite:
+   - inject inbound DM
+   - verify reply
+   - create thread
+   - verify follow-up in thread
+   - verify memory recall on later turn
+6. Add curated real-model matrix quality lane.
+7. Add controller subagent orchestration.
+8. Add host-side auto-fix worktree runner.
+
+This order gets real value quickly without requiring the full grand design to
+land before the first useful signal appears.
+
+## Current product decisions
+
+- `qa-bus` lives inside this repo
+- the first controller is host-side
+- Slack-class behavior is the MVP target
+- the quality lane uses a curated matrix
+- first version produces Markdown reports, not PRs
+- OpenClaw-native orchestration is a later phase, not a v1 requirement

docs/concepts/session-pruning.md

@@ -10,7 +10,7 @@ read_when:
 
 Session pruning trims **old tool results** from the context before each LLM
 call. It reduces context bloat from accumulated tool outputs (exec results, file
-reads, search results) without touching your conversation messages.
+reads, search results) without rewriting normal conversation text.
 
 <Info>
 Pruning is in-memory only -- it does not modify the on-disk session transcript.
@@ -30,19 +30,31 @@ cache-write size, directly lowering cost.
 ## How it works
 
 1. Wait for the cache TTL to expire (default 5 minutes).
-2. Find old tool results (user and assistant messages are never touched).
+2. Find old tool results for normal pruning (conversation text is left alone).
 3. **Soft-trim** oversized results -- keep the head and tail, insert `...`.
 4. **Hard-clear** the rest -- replace with a placeholder.
 5. Reset the TTL so follow-up requests reuse the fresh cache.
 
+## Legacy image cleanup
+
+OpenClaw also runs a separate idempotent cleanup for older legacy sessions that
+persisted raw image blocks 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]`.
+- This is separate from normal cache-TTL pruning. It exists to stop repeated
+  image payloads from busting prompt caches on later turns.
+
 ## Smart defaults
 
 OpenClaw auto-enables pruning for Anthropic profiles:
 
-| Profile type                    | Pruning enabled | Heartbeat |
-| ------------------------------- | --------------- | --------- |
-| Claude CLI or legacy token auth | Yes             | 1 hour    |
-| API key                         | Yes             | 30 min    |
+| Profile type                                            | Pruning enabled | Heartbeat |
+| ------------------------------------------------------- | --------------- | --------- |
+| Anthropic OAuth/token auth (including Claude CLI reuse) | Yes             | 1 hour    |
+| API key                                                 | Yes             | 30 min    |
 
 If you set explicit values, OpenClaw does not override them.
 

docs/concepts/session-tool.md

@@ -1,24 +1,28 @@
 ---
-summary: "Agent tools for listing sessions, reading history, and cross-session messaging"
+summary: "Agent tools for cross-session status, recall, messaging, and sub-agent orchestration"
 read_when:
   - You want to understand what session tools the agent has
   - You want to configure cross-session access or sub-agent spawning
+  - You want to inspect status or control spawned sub-agents
 title: "Session Tools"
 ---
 
 # Session Tools
 
-OpenClaw gives agents tools to work across sessions -- listing conversations,
-reading history, sending messages to other sessions, and spawning sub-agents.
+OpenClaw gives agents tools to work across sessions, inspect status, and
+orchestrate sub-agents.
 
 ## Available tools
 
-| Tool               | What it does                                            |
-| ------------------ | ------------------------------------------------------- |
-| `sessions_list`    | List sessions with optional filters (kind, recency)     |
-| `sessions_history` | Read the transcript of a specific session               |
-| `sessions_send`    | Send a message to another session and optionally wait   |
-| `sessions_spawn`   | Spawn an isolated sub-agent session for background work |
+| Tool               | What it does                                                                |
+| ------------------ | --------------------------------------------------------------------------- |
+| `sessions_list`    | List sessions with optional filters (kind, recency)                         |
+| `sessions_history` | Read the transcript of a specific session                                   |
+| `sessions_send`    | Send a message to another session and optionally wait                       |
+| `sessions_spawn`   | Spawn an isolated sub-agent session for background work                     |
+| `sessions_yield`   | End the current turn and wait for follow-up sub-agent results               |
+| `subagents`        | List, steer, or kill spawned sub-agents for this session                    |
+| `session_status`   | Show a `/status`-style card and optionally set a per-session model override |
 
 ## Listing and reading sessions
 
@@ -28,10 +32,34 @@ counts, and timestamps. Filter by kind (`main`, `group`, `cron`, `hook`,
 
 `sessions_history` fetches the conversation transcript for a specific session.
 By default, tool results are excluded -- pass `includeTools: true` to see them.
+The returned view is intentionally bounded and safety-filtered:
+
+- assistant text is normalized before recall:
+  - thinking tags are stripped
+  - `<relevant-memories>` / `<relevant_memories>` scaffolding blocks are stripped
+  - plain-text tool-call XML payload blocks such as `<tool_call>...</tool_call>`,
+    `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, and
+    `<function_calls>...</function_calls>` are stripped, including truncated
+    payloads that never close cleanly
+  - downgraded tool-call/result scaffolding such as `[Tool Call: ...]`,
+    `[Tool Result ...]`, and `[Historical context ...]` is stripped
+  - leaked model control tokens such as `<|assistant|>`, other ASCII
+    `<|...|>` tokens, and full-width `<｜...｜>` variants are stripped
+  - malformed MiniMax tool-call XML such as `<invoke ...>` /
+    `</minimax:tool_call>` is stripped
+- credential/token-like text is redacted before it is returned
+- long text blocks are truncated
+- very large histories can drop older rows or replace an oversized row with
+  `[sessions_history omitted: message too large]`
+- the tool reports summary flags such as `truncated`, `droppedMessages`,
+  `contentTruncated`, `contentRedacted`, and `bytes`
 
 Both tools accept either a **session key** (like `"main"`) or a **session ID**
 from a previous list call.
 
+If you need the exact byte-for-byte transcript, inspect the transcript file on
+disk instead of treating `sessions_history` as a raw dump.
+
 ## Sending cross-session messages
 
 `sessions_send` delivers a message to another session and optionally waits for
@@ -45,6 +73,26 @@ After the target responds, OpenClaw can run a **reply-back loop** where the
 agents alternate messages (up to 5 turns). The target agent can reply
 `REPLY_SKIP` to stop early.
 
+## Status and orchestration helpers
+
+`session_status` is the lightweight `/status`-equivalent tool for the current
+or another visible session. It reports usage, time, model/runtime state, and
+linked background-task context when present. Like `/status`, it can backfill
+sparse token/cache counters from the latest transcript usage entry, and
+`model=default` clears a per-session override.
+
+`sessions_yield` intentionally ends the current turn so the next message can be
+the follow-up event you are waiting for. Use it after spawning sub-agents when
+you want completion results to arrive as the next message instead of building
+poll loops.
+
+`subagents` is the control-plane helper for already spawned OpenClaw
+sub-agents. It supports:
+
+- `action: "list"` to inspect active/recent runs
+- `action: "steer"` to send follow-up guidance to a running child
+- `action: "kill"` to stop one child or `all`
+
 ## Spawning sub-agents
 
 `sessions_spawn` creates an isolated session for a background task. It is always
@@ -57,8 +105,17 @@ Key options:
 - `thread: true` to bind the spawn to a chat thread (Discord, Slack, etc.).
 - `sandbox: "require"` to enforce sandboxing on the child.
 
-Sub-agents get the full tool set minus session tools (no recursive spawning).
+Default leaf sub-agents do not get session tools. When
+`maxSpawnDepth >= 2`, depth-1 orchestrator sub-agents additionally receive
+`sessions_spawn`, `subagents`, `sessions_list`, and `sessions_history` so they
+can manage their own children. Leaf runs still do not get recursive
+orchestration tools.
+
 After completion, an announce step posts the result to the requester's channel.
+Completion delivery preserves bound thread/topic routing when available, and if
+the completion origin only identifies a channel OpenClaw can still reuse the
+requester session's stored route (`lastChannel` / `lastTo`) for direct
+delivery.
 
 For ACP-specific behavior, see [ACP Agents](/tools/acp-agents).
 

docs/concepts/system-prompt.md

@@ -19,7 +19,12 @@ The prompt is intentionally compact and uses fixed sections:
 - **Tooling**: current tool list + short descriptions.
 - **Safety**: short guardrail reminder to avoid power-seeking behavior or bypassing oversight.
 - **Skills** (when available): tells the model how to load skill instructions on demand.
-- **OpenClaw Self-Update**: how to run `config.apply` and `update.run`.
+- **OpenClaw Self-Update**: how to inspect config safely with
+  `config.schema.lookup`, patch config with `config.patch`, replace the full
+  config with `config.apply`, and run `update.run` only on explicit user
+  request. The owner-only `gateway` tool also refuses to rewrite
+  `tools.exec.ask` / `tools.exec.security`, including legacy `tools.bash.*`
+  aliases that normalize to those protected exec paths.
 - **Workspace**: working directory (`agents.defaults.workspace`).
 - **Documentation**: local path to OpenClaw docs (repo or npm package) and when to read them.
 - **Workspace Files (injected)**: indicates bootstrap files are included below.
@@ -30,8 +35,29 @@ The prompt is intentionally compact and uses fixed sections:
 - **Runtime**: host, OS, node, model, repo root (when detected), thinking level (one line).
 - **Reasoning**: current visibility level + /reasoning toggle hint.
 
+The Tooling section also includes runtime guidance for long-running work:
+
+- use cron for future follow-up (`check back later`, reminders, recurring work)
+  instead of `exec` sleep loops, `yieldMs` delay tricks, or repeated `process`
+  polling
+- use `exec` / `process` only for commands that start now and continue running
+  in the background
+- when automatic completion wake is enabled, start the command once and rely on
+  the push-based wake path when it emits output or fails
+- use `process` for logs, status, input, or intervention when you need to
+  inspect a running command
+- if the task is larger, prefer `sessions_spawn`; sub-agent completion is
+  push-based and auto-announces back to the requester
+- do not poll `subagents list` / `sessions_list` in a loop just to wait for
+  completion
+
 Safety guardrails in the system prompt are advisory. They guide model behavior but do not enforce policy. Use tool policy, exec approvals, sandboxing, and channel allowlists for hard enforcement; operators can disable these by design.
 
+On channels with native approval cards/buttons, the runtime prompt now tells the
+agent to rely on that native approval UI first. It should only include a manual
+`/approve` command when the tool result says chat approvals are unavailable or
+manual approval is the only path.
+
 ## Prompt modes
 
 OpenClaw can render smaller system prompts for sub-agents. The runtime sets a
@@ -96,7 +122,8 @@ user timezone is known. To keep the prompt cache-stable, it now only includes
 the **time zone** (no dynamic clock or time format).
 
 Use `session_status` when the agent needs the current time; the status card
-includes a timestamp line.
+includes a timestamp line. The same tool can optionally set a per-session model
+override (`model=default` clears it).
 
 Configure with:
 
@@ -134,6 +161,6 @@ This keeps the base prompt small while still enabling targeted skill usage.
 When available, the system prompt includes a **Documentation** section that points to the
 local OpenClaw docs directory (either `docs/` in the repo workspace or the bundled npm
 package docs) and also notes the public mirror, source repo, community Discord, and
-ClawHub ([https://clawhub.com](https://clawhub.com)) for skills discovery. The prompt instructs the model to consult local docs first
+ClawHub ([https://clawhub.ai](https://clawhub.ai)) for skills discovery. The prompt instructs the model to consult local 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).

docs/concepts/typebox.md

@@ -42,22 +42,25 @@ Client                    Gateway
 
 Common methods + events:
 
-| Category  | Examples                                                  | Notes                              |
-| --------- | --------------------------------------------------------- | ---------------------------------- |
-| Core      | `connect`, `health`, `status`                             | `connect` must be first            |
-| Messaging | `send`, `poll`, `agent`, `agent.wait`                     | side-effects need `idempotencyKey` |
-| Chat      | `chat.history`, `chat.send`, `chat.abort`, `chat.inject`  | WebChat uses these                 |
-| Sessions  | `sessions.list`, `sessions.patch`, `sessions.delete`      | session admin                      |
-| Nodes     | `node.list`, `node.invoke`, `node.pair.*`                 | Gateway WS + node actions          |
-| Events    | `tick`, `presence`, `agent`, `chat`, `health`, `shutdown` | server push                        |
+| Category   | Examples                                                   | Notes                              |
+| ---------- | ---------------------------------------------------------- | ---------------------------------- |
+| Core       | `connect`, `health`, `status`                              | `connect` must be first            |
+| Messaging  | `send`, `agent`, `agent.wait`, `system-event`, `logs.tail` | side-effects need `idempotencyKey` |
+| Chat       | `chat.history`, `chat.send`, `chat.abort`                  | WebChat uses these                 |
+| Sessions   | `sessions.list`, `sessions.patch`, `sessions.delete`       | session admin                      |
+| Automation | `wake`, `cron.list`, `cron.run`, `cron.runs`               | wake + cron control                |
+| Nodes      | `node.list`, `node.invoke`, `node.pair.*`                  | Gateway WS + node actions          |
+| Events     | `tick`, `presence`, `agent`, `chat`, `health`, `shutdown`  | server push                        |
 
-Authoritative list lives in `src/gateway/server.ts` (`METHODS`, `EVENTS`).
+Authoritative advertised **discovery** inventory lives in
+`src/gateway/server-methods-list.ts` (`listGatewayMethods`, `GATEWAY_EVENTS`).
 
 ## Where the schemas live
 
 - Source: `src/gateway/protocol/schema.ts`
 - Runtime validators (AJV): `src/gateway/protocol/index.ts`
-- Server handshake + method dispatch: `src/gateway/server.ts`
+- Advertised feature/discovery registry: `src/gateway/server-methods-list.ts`
+- Server handshake + method dispatch: `src/gateway/server.impl.ts`
 - Node client: `src/gateway/client.ts`
 - Generated JSON Schema: `dist/protocol.schema.json`
 - Generated Swift models: `apps/macos/Sources/OpenClawProtocol/GatewayModels.swift`
@@ -77,8 +80,13 @@ Authoritative list lives in `src/gateway/server.ts` (`METHODS`, `EVENTS`).
   accepts a `connect` request whose params match `ConnectParams`.
 - **Client side**: the JS client validates event and response frames before
   using them.
-- **Method surface**: the Gateway advertises the supported `methods` and
-  `events` in `hello-ok`.
+- **Feature discovery**: the Gateway sends a conservative `features.methods`
+  and `features.events` list in `hello-ok` from `listGatewayMethods()` and
+  `GATEWAY_EVENTS`.
+- That discovery list is not a generated dump of every callable helper in
+  `coreGatewayHandlers`; some helper RPCs are implemented in
+  `src/gateway/server-methods/*.ts` without being enumerated in the advertised
+  feature list.
 
 ## Example frames
 
@@ -90,8 +98,8 @@ Connect (first message):
   "id": "c1",
   "method": "connect",
   "params": {
-    "minProtocol": 2,
-    "maxProtocol": 2,
+    "minProtocol": 3,
+    "maxProtocol": 3,
     "client": {
       "id": "openclaw-macos",
       "displayName": "macos",
@@ -113,7 +121,7 @@ Hello-ok response:
   "ok": true,
   "payload": {
     "type": "hello-ok",
-    "protocol": 2,
+    "protocol": 3,
     "server": { "version": "dev", "connId": "ws-1" },
     "features": { "methods": ["health"], "events": ["tick"] },
     "snapshot": {
@@ -239,7 +247,12 @@ export const systemHandlers: GatewayRequestHandlers = {
 ```
 
 Register it in `src/gateway/server-methods.ts` (already merges `systemHandlers`),
-then add `"system.echo"` to `METHODS` in `src/gateway/server.ts`.
+then add `"system.echo"` to `listGatewayMethods` input in
+`src/gateway/server-methods-list.ts`.
+
+If the method is callable by operator or node clients, also classify it in
+`src/gateway/method-scopes.ts` so scope enforcement and `hello-ok` feature
+advertising stay aligned.
 
 4. **Regenerate**
 
@@ -287,5 +300,8 @@ published raw file is typically available at:
 ## When you change schemas
 
 1. Update the TypeBox schemas.
-2. Run `pnpm protocol:check`.
-3. Commit the regenerated schema + Swift models.
+2. Register the method/event in `src/gateway/server-methods-list.ts`.
+3. Update `src/gateway/method-scopes.ts` when the new RPC needs operator or
+   node scope classification.
+4. Run `pnpm protocol:check`.
+5. Commit the regenerated schema + Swift models.

docs/concepts/typing-indicators.md

@@ -59,8 +59,9 @@ You can override mode or cadence per session:
 
 ## Notes
 
-- `message` mode won’t show typing for silent-only replies (e.g. the `NO_REPLY`
-  token used to suppress output).
+- `message` mode won’t show typing for silent-only replies when the whole
+  payload is the exact silent token (for example `NO_REPLY` / `no_reply`,
+  matched case-insensitively).
 - `thinking` only fires if the run streams reasoning (`reasoningLevel: "stream"`).
   If the model doesn’t emit reasoning deltas, typing won’t start.
 - Heartbeats never show typing, regardless of mode.

docs/concepts/usage-tracking.md

@@ -12,10 +12,17 @@ title: "Usage Tracking"
 
 - Pulls provider usage/quota directly from their usage endpoints.
 - No estimated costs; only the provider-reported windows.
+- Human-readable status output is normalized to `X% left`, even when an
+  upstream API reports consumed quota, remaining quota, or only raw counts.
+- Session-level `/status` and `session_status` can fall back to the latest
+  transcript usage entry when the live session snapshot is sparse. That
+  fallback fills missing token/cache counters, can recover the active runtime
+  model label, and prefers the larger prompt-oriented total when session
+  metadata is missing or smaller. Existing nonzero live values still win.
 
 ## Where it shows up
 
-- `/status` in chats: emoji‑rich status card with session tokens + estimated cost (API key only). Provider usage shows for the **current model provider** when available.
+- `/status` in chats: emoji‑rich status card with session tokens + estimated cost (API key only). Provider usage shows for the **current model provider** when available as a normalized `X% left` window.
 - `/usage off|tokens|full` in chats: per-response usage footer (OAuth shows tokens only).
 - `/usage cost` in chats: local cost summary aggregated from OpenClaw session logs.
 - CLI: `openclaw status --usage` prints a full per-provider breakdown.
@@ -27,9 +34,26 @@ title: "Usage Tracking"
 - **Anthropic (Claude)**: OAuth tokens in auth profiles.
 - **GitHub Copilot**: OAuth tokens in auth profiles.
 - **Gemini CLI**: OAuth tokens in auth profiles.
-- **Antigravity**: OAuth tokens in auth profiles.
+  - JSON usage falls back to `stats`; `stats.cached` is normalized into
+    `cacheRead`.
 - **OpenAI Codex**: OAuth tokens in auth profiles (accountId used when present).
-- **MiniMax**: API key (coding plan key; `MINIMAX_CODE_PLAN_KEY` or `MINIMAX_API_KEY`); uses the 5‑hour coding plan window.
+- **MiniMax**: API key or MiniMax OAuth auth profile. OpenClaw treats
+  `minimax`, `minimax-cn`, and `minimax-portal` as the same MiniMax quota
+  surface, prefers stored MiniMax OAuth when present, and otherwise falls back
+  to `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, or `MINIMAX_API_KEY`.
+  MiniMax's raw `usage_percent` / `usagePercent` fields mean **remaining**
+  quota, so OpenClaw inverts them before display; count-based fields win when
+  present.
+  - Coding-plan window labels come from provider hours/minutes fields when
+    present, then fall back to the `start_time` / `end_time` span.
+  - If the coding-plan endpoint returns `model_remains`, OpenClaw prefers the
+    chat-model entry, derives the window label from timestamps when explicit
+    `window_hours` / `window_minutes` fields are absent, and includes the model
+    name in the plan label.
+- **Xiaomi MiMo**: API key via env/config/auth store (`XIAOMI_API_KEY`).
 - **z.ai**: API key via env/config/auth store.
 
-Usage is hidden if no matching OAuth/API credentials exist.
+Usage is hidden when no usable provider usage auth can be resolved. Providers
+can supply plugin-specific usage auth logic; otherwise OpenClaw falls back to
+matching OAuth/API-key credentials from auth profiles, environment variables,
+or config.

docs/docs.json

@@ -54,7 +54,7 @@
   "redirects": [
     {
       "source": "/providers/modelstudio",
-      "destination": "/providers/qwen_modelstudio"
+      "destination": "/providers/qwen"
     },
     {
       "source": "/platforms/oracle",

docs/gateway/authentication.md

@@ -61,12 +61,15 @@ See [Help](/help) for details on env inheritance (`env.shellEnv`,
 
 ## Anthropic: legacy token compatibility
 
-Existing Anthropic token profiles are still honored at runtime if they are
-already configured, but OpenClaw no longer offers Anthropic setup-token auth
-for new setup via onboarding or `models auth` commands.
+Anthropic setup-token auth is still available in OpenClaw as a
+legacy/manual path. Anthropic's public Claude Code docs still cover direct
+Claude Code terminal use under Claude plans, but Anthropic separately told
+OpenClaw users that the **OpenClaw** Claude-login path counts as third-party
+harness usage and requires **Extra Usage** billed separately from the
+subscription.
 
-For new setup, use an Anthropic API key or migrate to Claude CLI on the gateway
-host.
+For the clearest setup path, use an Anthropic API key or migrate to Claude CLI
+on the gateway host.
 
 Manual token entry (any provider; writes `auth-profiles.json` + updates config):
 
@@ -86,6 +89,22 @@ Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
 openclaw models status --check
 ```
 
+Live auth probes:
+
+```bash
+openclaw models status --probe
+```
+
+Notes:
+
+- Probe rows can come from auth profiles, env credentials, or `models.json`.
+- If explicit `auth.order.<provider>` omits a stored profile, probe reports
+  `excluded_by_auth_order` for that profile instead of trying it.
+- If auth exists but OpenClaw cannot resolve a probeable model candidate for
+  that provider, probe reports `status: no_model`.
+- Rate-limit cooldowns can be model-scoped. A profile cooling down for one
+  model can still be usable for a sibling model on the same provider.
+
 Optional ops scripts (systemd/Termux) are documented here:
 [Auth monitoring scripts](/help/scripts#auth-monitoring-scripts)
 
@@ -121,8 +140,9 @@ Onboarding shortcut:
 openclaw onboard --auth-choice anthropic-cli
 ```
 
-Interactive `openclaw onboard` and `openclaw configure` prefer Claude CLI for
-Anthropic and no longer offer setup-token as a new setup path.
+Interactive `openclaw onboard` and `openclaw configure` still prefer Claude CLI
+for Anthropic, but Anthropic setup-token is available again as a
+legacy/manual path and should be used with the Extra Usage billing expectation.
 
 ## Checking model auth status
 
@@ -144,7 +164,9 @@ hits a provider rate limit.
 - Google providers also include `GOOGLE_API_KEY` as an additional fallback.
 - The same key list is deduplicated before use.
 - OpenClaw retries with the next key only for rate-limit errors (for example
-  `429`, `rate_limit`, `quota`, `resource exhausted`).
+  `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent
+requests`, `ThrottlingException`, `concurrency limit reached`, or
+  `workers_ai ... quota limit exceeded`).
 - Non-rate-limit errors are not retried with alternate keys.
 - If all keys fail, the final error from the last attempt is returned.
 
@@ -167,6 +189,10 @@ openclaw models auth order clear --provider anthropic
 ```
 
 Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
+When you debug order issues, `openclaw models status --probe` shows omitted
+stored profiles as `excluded_by_auth_order` instead of silently skipping them.
+When you debug cooldown issues, remember that rate-limit cooldowns can be tied
+to one model id rather than the whole provider profile.
 
 ## Troubleshooting
 

docs/gateway/background-process.md

@@ -18,7 +18,7 @@ Key parameters:
 - `yieldMs` (default 10000): auto‑background after this delay
 - `background` (bool): background immediately
 - `timeout` (seconds, default 1800): kill the process after this timeout
-- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- `elevated` (bool): run outside the sandbox if elevated mode is enabled/allowed (`gateway` by default, or `node` when the exec target is `node`)
 - Need a real TTY? Set `pty: true`.
 - `workdir`, `env`
 
@@ -29,6 +29,13 @@ Behavior:
 - Output is kept in memory until the session is polled or cleared.
 - If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
 - Spawned exec commands receive `OPENCLAW_SHELL=exec` for context-aware shell/profile rules.
+- For long-running work that starts now, start it once and rely on automatic
+  completion wake when it is enabled and the command emits output or fails.
+- If automatic completion wake is unavailable, or you need quiet-success
+  confirmation for a command that exited cleanly without output, use `process`
+  to confirm completion.
+- Do not emulate reminders or delayed follow-ups with `sleep` loops or repeated
+  polling; use cron for future work.
 
 ## Child process bridging
 
@@ -57,6 +64,9 @@ Actions:
 - `poll`: drain new output for a session (also reports exit status)
 - `log`: read the aggregated output (supports `offset` + `limit`)
 - `write`: send stdin (`data`, optional `eof`)
+- `send-keys`: send explicit key tokens or bytes to a PTY-backed session
+- `submit`: send Enter / carriage return to a PTY-backed session
+- `paste`: send literal text, optionally wrapped in bracketed paste mode
 - `kill`: terminate a background session
 - `clear`: remove a finished session from memory
 - `remove`: kill if running, otherwise clear if finished
@@ -67,10 +77,16 @@ Notes:
 - Sessions are lost on process restart (no disk persistence).
 - Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
 - `process` is scoped per agent; it only sees sessions started by that agent.
+- Use `poll` / `log` for status, logs, quiet-success confirmation, or
+  completion confirmation when automatic completion wake is unavailable.
+- Use `write` / `send-keys` / `submit` / `paste` / `kill` when you need input
+  or intervention.
 - `process list` includes a derived `name` (command verb + target) for quick scans.
 - `process log` uses line-based `offset`/`limit`.
 - When both `offset` and `limit` are omitted, it returns the last 200 lines and includes a paging hint.
 - When `offset` is provided and `limit` is omitted, it returns from `offset` to the end (not capped to 200).
+- Polling is for on-demand status, not wait-loop scheduling. If the work should
+  happen later, use cron instead.
 
 ## Examples
 
@@ -95,3 +111,21 @@ Send stdin:
 ```json
 { "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
 ```
+
+Send PTY keys:
+
+```json
+{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
+```
+
+Submit current line:
+
+```json
+{ "tool": "process", "action": "submit", "sessionId": "<id>" }
+```
+
+Paste literal text:
+
+```json
+{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
+```

docs/gateway/bonjour.md

@@ -8,9 +8,10 @@ title: "Bonjour Discovery"
 
 # Bonjour / mDNS discovery
 
-OpenClaw uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover
-an active Gateway (WebSocket endpoint). It is best‑effort and does **not** replace SSH or
-Tailnet-based connectivity.
+OpenClaw uses Bonjour (mDNS / DNS‑SD) to discover an active Gateway (WebSocket endpoint).
+Multicast `local.` browsing is a **LAN-only convenience**. For cross-network discovery, the
+same beacon can also be published through a configured wide-area DNS-SD domain. Discovery is
+still best-effort and does **not** replace SSH or Tailnet-based connectivity.
 
 ## Wide-area Bonjour (Unicast DNS-SD) over Tailscale
 
@@ -63,7 +64,7 @@ In the Tailscale admin console:
 - Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
 - Add split DNS so your discovery domain uses that nameserver.
 
-Once clients accept tailnet DNS, iOS nodes can browse
+Once clients accept tailnet DNS, iOS nodes and CLI discovery can browse
 `_openclaw-gw._tcp` in your discovery domain without multicast.
 
 ### Gateway listener security (recommended)
@@ -95,15 +96,16 @@ The Gateway advertises small non‑secret hints to make UI flows convenient:
 - `gatewayTls=1` (only when TLS is enabled)
 - `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
 - `canvasPort=<port>` (only when the canvas host is enabled; currently the same as `gatewayPort`)
-- `sshPort=<port>` (defaults to 22 when not overridden)
 - `transport=gateway`
-- `cliPath=<path>` (optional; absolute path to a runnable `openclaw` entrypoint)
 - `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
+- `sshPort=<port>` (mDNS full mode only; wide-area DNS-SD may omit it)
+- `cliPath=<path>` (mDNS full mode only; wide-area DNS-SD still writes it as a remote-install hint)
 
 Security notes:
 
 - Bonjour/mDNS TXT records are **unauthenticated**. Clients must not treat TXT as authoritative routing.
 - Clients should route using the resolved service endpoint (SRV + A/AAAA). Treat `lanHost`, `tailnetDns`, `gatewayPort`, and `gatewayTlsSha256` as hints only.
+- SSH auto-targeting should likewise use the resolved service host, not TXT-only hints.
 - TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin.
 - iOS/Android nodes should treat discovery-based direct connects as **TLS-only** and require explicit user confirmation before trusting a first-time fingerprint.
 
@@ -167,7 +169,7 @@ sequences (e.g. spaces become `\032`).
 
 - `OPENCLAW_DISABLE_BONJOUR=1` disables advertising (legacy: `OPENCLAW_DISABLE_BONJOUR`).
 - `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
-- `OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (legacy: `OPENCLAW_SSH_PORT`).
+- `OPENCLAW_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `OPENCLAW_SSH_PORT`).
 - `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT (legacy: `OPENCLAW_TAILNET_DNS`).
 - `OPENCLAW_CLI_PATH` overrides the advertised CLI path (legacy: `OPENCLAW_CLI_PATH`).