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

.agents/skills/security-triage/SKILL.md

@@ -55,6 +55,8 @@ Check in this order:
    - Was it fixed before release?
 3. Exploit path
    - Does the report show a real boundary bypass, not just prompt injection, local same-user control, or helper-level semantics?
+   - If data only moves between trusted workspace-memory files called out in `SECURITY.md`, do not treat "injection markers" alone as a security bug.
+   - In that case, frame sanitization as optional hardening only if it preserves expected memory workflows.
 4. Functional tradeoff
    - If a hardening change would reduce intended user functionality, call that out before proposing it.
    - Prefer fixes that preserve user workflows over deny-by-default regressions unless the boundary demands it.
@@ -104,5 +106,6 @@ gh search prs --repo openclaw/openclaw --match title,body,comments -- "<terms>"
 - “fixed on main, unreleased” is usually not a close.
 - “needs attacker-controlled trusted local state first” is usually out of scope.
 - “same-host same-user process can already read/write local state” is usually out of scope.
+- “trusted workspace memory promotes/reindexes trusted workspace memory” is usually out of scope unless it crosses a documented boundary.
 - “helper function behaves differently than documented config semantics” is usually invalid.
 - If only the severity is wrong but the bug is real, keep it open and narrow the impact in the reply.

.dockerignore

@@ -33,6 +33,8 @@ node_modules
 **/.next
 coverage
 **/coverage
+docs/.generated
+**/.generated
 *.log
 tmp
 **/tmp

.github/actions/setup-node-env/action.yml

@@ -14,7 +14,7 @@ inputs:
   pnpm-version:
     description: pnpm version for corepack.
     required: false
-    default: "10.23.0"
+    default: "10.32.1"
   install-bun:
     description: Whether to install Bun alongside Node.
     required: false

.github/actions/setup-pnpm-store-cache/action.yml

@@ -4,7 +4,7 @@ inputs:
   pnpm-version:
     description: pnpm version to activate via corepack.
     required: false
-    default: "10.23.0"
+    default: "10.32.1"
   cache-key-suffix:
     description: Suffix appended to the cache key.
     required: false

.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/pull_request_template.md

@@ -35,19 +35,17 @@ If this PR fixes a plugin beta-release blocker, title it `fix(<plugin-id>): beta
 - Related #
 - [ ] This PR fixes a bug or regression
 
-## Root Cause / Regression History (if applicable)
+## Root Cause (if applicable)
 
 For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write `N/A`. If the cause is unclear, write `Unknown`.
 
 - Root cause:
 - Missing detection / guardrail:
-- Prior context (`git blame`, prior PR, issue, or refactor if known):
-- Why this regressed now:
-- If unknown, what was ruled out:
+- Contributing context (if known):
 
 ## Regression Test Plan (if applicable)
 
-For bug fixes or regressions, name the smallest reliable test coverage that should have caught this. Otherwise write `N/A`.
+For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write `N/A`.
 
 - Coverage level that should have caught this:
   - [ ] Unit test

.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,

.github/workflows/ci.yml

@@ -17,8 +17,8 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
 
 jobs:
-  # Preflight: establish routing truth and planner-owned matrices once, then let
-  # real work fan out from a single source of truth.
+  # Preflight: establish routing truth and job matrices once, then let real
+  # work fan out from a single source of truth.
   preflight:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: blacksmith-16vcpu-ubuntu-2404
@@ -36,7 +36,8 @@ jobs:
       changed_extensions_matrix: ${{ steps.manifest.outputs.changed_extensions_matrix }}
       run_build_artifacts: ${{ steps.manifest.outputs.run_build_artifacts }}
       run_checks_fast: ${{ steps.manifest.outputs.run_checks_fast }}
-      checks_fast_matrix: ${{ steps.manifest.outputs.checks_fast_matrix }}
+      checks_fast_core_matrix: ${{ steps.manifest.outputs.checks_fast_core_matrix }}
+      checks_fast_extensions_matrix: ${{ steps.manifest.outputs.checks_fast_extensions_matrix }}
       run_checks: ${{ steps.manifest.outputs.run_checks }}
       checks_matrix: ${{ steps.manifest.outputs.checks_matrix }}
       run_extension_fast: ${{ steps.manifest.outputs.run_extension_fast }}
@@ -103,7 +104,7 @@ jobs:
         run: |
           node --input-type=module <<'EOF'
           import { appendFileSync } from "node:fs";
-          import { listChangedExtensionIds } from "./scripts/test-extension.mjs";
+          import { listChangedExtensionIds } from "./scripts/lib/changed-extensions.mjs";
 
           const extensionIds = listChangedExtensionIds({
             base: process.env.BASE_SHA,
@@ -129,7 +130,150 @@ jobs:
           OPENCLAW_CI_RUN_SKILLS_PYTHON: ${{ steps.changed_scope.outputs.run_skills_python || 'false' }}
           OPENCLAW_CI_HAS_CHANGED_EXTENSIONS: ${{ steps.changed_extensions.outputs.has_changed_extensions || 'false' }}
           OPENCLAW_CI_CHANGED_EXTENSIONS_MATRIX: ${{ steps.changed_extensions.outputs.changed_extensions_matrix || '{"include":[]}' }}
-        run: node scripts/ci-write-manifest-outputs.mjs --workflow ci
+        run: |
+          node --input-type=module <<'EOF'
+          import { appendFileSync } from "node:fs";
+          import {
+            createExtensionTestShards,
+            DEFAULT_EXTENSION_TEST_SHARD_COUNT,
+          } from "./scripts/lib/extension-test-plan.mjs";
+
+          const parseBoolean = (value, fallback = false) => {
+            if (value === undefined) return fallback;
+            const normalized = value.trim().toLowerCase();
+            if (normalized === "true" || normalized === "1") return true;
+            if (normalized === "false" || normalized === "0" || normalized === "") return false;
+            return fallback;
+          };
+
+          const parseJson = (value, fallback) => {
+            try {
+              return value ? JSON.parse(value) : fallback;
+            } catch {
+              return fallback;
+            }
+          };
+
+          const createMatrix = (include) => ({ include });
+          const outputPath = process.env.GITHUB_OUTPUT;
+          const eventName = process.env.GITHUB_EVENT_NAME ?? "pull_request";
+          const isPush = eventName === "push";
+          const docsOnly = parseBoolean(process.env.OPENCLAW_CI_DOCS_ONLY);
+          const docsChanged = parseBoolean(process.env.OPENCLAW_CI_DOCS_CHANGED);
+          const runNode = parseBoolean(process.env.OPENCLAW_CI_RUN_NODE) && !docsOnly;
+          const runMacos = parseBoolean(process.env.OPENCLAW_CI_RUN_MACOS) && !docsOnly;
+          const runAndroid = parseBoolean(process.env.OPENCLAW_CI_RUN_ANDROID) && !docsOnly;
+          const runWindows = parseBoolean(process.env.OPENCLAW_CI_RUN_WINDOWS) && !docsOnly;
+          const runSkillsPython = parseBoolean(process.env.OPENCLAW_CI_RUN_SKILLS_PYTHON) && !docsOnly;
+          const hasChangedExtensions =
+            parseBoolean(process.env.OPENCLAW_CI_HAS_CHANGED_EXTENSIONS) && !docsOnly;
+          const changedExtensionsMatrix = hasChangedExtensions
+            ? parseJson(process.env.OPENCLAW_CI_CHANGED_EXTENSIONS_MATRIX, { include: [] })
+            : { include: [] };
+          const extensionShardMatrix = createMatrix(
+            runNode
+              ? createExtensionTestShards({
+                  shardCount: DEFAULT_EXTENSION_TEST_SHARD_COUNT,
+                }).map((shard) => ({
+                  check_name: shard.checkName,
+                  extensions_csv: shard.extensionIds.join(","),
+                  shard_index: shard.index + 1,
+                  task: "extensions-batch",
+                }))
+              : [],
+          );
+
+          const manifest = {
+            docs_only: docsOnly,
+            docs_changed: docsChanged,
+            run_node: runNode,
+            run_macos: runMacos,
+            run_android: runAndroid,
+            run_skills_python: runSkillsPython,
+            run_windows: runWindows,
+            has_changed_extensions: hasChangedExtensions,
+            changed_extensions_matrix: changedExtensionsMatrix,
+            run_build_artifacts: runNode,
+            run_checks_fast: runNode,
+            checks_fast_core_matrix: createMatrix(
+              runNode
+                ? [
+                    { check_name: "checks-fast-bundled", runtime: "node", task: "bundled" },
+                    {
+                      check_name: "checks-fast-contracts-protocol",
+                      runtime: "node",
+                      task: "contracts-protocol",
+                    },
+                  ]
+                : [],
+            ),
+            checks_fast_extensions_matrix: extensionShardMatrix,
+            run_checks: runNode,
+            checks_matrix: createMatrix(
+              runNode
+                ? [
+                    { check_name: "checks-node-test", runtime: "node", task: "test" },
+                    { check_name: "checks-node-channels", runtime: "node", task: "channels" },
+                    ...(isPush
+                      ? [
+                          {
+                            check_name: "checks-node-compat-node22",
+                            runtime: "node",
+                            task: "compat-node22",
+                            node_version: "22.x",
+                            cache_key_suffix: "node22",
+                          },
+                        ]
+                      : []),
+                  ]
+                : [],
+            ),
+            run_extension_fast: hasChangedExtensions,
+            extension_fast_matrix: createMatrix(
+              hasChangedExtensions
+                ? (changedExtensionsMatrix.include ?? []).map((entry) => ({
+                    check_name: `extension-fast-${entry.extension}`,
+                    extension: entry.extension,
+                  }))
+                : [],
+            ),
+            run_check: runNode,
+            run_check_additional: runNode,
+            run_build_smoke: runNode,
+            run_check_docs: docsChanged,
+            run_skills_python_job: runSkillsPython,
+            run_checks_windows: runWindows,
+            checks_windows_matrix: createMatrix(
+              runWindows
+                ? [{ check_name: "checks-windows-node-test", runtime: "node", task: "test" }]
+                : [],
+            ),
+            run_macos_node: runMacos,
+            macos_node_matrix: createMatrix(
+              runMacos ? [{ check_name: "macos-node", runtime: "node", task: "test" }] : [],
+            ),
+            run_macos_swift: runMacos,
+            run_android_job: runAndroid,
+            android_matrix: createMatrix(
+              runAndroid
+                ? [
+                    { check_name: "android-test-play", task: "test-play" },
+                    { check_name: "android-test-third-party", task: "test-third-party" },
+                    { check_name: "android-build-play", task: "build-play" },
+                    { check_name: "android-build-third-party", task: "build-third-party" },
+                  ]
+                : [],
+            ),
+          };
+
+          for (const [key, value] of Object.entries(manifest)) {
+            appendFileSync(
+              outputPath,
+              `${key}=${typeof value === "string" ? value : JSON.stringify(value)}\n`,
+              "utf8",
+            );
+          }
+          EOF
 
   # Run the fast security/SCM checks in parallel with scope detection so the
   # main Node jobs do not have to wait for Python/pre-commit setup.
@@ -277,7 +421,7 @@ jobs:
           include-hidden-files: true
           retention-days: 1
 
-  checks-fast:
+  checks-fast-core:
     name: ${{ matrix.check_name }}
     needs: [preflight]
     if: needs.preflight.outputs.run_checks_fast == 'true'
@@ -285,7 +429,7 @@ jobs:
     timeout-minutes: 60
     strategy:
       fail-fast: false
-      matrix: ${{ fromJson(needs.preflight.outputs.checks_fast_matrix) }}
+      matrix: ${{ fromJson(needs.preflight.outputs.checks_fast_core_matrix) }}
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -302,18 +446,12 @@ jobs:
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         env:
           TASK: ${{ matrix.task }}
-          SHARD_COUNT: ${{ matrix.shard_count || '' }}
-          SHARD_INDEX: ${{ matrix.shard_index || '' }}
         shell: bash
         run: |
           set -euo pipefail
           case "$TASK" in
-            extensions)
-              if [ -n "$SHARD_COUNT" ] && [ -n "$SHARD_INDEX" ]; then
-                export OPENCLAW_TEST_SHARDS="$SHARD_COUNT"
-                export OPENCLAW_TEST_SHARD_INDEX="$SHARD_INDEX"
-              fi
-              pnpm test:extensions
+            bundled)
+              pnpm test:bundled
               ;;
             contracts|contracts-protocol)
               pnpm build
@@ -326,6 +464,49 @@ jobs:
               ;;
           esac
 
+  checks-fast-extensions-shard:
+    name: ${{ matrix.check_name }}
+    needs: [preflight]
+    if: needs.preflight.outputs.run_checks_fast == 'true'
+    runs-on: blacksmith-16vcpu-ubuntu-2404
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.preflight.outputs.checks_fast_extensions_matrix) }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          submodules: false
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          install-bun: "false"
+          use-sticky-disk: "false"
+
+      - name: Run extension shard
+        env:
+          OPENCLAW_EXTENSION_BATCH: ${{ matrix.extensions_csv }}
+        run: pnpm test:extensions:batch -- "$OPENCLAW_EXTENSION_BATCH"
+
+  checks-fast-extensions:
+    name: checks-fast-extensions
+    needs: [preflight, checks-fast-extensions-shard]
+    if: always() && needs.preflight.outputs.run_checks_fast == 'true'
+    runs-on: blacksmith-16vcpu-ubuntu-2404
+    timeout-minutes: 5
+    steps:
+      - name: Verify extension shards
+        env:
+          SHARD_RESULT: ${{ needs.checks-fast-extensions-shard.result }}
+        run: |
+          if [ "$SHARD_RESULT" != "success" ]; then
+            echo "Extension shard checks failed: $SHARD_RESULT" >&2
+            exit 1
+          fi
+
   checks:
     name: ${{ matrix.check_name }}
     needs: [preflight, build-artifacts]
@@ -360,20 +541,10 @@ jobs:
         if: (github.event_name != 'pull_request' || matrix.task != 'compat-node22') && matrix.runtime == 'node' && (matrix.task == 'test' || matrix.task == 'channels' || matrix.task == 'compat-node22')
         env:
           TASK: ${{ matrix.task }}
-          SHARD_COUNT: ${{ matrix.shard_count || '' }}
-          SHARD_INDEX: ${{ matrix.shard_index || '' }}
         run: |
-          # `pnpm test` runs `scripts/test-parallel.mjs`, which spawns multiple Node processes.
-          # Default heap limits have been too low on Linux CI (V8 OOM near 4GB).
-          echo "OPENCLAW_TEST_WORKERS=2" >> "$GITHUB_ENV"
-          echo "OPENCLAW_TEST_MAX_OLD_SPACE_SIZE_MB=6144" >> "$GITHUB_ENV"
+          echo "OPENCLAW_VITEST_MAX_WORKERS=2" >> "$GITHUB_ENV"
           if [ "$TASK" = "channels" ]; then
-            echo "OPENCLAW_TEST_WORKERS=1" >> "$GITHUB_ENV"
-            echo "OPENCLAW_TEST_ISOLATE=1" >> "$GITHUB_ENV"
-          fi
-          if [ -n "$SHARD_COUNT" ] && [ -n "$SHARD_INDEX" ]; then
-            echo "OPENCLAW_TEST_SHARDS=$SHARD_COUNT" >> "$GITHUB_ENV"
-            echo "OPENCLAW_TEST_SHARD_INDEX=$SHARD_INDEX" >> "$GITHUB_ENV"
+            echo "OPENCLAW_VITEST_MAX_WORKERS=1" >> "$GITHUB_ENV"
           fi
 
       - name: Download dist artifact
@@ -394,6 +565,7 @@ jobs:
         if: github.event_name != 'pull_request' || matrix.task != 'compat-node22'
         env:
           TASK: ${{ matrix.task }}
+          NODE_OPTIONS: --max-old-space-size=6144
         shell: bash
         run: |
           set -euo pipefail
@@ -735,8 +907,7 @@ jobs:
     env:
       NODE_OPTIONS: --max-old-space-size=6144
       # Keep total concurrency predictable on the 32 vCPU runner.
-      # Windows shard 2 has shown intermittent instability at 2 workers.
-      OPENCLAW_TEST_WORKERS: 1
+      OPENCLAW_VITEST_MAX_WORKERS: 1
     defaults:
       run:
         shell: bash
@@ -778,7 +949,7 @@ jobs:
       - name: Setup pnpm + cache store
         uses: ./.github/actions/setup-pnpm-store-cache
         with:
-          pnpm-version: "10.23.0"
+          pnpm-version: "10.32.1"
           cache-key-suffix: "node24"
           # Sticky disk mount currently retries/fails on every shard and adds ~50s
           # before install while still yielding zero pnpm store reuse.
@@ -809,15 +980,6 @@ jobs:
           # caches can skip repeated rebuild/download work on later shards/runs.
           pnpm install --frozen-lockfile --prefer-offline --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true --config.side-effects-cache=true || pnpm install --frozen-lockfile --prefer-offline --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true --config.side-effects-cache=true
 
-      - name: Configure test shard (Windows)
-        if: matrix.task == 'test'
-        env:
-          SHARD_COUNT: ${{ matrix.shard_count }}
-          SHARD_INDEX: ${{ matrix.shard_index }}
-        run: |
-          echo "OPENCLAW_TEST_SHARDS=$SHARD_COUNT" >> "$GITHUB_ENV"
-          echo "OPENCLAW_TEST_SHARD_INDEX=$SHARD_INDEX" >> "$GITHUB_ENV"
-
       - name: Download dist artifact
         if: matrix.task == 'test'
         uses: actions/download-artifact@v8
@@ -881,17 +1043,10 @@ jobs:
           name: canvas-a2ui-bundle
           path: src/canvas-host/a2ui/
 
-      - name: Configure test shard (macOS)
-        env:
-          SHARD_COUNT: ${{ matrix.shard_count }}
-          SHARD_INDEX: ${{ matrix.shard_index }}
-        run: |
-          echo "OPENCLAW_TEST_SHARDS=$SHARD_COUNT" >> "$GITHUB_ENV"
-          echo "OPENCLAW_TEST_SHARD_INDEX=$SHARD_INDEX" >> "$GITHUB_ENV"
-
       - name: TS tests (macOS)
         env:
           NODE_OPTIONS: --max-old-space-size=4096
+          OPENCLAW_VITEST_MAX_WORKERS: 2
           TASK: ${{ matrix.task }}
         shell: bash
         run: |

.github/workflows/install-smoke.yml

@@ -67,16 +67,18 @@ jobs:
         id: manifest
         env:
           OPENCLAW_CI_DOCS_ONLY: ${{ steps.docs_scope.outputs.docs_only }}
-          OPENCLAW_CI_DOCS_CHANGED: "false"
-          OPENCLAW_CI_RUN_NODE: "false"
-          OPENCLAW_CI_RUN_MACOS: "false"
-          OPENCLAW_CI_RUN_ANDROID: "false"
-          OPENCLAW_CI_RUN_WINDOWS: "false"
-          OPENCLAW_CI_RUN_SKILLS_PYTHON: "false"
-          OPENCLAW_CI_HAS_CHANGED_EXTENSIONS: "false"
-          OPENCLAW_CI_CHANGED_EXTENSIONS_MATRIX: '{"include":[]}'
           OPENCLAW_CI_RUN_CHANGED_SMOKE: ${{ steps.changed_scope.outputs.run_changed_smoke || 'false' }}
-        run: node scripts/ci-write-manifest-outputs.mjs --workflow install-smoke
+        run: |
+          docs_only="${OPENCLAW_CI_DOCS_ONLY:-false}"
+          run_changed_smoke="${OPENCLAW_CI_RUN_CHANGED_SMOKE:-false}"
+          run_install_smoke=false
+          if [ "$docs_only" != "true" ] && [ "$run_changed_smoke" = "true" ]; then
+            run_install_smoke=true
+          fi
+          {
+            echo "docs_only=$docs_only"
+            echo "run_install_smoke=$run_install_smoke"
+          } >> "$GITHUB_OUTPUT"
 
   install-smoke:
     needs: [preflight]

.github/workflows/macos-release.yml

@@ -20,7 +20,7 @@ concurrency:
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
   NODE_VERSION: "24.x"
-  PNPM_VERSION: "10.23.0"
+  PNPM_VERSION: "10.32.1"
 
 jobs:
   validate_macos_release_request:

.github/workflows/openclaw-npm-release.yml

@@ -37,7 +37,7 @@ concurrency:
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
   NODE_VERSION: "24.x"
-  PNPM_VERSION: "10.23.0"
+  PNPM_VERSION: "10.32.1"
 
 jobs:
   preflight_openclaw_npm:
@@ -129,6 +129,31 @@ jobs:
       - name: Verify release contents
         run: pnpm release:check
 
+      - name: Validate live cache credentials
+        if: ${{ github.ref == 'refs/heads/main' }}
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${OPENAI_API_KEY}" ]]; then
+            echo "Missing OPENAI_API_KEY secret for release live cache validation." >&2
+            exit 1
+          fi
+          if [[ -z "${ANTHROPIC_API_KEY}" ]]; then
+            echo "Missing ANTHROPIC_API_KEY secret for release live cache validation." >&2
+            exit 1
+          fi
+
+      - name: Verify live prompt cache floors
+        if: ${{ github.ref == 'refs/heads/main' }}
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENCLAW_LIVE_CACHE_TEST: "1"
+          OPENCLAW_LIVE_TEST: "1"
+        run: pnpm test:live:cache
+
       - name: Pack prepared npm tarball
         id: packed_tarball
         env:

.github/workflows/plugin-clawhub-release.yml

@@ -0,0 +1,276 @@
+name: Plugin ClawHub Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish_scope:
+        description: Publish the selected plugins or all ClawHub-publishable plugins from the workflow ref
+        required: true
+        default: selected
+        type: choice
+        options:
+          - selected
+          - all-publishable
+      plugins:
+        description: Comma-separated plugin package names to publish when publish_scope=selected
+        required: false
+        type: string
+
+concurrency:
+  group: plugin-clawhub-release-${{ github.sha }}
+  cancel-in-progress: false
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  NODE_VERSION: "24.x"
+  PNPM_VERSION: "10.32.1"
+  CLAWHUB_REGISTRY: "https://clawhub.ai"
+  CLAWHUB_REPOSITORY: "openclaw/clawhub"
+  # Pinned to a reviewed ClawHub commit so release behavior stays reproducible.
+  CLAWHUB_REF: "4af2bd50a71465683dbf8aa269af764b9d39bdf5"
+
+jobs:
+  preview_plugins_clawhub:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      ref_sha: ${{ steps.ref.outputs.sha }}
+      has_candidates: ${{ steps.plan.outputs.has_candidates }}
+      candidate_count: ${{ steps.plan.outputs.candidate_count }}
+      skipped_published_count: ${{ steps.plan.outputs.skipped_published_count }}
+      matrix: ${{ steps.plan.outputs.matrix }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+          install-bun: "false"
+          use-sticky-disk: "false"
+
+      - name: Resolve checked-out ref
+        id: ref
+        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Validate ref is on main
+        run: |
+          set -euo pipefail
+          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+          git merge-base --is-ancestor HEAD origin/main
+
+      - name: Validate publishable plugin metadata
+        env:
+          PUBLISH_SCOPE: ${{ github.event_name == 'workflow_dispatch' && inputs.publish_scope || '' }}
+          RELEASE_PLUGINS: ${{ github.event_name == 'workflow_dispatch' && inputs.plugins || '' }}
+          BASE_REF: ${{ github.event_name != 'workflow_dispatch' && github.event.before || '' }}
+          HEAD_REF: ${{ steps.ref.outputs.sha }}
+        run: |
+          set -euo pipefail
+          if [[ -n "${PUBLISH_SCOPE}" ]]; then
+            release_args=(--selection-mode "${PUBLISH_SCOPE}")
+            if [[ -n "${RELEASE_PLUGINS}" ]]; then
+              release_args+=(--plugins "${RELEASE_PLUGINS}")
+            fi
+            pnpm release:plugins:clawhub:check -- "${release_args[@]}"
+          elif [[ -n "${BASE_REF}" ]]; then
+            pnpm release:plugins:clawhub:check -- --base-ref "${BASE_REF}" --head-ref "${HEAD_REF}"
+          else
+            pnpm release:plugins:clawhub:check
+          fi
+
+      - name: Resolve plugin release plan
+        id: plan
+        env:
+          PUBLISH_SCOPE: ${{ github.event_name == 'workflow_dispatch' && inputs.publish_scope || '' }}
+          RELEASE_PLUGINS: ${{ github.event_name == 'workflow_dispatch' && inputs.plugins || '' }}
+          BASE_REF: ${{ github.event_name != 'workflow_dispatch' && github.event.before || '' }}
+          HEAD_REF: ${{ steps.ref.outputs.sha }}
+          CLAWHUB_REGISTRY: ${{ env.CLAWHUB_REGISTRY }}
+        run: |
+          set -euo pipefail
+          mkdir -p .local
+          if [[ -n "${PUBLISH_SCOPE}" ]]; then
+            plan_args=(--selection-mode "${PUBLISH_SCOPE}")
+            if [[ -n "${RELEASE_PLUGINS}" ]]; then
+              plan_args+=(--plugins "${RELEASE_PLUGINS}")
+            fi
+            node --import tsx scripts/plugin-clawhub-release-plan.ts "${plan_args[@]}" > .local/plugin-clawhub-release-plan.json
+          elif [[ -n "${BASE_REF}" ]]; then
+            node --import tsx scripts/plugin-clawhub-release-plan.ts --base-ref "${BASE_REF}" --head-ref "${HEAD_REF}" > .local/plugin-clawhub-release-plan.json
+          else
+            node --import tsx scripts/plugin-clawhub-release-plan.ts > .local/plugin-clawhub-release-plan.json
+          fi
+
+          cat .local/plugin-clawhub-release-plan.json
+
+          candidate_count="$(jq -r '.candidates | length' .local/plugin-clawhub-release-plan.json)"
+          skipped_published_count="$(jq -r '.skippedPublished | length' .local/plugin-clawhub-release-plan.json)"
+          has_candidates="false"
+          if [[ "${candidate_count}" != "0" ]]; then
+            has_candidates="true"
+          fi
+          matrix_json="$(jq -c '.candidates' .local/plugin-clawhub-release-plan.json)"
+
+          {
+            echo "candidate_count=${candidate_count}"
+            echo "skipped_published_count=${skipped_published_count}"
+            echo "has_candidates=${has_candidates}"
+            echo "matrix=${matrix_json}"
+          } >> "$GITHUB_OUTPUT"
+
+          echo "Plugin release candidates:"
+          jq -r '.candidates[]? | "- \(.packageName)@\(.version) [\(.publishTag)] from \(.packageDir)"' .local/plugin-clawhub-release-plan.json
+
+          echo "Already published / skipped:"
+          jq -r '.skippedPublished[]? | "- \(.packageName)@\(.version)"' .local/plugin-clawhub-release-plan.json
+
+      - name: Fail manual publish when target versions already exist
+        if: github.event_name == 'workflow_dispatch' && inputs.publish_scope == 'selected' && steps.plan.outputs.skipped_published_count != '0'
+        run: |
+          echo "::error::One or more selected plugin versions already exist on ClawHub. Bump the version before running a real publish."
+          exit 1
+
+  preview_plugin_pack:
+    needs: preview_plugins_clawhub
+    if: needs.preview_plugins_clawhub.outputs.has_candidates == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        plugin: ${{ fromJson(needs.preview_plugins_clawhub.outputs.matrix) }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.preview_plugins_clawhub.outputs.ref_sha }}
+          fetch-depth: 1
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+          install-bun: "true"
+          use-sticky-disk: "false"
+          install-deps: "false"
+
+      - name: Checkout ClawHub CLI source
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ env.CLAWHUB_REPOSITORY }}
+          ref: ${{ env.CLAWHUB_REF }}
+          path: clawhub-source
+          fetch-depth: 1
+
+      - name: Install ClawHub CLI dependencies
+        working-directory: clawhub-source
+        run: bun install --frozen-lockfile
+
+      - name: Bootstrap ClawHub CLI
+        run: |
+          cat > "$RUNNER_TEMP/clawhub" <<'EOF'
+          #!/usr/bin/env bash
+          set -euo pipefail
+          exec bun "$GITHUB_WORKSPACE/clawhub-source/packages/clawhub/src/cli.ts" "$@"
+          EOF
+          chmod +x "$RUNNER_TEMP/clawhub"
+          echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
+
+      - name: Preview publish command
+        env:
+          CLAWHUB_REGISTRY: ${{ env.CLAWHUB_REGISTRY }}
+          SOURCE_REPO: ${{ github.repository }}
+          SOURCE_COMMIT: ${{ needs.preview_plugins_clawhub.outputs.ref_sha }}
+          SOURCE_REF: ${{ github.ref }}
+          PACKAGE_TAG: ${{ matrix.plugin.publishTag }}
+          PACKAGE_DIR: ${{ matrix.plugin.packageDir }}
+        run: bash scripts/plugin-clawhub-publish.sh --dry-run "${PACKAGE_DIR}"
+
+  publish_plugins_clawhub:
+    needs: [preview_plugins_clawhub, preview_plugin_pack]
+    if: github.event_name == 'workflow_dispatch' && needs.preview_plugins_clawhub.outputs.has_candidates == 'true'
+    runs-on: ubuntu-latest
+    environment: clawhub-plugin-release
+    permissions:
+      contents: read
+      id-token: write
+    strategy:
+      fail-fast: false
+      matrix:
+        plugin: ${{ fromJson(needs.preview_plugins_clawhub.outputs.matrix) }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.preview_plugins_clawhub.outputs.ref_sha }}
+          fetch-depth: 1
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+          install-bun: "true"
+          use-sticky-disk: "false"
+          install-deps: "false"
+
+      - name: Checkout ClawHub CLI source
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ env.CLAWHUB_REPOSITORY }}
+          ref: ${{ env.CLAWHUB_REF }}
+          path: clawhub-source
+          fetch-depth: 1
+
+      - name: Install ClawHub CLI dependencies
+        working-directory: clawhub-source
+        run: bun install --frozen-lockfile
+
+      - name: Bootstrap ClawHub CLI
+        run: |
+          cat > "$RUNNER_TEMP/clawhub" <<'EOF'
+          #!/usr/bin/env bash
+          set -euo pipefail
+          exec bun "$GITHUB_WORKSPACE/clawhub-source/packages/clawhub/src/cli.ts" "$@"
+          EOF
+          chmod +x "$RUNNER_TEMP/clawhub"
+          echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
+
+      - name: Ensure version is not already published
+        env:
+          PACKAGE_NAME: ${{ matrix.plugin.packageName }}
+          PACKAGE_VERSION: ${{ matrix.plugin.version }}
+          CLAWHUB_REGISTRY: ${{ env.CLAWHUB_REGISTRY }}
+        run: |
+          set -euo pipefail
+          encoded_name="$(node -e 'console.log(encodeURIComponent(process.env.PACKAGE_NAME ?? ""))')"
+          encoded_version="$(node -e 'console.log(encodeURIComponent(process.env.PACKAGE_VERSION ?? ""))')"
+          url="${CLAWHUB_REGISTRY%/}/api/v1/packages/${encoded_name}/versions/${encoded_version}"
+          status="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' "${url}")"
+          if [[ "${status}" =~ ^2 ]]; then
+            echo "${PACKAGE_NAME}@${PACKAGE_VERSION} is already published on ClawHub."
+            exit 1
+          fi
+          if [[ "${status}" != "404" ]]; then
+            echo "Unexpected ClawHub response (${status}) for ${PACKAGE_NAME}@${PACKAGE_VERSION}."
+            exit 1
+          fi
+
+      - name: Publish
+        env:
+          CLAWHUB_REGISTRY: ${{ env.CLAWHUB_REGISTRY }}
+          SOURCE_REPO: ${{ github.repository }}
+          SOURCE_COMMIT: ${{ needs.preview_plugins_clawhub.outputs.ref_sha }}
+          SOURCE_REF: ${{ github.ref }}
+          PACKAGE_TAG: ${{ matrix.plugin.publishTag }}
+          PACKAGE_DIR: ${{ matrix.plugin.packageDir }}
+        run: bash scripts/plugin-clawhub-publish.sh --publish "${PACKAGE_DIR}"

.github/workflows/plugin-npm-release.yml

@@ -38,7 +38,7 @@ concurrency:
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
   NODE_VERSION: "24.x"
-  PNPM_VERSION: "10.23.0"
+  PNPM_VERSION: "10.32.1"
 
 jobs:
   preview_plugins_npm:

.gitignore

@@ -4,7 +4,7 @@ node_modules
 docker-compose.override.yml
 docker-compose.extra.yml
 dist
-dist-runtime
+dist-runtime/
 pnpm-lock.yaml
 bun.lock
 bun.lockb
@@ -136,8 +136,16 @@ ui/src/ui/views/__screenshots__
 ui/.vitest-attachments
 docs/superpowers
 
+# Generated docs baseline artifacts (locally generated, only hashes tracked)
+docs/.generated/*.json
+docs/.generated/*.jsonl
+
 # Deprecated changelog fragment workflow
 changelog/fragments/
 
 # Local scratch workspace
 .tmp/
+test/fixtures/openclaw-vitest-unit-report.json
+analysis/
+.artifacts/qa-e2e/
+extensions/qa-lab/web/dist/

AGENTS.md

@@ -55,6 +55,11 @@
   - Public docs: `docs/gateway/protocol.md`, `docs/gateway/bridge-protocol.md`, `docs/concepts/architecture.md`
   - Definition files: `src/gateway/protocol/schema.ts`, `src/gateway/protocol/schema/*.ts`, `src/gateway/protocol/index.ts`
   - Rule: protocol changes are contract changes. Prefer additive evolution; incompatible changes require explicit versioning, docs, and client/codegen follow-through.
+- Config contract boundary:
+  - Canonical public config lives in exported config types, zod/schema surfaces, schema help/labels, generated config metadata, config baselines, and any user-facing gateway/config payloads. Keep those surfaces aligned.
+  - When a legacy config key is retired from the public contract, remove it from every public config surface above. Keep backward compatibility only through raw-config migration/doctor seams unless explicit product policy says otherwise.
+  - Do not reintroduce removed legacy aliases into public types/schema/help/baselines “for convenience”. If old configs still need to load, handle that in `legacy.migrations.*`, config ingest, or `openclaw doctor --fix`.
+  - `hooks.internal.entries` is the canonical public hook config model. `hooks.internal.handlers` is compatibility-only input and must not be re-exposed in public schema/help/baseline surfaces.
 - Bundled plugin contract boundary:
   - Public docs: `docs/plugins/architecture.md`, `docs/plugins/manifest.md`, `docs/plugins/sdk-overview.md`
 - Definition files: `src/plugins/contracts/registry.ts`, `src/plugins/types.ts`, `src/plugins/public-artifacts.ts`
@@ -125,10 +130,10 @@
 - Formatting gate: the pre-commit hook runs `pnpm format` before `pnpm check`. If you want a formatting-only preflight locally, run `pnpm format` explicitly.
 - If you need a fast commit loop, `FAST_COMMIT=1 git commit ...` skips the hook’s repo-wide `pnpm format` and `pnpm check`; use that only when you are deliberately covering the touched surface some other way.
 - Tests: `pnpm test` (vitest); coverage: `pnpm test:coverage`
-- Generated baseline artifacts live together under `docs/.generated/`.
+- Generated baseline drift detection uses SHA-256 hash files under `docs/.generated/` (`.sha256` files tracked in git; full JSON baselines are gitignored, generated locally for inspection).
 - Config schema drift uses `pnpm config:docs:gen` / `pnpm config:docs:check`.
 - Plugin SDK API drift uses `pnpm plugin-sdk:api:gen` / `pnpm plugin-sdk:api:check`.
-- If you change config schema/help or the public Plugin SDK surface, update the matching baseline artifact and keep the two drift-check flows adjacent in scripts/workflows/docs guidance rather than inventing a third pattern.
+- If you change config schema/help or the public Plugin SDK surface, run the matching gen command and commit the updated `.sha256` hash file. Keep the two drift-check flows adjacent in scripts/workflows/docs guidance rather than inventing a third pattern.
 - For narrowly scoped changes, prefer narrowly scoped tests that directly validate the touched behavior. If no meaningful scoped test exists, say so explicitly and use the next most direct validation available.
 - Verification modes for work on `main`:
   - Default mode: `main` is relatively stable. Count pre-commit hook coverage when it already verified the current tree, avoid rerunning the exact same checks just for ceremony, and prefer keeping CI/main green before landing.
@@ -140,6 +145,14 @@
 - For narrowly scoped changes, if unrelated failures already exist on latest `origin/main`, state that clearly, report the scoped tests you ran, and ask before broadening scope into unrelated fixes or landing despite those failures.
 - Do not use scoped tests as permission to ignore plausibly related failures.
 
+## Prompt Cache Stability
+
+- Treat prompt-cache stability as correctness/perf-critical, not cosmetic.
+- Any code that assembles model or tool payloads from maps, sets, registries, plugin lists, MCP catalogs, filesystem reads, or network results must make ordering deterministic before building the request.
+- Do not rewrite older transcript/history bytes on every turn unless you intentionally want to invalidate the cached prefix. Legacy cleanup, pruning, normalization, and migration logic should preserve recent prompt bytes when possible.
+- If truncation or compaction is required, prefer mutating newest or tail content first so the cached prefix stays byte-identical for as long as possible.
+- For cache-sensitive changes, require a regression test that proves turn-to-turn prefix stability or deterministic request assembly; helper-local tests alone are not enough.
+
 ## Coding Style & Naming Conventions
 
 - Language: TypeScript (ESM). Prefer strict typing; avoid `any`.
@@ -185,11 +198,16 @@
 - Test performance guardrail: inside an extension package, prefer a thin local seam (`./api.ts`, `./runtime-api.ts`, or a narrower local `*.runtime-api.ts`) over direct `openclaw/plugin-sdk/*` imports for internal production code. Keep local seams curated and lightweight; only reach for direct `plugin-sdk/*` imports when you are crossing a real package boundary or when no suitable local seam exists yet.
 - Test performance guardrail: keep expensive runtime fallback work such as snapshotting, migration, installs, or bootstrap behind dedicated `*.runtime.ts` boundaries so tests can mock the seam instead of accidentally invoking real work.
 - Test performance guardrail: for import-only/runtime-wrapper tests, keep the wrapper lazy. Do not eagerly load heavy verification/bootstrap/runtime modules at module top level if the exported function can import them on demand.
+- Test performance guardrail: prefer explicit mock factories over `importOriginal()` for broad modules. Reserve `importOriginal()` for narrow modules where partial-real behavior is genuinely needed.
+- Test performance guardrail: do not partial-mock broad `openclaw/plugin-sdk/*` barrels in hot tests. Add a plugin-local `*.runtime.ts` seam and mock that seam instead.
+- Test performance guardrail: when production code already accepts `deps`, callbacks, or runtime injection, use that seam in tests before adding module-level mocks.
+- Test performance guardrail: prefer narrow public SDK subpaths such as `models-provider-runtime`, `skill-commands-runtime`, and `reply-dispatch-runtime` over older broad helper barrels when both expose the needed helper.
+- Test performance guardrail: treat import-dominated test time as a boundary bug. Refactor the import surface before adding more cases to the slow file.
 - Agents MUST NOT modify baseline, inventory, ignore, snapshot, or expected-failure files to silence failing checks without explicit approval in this chat.
-- For targeted/local debugging, keep using the wrapper: `pnpm test -- <path-or-filter> [vitest args...]` (for example `pnpm test -- src/commands/onboard-search.test.ts -t "shows registered plugin providers"`); do not default to raw `pnpm vitest run ...` because it bypasses wrapper config/profile/pool routing.
+- For targeted/local debugging, use the native root-project entrypoint: `pnpm test <path-or-filter> [vitest args...]` (for example `pnpm test src/commands/onboard-search.test.ts -t "shows registered plugin providers"`); do not default to raw `pnpm vitest run ...` because it bypasses the repo's default config/profile/pool routing.
 - Do not set test workers above 16; tried already.
-- Keep Vitest on `forks` only. Do not introduce or reintroduce any non-`forks` Vitest pool or alternate execution mode in configs, wrapper scripts, or default test commands without explicit approval in this chat. This includes `threads`, `vmThreads`, `vmForks`, and any future/nonstandard pool variant.
-- If local Vitest runs cause memory pressure, the wrapper now derives budgets from host capabilities (CPU, memory band, current load). For a conservative explicit override during land/gate runs, use `OPENCLAW_TEST_PROFILE=serial OPENCLAW_TEST_SERIAL_GATEWAY=1 pnpm test`.
+- Vitest now defaults to native root-project `threads`, with hard `forks` exceptions for `gateway`, `agents`, and `commands`. Keep new pool changes explicit and justified; use `OPENCLAW_VITEST_POOL=forks` for full local fork debugging.
+- If local Vitest runs cause memory pressure, the default worker budget now derives from host capabilities (CPU, memory band, current load). For a conservative explicit override during land/gate runs, use `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`.
 - Live tests (real keys): `OPENCLAW_LIVE_TEST=1 pnpm test:live` (OpenClaw-only) or `LIVE=1 pnpm test:live` (includes provider live tests). Docker: `pnpm test:docker:live-models`, `pnpm test:docker:live-gateway`. Onboarding Docker E2E: `pnpm test:docker:onboard`.
 - `pnpm test:live` defaults quiet now. Keep `[live]` progress; suppress profile/gateway chatter. Full logs: `OPENCLAW_LIVE_TEST_QUIET=0 pnpm test:live`.
 - Full kit + what’s covered: `docs/help/testing.md`.
@@ -247,6 +265,8 @@
 - "Bump version everywhere" means all version locations above **except** `appcast.xml` (only touch appcast when cutting a new macOS Sparkle release).
 - **Restart apps:** “restart iOS/Android apps” means rebuild (recompile/install) and relaunch, not just kill/launch.
 - **Device checks:** before testing, verify connected real devices (iOS/Android) before reaching for simulators/emulators.
+- Mobile pairing: `ws://` (cleartext) is allowed for private LAN addresses (RFC 1918, link-local, mDNS `.local`) and loopback. Private LAN hosts typically lack PKI-backed identity, so requiring TLS there adds complexity without meaningful security gain. `wss://` is required for Tailscale and public endpoints.
+- Security report scope: reports that treat cleartext `ws://` mobile pairing over private LAN as a vulnerability are out of scope unless they demonstrate a trust-boundary bypass beyond passive network observation on the same LAN.
 - iOS Team ID lookup: `security find-identity -p codesigning -v` → use Apple Development (…) TEAMID. Fallback: `defaults read com.apple.dt.Xcode IDEProvisioningTeamIdentifiers`.
 - A2UI bundle hash: `src/canvas-host/a2ui/.bundle.hash` is auto-generated; ignore unexpected changes, and only regenerate via `pnpm canvas:a2ui:bundle` (or `scripts/bundle-a2ui.sh`) when needed. Commit the hash as a separate commit.
 - Release signing/notary credentials are managed outside the repo; maintainers keep that setup in the private [maintainer release docs](https://github.com/openclaw/maintainers/tree/main/release).

CHANGELOG.md

@@ -4,37 +4,133 @@ Docs: https://docs.openclaw.ai
 
 ## Unreleased
 
+### Breaking
+
+- Config: remove legacy public config aliases such as `talk.voiceId` / `talk.apiKey`, `agents.*.sandbox.perSession`, `browser.ssrfPolicy.allowPrivateNetwork`, `hooks.internal.handlers`, and channel/group/room `allow` toggles in favor of the canonical public paths and `enabled`, while keeping load-time compatibility and `openclaw doctor --fix` migration support for existing configs. (#60726) Thanks @vincentkoc.
+
 ### Changes
 
+- Memory/dreaming (experimental): add weighted short-term recall promotion, managed dreaming modes (`off|core|rem|deep`), a `/dreaming` command, Dreams UI, multilingual conceptual tagging, and doctor/status repair support so durable memory promotion can run in the background with less manual setup. (#60569, #60697)
 - 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/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
 
-- Telegram/reactions: preserve `reactionNotifications: "own"` across gateway restarts by persisting sent-message ownership state instead of treating cold cache as a permissive fallback. (#59207) Thanks @samzong.
-- Gateway/startup: detect PID recycling in gateway lock files on Windows and macOS, and add startup progress so stale lock conflicts no longer block healthy restarts. (#59843) Thanks @TonyDerek-dot.
-- MS Teams/DM media: download inline images in 1:1 chats via Graph API so Teams DM image attachments stop failing to load. (#52212) Thanks @Ted-developer.
-- MS Teams/threading: preserve channel reply threading in proactive fallback so replies stay in the original thread instead of dropping into the channel root. (#55198) Thanks @hyojin.
-- Telegram/media: preserve `<media:...>` placeholders and `file_id` in captioned messages when Bot API downloads fail, so agents still receive media context. (#59948) Thanks @v1p0r.
-- Telegram/media: keep inbound image attachments readable on upgraded installs where legacy state roots still differ from the managed config-dir media cache. (#59971) Thanks @neeravmakwana.
-- Telegram/local Bot API: thread `channels.telegram.apiRoot` through buffered reply-media and album downloads so self-hosted Bot API file paths stop falling back to `api.telegram.org` and 404ing. (#59544) Thanks @SARAMALI15792.
-- Telegram/replies: preserve explicit topic targets when `replyTo` is present while still inheriting the current topic for same-chat replies without an explicit topic. (#59634) Thanks @dashhuang.
-- Telegram/native commands: clean up metadata-driven progress placeholders when replies fall back, edits fail, or local exec approval prompts are suppressed. (#59300) Thanks @jalehman.
-- Media/request overrides: resolve shared and capability-filtered media request SecretRefs correctly and expose media transport override fields to schema-driven config consumers. (#59848) Thanks @vincentkoc.
-- Matrix: allow secret-storage recreation during automatic repair bootstrap so clients that lose their recovery key can recover and persist new cross-signing keys. (#59846) Thanks @al3mart.
-- Matrix/crypto persistence: capture and write the IndexedDB snapshot while holding the snapshot file lock so concurrent gateway and CLI persists cannot overwrite newer crypto state. (#59851) Thanks @al3mart.
-- Ollama/auth: prefer real cloud auth over local marker during model auth resolution so cloud-backed Ollama auth does not get shadowed by stale local-only markers.
-- Plugins/Kimi Coding: parse tagged Kimi tool-call text into structured tool calls on the provider stream path so tools execute instead of echoing raw markup. (#60051) Thanks @obviyus.
-- Channels/passive hooks: emit passive message hooks for mention-skipped Telegram and Signal group messages when `ingest` is enabled, including wildcard/default fallback and per-group override handling. (#60018) Thanks @obviyus.
-- Plugins/manifest registry: stop warning when an explicit manifest `id` intentionally differs from the discovery hint. (#59185) Thanks @samzong.
-- WhatsApp/streaming: honor `channels.whatsapp.blockStreaming` again for inbound auto-replies so progressive block replies can be enabled explicitly instead of being forced to final-only delivery. Thanks @mcaxtr.
-- Plugins/runtime: reuse compatible active registries for `web_search` and `web_fetch` provider snapshot resolution so repeated runtime reads do not re-import the same bundled plugin set on each agent message. Related #48380.
-- Infra/tailscale: ignore `OPENCLAW_TEST_TAILSCALE_BINARY` outside explicit test environments and block it from workspace `.env`, so test-only binary overrides cannot be injected through trusted repository state. (#58468) Thanks @eleqtrizit.
-- Agents/tool policy: preserve restrictive plugin-only allowlists instead of silently widening access to core tools, and keep allowlist warnings aligned with the enforced policy. (#58476) Thanks @eleqtrizit.
-- Hooks/session_end: preserve deterministic reason metadata for custom reset aliases and overlapping idle-plus-daily rollovers so plugins can rely on lifecycle reason reporting. (#59715) Thanks @jalehman.
-- Tools/image generation: stop inferring unsupported resolution overrides for OpenAI reference-image edits when no explicit `size` or `resolution` is provided, so default edit flows no longer fail before the provider request is sent.
-- Agents/sessions: release embedded runner session locks even when teardown cleanup throws, so timed-out or failed cleanup paths no longer leave sessions wedged until the stale-lock watchdog recovers them. (#59194) Thanks @samzong.
+- 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.
+- 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)
+- Android/Talk Mode: restore spoken assistant replies on node-scoped sessions by keeping reply routing synced to the resolved node session key and pausing mic capture during reply playback. (#60306) Thanks @MKV21.
+- Telegram: fix current-model checks in the model picker, HTML-format non-default `/model` confirmations, explicit topic replies, persisted reaction ownership across restarts, caption-media placeholder and `file_id` preservation on download failure, and upgraded-install inbound image reads. (#60384, #60042, #59634, #59207, #59948, #59971)
+- Telegram/local Bot API: honor `channels.telegram.apiRoot` for buffered media downloads, add `channels.telegram.network.dangerouslyAllowPrivateNetwork` for trusted fake-IP setups, and require `channels.telegram.trustedLocalFileRoots` before reading absolute Bot API `file_path` values. (#59544, #60705)
+- Matrix: recover more reliably when secret storage or recovery keys are missing by recreating secret storage during repair and backup reset, hold crypto snapshot locks during persistence, and surface explicit too-large attachment markers. (#59846, #59851, #60599, #60289)
+- ACP/agents: inherit the target agent workspace for cross-agent ACP spawns and fall back safely when the inherited workspace no longer exists. (#58438) Thanks @zssggle-rgb.
+- ACPX/Windows: preserve backslashes and absolute `.exe` paths in Claude CLI parsing, and fail fast on wrapper-script targets with guidance to use `cmd.exe /c`, `powershell.exe -File`, or `node <script>`. (#60689)
+- Gateway/Windows scheduled tasks: preserve Task Scheduler settings on reinstall, fail loudly when `/Run` does not start, and report fast failed restarts accurately instead of pretending they timed out after 60 seconds. (#59335) Thanks @tmimmanuel.
+- Discord: keep REST, webhook, and monitor traffic on the configured proxy, preserve component-only media sends, honor `@everyone` and `@here` mention gates, keep ACK reactions on the active account, and split voice connect/playback timeouts so auto-join is more reliable. (#57465, #60361, #60345)
+- 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.
+- Plugins/Kimi Coding: parse tagged tool calls and keep Anthropic-native tool payloads so Kimi coding endpoints execute tools instead of echoing raw markup. (#60051, #60391)
+- Tools/web_search (Kimi): when `tools.web.search.kimi.baseUrl` is unset, inherit native Moonshot chat `baseUrl` (`.ai` / `.cn`) so China console keys authenticate on the same host as chat. Fixes #44851. (#56769) Thanks @tonga54.
+- Plugins/marketplace: block remote marketplace symlink escapes without breaking ordinary local marketplace install paths. (#60556) Thanks @eleqtrizit.
+- Plugins/install: preserve unsafe override flags across linked plugin and hook-pack probes so local `--link` installs honor the documented override behavior. (#60624) Thanks @JerrettDavis.
+- Config/All Settings: keep the raw config view intact when sensitive fields are blank instead of corrupting or dropping the rendered snapshot. (#28214) Thanks @solodmd.
+- Security: preserve restrictive plugin-only tool allowlists, require owner access for `/allowlist add` and `/allowlist remove`, fail closed when `before_tool_call` hooks crash, block browser SSRF redirect bypasses earlier, and keep non-interactive auth-choice inference scoped to bundled and already-trusted plugins. (#58476, #59836, #59822, #58771, #59120)
+- Exec approvals: reuse durable exact-command `allow-always` approvals in allowlist mode so identical reruns stop prompting, and tighten Windows interpreter/path approval handling so wrapper and malformed-path cases fail closed more consistently. (#59880, #59780, #58040, #59182)
+- Agents/runtime: make default subagent allowlists, inherited skills/workspaces, and duplicate session-id resolution behave more predictably, and include value-shape hints in missing-parameter tool errors. (#59944, #59992, #59858, #55317)
+- Update/npm: prefer the npm binary that owns the installed global OpenClaw prefix so mixed Homebrew-plus-nvm setups update the right install. (#60153) Thanks @jayeshp19.
+- Gateway/plugin routes: keep gateway-auth plugin runtime routes on write-only fallback scopes unless a trusted-proxy caller explicitly declares narrower `x-openclaw-scopes`, so plugin HTTP handlers no longer mint admin-level runtime scopes on missing or untrusted HTTP scope headers. (#59815) Thanks @pgondhi987.
+- 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
 
@@ -64,7 +160,15 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- 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
+
 - Providers/transport policy: centralize request auth, proxy, TLS, and header shaping across shared HTTP, stream, and websocket paths, block insecure TLS/runtime transport overrides, and keep proxy-hop TLS separate from target mTLS settings. (#59682) Thanks @vincentkoc.
+- Providers/OpenRouter: gate documented OpenRouter attribution to native OpenRouter endpoints or the default route so custom proxy base URLs do not inherit OpenRouter request headers.
 - Providers/Copilot: classify native GitHub Copilot API hosts in the shared provider endpoint resolver and harden token-derived proxy endpoint parsing so Copilot base URL routing stays centralized and fails closed on malformed hints. (#59644) Thanks @vincentkoc.
 - Providers/streaming headers: centralize default and attribution header merging across OpenAI websocket, embedded-runner, and proxy stream paths so provider-specific headers stay consistent and caller overrides only win where intended. (#59542) Thanks @vincentkoc.
 - Providers/media HTTP: centralize base URL normalization, default auth/header injection, and explicit header override handling across shared OpenAI-compatible audio, Deepgram audio, Gemini media/image, and Moonshot video request paths. (#59469) Thanks @vincentkoc.
@@ -90,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.
@@ -113,23 +218,18 @@ Docs: https://docs.openclaw.ai
 - Telegram/exec approvals: fall back to the origin session key for async approval followups and keep resume-failure status delivery sanitized so Telegram followups still land without leaking raw exec metadata. (#59351) Thanks @seonang.
 - Node-host/exec approvals: bind `pnpm dlx` invocations through the approval planner's mutable-script path so the effective runtime command is resolved for approval instead of being left unbound. (#58374)
 - Exec/node hosts: stop forwarding the gateway workspace cwd to remote node exec when no workdir was explicitly requested, so cross-platform node approvals fall back to the node default cwd instead of failing with `SYSTEM_RUN_DENIED`. (#58977) Thanks @Starhappysh.
+- 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.
-- Plugins/runtime: reuse compatible active registries for `web_search` and `web_fetch` provider snapshot resolution so repeated runtime reads do not re-import the same bundled plugin set on each agent message. Related #48380.
-- Plugins/OpenAI: enable reference-image edits for `gpt-image-1` by routing edit calls to `/images/edits` with multipart image uploads, and update image-generation capability/docs metadata accordingly.
-- Android/assistant: keep queued App Actions prompts pending when auto-send enqueue is rejected, so transient chat-health drops do not silently lose the assistant request. Thanks @obviyus.
-- Agents/tools: include value-shape hints in missing-parameter tool errors so dropped, empty-string, and wrong-type write payloads are easier to diagnose from logs. (#55317) Thanks @priyansh19.
-- Plugins/Google: separate OAuth CSRF state from PKCE code verifier during Gemini browser sign-in so state validation and token exchange use independent values. (#59116) Thanks @eleqtrizit.
-- Plugins/browser: block SSRF redirect bypass by installing a real-time Playwright route handler before `page.goto()` so navigation to private/internal IPs is intercepted and aborted mid-redirect instead of checked post-hoc. (#58771) Thanks @pgondhi987.
-- Gateway/connect: omit admin-scoped config and auth metadata from lower-privilege `hello-ok` snapshots while preserving those fields for admin reconnects. (#58469) Thanks @eleqtrizit.
-- iOS/canvas: restrict A2UI bridge trust to the bundled scaffold and exact capability-backed remote canvas URLs, so generic `canvas.navigate` and `canvas.present` loads no longer gain action-dispatch authority. (#58471) Thanks @eleqtrizit.
-- Android/gateway: require TLS for non-loopback remote gateway endpoints while still allowing local loopback and emulator cleartext setup flows. (#58475) Thanks @eleqtrizit.
-- Zalo/webhook: scope replay-dedupe cache key to path and account using `JSON.stringify` so multi-account deployments do not silently drop events due to cross-account cache poisoning. (#59387) Thanks @pgondhi987.
-- Exec/Windows: hide transient console windows for `runExec` and `runCommandWithTimeout` child-process launches, matching other Windows exec paths and stopping visible shell flashes during tool runs. (#59466) Thanks @lawrence3699.
-- Exec/Windows: reject malformed drive-less rooted executable paths like `:\Users\...` so approval and allowlist candidate resolution no longer treat them as cwd-relative commands. (#58040) Thanks @SnowSky1.
-- Exec/preflight: fail closed on complex interpreter invocations that would otherwise skip script-content validation, and correctly inspect quoted script paths before host execution. Thanks @pgondhi987.
-- Exec/Windows: include Windows-compatible env override keys like `ProgramFiles(x86)` in system-run approval binding so changed approved values are rejected instead of silently passing unbound. (#59182) Thanks @pgondhi987.
-- ACP/Windows spawn: fail closed on unresolved `.cmd` and `.bat` OpenClaw wrappers unless a caller explicitly opts into shell fallback, so Windows ACP launches do not silently drop into shell-mediated execution when wrapper unwrapping fails. (#58436) Thanks @eleqtrizit.
-- Exec/Windows: prefer strict-inline-eval denial over generic allowlist prompts for interpreter carriers, while keeping persisted Windows allow-always approvals argv-bound. (#59780) Thanks @luoyanglang.
+- 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
 
@@ -158,6 +258,13 @@ Docs: https://docs.openclaw.ai
 - Telegram/local Bot API: preserve media MIME types for absolute-path downloads so local audio files still trigger transcription and other MIME-based handling. (#54603) Thanks @jzakirov
 - Channels/WhatsApp: pass inbound message timestamp to model context so the AI can see when WhatsApp messages were sent. (#58590) Thanks @Maninae
 - QQBot/voice: lazy-load `silk-wasm` in `audio-convert.ts` so qqbot still starts when the optional voice dependency is missing, while voice encode/decode degrades gracefully instead of crashing at module load time. (#58829) Thanks @WideLee.
+- WhatsApp/groups: fix bot waking up on self-number quoted replies in groups with `selfChatMode` enabled. (#60148) Thanks @lurebat
+- Device pairing: require `operator.pairing` or `operator.admin` for internal `/pair` setup-code, QR, and cleanup commands so lower-privilege gateway callers cannot mint or revoke pairing bootstrap material. (#60491) Thanks @eleqtrizit.
+- Agents/failover: unify structured and raw provider error classification so provider-specific `400`/`422` payloads no longer get forced into generic format failures before retry, billing, or compaction logic can inspect them. (#58856) Thanks @aaron-he-zhu.
+- Auth profiles/store: coerce misplaced SecretRef objects out of plaintext `key` and `token` fields during store load so agents without ACP runtime stop crashing on `.trim()` after upgrade. (#58923) Thanks @openperf.
+- ACPX/runtime: repair `queue owner unavailable` session recovery by replacing dead named sessions and resuming the backend session when ACPX exposes a stable session id, so the first ACP prompt no longer inherits a dead handle. (#58669) Thanks @neeravmakwana
+- ACPX/runtime: retry dead-session queue-owner repair without `--resume-session` when the reported ACPX session id is stale, so recovery still creates a fresh named session instead of failing session init. Thanks @obviyus.
+- Tools/web_search (Kimi): replay native Moonshot `$web_search` arguments verbatim, disable thinking for `kimi-k2.5`, and add Moonshot region/model setup prompts so bundled Kimi web search works again. (#59356) Thanks @Innocent-children.
 
 ## 2026.3.31
 
@@ -531,6 +638,9 @@ Docs: https://docs.openclaw.ai
 - Plugins/Matrix: encrypt E2EE image thumbnails with `thumbnail_file` while keeping unencrypted-room previews on `thumbnail_url`, so encrypted Matrix image events keep thumbnail metadata without leaking plaintext previews. (#54711) thanks @frischeDaten.
 - Telegram/forum topics: keep native `/new` and `/reset` routed to the active topic by preserving the topic target on forum-thread command context. (#35963)
 - Status/port diagnostics: treat single-process dual-stack loopback gateway listeners as healthy in `openclaw status --all`, suppressing false "port already in use" conflict warnings. (#53398) Thanks @DanWebb1949.
+- CLI/Docker: treat loopback private-host CLI gateway connects as local for silent pairing auto-approval, while keeping remote backend and public-host CLI connects behind pairing. (#55113) Thanks @sar618.
+
+## 2026.3.24
 
 ### Breaking
 
@@ -906,6 +1016,9 @@ Docs: https://docs.openclaw.ai
 - Feishu/topic threads: fetch full thread context, including prior bot replies, when starting a topic-thread session so follow-up turns in Feishu topics keep the right conversation state. (#45254) Thanks @Coobiw.
 - Feishu/media: keep native image, file, audio, and video/media handling aligned across outbound sends, inbound downloads, thread replies, directory/action aliases, and capability docs so unsupported areas are explicit instead of implied. (#47968) Thanks @Takhoffman.
 - Feishu/webhooks: harden signed webhook verification to use constant-time signature comparison and keep malformed short signatures fail-closed in webhook E2E coverage.
+- Ollama/tool replay: deserialize stringified tool-call arguments on native and OpenAI-compatible Ollama paths while preserving unsafe integer ids across round-trips. (#52253) Thanks @Adam-Researchh.
+- WhatsApp/reconnect: restore the append recency filter in the extension inbox monitor and handle protobuf `Long` timestamps correctly, so fresh post-reconnect append messages are processed while stale history sync stays suppressed. (#42588) Thanks @MonkeyLeeT.
+- WhatsApp/login: wait for pending creds writes before reopening after Baileys `515` pairing restarts in both QR login and `channels login` flows, and keep the restart coverage pinned to the real wrapped error shape plus per-account creds queues. (#27910) Thanks @asyncjason.
 - Telegram/message send: forward `--force-document` through the `sendPayload` path as well as `sendMedia`, so Telegram payload sends with `channelData` keep uploading images as documents instead of silently falling back to compressed photo sends. (#47119) Thanks @thepagent.
 - Telegram/message chunking: preserve spaces, paragraph separators, and word boundaries when HTML overflow rechunking splits formatted replies. (#47274) Thanks @obviyus.
 - Z.AI/onboarding: detect a working default model even for explicit `zai-coding-*` endpoint choices, so Coding Plan setup can keep the selected endpoint while defaulting to `glm-5` when available or `glm-4.7` as fallback. (#45969) Thanks @obviyus.

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

README.md

@@ -34,7 +34,7 @@ New install? Start here: [Getting started](https://docs.openclaw.ai/start/gettin
 
 <table>
   <tr>
-    <td align="center" width="20%">
+    <td align="center" width="16.66%">
       <a href="https://openai.com/">
         <picture>
           <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/openai-light.svg">
@@ -42,7 +42,15 @@ New install? Start here: [Getting started](https://docs.openclaw.ai/start/gettin
         </picture>
       </a>
     </td>
-    <td align="center" width="20%">
+    <td align="center" width="16.66%">
+      <a href="https://github.com/">
+        <picture>
+          <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/github-light.svg">
+          <img src="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/github.svg" alt="GitHub" height="28">
+        </picture>
+      </a>
+    </td>
+    <td align="center" width="16.66%">
       <a href="https://www.nvidia.com/">
         <picture>
           <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/nvidia.svg">
@@ -50,7 +58,7 @@ New install? Start here: [Getting started](https://docs.openclaw.ai/start/gettin
         </picture>
       </a>
     </td>
-    <td align="center" width="20%">
+    <td align="center" width="16.66%">
       <a href="https://vercel.com/">
         <picture>
           <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/vercel-light.svg">
@@ -58,7 +66,7 @@ New install? Start here: [Getting started](https://docs.openclaw.ai/start/gettin
         </picture>
       </a>
     </td>
-    <td align="center" width="20%">
+    <td align="center" width="16.66%">
       <a href="https://blacksmith.sh/">
         <picture>
           <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/blacksmith-light.svg">
@@ -66,7 +74,7 @@ New install? Start here: [Getting started](https://docs.openclaw.ai/start/gettin
         </picture>
       </a>
     </td>
-    <td align="center" width="20%">
+    <td align="center" width="16.66%">
       <a href="https://www.convex.dev/">
         <picture>
           <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/convex-light.svg">

apps/android/app/build.gradle.kts

@@ -65,8 +65,8 @@ android {
         applicationId = "ai.openclaw.app"
         minSdk = 31
         targetSdk = 36
-        versionCode = 2026040301
-        versionName = "2026.4.3"
+        versionCode = 2026040401
+        versionName = "2026.4.4"
         ndk {
             // Support all major ABIs — native libs are tiny (~47 KB per ABI)
             abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")

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

@@ -16,6 +16,8 @@ import ai.openclaw.app.gateway.DeviceIdentityStore
 import ai.openclaw.app.gateway.GatewayDiscovery
 import ai.openclaw.app.gateway.GatewayEndpoint
 import ai.openclaw.app.gateway.GatewaySession
+import ai.openclaw.app.gateway.GatewayTlsProbeFailure
+import ai.openclaw.app.gateway.GatewayTlsProbeResult
 import ai.openclaw.app.gateway.probeGatewayTlsFingerprint
 import ai.openclaw.app.node.*
 import ai.openclaw.app.protocol.OpenClawCanvasA2UIAction
@@ -44,7 +46,7 @@ import java.util.concurrent.atomic.AtomicLong
 class NodeRuntime(
   context: Context,
   val prefs: SecurePrefs = SecurePrefs(context.applicationContext),
-  private val tlsFingerprintProbe: suspend (String, Int) -> String? = ::probeGatewayTlsFingerprint,
+  private val tlsFingerprintProbe: suspend (String, Int) -> GatewayTlsProbeResult = ::probeGatewayTlsFingerprint,
 ) {
   data class GatewayConnectAuth(
     val token: String?,
@@ -69,6 +71,7 @@ class NodeRuntime(
 
   private val identityStore = DeviceIdentityStore(appContext)
   private var connectedEndpoint: GatewayEndpoint? = null
+  private var activeGatewayAuth: GatewayConnectAuth? = null
 
   private val cameraHandler: CameraHandler = CameraHandler(
     appContext = appContext,
@@ -297,6 +300,11 @@ class NodeRuntime(
         _canvasRehydrateErrorText.value = null
         updateStatus()
         showLocalCanvasOnConnect()
+        val endpoint = connectedEndpoint
+        val auth = activeGatewayAuth
+        if (endpoint != null && auth != null) {
+          maybeStartOperatorSessionAfterNodeConnect(endpoint, auth)
+        }
       },
       onDisconnected = { message ->
         _nodeConnected.value = false
@@ -343,6 +351,8 @@ class NodeRuntime(
       session = operatorSession,
       supportsChatSubscribe = false,
       isConnected = { operatorConnected },
+      onBeforeSpeak = { micCapture.pauseForTts() },
+      onAfterSpeak = { micCapture.resumeAfterTts() },
     ).also { speaker ->
       speaker.setPlaybackEnabled(prefs.speakerEnabled.value)
     }
@@ -371,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)
       },
     )
   }
@@ -414,14 +423,19 @@ class NodeRuntime(
       session = operatorSession,
       supportsChatSubscribe = true,
       isConnected = { operatorConnected },
+      onBeforeSpeak = { micCapture.pauseForTts() },
+      onAfterSpeak = { micCapture.resumeAfterTts() },
     )
   }
 
   private fun syncMainSessionKey(agentId: String?) {
     val resolvedKey = resolveNodeMainSessionKey(agentId)
+    // Always push the resolved session key into TalkMode, even when the
+    // state flow value is unchanged, so lazy TalkMode instances do not
+    // stay on the default "main" session key.
+    talkMode.setMainSessionKey(resolvedKey)
     if (_mainSessionKey.value == resolvedKey) return
     _mainSessionKey.value = resolvedKey
-    talkMode.setMainSessionKey(resolvedKey)
     chat.applyMainSessionKey(resolvedKey)
     updateHomeCanvasState()
   }
@@ -581,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
@@ -747,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)
@@ -763,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 {
@@ -791,15 +811,14 @@ class NodeRuntime(
     auth: GatewayConnectAuth,
     reconnect: Boolean = false,
   ) {
+    activeGatewayAuth = auth
     val tls = connectionManager.resolveTlsParams(endpoint)
-    val connectOperator =
-      shouldConnectOperatorSession(
-        auth.token,
-        auth.bootstrapToken,
-        auth.password,
-        loadStoredRoleDeviceToken("operator"),
+    val operatorAuth =
+      resolveOperatorSessionConnectAuth(
+        auth = auth,
+        storedOperatorToken = loadStoredRoleDeviceToken("operator"),
       )
-    if (!connectOperator) {
+    if (operatorAuth == null) {
       operatorConnected = false
       operatorStatusText = "Offline"
       operatorSession.disconnect()
@@ -807,9 +826,9 @@ class NodeRuntime(
     } else {
       operatorSession.connect(
         endpoint,
-        auth.token,
-        auth.bootstrapToken,
-        auth.password,
+        operatorAuth.token,
+        operatorAuth.bootstrapToken,
+        operatorAuth.password,
         connectionManager.buildOperatorConnectOptions(),
         tls,
       )
@@ -822,7 +841,7 @@ class NodeRuntime(
       connectionManager.buildNodeConnectOptions(),
       tls,
     )
-    if (reconnect && connectOperator) {
+    if (reconnect && operatorAuth != null) {
       operatorSession.reconnect()
     }
     if (reconnect) {
@@ -839,8 +858,9 @@ class NodeRuntime(
       // First-time TLS: capture fingerprint, ask user to verify out-of-band, then store and connect.
       _statusText.value = "Verify gateway TLS fingerprint…"
       scope.launch {
-        val fp = tlsFingerprintProbe(endpoint.host, endpoint.port) ?: run {
-          _statusText.value = "Failed: can't read TLS fingerprint"
+        val tlsProbe = tlsFingerprintProbe(endpoint.host, endpoint.port)
+        val fp = tlsProbe.fingerprintSha256 ?: run {
+          _statusText.value = gatewayTlsProbeFailureMessage(tlsProbe.failure)
           return@launch
         }
         _pendingGatewayTrust.value =
@@ -888,6 +908,15 @@ class NodeRuntime(
     _statusText.value = "Offline"
   }
 
+  private fun gatewayTlsProbeFailureMessage(failure: GatewayTlsProbeFailure?): String {
+    return when (failure) {
+      GatewayTlsProbeFailure.TLS_UNAVAILABLE ->
+        "Failed: this host requires wss:// or Tailscale Serve. No TLS endpoint detected."
+      GatewayTlsProbeFailure.ENDPOINT_UNREACHABLE, null ->
+        "Failed: couldn't reach the secure gateway endpoint for this host."
+    }
+  }
+
   private fun hasRecordAudioPermission(): Boolean {
     return (
       ContextCompat.checkSelfPermission(appContext, Manifest.permission.RECORD_AUDIO) ==
@@ -910,8 +939,33 @@ class NodeRuntime(
     return deviceAuthStore.loadToken(deviceId, role)
   }
 
+  private fun maybeStartOperatorSessionAfterNodeConnect(
+    endpoint: GatewayEndpoint,
+    auth: GatewayConnectAuth,
+  ) {
+    if (operatorConnected || operatorStatusText == "Connecting…") {
+      return
+    }
+    val operatorAuth =
+      resolveOperatorSessionConnectAuth(
+        auth = auth,
+        storedOperatorToken = loadStoredRoleDeviceToken("operator"),
+      ) ?: return
+    operatorStatusText = "Connecting…"
+    updateStatus()
+    operatorSession.connect(
+      endpoint,
+      operatorAuth.token,
+      operatorAuth.bootstrapToken,
+      operatorAuth.password,
+      connectionManager.buildOperatorConnectOptions(),
+      connectionManager.resolveTlsParams(endpoint),
+    )
+  }
+
   fun disconnect() {
     connectedEndpoint = null
+    activeGatewayAuth = null
     _pendingGatewayTrust.value = null
     operatorSession.disconnect()
     nodeSession.disconnect()
@@ -1247,18 +1301,47 @@ class NodeRuntime(
 
 }
 
+internal fun resolveOperatorSessionConnectAuth(
+  auth: NodeRuntime.GatewayConnectAuth,
+  storedOperatorToken: String?,
+): NodeRuntime.GatewayConnectAuth? {
+  val explicitToken = auth.token?.trim()?.takeIf { it.isNotEmpty() }
+  if (explicitToken != null) {
+    return NodeRuntime.GatewayConnectAuth(
+      token = explicitToken,
+      bootstrapToken = null,
+      password = null,
+    )
+  }
+
+  val explicitPassword = auth.password?.trim()?.takeIf { it.isNotEmpty() }
+  if (explicitPassword != null) {
+    return NodeRuntime.GatewayConnectAuth(
+      token = null,
+      bootstrapToken = null,
+      password = explicitPassword,
+    )
+  }
+
+  val storedToken = storedOperatorToken?.trim()?.takeIf { it.isNotEmpty() }
+  if (storedToken != null) {
+    // Bootstrap can seed the operator token, but operator should reconnect
+    // through the stored device-token path rather than bootstrap auth itself.
+    return NodeRuntime.GatewayConnectAuth(
+      token = null,
+      bootstrapToken = null,
+      password = null,
+    )
+  }
+
+  return null
+}
+
 internal fun shouldConnectOperatorSession(
-  token: String?,
-  bootstrapToken: String?,
-  password: String?,
+  auth: NodeRuntime.GatewayConnectAuth,
   storedOperatorToken: String?,
 ): Boolean {
-  return (
-    !token.isNullOrBlank() ||
-      !bootstrapToken.isNullOrBlank() ||
-      !password.isNullOrBlank() ||
-      !storedOperatorToken.isNullOrBlank()
-    )
+  return resolveOperatorSessionConnectAuth(auth, storedOperatorToken) != null
 }
 
 private enum class HomeCanvasGatewayState {

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

@@ -1,32 +1,92 @@
 package ai.openclaw.app.gateway
 
 import ai.openclaw.app.SecurePrefs
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+
+data class DeviceAuthEntry(
+  val token: String,
+  val role: String,
+  val scopes: List<String>,
+  val updatedAtMs: Long,
+)
+
+@Serializable
+private data class PersistedDeviceAuthMetadata(
+  val scopes: List<String> = emptyList(),
+  val updatedAtMs: Long = 0L,
+)
 
 interface DeviceAuthTokenStore {
-  fun loadToken(deviceId: String, role: String): String?
-  fun saveToken(deviceId: String, role: String, token: String)
+  fun loadEntry(deviceId: String, role: String): DeviceAuthEntry?
+  fun loadToken(deviceId: String, role: String): String? = loadEntry(deviceId, role)?.token
+  fun saveToken(deviceId: String, role: String, token: String, scopes: List<String> = emptyList())
   fun clearToken(deviceId: String, role: String)
 }
 
 class DeviceAuthStore(private val prefs: SecurePrefs) : DeviceAuthTokenStore {
-  override fun loadToken(deviceId: String, role: String): String? {
+  private val json = Json { ignoreUnknownKeys = true }
+
+  override fun loadEntry(deviceId: String, role: String): DeviceAuthEntry? {
     val key = tokenKey(deviceId, role)
-    return prefs.getString(key)?.trim()?.takeIf { it.isNotEmpty() }
+    val token = prefs.getString(key)?.trim()?.takeIf { it.isNotEmpty() } ?: return null
+    val normalizedRole = normalizeRole(role)
+    val metadata =
+      prefs.getString(metadataKey(deviceId, role))
+        ?.let { raw ->
+          runCatching { json.decodeFromString<PersistedDeviceAuthMetadata>(raw) }.getOrNull()
+        }
+    return DeviceAuthEntry(
+      token = token,
+      role = normalizedRole,
+      scopes = metadata?.scopes ?: emptyList(),
+      updatedAtMs = metadata?.updatedAtMs ?: 0L,
+    )
   }
 
-  override fun saveToken(deviceId: String, role: String, token: String) {
+  override fun saveToken(deviceId: String, role: String, token: String, scopes: List<String>) {
+    val normalizedScopes = normalizeScopes(scopes)
     val key = tokenKey(deviceId, role)
     prefs.putString(key, token.trim())
+    prefs.putString(
+      metadataKey(deviceId, role),
+      json.encodeToString(
+        PersistedDeviceAuthMetadata(
+          scopes = normalizedScopes,
+          updatedAtMs = System.currentTimeMillis(),
+        ),
+      ),
+    )
   }
 
   override fun clearToken(deviceId: String, role: String) {
     val key = tokenKey(deviceId, role)
     prefs.remove(key)
+    prefs.remove(metadataKey(deviceId, role))
   }
 
   private fun tokenKey(deviceId: String, role: String): String {
-    val normalizedDevice = deviceId.trim().lowercase()
-    val normalizedRole = role.trim().lowercase()
+    val normalizedDevice = normalizeDeviceId(deviceId)
+    val normalizedRole = normalizeRole(role)
     return "gateway.deviceToken.$normalizedDevice.$normalizedRole"
   }
+
+  private fun metadataKey(deviceId: String, role: String): String {
+    val normalizedDevice = normalizeDeviceId(deviceId)
+    val normalizedRole = normalizeRole(role)
+    return "gateway.deviceTokenMeta.$normalizedDevice.$normalizedRole"
+  }
+
+  private fun normalizeDeviceId(deviceId: String): String = deviceId.trim().lowercase()
+
+  private fun normalizeRole(role: String): String = role.trim().lowercase()
+
+  private fun normalizeScopes(scopes: List<String>): List<String> {
+    return scopes
+      .map { it.trim() }
+      .filter { it.isNotEmpty() }
+      .distinct()
+      .sorted()
+  }
 }

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

@@ -18,9 +18,7 @@ internal fun isLoopbackGatewayHost(
     host = host.dropLast(1)
   }
   val zoneIndex = host.indexOf('%')
-  if (zoneIndex >= 0) {
-    host = host.substring(0, zoneIndex)
-  }
+  if (zoneIndex >= 0) return false
   if (host.isEmpty()) return false
   if (host == "localhost") return true
   if (allowEmulatorBridgeAlias && host == "10.0.2.2") return true
@@ -46,6 +44,52 @@ internal fun isLoopbackGatewayHost(
   return isMappedIpv4 && address[12] == 127.toByte()
 }
 
+internal fun isPrivateLanGatewayHost(
+  rawHost: String?,
+  allowEmulatorBridgeAlias: Boolean = isAndroidEmulatorRuntime(),
+): Boolean {
+  var host =
+    rawHost
+      ?.trim()
+      ?.lowercase(Locale.US)
+      ?.trim('[', ']')
+      .orEmpty()
+  if (host.endsWith(".")) {
+    host = host.dropLast(1)
+  }
+  val zoneIndex = host.indexOf('%')
+  if (zoneIndex >= 0) {
+    host = host.substring(0, zoneIndex)
+  }
+  if (host.isEmpty()) return false
+  if (isLoopbackGatewayHost(host, allowEmulatorBridgeAlias = allowEmulatorBridgeAlias)) return true
+  if (host.endsWith(".local")) return true
+  if (!host.contains('.') && !host.contains(':')) return true
+
+  parseIpv4Address(host)?.let { ipv4 ->
+    val first = ipv4[0].toInt() and 0xff
+    val second = ipv4[1].toInt() and 0xff
+    return when {
+      first == 10 -> true
+      first == 172 && second in 16..31 -> true
+      first == 192 && second == 168 -> true
+      first == 169 && second == 254 -> true
+      else -> false
+    }
+  }
+  if (!host.contains(':') || !host.all(::isIpv6LiteralChar)) return false
+
+  val address = runCatching { InetAddress.getByName(host) }.getOrNull() ?: return false
+  return when {
+    address.isLinkLocalAddress -> true
+    address.isSiteLocalAddress -> true
+    else -> {
+      val bytes = address.address
+      bytes.size == 16 && (bytes[0].toInt() and 0xfe) == 0xfc
+    }
+  }
+}
+
 private fun isAndroidEmulatorRuntime(): Boolean {
   val fingerprint = Build.FINGERPRINT?.lowercase(Locale.US).orEmpty()
   val model = Build.MODEL?.lowercase(Locale.US).orEmpty()

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 {
@@ -418,11 +426,63 @@ class GatewaySession(
         }
         throw GatewayConnectFailure(error)
       }
-      handleConnectSuccess(res, identity.deviceId)
+      handleConnectSuccess(res, identity.deviceId, selectedAuth.authSource)
       connectDeferred.complete(Unit)
     }
 
-    private fun handleConnectSuccess(res: RpcResponse, deviceId: String) {
+    private fun shouldPersistBootstrapHandoffTokens(authSource: GatewayConnectAuthSource): Boolean {
+      if (authSource != GatewayConnectAuthSource.BOOTSTRAP_TOKEN) return false
+      if (isLoopbackGatewayHost(endpoint.host)) return true
+      return tls != null
+    }
+
+    private fun filteredBootstrapHandoffScopes(role: String, scopes: List<String>): List<String>? {
+      return when (role.trim()) {
+        "node" -> emptyList()
+        "operator" -> {
+          val allowedOperatorScopes =
+            setOf(
+              "operator.approvals",
+              "operator.read",
+              "operator.talk.secrets",
+              "operator.write",
+            )
+          scopes.filter { allowedOperatorScopes.contains(it) }.distinct().sorted()
+        }
+        else -> null
+      }
+    }
+
+    private fun persistBootstrapHandoffToken(
+      deviceId: String,
+      role: String,
+      token: String,
+      scopes: List<String>,
+    ) {
+      val filteredScopes = filteredBootstrapHandoffScopes(role, scopes) ?: return
+      deviceAuthStore.saveToken(deviceId, role, token, filteredScopes)
+    }
+
+    private fun persistIssuedDeviceToken(
+      authSource: GatewayConnectAuthSource,
+      deviceId: String,
+      role: String,
+      token: String,
+      scopes: List<String>,
+    ) {
+      if (authSource == GatewayConnectAuthSource.BOOTSTRAP_TOKEN) {
+        if (!shouldPersistBootstrapHandoffTokens(authSource)) return
+        persistBootstrapHandoffToken(deviceId, role, token, scopes)
+        return
+      }
+      deviceAuthStore.saveToken(deviceId, role, token, scopes)
+    }
+
+    private fun handleConnectSuccess(
+      res: RpcResponse,
+      deviceId: String,
+      authSource: GatewayConnectAuthSource,
+    ) {
       val payloadJson = res.payloadJson ?: throw IllegalStateException("connect failed: missing payload")
       val obj = json.parseToJsonElement(payloadJson).asObjectOrNull() ?: throw IllegalStateException("connect failed")
       pendingDeviceTokenRetry = false
@@ -432,8 +492,27 @@ class GatewaySession(
       val authObj = obj["auth"].asObjectOrNull()
       val deviceToken = authObj?.get("deviceToken").asStringOrNull()
       val authRole = authObj?.get("role").asStringOrNull() ?: options.role
+      val authScopes =
+        authObj?.get("scopes").asArrayOrNull()
+          ?.mapNotNull { it.asStringOrNull() }
+          ?: emptyList()
       if (!deviceToken.isNullOrBlank()) {
-        deviceAuthStore.saveToken(deviceId, authRole, deviceToken)
+        persistIssuedDeviceToken(authSource, deviceId, authRole, deviceToken, authScopes)
+      }
+      if (shouldPersistBootstrapHandoffTokens(authSource)) {
+        authObj?.get("deviceTokens").asArrayOrNull()
+          ?.mapNotNull { it.asObjectOrNull() }
+          ?.forEach { tokenEntry ->
+            val handoffToken = tokenEntry["deviceToken"].asStringOrNull()
+            val handoffRole = tokenEntry["role"].asStringOrNull()
+            val handoffScopes =
+              tokenEntry["scopes"].asArrayOrNull()
+                ?.mapNotNull { it.asStringOrNull() }
+                ?: emptyList()
+            if (!handoffToken.isNullOrBlank() && !handoffRole.isNullOrBlank()) {
+              persistBootstrapHandoffToken(deviceId, handoffRole, handoffToken, handoffScopes)
+            }
+          }
       }
       val rawCanvas = obj["canvasHostUrl"].asStringOrNull()
       canvasHostUrl = normalizeCanvasHostUrl(rawCanvas, endpoint, isTlsConnection = tls != null)
@@ -560,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)
@@ -899,6 +979,8 @@ private fun formatGatewayAuthorityHost(host: String): String {
 
 private fun JsonElement?.asObjectOrNull(): JsonObject? = this as? JsonObject
 
+private fun JsonElement?.asArrayOrNull(): JsonArray? = this as? JsonArray
+
 private fun JsonElement?.asStringOrNull(): String? =
   when (this) {
     is JsonNull -> null

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

@@ -3,7 +3,11 @@ package ai.openclaw.app.gateway
 import android.annotation.SuppressLint
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
+import java.io.EOFException
+import java.net.ConnectException
 import java.net.InetSocketAddress
+import java.net.SocketTimeoutException
+import java.net.UnknownHostException
 import java.security.MessageDigest
 import java.security.SecureRandom
 import java.security.cert.CertificateException
@@ -12,6 +16,7 @@ import java.util.Locale
 import javax.net.ssl.HttpsURLConnection
 import javax.net.ssl.HostnameVerifier
 import javax.net.ssl.SSLContext
+import javax.net.ssl.SSLException
 import javax.net.ssl.SSLParameters
 import javax.net.ssl.SSLSocketFactory
 import javax.net.ssl.SNIHostName
@@ -32,6 +37,16 @@ data class GatewayTlsConfig(
   val hostnameVerifier: HostnameVerifier,
 )
 
+enum class GatewayTlsProbeFailure {
+  TLS_UNAVAILABLE,
+  ENDPOINT_UNREACHABLE,
+}
+
+data class GatewayTlsProbeResult(
+  val fingerprintSha256: String? = null,
+  val failure: GatewayTlsProbeFailure? = null,
+)
+
 fun buildGatewayTlsConfig(
   params: GatewayTlsParams?,
   onStore: ((String) -> Unit)? = null,
@@ -85,10 +100,10 @@ suspend fun probeGatewayTlsFingerprint(
   host: String,
   port: Int,
   timeoutMs: Int = 3_000,
-): String? {
+): GatewayTlsProbeResult {
   val trimmedHost = host.trim()
-  if (trimmedHost.isEmpty()) return null
-  if (port !in 1..65535) return null
+  if (trimmedHost.isEmpty()) return GatewayTlsProbeResult(failure = GatewayTlsProbeFailure.ENDPOINT_UNREACHABLE)
+  if (port !in 1..65535) return GatewayTlsProbeResult(failure = GatewayTlsProbeFailure.ENDPOINT_UNREACHABLE)
 
   return withContext(Dispatchers.IO) {
     val trustAll =
@@ -121,10 +136,21 @@ suspend fun probeGatewayTlsFingerprint(
       }
 
       socket.startHandshake()
-      val cert = socket.session.peerCertificates.firstOrNull() as? X509Certificate ?: return@withContext null
-      sha256Hex(cert.encoded)
-    } catch (_: Throwable) {
-      null
+      val cert =
+        socket.session.peerCertificates.firstOrNull() as? X509Certificate
+          ?: return@withContext GatewayTlsProbeResult(failure = GatewayTlsProbeFailure.TLS_UNAVAILABLE)
+      GatewayTlsProbeResult(fingerprintSha256 = sha256Hex(cert.encoded))
+    } catch (err: Throwable) {
+      val failure =
+        when (err) {
+          is SSLException,
+          is EOFException -> GatewayTlsProbeFailure.TLS_UNAVAILABLE
+          is ConnectException,
+          is SocketTimeoutException,
+          is UnknownHostException -> GatewayTlsProbeFailure.ENDPOINT_UNREACHABLE
+          else -> GatewayTlsProbeFailure.ENDPOINT_UNREACHABLE
+        }
+      GatewayTlsProbeResult(failure = failure)
     } finally {
       try {
         socket.close()

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/node/ConnectionManager.kt

@@ -7,7 +7,7 @@ import ai.openclaw.app.gateway.GatewayClientInfo
 import ai.openclaw.app.gateway.GatewayConnectOptions
 import ai.openclaw.app.gateway.GatewayEndpoint
 import ai.openclaw.app.gateway.GatewayTlsParams
-import ai.openclaw.app.gateway.isLoopbackGatewayHost
+import ai.openclaw.app.gateway.isPrivateLanGatewayHost
 import ai.openclaw.app.LocationMode
 import ai.openclaw.app.VoiceWakeMode
 
@@ -34,10 +34,10 @@ class ConnectionManager(
       val stableId = endpoint.stableId
       val stored = storedFingerprint?.trim().takeIf { !it.isNullOrEmpty() }
       val isManual = stableId.startsWith("manual|")
-      val isLoopback = isLoopbackGatewayHost(endpoint.host)
+      val cleartextAllowedHost = isPrivateLanGatewayHost(endpoint.host)
 
       if (isManual) {
-        if (!manualTlsEnabled && isLoopback) return null
+        if (!manualTlsEnabled && cleartextAllowedHost) return null
         if (!stored.isNullOrBlank()) {
           return GatewayTlsParams(
             required = true,
@@ -75,7 +75,7 @@ class ConnectionManager(
         )
       }
 
-      if (!isLoopback) {
+      if (!cleartextAllowedHost) {
         return GatewayTlsParams(
           required = true,
           expectedFingerprint = 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/ui/ConnectTabScreen.kt

@@ -256,9 +256,23 @@ fun ConnectTabScreen(viewModel: MainViewModel) {
           if (config == null) {
             validationText =
               if (inputMode == ConnectInputMode.SetupCode) {
-                "Paste a valid setup code to connect."
+                val parsedSetup = decodeGatewaySetupCode(setupCode)
+                if (parsedSetup == null) {
+                  "Paste a valid setup code to connect."
+                } else {
+                  val parsedGateway = parseGatewayEndpointResult(parsedSetup.url)
+                  gatewayEndpointValidationMessage(
+                    parsedGateway.error ?: GatewayEndpointValidationError.INVALID_URL,
+                    GatewayEndpointInputSource.SETUP_CODE,
+                  )
+                }
               } else {
-                "Enter a valid manual host and port to connect."
+                val manualUrl = composeGatewayManualUrl(manualHostInput, manualPortInput, manualTlsInput)
+                val parsedGateway = manualUrl?.let(::parseGatewayEndpointResult)
+                gatewayEndpointValidationMessage(
+                  parsedGateway?.error ?: GatewayEndpointValidationError.INVALID_URL,
+                  GatewayEndpointInputSource.MANUAL,
+                )
               }
             return@Button
           }
@@ -386,6 +400,11 @@ fun ConnectTabScreen(viewModel: MainViewModel) {
           Text("Run these on the gateway host:", style = mobileCallout, color = mobileTextSecondary)
           CommandBlock("openclaw qr --setup-code-only")
           CommandBlock("openclaw qr --json")
+          Text(
+            "For Tailscale or public hosts, use wss:// or Tailscale Serve. Private LAN ws:// remains supported.",
+            style = mobileCaption1,
+            color = mobileTextSecondary,
+          )
 
           if (inputMode == ConnectInputMode.SetupCode) {
             Text("Setup Code", style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold), color = mobileTextSecondary)
@@ -468,7 +487,11 @@ fun ConnectTabScreen(viewModel: MainViewModel) {
             ) {
               Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
                 Text("Use TLS", style = mobileHeadline, color = mobileText)
-                Text("Switch to secure websocket (`wss`).", style = mobileCallout, color = mobileTextSecondary)
+                Text(
+                  "Turn this on for Tailscale or public hosts. Private LAN ws:// remains supported.",
+                  style = mobileCallout,
+                  color = mobileTextSecondary,
+                )
               }
               Switch(
                 checked = manualTlsInput,

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

@@ -1,6 +1,6 @@
 package ai.openclaw.app.ui
 
-import ai.openclaw.app.gateway.isLoopbackGatewayHost
+import ai.openclaw.app.gateway.isPrivateLanGatewayHost
 import java.util.Base64
 import java.util.Locale
 import java.net.URI
@@ -33,7 +33,32 @@ internal data class GatewayConnectConfig(
   val password: String,
 )
 
+internal enum class GatewayEndpointValidationError {
+  INVALID_URL,
+  INSECURE_REMOTE_URL,
+}
+
+internal enum class GatewayEndpointInputSource {
+  SETUP_CODE,
+  MANUAL,
+  QR_SCAN,
+}
+
+internal data class GatewayEndpointParseResult(
+  val config: GatewayEndpointConfig? = null,
+  val error: GatewayEndpointValidationError? = null,
+)
+
+internal data class GatewayScannedSetupCodeResult(
+  val setupCode: String? = null,
+  val error: GatewayEndpointValidationError? = null,
+)
+
 private val gatewaySetupJson = Json { ignoreUnknownKeys = true }
+private const val remoteGatewaySecurityRule =
+  "Tailscale and public mobile nodes require wss:// or Tailscale Serve. ws:// is allowed for private LAN, localhost, and the Android emulator."
+private const val remoteGatewaySecurityFix =
+  "Use a private LAN host/address, or enable Tailscale Serve / expose a wss:// gateway URL."
 
 internal fun resolveGatewayConnectConfig(
   useSetupCode: Boolean,
@@ -50,7 +75,7 @@ internal fun resolveGatewayConnectConfig(
 ): GatewayConnectConfig? {
   if (useSetupCode) {
     val setup = decodeGatewaySetupCode(setupCode) ?: return null
-    val parsed = parseGatewayEndpoint(setup.url) ?: return null
+    val parsed = parseGatewayEndpointResult(setup.url).config ?: return null
     val setupBootstrapToken = setup.bootstrapToken?.trim().orEmpty()
     val sharedToken =
       when {
@@ -75,10 +100,10 @@ internal fun resolveGatewayConnectConfig(
   }
 
   val manualUrl = composeGatewayManualUrl(manualHostInput, manualPortInput, manualTlsInput) ?: return null
-  val parsed = parseGatewayEndpoint(manualUrl) ?: return null
+  val parsed = parseGatewayEndpointResult(manualUrl).config ?: return null
   val savedManualEndpoint =
     composeGatewayManualUrl(savedManualHost, savedManualPort, savedManualTls)
-      ?.let(::parseGatewayEndpoint)
+      ?.let { parseGatewayEndpointResult(it).config }
   val preserveBootstrapToken =
     savedManualEndpoint != null &&
       savedManualEndpoint.host == parsed.host &&
@@ -97,13 +122,19 @@ internal fun resolveGatewayConnectConfig(
 }
 
 internal fun parseGatewayEndpoint(rawInput: String): GatewayEndpointConfig? {
+  return parseGatewayEndpointResult(rawInput).config
+}
+
+  internal fun parseGatewayEndpointResult(rawInput: String): GatewayEndpointParseResult {
   val raw = rawInput.trim()
-  if (raw.isEmpty()) return null
+  if (raw.isEmpty()) return GatewayEndpointParseResult(error = GatewayEndpointValidationError.INVALID_URL)
 
   val normalized = if (raw.contains("://")) raw else "https://$raw"
-  val uri = runCatching { URI(normalized) }.getOrNull() ?: return null
+  val uri =
+    runCatching { URI(normalized) }.getOrNull()
+      ?: return GatewayEndpointParseResult(error = GatewayEndpointValidationError.INVALID_URL)
   val host = uri.host?.trim()?.trim('[', ']').orEmpty()
-  if (host.isEmpty()) return null
+  if (host.isEmpty()) return GatewayEndpointParseResult(error = GatewayEndpointValidationError.INVALID_URL)
 
   val scheme = uri.scheme?.trim()?.lowercase(Locale.US).orEmpty()
   val tls =
@@ -112,7 +143,9 @@ internal fun parseGatewayEndpoint(rawInput: String): GatewayEndpointConfig? {
       "wss", "https" -> true
       else -> true
     }
-  if (!tls && !isLoopbackGatewayHost(host)) return null
+  if (!tls && !isPrivateLanGatewayHost(host)) {
+    return GatewayEndpointParseResult(error = GatewayEndpointValidationError.INSECURE_REMOTE_URL)
+  }
   val defaultPort =
     when (scheme) {
       "wss", "https" -> 443
@@ -134,7 +167,9 @@ internal fun parseGatewayEndpoint(rawInput: String): GatewayEndpointConfig? {
       "${if (tls) "https" else "http"}://$displayHost:$port"
     }
 
-  return GatewayEndpointConfig(host = host, port = port, tls = tls, displayUrl = displayUrl)
+  return GatewayEndpointParseResult(
+    config = GatewayEndpointConfig(host = host, port = port, tls = tls, displayUrl = displayUrl),
+  )
 }
 
 internal fun decodeGatewaySetupCode(rawInput: String): GatewaySetupCode? {
@@ -165,9 +200,44 @@ internal fun decodeGatewaySetupCode(rawInput: String): GatewaySetupCode? {
 }
 
 internal fun resolveScannedSetupCode(rawInput: String): String? {
-  val setupCode = resolveSetupCodeCandidate(rawInput) ?: return null
-  val decoded = decodeGatewaySetupCode(setupCode) ?: return null
-  return setupCode.takeIf { parseGatewayEndpoint(decoded.url) != null }
+  return resolveScannedSetupCodeResult(rawInput).setupCode
+}
+
+internal fun resolveScannedSetupCodeResult(rawInput: String): GatewayScannedSetupCodeResult {
+  val setupCode =
+    resolveSetupCodeCandidate(rawInput)
+      ?: return GatewayScannedSetupCodeResult(error = GatewayEndpointValidationError.INVALID_URL)
+  val decoded =
+    decodeGatewaySetupCode(setupCode)
+      ?: return GatewayScannedSetupCodeResult(error = GatewayEndpointValidationError.INVALID_URL)
+  val parsed = parseGatewayEndpointResult(decoded.url)
+  if (parsed.config == null) {
+    return GatewayScannedSetupCodeResult(error = parsed.error)
+  }
+  return GatewayScannedSetupCodeResult(setupCode = setupCode)
+}
+
+internal fun gatewayEndpointValidationMessage(
+  error: GatewayEndpointValidationError,
+  source: GatewayEndpointInputSource,
+): String {
+  return when (error) {
+    GatewayEndpointValidationError.INSECURE_REMOTE_URL ->
+      when (source) {
+        GatewayEndpointInputSource.SETUP_CODE ->
+          "Setup code points to an insecure remote gateway. $remoteGatewaySecurityRule $remoteGatewaySecurityFix"
+        GatewayEndpointInputSource.QR_SCAN ->
+          "QR code points to an insecure remote gateway. $remoteGatewaySecurityRule $remoteGatewaySecurityFix"
+        GatewayEndpointInputSource.MANUAL ->
+          "$remoteGatewaySecurityRule $remoteGatewaySecurityFix"
+      }
+    GatewayEndpointValidationError.INVALID_URL ->
+      when (source) {
+        GatewayEndpointInputSource.SETUP_CODE -> "Setup code has invalid gateway URL."
+        GatewayEndpointInputSource.QR_SCAN -> "QR code did not contain a valid setup code."
+        GatewayEndpointInputSource.MANUAL -> "Enter a valid manual host and port to connect."
+      }
+  }
 }
 
 internal fun composeGatewayManualUrl(hostInput: String, portInput: String, tls: Boolean): String? {

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

@@ -49,6 +49,7 @@ internal fun buildGatewayDiagnosticsReport(
     Please:
     - pick one route only: same machine, same LAN, Tailscale, or public URL
     - classify this as pairing/auth, TLS trust, wrong advertised route, wrong address/port, or gateway down
+    - remember: Tailscale/public mobile routes require wss:// or Tailscale Serve; private LAN ws:// is still allowed
     - quote the exact app status/error below
     - tell me whether `openclaw devices list` should show a pending pairing request
     - if more signal is needed, ask for `openclaw qr --json`, `openclaw devices list`, and `openclaw nodes status`

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

@@ -566,12 +566,16 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
                     if (contents.isEmpty()) {
                       return@addOnSuccessListener
                     }
-                    val scannedSetupCode = resolveScannedSetupCode(contents)
-                    if (scannedSetupCode == null) {
-                      gatewayError = "QR code did not contain a valid setup code."
+                    val scannedSetupCode = resolveScannedSetupCodeResult(contents)
+                    if (scannedSetupCode.setupCode == null) {
+                      gatewayError =
+                        gatewayEndpointValidationMessage(
+                          scannedSetupCode.error ?: GatewayEndpointValidationError.INVALID_URL,
+                          GatewayEndpointInputSource.QR_SCAN,
+                        )
                       return@addOnSuccessListener
                     }
-                    setupCode = scannedSetupCode
+                    setupCode = scannedSetupCode.setupCode
                     gatewayInputMode = GatewayInputMode.SetupCode
                     gatewayError = null
                     attemptedConnect = false
@@ -799,9 +803,13 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
                     gatewayError = "Scan QR code first, or use Advanced setup."
                     return@Button
                   }
-                  val parsedGateway = parseGatewayEndpoint(parsedSetup.url)
-                  if (parsedGateway == null) {
-                    gatewayError = "Setup code has invalid gateway URL."
+                  val parsedGateway = parseGatewayEndpointResult(parsedSetup.url)
+                  if (parsedGateway.config == null) {
+                    gatewayError =
+                      gatewayEndpointValidationMessage(
+                        parsedGateway.error ?: GatewayEndpointValidationError.INVALID_URL,
+                        GatewayEndpointInputSource.SETUP_CODE,
+                      )
                     return@Button
                   }
                   gatewayUrl = parsedSetup.url
@@ -819,12 +827,16 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
                   }
                 } else {
                   val manualUrl = composeGatewayManualUrl(manualHost, manualPort, manualTls)
-                  val parsedGateway = manualUrl?.let(::parseGatewayEndpoint)
-                  if (parsedGateway == null) {
-                    gatewayError = "Manual endpoint is invalid."
+                  val parsedGateway = manualUrl?.let(::parseGatewayEndpointResult)
+                  if (parsedGateway?.config == null) {
+                    gatewayError =
+                      gatewayEndpointValidationMessage(
+                        parsedGateway?.error ?: GatewayEndpointValidationError.INVALID_URL,
+                        GatewayEndpointInputSource.MANUAL,
+                      )
                     return@Button
                   }
-                  gatewayUrl = parsedGateway.displayUrl
+                  gatewayUrl = parsedGateway.config.displayUrl
                   viewModel.setGatewayBootstrapToken("")
                 }
                 step = OnboardingStep.Permissions
@@ -863,19 +875,23 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
             } else {
               Button(
                 onClick = {
-                  val parsed = parseGatewayEndpoint(gatewayUrl)
-                  if (parsed == null) {
+                  val parsed = parseGatewayEndpointResult(gatewayUrl)
+                  if (parsed.config == null) {
                     step = OnboardingStep.Gateway
-                    gatewayError = "Invalid gateway URL."
+                    gatewayError =
+                      gatewayEndpointValidationMessage(
+                        parsed.error ?: GatewayEndpointValidationError.INVALID_URL,
+                        GatewayEndpointInputSource.MANUAL,
+                      )
                     return@Button
                   }
                   val token = persistedGatewayToken.trim()
                   val password = gatewayPassword.trim()
                   attemptedConnect = true
                   viewModel.setManualEnabled(true)
-                  viewModel.setManualHost(parsed.host)
-                  viewModel.setManualPort(parsed.port)
-                  viewModel.setManualTls(parsed.tls)
+                  viewModel.setManualHost(parsed.config.host)
+                  viewModel.setManualPort(parsed.config.port)
+                  viewModel.setManualTls(parsed.config.tls)
                   if (gatewayInputMode == GatewayInputMode.Manual) {
                     viewModel.setGatewayBootstrapToken("")
                   }
@@ -886,7 +902,7 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
                   }
                   viewModel.setGatewayPassword(password)
                   viewModel.connect(
-                    GatewayEndpoint.manual(host = parsed.host, port = parsed.port),
+                    GatewayEndpoint.manual(host = parsed.config.host, port = parsed.config.port),
                     token = token.ifEmpty { null },
                     bootstrapToken =
                       if (gatewayInputMode == GatewayInputMode.SetupCode) {
@@ -1040,7 +1056,7 @@ private fun GatewayStep(
 
   StepShell(title = "Gateway Connection") {
     Text(
-      "Run `openclaw qr` on your gateway host, then scan the code with this device.",
+      "Run `openclaw qr` on your gateway host, then scan the code with this device. For Tailscale or public hosts, use wss:// or Tailscale Serve.",
       style = onboardingCalloutStyle,
       color = onboardingTextSecondary,
     )
@@ -1072,7 +1088,7 @@ private fun GatewayStep(
       ) {
         Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
           Text("Advanced setup", style = onboardingHeadlineStyle, color = onboardingText)
-          Text("Paste setup code or enter host/port manually.", style = onboardingCaption1Style, color = onboardingTextSecondary)
+          Text("Paste setup code or enter host/port manually. Private LAN ws:// is supported; Tailscale/public hosts need wss://.", style = onboardingCaption1Style, color = onboardingTextSecondary)
         }
         Icon(
           imageVector = if (advancedOpen) Icons.Default.ExpandLess else Icons.Default.ExpandMore,
@@ -1153,7 +1169,11 @@ private fun GatewayStep(
           ) {
             Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
               Text("Use TLS", style = onboardingHeadlineStyle, color = onboardingText)
-              Text("Switch to secure websocket (`wss`).", style = onboardingCalloutStyle.copy(lineHeight = 18.sp), color = onboardingTextSecondary)
+              Text(
+                "Turn this on for Tailscale or public hosts. Private LAN ws:// remains supported.",
+                style = onboardingCalloutStyle.copy(lineHeight = 18.sp),
+                color = onboardingTextSecondary,
+              )
             }
             Switch(
               checked = manualTls,

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

@@ -14,11 +14,13 @@ import android.speech.SpeechRecognizer
 import androidx.core.content.ContextCompat
 import java.util.UUID
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonArray
 import kotlinx.serialization.json.JsonObject
@@ -88,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
@@ -99,11 +102,63 @@ class MicCaptureManager(
   private var transcriptFlushJob: Job? = null
   private var pendingRunTimeoutJob: Job? = null
   private var stopRequested = false
+  private val ttsPauseLock = Any()
+  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
     if (enabled) {
+      val pausedForTts =
+        synchronized(ttsPauseLock) {
+          if (ttsPauseDepth > 0) {
+            resumeMicAfterTts = true
+            true
+          } else {
+            false
+          }
+        }
+      if (pausedForTts) {
+        _statusText.value = if (_isSending.value) "Speaking · waiting for reply" else "Speaking…"
+        return
+      }
       start()
       sendQueuedIfIdle()
     } else {
@@ -126,6 +181,58 @@ class MicCaptureManager(
     }
   }
 
+  suspend fun pauseForTts() {
+    val shouldPause =
+      synchronized(ttsPauseLock) {
+        ttsPauseDepth += 1
+        if (ttsPauseDepth > 1) return@synchronized false
+        resumeMicAfterTts = _micEnabled.value
+        val active = resumeMicAfterTts || recognizer != null || _isListening.value
+        if (!active) return@synchronized false
+        stopRequested = true
+        restartJob?.cancel()
+        restartJob = null
+        transcriptFlushJob?.cancel()
+        transcriptFlushJob = null
+        _isListening.value = false
+        _inputLevel.value = 0f
+        _liveTranscript.value = null
+        _statusText.value = if (_isSending.value) "Speaking · waiting for reply" else "Speaking…"
+        true
+      }
+    if (!shouldPause) return
+    withContext(Dispatchers.Main) {
+      recognizer?.cancel()
+      recognizer?.destroy()
+      recognizer = null
+    }
+  }
+
+  suspend fun resumeAfterTts() {
+    val shouldResume =
+      synchronized(ttsPauseLock) {
+        if (ttsPauseDepth == 0) return@synchronized false
+        ttsPauseDepth -= 1
+        if (ttsPauseDepth > 0) return@synchronized false
+        val resume = resumeMicAfterTts && _micEnabled.value
+        resumeMicAfterTts = false
+        if (!resume) {
+          _statusText.value =
+            when {
+              _micEnabled.value && _isSending.value -> "Listening · sending queued voice"
+              _micEnabled.value -> "Listening"
+              _isSending.value -> "Mic off · sending…"
+              else -> "Mic off"
+            }
+        }
+        resume
+      }
+    if (!shouldResume) return
+    stopRequested = false
+    start()
+    sendQueuedIfIdle()
+  }
+
   fun onGatewayConnectionChanged(connected: Boolean) {
     gatewayConnected = connected
     if (connected) {
@@ -137,7 +244,7 @@ class MicCaptureManager(
     pendingRunId = null
     pendingAssistantEntryId = null
     _isSending.value = false
-    if (messageQueue.isNotEmpty()) {
+    if (hasQueuedMessages()) {
       _statusText.value = queuedWaitingStatus()
     }
   }
@@ -245,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
@@ -278,7 +385,7 @@ class MicCaptureManager(
       role = VoiceConversationRole.User,
       text = message,
     )
-    messageQueue.addLast(message)
+    enqueueMessage(message)
     publishQueue()
   }
 
@@ -297,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 {
@@ -315,7 +422,7 @@ class MicCaptureManager(
       return
     }
 
-    val next = messageQueue.first()
+    val next = firstQueuedMessage() ?: return
     _isSending.value = true
     pendingRunTimeoutJob?.cancel()
     pendingRunTimeoutJob = null
@@ -333,7 +440,7 @@ class MicCaptureManager(
         if (runId == null) {
           pendingRunTimeoutJob?.cancel()
           pendingRunTimeoutJob = null
-          messageQueue.removeFirst()
+          removeFirstQueuedMessage()
           publishQueue()
           _isSending.value = false
           pendingAssistantEntryId = null
@@ -379,8 +486,7 @@ class MicCaptureManager(
   private fun completePendingTurn() {
     pendingRunTimeoutJob?.cancel()
     pendingRunTimeoutJob = null
-    if (messageQueue.isNotEmpty()) {
-      messageQueue.removeFirst()
+    if (removeFirstQueuedMessage() != null) {
       publishQueue()
     }
     pendingRunId = null
@@ -390,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,19 +14,21 @@ 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
 import java.util.UUID
 import java.util.concurrent.atomic.AtomicLong
+import kotlin.coroutines.coroutineContext
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
+import kotlinx.coroutines.NonCancellable
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.ensureActive
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -46,6 +48,8 @@ class TalkModeManager(
   private val session: GatewaySession,
   private val supportsChatSubscribe: Boolean,
   private val isConnected: () -> Boolean,
+  private val onBeforeSpeak: suspend () -> Unit = {},
+  private val onAfterSpeak: suspend () -> Unit = {},
 ) {
   companion object {
     private const val tag = "TalkMode"
@@ -57,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
@@ -101,6 +107,7 @@ class TalkModeManager(
   private val playbackGeneration = AtomicLong(0L)
 
   private var ttsJob: Job? = null
+  private val ttsJobLock = Any()
   private val ttsLock = Any()
   private var textToSpeech: TextToSpeech? = null
   private var textToSpeechInit: CompletableDeferred<TextToSpeech>? = null
@@ -163,8 +170,11 @@ class TalkModeManager(
           ?: waitForAssistantText(session, startedAt, if (ok) 12_000 else 25_000)
         if (!assistant.isNullOrBlank()) {
           val playbackToken = playbackGeneration.incrementAndGet()
+          cancelActivePlayback()
           _statusText.value = "Speaking…"
-          playAssistant(assistant, playbackToken)
+          runPlaybackSession(playbackToken) {
+            playAssistant(assistant, playbackToken)
+          }
         } else {
           _statusText.value = "No reply"
         }
@@ -180,14 +190,12 @@ class TalkModeManager(
 
   fun playTtsForText(text: String) {
     val playbackToken = playbackGeneration.incrementAndGet()
-    ttsJob?.cancel()
-    ttsJob = scope.launch {
+    cancelActivePlayback()
+    scope.launch {
       reloadConfig()
-      ensurePlaybackActive(playbackToken)
-      _isSpeaking.value = true
-      _statusText.value = "Speaking…"
-      playAssistant(text, playbackToken)
-      ttsJob = null
+      runPlaybackSession(playbackToken) {
+        playAssistant(text, playbackToken)
+      }
     }
   }
 
@@ -258,7 +266,6 @@ class TalkModeManager(
     if (playbackEnabled == enabled) return
     playbackEnabled = enabled
     if (!enabled) {
-      playbackGeneration.incrementAndGet()
       stopSpeaking()
     }
   }
@@ -270,10 +277,11 @@ class TalkModeManager(
   suspend fun speakAssistantReply(text: String) {
     if (!playbackEnabled) return
     val playbackToken = playbackGeneration.incrementAndGet()
-    stopSpeaking(resetInterrupt = false)
+    cancelActivePlayback()
     ensureConfigLoaded()
-    ensurePlaybackActive(playbackToken)
-    playAssistant(text, playbackToken)
+    runPlaybackSession(playbackToken) {
+      playAssistant(text, playbackToken)
+    }
   }
 
   private fun start() {
@@ -483,9 +491,10 @@ class TalkModeManager(
       }
       Log.d(tag, "assistant text ok chars=${assistant.length}")
       val playbackToken = playbackGeneration.incrementAndGet()
-      stopSpeaking(resetInterrupt = false)
-      ensurePlaybackActive(playbackToken)
-      playAssistant(assistant, playbackToken)
+      cancelActivePlayback()
+      runPlaybackSession(playbackToken) {
+        playAssistant(assistant, playbackToken)
+      }
     } catch (err: Throwable) {
       if (err is CancellationException) {
         Log.d(tag, "finalize speech cancelled")
@@ -655,22 +664,87 @@ 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
     }
   }
 
+  private suspend fun runPlaybackSession(
+    playbackToken: Long,
+    block: suspend () -> Unit,
+  ) {
+    val currentJob = coroutineContext[Job]
+    var shouldResumeAfterSpeak = false
+    try {
+      val claimedPlayback =
+        synchronized(ttsJobLock) {
+          if (!playbackEnabled || playbackToken != playbackGeneration.get()) {
+            false
+          } else {
+            ttsJob = currentJob
+            true
+          }
+        }
+      if (!claimedPlayback) {
+        ensurePlaybackActive(playbackToken)
+        return
+      }
+      ensurePlaybackActive(playbackToken)
+      shouldResumeAfterSpeak = true
+      onBeforeSpeak()
+      ensurePlaybackActive(playbackToken)
+      _isSpeaking.value = true
+      _statusText.value = "Speaking…"
+      block()
+    } finally {
+      synchronized(ttsJobLock) {
+        if (ttsJob === currentJob) {
+          ttsJob = null
+        }
+      }
+      _isSpeaking.value = false
+      if (shouldResumeAfterSpeak) {
+        withContext(NonCancellable) {
+          onAfterSpeak()
+        }
+      }
+    }
+  }
+
+  private fun cancelActivePlayback() {
+    val activeJob =
+      synchronized(ttsJobLock) {
+        ttsJob
+      }
+    activeJob?.cancel()
+    talkAudioPlayer.stop()
+    stopTextToSpeechPlayback()
+  }
+
   private suspend fun speakWithSystemTts(text: String, directive: TalkDirective?, playbackToken: Long) {
     ensurePlaybackActive(playbackToken)
     val engine = ensureTextToSpeech()
@@ -755,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/GatewayBootstrapAuthTest.kt

@@ -2,6 +2,8 @@ package ai.openclaw.app
 
 import ai.openclaw.app.gateway.GatewayEndpoint
 import ai.openclaw.app.gateway.GatewaySession
+import ai.openclaw.app.gateway.GatewayTlsProbeFailure
+import ai.openclaw.app.gateway.GatewayTlsProbeResult
 import kotlinx.coroutines.runBlocking
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
@@ -19,17 +21,72 @@ import java.util.UUID
 @Config(sdk = [34])
 class GatewayBootstrapAuthTest {
   @Test
-  fun connectsOperatorSessionWhenBootstrapAuthExists() {
-    assertTrue(shouldConnectOperatorSession(token = "", bootstrapToken = "bootstrap-1", password = "", storedOperatorToken = ""))
-    assertTrue(shouldConnectOperatorSession(token = null, bootstrapToken = "bootstrap-1", password = null, storedOperatorToken = null))
+  fun skipsOperatorSessionWhenOnlyBootstrapAuthExists() {
+    assertFalse(
+      shouldConnectOperatorSession(
+        NodeRuntime.GatewayConnectAuth(token = "", bootstrapToken = "bootstrap-1", password = ""),
+        storedOperatorToken = "",
+      ),
+    )
+    assertFalse(
+      shouldConnectOperatorSession(
+        NodeRuntime.GatewayConnectAuth(token = null, bootstrapToken = "bootstrap-1", password = null),
+        storedOperatorToken = null,
+      ),
+    )
   }
 
   @Test
-  fun skipsOperatorSessionOnlyWhenNoSharedBootstrapOrStoredAuthExists() {
-    assertTrue(shouldConnectOperatorSession(token = "shared-token", bootstrapToken = "bootstrap-1", password = null, storedOperatorToken = null))
-    assertTrue(shouldConnectOperatorSession(token = null, bootstrapToken = "bootstrap-1", password = "shared-password", storedOperatorToken = null))
-    assertTrue(shouldConnectOperatorSession(token = null, bootstrapToken = null, password = null, storedOperatorToken = "stored-token"))
-    assertFalse(shouldConnectOperatorSession(token = null, bootstrapToken = "", password = null, storedOperatorToken = null))
+  fun connectsOperatorSessionWhenSharedPasswordOrStoredAuthExists() {
+    assertTrue(
+      shouldConnectOperatorSession(
+        NodeRuntime.GatewayConnectAuth(token = "shared-token", bootstrapToken = "bootstrap-1", password = null),
+        storedOperatorToken = null,
+      ),
+    )
+    assertTrue(
+      shouldConnectOperatorSession(
+        NodeRuntime.GatewayConnectAuth(token = null, bootstrapToken = "bootstrap-1", password = "shared-password"),
+        storedOperatorToken = null,
+      ),
+    )
+    assertTrue(
+      shouldConnectOperatorSession(
+        NodeRuntime.GatewayConnectAuth(token = null, bootstrapToken = "bootstrap-1", password = null),
+        storedOperatorToken = "stored-token",
+      ),
+    )
+    assertFalse(
+      shouldConnectOperatorSession(
+        NodeRuntime.GatewayConnectAuth(token = null, bootstrapToken = "", password = null),
+        storedOperatorToken = null,
+      ),
+    )
+  }
+
+  @Test
+  fun resolveOperatorSessionConnectAuthUsesStoredTokenPathAfterBootstrapHandoff() {
+    val resolved =
+      resolveOperatorSessionConnectAuth(
+        auth = NodeRuntime.GatewayConnectAuth(token = null, bootstrapToken = "bootstrap-1", password = null),
+        storedOperatorToken = "stored-token",
+      )
+
+    assertEquals(NodeRuntime.GatewayConnectAuth(token = null, bootstrapToken = null, password = null), resolved)
+  }
+
+  @Test
+  fun resolveOperatorSessionConnectAuthPrefersExplicitSharedAuth() {
+    val resolved =
+      resolveOperatorSessionConnectAuth(
+        auth = NodeRuntime.GatewayConnectAuth(token = "shared-token", bootstrapToken = "bootstrap-1", password = "shared-password"),
+        storedOperatorToken = "stored-token",
+      )
+
+    assertEquals(
+      NodeRuntime.GatewayConnectAuth(token = "shared-token", bootstrapToken = null, password = null),
+      resolved,
+    )
   }
 
   @Test
@@ -77,7 +134,7 @@ class GatewayBootstrapAuthTest {
         NodeRuntime(
           app,
           prefs,
-          tlsFingerprintProbe = { _, _ -> "fp-1" },
+          tlsFingerprintProbe = { _, _ -> GatewayTlsProbeResult(fingerprintSha256 = "fp-1") },
         )
       val endpoint = GatewayEndpoint.manual(host = "gateway.example", port = 18789)
       val explicitAuth =
@@ -95,9 +152,32 @@ class GatewayBootstrapAuthTest {
 
       assertEquals("fp-1", prefs.loadGatewayTlsFingerprint(endpoint.stableId))
       assertEquals("setup-bootstrap-token", desiredBootstrapToken(runtime, "nodeSession"))
-      assertEquals("setup-bootstrap-token", desiredBootstrapToken(runtime, "operatorSession"))
+      assertNull(desiredBootstrapToken(runtime, "operatorSession"))
     }
 
+  @Test
+  fun connect_showsSecureEndpointGuidanceWhenTlsProbeFails() {
+    val app = RuntimeEnvironment.getApplication()
+    val runtime =
+      NodeRuntime(
+        app,
+        tlsFingerprintProbe = { _, _ ->
+          GatewayTlsProbeResult(failure = GatewayTlsProbeFailure.TLS_UNAVAILABLE)
+        },
+      )
+
+    runtime.connect(
+      GatewayEndpoint.manual(host = "gateway.example", port = 18789),
+      NodeRuntime.GatewayConnectAuth(token = "shared-token", bootstrapToken = null, password = null),
+    )
+
+    assertEquals(
+      "Failed: this host requires wss:// or Tailscale Serve. No TLS endpoint detected.",
+      waitForStatusText(runtime),
+    )
+    assertNull(runtime.pendingGatewayTrust.value)
+  }
+
   private fun waitForGatewayTrustPrompt(runtime: NodeRuntime): NodeRuntime.GatewayTrustPrompt {
     repeat(50) {
       runtime.pendingGatewayTrust.value?.let { return it }
@@ -106,6 +186,17 @@ class GatewayBootstrapAuthTest {
     error("Expected pending gateway trust prompt")
   }
 
+  private fun waitForStatusText(runtime: NodeRuntime): String {
+    repeat(50) {
+      val status = runtime.statusText.value
+      if (status != "Verify gateway TLS fingerprint…") {
+        return status
+      }
+      Thread.sleep(10)
+    }
+    error("Expected status text update")
+  }
+
   private fun desiredBootstrapToken(runtime: NodeRuntime, sessionFieldName: String): String? {
     val session = readField<GatewaySession>(runtime, sessionFieldName)
     val desired = readField<Any?>(session, "desired") ?: return null

apps/android/app/src/test/java/ai/openclaw/app/gateway/DeviceAuthStoreTest.kt

@@ -0,0 +1,63 @@
+package ai.openclaw.app.gateway
+
+import ai.openclaw.app.SecurePrefs
+import android.content.Context
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+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
+import java.util.UUID
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class DeviceAuthStoreTest {
+  @Test
+  fun saveTokenPersistsNormalizedScopesMetadata() {
+    val app = RuntimeEnvironment.getApplication()
+    val securePrefs =
+      app.getSharedPreferences(
+        "openclaw.node.secure.test.${UUID.randomUUID()}",
+        Context.MODE_PRIVATE,
+      )
+    val prefs = SecurePrefs(app, securePrefsOverride = securePrefs)
+    val store = DeviceAuthStore(prefs)
+
+    store.saveToken(
+      deviceId = " Device-1 ",
+      role = " Operator ",
+      token = " operator-token ",
+      scopes = listOf("operator.write", "operator.read", "operator.write", " "),
+    )
+
+    val entry = store.loadEntry("device-1", "operator")
+    assertNotNull(entry)
+    assertEquals("operator-token", entry?.token)
+    assertEquals("operator", entry?.role)
+    assertEquals(listOf("operator.read", "operator.write"), entry?.scopes)
+    assertTrue((entry?.updatedAtMs ?: 0L) > 0L)
+  }
+
+  @Test
+  fun loadEntryReadsLegacyTokenWithoutMetadata() {
+    val app = RuntimeEnvironment.getApplication()
+    val securePrefs =
+      app.getSharedPreferences(
+        "openclaw.node.secure.test.${UUID.randomUUID()}",
+        Context.MODE_PRIVATE,
+      )
+    val prefs = SecurePrefs(app, securePrefsOverride = securePrefs)
+    prefs.putString("gateway.deviceToken.device-1.operator", "legacy-token")
+    val store = DeviceAuthStore(prefs)
+
+    val entry = store.loadEntry("device-1", "operator")
+    assertNotNull(entry)
+    assertEquals("legacy-token", entry?.token)
+    assertEquals("operator", entry?.role)
+    assertEquals(emptyList<String>(), entry?.scopes)
+    assertEquals(0L, entry?.updatedAtMs)
+  }
+}

apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionInvokeTest.kt

@@ -35,12 +35,18 @@ private const val CONNECT_CHALLENGE_FRAME =
   """{"type":"event","event":"connect.challenge","payload":{"nonce":"android-test-nonce"}}"""
 
 private class InMemoryDeviceAuthStore : DeviceAuthTokenStore {
-  private val tokens = mutableMapOf<String, String>()
+  private val tokens = mutableMapOf<String, DeviceAuthEntry>()
 
-  override fun loadToken(deviceId: String, role: String): String? = tokens["${deviceId.trim()}|${role.trim()}"]?.trim()?.takeIf { it.isNotEmpty() }
+  override fun loadEntry(deviceId: String, role: String): DeviceAuthEntry? = tokens["${deviceId.trim()}|${role.trim()}"]
 
-  override fun saveToken(deviceId: String, role: String, token: String) {
-    tokens["${deviceId.trim()}|${role.trim()}"] = token.trim()
+  override fun saveToken(deviceId: String, role: String, token: String, scopes: List<String>) {
+    tokens["${deviceId.trim()}|${role.trim()}"] =
+      DeviceAuthEntry(
+        token = token.trim(),
+        role = role.trim(),
+        scopes = scopes,
+        updatedAtMs = System.currentTimeMillis(),
+      )
   }
 
   override fun clearToken(deviceId: String, role: String) {
@@ -213,6 +219,144 @@ class GatewaySessionInvokeTest {
     }
   }
 
+  @Test
+  fun connect_storesPrimaryDeviceTokenFromSuccessfulSharedTokenConnect() = runBlocking {
+    val json = testJson()
+    val connected = CompletableDeferred<Unit>()
+    val lastDisconnect = AtomicReference("")
+    val server =
+      startGatewayServer(json) { webSocket, id, method, _ ->
+        when (method) {
+          "connect" -> {
+            webSocket.send(
+              connectResponseFrame(
+                id,
+                authJson = """{"deviceToken":"shared-node-token","role":"node","scopes":[]}""",
+              ),
+            )
+            webSocket.close(1000, "done")
+          }
+        }
+      }
+
+    val harness =
+      createNodeHarness(
+        connected = connected,
+        lastDisconnect = lastDisconnect,
+      ) { GatewaySession.InvokeResult.ok("""{"handled":true}""") }
+
+    try {
+      connectNodeSession(
+        session = harness.session,
+        port = server.port,
+        token = "shared-auth-token",
+        bootstrapToken = null,
+      )
+      awaitConnectedOrThrow(connected, lastDisconnect, server)
+
+      val deviceId = DeviceIdentityStore(RuntimeEnvironment.getApplication()).loadOrCreate().deviceId
+      assertEquals("shared-node-token", harness.deviceAuthStore.loadToken(deviceId, "node"))
+      assertNull(harness.deviceAuthStore.loadToken(deviceId, "operator"))
+    } finally {
+      shutdownHarness(harness, server)
+    }
+  }
+
+  @Test
+  fun bootstrapConnect_storesAdditionalBoundedDeviceTokensOnTrustedTransport() = runBlocking {
+    val json = testJson()
+    val connected = CompletableDeferred<Unit>()
+    val lastDisconnect = AtomicReference("")
+    val server =
+      startGatewayServer(json) { webSocket, id, method, _ ->
+        when (method) {
+          "connect" -> {
+            webSocket.send(
+              connectResponseFrame(
+                id,
+                authJson =
+                  """{"deviceToken":"bootstrap-node-token","role":"node","scopes":[],"deviceTokens":[{"deviceToken":"bootstrap-operator-token","role":"operator","scopes":["operator.admin","operator.approvals","operator.read","operator.talk.secrets","operator.write"]}]}""",
+              ),
+            )
+            webSocket.close(1000, "done")
+          }
+        }
+      }
+
+    val harness =
+      createNodeHarness(
+        connected = connected,
+        lastDisconnect = lastDisconnect,
+      ) { GatewaySession.InvokeResult.ok("""{"handled":true}""") }
+
+    try {
+      connectNodeSession(
+        session = harness.session,
+        port = server.port,
+        token = null,
+        bootstrapToken = "bootstrap-token",
+      )
+      awaitConnectedOrThrow(connected, lastDisconnect, server)
+
+      val deviceId = DeviceIdentityStore(RuntimeEnvironment.getApplication()).loadOrCreate().deviceId
+      val nodeEntry = harness.deviceAuthStore.loadEntry(deviceId, "node")
+      val operatorEntry = harness.deviceAuthStore.loadEntry(deviceId, "operator")
+      assertEquals("bootstrap-node-token", nodeEntry?.token)
+      assertEquals(emptyList<String>(), nodeEntry?.scopes)
+      assertEquals("bootstrap-operator-token", operatorEntry?.token)
+      assertEquals(
+        listOf("operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"),
+        operatorEntry?.scopes,
+      )
+    } finally {
+      shutdownHarness(harness, server)
+    }
+  }
+
+  @Test
+  fun nonBootstrapConnect_ignoresAdditionalBootstrapDeviceTokens() = runBlocking {
+    val json = testJson()
+    val connected = CompletableDeferred<Unit>()
+    val lastDisconnect = AtomicReference("")
+    val server =
+      startGatewayServer(json) { webSocket, id, method, _ ->
+        when (method) {
+          "connect" -> {
+            webSocket.send(
+              connectResponseFrame(
+                id,
+                authJson =
+                  """{"deviceToken":"shared-node-token","role":"node","scopes":[],"deviceTokens":[{"deviceToken":"shared-operator-token","role":"operator","scopes":["operator.approvals","operator.read"]}]}""",
+              ),
+            )
+            webSocket.close(1000, "done")
+          }
+        }
+      }
+
+    val harness =
+      createNodeHarness(
+        connected = connected,
+        lastDisconnect = lastDisconnect,
+      ) { GatewaySession.InvokeResult.ok("""{"handled":true}""") }
+
+    try {
+      connectNodeSession(
+        session = harness.session,
+        port = server.port,
+        token = "shared-auth-token",
+        bootstrapToken = null,
+      )
+      awaitConnectedOrThrow(connected, lastDisconnect, server)
+
+      val deviceId = DeviceIdentityStore(RuntimeEnvironment.getApplication()).loadOrCreate().deviceId
+      assertEquals("shared-node-token", harness.deviceAuthStore.loadToken(deviceId, "node"))
+      assertNull(harness.deviceAuthStore.loadToken(deviceId, "operator"))
+    } finally {
+      shutdownHarness(harness, server)
+    }
+  }
+
   @Test
   fun nodeInvokeRequest_roundTripsInvokeResult() = runBlocking {
     val handshakeOrigin = AtomicReference<String?>(null)
@@ -470,9 +614,14 @@ class GatewaySessionInvokeTest {
     }
   }
 
-  private fun connectResponseFrame(id: String, canvasHostUrl: String? = null): String {
+  private fun connectResponseFrame(
+    id: String,
+    canvasHostUrl: String? = null,
+    authJson: String? = null,
+  ): String {
     val canvas = canvasHostUrl?.let { "\"canvasHostUrl\":\"$it\"," } ?: ""
-    return """{"type":"res","id":"$id","ok":true,"payload":{$canvas"snapshot":{"sessionDefaults":{"mainSessionKey":"main"}}}}"""
+    val auth = authJson?.let { "\"auth\":$it," } ?: ""
+    return """{"type":"res","id":"$id","ok":true,"payload":{$canvas$auth"snapshot":{"sessionDefaults":{"mainSessionKey":"main"}}}}"""
   }
 
   private fun startGatewayServer(

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/node/ConnectionManagerTest.kt

@@ -11,6 +11,7 @@ import ai.openclaw.app.protocol.OpenClawMotionCommand
 import ai.openclaw.app.protocol.OpenClawSmsCommand
 import ai.openclaw.app.gateway.GatewayEndpoint
 import ai.openclaw.app.gateway.isLoopbackGatewayHost
+import ai.openclaw.app.gateway.isPrivateLanGatewayHost
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNull
@@ -107,12 +108,26 @@ class ConnectionManagerTest {
   }
 
   @Test
-  fun resolveTlsParamsForEndpoint_discoveryNonLoopbackWithoutHintsStillRequiresTls() {
+  fun resolveTlsParamsForEndpoint_manualPrivateLanCanStayCleartextWhenToggleIsOff() {
+    val endpoint = GatewayEndpoint.manual(host = "192.168.1.20", port = 18789)
+
+    val params =
+      ConnectionManager.resolveTlsParamsForEndpoint(
+        endpoint,
+        storedFingerprint = null,
+        manualTlsEnabled = false,
+      )
+
+    assertNull(params)
+  }
+
+  @Test
+  fun resolveTlsParamsForEndpoint_discoveryTailnetWithoutHintsStillRequiresTls() {
     val endpoint =
       GatewayEndpoint(
         stableId = "_openclaw-gw._tcp.|local.|Test",
         name = "Test",
-        host = "10.0.0.2",
+        host = "100.64.0.9",
         port = 18789,
         tlsEnabled = false,
         tlsFingerprintSha256 = null,
@@ -130,6 +145,28 @@ class ConnectionManagerTest {
     assertEquals(false, params?.allowTOFU)
   }
 
+  @Test
+  fun resolveTlsParamsForEndpoint_discoveryPrivateLanWithoutHintsCanStayCleartext() {
+    val endpoint =
+      GatewayEndpoint(
+        stableId = "_openclaw-gw._tcp.|local.|Test",
+        name = "Test",
+        host = "192.168.1.20",
+        port = 18789,
+        tlsEnabled = false,
+        tlsFingerprintSha256 = null,
+      )
+
+    val params =
+      ConnectionManager.resolveTlsParamsForEndpoint(
+        endpoint,
+        storedFingerprint = null,
+        manualTlsEnabled = false,
+      )
+
+    assertNull(params)
+  }
+
   @Test
   fun resolveTlsParamsForEndpoint_discoveryLoopbackWithoutHintsCanStayCleartext() {
     val endpoint =
@@ -202,6 +239,14 @@ class ConnectionManagerTest {
     assertFalse(isLoopbackGatewayHost("10.0.2.2", allowEmulatorBridgeAlias = false))
   }
 
+  @Test
+  fun isPrivateLanGatewayHost_acceptsLanHostsButRejectsTailnetHosts() {
+    assertTrue(isPrivateLanGatewayHost("192.168.1.20"))
+    assertTrue(isPrivateLanGatewayHost("gateway.local"))
+    assertFalse(isPrivateLanGatewayHost("100.64.0.9"))
+    assertFalse(isPrivateLanGatewayHost("gateway.tailnet.ts.net"))
+  }
+
   @Test
   fun resolveTlsParamsForEndpoint_discoveryIpv6LoopbackWithoutHintsCanStayCleartext() {
     val endpoint =

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/ui/GatewayConfigResolverTest.kt

@@ -31,6 +31,13 @@ class GatewayConfigResolverTest {
     assertNull(parsed)
   }
 
+  @Test
+  fun parseGatewayEndpointRejectsTailnetCleartextWsUrls() {
+    val parsed = parseGatewayEndpoint("ws://100.64.0.9:18789")
+
+    assertNull(parsed)
+  }
+
   @Test
   fun parseGatewayEndpointOmitsExplicitDefaultTlsPortFromDisplayUrl() {
     val parsed = parseGatewayEndpoint("https://gateway.example:443")
@@ -91,6 +98,36 @@ class GatewayConfigResolverTest {
     )
   }
 
+  @Test
+  fun parseGatewayEndpointAllowsPrivateLanCleartextWsUrls() {
+    val parsed = parseGatewayEndpoint("ws://192.168.1.20:18789")
+
+    assertEquals(
+      GatewayEndpointConfig(
+        host = "192.168.1.20",
+        port = 18789,
+        tls = false,
+        displayUrl = "http://192.168.1.20:18789",
+      ),
+      parsed,
+    )
+  }
+
+  @Test
+  fun parseGatewayEndpointAllowsMdnsCleartextWsUrls() {
+    val parsed = parseGatewayEndpoint("ws://gateway.local:18789")
+
+    assertEquals(
+      GatewayEndpointConfig(
+        host = "gateway.local",
+        port = 18789,
+        tls = false,
+        displayUrl = "http://gateway.local:18789",
+      ),
+      parsed,
+    )
+  }
+
   @Test
   fun parseGatewayEndpointAllowsIpv6LoopbackCleartextWsUrls() {
     val parsed = parseGatewayEndpoint("ws://[::1]")
@@ -126,10 +163,23 @@ class GatewayConfigResolverTest {
   }
 
   @Test
-  fun parseGatewayEndpointRejectsLinkLocalIpv6ZoneCleartextWsUrls() {
+  fun parseGatewayEndpointAllowsLinkLocalIpv6ZoneCleartextWsUrls() {
     val parsed = parseGatewayEndpoint("ws://[fe80::1%25eth0]")
 
-    assertNull(parsed)
+    assertEquals("fe80::1%25eth0", parsed?.host)
+    assertEquals(18789, parsed?.port)
+    assertEquals(false, parsed?.tls)
+    assertEquals("http://[fe80::1%25eth0]:18789", parsed?.displayUrl)
+  }
+
+  @Test
+  fun parseGatewayEndpointAllowsSecureIpv6ZoneUrls() {
+    val parsed = parseGatewayEndpoint("wss://[fe80::1%25wlan0]:443")
+
+    assertEquals("fe80::1%25wlan0", parsed?.host)
+    assertEquals(443, parsed?.port)
+    assertEquals(true, parsed?.tls)
+    assertEquals("https://[fe80::1%25wlan0]", parsed?.displayUrl)
   }
 
   @Test
@@ -220,6 +270,41 @@ class GatewayConfigResolverTest {
     assertNull(resolved)
   }
 
+  @Test
+  fun resolveScannedSetupCodeResultFlagsInsecureRemoteGateway() {
+    val setupCode =
+      encodeSetupCode("""{"url":"ws://attacker.example:18789","bootstrapToken":"bootstrap-1"}""")
+
+    val resolved = resolveScannedSetupCodeResult(setupCode)
+
+    assertNull(resolved.setupCode)
+    assertEquals(GatewayEndpointValidationError.INSECURE_REMOTE_URL, resolved.error)
+  }
+
+  @Test
+  fun parseGatewayEndpointResultFlagsInsecureRemoteGateway() {
+    val parsed = parseGatewayEndpointResult("ws://gateway.example:18789")
+
+    assertNull(parsed.config)
+    assertEquals(GatewayEndpointValidationError.INSECURE_REMOTE_URL, parsed.error)
+  }
+
+  @Test
+  fun parseGatewayEndpointResultAcceptsLanCleartextGateway() {
+    val parsed = parseGatewayEndpointResult("ws://192.168.1.20:18789")
+
+    assertEquals(
+      GatewayEndpointConfig(
+        host = "192.168.1.20",
+        port = 18789,
+        tls = false,
+        displayUrl = "http://192.168.1.20:18789",
+      ),
+      parsed.config,
+    )
+    assertNull(parsed.error)
+  }
+
   @Test
   fun decodeGatewaySetupCodeParsesBootstrapToken() {
     val setupCode =
@@ -358,7 +443,7 @@ class GatewayConfigResolverTest {
   }
 
   @Test
-  fun resolveGatewayConnectConfigRejectsNonLoopbackManualCleartextEndpoint() {
+  fun resolveGatewayConnectConfigAllowsPrivateLanManualCleartextEndpoint() {
     val resolved =
       resolveGatewayConnectConfig(
         useSetupCode = false,
@@ -374,7 +459,9 @@ class GatewayConfigResolverTest {
         fallbackPassword = "",
       )
 
-    assertNull(resolved)
+    assertEquals("192.168.31.100", resolved?.host)
+    assertEquals(18789, resolved?.port)
+    assertEquals(false, resolved?.tls)
   }
 
   private fun encodeSetupCode(payloadJson: String): String {

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/ios/Config/Version.xcconfig

@@ -1,8 +1,8 @@
 // Shared iOS version defaults.
 // Generated overrides live in build/Version.xcconfig (git-ignored).
 
-OPENCLAW_GATEWAY_VERSION = 2026.4.3
-OPENCLAW_MARKETING_VERSION = 2026.4.3
-OPENCLAW_BUILD_VERSION = 2026040301
+OPENCLAW_GATEWAY_VERSION = 2026.4.4
+OPENCLAW_MARKETING_VERSION = 2026.4.4
+OPENCLAW_BUILD_VERSION = 2026040401
 
 #include? "../build/Version.xcconfig"

apps/ios/Sources/Gateway/ExecApprovalPromptDialog.swift

@@ -1,196 +0,0 @@
-import SwiftUI
-
-private struct ExecApprovalPromptDialogModifier: ViewModifier {
-    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
-    @Environment(\.colorScheme) private var colorScheme
-
-    func body(content: Content) -> some View {
-        content
-            .overlay {
-                if let prompt = self.appModel.pendingExecApprovalPrompt {
-                    ZStack {
-                        Color.black.opacity(0.38)
-                            .ignoresSafeArea()
-
-                        ExecApprovalPromptCard(
-                            prompt: prompt,
-                            isResolving: self.appModel.pendingExecApprovalPromptResolving,
-                            errorText: self.appModel.pendingExecApprovalPromptErrorText,
-                            brighten: self.colorScheme == .light,
-                            onAllowOnce: {
-                                Task {
-                                    await self.appModel.resolvePendingExecApprovalPrompt(decision: "allow-once")
-                                }
-                            },
-                            onAllowAlways: {
-                                Task {
-                                    await self.appModel.resolvePendingExecApprovalPrompt(decision: "allow-always")
-                                }
-                            },
-                            onDeny: {
-                                Task {
-                                    await self.appModel.resolvePendingExecApprovalPrompt(decision: "deny")
-                                }
-                            },
-                            onCancel: {
-                                self.appModel.dismissPendingExecApprovalPrompt()
-                            })
-                            .padding(.horizontal, 20)
-                            .frame(maxWidth: 460)
-                            .transition(.scale(scale: 0.98).combined(with: .opacity))
-                    }
-                    .zIndex(1)
-                }
-            }
-            .animation(.easeInOut(duration: 0.18), value: self.appModel.pendingExecApprovalPrompt?.id)
-    }
-}
-
-private struct ExecApprovalPromptCard: View {
-    let prompt: NodeAppModel.ExecApprovalPrompt
-    let isResolving: Bool
-    let errorText: String?
-    let brighten: Bool
-    let onAllowOnce: () -> Void
-    let onAllowAlways: () -> Void
-    let onDeny: () -> Void
-    let onCancel: () -> Void
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 14) {
-            VStack(alignment: .leading, spacing: 6) {
-                Text("Exec approval required")
-                    .font(.headline)
-                Text("OpenClaw opened from a notification. Review this exec request before continuing.")
-                    .font(.subheadline)
-                    .foregroundStyle(.secondary)
-            }
-
-            Text(self.prompt.commandText)
-                .font(.system(size: 15, weight: .regular, design: .monospaced))
-                .frame(maxWidth: .infinity, alignment: .leading)
-                .padding(10)
-                .background(.black.opacity(0.14), in: RoundedRectangle(cornerRadius: 12, style: .continuous))
-
-            VStack(alignment: .leading, spacing: 8) {
-                if let host = self.normalized(self.prompt.host) {
-                    ExecApprovalPromptMetadataRow(label: "Host", value: host)
-                }
-                if let nodeId = self.normalized(self.prompt.nodeId) {
-                    ExecApprovalPromptMetadataRow(label: "Node", value: nodeId)
-                }
-                if let agentId = self.normalized(self.prompt.agentId) {
-                    ExecApprovalPromptMetadataRow(label: "Agent", value: agentId)
-                }
-                if let expiresText = self.expiresText(self.prompt.expiresAtMs) {
-                    ExecApprovalPromptMetadataRow(label: "Expires", value: expiresText)
-                }
-            }
-
-            if let errorText = self.normalized(self.errorText) {
-                Text(errorText)
-                    .font(.footnote)
-                    .foregroundStyle(.red)
-            }
-
-            if self.isResolving {
-                HStack(spacing: 8) {
-                    ProgressView()
-                        .progressViewStyle(.circular)
-                    Text("Resolving…")
-                        .font(.footnote)
-                        .foregroundStyle(.secondary)
-                }
-            }
-
-            VStack(spacing: 10) {
-                Button {
-                    self.onAllowOnce()
-                } label: {
-                    Text("Allow Once")
-                        .frame(maxWidth: .infinity)
-                }
-                .buttonStyle(.borderedProminent)
-                .disabled(self.isResolving)
-
-                if self.prompt.allowsAllowAlways {
-                    Button {
-                        self.onAllowAlways()
-                    } label: {
-                        Text("Allow Always")
-                            .frame(maxWidth: .infinity)
-                    }
-                    .buttonStyle(.bordered)
-                    .disabled(self.isResolving)
-                }
-
-                HStack(spacing: 10) {
-                    Button(role: .destructive) {
-                        self.onDeny()
-                    } label: {
-                        Text("Deny")
-                            .frame(maxWidth: .infinity)
-                    }
-                    .buttonStyle(.bordered)
-                    .disabled(self.isResolving)
-
-                    Button(role: .cancel) {
-                        self.onCancel()
-                    } label: {
-                        Text("Cancel")
-                            .frame(maxWidth: .infinity)
-                    }
-                    .buttonStyle(.bordered)
-                    .disabled(self.isResolving)
-                }
-            }
-            .controlSize(.large)
-            .frame(maxWidth: .infinity)
-        }
-        .statusGlassCard(brighten: self.brighten, verticalPadding: 18, horizontalPadding: 18)
-    }
-
-    private func normalized(_ value: String?) -> String? {
-        let trimmed = (value ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
-        return trimmed.isEmpty ? nil : trimmed
-    }
-
-    private func expiresText(_ expiresAtMs: Int?) -> String? {
-        guard let expiresAtMs else { return nil }
-        let remainingSeconds = Int((Double(expiresAtMs) / 1000.0) - Date().timeIntervalSince1970)
-        if remainingSeconds <= 0 {
-            return "expired"
-        }
-        if remainingSeconds < 60 {
-            return "under a minute"
-        }
-        if remainingSeconds < 3600 {
-            let minutes = Int(ceil(Double(remainingSeconds) / 60.0))
-            return minutes == 1 ? "about 1 minute" : "about \(minutes) minutes"
-        }
-        let hours = Int(ceil(Double(remainingSeconds) / 3600.0))
-        return hours == 1 ? "about 1 hour" : "about \(hours) hours"
-    }
-}
-
-private struct ExecApprovalPromptMetadataRow: View {
-    let label: String
-    let value: String
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 2) {
-            Text(self.label)
-                .font(.caption)
-                .foregroundStyle(.secondary)
-            Text(self.value)
-                .font(.footnote)
-                .textSelection(.enabled)
-        }
-    }
-}
-
-extension View {
-    func execApprovalPromptDialog() -> some View {
-        self.modifier(ExecApprovalPromptDialogModifier())
-    }
-}

apps/ios/Sources/Model/NodeAppModel.swift

@@ -61,35 +61,11 @@ final class NodeAppModel {
         let request: AgentDeepLink
     }
 
-    struct ExecApprovalPrompt: Identifiable, Equatable {
-        let id: String
-        let commandText: String
-        let allowedDecisions: [String]
-        let host: String?
-        let nodeId: String?
-        let agentId: String?
-        let expiresAtMs: Int?
-
-        var allowsAllowAlways: Bool {
-            self.allowedDecisions.contains("allow-always")
-        }
-    }
-
-    private enum ExecApprovalResolutionOutcome {
-        case resolved
-        case stale
-        case unavailable
-        case failed(message: String)
-    }
-
     private let deepLinkLogger = Logger(subsystem: "ai.openclaw.ios", category: "DeepLink")
     private let pushWakeLogger = Logger(subsystem: "ai.openclaw.ios", category: "PushWake")
     private let pendingActionLogger = Logger(subsystem: "ai.openclaw.ios", category: "PendingAction")
     private let locationWakeLogger = Logger(subsystem: "ai.openclaw.ios", category: "LocationWake")
     private let watchReplyLogger = Logger(subsystem: "ai.openclaw.ios", category: "WatchReply")
-    private let execApprovalNotificationLogger = Logger(
-        subsystem: "ai.openclaw.ios",
-        category: "ExecApprovalNotification")
     enum CameraHUDKind {
         case photo
         case recording
@@ -122,9 +98,6 @@ final class NodeAppModel {
     var lastShareEventText: String = "No share events yet."
     var openChatRequestID: Int = 0
     private(set) var pendingAgentDeepLinkPrompt: AgentDeepLinkPrompt?
-    private(set) var pendingExecApprovalPrompt: ExecApprovalPrompt?
-    private(set) var pendingExecApprovalPromptResolving: Bool = false
-    private(set) var pendingExecApprovalPromptErrorText: String?
     private var queuedAgentDeepLinkPrompt: AgentDeepLinkPrompt?
     private var lastAgentDeepLinkPromptAt: Date = .distantPast
     @ObservationIgnored private var queuedAgentDeepLinkPromptTask: Task<Void, Never>?
@@ -1984,17 +1957,20 @@ private extension NodeAppModel {
                     continue
                 }
 
+                let reconnectAuth = self.currentGatewayReconnectAuth(
+                    fallbackToken: token,
+                    fallbackBootstrapToken: bootstrapToken,
+                    fallbackPassword: password)
                 let effectiveClientId =
                     GatewaySettingsStore.loadGatewayClientIdOverride(stableID: stableID) ?? nodeOptions.clientId
                 let operatorOptions = self.makeOperatorConnectOptions(
                     clientId: effectiveClientId,
-                    displayName: nodeOptions.clientDisplayName)
+                    displayName: nodeOptions.clientDisplayName,
+                    includeApprovalScope: self.shouldRequestOperatorApprovalScope(
+                        token: reconnectAuth.token,
+                        password: reconnectAuth.password))
 
                 do {
-                    let reconnectAuth = self.currentGatewayReconnectAuth(
-                        fallbackToken: token,
-                        fallbackBootstrapToken: bootstrapToken,
-                        fallbackPassword: password)
                     try await self.operatorGateway.connect(
                         url: url,
                         token: reconnectAuth.token,
@@ -2293,10 +2269,47 @@ private extension NodeAppModel {
         }
     }
 
-    func makeOperatorConnectOptions(clientId: String, displayName: String?) -> GatewayConnectOptions {
-        GatewayConnectOptions(
+    func shouldRequestOperatorApprovalScope(token: String?, password: String?) -> Bool {
+        let identity = DeviceIdentityStore.loadOrCreate()
+        let storedOperatorScopes = DeviceAuthStore
+            .loadToken(deviceId: identity.deviceId, role: "operator")?
+            .scopes ?? []
+        return Self.shouldRequestOperatorApprovalScope(
+            token: token,
+            password: password,
+            storedOperatorScopes: storedOperatorScopes)
+    }
+
+    nonisolated static func shouldRequestOperatorApprovalScope(
+        token: String?,
+        password: String?,
+        storedOperatorScopes: [String]
+    ) -> Bool {
+        let trimmedToken = token?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedToken.isEmpty {
+            return true
+        }
+        let trimmedPassword = password?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedPassword.isEmpty {
+            return true
+        }
+        return storedOperatorScopes.contains("operator.approvals")
+    }
+
+    func makeOperatorConnectOptions(
+        clientId: String,
+        displayName: String?,
+        includeApprovalScope: Bool
+    ) -> GatewayConnectOptions {
+        var scopes = ["operator.read", "operator.write", "operator.talk.secrets"]
+        // Preserve reconnect compatibility for older paired operator tokens that were
+        // approved before iOS requested operator.approvals by default.
+        if includeApprovalScope {
+            scopes.append("operator.approvals")
+        }
+        return GatewayConnectOptions(
             role: "operator",
-            scopes: ["operator.read", "operator.write", "operator.approvals", "operator.talk.secrets"],
+            scopes: scopes,
             caps: [],
             commands: [],
             permissions: [:],
@@ -2594,19 +2607,6 @@ extension NodeAppModel {
             + "backgrounded=\(self.isBackgrounded) "
             + "autoReconnect=\(self.gatewayAutoReconnectEnabled)"
         self.pushWakeLogger.info("\(receivedMessage, privacy: .public)")
-
-        if await ExecApprovalNotificationBridge.handleResolvedPushIfNeeded(
-            userInfo: userInfo,
-            notificationCenter: self.notificationCenter)
-        {
-            if let approvalId = ExecApprovalNotificationBridge.approvalID(from: userInfo) {
-                self.clearPendingExecApprovalPromptIfMatches(approvalId)
-            }
-            self.execApprovalNotificationLogger.info(
-                "Handled exec approval cleanup push wakeId=\(wakeId, privacy: .public)")
-            return true
-        }
-
         let result = await self.reconnectGatewaySessionsForSilentPushIfNeeded(wakeId: wakeId)
         let outcomeMessage =
             "Silent push outcome wakeId=\(wakeId) "
@@ -2779,203 +2779,6 @@ extension NodeAppModel {
         return "unknown"
     }
 
-    private struct ExecApprovalGetRequest: Encodable {
-        var id: String
-    }
-
-    private struct ExecApprovalResolveRequest: Encodable {
-        var id: String
-        var decision: String
-    }
-
-    private struct ExecApprovalGetResponse: Decodable {
-        var id: String
-        var commandText: String
-        var allowedDecisions: [String]
-        var host: String?
-        var nodeId: String?
-        var agentId: String?
-        var expiresAtMs: Int?
-    }
-
-    func presentExecApprovalNotificationPrompt(_ prompt: ExecApprovalNotificationPrompt) async {
-        let approvalId = prompt.approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !approvalId.isEmpty else { return }
-
-        self.pendingExecApprovalPromptResolving = true
-        self.pendingExecApprovalPromptErrorText = nil
-
-        let fetchedPrompt = await self.fetchExecApprovalPrompt(approvalId: approvalId)
-        self.pendingExecApprovalPromptResolving = false
-        switch fetchedPrompt {
-        case let .loaded(fetchedPrompt):
-            self.presentFetchedExecApprovalPrompt(fetchedPrompt)
-        case .stale:
-            await ExecApprovalNotificationBridge.removeNotifications(
-                forApprovalID: approvalId,
-                notificationCenter: self.notificationCenter)
-            self.dismissPendingExecApprovalPrompt()
-        case let .failed(message):
-            self.execApprovalNotificationLogger.error(
-                "Exec approval prompt fetch failed id=\(approvalId, privacy: .public) reason=\(message, privacy: .public)")
-        }
-    }
-
-    private enum ExecApprovalPromptFetchOutcome {
-        case loaded(ExecApprovalPrompt)
-        case stale
-        case failed(message: String)
-    }
-
-    private func presentFetchedExecApprovalPrompt(_ prompt: ExecApprovalPrompt) {
-        self.pendingExecApprovalPrompt = prompt
-        self.pendingExecApprovalPromptResolving = false
-        self.pendingExecApprovalPromptErrorText = nil
-    }
-
-    private static func makeExecApprovalPrompt(from details: ExecApprovalGetResponse) -> ExecApprovalPrompt? {
-        let approvalId = details.id.trimmingCharacters(in: .whitespacesAndNewlines)
-        let commandText = details.commandText.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !approvalId.isEmpty, !commandText.isEmpty else { return nil }
-        return ExecApprovalPrompt(
-            id: approvalId,
-            commandText: commandText,
-            allowedDecisions: details.allowedDecisions.compactMap { decision in
-                let trimmed = decision.trimmingCharacters(in: .whitespacesAndNewlines)
-                return trimmed.isEmpty ? nil : trimmed
-            },
-            host: details.host?.trimmingCharacters(in: .whitespacesAndNewlines),
-            nodeId: details.nodeId?.trimmingCharacters(in: .whitespacesAndNewlines),
-            agentId: details.agentId?.trimmingCharacters(in: .whitespacesAndNewlines),
-            expiresAtMs: details.expiresAtMs)
-    }
-
-    private func fetchExecApprovalPrompt(approvalId: String) async -> ExecApprovalPromptFetchOutcome {
-        let connected = await self.ensureOperatorApprovalConnection(timeoutMs: 12_000)
-        guard connected else {
-            return .failed(message: "operator_not_connected")
-        }
-
-        do {
-            let payloadJSON = try Self.encodePayload(ExecApprovalGetRequest(id: approvalId))
-            let response = try await self.operatorGateway.request(
-                method: "exec.approval.get",
-                paramsJSON: payloadJSON,
-                timeoutSeconds: 12)
-            let details = try JSONDecoder().decode(ExecApprovalGetResponse.self, from: response)
-            guard let prompt = Self.makeExecApprovalPrompt(from: details) else {
-                return .failed(message: "invalid_prompt_payload")
-            }
-            return .loaded(prompt)
-        } catch {
-            if Self.isApprovalNotificationStaleError(error) {
-                return .stale
-            }
-            return .failed(message: error.localizedDescription)
-        }
-    }
-
-    func dismissPendingExecApprovalPrompt() {
-        self.pendingExecApprovalPrompt = nil
-        self.pendingExecApprovalPromptResolving = false
-        self.pendingExecApprovalPromptErrorText = nil
-    }
-
-    func dismissPendingExecApprovalPrompt(approvalId: String) {
-        self.clearPendingExecApprovalPromptIfMatches(approvalId)
-    }
-
-    func resolvePendingExecApprovalPrompt(decision: String) async {
-        guard let prompt = self.pendingExecApprovalPrompt else { return }
-        let normalizedDecision = decision.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !normalizedDecision.isEmpty else { return }
-
-        self.pendingExecApprovalPromptResolving = true
-        self.pendingExecApprovalPromptErrorText = nil
-        let outcome = await self.resolveExecApprovalNotificationDecision(
-            approvalId: prompt.id,
-            decision: normalizedDecision)
-        switch outcome {
-        case .resolved, .stale, .unavailable:
-            break
-        case let .failed(message):
-            self.pendingExecApprovalPromptResolving = false
-            self.pendingExecApprovalPromptErrorText = message
-        }
-    }
-
-    private func resolveExecApprovalNotificationDecision(
-        approvalId: String,
-        decision: String
-    ) async -> ExecApprovalResolutionOutcome {
-        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
-        let normalizedDecision = decision.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !normalizedApprovalID.isEmpty, !normalizedDecision.isEmpty else {
-            return .failed(message: "Invalid approval request.")
-        }
-
-        let connected = await self.ensureOperatorApprovalConnection(timeoutMs: 12_000)
-        guard connected else {
-            self.execApprovalNotificationLogger.error(
-                "Exec approval action failed id=\(normalizedApprovalID, privacy: .public): operator not connected")
-            return .failed(message: "OpenClaw couldn't connect to the gateway operator session.")
-        }
-
-        do {
-            let payloadJSON = try Self.encodePayload(
-                ExecApprovalResolveRequest(id: normalizedApprovalID, decision: normalizedDecision))
-            _ = try await self.operatorGateway.request(
-                method: "exec.approval.resolve",
-                paramsJSON: payloadJSON,
-                timeoutSeconds: 12)
-            await ExecApprovalNotificationBridge.removeNotifications(
-                forApprovalID: normalizedApprovalID,
-                notificationCenter: self.notificationCenter)
-            self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
-            return .resolved
-        } catch {
-            if Self.isApprovalNotificationStaleError(error) {
-                await ExecApprovalNotificationBridge.removeNotifications(
-                    forApprovalID: normalizedApprovalID,
-                    notificationCenter: self.notificationCenter)
-                self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
-                return .stale
-            }
-            if Self.isApprovalNotificationUnavailableError(error) {
-                await ExecApprovalNotificationBridge.removeNotifications(
-                    forApprovalID: normalizedApprovalID,
-                    notificationCenter: self.notificationCenter)
-                self.clearPendingExecApprovalPromptIfMatches(normalizedApprovalID)
-                return .unavailable
-            }
-            let logMessage =
-                "Exec approval action failed id=\(normalizedApprovalID) error=\(error.localizedDescription)"
-            self.execApprovalNotificationLogger.error("\(logMessage, privacy: .public)")
-            return .failed(
-                message: "OpenClaw couldn't resolve this approval right now. Try again.")
-        }
-    }
-
-    private func clearPendingExecApprovalPromptIfMatches(_ approvalId: String) {
-        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard self.pendingExecApprovalPrompt?.id == normalizedApprovalID else { return }
-        self.dismissPendingExecApprovalPrompt()
-    }
-
-    private static func isApprovalNotificationStaleError(_ error: Error) -> Bool {
-        guard let gatewayError = error as? GatewayResponseError else { return false }
-        let message = gatewayError.message.lowercased()
-        return gatewayError.code == "INVALID_REQUEST"
-            && (message.contains("unknown or expired approval id") || message.contains("approval_not_found"))
-    }
-
-    private static func isApprovalNotificationUnavailableError(_ error: Error) -> Bool {
-        guard let gatewayError = error as? GatewayResponseError else { return false }
-        let message = gatewayError.message.lowercased()
-        return gatewayError.code == "INVALID_REQUEST"
-            && message.contains("allow-always is unavailable")
-    }
-
     private struct SilentPushWakeAttemptResult {
         var applied: Bool
         var reason: String
@@ -2987,51 +2790,14 @@ extension NodeAppModel {
         let pollIntervalNs = UInt64(max(50, pollMs)) * 1_000_000
         let deadline = Date().addingTimeInterval(Double(clampedTimeoutMs) / 1000.0)
         while Date() < deadline {
-            if Task.isCancelled {
-                return false
-            }
             if await self.isGatewayConnected() {
                 return true
             }
-            do {
-                try await Task.sleep(nanoseconds: pollIntervalNs)
-            } catch {
-                return false
-            }
+            try? await Task.sleep(nanoseconds: pollIntervalNs)
         }
         return await self.isGatewayConnected()
     }
 
-    private func waitForOperatorConnection(timeoutMs: Int, pollMs: Int) async -> Bool {
-        let clampedTimeoutMs = max(0, timeoutMs)
-        let pollIntervalNs = UInt64(max(50, pollMs)) * 1_000_000
-        let deadline = Date().addingTimeInterval(Double(clampedTimeoutMs) / 1000.0)
-        while Date() < deadline {
-            if Task.isCancelled {
-                return false
-            }
-            if await self.isOperatorConnected() {
-                return true
-            }
-            do {
-                try await Task.sleep(nanoseconds: pollIntervalNs)
-            } catch {
-                return false
-            }
-        }
-        return await self.isOperatorConnected()
-    }
-
-    private func ensureOperatorApprovalConnection(timeoutMs: Int) async -> Bool {
-        if await self.isOperatorConnected() {
-            return true
-        }
-        if let cfg = self.activeGatewayConnectConfig {
-            self.applyGatewayConnectConfig(cfg)
-        }
-        return await self.waitForOperatorConnection(timeoutMs: timeoutMs, pollMs: 250)
-    }
-
     private func reconnectGatewaySessionsForSilentPushIfNeeded(
         wakeId: String
     ) async -> SilentPushWakeAttemptResult {
@@ -3433,41 +3199,13 @@ extension NodeAppModel {
 
     func _test_makeOperatorConnectOptions(
         clientId: String,
-        displayName: String?
+        displayName: String?,
+        includeApprovalScope: Bool
     ) -> GatewayConnectOptions {
-        self.makeOperatorConnectOptions(clientId: clientId, displayName: displayName)
-    }
-
-    func _test_presentExecApprovalPrompt(_ prompt: ExecApprovalPrompt) {
-        self.presentFetchedExecApprovalPrompt(prompt)
-    }
-
-    func _test_dismissPendingExecApprovalPrompt() {
-        self.dismissPendingExecApprovalPrompt()
-    }
-
-    func _test_pendingExecApprovalPrompt() -> ExecApprovalPrompt? {
-        self.pendingExecApprovalPrompt
-    }
-
-    static func _test_makeExecApprovalPrompt(
-        id: String,
-        commandText: String,
-        allowedDecisions: [String],
-        host: String?,
-        nodeId: String?,
-        agentId: String?,
-        expiresAtMs: Int?
-    ) -> ExecApprovalPrompt? {
-        self.makeExecApprovalPrompt(
-            from: ExecApprovalGetResponse(
-                id: id,
-                commandText: commandText,
-                allowedDecisions: allowedDecisions,
-                host: host,
-                nodeId: nodeId,
-                agentId: agentId,
-                expiresAtMs: expiresAtMs))
+        self.makeOperatorConnectOptions(
+            clientId: clientId,
+            displayName: displayName,
+            includeApprovalScope: includeApprovalScope)
     }
 
     static func _test_currentDeepLinkKey() -> String {
@@ -3487,6 +3225,17 @@ extension NodeAppModel {
             hasStoredOperatorToken: hasStoredOperatorToken)
     }
 
+    nonisolated static func _test_shouldRequestOperatorApprovalScope(
+        token: String?,
+        password: String?,
+        storedOperatorScopes: [String]
+    ) -> Bool {
+        self.shouldRequestOperatorApprovalScope(
+            token: token,
+            password: password,
+            storedOperatorScopes: storedOperatorScopes)
+    }
+
     nonisolated static func _test_clearingBootstrapToken(
         in config: GatewayConnectConfig?
     ) -> GatewayConnectConfig? {
@@ -3510,6 +3259,7 @@ extension NodeAppModel {
                 clientDisplayName: nil),
             sessionBox: nil)
     }
+
 }
 #endif
 // swiftlint:enable type_body_length file_length

apps/ios/Sources/OpenClawApp.swift

@@ -13,8 +13,6 @@ private struct PendingWatchPromptAction {
     var sessionKey: String?
 }
 
-private typealias PendingExecApprovalPrompt = ExecApprovalNotificationPrompt
-
 @MainActor
 final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrency UNUserNotificationCenterDelegate {
     private let logger = Logger(subsystem: "ai.openclaw.ios", category: "Push")
@@ -23,7 +21,6 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
     private var backgroundWakeTask: Task<Bool, Never>?
     private var pendingAPNsDeviceToken: Data?
     private var pendingWatchPromptActions: [PendingWatchPromptAction] = []
-    private var pendingExecApprovalPrompts: [PendingExecApprovalPrompt] = []
 
     weak var appModel: NodeAppModel? {
         didSet {
@@ -47,15 +44,6 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
                     }
                 }
             }
-            if !self.pendingExecApprovalPrompts.isEmpty {
-                let pending = self.pendingExecApprovalPrompts
-                self.pendingExecApprovalPrompts.removeAll()
-                Task { @MainActor in
-                    for prompt in pending {
-                        await model.presentExecApprovalNotificationPrompt(prompt)
-                    }
-                }
-            }
         }
     }
 
@@ -92,17 +80,6 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
     {
         self.logger.info("APNs remote notification received keys=\(userInfo.keys.count, privacy: .public)")
         Task { @MainActor in
-            let notificationCenter = LiveNotificationCenter()
-            if await ExecApprovalNotificationBridge.handleResolvedPushIfNeeded(
-                userInfo: userInfo,
-                notificationCenter: notificationCenter)
-            {
-                if let approvalId = ExecApprovalNotificationBridge.approvalID(from: userInfo) {
-                    self.appModel?.dismissPendingExecApprovalPrompt(approvalId: approvalId)
-                }
-                completionHandler(.newData)
-                return
-            }
             guard let appModel = self.appModel else {
                 self.logger.info("APNs wake skipped: appModel unavailable")
                 self.scheduleBackgroundWakeRefresh(afterSeconds: 90, reason: "silent_push_no_model")
@@ -239,14 +216,6 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
             sessionKey: sessionKey)
     }
 
-    private static func parseExecApprovalPrompt(
-        from response: UNNotificationResponse) -> PendingExecApprovalPrompt?
-    {
-        ExecApprovalNotificationBridge.parsePrompt(
-            actionIdentifier: response.actionIdentifier,
-            userInfo: response.notification.request.content.userInfo)
-    }
-
     private func routeWatchPromptAction(_ action: PendingWatchPromptAction) async {
         guard let appModel = self.appModel else {
             self.pendingWatchPromptActions.append(action)
@@ -260,25 +229,13 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
         _ = await appModel.handleBackgroundRefreshWake(trigger: "watch_prompt_action")
     }
 
-    private func routeExecApprovalPrompt(_ prompt: PendingExecApprovalPrompt) {
-        guard let appModel = self.appModel else {
-            self.pendingExecApprovalPrompts.append(prompt)
-            return
-        }
-        Task { @MainActor in
-            await appModel.presentExecApprovalNotificationPrompt(prompt)
-        }
-    }
-
     func userNotificationCenter(
         _ center: UNUserNotificationCenter,
         willPresent notification: UNNotification,
         withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void)
     {
         let userInfo = notification.request.content.userInfo
-        if Self.isWatchPromptNotification(userInfo)
-            || ExecApprovalNotificationBridge.shouldPresentNotification(userInfo: userInfo)
-        {
+        if Self.isWatchPromptNotification(userInfo) {
             completionHandler([.banner, .list, .sound])
             return
         }
@@ -290,29 +247,18 @@ final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrenc
         didReceive response: UNNotificationResponse,
         withCompletionHandler completionHandler: @escaping () -> Void)
     {
-        if let action = Self.parseWatchPromptAction(from: response) {
-            Task { @MainActor [weak self] in
-                guard let self else {
-                    completionHandler()
-                    return
-                }
-                await self.routeWatchPromptAction(action)
-                completionHandler()
-            }
+        guard let action = Self.parseWatchPromptAction(from: response) else {
+            completionHandler()
             return
         }
-        if let prompt = Self.parseExecApprovalPrompt(from: response) {
-            Task { @MainActor [weak self] in
-                guard let self else {
-                    completionHandler()
-                    return
-                }
-                self.routeExecApprovalPrompt(prompt)
+        Task { @MainActor [weak self] in
+            guard let self else {
                 completionHandler()
+                return
             }
-            return
+            await self.routeWatchPromptAction(action)
+            completionHandler()
         }
-        completionHandler()
     }
 }
 

apps/ios/Sources/Push/ExecApprovalNotificationBridge.swift

@@ -1,92 +0,0 @@
-import Foundation
-import UserNotifications
-
-struct ExecApprovalNotificationPrompt: Sendable, Equatable {
-    let approvalId: String
-}
-
-enum ExecApprovalNotificationBridge {
-    static let requestedKind = "exec.approval.requested"
-    static let resolvedKind = "exec.approval.resolved"
-
-    private static let localRequestPrefix = "exec.approval."
-
-    static func shouldPresentNotification(userInfo: [AnyHashable: Any]) -> Bool {
-        self.payloadKind(userInfo: userInfo) == self.requestedKind
-    }
-
-    static func parsePrompt(
-        actionIdentifier: String,
-        userInfo: [AnyHashable: Any]
-    ) -> ExecApprovalNotificationPrompt?
-    {
-        guard actionIdentifier == UNNotificationDefaultActionIdentifier else { return nil }
-        guard self.payloadKind(userInfo: userInfo) == self.requestedKind else { return nil }
-        guard let approvalId = self.approvalID(from: userInfo) else { return nil }
-        return ExecApprovalNotificationPrompt(approvalId: approvalId)
-    }
-
-    @MainActor
-    static func handleResolvedPushIfNeeded(
-        userInfo: [AnyHashable: Any],
-        notificationCenter: NotificationCentering
-    ) async -> Bool
-    {
-        guard self.payloadKind(userInfo: userInfo) == self.resolvedKind,
-              let approvalId = self.approvalID(from: userInfo)
-        else {
-            return false
-        }
-
-        await self.removeNotifications(forApprovalID: approvalId, notificationCenter: notificationCenter)
-        return true
-    }
-
-    @MainActor
-    static func removeNotifications(
-        forApprovalID approvalId: String,
-        notificationCenter: NotificationCentering
-    ) async {
-        let normalizedID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !normalizedID.isEmpty else { return }
-
-        await notificationCenter.removePendingNotificationRequests(
-            withIdentifiers: [self.localRequestIdentifier(for: normalizedID)])
-
-        let delivered = await notificationCenter.deliveredNotifications()
-        let identifiers = delivered.compactMap { snapshot -> String? in
-            guard self.approvalID(from: snapshot.userInfo) == normalizedID else { return nil }
-            return snapshot.identifier
-        }
-        await notificationCenter.removeDeliveredNotifications(withIdentifiers: identifiers)
-    }
-
-    static func approvalID(from userInfo: [AnyHashable: Any]) -> String? {
-        let raw = self.openClawPayload(userInfo: userInfo)?["approvalId"] as? String
-        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        return trimmed.isEmpty ? nil : trimmed
-    }
-
-    private static func localRequestIdentifier(for approvalId: String) -> String {
-        "\(self.localRequestPrefix)\(approvalId)"
-    }
-
-    private static func payloadKind(userInfo: [AnyHashable: Any]) -> String {
-        let raw = self.openClawPayload(userInfo: userInfo)?["kind"] as? String
-        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        return trimmed.isEmpty ? "unknown" : trimmed
-    }
-
-    private static func openClawPayload(userInfo: [AnyHashable: Any]) -> [String: Any]? {
-        if let payload = userInfo["openclaw"] as? [String: Any] {
-            return payload
-        }
-        if let payload = userInfo["openclaw"] as? [AnyHashable: Any] {
-            return payload.reduce(into: [String: Any]()) { partialResult, pair in
-                guard let key = pair.key as? String else { return }
-                partialResult[key] = pair.value
-            }
-        }
-        return nil
-    }
-}

apps/ios/Sources/RootCanvas.swift

@@ -107,7 +107,6 @@ struct RootCanvas: View {
         }
         .gatewayTrustPromptAlert()
         .deepLinkAgentPromptAlert()
-        .execApprovalPromptDialog()
         .sheet(item: self.$presentedSheet) { sheet in
             switch sheet {
             case .settings:

apps/ios/Sources/Services/NotificationService.swift

@@ -1,11 +1,6 @@
 import Foundation
 import UserNotifications
 
-struct NotificationSnapshot: @unchecked Sendable {
-    let identifier: String
-    let userInfo: [AnyHashable: Any]
-}
-
 enum NotificationAuthorizationStatus: Sendable {
     case notDetermined
     case denied
@@ -18,9 +13,6 @@ protocol NotificationCentering: Sendable {
     func authorizationStatus() async -> NotificationAuthorizationStatus
     func requestAuthorization(options: UNAuthorizationOptions) async throws -> Bool
     func add(_ request: UNNotificationRequest) async throws
-    func removePendingNotificationRequests(withIdentifiers identifiers: [String]) async
-    func removeDeliveredNotifications(withIdentifiers identifiers: [String]) async
-    func deliveredNotifications() async -> [NotificationSnapshot]
 }
 
 struct LiveNotificationCenter: NotificationCentering, @unchecked Sendable {
@@ -63,27 +55,4 @@ struct LiveNotificationCenter: NotificationCentering, @unchecked Sendable {
             }
         }
     }
-
-    func removePendingNotificationRequests(withIdentifiers identifiers: [String]) async {
-        guard !identifiers.isEmpty else { return }
-        self.center.removePendingNotificationRequests(withIdentifiers: identifiers)
-    }
-
-    func removeDeliveredNotifications(withIdentifiers identifiers: [String]) async {
-        guard !identifiers.isEmpty else { return }
-        self.center.removeDeliveredNotifications(withIdentifiers: identifiers)
-    }
-
-    func deliveredNotifications() async -> [NotificationSnapshot] {
-        await withCheckedContinuation { continuation in
-            self.center.getDeliveredNotifications { notifications in
-                continuation.resume(
-                    returning: notifications.map { notification in
-                        NotificationSnapshot(
-                            identifier: notification.request.identifier,
-                            userInfo: notification.request.content.userInfo)
-                    })
-            }
-        }
-    }
 }

apps/ios/Tests/ExecApprovalNotificationBridgeTests.swift

@@ -1,86 +0,0 @@
-import Foundation
-import Testing
-import UserNotifications
-@testable import OpenClaw
-
-private final class MockNotificationCenter: NotificationCentering, @unchecked Sendable {
-    var authorization: NotificationAuthorizationStatus = .authorized
-    var addedRequests: [UNNotificationRequest] = []
-    var pendingRemovedIdentifiers: [[String]] = []
-    var deliveredRemovedIdentifiers: [[String]] = []
-    var delivered: [NotificationSnapshot] = []
-
-    func authorizationStatus() async -> NotificationAuthorizationStatus {
-        self.authorization
-    }
-
-    func requestAuthorization(options _: UNAuthorizationOptions) async throws -> Bool {
-        true
-    }
-
-    func add(_ request: UNNotificationRequest) async throws {
-        self.addedRequests.append(request)
-    }
-
-    func removePendingNotificationRequests(withIdentifiers identifiers: [String]) async {
-        self.pendingRemovedIdentifiers.append(identifiers)
-    }
-
-    func removeDeliveredNotifications(withIdentifiers identifiers: [String]) async {
-        self.deliveredRemovedIdentifiers.append(identifiers)
-    }
-
-    func deliveredNotifications() async -> [NotificationSnapshot] {
-        self.delivered
-    }
-}
-
-@Suite(.serialized) struct ExecApprovalNotificationBridgeTests {
-    @Test func parsePromptMapsDefaultNotificationTap() {
-        let prompt = ExecApprovalNotificationBridge.parsePrompt(
-            actionIdentifier: UNNotificationDefaultActionIdentifier,
-            userInfo: [
-                "openclaw": [
-                    "kind": ExecApprovalNotificationBridge.requestedKind,
-                    "approvalId": "approval-123",
-                ],
-            ])
-
-        #expect(prompt == ExecApprovalNotificationPrompt(approvalId: "approval-123"))
-    }
-
-    @Test @MainActor func handleResolvedPushRemovesMatchingNotifications() async {
-        let center = MockNotificationCenter()
-        center.delivered = [
-            NotificationSnapshot(
-                identifier: "remote-approval-1",
-                userInfo: [
-                    "openclaw": [
-                        "kind": ExecApprovalNotificationBridge.requestedKind,
-                        "approvalId": "approval-123",
-                    ],
-                ]),
-            NotificationSnapshot(
-                identifier: "remote-other",
-                userInfo: [
-                    "openclaw": [
-                        "kind": ExecApprovalNotificationBridge.requestedKind,
-                        "approvalId": "approval-999",
-                    ],
-                ]),
-        ]
-
-        let handled = await ExecApprovalNotificationBridge.handleResolvedPushIfNeeded(
-            userInfo: [
-                "openclaw": [
-                    "kind": ExecApprovalNotificationBridge.resolvedKind,
-                    "approvalId": "approval-123",
-                ],
-            ],
-            notificationCenter: center)
-
-        #expect(handled)
-        #expect(center.pendingRemovedIdentifiers == [["exec.approval.approval-123"]])
-        #expect(center.deliveredRemovedIdentifiers == [["remote-approval-1"]])
-    }
-}

apps/ios/Tests/GatewayConnectionControllerTests.swift

@@ -70,17 +70,50 @@ import UIKit
         }
     }
 
-    @Test @MainActor func operatorConnectOptionsRequestApprovalScope() {
+    @Test @MainActor func operatorConnectOptionsOnlyRequestApprovalScopeWhenEnabled() {
         let appModel = NodeAppModel()
-        let options = appModel._test_makeOperatorConnectOptions(
+        let withoutApprovalScope = appModel._test_makeOperatorConnectOptions(
             clientId: "openclaw-ios",
-            displayName: "OpenClaw iOS")
+            displayName: "OpenClaw iOS",
+            includeApprovalScope: false)
+        let withApprovalScope = appModel._test_makeOperatorConnectOptions(
+            clientId: "openclaw-ios",
+            displayName: "OpenClaw iOS",
+            includeApprovalScope: true)
 
-        #expect(options.role == "operator")
-        #expect(options.scopes.contains("operator.read"))
-        #expect(options.scopes.contains("operator.write"))
-        #expect(options.scopes.contains("operator.approvals"))
-        #expect(options.scopes.contains("operator.talk.secrets"))
+        #expect(withoutApprovalScope.role == "operator")
+        #expect(withoutApprovalScope.scopes.contains("operator.read"))
+        #expect(withoutApprovalScope.scopes.contains("operator.write"))
+        #expect(!withoutApprovalScope.scopes.contains("operator.approvals"))
+        #expect(withoutApprovalScope.scopes.contains("operator.talk.secrets"))
+
+        #expect(withApprovalScope.scopes.contains("operator.approvals"))
+    }
+
+    @Test func operatorApprovalScopeRequestsStayBackwardCompatible() {
+        #expect(
+            !NodeAppModel._test_shouldRequestOperatorApprovalScope(
+                token: nil,
+                password: nil,
+                storedOperatorScopes: ["operator.read", "operator.write", "operator.talk.secrets"])
+        )
+        #expect(
+            NodeAppModel._test_shouldRequestOperatorApprovalScope(
+                token: nil,
+                password: nil,
+                storedOperatorScopes: [
+                    "operator.approvals",
+                    "operator.read",
+                    "operator.write",
+                    "operator.talk.secrets",
+                ])
+        )
+        #expect(
+            NodeAppModel._test_shouldRequestOperatorApprovalScope(
+                token: "shared-token",
+                password: nil,
+                storedOperatorScopes: [])
+        )
     }
 
     @Test @MainActor func loadLastConnectionReadsSavedValues() {

apps/ios/Tests/NodeAppModelInvokeTests.swift

@@ -89,14 +89,6 @@ private final class MockBootstrapNotificationCenter: NotificationCentering, @unc
     }
 
     func add(_: UNNotificationRequest) async throws {}
-
-    func removePendingNotificationRequests(withIdentifiers _: [String]) async {}
-
-    func removeDeliveredNotifications(withIdentifiers _: [String]) async {}
-
-    func deliveredNotifications() async -> [NotificationSnapshot] {
-        []
-    }
 }
 
 @Suite(.serialized) struct NodeAppModelInvokeTests {
@@ -127,44 +119,6 @@ private final class MockBootstrapNotificationCenter: NotificationCentering, @unc
         #expect(appModel.mainSessionKey == "agent:agent-123:main")
     }
 
-    @Test @MainActor func execApprovalPromptPresentationTracksLatestNotificationTap() throws {
-        let appModel = NodeAppModel()
-        appModel._test_presentExecApprovalPrompt(
-            try #require(
-                NodeAppModel._test_makeExecApprovalPrompt(
-                    id: "approval-1",
-                    commandText: "echo first",
-                    allowedDecisions: ["allow-once", "deny"],
-                    host: "gateway",
-                    nodeId: nil,
-                    agentId: "main",
-                    expiresAtMs: 1)))
-
-        let firstPrompt = try #require(appModel._test_pendingExecApprovalPrompt())
-        #expect(firstPrompt.id == "approval-1")
-        #expect(firstPrompt.commandText == "echo first")
-        #expect(firstPrompt.allowsAllowAlways == false)
-
-        appModel._test_presentExecApprovalPrompt(
-            try #require(
-                NodeAppModel._test_makeExecApprovalPrompt(
-                    id: "approval-2",
-                    commandText: "echo second",
-                    allowedDecisions: ["allow-once", "allow-always", "deny"],
-                    host: "gateway",
-                    nodeId: "node-2",
-                    agentId: nil,
-                    expiresAtMs: 2)))
-
-        let secondPrompt = try #require(appModel._test_pendingExecApprovalPrompt())
-        #expect(secondPrompt.id == "approval-2")
-        #expect(secondPrompt.commandText == "echo second")
-        #expect(secondPrompt.allowsAllowAlways)
-
-        appModel._test_dismissPendingExecApprovalPrompt()
-        #expect(appModel._test_pendingExecApprovalPrompt() == nil)
-    }
-
     @Test func operatorLoopWaitsForBootstrapHandoffBeforeUsingStoredToken() {
         #expect(
             !NodeAppModel._test_shouldStartOperatorGatewayLoop(

apps/macos/Package.resolved

@@ -1,5 +1,5 @@
 {
-  "originHash" : "1c9c9d251b760ed3234ecff741a88eb4bf42315ad6f50ac7392b187cf226c16c",
+  "originHash" : "fb90e7b1977f43661ac91681d16da11f9ddd85630407ef170eaada0a6ee39972",
   "pins" : [
     {
       "identity" : "axorcist",
@@ -24,7 +24,7 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/steipete/ElevenLabsKit",
       "state" : {
-        "revision" : "c8679fbd37416a8780fe43be88a497ff16209e2d",
+        "revision" : "7e3c948d8340abe3977014f3de020edf221e9269",
         "version" : "0.1.0"
       }
     },

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

@@ -110,6 +110,7 @@ enum HostEnvSecurityPolicy {
         "PIP_TRUSTED_HOST",
         "UV_INDEX",
         "UV_INDEX_URL",
+        "UV_PYTHON",
         "UV_EXTRA_INDEX_URL",
         "UV_DEFAULT_INDEX",
         "DOCKER_HOST",

apps/macos/Sources/OpenClaw/Resources/Info.plist

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.4.3</string>
+    <string>2026.4.4</string>
     <key>CFBundleVersion</key>
-    <string>2026040301</string>
+    <string>2026040401</string>
     <key>CFBundleIconFile</key>
     <string>OpenClaw</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/OpenClawDiscovery/WideAreaGatewayDiscovery.swift

@@ -43,8 +43,8 @@ enum WideAreaGatewayDiscovery {
         guard let statusJson = context.tailscaleStatus(),
               !collectTailnetIPv4s(statusJson: statusJson).isEmpty,
               let discovery = loadWideAreaPtrRecords(
-            remaining: remaining,
-            dig: context.dig)
+                  remaining: remaining,
+                  dig: context.dig)
         else { return [] }
 
         let domainTrimmed = discovery.domainTrimmed

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"
     }
 }
 
@@ -2893,6 +2901,78 @@ public struct SkillsBinsResult: Codable, Sendable {
     }
 }
 
+public struct SkillsSearchParams: Codable, Sendable {
+    public let query: String?
+    public let limit: Int?
+
+    public init(
+        query: String?,
+        limit: Int?)
+    {
+        self.query = query
+        self.limit = limit
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case query
+        case limit
+    }
+}
+
+public struct SkillsSearchResult: Codable, Sendable {
+    public let results: [[String: AnyCodable]]
+
+    public init(
+        results: [[String: AnyCodable]])
+    {
+        self.results = results
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case results
+    }
+}
+
+public struct SkillsDetailParams: Codable, Sendable {
+    public let slug: String
+
+    public init(
+        slug: String)
+    {
+        self.slug = slug
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case slug
+    }
+}
+
+public struct SkillsDetailResult: Codable, Sendable {
+    public let skill: AnyCodable
+    public let latestversion: AnyCodable?
+    public let metadata: AnyCodable?
+    public let owner: AnyCodable?
+
+    public init(
+        skill: AnyCodable,
+        latestversion: AnyCodable?,
+        metadata: AnyCodable?,
+        owner: AnyCodable?)
+    {
+        self.skill = skill
+        self.latestversion = latestversion
+        self.metadata = metadata
+        self.owner = owner
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case skill
+        case latestversion = "latestVersion"
+        case metadata
+        case owner
+    }
+}
+
 public struct CronJob: Codable, Sendable {
     public let id: String
     public let agentid: String?

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift

@@ -588,6 +588,31 @@ public actor GatewayChannelActor {
             scopes: filteredScopes)
     }
 
+    private func persistIssuedDeviceToken(
+        authSource: GatewayAuthSource,
+        deviceId: String,
+        role: String,
+        token: String,
+        scopes: [String]
+    ) {
+        if authSource == .bootstrapToken {
+            guard self.shouldPersistBootstrapHandoffTokens() else {
+                return
+            }
+            self.persistBootstrapHandoffToken(
+                deviceId: deviceId,
+                role: role,
+                token: token,
+                scopes: scopes)
+            return
+        }
+        _ = DeviceAuthStore.storeToken(
+            deviceId: deviceId,
+            role: role,
+            token: token,
+            scopes: scopes)
+    }
+
     private func handleConnectResponse(
         _ res: ResponseFrame,
         identity: DeviceIdentity?,
@@ -618,18 +643,21 @@ public actor GatewayChannelActor {
         } else if let tick = ok.policy["tickIntervalMs"]?.value as? Int {
             self.tickIntervalMs = Double(tick)
         }
-        if let auth = ok.auth, let identity, self.shouldPersistBootstrapHandoffTokens() {
+        if let auth = ok.auth, let identity {
             if let deviceToken = auth["deviceToken"]?.value as? String {
                 let authRole = auth["role"]?.value as? String ?? role
                 let scopes = (auth["scopes"]?.value as? [ProtoAnyCodable])?
                     .compactMap { $0.value as? String } ?? []
-                self.persistBootstrapHandoffToken(
+                self.persistIssuedDeviceToken(
+                    authSource: self.lastAuthSource,
                     deviceId: identity.deviceId,
                     role: authRole,
                     token: deviceToken,
                     scopes: scopes)
             }
-            if let tokenEntries = auth["deviceTokens"]?.value as? [ProtoAnyCodable] {
+            if self.shouldPersistBootstrapHandoffTokens(),
+               let tokenEntries = auth["deviceTokens"]?.value as? [ProtoAnyCodable]
+            {
                 for entry in tokenEntries {
                     guard let rawEntry = entry.value as? [String: ProtoAnyCodable],
                           let deviceToken = rawEntry["deviceToken"]?.value as? String,

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"
     }
 }
 
@@ -2893,6 +2901,78 @@ public struct SkillsBinsResult: Codable, Sendable {
     }
 }
 
+public struct SkillsSearchParams: Codable, Sendable {
+    public let query: String?
+    public let limit: Int?
+
+    public init(
+        query: String?,
+        limit: Int?)
+    {
+        self.query = query
+        self.limit = limit
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case query
+        case limit
+    }
+}
+
+public struct SkillsSearchResult: Codable, Sendable {
+    public let results: [[String: AnyCodable]]
+
+    public init(
+        results: [[String: AnyCodable]])
+    {
+        self.results = results
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case results
+    }
+}
+
+public struct SkillsDetailParams: Codable, Sendable {
+    public let slug: String
+
+    public init(
+        slug: String)
+    {
+        self.slug = slug
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case slug
+    }
+}
+
+public struct SkillsDetailResult: Codable, Sendable {
+    public let skill: AnyCodable
+    public let latestversion: AnyCodable?
+    public let metadata: AnyCodable?
+    public let owner: AnyCodable?
+
+    public init(
+        skill: AnyCodable,
+        latestversion: AnyCodable?,
+        metadata: AnyCodable?,
+        owner: AnyCodable?)
+    {
+        self.skill = skill
+        self.latestversion = latestversion
+        self.metadata = metadata
+        self.owner = owner
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case skill
+        case latestversion = "latestVersion"
+        case metadata
+        case owner
+    }
+}
+
 public struct CronJob: Codable, Sendable {
     public let id: String
     public let agentid: String?

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

@@ -190,6 +190,7 @@ private actor SeqGapProbe {
     func value() -> Bool { self.saw }
 }
 
+@Suite(.serialized)
 struct GatewayNodeSessionTests {
     @Test
     func scannedSetupCodePrefersBootstrapAuthOverStoredDeviceToken() async throws {
@@ -270,18 +271,14 @@ struct GatewayNodeSessionTests {
             "scopes": [],
             "issuedAtMs": 1000,
             "deviceTokens": [
-                [
-                    "deviceToken": "node-device-token",
-                    "role": "node",
-                    "scopes": ["operator.admin"],
-                    "issuedAtMs": 1000,
-                ],
                 [
                     "deviceToken": "operator-device-token",
                     "role": "operator",
                     "scopes": [
+                        "node.exec",
                         "operator.admin",
                         "operator.approvals",
+                        "operator.pairing",
                         "operator.read",
                         "operator.talk.secrets",
                         "operator.write",
@@ -320,14 +317,18 @@ 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()
     }
 
     @Test
-    func nonBootstrapHelloDoesNotOverwriteStoredDeviceTokens() async throws {
+    func nonBootstrapHelloStoresPrimaryDeviceTokenButNotAdditionalBootstrapTokens() async throws {
         let tempDir = FileManager.default.temporaryDirectory
             .appendingPathComponent(UUID().uuidString, isDirectory: true)
         try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
@@ -380,6 +381,71 @@ struct GatewayNodeSessionTests {
                 BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: nil, error: nil)
             })
 
+        let nodeEntry = try #require(DeviceAuthStore.loadToken(deviceId: identity.deviceId, role: "node"))
+        #expect(nodeEntry.token == "server-node-token")
+        #expect(nodeEntry.scopes == [])
+        #expect(DeviceAuthStore.loadToken(deviceId: identity.deviceId, role: "operator") == nil)
+
+        await gateway.disconnect()
+    }
+
+    @Test
+    func untrustedBootstrapHelloDoesNotPersistBootstrapHandoffTokens() async throws {
+        let tempDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent(UUID().uuidString, isDirectory: true)
+        try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+        let previousStateDir = ProcessInfo.processInfo.environment["OPENCLAW_STATE_DIR"]
+        setenv("OPENCLAW_STATE_DIR", tempDir.path, 1)
+        defer {
+            if let previousStateDir {
+                setenv("OPENCLAW_STATE_DIR", previousStateDir, 1)
+            } else {
+                unsetenv("OPENCLAW_STATE_DIR")
+            }
+            try? FileManager.default.removeItem(at: tempDir)
+        }
+
+        let identity = DeviceIdentityStore.loadOrCreate()
+        let session = FakeGatewayWebSocketSession(helloAuth: [
+            "deviceToken": "untrusted-node-token",
+            "role": "node",
+            "scopes": [],
+            "deviceTokens": [
+                [
+                    "deviceToken": "untrusted-operator-token",
+                    "role": "operator",
+                    "scopes": [
+                        "operator.approvals",
+                        "operator.read",
+                    ],
+                ],
+            ],
+        ])
+        let gateway = GatewayNodeSession()
+        let options = GatewayConnectOptions(
+            role: "node",
+            scopes: [],
+            caps: [],
+            commands: [],
+            permissions: [:],
+            clientId: "openclaw-ios-test",
+            clientMode: "node",
+            clientDisplayName: "iOS Test",
+            includeDeviceIdentity: true)
+
+        try await gateway.connect(
+            url: URL(string: "ws://example.invalid")!,
+            token: nil,
+            bootstrapToken: "fresh-bootstrap-token",
+            password: nil,
+            connectOptions: options,
+            sessionBox: WebSocketSessionBox(session: session),
+            onConnected: {},
+            onDisconnected: { _ in },
+            onInvoke: { req in
+                BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: nil, error: nil)
+            })
+
         #expect(DeviceAuthStore.loadToken(deviceId: identity.deviceId, role: "node") == nil)
         #expect(DeviceAuthStore.loadToken(deviceId: identity.deviceId, role: "operator") == nil)
 

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

@@ -1,6 +1,7 @@
 import XCTest
 @testable import OpenClawKit
 
+@MainActor
 final class TalkSystemSpeechSynthesizerTests: XCTestCase {
     func testWatchdogTimeoutDefaultsToLatinProfile() {
         let timeout = TalkSystemSpeechSynthesizer.watchdogTimeoutSeconds(

docs/.generated/README.md

@@ -1,12 +1,21 @@
 # Generated Docs Artifacts
 
-These baseline artifacts are generated from the repo-owned OpenClaw config schema and bundled channel/plugin metadata.
+SHA-256 hash files are the tracked drift-detection artifacts. The full JSON
+baselines are generated locally (gitignored) for inspection only.
 
-- Do not edit `config-baseline.json` by hand.
-- Do not edit `config-baseline.jsonl` by hand.
-- Do not edit `plugin-sdk-api-baseline.json` by hand.
-- Do not edit `plugin-sdk-api-baseline.jsonl` by hand.
-- Regenerate config baseline artifacts with `pnpm config:docs:gen`.
-- Validate config baseline artifacts in CI or locally with `pnpm config:docs:check`.
-- Regenerate Plugin SDK API baseline artifacts with `pnpm plugin-sdk:api:gen`.
-- Validate Plugin SDK API baseline artifacts in CI or locally with `pnpm plugin-sdk:api:check`.
+**Tracked (committed to git):**
+
+- `config-baseline.sha256` — hashes of config baseline JSON artifacts.
+- `plugin-sdk-api-baseline.sha256` — hashes of Plugin SDK API baseline artifacts.
+
+**Local only (gitignored):**
+
+- `config-baseline.json`, `config-baseline.core.json`, `config-baseline.channel.json`, `config-baseline.plugin.json`
+- `plugin-sdk-api-baseline.json`, `plugin-sdk-api-baseline.jsonl`
+
+Do not edit any of these files by hand.
+
+- Regenerate config baseline: `pnpm config:docs:gen`
+- Validate config baseline: `pnpm config:docs:check`
+- Regenerate Plugin SDK API baseline: `pnpm plugin-sdk:api:gen`
+- Validate Plugin SDK API baseline: `pnpm plugin-sdk:api:check`

docs/.generated/config-baseline.sha256

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,2 @@
+cbffdf76d6a7254d8b2d3a601e1206d7b6c835bc44f170d4038bc711a35ef756  plugin-sdk-api-baseline.json
+fe026bf3ba1e3b55f6c0b560d76940f3c301d8f593d6f0f6dcc4625745c76d31  plugin-sdk-api-baseline.jsonl

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

@@ -47,6 +47,38 @@
     "source": "Quick Start",
     "target": "快速开始"
   },
+  {
+    "source": "Chutes",
+    "target": "Chutes"
+  },
+  {
+    "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"
+  },
+  {
+    "source": "Additional bundled variants",
+    "target": "其他内置变体"
+  },
   {
     "source": "Diffs",
     "target": "Diffs"
@@ -143,6 +175,10 @@
     "source": "Network model",
     "target": "网络模型"
   },
+  {
+    "source": "Bridge protocol (legacy nodes, historical)",
+    "target": "Bridge protocol（旧版节点，历史参考）"
+  },
   {
     "source": "Doctor",
     "target": "Doctor"
@@ -151,6 +187,10 @@
     "source": "Polls",
     "target": "投票"
   },
+  {
+    "source": "QQ Bot",
+    "target": "QQ Bot"
+  },
   {
     "source": "Release Policy",
     "target": "发布策略"
@@ -199,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": "安装完整性检查"
@@ -215,6 +263,10 @@
     "source": "FAQ",
     "target": "常见问题"
   },
+  {
+    "source": "Ollama Web Search",
+    "target": "Ollama Web 搜索"
+  },
   {
     "source": "onboarding",
     "target": "新手引导"

docs/assets/sponsors/github-light.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#111827" aria-hidden="true">
+  <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/>
+</svg>

docs/assets/sponsors/github.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#fff" aria-hidden="true">
+  <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/>
+</svg>

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,17 @@ 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.
+Once the runtime stops owning the job and the 5-minute grace window expires, maintenance can
+mark the task `lost`.
 
 ## Schedule types
 
@@ -60,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)
@@ -67,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                                             |
@@ -77,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):
@@ -163,7 +219,7 @@ Run an isolated agent turn:
 curl -X POST http://127.0.0.1:18789/hooks/agent \
   -H 'Authorization: Bearer SECRET' \
   -H 'Content-Type: application/json' \
-  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'
+  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'
 ```
 
 Fields: `message` (required), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`.
@@ -176,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
@@ -265,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
@@ -313,13 +382,19 @@ openclaw doctor
 - Check `cron.enabled` and `OPENCLAW_SKIP_CRON` env var.
 - Confirm the Gateway is running continuously.
 - For `cron` schedules, verify timezone (`--tz`) vs the host timezone.
-- `reason: not-due` in run output means manual run called without `--force`.
+- `reason: not-due` in run output means manual run was checked with `openclaw cron run <jobId> --due` and the job was not due yet.
 
 ### Cron fired but no delivery
 
 - Delivery mode 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

@@ -25,6 +25,14 @@ Not every agent run creates a task. Heartbeat turns and normal interactive chat
 - Tasks are **records**, not schedulers — cron and heartbeat decide _when_ work runs, tasks track _what happened_.
 - ACP, subagents, all cron jobs, and CLI operations create tasks. Heartbeat turns do not.
 - Each task moves through `queued → running → terminal` (succeeded, failed, timed_out, cancelled, or lost).
+- Cron tasks stay live while the cron runtime still owns the job; chat-backed CLI tasks stay live only while their owning run context is still active.
+- 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.
@@ -50,6 +58,15 @@ openclaw tasks notify <lookup> state_changes
 
 # Run a health audit
 openclaw tasks audit
+
+# Preview or apply maintenance
+openclaw tasks maintenance
+openclaw tasks maintenance --apply
+
+# Inspect TaskFlow state
+openclaw tasks flow list
+openclaw tasks flow show <lookup>
+openclaw tasks flow cancel <lookup>
 ```
 
 ## What creates a task
@@ -91,15 +108,22 @@ stateDiagram-v2
 | `failed`    | Completed with an error                                                    |
 | `timed_out` | Exceeded the configured timeout                                            |
 | `cancelled` | Stopped by the operator via `openclaw tasks cancel`                        |
-| `lost`      | Backing child session disappeared (detected after a 5-minute grace period) |
+| `lost`      | The runtime lost authoritative backing state after a 5-minute grace period |
 
 Transitions happen automatically — when the associated agent run ends, the task status updates to match.
 
+`lost` is runtime-aware:
+
+- ACP tasks: backing ACP child session metadata disappeared.
+- Subagent tasks: backing child session disappeared from the target agent store.
+- Cron tasks: the cron runtime no longer tracks the job as active.
+- CLI tasks: isolated child-session tasks use the child session; chat-backed CLI tasks use the live run context instead, so lingering channel/group/direct session rows do not keep them alive.
+
 ## Delivery and notifications
 
 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.
 
@@ -107,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:
@@ -167,11 +195,47 @@ Surfaces operational issues. Findings also appear in `openclaw status` when issu
 | ------------------------- | -------- | ----------------------------------------------------- |
 | `stale_queued`            | warn     | Queued for more than 10 minutes                       |
 | `stale_running`           | error    | Running for more than 30 minutes                      |
-| `lost`                    | error    | Backing session is gone                               |
+| `lost`                    | error    | Runtime-backed task ownership disappeared             |
 | `delivery_failed`         | warn     | Delivery failed and notify policy is not `silent`     |
 | `missing_cleanup`         | warn     | Terminal task with no cleanup timestamp               |
 | `inconsistent_timestamps` | warn     | Timeline violation (for example ended before started) |
 
+### `tasks maintenance`
+
+```bash
+openclaw tasks maintenance [--json]
+openclaw tasks maintenance --apply [--json]
+```
+
+Use this to preview or apply reconciliation, cleanup stamping, and pruning for
+tasks and Task Flow state.
+
+Reconciliation is runtime-aware:
+
+- ACP/subagent tasks check their backing child session.
+- Cron tasks check whether the cron runtime still owns the job.
+- Chat-backed CLI tasks check the owning live run context, not just the chat session row.
+
+Completion cleanup is also runtime-aware:
+
+- Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
+- Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
+- Isolated cron delivery waits out descendant subagent follow-up when needed and
+  suppresses stale parent acknowledgement text instead of announcing it.
+- Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary.
+- Cleanup failures do not mask the real task outcome.
+
+### `tasks flow list|show|cancel`
+
+```bash
+openclaw tasks flow list [--status <status>] [--json]
+openclaw tasks flow show <lookup> [--json]
+openclaw tasks flow cancel <lookup>
+```
+
+Use these when the orchestrating Task Flow is the thing you care about rather
+than one individual background task record.
+
 ## Chat task board (`/tasks`)
 
 Use `/tasks` in any chat session to see background tasks linked to that session. The board shows
@@ -216,7 +280,7 @@ The registry loads into memory at gateway start and syncs writes to SQLite for d
 
 A sweeper runs every **60 seconds** and handles three things:
 
-1. **Reconciliation** — checks if active tasks' backing sessions still exist. If a child session has been gone for more than 5 minutes, the task is marked `lost`.
+1. **Reconciliation** — checks whether active tasks still have authoritative runtime backing. ACP/subagent tasks use child-session state, cron tasks use active-job ownership, and chat-backed CLI tasks use the owning run context. If that backing state is gone for more than 5 minutes, the task is marked `lost`.
 2. **Cleanup stamping** — sets a `cleanupAfter` timestamp on terminal tasks (endedAt + 7 days).
 3. **Pruning** — deletes records past their `cleanupAfter` date.
 

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/groups.md

@@ -320,6 +320,9 @@ Notes:
 
 When `channels.whatsapp.groups`, `channels.telegram.groups`, or `channels.imessage.groups` is configured, the keys act as a group allowlist. Use `"*"` to allow all groups while still setting default mention behavior.
 
+Common confusion: DM pairing approval is not the same as group authorization.
+For channels that support DM pairing, the pairing store unlocks DMs only. Group commands still require explicit group sender authorization from config allowlists such as `groupAllowFrom` or the documented config fallback for that channel.
+
 Common intents (copy/paste):
 
 1. Disable all group replies

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
@@ -319,7 +325,9 @@ Verbose restore diagnostics:
 openclaw matrix verify backup restore --verbose
 ```
 
-Delete the current server backup and create a fresh backup baseline:
+Delete the current server backup and create a fresh backup baseline. If the stored
+backup key cannot be loaded cleanly, this reset can also recreate secret storage so
+future cold starts can load the new backup key:
 
 ```bash
 openclaw matrix verify backup reset --yes
@@ -366,8 +374,11 @@ If the homeserver requires interactive auth to upload cross-signing keys, OpenCl
 
 Use `--force-reset-cross-signing` only when you intentionally want to discard the current cross-signing identity and create a new one.
 
-If you intentionally want to discard the current room-key backup and start a new backup baseline for future messages, use `openclaw matrix verify backup reset --yes`.
-Do this only when you accept that unrecoverable old encrypted history will stay unavailable.
+If you intentionally want to discard the current room-key backup and start a new
+backup baseline for future messages, use `openclaw matrix verify backup reset --yes`.
+Do this only when you accept that unrecoverable old encrypted history will stay
+unavailable and that OpenClaw may recreate secret storage if the current backup
+secret cannot be loaded safely.
 
 ### Fresh backup baseline
 
@@ -654,7 +665,13 @@ Matrix can act as an exec approval client for a Matrix account.
 - `channels.matrix.execApprovals.agentFilter`
 - `channels.matrix.execApprovals.sessionFilter`
 
-Matrix becomes an exec approval client when `enabled` is true and at least one approver can be resolved. Approvers must be Matrix user IDs such as `@owner:example.org`.
+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:
 
@@ -666,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:
 
@@ -708,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

@@ -54,6 +54,9 @@ Account scoping behavior:
 
 Treat these as sensitive (they gate access to your assistant).
 
+Important: this store is for DM access. Group authorization is separate.
+Approving a DM pairing code does not automatically allow that sender to run group commands or control the bot in groups. For group access, configure the channel's explicit group allowlists (for example `groupAllowFrom`, `groups`, or per-group/per-topic overrides depending on the channel).
+
 ## 2) Node device pairing (iOS/Android/macOS/headless nodes)
 
 Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
@@ -74,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
@@ -97,8 +109,11 @@ Stored under `~/.openclaw/devices/`:
 
 ### Notes
 
-- The legacy `node.pair.*` API (CLI: `openclaw nodes pending/approve`) is a
+- 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,19 +120,142 @@ openclaw gateway
   </Tab>
 </Tabs>
 
+## Manifest and scope checklist
+
+<AccordionGroup>
+  <Accordion title="Slack app manifest example" defaultOpen>
+
+```json
+{
+  "display_information": {
+    "name": "OpenClaw",
+    "description": "Slack connector for OpenClaw"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "OpenClaw",
+      "always_online": true
+    },
+    "app_home": {
+      "messages_tab_enabled": true,
+      "messages_tab_read_only_enabled": false
+    },
+    "slash_commands": [
+      {
+        "command": "/openclaw",
+        "description": "Send a message to OpenClaw",
+        "should_escape": false
+      }
+    ]
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "app_mentions:read",
+        "assistant:write",
+        "channels:history",
+        "channels:read",
+        "chat:write",
+        "commands",
+        "emoji:read",
+        "files:read",
+        "files:write",
+        "groups:history",
+        "groups:read",
+        "im:history",
+        "im:read",
+        "im:write",
+        "mpim:history",
+        "mpim:read",
+        "mpim:write",
+        "pins:read",
+        "pins:write",
+        "reactions:read",
+        "reactions:write",
+        "users:read"
+      ]
+    }
+  },
+  "settings": {
+    "socket_mode_enabled": true,
+    "event_subscriptions": {
+      "bot_events": [
+        "app_mention",
+        "channel_rename",
+        "member_joined_channel",
+        "member_left_channel",
+        "message.channels",
+        "message.groups",
+        "message.im",
+        "message.mpim",
+        "pin_added",
+        "pin_removed",
+        "reaction_added",
+        "reaction_removed"
+      ]
+    }
+  }
+}
+```
+
+  </Accordion>
+
+  <Accordion title="Optional user-token scopes (read operations)">
+    If you configure `channels.slack.userToken`, typical read scopes are:
+
+    - `channels:history`, `groups:history`, `im:history`, `mpim:history`
+    - `channels:read`, `groups:read`, `im:read`, `mpim:read`
+    - `users:read`
+    - `reactions:read`
+    - `pins:read`
+    - `emoji:read`
+    - `search:read` (if you depend on Slack search reads)
+
+  </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>
@@ -204,6 +327,119 @@ For actions/directory reads, user token can be preferred when configured. For wr
   </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).
@@ -218,6 +454,19 @@ For actions/directory reads, user token can be preferred when configured. For wr
   - 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.
@@ -267,226 +516,18 @@ Notes:
 - 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.
 
-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`).
-
-## 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>
-  <Accordion title="Slack app manifest example">
-
-```json
-{
-  "display_information": {
-    "name": "OpenClaw",
-    "description": "Slack connector for OpenClaw"
-  },
-  "features": {
-    "bot_user": {
-      "display_name": "OpenClaw",
-      "always_online": false
-    },
-    "app_home": {
-      "messages_tab_enabled": true,
-      "messages_tab_read_only_enabled": false
-    },
-    "slash_commands": [
-      {
-        "command": "/openclaw",
-        "description": "Send a message to OpenClaw",
-        "should_escape": false
-      }
-    ]
-  },
-  "oauth_config": {
-    "scopes": {
-      "bot": [
-        "app_mentions:read",
-        "assistant:write",
-        "channels:history",
-        "channels:read",
-        "chat:write",
-        "commands",
-        "emoji:read",
-        "files:read",
-        "files:write",
-        "groups:history",
-        "im:history",
-        "im:read",
-        "im:write",
-        "mpim:history",
-        "mpim:read",
-        "mpim:write",
-        "pins:read",
-        "pins:write",
-        "reactions:read",
-        "reactions:write",
-        "users:read"
-      ]
-    }
-  },
-  "settings": {
-    "socket_mode_enabled": true,
-    "event_subscriptions": {
-      "bot_events": [
-        "app_mention",
-        "channel_rename",
-        "member_joined_channel",
-        "member_left_channel",
-        "message.channels",
-        "message.groups",
-        "message.im",
-        "message.mpim",
-        "pin_added",
-        "pin_removed",
-        "reaction_added",
-        "reaction_removed"
-      ]
-    }
-  }
-}
-```
-
-  </Accordion>
-
-  <Accordion title="Optional user-token scopes (read operations)">
-    If you configure `channels.slack.userToken`, typical read scopes are:
-
-    - `channels:history`, `groups:history`, `im:history`, `mpim:history`
-    - `channels:read`, `groups:read`, `im:read`, `mpim:read`
-    - `users:read`
-    - `reactions:read`
-    - `pins:read`
-    - `emoji:read`
-    - `search:read` (if you depend on Slack search reads)
-
-  </Accordion>
-</AccordionGroup>
-
 ## 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:
 
@@ -526,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>
@@ -567,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">
@@ -577,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">
@@ -590,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

@@ -121,6 +121,10 @@ Token resolution order is account-aware. In practice, config values win over env
 
     For one-owner bots, prefer `dmPolicy: "allowlist"` with explicit numeric `allowFrom` IDs to keep access policy durable in config (instead of depending on previous pairing approvals).
 
+    Common confusion: DM pairing approval does not mean "this sender is authorized everywhere".
+    Pairing grants DM access only. Group sender authorization still comes from explicit config allowlists.
+    If you want "I am authorized once and both DMs and group commands work", put your numeric Telegram user ID in `channels.telegram.allowFrom`.
+
     ### Finding your Telegram user ID
 
     Safer (no third-party bot):
@@ -159,6 +163,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     Non-numeric entries are ignored for sender authorization.
     Security boundary (`2026.2.25+`): group sender auth does **not** inherit DM pairing-store approvals.
     Pairing stays DM-only. For groups, set `groupAllowFrom` or per-group/per-topic `allowFrom`.
+    If `groupAllowFrom` is unset, Telegram falls back to config `allowFrom`, not the pairing store.
+    Practical pattern for one-owner bots: set your user ID in `channels.telegram.allowFrom`, leave `groupAllowFrom` unset, and allow the target groups under `channels.telegram.groups`.
     Runtime note: if `channels.telegram` is completely missing, runtime defaults to fail-closed `groupPolicy="allowlist"` unless `channels.defaults.groupPolicy` is explicitly set.
 
     Example: allow any member in one specific group:
@@ -352,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).
@@ -815,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:
 
@@ -824,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`).
@@ -914,6 +935,33 @@ channels:
       autoSelectFamily: false
 ```
 
+    - RFC 2544 benchmark-range answers (`198.18.0.0/15`) are already allowed
+      for Telegram media downloads by default. If a trusted fake-IP or
+      transparent proxy rewrites `api.telegram.org` to some other
+      private/internal/special-use address during media downloads, you can opt
+      in to the Telegram-only bypass:
+
+```yaml
+channels:
+  telegram:
+    network:
+      dangerouslyAllowPrivateNetwork: true
+```
+
+    - The same opt-in is available per account at
+      `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
+    - If your proxy resolves Telegram media hosts into `198.18.x.x`, leave the
+      dangerous flag off first. Telegram media already allows the RFC 2544
+      benchmark range by default.
+
+    <Warning>
+      `channels.telegram.network.dangerouslyAllowPrivateNetwork` weakens Telegram
+      media SSRF protections. Use it only for trusted operator-controlled proxy
+      environments such as Clash, Mihomo, or Surge fake-IP routing when they
+      synthesize private or special-use answers outside the RFC 2544 benchmark
+      range. Leave it off for normal public internet Telegram access.
+    </Warning>
+
     - Environment overrides (temporary):
       - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
       - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
@@ -980,6 +1028,7 @@ Primary reference:
 - `channels.telegram.retry`: retry policy for Telegram send helpers (CLI/tools/actions) on recoverable outbound API errors (attempts, minDelayMs, maxDelayMs, jitter).
 - `channels.telegram.network.autoSelectFamily`: override Node autoSelectFamily (true=enable, false=disable). Defaults to enabled on Node 22+, with WSL2 defaulting to disabled.
 - `channels.telegram.network.dnsResultOrder`: override DNS result order (`ipv4first` or `verbatim`). Defaults to `ipv4first` on Node 22+.
+- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: dangerous opt-in for trusted fake-IP or transparent-proxy environments where Telegram media downloads resolve `api.telegram.org` to private/internal/special-use addresses outside the default RFC 2544 benchmark-range allowance.
 - `channels.telegram.proxy`: proxy URL for Bot API calls (SOCKS/HTTP).
 - `channels.telegram.webhookUrl`: enable webhook mode (requires `channels.telegram.webhookSecret`).
 - `channels.telegram.webhookSecret`: webhook secret (required when webhookUrl is set).
@@ -1006,7 +1055,7 @@ Telegram-specific high-signal fields:
 - threading/replies: `replyToMode`
 - streaming: `streaming` (preview), `blockStreaming`
 - formatting/delivery: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
-- media/network: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `proxy`
+- media/network: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
 - webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
 - actions/capabilities: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
 - reactions: `reactionNotifications`, `reactionLevel`

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.