fix(plugins): stabilize registry package paths

Co-authored-by: alex-latitude <213670856+alex-latitude@users.noreply.github.com>

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

@@ -68,6 +68,7 @@ gh search issues --repo openclaw/openclaw --match title,body --limit 50 \
 - Keep commit messages concise and action-oriented.
 - Group related changes; avoid bundling unrelated refactors.
 - Use `.github/pull_request_template.md` for PR submissions and `.github/ISSUE_TEMPLATE/` for issues.
+- Do not commit PR-only artifacts such as screenshots under `.github/pr-assets`; attach them to the PR/comment or use an external artifact store instead.
 
 ## Extra safety
 

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

@@ -49,6 +49,66 @@ pnpm openclaw qa suite \
 5. If the user wants to watch the live UI, find the current `openclaw-qa` listen port and report `http://127.0.0.1:<port>`.
 6. If a scenario fails, fix the product or harness root cause, then rerun the full lane.
 
+## QA credentials and 1Password
+
+- Use `op` only inside `tmux` for QA secret lookup in this repo.
+- Quick auth check inside tmux:
+
+```bash
+op account list
+```
+
+- Direct Telegram npm live test secrets currently live in 1Password item:
+  - vault: `OpenClaw`
+  - item: `Telegram E2E`
+- That item is the first place to look for:
+  - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
+  - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
+  - `OPENCLAW_QA_PROVIDER_MODE`
+  - `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC`
+- Convex QA secrets currently live in 1Password items:
+  - vault: `OpenClaw`
+  - item: `OPENCLAW_QA_CONVEX_SITE_URL`
+  - item: `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`
+  - item: `OPENCLAW_QA_CONVEX_SECRET_CI`
+- Additional related notes/login items seen during QA credential work:
+  - vault: `Private`
+  - items: `OPENCLAW QA`, `Convex`, `Telegram`
+- If a required value is missing from those notes:
+  - do not guess
+  - ask the maintainer/operator for the current value or the current 1Password item name
+  - for Telegram direct runs, `OPENCLAW_QA_TELEGRAM_GROUP_ID` may be stored separately from `Telegram E2E`
+  - for Convex runs, the leased Telegram credential should provide the Telegram group id and bot tokens together; do not require a separate `OPENCLAW_QA_TELEGRAM_GROUP_ID`
+  - for Convex runs, prefer `OpenClaw/OPENCLAW_QA_CONVEX_SITE_URL`; if that is stale or unclear, ask for the active pool URL before running
+- Prefer direct Telegram envs for the npm Telegram Docker lane when available:
+
+```bash
+OPENCLAW_QA_TELEGRAM_GROUP_ID="..." \
+OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN="..." \
+OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN="..." \
+OPENCLAW_QA_PROVIDER_MODE="mock-openai" \
+OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC="openclaw@beta" \
+pnpm test:docker:npm-telegram-live
+```
+
+- Prefer Convex mode when the goal is stable shared QA infra:
+  - round-robin credential leasing
+  - thinner wrapper for channel-specific setup
+  - CLI/admin flows around the pooled credentials
+- Live npm Telegram Docker lane note:
+  - `scripts/e2e/npm-telegram-live-runner.ts` reads `OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE`
+  - do not assume `OPENCLAW_QA_PROVIDER_MODE` is consumed by that wrapper
+  - if a 1Password note only gives `OPENCLAW_QA_PROVIDER_MODE`, map it explicitly to `OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE` before running the Docker lane
+- Verified live shape:
+  - Convex mode can pass the real Docker lane without direct Telegram env vars
+  - leased Telegram payload includes the group id coupled to the driver/SUT tokens
+  - a real run of `pnpm test:docker:npm-telegram-live` passed with:
+    - `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`
+    - `OPENCLAW_QA_CREDENTIAL_ROLE=maintainer`
+    - `OPENCLAW_QA_CONVEX_SITE_URL`
+    - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`
+    - `OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE=mock-openai`
+
 ## Character evals
 
 Use `qa character-eval` for style/persona/vibe checks across multiple live models.

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

@@ -97,6 +97,11 @@ Use this skill for release and publish-time workflow. Keep ordinary development
 
 ## Build changelog-backed release notes
 
+- Before release branching or tagging, rewrite the target `CHANGELOG.md`
+  section from commit history, not just from existing notes: scan commits since
+  the last reachable release tag, add missed user-facing changes, dedupe
+  overlapping entries, and sort each section from most to least interesting for
+  users.
 - Changelog entries should be user-facing, not internal release-process notes.
 - GitHub release and prerelease bodies must use the full matching
   `CHANGELOG.md` version section, not highlights or an excerpt. When creating
@@ -279,8 +284,20 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
   - `node --import tsx scripts/openclaw-npm-postpublish-verify.ts <beta-version>`
   - install/update smoke against the published beta channel
   - Docker install/update coverage that exercises the published beta package
+  - published npm Telegram proof: dispatch Actions > `NPM Telegram Beta E2E`
+    from `main` with `package_spec=openclaw@<beta-version>` and
+    `provider_mode=mock-openai`, approve `npm-release`, and require success.
+    This is the default button path for installed-package onboarding,
+    Telegram setup, and real Telegram E2E against the published npm package.
+    Use the local `pnpm test:docker:npm-telegram-live` lane with the matching
+    `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC` and Convex CI env only as a fallback
+    or debugging path.
   - Parallels published beta install/update coverage with both OpenAI and
     Anthropic provider keys available
+  - Parallels install/update proof must keep plugin installs enabled unless the
+    operator explicitly scopes a harness-only isolation check; a lane that
+    disables bundled plugin installs is not valid plugin/dependency release
+    evidence.
   - targeted QA reruns only for areas touched by fixes after the full pre-npm
     roster, unless the operator requests the full QA roster again. If the fix
     touches live channel QA, credential plumbing, Matrix, Telegram, or the QA
@@ -329,10 +346,17 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
   `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
   workflow because `npm dist-tag` management needs `NPM_TOKEN`, while the
   public npm release workflow stays OIDC-only.
+- Prefer fixing the private workflow token path over any local 1Password
+  fallback. The desired setup is a granular npm token stored as the private
+  repo's `NPM_TOKEN` secret, scoped to the `openclaw` package with read/write
+  and 2FA bypass for automation.
 - If the private dist-tag workflow cannot promote because `NPM_TOKEN` is absent
   or stale, use the local tmux + 1Password fallback:
   - Start or reuse a tmux session so interactive `npm login` and OTP prompts
     are observable and recoverable.
+  - Hard rule: never run `op` directly in the main agent shell during release
+    work. Any 1Password CLI use must happen inside that tmux session so prompts
+    and alerts are contained and observable.
   - Use the 1Password item `op://Private/Npmjs` for npm credentials and OTP.
     Do not print passwords, tokens, or OTPs to the transcript; send them through
     tmux buffers, env vars scoped to the tmux command, or `expect` with
@@ -502,9 +526,11 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
 23. Run the post-published beta verification roster. If any lane fails after
     the beta tag/package is pushed or published, fix, commit/push/pull,
     increment to the next beta tag, and restart at the full pre-npm beta test
-    roster for the new beta. If a pre-npm lane fails before any tag/package
-    leaves the machine, fix and rerun the same intended beta attempt. Repeat up
-    to the operator's authorized beta-attempt limit, normally 4.
+    roster for the new beta. The roster includes the manual Actions >
+    `NPM Telegram Beta E2E` workflow against the exact published beta package.
+    If a pre-npm lane fails before any tag/package leaves the machine, fix and
+    rerun the same intended beta attempt. Repeat up to the operator's
+    authorized beta-attempt limit, normally 4.
 24. Announce the beta/stable release on Discord best-effort using Peter's bot
     token from `.profile`.
 25. If the operator requested beta only, stop after beta verification and the

.dockerignore

@@ -8,6 +8,14 @@
 
 .bun-cache
 .bun
+.artifacts
+**/.artifacts
+.local
+**/.local
+.pi
+**/.pi
+__openclaw_vitest__
+**/__openclaw_vitest__
 .tmp
 **/.tmp
 .DS_Store
@@ -38,6 +46,9 @@ docs/.generated
 *.log
 tmp
 **/tmp
+dist-runtime
+**/dist-runtime
+openclaw-path-alias-*
 
 # build artifacts
 dist

.github/codeql/codeql-javascript-typescript.yml

@@ -12,6 +12,9 @@ paths-ignore:
   - docs
   - "**/node_modules"
   - "**/coverage"
+  - "**/*.generated.ts"
+  - "**/*.bundle.js"
+  - "**/*-runtime.js"
   - "**/*.test.ts"
   - "**/*.test.tsx"
   - "**/*.e2e.test.ts"

.github/labeler.yml

@@ -29,6 +29,11 @@
       - any-glob-to-any-file:
           - "extensions/google-meet/**"
           - "docs/plugins/google-meet.md"
+"plugin: bonjour":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/bonjour/**"
+          - "docs/gateway/bonjour.md"
 "channel: imessage":
   - changed-files:
       - any-glob-to-any-file:
@@ -310,6 +315,11 @@
   - changed-files:
       - any-glob-to-any-file:
           - "extensions/lmstudio/**"
+"extensions: litellm":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/litellm/**"
+          - "docs/providers/litellm.md"
 "extensions: openai":
   - changed-files:
       - any-glob-to-any-file:
@@ -346,6 +356,11 @@
   - changed-files:
       - any-glob-to-any-file:
           - "extensions/qianfan/**"
+"extensions: senseaudio":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/senseaudio/**"
+          - "docs/providers/senseaudio.md"
 "extensions: synthetic":
   - changed-files:
       - any-glob-to-any-file:
@@ -362,6 +377,11 @@
   - changed-files:
       - any-glob-to-any-file:
           - "extensions/together/**"
+"extensions: tts-local-cli":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/tts-local-cli/**"
+          - "docs/tools/tts.md"
 "extensions: venice":
   - changed-files:
       - any-glob-to-any-file:
@@ -382,3 +402,7 @@
   - changed-files:
       - any-glob-to-any-file:
           - "extensions/fal/**"
+"extensions: gradium":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/gradium/**"

.github/workflows/ci.yml

@@ -3,6 +3,9 @@ name: CI
 on:
   push:
     branches: [main]
+    paths-ignore:
+      - "**/*.md"
+      - "docs/**"
   pull_request:
     types: [opened, reopened, synchronize, ready_for_review, converted_to_draft]
 
@@ -37,6 +40,7 @@ jobs:
       has_changed_extensions: ${{ steps.manifest.outputs.has_changed_extensions }}
       changed_extensions_matrix: ${{ steps.manifest.outputs.changed_extensions_matrix }}
       run_build_artifacts: ${{ steps.manifest.outputs.run_build_artifacts }}
+      run_checks_fast_core: ${{ steps.manifest.outputs.run_checks_fast_core }}
       run_checks_fast: ${{ steps.manifest.outputs.run_checks_fast }}
       checks_fast_core_matrix: ${{ steps.manifest.outputs.checks_fast_core_matrix }}
       channel_contracts_matrix: ${{ steps.manifest.outputs.channel_contracts_matrix }}
@@ -127,6 +131,9 @@ jobs:
           OPENCLAW_CI_RUN_MACOS: ${{ steps.changed_scope.outputs.run_macos || 'false' }}
           OPENCLAW_CI_RUN_ANDROID: ${{ steps.changed_scope.outputs.run_android || 'false' }}
           OPENCLAW_CI_RUN_WINDOWS: ${{ steps.changed_scope.outputs.run_windows || 'false' }}
+          OPENCLAW_CI_RUN_NODE_FAST_ONLY: ${{ steps.changed_scope.outputs.run_node_fast_only || 'false' }}
+          OPENCLAW_CI_RUN_NODE_FAST_PLUGIN_CONTRACTS: ${{ steps.changed_scope.outputs.run_node_fast_plugin_contracts || 'false' }}
+          OPENCLAW_CI_RUN_NODE_FAST_CI_ROUTING: ${{ steps.changed_scope.outputs.run_node_fast_ci_routing || 'false' }}
           OPENCLAW_CI_RUN_SKILLS_PYTHON: ${{ steps.changed_scope.outputs.run_skills_python || 'false' }}
           OPENCLAW_CI_RUN_CONTROL_UI_I18N: ${{ steps.changed_scope.outputs.run_control_ui_i18n || 'false' }}
           OPENCLAW_CI_HAS_CHANGED_EXTENSIONS: ${{ steps.changed_extensions.outputs.has_changed_extensions || 'false' }}
@@ -170,12 +177,23 @@ jobs:
           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 runNodeFastOnly =
+            runNode && parseBoolean(process.env.OPENCLAW_CI_RUN_NODE_FAST_ONLY);
+          const runNodeFull = runNode && !runNodeFastOnly;
+          const runNodeFastPluginContracts =
+            runNode && parseBoolean(process.env.OPENCLAW_CI_RUN_NODE_FAST_PLUGIN_CONTRACTS);
+          const runNodeFastCiRouting =
+            runNode && parseBoolean(process.env.OPENCLAW_CI_RUN_NODE_FAST_CI_ROUTING);
+          const runChecksFastCore = runNodeFull || runNodeFastPluginContracts || runNodeFastCiRouting;
           const runMacos =
             parseBoolean(process.env.OPENCLAW_CI_RUN_MACOS) && !docsOnly && isCanonicalRepository;
           const runAndroid =
             parseBoolean(process.env.OPENCLAW_CI_RUN_ANDROID) && !docsOnly && isCanonicalRepository;
           const runWindows =
-            parseBoolean(process.env.OPENCLAW_CI_RUN_WINDOWS) && !docsOnly && isCanonicalRepository;
+            parseBoolean(process.env.OPENCLAW_CI_RUN_WINDOWS) &&
+            !docsOnly &&
+            !runNodeFastOnly &&
+            isCanonicalRepository;
           const runSkillsPython = parseBoolean(process.env.OPENCLAW_CI_RUN_SKILLS_PYTHON) && !docsOnly;
           const runControlUiI18n =
             parseBoolean(process.env.OPENCLAW_CI_RUN_CONTROL_UI_I18N) && !docsOnly;
@@ -188,18 +206,49 @@ jobs:
             ? DEFAULT_EXTENSION_TEST_SHARD_COUNT
             : Math.max(DEFAULT_EXTENSION_TEST_SHARD_COUNT, 36);
           const extensionShardMatrix = createMatrix(
-            runNode
+            runNodeFull
               ? createExtensionTestShards({
                   shardCount: extensionTestShardCount,
                 }).map((shard) => ({
                   check_name: shard.checkName,
                   extensions_csv: shard.extensionIds.join(","),
+                  runner: isCanonicalRepository && [0, 3, 4].includes(shard.index)
+                    ? "blacksmith-8vcpu-ubuntu-2404"
+                    : isCanonicalRepository
+                      ? "blacksmith-4vcpu-ubuntu-2404"
+                      : "ubuntu-24.04",
                   shard_index: shard.index + 1,
                   task: "extensions-batch",
                 }))
               : [],
           );
-          const nodeTestShards = runNode
+          const checksFastCoreTasks = [];
+          if (runNodeFull) {
+            checksFastCoreTasks.push(
+              { check_name: "checks-fast-bundled", runtime: "node", task: "bundled" },
+              {
+                check_name: "checks-fast-contracts-plugins",
+                runtime: "node",
+                task: "contracts-plugins",
+              },
+            );
+          } else {
+            if (runNodeFastPluginContracts) {
+              checksFastCoreTasks.push({
+                check_name: "checks-fast-contracts-plugins",
+                runtime: "node",
+                task: runNodeFastCiRouting ? "contracts-plugins-ci-routing" : "contracts-plugins",
+              });
+            } else if (runNodeFastCiRouting) {
+              checksFastCoreTasks.push({
+                check_name: "checks-fast-ci-routing",
+                runtime: "node",
+                task: "ci-routing",
+              });
+            }
+          }
+
+          const nodeTestShards = runNodeFull
             ? createNodeTestShards().map((shard) => ({
                 check_name: shard.checkName,
                 runtime: "node",
@@ -208,6 +257,7 @@ jobs:
                 configs: shard.configs,
                 includePatterns: shard.includePatterns,
                 requires_dist: shard.requiresDist,
+                runner: shard.runner,
               }))
             : [];
           const nodeTestNonDistShards = nodeTestShards.filter((shard) => !shard.requires_dist);
@@ -223,25 +273,17 @@ jobs:
             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-plugins",
-                      runtime: "node",
-                      task: "contracts-plugins",
-                    },
-                  ]
-                : [],
+            run_build_artifacts: runNodeFull,
+            run_checks_fast_core: runChecksFastCore,
+            run_checks_fast: runNodeFull,
+            checks_fast_core_matrix: createMatrix(checksFastCoreTasks),
+            channel_contracts_matrix: createMatrix(
+              runNodeFull ? createChannelContractTestShards() : [],
             ),
-            channel_contracts_matrix: createMatrix(runNode ? createChannelContractTestShards() : []),
             checks_node_extensions_matrix: extensionShardMatrix,
-            run_checks: runNode,
+            run_checks: runNodeFull,
             checks_matrix: createMatrix(
-              runNode
+              runNodeFull
                 ? [
                     { check_name: "checks-node-channels", runtime: "node", task: "channels" },
                   ]
@@ -260,9 +302,9 @@ jobs:
                   }))
                 : [],
             ),
-            run_check: runNode,
-            run_check_additional: runNode,
-            run_build_smoke: runNode,
+            run_check: runNodeFull,
+            run_check_additional: runNodeFull,
+            run_build_smoke: runNodeFull,
             run_check_docs: docsChanged,
             run_control_ui_i18n: runControlUiI18n,
             run_skills_python_job: runSkillsPython,
@@ -653,8 +695,8 @@ jobs:
       contents: read
     name: ${{ matrix.check_name }}
     needs: [preflight]
-    if: needs.preflight.outputs.run_checks_fast == 'true'
-    runs-on: ubuntu-24.04
+    if: needs.preflight.outputs.run_checks_fast_core == 'true'
+    runs-on: ${{ github.repository == 'openclaw/openclaw' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-24.04' }}
     timeout-minutes: 60
     strategy:
       fail-fast: false
@@ -730,6 +772,13 @@ jobs:
             contracts-plugins)
               pnpm test:contracts:plugins
               ;;
+            contracts-plugins-ci-routing)
+              pnpm test:contracts:plugins
+              pnpm test src/commands/status.scan-result.test.ts src/scripts/ci-changed-scope.test.ts test/scripts/test-projects.test.ts
+              ;;
+            ci-routing)
+              pnpm test src/commands/status.scan-result.test.ts src/scripts/ci-changed-scope.test.ts test/scripts/test-projects.test.ts
+              ;;
             *)
               echo "Unsupported checks-fast task: $TASK" >&2
               exit 1
@@ -913,7 +962,7 @@ jobs:
     name: ${{ matrix.check_name }}
     needs: [preflight]
     if: needs.preflight.outputs.run_checks_fast == 'true'
-    runs-on: ${{ github.repository == 'openclaw/openclaw' && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-24.04' }}
+    runs-on: ${{ matrix.runner }}
     timeout-minutes: 60
     strategy:
       fail-fast: false
@@ -975,7 +1024,7 @@ jobs:
       - name: Run extension shard
         env:
           NODE_OPTIONS: --max-old-space-size=6144
-          OPENCLAW_EXTENSION_BATCH_PARALLEL: 1
+          OPENCLAW_EXTENSION_BATCH_PARALLEL: 2
           OPENCLAW_VITEST_MAX_WORKERS: 1
           OPENCLAW_EXTENSION_BATCH: ${{ matrix.extensions_csv }}
         run: pnpm test:extensions:batch -- "$OPENCLAW_EXTENSION_BATCH"
@@ -1035,8 +1084,8 @@ jobs:
       contents: read
     name: checks-node-compat-node22
     needs: [preflight]
-    if: needs.preflight.outputs.run_node == 'true' && github.event_name == 'push'
-    runs-on: ${{ github.repository == 'openclaw/openclaw' && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-24.04' }}
+    if: needs.preflight.outputs.run_build_artifacts == 'true' && github.event_name == 'push'
+    runs-on: ${{ github.repository == 'openclaw/openclaw' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-24.04' }}
     timeout-minutes: 60
     steps:
       - name: Checkout
@@ -1113,10 +1162,7 @@ jobs:
     name: ${{ matrix.check_name }}
     needs: [preflight]
     if: needs.preflight.outputs.run_checks_node_core_nondist == 'true'
-    # Keep core shards on GitHub-hosted runners. The Blacksmith pool is already
-    # occupied by build and extension shards; queueing these shards there hides
-    # actual test-speed improvements behind runner wait time.
-    runs-on: ubuntu-24.04
+    runs-on: ${{ github.repository == 'openclaw/openclaw' && (matrix.runner || 'ubuntu-24.04') || 'ubuntu-24.04' }}
     timeout-minutes: 60
     strategy:
       fail-fast: false
@@ -1372,16 +1418,16 @@ jobs:
             runner: ubuntu-24.04
           - check_name: check-prod-types
             task: prod-types
-            runner: ubuntu-24.04
+            runner: blacksmith-4vcpu-ubuntu-2404
           - check_name: check-lint
             task: lint
-            runner: ubuntu-24.04
+            runner: blacksmith-16vcpu-ubuntu-2404
           - check_name: check-policy-guards
             task: policy-guards
             runner: ubuntu-24.04
           - check_name: check-test-types
             task: test-types
-            runner: ubuntu-24.04
+            runner: blacksmith-4vcpu-ubuntu-2404
           - check_name: check-strict-smoke
             task: strict-smoke
             runner: ubuntu-24.04
@@ -1456,7 +1502,7 @@ jobs:
               pnpm tsgo:prod
               ;;
             lint)
-              pnpm lint
+              pnpm lint --threads=8
               ;;
             policy-guards)
               pnpm lint:webhook:no-low-level-body-read
@@ -1581,7 +1627,7 @@ jobs:
             packages/plugin-sdk/dist
             extensions/*/dist/.boundary-tsc.tsbuildinfo
             extensions/*/dist/.boundary-tsc.stamp
-          key: ${{ runner.os }}-extension-package-boundary-v1-${{ hashFiles('tsconfig.json', 'tsconfig.plugin-sdk.dts.json', 'packages/plugin-sdk/tsconfig.json', 'scripts/check-extension-package-tsc-boundary.mjs', 'scripts/prepare-extension-package-boundary-artifacts.mjs', 'scripts/write-plugin-sdk-entry-dts.ts', 'scripts/lib/plugin-sdk-entrypoints.json', 'scripts/lib/plugin-sdk-entries.mjs', 'src/plugin-sdk/**', 'src/video-generation/dashscope-compatible.ts', 'src/video-generation/types.ts', 'src/types/**', 'extensions/**', 'extensions/tsconfig.package-boundary*.json', 'package.json', 'pnpm-lock.yaml') }}
+          key: ${{ runner.os }}-extension-package-boundary-v1-${{ hashFiles('tsconfig.json', 'tsconfig.plugin-sdk.dts.json', 'packages/plugin-sdk/tsconfig.json', 'scripts/check-extension-package-tsc-boundary.mjs', 'scripts/prepare-extension-package-boundary-artifacts.mjs', 'scripts/write-plugin-sdk-entry-dts.ts', 'scripts/lib/plugin-sdk-entrypoints.json', 'scripts/lib/plugin-sdk-entries.mjs', 'src/plugin-sdk/**', 'src/auto-reply/**', 'src/video-generation/dashscope-compatible.ts', 'src/video-generation/types.ts', 'src/types/**', 'extensions/**', 'extensions/tsconfig.package-boundary*.json', 'package.json', 'pnpm-lock.yaml') }}
           restore-keys: |
             ${{ runner.os }}-extension-package-boundary-v1-
 

.github/workflows/codeql.yml

@@ -26,7 +26,7 @@ jobs:
       matrix:
         include:
           - language: javascript-typescript
-            runs_on: blacksmith-16vcpu-ubuntu-2404
+            runs_on: blacksmith-32vcpu-ubuntu-2404
             needs_node: true
             needs_python: false
             needs_java: false

.github/workflows/control-ui-locale-refresh.yml

@@ -137,7 +137,7 @@ jobs:
         env:
           OPENAI_API_KEY: ${{ secrets.OPENCLAW_DOCS_I18N_OPENAI_API_KEY || secrets.OPENAI_API_KEY }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          OPENCLAW_CONTROL_UI_I18N_MODEL: gpt-5.4
+          OPENCLAW_CONTROL_UI_I18N_MODEL: ${{ vars.OPENCLAW_CI_OPENAI_MODEL_BARE }}
           OPENCLAW_CONTROL_UI_I18N_THINKING: low
           LOCALE: ${{ matrix.locale }}
         run: node --import tsx scripts/control-ui-i18n.ts sync --locale "${LOCALE}" --write

.github/workflows/docs-agent.yml

@@ -156,7 +156,7 @@ jobs:
         with:
           openai-api-key: ${{ secrets.OPENCLAW_DOCS_AGENT_OPENAI_API_KEY || secrets.OPENAI_API_KEY }}
           prompt-file: .github/codex/prompts/docs-agent.md
-          model: gpt-5.4
+          model: ${{ vars.OPENCLAW_CI_OPENAI_MODEL_BARE }}
           effort: medium
           sandbox: workspace-write
           safety-strategy: drop-sudo

.github/workflows/docs-sync-publish.yml

@@ -63,18 +63,43 @@ jobs:
         working-directory: publish
         run: |
           set -euo pipefail
+          remote_source_sha() {
+            git show refs/remotes/origin/main:.openclaw-sync/source.json 2>/dev/null \
+              | node -e 'const fs = require("node:fs"); try { const data = JSON.parse(fs.readFileSync(0, "utf8")); if (data.sha) process.stdout.write(data.sha); } catch {}' \
+              || true
+          }
+
+          skip_stale_source() {
+            current_source_sha="$(remote_source_sha)"
+            if [ -z "$current_source_sha" ] || [ "$current_source_sha" = "$GITHUB_SHA" ]; then
+              return
+            fi
+
+            if git -C "$GITHUB_WORKSPACE" merge-base --is-ancestor "$GITHUB_SHA" "$current_source_sha"; then
+              echo "Skipping stale publish sync for $GITHUB_SHA; origin/main already mirrors $current_source_sha."
+              exit 0
+            fi
+          }
+
           if git diff --quiet -- docs .openclaw-sync; then
             echo "No publish-repo changes."
             exit 0
           fi
 
+          if git fetch origin main:refs/remotes/origin/main; then
+            skip_stale_source
+          fi
+
           git config user.name "openclaw-docs-sync[bot]"
           git config user.email "openclaw-docs-sync[bot]@users.noreply.github.com"
           git add docs .openclaw-sync
           git commit -m "chore(sync): mirror docs from $GITHUB_REPOSITORY@$GITHUB_SHA"
           for attempt in 1 2 3 4 5; do
-            if git fetch origin main && git rebase origin/main && git push origin HEAD:main; then
-              exit 0
+            if git fetch origin main:refs/remotes/origin/main; then
+              skip_stale_source
+              if git rebase -X theirs origin/main && git push origin HEAD:main; then
+                exit 0
+              fi
             fi
             git rebase --abort >/dev/null 2>&1 || true
             echo "Publish sync attempt ${attempt} failed; retrying."

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "**/*.md"
+      - "docs/**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ format('{0}-{1}', github.workflow, github.ref) }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  docs:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+          fetch-tags: false
+          persist-credentials: false
+          submodules: false
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          install-bun: "false"
+
+      - name: Check docs
+        run: pnpm check:docs

.github/workflows/install-smoke.yml

@@ -1,10 +1,6 @@
 name: Install Smoke
 
 on:
-  push:
-    branches: [main]
-  pull_request:
-    types: [opened, reopened, synchronize, ready_for_review, converted_to_draft]
   schedule:
     - cron: "17 3 * * *"
   workflow_dispatch:
@@ -30,7 +26,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: ${{ github.event_name == 'workflow_dispatch' && format('{0}-manual-{1}', github.workflow, github.run_id) || github.event_name == 'pull_request' && format('{0}-{1}', github.workflow, github.event.pull_request.number) || format('{0}-{1}', github.workflow, github.ref) }}
+  group: ${{ github.event_name == 'workflow_dispatch' && format('{0}-manual-{1}', github.workflow, github.run_id) || format('{0}-{1}', github.workflow, github.ref) }}
   cancel-in-progress: true
 
 env:
@@ -38,7 +34,6 @@ env:
 
 jobs:
   preflight:
-    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-24.04
     outputs:
       docs_only: ${{ steps.manifest.outputs.docs_only }}
@@ -56,67 +51,19 @@ jobs:
           persist-credentials: false
           submodules: false
 
-      - name: Ensure preflight base commit
-        if: github.event_name != 'workflow_dispatch' && github.event_name != 'schedule' && github.event_name != 'workflow_call'
-        uses: ./.github/actions/ensure-base-commit
-        with:
-          base-sha: ${{ github.event_name == 'push' && github.event.before || github.event.pull_request.base.sha }}
-          fetch-ref: ${{ github.event_name == 'push' && github.ref_name || github.event.pull_request.base.ref }}
-
-      - name: Detect docs-only changes
-        id: docs_scope
-        uses: ./.github/actions/detect-docs-changes
-
-      - name: Detect changed smoke scope
-        id: changed_scope
-        if: github.event_name != 'workflow_dispatch' && github.event_name != 'schedule' && github.event_name != 'workflow_call' && steps.docs_scope.outputs.docs_only != 'true'
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          if [ "${{ github.event_name }}" = "push" ]; then
-            BASE="${{ github.event.before }}"
-          else
-            BASE="${{ github.event.pull_request.base.sha }}"
-          fi
-
-          node scripts/ci-changed-scope.mjs --base "$BASE" --head HEAD
-
       - name: Build install-smoke CI manifest
         id: manifest
         env:
-          OPENCLAW_CI_DOCS_ONLY: ${{ steps.docs_scope.outputs.docs_only }}
           OPENCLAW_CI_EVENT_NAME: ${{ github.event_name }}
-          OPENCLAW_CI_FORCE_FULL_INSTALL_SMOKE: ${{ (github.event_name == 'workflow_dispatch' || github.event_name == 'schedule' || github.event_name == 'workflow_call') && 'true' || 'false' }}
           OPENCLAW_CI_WORKFLOW_BUN_GLOBAL_INSTALL_SMOKE: ${{ inputs.run_bun_global_install_smoke || 'false' }}
-          OPENCLAW_CI_RUN_FAST_INSTALL_SMOKE: ${{ steps.changed_scope.outputs.run_fast_install_smoke || steps.changed_scope.outputs.run_changed_smoke || 'false' }}
-          OPENCLAW_CI_RUN_FULL_INSTALL_SMOKE: ${{ steps.changed_scope.outputs.run_full_install_smoke || 'false' }}
         run: |
-          docs_only="${OPENCLAW_CI_DOCS_ONLY:-false}"
           event_name="${OPENCLAW_CI_EVENT_NAME:-}"
-          force_full_install_smoke="${OPENCLAW_CI_FORCE_FULL_INSTALL_SMOKE:-false}"
           workflow_bun_global_install_smoke="${OPENCLAW_CI_WORKFLOW_BUN_GLOBAL_INSTALL_SMOKE:-false}"
-          run_changed_fast_install_smoke="${OPENCLAW_CI_RUN_FAST_INSTALL_SMOKE:-false}"
-          run_changed_full_install_smoke="${OPENCLAW_CI_RUN_FULL_INSTALL_SMOKE:-false}"
-          run_fast_install_smoke=false
-          run_full_install_smoke=false
+          docs_only=false
+          run_fast_install_smoke=true
+          run_full_install_smoke=true
           run_bun_global_install_smoke=false
-          run_install_smoke=false
-          if [ "$force_full_install_smoke" = "true" ]; then
-            run_fast_install_smoke=true
-            run_full_install_smoke=true
-            run_install_smoke=true
-          elif [ "$docs_only" != "true" ] && [ "$event_name" != "push" ] && [ "$run_changed_full_install_smoke" = "true" ]; then
-            run_fast_install_smoke=true
-            run_full_install_smoke=true
-            run_install_smoke=true
-          elif [ "$docs_only" != "true" ] && [ "$run_changed_full_install_smoke" = "true" ]; then
-            run_fast_install_smoke=true
-            run_install_smoke=true
-          elif [ "$docs_only" != "true" ] && [ "$run_changed_fast_install_smoke" = "true" ]; then
-            run_fast_install_smoke=true
-            run_install_smoke=true
-          fi
+          run_install_smoke=true
           if [ "$event_name" = "schedule" ]; then
             run_bun_global_install_smoke=true
           elif [ "$event_name" = "workflow_dispatch" ] || [ "$event_name" = "workflow_call" ]; then
@@ -169,6 +116,12 @@ jobs:
         run: |
           docker run --rm --entrypoint sh openclaw-dockerfile-smoke:local -lc 'which openclaw && openclaw --version'
 
+      - name: Run agents delete shared workspace Docker CLI smoke
+        env:
+          OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE: openclaw-dockerfile-smoke:local
+          OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD: "1"
+        run: bash scripts/e2e/agents-delete-shared-workspace-docker.sh
+
       - name: Run Docker gateway network e2e
         env:
           OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE: openclaw-dockerfile-smoke:local
@@ -264,6 +217,12 @@ jobs:
         run: |
           docker run --rm --entrypoint sh openclaw-dockerfile-smoke:local -lc 'which openclaw && openclaw --version'
 
+      - name: Run agents delete shared workspace Docker CLI smoke
+        env:
+          OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE: openclaw-dockerfile-smoke:local
+          OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD: "1"
+        run: bash scripts/e2e/agents-delete-shared-workspace-docker.sh
+
       - name: Run Docker gateway network e2e
         env:
           OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE: openclaw-dockerfile-smoke:local
@@ -326,7 +285,6 @@ jobs:
           provenance: false
 
       - name: Build installer non-root image
-        if: github.event_name != 'pull_request'
         uses: useblacksmith/build-push-action@cbd1f60d194a98cb3be5523b15134501eaf0fbf3 # v2
         with:
           context: ./scripts/docker
@@ -356,8 +314,8 @@ jobs:
           OPENCLAW_NO_ONBOARD: "1"
           OPENCLAW_INSTALL_SMOKE_SKIP_CLI: "1"
           OPENCLAW_INSTALL_SMOKE_SKIP_IMAGE_BUILD: "1"
-          OPENCLAW_INSTALL_NONROOT_SKIP_IMAGE_BUILD: ${{ github.event_name == 'pull_request' && '0' || '1' }}
-          OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT: ${{ github.event_name == 'pull_request' && '1' || '0' }}
+          OPENCLAW_INSTALL_NONROOT_SKIP_IMAGE_BUILD: "1"
+          OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT: "0"
           OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL: "1"
           OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS: "1"
           OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE: latest
@@ -391,4 +349,5 @@ jobs:
       - name: Run fast bundled plugin Docker E2E
         env:
           OPENCLAW_BUNDLED_CHANNEL_DEPS_E2E_IMAGE: openclaw-bundled-channel-fast:local
-        run: timeout 120s pnpm test:docker:bundled-channel-deps:fast
+          OPENCLAW_BUNDLED_CHANNEL_DOCKER_RUN_TIMEOUT: 90s
+        run: timeout 240s pnpm test:docker:bundled-channel-deps:fast

.github/workflows/npm-telegram-beta-e2e.yml

@@ -0,0 +1,210 @@
+name: NPM Telegram Beta E2E
+
+on:
+  workflow_dispatch:
+    inputs:
+      package_spec:
+        description: Published OpenClaw package spec to test
+        required: true
+        default: openclaw@beta
+        type: string
+      provider_mode:
+        description: QA provider mode
+        required: true
+        default: mock-openai
+        type: choice
+        options:
+          - mock-openai
+          - live-frontier
+      scenario:
+        description: Optional comma-separated Telegram scenario ids
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: npm-telegram-beta-e2e-${{ github.run_id }}
+  cancel-in-progress: false
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  NODE_VERSION: "24.x"
+  PNPM_VERSION: "10.33.0"
+
+jobs:
+  validate_dispatch_ref:
+    name: Validate dispatch ref
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    steps:
+      - name: Require main workflow ref
+        env:
+          WORKFLOW_REF: ${{ github.ref }}
+        run: |
+          set -euo pipefail
+          if [[ "${WORKFLOW_REF}" != "refs/heads/main" ]]; then
+            echo "NPM Telegram beta E2E must be dispatched from main so workflow logic stays controlled." >&2
+            exit 1
+          fi
+
+  approve_release_manager:
+    name: Approve npm Telegram beta E2E
+    needs: validate_dispatch_ref
+    runs-on: ubuntu-latest
+    environment: npm-release
+    steps:
+      - name: Record approval
+        env:
+          PACKAGE_SPEC: ${{ inputs.package_spec }}
+        run: echo "Approved npm Telegram beta E2E for ${PACKAGE_SPEC}"
+
+  prepare_docker_e2e_image:
+    name: Prepare Docker E2E image
+    needs: validate_dispatch_ref
+    runs-on: blacksmith-32vcpu-ubuntu-2404
+    timeout-minutes: 90
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      image: ${{ steps.image.outputs.image }}
+    env:
+      DOCKER_BUILD_SUMMARY: "false"
+      DOCKER_BUILD_RECORD_UPLOAD: "false"
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 1
+
+      - name: Resolve Docker E2E image tag
+        id: image
+        shell: bash
+        env:
+          SELECTED_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          repository="${GITHUB_REPOSITORY,,}"
+          image="ghcr.io/${repository}-docker-e2e:${SELECTED_SHA}"
+          echo "image=$image" >> "$GITHUB_OUTPUT"
+          echo "Docker E2E image: \`$image\`" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Set up Blacksmith Docker Builder
+        uses: useblacksmith/setup-docker-builder@ac083cc84672d01c60d5e8561d0a939b697de542 # v1
+
+      - name: Log in to GHCR
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Build and push Docker E2E image
+        uses: useblacksmith/build-push-action@cbd1f60d194a98cb3be5523b15134501eaf0fbf3 # v2
+        with:
+          context: .
+          file: ./scripts/e2e/Dockerfile
+          target: build
+          platforms: linux/amd64
+          tags: ${{ steps.image.outputs.image }}
+          provenance: false
+          push: true
+
+  run_npm_telegram_beta_e2e:
+    name: Run published npm Telegram E2E
+    needs: [approve_release_manager, prepare_docker_e2e_image]
+    runs-on: blacksmith-32vcpu-ubuntu-2404
+    timeout-minutes: 60
+    environment: qa-live-shared
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 1
+
+      - name: Log in to GHCR
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+          install-bun: "true"
+
+      - name: Validate inputs and secrets
+        env:
+          PACKAGE_SPEC: ${{ inputs.package_spec }}
+          PROVIDER_MODE: ${{ inputs.provider_mode }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENCLAW_QA_CONVEX_SITE_URL: ${{ secrets.OPENCLAW_QA_CONVEX_SITE_URL }}
+          OPENCLAW_QA_CONVEX_SECRET_CI: ${{ secrets.OPENCLAW_QA_CONVEX_SECRET_CI }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ ! "${PACKAGE_SPEC}" =~ ^openclaw@(beta|latest|[0-9]{4}\.[1-9][0-9]*\.[1-9][0-9]*(-[1-9][0-9]*|-beta\.[1-9][0-9]*)?)$ ]]; then
+            echo "package_spec must be openclaw@beta, openclaw@latest, or an exact OpenClaw release version; got: ${PACKAGE_SPEC}" >&2
+            exit 1
+          fi
+
+          require_var() {
+            local key="$1"
+            if [[ -z "${!key:-}" ]]; then
+              echo "Missing required ${key}." >&2
+              exit 1
+            fi
+          }
+
+          require_var OPENCLAW_QA_CONVEX_SITE_URL
+          require_var OPENCLAW_QA_CONVEX_SECRET_CI
+          if [[ "${PROVIDER_MODE}" == "live-frontier" ]]; then
+            require_var OPENAI_API_KEY
+          fi
+
+      - name: Run npm Telegram beta E2E
+        id: run_lane
+        shell: bash
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENCLAW_SKIP_DOCKER_BUILD: "1"
+          OPENCLAW_DOCKER_E2E_IMAGE: ${{ needs.prepare_docker_e2e_image.outputs.image }}
+          OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC: ${{ inputs.package_spec }}
+          OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE: ${{ inputs.provider_mode }}
+          OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE: convex
+          OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE: ci
+          OPENCLAW_QA_CONVEX_SITE_URL: ${{ secrets.OPENCLAW_QA_CONVEX_SITE_URL }}
+          OPENCLAW_QA_CONVEX_SECRET_CI: ${{ secrets.OPENCLAW_QA_CONVEX_SECRET_CI }}
+          OPENCLAW_QA_REDACT_PUBLIC_METADATA: "1"
+          INPUT_SCENARIO: ${{ inputs.scenario }}
+        run: |
+          set -euo pipefail
+
+          output_dir=".artifacts/qa-e2e/npm-telegram-beta-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          echo "output_dir=${output_dir}" >> "$GITHUB_OUTPUT"
+          export OPENCLAW_NPM_TELEGRAM_OUTPUT_DIR="${output_dir}"
+
+          if [[ -n "${INPUT_SCENARIO// }" ]]; then
+            export OPENCLAW_NPM_TELEGRAM_SCENARIOS="${INPUT_SCENARIO}"
+          fi
+
+          pnpm test:docker:npm-telegram-live
+
+      - name: Upload npm Telegram E2E artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: npm-telegram-beta-e2e-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ steps.run_lane.outputs.output_dir }}
+          retention-days: 14
+          if-no-files-found: warn

.github/workflows/openclaw-cross-os-release-checks-reusable.yml

@@ -432,24 +432,35 @@ jobs:
           OPENCLAW_DISCORD_SMOKE_CHANNEL_ID: ${{ secrets.OPENCLAW_DISCORD_SMOKE_CHANNEL_ID }}
           OPENCLAW_RELEASE_CHECK_OS: ${{ matrix.os_id }}
           OPENCLAW_RELEASE_CHECK_RUNNER: ${{ matrix.runner }}
+          CANDIDATE_TGZ: ${{ runner.temp }}/openclaw-cross-os-release-checks/candidate/${{ needs.prepare.outputs.candidate_file_name }}
+          CANDIDATE_VERSION: ${{ needs.prepare.outputs.candidate_version }}
+          SOURCE_SHA: ${{ needs.prepare.outputs.source_sha }}
+          BASELINE_SPEC: ${{ needs.prepare.outputs.baseline_spec }}
+          PREVIOUS_VERSION: ${{ inputs.previous_version }}
+          BASELINE_TGZ: ${{ runner.temp }}/openclaw-cross-os-release-checks/baseline/${{ needs.prepare.outputs.baseline_file_name }}
+          PROVIDER: ${{ inputs.provider }}
+          MODE: ${{ matrix.lane }}
+          SUITE: ${{ matrix.suite }}
+          REF: ${{ inputs.ref }}
+          OUTPUT_DIR: ${{ runner.temp }}/openclaw-cross-os-release-checks/${{ matrix.artifact_name }}-${{ matrix.suite }}
         run: |
           DISCORD_ARGS=()
           if [[ -n "${OPENCLAW_DISCORD_SMOKE_BOT_TOKEN}" ]] && [[ -n "${OPENCLAW_DISCORD_SMOKE_GUILD_ID}" ]] && [[ -n "${OPENCLAW_DISCORD_SMOKE_CHANNEL_ID}" ]]; then
             DISCORD_ARGS+=(--run-discord-roundtrip true)
           fi
           pnpm dlx "tsx@${TSX_VERSION}" workflow/scripts/openclaw-cross-os-release-checks.ts \
-            --candidate-tgz "$RUNNER_TEMP/openclaw-cross-os-release-checks/candidate/${{ needs.prepare.outputs.candidate_file_name }}" \
-            --candidate-version "${{ needs.prepare.outputs.candidate_version }}" \
-            --source-sha "${{ needs.prepare.outputs.source_sha }}" \
-            --baseline-spec "${{ needs.prepare.outputs.baseline_spec }}" \
-            --previous-version "${{ inputs.previous_version }}" \
-            --baseline-tgz "$RUNNER_TEMP/openclaw-cross-os-release-checks/baseline/${{ needs.prepare.outputs.baseline_file_name }}" \
-            --provider "${{ inputs.provider }}" \
-            --mode "${{ matrix.lane }}" \
-            --suite "${{ matrix.suite }}" \
-            --ref "${{ inputs.ref }}" \
+            --candidate-tgz "${CANDIDATE_TGZ}" \
+            --candidate-version "${CANDIDATE_VERSION}" \
+            --source-sha "${SOURCE_SHA}" \
+            --baseline-spec "${BASELINE_SPEC}" \
+            --previous-version "${PREVIOUS_VERSION}" \
+            --baseline-tgz "${BASELINE_TGZ}" \
+            --provider "${PROVIDER}" \
+            --mode "${MODE}" \
+            --suite "${SUITE}" \
+            --ref "${REF}" \
             "${DISCORD_ARGS[@]}" \
-            --output-dir "$RUNNER_TEMP/openclaw-cross-os-release-checks/${{ matrix.artifact_name }}-${{ matrix.suite }}"
+            --output-dir "${OUTPUT_DIR}"
 
       - name: Summarize release checks
         if: always()

.github/workflows/openclaw-live-and-e2e-checks-reusable.yml

@@ -623,6 +623,9 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ github.token }}
 
+      - name: Setup Docker builder
+        uses: useblacksmith/setup-docker-builder@ac083cc84672d01c60d5e8561d0a939b697de542 # v1
+
       - name: Build and push shared Docker E2E image
         uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:

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

@@ -34,6 +34,7 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
   NODE_VERSION: "24.x"
   PNPM_VERSION: "10.33.0"
+  OPENCLAW_CI_OPENAI_MODEL: ${{ vars.OPENCLAW_CI_OPENAI_MODEL }}
 
 jobs:
   resolve_target:
@@ -245,13 +246,13 @@ jobs:
       - name: Build private QA runtime
         run: pnpm build
 
-      - name: Run GPT-5.4 lane
+      - name: Run OpenAI candidate lane
         run: |
           pnpm openclaw qa suite \
             --provider-mode mock-openai \
             --parity-pack agentic \
             --concurrency "${QA_PARITY_CONCURRENCY}" \
-            --model openai/gpt-5.4 \
+            --model "${OPENCLAW_CI_OPENAI_MODEL}" \
             --alt-model openai/gpt-5.4-alt \
             --output-dir .artifacts/qa-e2e/gpt54
 
@@ -271,7 +272,7 @@ jobs:
             --repo-root . \
             --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \
             --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \
-            --candidate-label openai/gpt-5.4 \
+            --candidate-label "${OPENCLAW_CI_OPENAI_MODEL}" \
             --baseline-label anthropic/claude-opus-4-6 \
             --output-dir .artifacts/qa-e2e/parity
 
@@ -341,8 +342,8 @@ jobs:
             --repo-root . \
             --output-dir "${output_dir}" \
             --provider-mode live-frontier \
-            --model openai/gpt-5.4 \
-            --alt-model openai/gpt-5.4 \
+            --model "${OPENCLAW_CI_OPENAI_MODEL}" \
+            --alt-model "${OPENCLAW_CI_OPENAI_MODEL}" \
             --fast
 
       - name: Upload Matrix QA artifacts
@@ -423,8 +424,8 @@ jobs:
             --repo-root . \
             --output-dir "${output_dir}" \
             --provider-mode live-frontier \
-            --model openai/gpt-5.4 \
-            --alt-model openai/gpt-5.4 \
+            --model "${OPENCLAW_CI_OPENAI_MODEL}" \
+            --alt-model "${OPENCLAW_CI_OPENAI_MODEL}" \
             --fast \
             --credential-source convex \
             --credential-role ci

.github/workflows/parity-gate.yml

@@ -24,7 +24,7 @@ concurrency:
 
 jobs:
   parity-gate:
-    name: Run the GPT-5.4 / Opus 4.6 parity gate against the qa-lab mock
+    name: Run the OpenAI / Opus 4.6 parity gate against the qa-lab mock
     if: ${{ github.event.pull_request.draft != true }}
     runs-on: blacksmith-32vcpu-ubuntu-2404
     timeout-minutes: 30
@@ -42,6 +42,7 @@ jobs:
       # followthrough gate that expects a fast post-approval read within a 30s
       # agent.wait timeout.
       QA_PARITY_CONCURRENCY: "1"
+      OPENCLAW_CI_OPENAI_MODEL: ${{ vars.OPENCLAW_CI_OPENAI_MODEL }}
       OPENCLAW_QA_TRANSPORT_READY_TIMEOUT_MS: "180000"
       OPENAI_API_KEY: ""
       ANTHROPIC_API_KEY: ""
@@ -75,13 +76,13 @@ jobs:
       # The approval-turn sentinel still runs inside the full parity pack below.
       # Keep the exact mock read-plan contract in deterministic unit tests instead
       # of paying for a separate full-runtime preflight that has been flaky in CI.
-      - name: Run GPT-5.4 lane
+      - name: Run OpenAI candidate lane
         run: |
           pnpm openclaw qa suite \
             --provider-mode mock-openai \
             --parity-pack agentic \
             --concurrency "${QA_PARITY_CONCURRENCY}" \
-            --model openai/gpt-5.4 \
+            --model "${OPENCLAW_CI_OPENAI_MODEL}" \
             --alt-model openai/gpt-5.4-alt \
             --output-dir .artifacts/qa-e2e/gpt54
 
@@ -101,7 +102,7 @@ jobs:
             --repo-root . \
             --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \
             --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \
-            --candidate-label openai/gpt-5.4 \
+            --candidate-label "${OPENCLAW_CI_OPENAI_MODEL}" \
             --baseline-label anthropic/claude-opus-4-6 \
             --output-dir .artifacts/qa-e2e/parity
 

.github/workflows/qa-live-transports-convex.yml

@@ -31,6 +31,7 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
   NODE_VERSION: "24.x"
   PNPM_VERSION: "10.33.0"
+  OPENCLAW_CI_OPENAI_MODEL: ${{ vars.OPENCLAW_CI_OPENAI_MODEL }}
   OPENCLAW_BUILD_PRIVATE_QA: "1"
   OPENCLAW_ENABLE_PRIVATE_QA_CLI: "1"
 
@@ -156,13 +157,13 @@ jobs:
       - name: Build private QA runtime
         run: pnpm build
 
-      - name: Run GPT-5.4 lane
+      - name: Run OpenAI candidate lane
         run: |
           pnpm openclaw qa suite \
             --provider-mode mock-openai \
             --parity-pack agentic \
             --concurrency "${QA_PARITY_CONCURRENCY}" \
-            --model openai/gpt-5.4 \
+            --model "${OPENCLAW_CI_OPENAI_MODEL}" \
             --alt-model openai/gpt-5.4-alt \
             --output-dir .artifacts/qa-e2e/gpt54
 
@@ -182,7 +183,7 @@ jobs:
             --repo-root . \
             --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \
             --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \
-            --candidate-label openai/gpt-5.4 \
+            --candidate-label "${OPENCLAW_CI_OPENAI_MODEL}" \
             --baseline-label anthropic/claude-opus-4-6 \
             --output-dir .artifacts/qa-e2e/parity
 
@@ -246,8 +247,8 @@ jobs:
             --repo-root . \
             --output-dir "${output_dir}" \
             --provider-mode live-frontier \
-            --model openai/gpt-5.4 \
-            --alt-model openai/gpt-5.4 \
+            --model "${OPENCLAW_CI_OPENAI_MODEL}" \
+            --alt-model "${OPENCLAW_CI_OPENAI_MODEL}" \
             --fast
 
       - name: Upload Matrix QA artifacts
@@ -335,8 +336,8 @@ jobs:
             --repo-root . \
             --output-dir "${output_dir}" \
             --provider-mode live-frontier \
-            --model openai/gpt-5.4 \
-            --alt-model openai/gpt-5.4 \
+            --model "${OPENCLAW_CI_OPENAI_MODEL}" \
+            --alt-model "${OPENCLAW_CI_OPENAI_MODEL}" \
             --fast \
             --credential-source convex \
             --credential-role ci \

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

@@ -133,7 +133,7 @@ jobs:
         with:
           openai-api-key: ${{ secrets.OPENCLAW_TEST_PERF_AGENT_OPENAI_API_KEY || secrets.OPENAI_API_KEY }}
           prompt-file: .github/codex/prompts/test-performance-agent.md
-          model: gpt-5.4
+          model: ${{ vars.OPENCLAW_CI_OPENAI_MODEL_BARE }}
           effort: high
           sandbox: workspace-write
           safety-strategy: drop-sudo

.gitignore

@@ -128,15 +128,14 @@ dist/protocol.schema.json
 # Synthing
 **/.stfolder/
 .dev-state
-docs/superpowers/plans/2026-03-10-collapsed-side-nav.md
-docs/superpowers/specs/2026-03-10-collapsed-side-nav-design.md
+docs/superpowers
+.superpowers/
 .gitignore
 test/config-form.analyze.telegram.test.ts
 ui/src/ui/theme-variants.browser.test.ts
 ui/src/ui/__screenshots__
 ui/src/ui/views/__screenshots__
 ui/.vitest-attachments
-docs/superpowers
 
 # Generated docs baseline artifacts (locally generated, only hashes tracked)
 docs/.generated/*.json
@@ -147,6 +146,7 @@ changelog/fragments/
 
 # Local scratch workspace
 .tmp/
+.vmux*
 .artifacts/
 test/fixtures/openclaw-vitest-unit-report.json
 analysis/

AGENTS.md

@@ -1,214 +1,168 @@
 # AGENTS.MD
 
-Telegraph style. Root rules only. Read scoped `AGENTS.md` before touching a subtree.
+Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work.
 
 ## Start
 
 - Repo: `https://github.com/openclaw/openclaw`
-- Replies: repo-root file refs only, e.g. `extensions/telegram/src/index.ts:80`. No absolute paths, no `~/`.
-- CODEOWNERS: maintenance/refactors/tests are ok. For larger behavior, product, security, or ownership-sensitive changes, get a listed owner request/review first.
-- First pass: run docs list (`pnpm docs:list`; ignore if unavailable), then read only relevant docs/guides.
-- Missing deps: run `pnpm install`, rerun once, then report first actionable error.
-- Use "plugin/plugins" in docs/UI/changelog. `extensions/` remains internal workspace layout.
-- Add channel/plugin/app/doc surface: update `.github/labeler.yml` and matching GitHub labels.
-- New `AGENTS.md`: add sibling `CLAUDE.md` symlink to it.
+- Replies: repo-root refs only: `extensions/telegram/src/index.ts:80`. No absolute paths, no `~/`.
+- Run docs list first: `pnpm docs:list` if available; read relevant docs only.
+- High-confidence answers only when fixing/triaging: verify source, tests, shipped/current behavior, and dependency contracts before deciding.
+- Dependency-backed behavior: read upstream dependency docs/source/types first. Do not assume APIs, defaults, errors, timing, or runtime behavior.
+- Live-verify when feasible. Check env/`~/.profile` for keys before assuming live tests are blocked; keep secret output redacted.
+- Missing deps: `pnpm install`, retry once, then report first actionable error.
+- CODEOWNERS: maint/refactor/tests ok. Larger behavior/product/security/ownership: owner ask/review.
+- Wording: product/docs/UI/changelog say "plugin/plugins"; `extensions/` is internal.
+- New channel/plugin/app/doc surface: update `.github/labeler.yml` + GH labels.
+- New `AGENTS.md`: add sibling `CLAUDE.md` symlink.
 
-## Repo Map
+## Map
 
-- Core TS: `src/`, `ui/`, `packages/`
-- Bundled plugins: `extensions/`
-- Plugin SDK/public contract: `src/plugin-sdk/*`
-- Core channel internals: `src/channels/*`
-- Plugin loader/registry/contracts: `src/plugins/*`
-- Gateway protocol: `src/gateway/protocol/*`
-- Docs: `docs/`
-- Apps: `apps/`, `Swabble/`
-- Installers served from `openclaw.ai`: sibling `../openclaw.ai`
-
-Scoped guides:
-
-- `extensions/AGENTS.md`: bundled plugin rules
-- `src/plugin-sdk/AGENTS.md`: public SDK rules
-- `src/channels/AGENTS.md`: channel core rules
-- `src/plugins/AGENTS.md`: plugin loader/registry rules
-- `src/gateway/AGENTS.md`, `src/gateway/protocol/AGENTS.md`: gateway/protocol rules
-- `src/agents/AGENTS.md`: agent import/test perf rules
-- `test/helpers/AGENTS.md`, `test/helpers/channels/AGENTS.md`: shared test helpers
-- `docs/AGENTS.md`, `ui/AGENTS.md`, `scripts/AGENTS.md`: docs/UI/scripts
+- Core TS: `src/`, `ui/`, `packages/`; plugins: `extensions/`; SDK: `src/plugin-sdk/*`; channels: `src/channels/*`; loader: `src/plugins/*`; protocol: `src/gateway/protocol/*`; docs/apps: `docs/`, `apps/`, `Swabble/`.
+- Installers: sibling `../openclaw.ai`.
+- Scoped guides exist in: `extensions/`, `src/{plugin-sdk,channels,plugins,gateway,gateway/protocol,agents}/`, `test/helpers*/`, `docs/`, `ui/`, `scripts/`.
 
 ## Architecture
 
-- Core must stay extension-agnostic. No core special cases for bundled plugin/provider/channel ids when manifest/registry/capability contracts can express it.
-- Extensions cross into core only via `openclaw/plugin-sdk/*`, manifest metadata, injected runtime helpers, and documented local barrels (`api.ts`, `runtime-api.ts`).
-- Extension production code must not import core `src/**`, `src/plugin-sdk-internal/**`, another extension's `src/**`, or relative paths outside its package.
-- Core code/tests must not deep-import plugin internals (`extensions/*/src/**`, `onboard.js`). Use plugin `api.ts` / public SDK facade / generic contract.
-- Extension-owned behavior stays in the extension: legacy repair, detection, onboarding, auth/provider defaults, provider tools/settings.
-- Legacy config repair: prefer doctor/fix paths over startup/load-time core migrations.
-- If a core test asserts extension-specific behavior, move it to the owning extension or a generic contract test.
+- Core stays extension-agnostic. No bundled ids in core when manifest/registry/capability contracts work.
+- Extensions cross into core only via `openclaw/plugin-sdk/*`, manifest metadata, injected runtime helpers, documented barrels (`api.ts`, `runtime-api.ts`).
+- Extension prod code: no core `src/**`, `src/plugin-sdk-internal/**`, other extension `src/**`, or relative outside package.
+- Core/tests: no deep plugin internals (`extensions/*/src/**`, `onboard.js`). Use `api.ts`, SDK facade, generic contracts.
+- Extension-owned behavior stays extension-owned: repair, detection, onboarding, auth/provider defaults, provider tools/settings.
+- Legacy config repair: doctor/fix paths, not startup/load-time core migrations.
+- Core test asserting extension-specific behavior: move to owner extension or generic contract test.
 - New seams: backwards-compatible, documented, versioned. Third-party plugins exist.
-- Channels: `src/channels/**` is implementation. Plugin authors get SDK seams, not channel internals.
-- Providers: core owns generic inference loop; provider plugins own provider-specific auth/catalog/runtime hooks.
-- Gateway protocol changes are contract changes: additive first; incompatible needs versioning/docs/client follow-through.
-- Config contract: keep exported types, schema/help, generated metadata, baselines, docs aligned. Retired public keys stay retired; compatibility belongs in raw migration/doctor paths.
-- Plugin architecture direction: manifest-first control plane; targeted runtime loaders; no hidden paths around declared contracts; broad mutable registries are transitional.
-- Prompt-cache rule: deterministic ordering for maps/sets/registries/plugin lists/files/network results before model/tool payloads. Preserve old transcript bytes when possible.
+- Channels: `src/channels/**` is implementation; plugin authors get SDK seams.
+- Providers: core owns generic loop; provider plugins own auth/catalog/runtime hooks.
+- Gateway protocol changes: additive first; incompatible needs versioning/docs/client follow-through.
+- Config contract: exported types, schema/help, metadata, baselines, docs aligned. Retired public keys stay retired; compat in raw migration/doctor.
+- Direction: manifest-first control plane; targeted runtime loaders; no hidden contract bypasses; broad mutable registries transitional.
+- Prompt cache: deterministic ordering for maps/sets/registries/plugin lists/files/network results before model/tool payloads. Preserve old transcript bytes when possible.
 
 ## Commands
 
-- Runtime: Node 22+. Keep Node and Bun paths working.
-- Install: `pnpm install` (Bun supported; keep lockfiles/patches aligned if touched).
-- Dev CLI: `pnpm openclaw ...` or `pnpm dev`.
-- Build: `pnpm build`
-- Smart local gate: `pnpm check:changed` (scoped typecheck/lint/guards + relevant tests)
-- Explain smart gate: `pnpm changed:lanes --json`
-- Staged gate preview: `pnpm check:changed --staged`
-- Normal full prod sweep: `pnpm check` (prod typecheck/lint/guards, no tests)
-- Full tests: `pnpm test`
-- Changed tests only: `pnpm test:changed`
-- Local serial loop: `pnpm test:serial`
-- Extension tests: `pnpm test:extensions` or `pnpm test extensions` = all extension shards; `pnpm test extensions/<id>` = one extension lane. Heavy channels/OpenAI have dedicated shards.
-- Shard timing artifact: `.artifacts/vitest-shard-timings.json`; auto-used for balanced shard ordering. Disable with `OPENCLAW_TEST_PROJECTS_TIMINGS=0`.
-- Targeted tests: `pnpm test <path-or-filter> [vitest args...]`; do not call raw `vitest`.
-- Coverage: `pnpm test:coverage`
-- Format check/fix: `pnpm format:check` / `pnpm format`
-- Typecheck:
-  - `pnpm tsgo`: fastest core prod graph
-  - `pnpm tsgo:prod`: core + extensions prod graphs; used by `pnpm check`
-  - `pnpm check:test-types` / `pnpm tsgo:test`: all test graphs
-  - `pnpm tsgo:all`: all prod + test project refs
-  - Debug slices exist; do not present as normal user flow.
-  - Profile: `pnpm tsgo:profile [core-test|extensions-test|--all]`
-- Type policy: use `tsgo`; do not add `tsc --noEmit`, `typecheck`, or `check:types` lanes. `tsc` only for declaration/package-boundary emit gaps.
-- Lint:
-  - `pnpm lint`: core/extensions/scripts shards
-  - `pnpm lint:core`, `pnpm lint:extensions`, `pnpm lint:scripts`
-  - `pnpm lint:apps`: Swift/app surface, separate from TS lint
-  - `pnpm lint:all`: legacy comparison lane
-- Local heavy-check behavior: `OPENCLAW_LOCAL_CHECK=1` default; `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`; `OPENCLAW_LOCAL_CHECK=0` for CI/shared runs.
-- Local validation is local-first. Do not default to Blacksmith/Testbox for routine OpenClaw iteration; it burns warm caches and startup time. Use repo `pnpm` lanes first, then reach for remote CI/Testbox only for parity-only failures, secrets/services, or when explicitly requested.
+- Runtime: Node 22+. Keep Node + Bun paths working.
+- Install: `pnpm install` (keep Bun lock/patches aligned if touched).
+- CLI: `pnpm openclaw ...` or `pnpm dev`; build: `pnpm build`.
+- Smart gate: `pnpm check:changed`; explain `pnpm changed:lanes --json`; staged preview `pnpm check:changed --staged`.
+- Sparse worktrees: `pnpm check:changed` is sparse-safe and may skip sparse-missing typecheck projects; do not expand sparse checkout just to satisfy changed-gate tsgo. Direct `pnpm tsgo*` remains strict; use a fuller worktree when you need direct typecheck proof.
+- Prod sweep: `pnpm check`; tests: `pnpm test`, `pnpm test:changed`, `pnpm test:serial`, `pnpm test:coverage`.
+- Extension tests: `pnpm test:extensions`, `pnpm test extensions`, `pnpm test extensions/<id>`.
+- Targeted tests: `pnpm test <path-or-filter> [vitest args...]`; never raw `vitest`.
+- Typecheck: `tsgo` lanes only (`pnpm tsgo*`, `pnpm check:test-types`); do not add `tsc --noEmit`, `typecheck`, `check:types`.
+- Format/lint: `pnpm format:check`/`pnpm format`; `pnpm lint*` lanes.
+- Heavy checks: `OPENCLAW_LOCAL_CHECK=1`, mode `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`; CI/shared use `OPENCLAW_LOCAL_CHECK=0`.
+- Local first. Use repo `pnpm` lanes before Blacksmith/Testbox. Remote only for parity-only failures, secrets/services, or explicit ask.
 
-## GitHub API
+## GitHub / CI
 
-- Issue/PR triage: list first, hydrate few. Use bounded fields + `--jq`, e.g. `gh issue list --state open --limit 80 --json number,title,labels,updatedAt,comments --jq '.[]|[.number,.updatedAt,.comments,.title]|@tsv'`; then `gh issue view <n> --json title,body,comments,labels,createdAt,updatedAt,url --jq '{title,labels,createdAt,updatedAt,url,body,comments:[.comments[]|{author:.author.login,createdAt,body}]}'` only for shortlisted items.
-- Search/dedupe: prefer `gh search issues 'repo:openclaw/openclaw is:open <terms>' --json number,title,state,updatedAt --limit 20 --jq '.[]|[.number,.updatedAt,.title]|@tsv'`; avoid repeated full `--comments` scans.
-- After landing a PR: search for duplicate open issues/PRs that can be closed.
-- Before closing an issue/PR: add a comment explaining why, usually duplicate/invalid, with the canonical issue/PR when relevant.
-- PR links: `gh pr list --state open --search '<issue-or-terms>' --json number,title,updatedAt,headRefName --limit 20`; use `gh pr view <n> --json number,title,body,closingIssuesReferences,files,statusCheckRollup,reviewDecision` only after shortlist.
-- CI polling: keep full `gh` capability, but request only needed fields. Known run status: `gh api repos/<owner>/<repo>/actions/runs/<id> --jq '{status,conclusion,head_sha,updated_at,name,path}'`.
-- Non-blocking background workflows: `Auto response`, `Docs Sync Publish Repo`, `Docs Agent`, and `Test Performance Agent` are service/agent work. Do not wait on, rerun, or fix them during normal push/PR verification unless the user explicitly asks or the task is about those workflows. Report them as background if mentioned.
-- `/landpr` CI wait scope: do not idle on pending `auto-response`/`Auto response` or `check-docs`. Treat docs as local proof unless `check-docs` already failed with a relevant, actionable error. If required product/code gates and touched-surface local gates are green, proceed without waiting for docs-only or auto-response automation.
-- Waiting: poll lightly, usually 30-60s backoff. Fetch jobs/logs/artifacts only after completion/failure or when job detail is needed; avoid repeated workflow + run + jobs loops.
+- Triage: list first, hydrate few. Use bounded `gh --json --jq`; avoid repeated full comment scans.
+- Search/dedupe: prefer `gh search issues 'repo:openclaw/openclaw is:open <terms>' --json number,title,state,updatedAt --limit 20`.
+- PR shortlist: `gh pr list ...`; then `gh pr view <n> --json number,title,body,closingIssuesReferences,files,statusCheckRollup,reviewDecision`.
+- After landing PR: search duplicate open issues/PRs. Before closing: comment why + canonical link.
+- GH comments with markdown backticks, `$`, or shell snippets: avoid inline double-quoted `--body`; use single quotes or `--body-file`.
+- PR execution artifacts/screenshots: attach them to the PR, comment, or an external artifact store. Do not add `.github/pr-assets` or other PR-only assets to the repo.
+- PR review answer must explicitly cover: what bug/behavior we are trying to fix; PR/issue URL(s) and affected endpoint/surface; whether this is the best possible fix, with high-certainty evidence from code, tests, CI, and shipped/current behavior.
+- CI polling: exact SHA, needed fields only. Example: `gh api repos/<owner>/<repo>/actions/runs/<id> --jq '{status,conclusion,head_sha,updated_at,name,path}'`.
+- Post-land wait: minimal. Exact landed SHA only. If superseded on `main`, same-branch `cancel-in-progress` cancellations are expected; stop once local touched-surface proof exists. Never wait for newer unrelated `main` unless asked.
+- Wait matrix:
+  - never: `Auto response`, `Labeler`, `Docs Sync Publish Repo`, `Docs Agent`, `Test Performance Agent`, `Stale`.
+  - conditional: `CI` exact SHA only; `Docs` only docs task/no local docs proof; `Workflow Sanity` only workflow/composite/CI-policy edits; `Plugin NPM Release` only plugin package/release metadata.
+  - release/manual only: `Docker Release`, `OpenClaw NPM Release`, `macOS Release`, `OpenClaw Release Checks`, `Cross-OS Release Checks`, `NPM Telegram Beta E2E`.
+  - explicit/surface only: `QA-Lab - All Lanes`, `Scheduled Live And E2E`, `Install Smoke`, `CodeQL`, `Sandbox Common Smoke`, `Parity gate`, `Blacksmith Testbox`, `Control UI Locale Refresh`.
+- `/landpr`: do not idle on `auto-response` or `check-docs`. Treat docs as local proof unless `check-docs` already failed with actionable relevant error.
+- Poll 30-60s. Fetch jobs/logs/artifacts only after failure/completion or concrete need.
 
 ## Gates
 
-- Pre-commit hook: staged formatting only. It does not run lint, typecheck, or tests.
+- Pre-commit hook: staged formatting only. Validation explicit.
 - Changed lanes:
-  - core prod => core prod typecheck + core tests
-  - core tests => core test typecheck/tests only
-  - extension prod => extension prod typecheck + extension tests
-  - extension tests => extension test typecheck/tests only
-  - public SDK/plugin contract => extension prod/test validation too
-  - unknown root/config => all lanes
-- Local loop: run `pnpm check:changed` explicitly before handoff/push; use `pnpm test:changed` for tests only; use `pnpm check` for full prod TS/lint sweep without tests.
-- Landing on `main`: verify touched surface near landing; default bar is `pnpm check` + `pnpm test` when feasible.
-- Hard build gate: run/pass `pnpm build` before push if build output, packaging, lazy/module boundaries, or published surfaces can change.
-- Do not land related failing format/lint/type/build/tests. If failures are unrelated on latest `origin/main`, say so and give scoped proof.
-- Commit helper is formatting-only; validation gates are explicit commands, not commit side effects.
-- CI architecture gate: `check-additional`; local equivalent `pnpm check:architecture`.
-- Config docs drift: `pnpm config:docs:gen/check`
-- Plugin SDK API drift: `pnpm plugin-sdk:api:gen/check`
-- Generated docs baselines: tracked `docs/.generated/*.sha256`; full JSON ignored.
+  - core prod: core prod typecheck + core tests
+  - core tests: core test typecheck/tests
+  - extension prod: extension prod typecheck + extension tests
+  - extension tests: extension test typecheck/tests
+  - public SDK/plugin contract: extension prod/test too
+  - unknown root/config: all lanes
+- Before handoff/push: `pnpm check:changed`. Tests-only: `pnpm test:changed`. Full prod sweep: `pnpm check`.
+- Landing on `main`: verify touched surface near landing. Default feasible bar: `pnpm check` + `pnpm test`.
+- Hard build gate: `pnpm build` before push if build output, packaging, lazy/module boundaries, or published surfaces can change.
+- Do not land related failing format/lint/type/build/tests. If unrelated on latest `origin/main`, say so with scoped proof.
+- Generated/API drift: `pnpm check:architecture`, `pnpm config:docs:gen/check`, `pnpm plugin-sdk:api:gen/check`. Track `docs/.generated/*.sha256`; full JSON ignored.
 
-## Code Style
+## Code
 
-- TypeScript ESM. Strict types. Avoid `any`; prefer real types/`unknown`/narrow adapters.
-- No `@ts-nocheck`. No lint suppressions unless intentional and explained.
+- TS ESM, strict. Avoid `any`; prefer real types, `unknown`, narrow adapters.
+- No `@ts-nocheck`. Lint suppressions only intentional + explained.
 - External boundaries: prefer `zod` or existing schema helpers.
-- Runtime branching: prefer discriminated unions / closed codes over freeform strings.
-- Avoid magic sentinels like `?? 0`, empty object/string when semantics change.
-- Dynamic import: do not mix static and dynamic import for same module in prod path. Use dedicated `*.runtime.ts` lazy boundary. After lazy-boundary edits, run `pnpm build` and check `[INEFFECTIVE_DYNAMIC_IMPORT]`.
-- Cycles: keep `pnpm check:import-cycles` and architecture/madge cycle checks green.
-- Classes: no prototype mixins/mutations. Use explicit inheritance/composition. Tests prefer per-instance stubs.
-- Comments: brief only for non-obvious logic.
-- File size: split around ~700 LOC when it improves clarity/testability.
-- Product naming: **OpenClaw** product/docs; `openclaw` CLI/package/path/config.
-- Written English: American spelling.
+- Runtime branching: discriminated unions/closed codes over freeform strings.
+- Avoid semantic sentinels: `?? 0`, empty object/string, etc.
+- Dynamic import: no static+dynamic import for same prod module. Use `*.runtime.ts` lazy boundary. After edits: `pnpm build`; check `[INEFFECTIVE_DYNAMIC_IMPORT]`.
+- Cycles: keep `pnpm check:import-cycles` + architecture/madge green.
+- Classes: no prototype mixins/mutations. Prefer inheritance/composition. Tests prefer per-instance stubs.
+- Comments: brief, only non-obvious logic.
+- Split files around ~700 LOC when clarity/testability improves.
+- Naming: **OpenClaw** product/docs; `openclaw` CLI/package/path/config.
+- English: American spelling.
 
 ## Tests
 
-- Vitest. Tests colocated `*.test.ts`; e2e `*.e2e.test.ts`.
-- Example models in tests: `sonnet-4.6`, `gpt-5.4`.
-- Clean up timers/env/globals/mocks/sockets/temp dirs/module state; `--isolate=false` must stay safe.
-- Hot tests: avoid per-test `vi.resetModules()` + fresh heavy imports; prefer static or `beforeAll` imports and reset state directly.
-- Measure first: `pnpm test:perf:imports <file>` for import drag; `pnpm test:perf:hotspots --limit N` for suite targets.
-- Keep tests at seam depth: unit-test pure helpers/contracts; one integration smoke per boundary, not per branch.
-- Mock expensive runtime seams directly: scanners, manifests, package registries, filesystem crawls, provider SDKs, network/process launch.
-- Prefer injected deps over module mocks; if mocking modules, mock narrow local `*.runtime.ts` seams, not broad barrels.
-- Share fixtures/builders; do not recreate temp dirs, package manifests, or plugin workspaces in every case unless state isolation needs it.
-- Delete duplicate assertions when another test owns the boundary; assert only the behavior that can regress here.
-- Avoid broad `importOriginal()` / broad `openclaw/plugin-sdk/*` partial mocks in hot tests. Add narrow local `*.runtime.ts` seam and mock it.
-- Use existing deps/callback/runtime injection seams before module mocks.
-- Import-dominated test time is a boundary smell; shrink import surface before adding cases.
-- Replacing slow integration coverage: extract production composition into a named helper and test that helper.
-- Do not modify baseline/inventory/ignore/snapshot/expected-failure files to silence checks without explicit approval.
-- Do not set test workers above 16. For memory pressure: `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`.
-- Live: `OPENCLAW_LIVE_TEST=1 pnpm test:live`; full logs `OPENCLAW_LIVE_TEST_QUIET=0`.
-- Full testing guide: `docs/help/testing.md`.
+- Vitest. Colocated `*.test.ts`; e2e `*.e2e.test.ts`; example models `sonnet-4.6`, `gpt-5.4`.
+- Clean timers/env/globals/mocks/sockets/temp dirs/module state; `--isolate=false` safe.
+- Hot tests: avoid per-test `vi.resetModules()` + heavy imports. Measure with `pnpm test:perf:imports <file>` / `pnpm test:perf:hotspots --limit N`.
+- Seam depth: pure helper/contract unit tests; one integration smoke per boundary.
+- Mock expensive seams directly: scanners, manifests, registries, fs crawls, provider SDKs, network/process launch.
+- Prefer injection; if module mocking, mock narrow local `*.runtime.ts`, not broad barrels or `openclaw/plugin-sdk/*`.
+- Share fixtures/builders; delete duplicate assertions; assert behavior that can regress here.
+- Do not edit baseline/inventory/ignore/snapshot/expected-failure files to silence checks without explicit approval.
+- Test workers max 16. Memory pressure: `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`.
+- Live: `OPENCLAW_LIVE_TEST=1 pnpm test:live`; verbose `OPENCLAW_LIVE_TEST_QUIET=0`.
+- Guide: `docs/help/testing.md`.
 
 ## Docs / Changelog
 
-- Update docs when behavior/API changes. Use docs list/read_when hints.
-- Docs links: see `docs/AGENTS.md`.
-- Changelog: user-facing only. Pure test/internal changes usually no entry.
-- Changelog placement: append to active version `### Changes`/`### Fixes`; at most one contributor mention, prefer `Thanks @user`.
+- Docs change with behavior/API. Use docs list/read_when hints; docs links per `docs/AGENTS.md`.
+- Changelog user-facing only; pure test/internal usually no entry.
+- Changelog placement: active version `### Changes`/`### Fixes`; every added entry must include at least one `Thanks @author` attribution, using credited GitHub username(s).
 
 ## Git
 
-- Use `scripts/committer "<msg>" <file...>`; stage only intended files. It formats staged files only; run validation separately.
-- Commits: conventional-ish, concise/action-oriented. Group related changes.
-- No manual stash/autostash unless explicitly requested. No branch/worktree changes unless requested.
-- No merge commits on `main`; rebase on latest `origin/main` before push.
-- User says "commit": commit your changes only. "commit all": commit everything in grouped chunks. "push": may `git pull --rebase` first.
-- Do not delete/rename unexpected files; ask if it blocks. Otherwise ignore unrelated WIP.
-- If bulk PR close/reopen affects >5 PRs, ask with exact count/scope.
-- PR/issue workflows: use `$openclaw-pr-maintainer`.
-- `/landpr`: use `~/.codex/prompts/landpr.md`.
+- Commit via `scripts/committer "<msg>" <file...>`; stage intended files only. It formats staged files; still run gates.
+- Commits: conventional-ish, concise, grouped.
+- No manual stash/autostash unless explicit. No branch/worktree changes unless requested.
+- `main`: no merge commits; rebase on latest `origin/main` before push.
+- User says `commit`: your changes only. `commit all`: all changes in grouped chunks. `push`: may `git pull --rebase` first.
+- Do not delete/rename unexpected files; ask if blocking, else ignore.
+- Bulk PR close/reopen >5: ask with count/scope.
+- PR/issue workflows: `$openclaw-pr-maintainer`. `/landpr`: `~/.codex/prompts/landpr.md`.
 
 ## Security / Release
 
 - Never commit real phone numbers, videos, credentials, live config.
-- Secrets: channel/provider credentials under `~/.openclaw/credentials/`; model auth profiles under `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`.
+- Secrets: channel/provider creds in `~/.openclaw/credentials/`; model auth profiles in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`.
 - Env keys: check `~/.profile`.
-- Dependency patches/overrides/vendor changes require explicit approval. `pnpm.patchedDependencies` must use exact versions.
-- Carbon pins owner-only: do not change `@buape/carbon` versions unless Shadow (`@thewilloftheshadow`, verified by `gh`) asks.
-- Releases/publish/version bumps require explicit approval.
-- Release docs: `docs/reference/RELEASING.md`; use `$openclaw-release-maintainer`.
-- GHSA/advisories: use `$openclaw-ghsa-maintainer`.
-- Beta tag/version must match, e.g. `vYYYY.M.D-beta.N` => npm `YYYY.M.D-beta.N --tag beta`.
+- Dependency patches/overrides/vendor changes need explicit approval. `pnpm.patchedDependencies` exact versions only.
+- Carbon pins owner-only: do not change `@buape/carbon` unless Shadow (`@thewilloftheshadow`, verified by `gh`) asks.
+- Releases/publish/version bumps need explicit approval. Release docs: `docs/reference/RELEASING.md`; use `$openclaw-release-maintainer`.
+- GHSA/advisories: `$openclaw-ghsa-maintainer`.
+- Beta tag/version match: `vYYYY.M.D-beta.N` -> npm `YYYY.M.D-beta.N --tag beta`.
 
 ## Apps / Platform
 
-- Before simulator/emulator testing, check connected real iOS/Android devices first.
+- Before simulator/emulator testing, check real iOS/Android devices.
 - "restart iOS/Android apps" = rebuild/reinstall/relaunch, not kill/launch.
-- SwiftUI: prefer Observation (`@Observable`, `@Bindable`) over new `ObservableObject`.
-- mac gateway: use app or `openclaw gateway restart/status --deep`; avoid ad-hoc tmux gateway sessions. Rebuild mac app locally, not over SSH.
-- mac logs: `./scripts/clawlog.sh`.
-- Version bump touches: `package.json`, `apps/android/app/build.gradle.kts`, `apps/ios/version.json` then `pnpm ios:version:sync`, `apps/macos/.../Info.plist`, `docs/install/updating.md`. Appcast only for Sparkle release.
-- iOS Team ID: `security find-identity -p codesigning -v`; fallback `defaults read com.apple.dt.Xcode IDEProvisioningTeamIdentifiers`.
-- Mobile LAN pairing: plaintext `ws://` is loopback-only by default. Trusted private-network `ws://` needs `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`; Tailscale/public use `wss://` or a tunnel.
+- SwiftUI: Observation (`@Observable`, `@Bindable`) over new `ObservableObject`.
+- Mac gateway: use app or `openclaw gateway restart/status --deep`; no ad-hoc tmux gateway. Logs: `./scripts/clawlog.sh`.
+- Version bump touches: `package.json`, `apps/android/app/build.gradle.kts`, `apps/ios/version.json` + `pnpm ios:version:sync`, macOS `Info.plist`, `docs/install/updating.md`. Appcast only for Sparkle release.
+- Mobile LAN pairing: plaintext `ws://` loopback-only. Private-network `ws://` needs `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`; Tailscale/public use `wss://` or tunnel.
 - A2UI hash `src/canvas-host/a2ui/.bundle.hash`: generated; ignore unless running `pnpm canvas:a2ui:bundle`; commit separately.
 
-## External Ops
-
-- Remote install docs: `docs/install/exe-dev.md`, `docs/install/fly.md`, `docs/install/hetzner.md`.
-- Parallels smoke: `$openclaw-parallels-smoke`; Discord roundtrip: `parallels-discord-roundtrip`.
-
-## Misc Footguns
+## Ops / Footguns
 
+- Remote install docs: `docs/install/{exe-dev,fly,hetzner}.md`. Parallels smoke: `$openclaw-parallels-smoke`; Discord roundtrip: `parallels-discord-roundtrip`.
 - Rebrand/migration/config warnings: run `openclaw doctor`.
 - Never edit `node_modules`.
-- Local-only `.agents` ignores: use `.git/info/exclude`, not repo `.gitignore`.
-- CLI progress: use `src/cli/progress.ts`; status tables: `src/terminal/table.ts`.
+- Local-only `.agents` ignores: `.git/info/exclude`, not repo `.gitignore`.
+- CLI progress: `src/cli/progress.ts`; status tables: `src/terminal/table.ts`.
 - Connection/provider additions: update all UI surfaces + docs + status/config forms.
-- Provider-facing tool schemas: prefer flat string enum helpers over `Type.Union([Type.Literal(...)])`; some providers reject generated `anyOf`. Do not treat this as a repo-wide protocol/schema ban.
-- External messaging surfaces: no token-delta channel messages. Follow `docs/concepts/streaming.md`; preview/block streaming uses message edits/chunks and must preserve final/fallback delivery.
+- Provider tool schemas: prefer flat string enum helpers over `Type.Union([Type.Literal(...)])`; some providers reject `anyOf`. Not a repo-wide protocol/schema ban.
+- External messaging: no token-delta channel messages. Follow `docs/concepts/streaming.md`; preview/block streaming uses edits/chunks and preserves final/fallback delivery.

Dockerfile

@@ -29,9 +29,9 @@ ARG OPENCLAW_NODE_BOOKWORM_SLIM_DIGEST="sha256:e8e2e91b1378f83c5b2dd15f0247f3411
 FROM ${OPENCLAW_NODE_BOOKWORM_IMAGE} AS ext-deps
 ARG OPENCLAW_EXTENSIONS
 ARG OPENCLAW_BUNDLED_PLUGIN_DIR
-COPY ${OPENCLAW_BUNDLED_PLUGIN_DIR} /tmp/${OPENCLAW_BUNDLED_PLUGIN_DIR}
 # Copy package.json for opted-in extensions so pnpm resolves their deps.
-RUN mkdir -p /out && \
+RUN --mount=type=bind,source=${OPENCLAW_BUNDLED_PLUGIN_DIR},target=/tmp/${OPENCLAW_BUNDLED_PLUGIN_DIR},readonly \
+    mkdir -p /out && \
     for ext in $OPENCLAW_EXTENSIONS; do \
       if [ -f "/tmp/${OPENCLAW_BUNDLED_PLUGIN_DIR}/$ext/package.json" ]; then \
         mkdir -p "/out/$ext" && \

README.md

@@ -96,7 +96,7 @@ Model note: while many providers and models are supported, prefer a current flag
 
 ## Install (recommended)
 
-Runtime: **Node 24 (recommended) or Node 22.16+**.
+Runtime: **Node 24 (recommended) or Node 22.14+**.
 
 ```bash
 npm install -g openclaw@latest
@@ -109,7 +109,7 @@ OpenClaw Onboard installs the Gateway daemon (launchd/systemd user service) so i
 
 ## Quick start (TL;DR)
 
-Runtime: **Node 24 (recommended) or Node 22.16+**.
+Runtime: **Node 24 (recommended) or Node 22.14+**.
 
 Full beginner guide (auth, pairing, channels): [Getting started](https://docs.openclaw.ai/start/getting-started)
 
@@ -119,7 +119,7 @@ openclaw onboard --install-daemon
 openclaw gateway --port 18789 --verbose
 
 # Send a message
-openclaw message send --to +1234567890 --message "Hello from OpenClaw"
+openclaw message send --target +1234567890 --message "Hello from OpenClaw"
 
 # Talk to the assistant (optionally deliver back to any connected channel: WhatsApp/Telegram/Slack/Discord/Google Chat/Signal/iMessage/BlueBubbles/IRC/Microsoft Teams/Matrix/Feishu/LINE/Mattermost/Nextcloud Talk/Nostr/Synology Chat/Tlon/Twitch/Zalo/Zalo Personal/WeChat/QQ/WebChat)
 openclaw agent --message "Ship checklist" --thinking high

SECURITY.md

@@ -288,7 +288,7 @@ OpenClaw's web interface (Gateway Control UI + HTTP endpoints) is intended for *
 
 ### Node.js Version
 
-OpenClaw requires **Node.js 22.12.0 or later** (LTS). This version includes important security patches:
+OpenClaw requires **Node.js 22.14.0 or later** (LTS). This version includes important security patches:
 
 - CVE-2025-59466: async_hooks DoS vulnerability
 - CVE-2026-21636: Permission model bypass vulnerability
@@ -296,7 +296,7 @@ OpenClaw requires **Node.js 22.12.0 or later** (LTS). This version includes impo
 Verify your Node.js version:
 
 ```bash
-node --version  # Should be v22.12.0 or later
+node --version  # Should be v22.14.0 or later
 ```
 
 ### Docker Security

VISION.md

@@ -53,12 +53,24 @@ We prioritize secure defaults, but also expose clear knobs for trusted high-powe
 
 OpenClaw has an extensive plugin API.
 Core stays lean; optional capability should usually ship as plugins.
+We are generally slimming down core while expanding what plugins can do.
+If a useful feature cannot be built as a plugin yet, we welcome PRs and design discussions that extend the plugin API instead of adding one-off core behavior.
+
+There are two broad plugin styles:
+
+- Code plugins run OpenClaw plugin code and are appropriate for deeper runtime extension.
+- Bundle-style plugins package stable external surfaces such as skills, MCP servers, and related configuration.
+
+Prefer bundle-style plugins when they can express the capability.
+They have a smaller, more stable interface and better security boundaries.
+Use code plugins when the capability needs runtime hooks, providers, channels, tools, or other in-process extension points.
 
 Preferred plugin path is npm package distribution plus local extension loading for development.
 If you build a plugin, host and maintain it in your own repository.
 The bar for adding optional plugins to core is intentionally high.
 Plugin docs: [`docs/tools/plugin.md`](docs/tools/plugin.md)
-Community plugin listing + PR bar: https://docs.openclaw.ai/plugins/community
+Plugin discovery, official publisher status, provenance, and security review live in [ClawHub](https://clawhub.ai/).
+OpenClaw docs should document core extension points; plugin promotion belongs in ClawHub, preferably under vetted org publishers for official plugins.
 
 Memory is a special plugin slot where only one memory plugin can be active at a time.
 Today we ship multiple memory options; over time we plan to converge on one recommended default path.
@@ -66,21 +78,16 @@ Today we ship multiple memory options; over time we plan to converge on one reco
 ### Skills
 
 We still ship some bundled skills for baseline UX.
-New skills should be published to ClawHub first (`clawhub.ai`), not added to core by default.
-Core skill additions should be rare and require a strong product or security reason.
+New skills should be published through [ClawHub](https://clawhub.ai/) first, not added to core by default.
+Official or bundled promotion should require a clear product, security, or maintainer-ownership reason.
 
 ### MCP Support
 
-OpenClaw supports MCP through `mcporter`: https://github.com/steipete/mcporter
+OpenClaw supports MCP as both a server and a runtime integration surface.
+MCP details live in [`docs/cli/mcp.md`](docs/cli/mcp.md).
 
-This keeps MCP integration flexible and decoupled from core runtime:
-
-- add or change MCP servers without restarting the gateway
-- keep core tool/context surface lean
-- reduce MCP churn impact on core stability and security
-
-For now, we prefer this bridge model over building first-class MCP runtime into core.
-If there is an MCP server or feature `mcporter` does not support yet, please open an issue there.
+The project goal is pragmatic MCP support without duplicating existing agent,
+tool, ACPX, plugin, or ClawHub paths.
 
 ### Setup
 
@@ -98,11 +105,11 @@ It is widely known, fast to iterate in, and easy to read, modify, and extend.
 
 ## What We Will Not Merge (For Now)
 
-- New core skills when they can live on ClawHub
+- New core skills when they can live on [ClawHub](https://clawhub.ai/)
 - Full-doc translation sets for all docs (deferred; we plan AI-generated translations later)
 - Commercial service integrations that do not clearly fit the model-provider category
 - Wrapper channels around already supported channels without a clear capability or security gap
-- First-class MCP runtime in core when `mcporter` already provides the integration path
+- MCP work that duplicates existing MCP, ACPX, plugin, or ClawHub paths without a clear product or security gap
 - Agent-hierarchy frameworks (manager-of-managers / nested planner trees) as a default architecture
 - Heavy orchestration layers that duplicate existing agent and tool infrastructure
 

apps/android/app/build.gradle.kts

@@ -65,8 +65,8 @@ android {
         applicationId = "ai.openclaw.app"
         minSdk = 31
         targetSdk = 36
-        versionCode = 2026042400
-        versionName = "2026.4.24"
+        versionCode = 2026042500
+        versionName = "2026.4.25"
         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/AndroidManifest.xml

@@ -3,6 +3,7 @@
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
     <uses-permission
         android:name="android.permission.NEARBY_WIFI_DEVICES"
@@ -52,7 +53,7 @@
         <service
             android:name=".NodeForegroundService"
             android:exported="false"
-            android:foregroundServiceType="dataSync" />
+            android:foregroundServiceType="dataSync|microphone" />
         <service
             android:name=".node.DeviceNotificationListenerService"
             android:label="@string/app_name"

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

@@ -101,7 +101,8 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
   val onboardingCompleted: StateFlow<Boolean> = prefs.onboardingCompleted
   val canvasDebugStatusEnabled: StateFlow<Boolean> = prefs.canvasDebugStatusEnabled
   val speakerEnabled: StateFlow<Boolean> = prefs.speakerEnabled
-  val micEnabled: StateFlow<Boolean> = prefs.talkEnabled
+  val voiceCaptureMode: StateFlow<VoiceCaptureMode> = runtimeState(initial = VoiceCaptureMode.Off) { it.voiceCaptureMode }
+  val micEnabled: StateFlow<Boolean> = runtimeState(initial = false) { it.micEnabled }
 
   val micCooldown: StateFlow<Boolean> = runtimeState(initial = false) { it.micCooldown }
   val micStatusText: StateFlow<String> = runtimeState(initial = "Mic off") { it.micStatusText }
@@ -111,6 +112,10 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
   val micConversation: StateFlow<List<VoiceConversationEntry>> = runtimeState(initial = emptyList()) { it.micConversation }
   val micInputLevel: StateFlow<Float> = runtimeState(initial = 0f) { it.micInputLevel }
   val micIsSending: StateFlow<Boolean> = runtimeState(initial = false) { it.micIsSending }
+  val talkModeEnabled: StateFlow<Boolean> = runtimeState(initial = false) { it.talkModeEnabled }
+  val talkModeListening: StateFlow<Boolean> = runtimeState(initial = false) { it.talkModeListening }
+  val talkModeSpeaking: StateFlow<Boolean> = runtimeState(initial = false) { it.talkModeSpeaking }
+  val talkModeStatusText: StateFlow<String> = runtimeState(initial = "Off") { it.talkModeStatusText }
 
   val chatSessionKey: StateFlow<String> = runtimeState(initial = "main") { it.chatSessionKey }
   val chatSessionId: StateFlow<String?> = runtimeState(initial = null) { it.chatSessionId }
@@ -283,6 +288,10 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
     ensureRuntime().setMicEnabled(enabled)
   }
 
+  fun setTalkModeEnabled(enabled: Boolean) {
+    ensureRuntime().setTalkModeEnabled(enabled)
+  }
+
   fun setSpeakerEnabled(enabled: Boolean) {
     ensureRuntime().setSpeakerEnabled(enabled)
   }

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

@@ -3,12 +3,14 @@ package ai.openclaw.app
 import android.app.Notification
 import android.app.NotificationChannel
 import android.app.NotificationManager
-import android.app.Service
 import android.app.PendingIntent
+import android.app.Service
 import android.content.Context
 import android.content.Intent
 import android.content.pm.ServiceInfo
 import androidx.core.app.NotificationCompat
+import androidx.core.app.ServiceCompat
+import androidx.core.content.ContextCompat
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
@@ -21,6 +23,7 @@ class NodeForegroundService : Service() {
   private val scope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
   private var notificationJob: Job? = null
   private var didStartForeground = false
+  private var voiceCaptureMode = VoiceCaptureMode.Off
 
   override fun onCreate() {
     super.onCreate()
@@ -36,22 +39,51 @@ class NodeForegroundService : Service() {
     notificationJob =
       scope.launch {
         combine(
-          runtime.statusText,
-          runtime.serverName,
-          runtime.isConnected,
-          runtime.micEnabled,
-          runtime.micIsListening,
-        ) { status, server, connected, micEnabled, micListening ->
-          Quint(status, server, connected, micEnabled, micListening)
-        }.collect { (status, server, connected, micEnabled, micListening) ->
-          val title = if (connected) "OpenClaw Node · Connected" else "OpenClaw Node"
-          val micSuffix =
-            if (micEnabled) {
-              if (micListening) " · Mic: Listening" else " · Mic: Pending"
-            } else {
-              ""
+          combine(
+            runtime.statusText,
+            runtime.serverName,
+            runtime.isConnected,
+            runtime.voiceCaptureMode,
+          ) { status, server, connected, mode ->
+            VoiceNotificationBase(
+              status = status,
+              server = server,
+              connected = connected,
+              mode = mode,
+            )
+          },
+          combine(
+            runtime.micEnabled,
+            runtime.micIsListening,
+            runtime.talkModeListening,
+            runtime.talkModeSpeaking,
+          ) { micEnabled, micListening, talkListening, talkSpeaking ->
+            VoiceNotificationCapture(
+              micEnabled = micEnabled,
+              micListening = micListening,
+              talkListening = talkListening,
+              talkSpeaking = talkSpeaking,
+            )
+          },
+        ) { base, capture ->
+          VoiceNotificationState(base = base, capture = capture)
+        }.collect { state ->
+          voiceCaptureMode = state.mode
+          val title =
+            when {
+              state.connected && state.mode == VoiceCaptureMode.TalkMode -> "OpenClaw Node · Talk"
+              state.connected -> "OpenClaw Node · Connected"
+              else -> "OpenClaw Node"
             }
-          val text = (server?.let { "$status · $it" } ?: status) + micSuffix
+          val text =
+            (state.server?.let { "${state.status} · $it" } ?: state.status) +
+              voiceNotificationSuffix(
+                mode = state.mode,
+                manualMicEnabled = state.capture.micEnabled,
+                manualMicListening = state.capture.micListening,
+                talkListening = state.capture.talkListening,
+                talkSpeaking = state.capture.talkSpeaking,
+              )
 
           startForegroundWithTypes(
             notification = buildNotification(title = title, text = text),
@@ -60,13 +92,27 @@ class NodeForegroundService : Service() {
       }
   }
 
-  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+  override fun onStartCommand(
+    intent: Intent?,
+    flags: Int,
+    startId: Int,
+  ): Int {
     when (intent?.action) {
       ACTION_STOP -> {
         (application as NodeApp).peekRuntime()?.disconnect()
         stopSelf()
         return START_NOT_STICKY
       }
+      ACTION_SET_VOICE_CAPTURE_MODE -> {
+        voiceCaptureMode = intent.getStringExtra(EXTRA_VOICE_CAPTURE_MODE).toVoiceCaptureMode()
+        startForegroundWithTypes(
+          notification =
+            buildNotification(
+              title = "OpenClaw Node",
+              text = if (voiceCaptureMode == VoiceCaptureMode.TalkMode) "Talk mode active" else "Connected",
+            ),
+        )
+      }
     }
     // Keep running; connection is managed by NodeRuntime (auto-reconnect + manual).
     return START_STICKY
@@ -127,17 +173,13 @@ class NodeForegroundService : Service() {
       .build()
   }
 
-  private fun updateNotification(notification: Notification) {
-    val mgr = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
-    mgr.notify(NOTIFICATION_ID, notification)
-  }
-
   private fun startForegroundWithTypes(notification: Notification) {
+    val serviceTypes = foregroundServiceTypesForVoiceMode(voiceCaptureMode)
     if (didStartForeground) {
-      updateNotification(notification)
+      ServiceCompat.startForeground(this, NOTIFICATION_ID, notification, serviceTypes)
       return
     }
-    startForeground(NOTIFICATION_ID, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC)
+    ServiceCompat.startForeground(this, NOTIFICATION_ID, notification, serviceTypes)
     didStartForeground = true
   }
 
@@ -146,6 +188,8 @@ class NodeForegroundService : Service() {
     private const val NOTIFICATION_ID = 1
 
     private const val ACTION_STOP = "ai.openclaw.app.action.STOP"
+    private const val ACTION_SET_VOICE_CAPTURE_MODE = "ai.openclaw.app.action.SET_VOICE_CAPTURE_MODE"
+    private const val EXTRA_VOICE_CAPTURE_MODE = "ai.openclaw.app.extra.VOICE_CAPTURE_MODE"
 
     fun start(context: Context) {
       val intent = Intent(context, NodeForegroundService::class.java)
@@ -156,7 +200,85 @@ class NodeForegroundService : Service() {
       val intent = Intent(context, NodeForegroundService::class.java).setAction(ACTION_STOP)
       context.startService(intent)
     }
+
+    fun setVoiceCaptureMode(
+      context: Context,
+      mode: VoiceCaptureMode,
+    ) {
+      val intent =
+        Intent(context, NodeForegroundService::class.java)
+          .setAction(ACTION_SET_VOICE_CAPTURE_MODE)
+          .putExtra(EXTRA_VOICE_CAPTURE_MODE, mode.name)
+      if (mode == VoiceCaptureMode.TalkMode) {
+        ContextCompat.startForegroundService(context, intent)
+      } else {
+        context.startService(intent)
+      }
+    }
   }
 }
 
-private data class Quint<A, B, C, D, E>(val first: A, val second: B, val third: C, val fourth: D, val fifth: E)
+internal fun foregroundServiceTypesForVoiceMode(mode: VoiceCaptureMode): Int {
+  val base = ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC
+  return if (mode == VoiceCaptureMode.TalkMode) {
+    base or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
+  } else {
+    base
+  }
+}
+
+internal fun voiceNotificationSuffix(
+  mode: VoiceCaptureMode,
+  manualMicEnabled: Boolean,
+  manualMicListening: Boolean,
+  talkListening: Boolean,
+  talkSpeaking: Boolean,
+): String {
+  return when (mode) {
+    VoiceCaptureMode.TalkMode ->
+      when {
+        talkSpeaking -> " · Talk: Speaking"
+        talkListening -> " · Talk: Listening"
+        else -> " · Talk: On"
+      }
+    VoiceCaptureMode.ManualMic ->
+      if (manualMicEnabled) {
+        if (manualMicListening) " · Mic: Listening" else " · Mic: Pending"
+      } else {
+        ""
+      }
+    VoiceCaptureMode.Off -> ""
+  }
+}
+
+private fun String?.toVoiceCaptureMode(): VoiceCaptureMode {
+  return VoiceCaptureMode.entries.firstOrNull { it.name == this } ?: VoiceCaptureMode.Off
+}
+
+private data class VoiceNotificationBase(
+  val status: String,
+  val server: String?,
+  val connected: Boolean,
+  val mode: VoiceCaptureMode,
+)
+
+private data class VoiceNotificationCapture(
+  val micEnabled: Boolean,
+  val micListening: Boolean,
+  val talkListening: Boolean,
+  val talkSpeaking: Boolean,
+)
+
+private data class VoiceNotificationState(
+  val base: VoiceNotificationBase,
+  val capture: VoiceNotificationCapture,
+) {
+  val status: String
+    get() = base.status
+  val server: String?
+    get() = base.server
+  val connected: Boolean
+    get() = base.connected
+  val mode: VoiceCaptureMode
+    get() = base.mode
+}

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

@@ -64,6 +64,8 @@ class NodeRuntime(
   private val json = Json { ignoreUnknownKeys = true }
 
   private val externalAudioCaptureActive = MutableStateFlow(false)
+  private val _voiceCaptureMode = MutableStateFlow(VoiceCaptureMode.Off)
+  val voiceCaptureMode: StateFlow<VoiceCaptureMode> = _voiceCaptureMode.asStateFlow()
 
   private val discovery = GatewayDiscovery(appContext, scope = scope)
   val gateways: StateFlow<List<GatewayEndpoint>> = discovery.gateways
@@ -428,6 +430,18 @@ class NodeRuntime(
     )
   }
 
+  val talkModeEnabled: StateFlow<Boolean>
+    get() = talkMode.isEnabled
+
+  val talkModeListening: StateFlow<Boolean>
+    get() = talkMode.isListening
+
+  val talkModeSpeaking: StateFlow<Boolean>
+    get() = talkMode.isSpeaking
+
+  val talkModeStatusText: StateFlow<String>
+    get() = talkMode.statusText
+
   private fun syncMainSessionKey(agentId: String?) {
     val resolvedKey = resolveNodeMainSessionKey(agentId)
     // Always push the resolved session key into TalkMode, even when the
@@ -599,17 +613,8 @@ class NodeRuntime(
       prefs.loadGatewayToken()
     }
 
-    scope.launch {
-      prefs.talkEnabled.collect { enabled ->
-        // 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) {
-          talkMode.ttsOnAllResponses = false
-          scope.launch { talkMode.ensureChatSubscribed() }
-        }
-        externalAudioCaptureActive.value = enabled
-      }
+    if (prefs.voiceMicEnabled.value) {
+      setVoiceCaptureMode(VoiceCaptureMode.ManualMic, persistManualMic = false)
     }
 
     scope.launch(Dispatchers.Default) {
@@ -643,7 +648,7 @@ class NodeRuntime(
     if (value) {
       reconnectPreferredGatewayOnForeground()
     } else {
-      stopActiveVoiceSession()
+      stopManualVoiceSession()
     }
   }
 
@@ -757,21 +762,17 @@ class NodeRuntime(
 
   fun setVoiceScreenActive(active: Boolean) {
     if (!active) {
-      stopActiveVoiceSession()
+      stopManualVoiceSession()
     }
     // Don't re-enable on active=true; mic toggle drives that
   }
 
   fun setMicEnabled(value: Boolean) {
-    prefs.setTalkEnabled(value)
-    if (value) {
-      // Tapping mic on interrupts any active TTS (barge-in)
-      stopVoicePlayback()
-      talkMode.ttsOnAllResponses = false
-      scope.launch { talkMode.ensureChatSubscribed() }
-    }
-    micCapture.setMicEnabled(value)
-    externalAudioCaptureActive.value = value
+    setVoiceCaptureMode(if (value) VoiceCaptureMode.ManualMic else VoiceCaptureMode.Off)
+  }
+
+  fun setTalkModeEnabled(value: Boolean) {
+    setVoiceCaptureMode(if (value) VoiceCaptureMode.TalkMode else VoiceCaptureMode.Off)
   }
 
   val speakerEnabled: StateFlow<Boolean>
@@ -786,11 +787,72 @@ class NodeRuntime(
     talkMode.setPlaybackEnabled(value)
   }
 
+  private fun setVoiceCaptureMode(
+    mode: VoiceCaptureMode,
+    persistManualMic: Boolean = true,
+  ) {
+    if (mode == VoiceCaptureMode.TalkMode && !hasRecordAudioPermission()) {
+      _voiceCaptureMode.value = VoiceCaptureMode.Off
+      externalAudioCaptureActive.value = false
+      return
+    }
+    if (_voiceCaptureMode.value == mode) return
+    _voiceCaptureMode.value = mode
+    when (mode) {
+      VoiceCaptureMode.Off -> {
+        talkMode.ttsOnAllResponses = false
+        talkMode.setEnabled(false)
+        stopVoicePlayback()
+        micCapture.setMicEnabled(false)
+        if (persistManualMic) {
+          prefs.setVoiceMicEnabled(false)
+        }
+        NodeForegroundService.setVoiceCaptureMode(appContext, VoiceCaptureMode.Off)
+        externalAudioCaptureActive.value = false
+      }
+
+      VoiceCaptureMode.ManualMic -> {
+        talkMode.ttsOnAllResponses = false
+        talkMode.setEnabled(false)
+        NodeForegroundService.setVoiceCaptureMode(appContext, VoiceCaptureMode.ManualMic)
+        if (persistManualMic) {
+          prefs.setVoiceMicEnabled(true)
+        }
+        // Tapping mic on interrupts any active TTS (barge-in).
+        stopVoicePlayback()
+        scope.launch { talkMode.ensureChatSubscribed() }
+        micCapture.setMicEnabled(true)
+        externalAudioCaptureActive.value = true
+      }
+
+      VoiceCaptureMode.TalkMode -> {
+        if (persistManualMic) {
+          prefs.setVoiceMicEnabled(false)
+        }
+        micCapture.setMicEnabled(false)
+        NodeForegroundService.setVoiceCaptureMode(appContext, VoiceCaptureMode.TalkMode)
+        talkMode.ttsOnAllResponses = true
+        talkMode.setPlaybackEnabled(speakerEnabled.value)
+        scope.launch { talkMode.ensureChatSubscribed() }
+        talkMode.setEnabled(true)
+        externalAudioCaptureActive.value = true
+      }
+    }
+  }
+
+  private fun stopManualVoiceSession() {
+    if (_voiceCaptureMode.value != VoiceCaptureMode.ManualMic) return
+    setVoiceCaptureMode(VoiceCaptureMode.Off)
+  }
+
   private fun stopActiveVoiceSession() {
     talkMode.ttsOnAllResponses = false
+    talkMode.setEnabled(false)
     stopVoicePlayback()
     micCapture.setMicEnabled(false)
-    prefs.setTalkEnabled(false)
+    prefs.setVoiceMicEnabled(false)
+    NodeForegroundService.setVoiceCaptureMode(appContext, VoiceCaptureMode.Off)
+    _voiceCaptureMode.value = VoiceCaptureMode.Off
     externalAudioCaptureActive.value = false
   }
 
@@ -970,6 +1032,7 @@ class NodeRuntime(
   }
 
   fun disconnect() {
+    stopActiveVoiceSession()
     connectedEndpoint = null
     activeGatewayAuth = null
     _pendingGatewayTrust.value = null

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

@@ -37,6 +37,7 @@ class SecurePrefs(
     private const val notificationsForwardingMaxEventsPerMinuteKey =
       "notifications.forwarding.maxEventsPerMinute"
     private const val notificationsForwardingSessionKeyKey = "notifications.forwarding.sessionKey"
+    private const val voiceMicEnabledKey = "voice.micEnabled"
   }
 
   private val appContext = context.applicationContext
@@ -162,8 +163,8 @@ class SecurePrefs(
   private val _voiceWakeMode = MutableStateFlow(loadVoiceWakeMode())
   val voiceWakeMode: StateFlow<VoiceWakeMode> = _voiceWakeMode
 
-  private val _talkEnabled = MutableStateFlow(plainPrefs.getBoolean("talk.enabled", false))
-  val talkEnabled: StateFlow<Boolean> = _talkEnabled
+  private val _voiceMicEnabled = MutableStateFlow(plainPrefs.getBoolean(voiceMicEnabledKey, false))
+  val voiceMicEnabled: StateFlow<Boolean> = _voiceMicEnabled
 
   private val _speakerEnabled = MutableStateFlow(plainPrefs.getBoolean("voice.speakerEnabled", true))
   val speakerEnabled: StateFlow<Boolean> = _speakerEnabled
@@ -478,9 +479,9 @@ class SecurePrefs(
     _voiceWakeMode.value = mode
   }
 
-  fun setTalkEnabled(value: Boolean) {
-    plainPrefs.edit { putBoolean("talk.enabled", value) }
-    _talkEnabled.value = value
+  fun setVoiceMicEnabled(value: Boolean) {
+    plainPrefs.edit { putBoolean(voiceMicEnabledKey, value) }
+    _voiceMicEnabled.value = value
   }
 
   fun setSpeakerEnabled(value: Boolean) {

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

@@ -0,0 +1,7 @@
+package ai.openclaw.app
+
+enum class VoiceCaptureMode {
+  Off,
+  ManualMic,
+  TalkMode,
+}

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

@@ -35,10 +35,11 @@ import androidx.compose.foundation.lazy.rememberLazyListState
 import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material.icons.Icons
-import androidx.compose.material.icons.filled.Mic
-import androidx.compose.material.icons.filled.MicOff
 import androidx.compose.material.icons.automirrored.filled.VolumeOff
 import androidx.compose.material.icons.automirrored.filled.VolumeUp
+import androidx.compose.material.icons.filled.Mic
+import androidx.compose.material.icons.filled.MicOff
+import androidx.compose.material.icons.filled.RecordVoiceOver
 import androidx.compose.material3.Button
 import androidx.compose.material3.ButtonDefaults
 import androidx.compose.material3.Icon
@@ -69,6 +70,7 @@ import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleEventObserver
 import androidx.lifecycle.compose.LocalLifecycleOwner
 import ai.openclaw.app.MainViewModel
+import ai.openclaw.app.VoiceCaptureMode
 import ai.openclaw.app.voice.VoiceConversationEntry
 import ai.openclaw.app.voice.VoiceConversationRole
 import kotlin.math.max
@@ -81,6 +83,7 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
   val listState = rememberLazyListState()
 
   val gatewayStatus by viewModel.statusText.collectAsState()
+  val voiceCaptureMode by viewModel.voiceCaptureMode.collectAsState()
   val micEnabled by viewModel.micEnabled.collectAsState()
   val micCooldown by viewModel.micCooldown.collectAsState()
   val speakerEnabled by viewModel.speakerEnabled.collectAsState()
@@ -90,12 +93,15 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
   val micConversation by viewModel.micConversation.collectAsState()
   val micInputLevel by viewModel.micInputLevel.collectAsState()
   val micIsSending by viewModel.micIsSending.collectAsState()
+  val talkModeEnabled by viewModel.talkModeEnabled.collectAsState()
+  val talkModeListening by viewModel.talkModeListening.collectAsState()
+  val talkModeSpeaking by viewModel.talkModeSpeaking.collectAsState()
 
   val hasStreamingAssistant = micConversation.any { it.role == VoiceConversationRole.Assistant && it.isStreaming }
   val showThinkingBubble = micIsSending && !hasStreamingAssistant
 
   var hasMicPermission by remember { mutableStateOf(context.hasRecordAudioPermission()) }
-  var pendingMicEnable by remember { mutableStateOf(false) }
+  var pendingVoicePermissionAction by remember { mutableStateOf<PendingVoicePermissionAction?>(null) }
 
   DisposableEffect(lifecycleOwner, context) {
     val observer =
@@ -107,7 +113,7 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
     lifecycleOwner.lifecycle.addObserver(observer)
     onDispose {
       lifecycleOwner.lifecycle.removeObserver(observer)
-      // Stop TTS when leaving the voice screen
+      // Manual mic is tied to the Voice tab; Talk Mode is explicit and can continue.
       viewModel.setVoiceScreenActive(false)
     }
   }
@@ -115,10 +121,14 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
   val requestMicPermission =
     rememberLauncherForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
       hasMicPermission = granted
-      if (granted && pendingMicEnable) {
-        viewModel.setMicEnabled(true)
+      if (granted) {
+        when (pendingVoicePermissionAction) {
+          PendingVoicePermissionAction.ManualMic -> viewModel.setMicEnabled(true)
+          PendingVoicePermissionAction.TalkMode -> viewModel.setTalkModeEnabled(true)
+          null -> Unit
+        }
       }
-      pendingMicEnable = false
+      pendingVoicePermissionAction = null
     }
 
   LaunchedEffect(micConversation.size, showThinkingBubble) {
@@ -161,12 +171,12 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
                 tint = mobileTextTertiary,
               )
               Text(
-                "Tap the mic to start",
+                "Tap mic or Talk",
                 style = mobileHeadline,
                 color = mobileTextSecondary,
               )
               Text(
-                "Each pause sends a turn automatically.",
+                "Mic sends turns; Talk keeps the conversation open.",
                 style = mobileCallout,
                 color = mobileTextTertiary,
               )
@@ -263,7 +273,7 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
               if (hasMicPermission) {
                 viewModel.setMicEnabled(true)
               } else {
-                pendingMicEnable = true
+                pendingVoicePermissionAction = PendingVoicePermissionAction.ManualMic
                 requestMicPermission.launch(Manifest.permission.RECORD_AUDIO)
               }
             },
@@ -287,11 +297,39 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
           }
         }
 
-        // Invisible spacer to balance the row (matches speaker column width)
-        Column(horizontalAlignment = Alignment.CenterHorizontally) {
-          Box(modifier = Modifier.size(48.dp))
+        Column(horizontalAlignment = Alignment.CenterHorizontally, verticalArrangement = Arrangement.spacedBy(4.dp)) {
+          IconButton(
+            onClick = {
+              if (talkModeEnabled) {
+                viewModel.setTalkModeEnabled(false)
+                return@IconButton
+              }
+              if (hasMicPermission) {
+                viewModel.setTalkModeEnabled(true)
+              } else {
+                pendingVoicePermissionAction = PendingVoicePermissionAction.TalkMode
+                requestMicPermission.launch(Manifest.permission.RECORD_AUDIO)
+              }
+            },
+            modifier = Modifier.size(48.dp),
+            colors =
+              IconButtonDefaults.iconButtonColors(
+                containerColor = if (talkModeEnabled) mobileSuccessSoft else mobileSurface,
+              ),
+          ) {
+            Icon(
+              imageVector = Icons.Default.RecordVoiceOver,
+              contentDescription = if (talkModeEnabled) "Turn Talk Mode off" else "Turn Talk Mode on",
+              modifier = Modifier.size(22.dp),
+              tint = if (talkModeEnabled) mobileSuccess else mobileTextSecondary,
+            )
+          }
           Spacer(modifier = Modifier.height(4.dp))
-          Text("", style = mobileCaption2)
+          Text(
+            if (talkModeEnabled) "Talk on" else "Talk",
+            style = mobileCaption2,
+            color = if (talkModeEnabled) mobileSuccess else mobileTextTertiary,
+          )
         }
       }
 
@@ -299,6 +337,9 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
       val queueCount = micQueuedMessages.size
       val stateText =
         when {
+          voiceCaptureMode == VoiceCaptureMode.TalkMode && talkModeSpeaking -> "Talk speaking"
+          voiceCaptureMode == VoiceCaptureMode.TalkMode && talkModeListening -> "Talk listening"
+          voiceCaptureMode == VoiceCaptureMode.TalkMode -> "Talk on"
           queueCount > 0 -> "$queueCount queued"
           micIsSending -> "Sending"
           micCooldown -> "Cooldown"
@@ -307,14 +348,15 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
         }
       val stateColor =
         when {
+          voiceCaptureMode == VoiceCaptureMode.TalkMode -> mobileSuccess
           micEnabled -> mobileSuccess
           micIsSending -> mobileAccent
           else -> mobileTextSecondary
         }
       Surface(
         shape = RoundedCornerShape(999.dp),
-        color = if (micEnabled) mobileSuccessSoft else mobileSurface,
-        border = BorderStroke(1.dp, if (micEnabled) mobileSuccess.copy(alpha = 0.3f) else mobileBorder),
+        color = if (micEnabled || talkModeEnabled) mobileSuccessSoft else mobileSurface,
+        border = BorderStroke(1.dp, if (micEnabled || talkModeEnabled) mobileSuccess.copy(alpha = 0.3f) else mobileBorder),
       ) {
         Text(
           "$gatewayStatus · $stateText",
@@ -353,6 +395,11 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
   }
 }
 
+private enum class PendingVoicePermissionAction {
+  ManualMic,
+  TalkMode,
+}
+
 @Composable
 private fun VoiceTurnBubble(entry: VoiceConversationEntry) {
   val isUser = entry.role == VoiceConversationRole.User

apps/android/app/src/test/java/ai/openclaw/app/NodeForegroundServiceTest.kt

@@ -2,6 +2,7 @@ package ai.openclaw.app
 
 import android.app.Notification
 import android.content.Intent
+import android.content.pm.ServiceInfo
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNotNull
 import org.junit.Test
@@ -30,6 +31,35 @@ class NodeForegroundServiceTest {
     assertEquals(expectedFlags, savedIntent.flags and expectedFlags)
   }
 
+  @Test
+  fun foregroundServiceTypesForVoiceMode_addsMicrophoneOnlyForTalkMode() {
+    assertEquals(
+      ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+      foregroundServiceTypesForVoiceMode(VoiceCaptureMode.Off),
+    )
+    assertEquals(
+      ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+      foregroundServiceTypesForVoiceMode(VoiceCaptureMode.ManualMic),
+    )
+    assertEquals(
+      ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE,
+      foregroundServiceTypesForVoiceMode(VoiceCaptureMode.TalkMode),
+    )
+  }
+
+  @Test
+  fun voiceNotificationSuffixReflectsActiveCaptureMode() {
+    assertEquals("", voiceNotificationSuffix(VoiceCaptureMode.Off, false, false, false, false))
+    assertEquals(
+      " · Mic: Listening",
+      voiceNotificationSuffix(VoiceCaptureMode.ManualMic, true, true, false, false),
+    )
+    assertEquals(
+      " · Talk: Speaking",
+      voiceNotificationSuffix(VoiceCaptureMode.TalkMode, false, false, true, true),
+    )
+  }
+
   private fun buildNotification(service: NodeForegroundService): Notification {
     val method =
       NodeForegroundService::class.java.getDeclaredMethod(

apps/android/app/src/test/java/ai/openclaw/app/SecurePrefsTest.kt

@@ -2,7 +2,9 @@ package ai.openclaw.app
 
 import android.content.Context
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
 import org.junit.Test
 import org.junit.runner.RunWith
 import org.robolectric.RobolectricTestRunner
@@ -22,6 +24,32 @@ class SecurePrefsTest {
     assertEquals("whileUsing", plainPrefs.getString("location.enabledMode", null))
   }
 
+  @Test
+  fun voiceMicEnabled_ignoresOldTalkEnabledKey() {
+    val context = RuntimeEnvironment.getApplication()
+    val plainPrefs = context.getSharedPreferences("openclaw.node", Context.MODE_PRIVATE)
+    plainPrefs.edit().clear().putBoolean("talk.enabled", true).commit()
+
+    val prefs = SecurePrefs(context)
+
+    assertFalse(prefs.voiceMicEnabled.value)
+    assertFalse(plainPrefs.contains("voice.micEnabled"))
+  }
+
+  @Test
+  fun setVoiceMicEnabled_persistsNewKeyOnly() {
+    val context = RuntimeEnvironment.getApplication()
+    val plainPrefs = context.getSharedPreferences("openclaw.node", Context.MODE_PRIVATE)
+    plainPrefs.edit().clear().putBoolean("talk.enabled", false).commit()
+    val prefs = SecurePrefs(context)
+
+    prefs.setVoiceMicEnabled(true)
+
+    assertTrue(prefs.voiceMicEnabled.value)
+    assertTrue(plainPrefs.getBoolean("voice.micEnabled", false))
+    assertFalse(plainPrefs.getBoolean("talk.enabled", false))
+  }
+
   @Test
   fun saveGatewayBootstrapToken_persistsSeparatelyFromSharedToken() {
     val context = RuntimeEnvironment.getApplication()

apps/ios/CHANGELOG.md

@@ -1,6 +1,6 @@
 # OpenClaw iOS Changelog
 
-## 2026.4.24 - 2026-04-24
+## 2026.4.25 - 2026-04-25
 
 Maintenance update for the current OpenClaw development release.
 

apps/ios/Config/Version.xcconfig

@@ -2,8 +2,8 @@
 // Source of truth: apps/ios/version.json
 // Generated by scripts/ios-sync-versioning.ts.
 
-OPENCLAW_IOS_VERSION = 2026.4.24
-OPENCLAW_MARKETING_VERSION = 2026.4.24
+OPENCLAW_IOS_VERSION = 2026.4.25
+OPENCLAW_MARKETING_VERSION = 2026.4.25
 OPENCLAW_BUILD_VERSION = 1
 
 #include? "../build/Version.xcconfig"

apps/ios/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "2026.4.24"
+  "version": "2026.4.25"
 }

apps/macos/Sources/OpenClaw/ChannelsStore+Lifecycle.swift

@@ -1,6 +1,24 @@
 import Foundation
 import OpenClawProtocol
 
+func whatsappLoginWaitRequestTimeoutMs(
+    startedAt: Date,
+    timeoutMs: Int,
+    didRunFinalWait: inout Bool,
+    now: Date = Date()) -> Int?
+{
+    let elapsedMs = Int(now.timeIntervalSince(startedAt) * 1000)
+    let remainingMs = max(timeoutMs - elapsedMs, 0)
+    if remainingMs > 0 {
+        return remainingMs
+    }
+    if didRunFinalWait {
+        return nil
+    }
+    didRunFinalWait = true
+    return 1
+}
+
 extension ChannelsStore {
     func start() {
         guard !self.isPreview else { return }
@@ -77,18 +95,28 @@ extension ChannelsStore {
         guard !self.whatsappBusy else { return }
         self.whatsappBusy = true
         defer { self.whatsappBusy = false }
+        let startedAt = Date()
+        var didRunFinalWait = false
         do {
-            let params: [String: AnyCodable] = [
-                "timeoutMs": AnyCodable(timeoutMs),
-            ]
-            let result: WhatsAppLoginWaitResult = try await GatewayConnection.shared.requestDecoded(
-                method: .webLoginWait,
-                params: params,
-                timeoutMs: Double(timeoutMs) + 5000)
-            self.whatsappLoginMessage = result.message
-            self.whatsappLoginConnected = result.connected
-            if result.connected {
-                self.whatsappLoginQrDataUrl = nil
+            while let remainingMs = whatsappLoginWaitRequestTimeoutMs(
+                startedAt: startedAt,
+                timeoutMs: timeoutMs,
+                didRunFinalWait: &didRunFinalWait)
+            {
+                var params: [String: AnyCodable] = [
+                    "timeoutMs": AnyCodable(remainingMs),
+                ]
+                if let currentQrDataUrl = self.whatsappLoginQrDataUrl {
+                    params["currentQrDataUrl"] = AnyCodable(currentQrDataUrl)
+                }
+                let result: WhatsAppLoginWaitResult = try await GatewayConnection.shared.requestDecoded(
+                    method: .webLoginWait,
+                    params: params,
+                    timeoutMs: Double(remainingMs) + 5000)
+                self.applyWhatsAppLoginWaitResult(result)
+                if result.connected || result.qrDataUrl == nil || didRunFinalWait {
+                    break
+                }
             }
         } catch {
             self.whatsappLoginMessage = error.localizedDescription
@@ -151,9 +179,10 @@ private struct WhatsAppLoginStartResult: Codable {
     let connected: Bool?
 }
 
-private struct WhatsAppLoginWaitResult: Codable {
+struct WhatsAppLoginWaitResult: Codable {
     let connected: Bool
     let message: String
+    let qrDataUrl: String?
 }
 
 private struct ChannelLogoutResult: Codable {

apps/macos/Sources/OpenClaw/ChannelsStore.swift

@@ -290,6 +290,16 @@ final class ChannelsStore {
         return self.snapshot?.channelOrder ?? []
     }
 
+    func applyWhatsAppLoginWaitResult(_ result: WhatsAppLoginWaitResult) {
+        self.whatsappLoginMessage = result.message
+        self.whatsappLoginConnected = result.connected
+        if let qrDataUrl = result.qrDataUrl {
+            self.whatsappLoginQrDataUrl = qrDataUrl
+        } else if result.connected {
+            self.whatsappLoginQrDataUrl = nil
+        }
+    }
+
     init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
         self.isPreview = isPreview
     }

apps/macos/Sources/OpenClaw/ExecAllowlistMatcher.swift

@@ -9,8 +9,14 @@ enum ExecAllowlistMatcher {
         for entry in entries {
             switch ExecApprovalHelpers.validateAllowlistPattern(entry.pattern) {
             case let .valid(pattern):
-                let target = resolvedPath ?? rawExecutable
-                if self.matches(pattern: pattern, target: target) { return entry }
+                if ExecApprovalHelpers.patternHasPathSelector(pattern) {
+                    let target = resolvedPath ?? rawExecutable
+                    if self.matches(pattern: pattern, target: target) { return entry }
+                } else if pattern != "*",
+                          !ExecApprovalHelpers.patternHasPathSelector(rawExecutable),
+                          self.matchesExecutableBasename(pattern: pattern, resolution: resolution) {
+                    return entry
+                }
             case .invalid:
                 continue
             }
@@ -34,6 +40,20 @@ enum ExecAllowlistMatcher {
         return matches
     }
 
+    private static func matchesExecutableBasename(
+        pattern: String,
+        resolution: ExecCommandResolution) -> Bool
+    {
+        var candidates = Set<String>()
+        if !resolution.executableName.isEmpty {
+            candidates.insert(resolution.executableName)
+        }
+        if let resolvedPath = resolution.resolvedPath, !resolvedPath.isEmpty {
+            candidates.insert(URL(fileURLWithPath: resolvedPath).lastPathComponent)
+        }
+        return candidates.contains { self.matches(pattern: pattern, target: $0) }
+    }
+
     private static func matches(pattern: String, target: String) -> Bool {
         let trimmed = pattern.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !trimmed.isEmpty else { return false }

apps/macos/Sources/OpenClaw/ExecApprovals.swift

@@ -616,6 +616,17 @@ enum ExecApprovalsStore {
         let trimmedResolved = entry.lastResolvedPath?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
         let normalizedResolved = trimmedResolved.isEmpty ? nil : trimmedResolved
 
+        if !ExecApprovalHelpers.patternHasPathSelector(trimmedPattern),
+           !trimmedResolved.isEmpty,
+           case let .valid(migratedPattern) = ExecApprovalHelpers.validateAllowlistPattern(trimmedResolved) {
+            return ExecAllowlistEntry(
+                id: entry.id,
+                pattern: migratedPattern,
+                lastUsedAt: entry.lastUsedAt,
+                lastUsedCommand: entry.lastUsedCommand,
+                lastResolvedPath: normalizedResolved)
+        }
+
         switch ExecApprovalHelpers.validateAllowlistPattern(trimmedPattern) {
         case let .valid(pattern):
             return ExecAllowlistEntry(
@@ -724,11 +735,10 @@ enum ExecApprovalHelpers {
     static func validateAllowlistPattern(_ pattern: String?) -> ExecAllowlistPatternValidation {
         let trimmed = pattern?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
         guard !trimmed.isEmpty else { return .invalid(.empty) }
-        guard self.containsPathComponent(trimmed) else { return .invalid(.missingPathComponent) }
         return .valid(trimmed)
     }
 
-    static func isPathPattern(_ pattern: String?) -> Bool {
+    static func isValidAllowlistPattern(_ pattern: String?) -> Bool {
         switch self.validateAllowlistPattern(pattern) {
         case .valid:
             true
@@ -737,6 +747,11 @@ enum ExecApprovalHelpers {
         }
     }
 
+    static func isPathPattern(_ pattern: String?) -> Bool {
+        let trimmed = pattern?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return self.patternHasPathSelector(trimmed)
+    }
+
     static func parseDecision(_ raw: String?) -> ExecApprovalDecision? {
         let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
         guard !trimmed.isEmpty else { return nil }
@@ -759,7 +774,7 @@ enum ExecApprovalHelpers {
         return pattern.isEmpty ? nil : pattern
     }
 
-    private static func containsPathComponent(_ pattern: String) -> Bool {
+    static func patternHasPathSelector(_ pattern: String) -> Bool {
         pattern.contains("/") || pattern.contains("~") || pattern.contains("\\")
     }
 }

apps/macos/Sources/OpenClaw/GatewayConnection.swift

@@ -70,6 +70,7 @@ actor GatewayConnection {
         case wizardStatus = "wizard.status"
         case talkConfig = "talk.config"
         case talkMode = "talk.mode"
+        case talkSpeak = "talk.speak"
         case webLoginStart = "web.login.start"
         case webLoginWait = "web.login.wait"
         case channelsLogout = "channels.logout"

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

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.4.24</string>
+    <string>2026.4.25</string>
     <key>CFBundleVersion</key>
-    <string>2026042400</string>
+    <string>2026042500</string>
     <key>CFBundleIconFile</key>
     <string>OpenClaw</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/OpenClaw/SystemRunSettingsView.swift

@@ -105,7 +105,7 @@ struct SystemRunSettingsView: View {
                     .foregroundStyle(.secondary)
             } else {
                 HStack(spacing: 8) {
-                    TextField("Add allowlist path pattern (case-insensitive globs)", text: self.$newPattern)
+                    TextField("Add command name or path glob", text: self.$newPattern)
                         .textFieldStyle(.roundedBorder)
                     Button("Add") {
                         if self.model.addEntry(self.newPattern) == nil {
@@ -113,10 +113,10 @@ struct SystemRunSettingsView: View {
                         }
                     }
                     .buttonStyle(.bordered)
-                    .disabled(!self.model.isPathPattern(self.newPattern))
+                    .disabled(!self.model.isValidPattern(self.newPattern))
                 }
 
-                Text("Path patterns only. Basename entries like \"echo\" are ignored.")
+                Text("Bare names match PATH-resolved commands. Use a path glob for a specific binary.")
                     .font(.footnote)
                     .foregroundStyle(.secondary)
                 if let validationMessage = self.model.allowlistValidationMessage {
@@ -424,8 +424,8 @@ final class ExecApprovalsSettingsModel {
         self.entries.first(where: { $0.id == id })
     }
 
-    func isPathPattern(_ pattern: String) -> Bool {
-        ExecApprovalHelpers.isPathPattern(pattern)
+    func isValidPattern(_ pattern: String) -> Bool {
+        ExecApprovalHelpers.isValidAllowlistPattern(pattern)
     }
 
     func refreshSkillBins(force: Bool = false) async {

apps/macos/Sources/OpenClaw/TalkModeRuntime.swift

@@ -2,6 +2,7 @@ import AVFoundation
 import Foundation
 import OpenClawChatUI
 import OpenClawKit
+import OpenClawProtocol
 import OSLog
 import Speech
 
@@ -475,7 +476,16 @@ actor TalkModeRuntime {
                 self.ttsLogger
                     .error(
                         "talk TTS failed: \(error.localizedDescription, privacy: .public); " +
-                            "falling back to system voice")
+                            "retrying gateway talk.speak")
+                do {
+                    try await self.playGatewayTalkSpeak(input: input)
+                    return
+                } catch {
+                    self.ttsLogger
+                        .error(
+                            "talk gateway TTS failed: \(error.localizedDescription, privacy: .public); " +
+                                "falling back to system voice")
+                }
                 do {
                     try await self.playSystemVoice(input: input)
                 } catch {
@@ -720,6 +730,42 @@ actor TalkModeRuntime {
         return await self.playMP3(stream: stream)
     }
 
+    private func playGatewayTalkSpeak(input: TalkPlaybackInput) async throws {
+        let params = Self.makeTalkSpeakParams(
+            text: input.cleanedText,
+            voiceId: input.voiceId,
+            modelId: self.currentModelId ?? self.defaultModelId,
+            outputFormat: self.defaultOutputFormat,
+            directive: input.directive)
+        let result: TalkSpeakResult = try await GatewayConnection.shared.requestDecoded(
+            method: .talkSpeak,
+            params: params,
+            timeoutMs: max(30000, input.synthTimeoutSeconds * 1000 + 5000))
+        guard let audioData = Data(base64Encoded: result.audiobase64), !audioData.isEmpty else {
+            throw NSError(domain: "TalkSpeak", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "gateway talk.speak returned empty audio",
+            ])
+        }
+        _ = await self.stopPCM()
+        _ = await self.stopMP3()
+        if self.interruptOnSpeech {
+            guard await self.prepareForPlayback(generation: input.generation) else { return }
+        }
+        await MainActor.run { TalkModeController.shared.updatePhase(.speaking) }
+        self.phase = .speaking
+        let playback = await self.playTalkAudio(data: audioData)
+        self.ttsLogger
+            .info(
+                "talk gateway audio provider=\(result.provider, privacy: .public) " +
+                    "format=\(result.outputformat ?? "unknown", privacy: .public) " +
+                    "finished=\(playback.finished, privacy: .public)")
+        if !playback.finished, playback.interruptedAt == nil {
+            throw NSError(domain: "TalkSpeak", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "gateway talk.speak audio playback failed",
+            ])
+        }
+    }
+
     private func playSystemVoice(input: TalkPlaybackInput) async throws {
         self.ttsLogger.info("talk system voice start chars=\(input.cleanedText.count, privacy: .public)")
         if self.interruptOnSpeech {
@@ -847,6 +893,54 @@ actor TalkModeRuntime {
 }
 
 extension TalkModeRuntime {
+    static func makeTalkSpeakParams(
+        text: String,
+        voiceId: String?,
+        modelId: String?,
+        outputFormat: String?,
+        directive: TalkDirective?) -> [String: AnyCodable]
+    {
+        var params: [String: AnyCodable] = ["text": AnyCodable(text)]
+
+        func addString(_ key: String, _ value: String?) {
+            let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            guard !trimmed.isEmpty else { return }
+            params[key] = AnyCodable(trimmed)
+        }
+
+        addString("voiceId", voiceId)
+        addString("modelId", directive?.modelId ?? modelId)
+        addString("outputFormat", directive?.outputFormat ?? outputFormat)
+        if let speed = directive?.speed {
+            params["speed"] = AnyCodable(speed)
+        }
+        if let rateWPM = directive?.rateWPM {
+            params["rateWpm"] = AnyCodable(rateWPM)
+        }
+        if let stability = directive?.stability {
+            params["stability"] = AnyCodable(stability)
+        }
+        if let similarity = directive?.similarity {
+            params["similarity"] = AnyCodable(similarity)
+        }
+        if let style = directive?.style {
+            params["style"] = AnyCodable(style)
+        }
+        if let speakerBoost = directive?.speakerBoost {
+            params["speakerBoost"] = AnyCodable(speakerBoost)
+        }
+        if let seed = directive?.seed {
+            params["seed"] = AnyCodable(seed)
+        }
+        addString("normalize", directive?.normalize)
+        addString("language", directive?.language)
+        if let latencyTier = directive?.latencyTier {
+            params["latencyTier"] = AnyCodable(latencyTier)
+        }
+
+        return params
+    }
+
     // MARK: - Audio playback (MainActor helpers)
 
     @MainActor

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -723,17 +723,26 @@ public struct AgentIdentityResult: Codable, Sendable {
     public let agentid: String
     public let name: String?
     public let avatar: String?
+    public let avatarsource: String?
+    public let avatarstatus: String?
+    public let avatarreason: String?
     public let emoji: String?
 
     public init(
         agentid: String,
         name: String?,
         avatar: String?,
+        avatarsource: String?,
+        avatarstatus: String?,
+        avatarreason: String?,
         emoji: String?)
     {
         self.agentid = agentid
         self.name = name
         self.avatar = avatar
+        self.avatarsource = avatarsource
+        self.avatarstatus = avatarstatus
+        self.avatarreason = avatarreason
         self.emoji = emoji
     }
 
@@ -741,6 +750,9 @@ public struct AgentIdentityResult: Codable, Sendable {
         case agentid = "agentId"
         case name
         case avatar
+        case avatarsource = "avatarSource"
+        case avatarstatus = "avatarStatus"
+        case avatarreason = "avatarReason"
         case emoji
     }
 }
@@ -2330,20 +2342,17 @@ public struct TalkRealtimeSessionParams: Codable, Sendable {
     public let provider: String?
     public let model: String?
     public let voice: String?
-    public let instructions: String?
 
     public init(
         sessionkey: String?,
         provider: String?,
         model: String?,
-        voice: String?,
-        instructions: String?)
+        voice: String?)
     {
         self.sessionkey = sessionkey
         self.provider = provider
         self.model = model
         self.voice = voice
-        self.instructions = instructions
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -2351,7 +2360,6 @@ public struct TalkRealtimeSessionParams: Codable, Sendable {
         case provider
         case model
         case voice
-        case instructions
     }
 }
 
@@ -2614,18 +2622,22 @@ public struct WebLoginStartParams: Codable, Sendable {
 public struct WebLoginWaitParams: Codable, Sendable {
     public let timeoutms: Int?
     public let accountid: String?
+    public let currentqrdataurl: String?
 
     public init(
         timeoutms: Int?,
-        accountid: String?)
+        accountid: String?,
+        currentqrdataurl: String?)
     {
         self.timeoutms = timeoutms
         self.accountid = accountid
+        self.currentqrdataurl = currentqrdataurl
     }
 
     private enum CodingKeys: String, CodingKey {
         case timeoutms = "timeoutMs"
         case accountid = "accountId"
+        case currentqrdataurl = "currentQrDataUrl"
     }
 }
 

apps/macos/Tests/OpenClawIPCTests/ChannelsSettingsSmokeTests.swift

@@ -156,4 +156,63 @@ struct ChannelsSettingsSmokeTests {
         let view = ChannelsSettings(store: store)
         _ = view.body
     }
+
+    @Test func `whatsapp login wait result keeps latest qr until connected`() {
+        let store = makeChannelsStore(channels: [:])
+        store.whatsappLoginQrDataUrl = "data:image/png;base64,initial"
+
+        store.applyWhatsAppLoginWaitResult(
+            WhatsAppLoginWaitResult(
+                connected: false,
+                message: "QR refreshed. Scan the latest code in WhatsApp → Linked Devices.",
+                qrDataUrl: "data:image/png;base64,rotated"))
+
+        #expect(store.whatsappLoginQrDataUrl == "data:image/png;base64,rotated")
+        #expect(store.whatsappLoginConnected == false)
+
+        store.applyWhatsAppLoginWaitResult(
+            WhatsAppLoginWaitResult(
+                connected: false,
+                message: "Still waiting for the QR scan. Let me know when you’ve scanned it.",
+                qrDataUrl: nil))
+
+        #expect(store.whatsappLoginQrDataUrl == "data:image/png;base64,rotated")
+
+        store.applyWhatsAppLoginWaitResult(
+            WhatsAppLoginWaitResult(
+                connected: true,
+                message: "✅ Linked! WhatsApp is ready.",
+                qrDataUrl: nil))
+
+        #expect(store.whatsappLoginQrDataUrl == nil)
+        #expect(store.whatsappLoginConnected == true)
+    }
+
+    @Test func `whatsapp login wait budget allows one final poll`() {
+        let startedAt = Date(timeIntervalSince1970: 1_700_000_000)
+        var didRunFinalWait = false
+
+        #expect(
+            whatsappLoginWaitRequestTimeoutMs(
+                startedAt: startedAt,
+                timeoutMs: 1_000,
+                didRunFinalWait: &didRunFinalWait,
+                now: Date(timeInterval: 0.25, since: startedAt)) == 750)
+        #expect(didRunFinalWait == false)
+
+        #expect(
+            whatsappLoginWaitRequestTimeoutMs(
+                startedAt: startedAt,
+                timeoutMs: 1_000,
+                didRunFinalWait: &didRunFinalWait,
+                now: Date(timeInterval: 1.25, since: startedAt)) == 1)
+        #expect(didRunFinalWait == true)
+
+        #expect(
+            whatsappLoginWaitRequestTimeoutMs(
+                startedAt: startedAt,
+                timeoutMs: 1_000,
+                didRunFinalWait: &didRunFinalWait,
+                now: Date(timeInterval: 1.5, since: startedAt)) == nil)
+    }
 }

apps/macos/Tests/OpenClawIPCTests/ExecAllowlistTests.swift

@@ -66,22 +66,34 @@ struct ExecAllowlistTests {
         #expect(match?.pattern == entry.pattern)
     }
 
-    @Test func `match ignores basename pattern`() {
+    @Test func `match accepts basename pattern for PATH resolved executable`() {
         let entry = ExecAllowlistEntry(pattern: "rg")
         let resolution = Self.homebrewRGResolution()
         let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
-        #expect(match == nil)
+        #expect(match?.pattern == entry.pattern)
     }
 
-    @Test func `match ignores basename for relative executable`() {
+    @Test func `match accepts basename glob for PATH resolved executable`() {
+        let entry = ExecAllowlistEntry(pattern: "r?")
+        let resolution = Self.homebrewRGResolution()
+        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
+        #expect(match?.pattern == entry.pattern)
+    }
+
+    @Test func `match ignores basename for path selected executable`() {
         let entry = ExecAllowlistEntry(pattern: "echo")
-        let resolution = ExecCommandResolution(
+        let relativeResolution = ExecCommandResolution(
             rawExecutable: "./echo",
             resolvedPath: "/tmp/oc-basename/echo",
             executableName: "echo",
             cwd: "/tmp/oc-basename")
-        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
-        #expect(match == nil)
+        let absoluteResolution = ExecCommandResolution(
+            rawExecutable: "/tmp/oc-basename/echo",
+            resolvedPath: "/tmp/oc-basename/echo",
+            executableName: "echo",
+            cwd: "/tmp/oc-basename")
+        #expect(ExecAllowlistMatcher.match(entries: [entry], resolution: relativeResolution) == nil)
+        #expect(ExecAllowlistMatcher.match(entries: [entry], resolution: absoluteResolution) == nil)
     }
 
     @Test func `match is case insensitive`() {

apps/macos/Tests/OpenClawIPCTests/ExecApprovalHelpersTests.swift

@@ -33,18 +33,13 @@ struct ExecApprovalHelpersTests {
         #expect(ExecApprovalHelpers.isPathPattern("/usr/bin/rg"))
         #expect(ExecApprovalHelpers.isPathPattern(" ~/bin/rg "))
         #expect(!ExecApprovalHelpers.isPathPattern("rg"))
+        #expect(ExecApprovalHelpers.isValidAllowlistPattern("rg"))
 
         if case let .invalid(reason) = ExecApprovalHelpers.validateAllowlistPattern("  ") {
             #expect(reason == .empty)
         } else {
             Issue.record("Expected empty pattern rejection")
         }
-
-        if case let .invalid(reason) = ExecApprovalHelpers.validateAllowlistPattern("echo") {
-            #expect(reason == .missingPathComponent)
-        } else {
-            Issue.record("Expected basename pattern rejection")
-        }
     }
 
     @Test func `requires ask matches policy`() {

apps/macos/Tests/OpenClawIPCTests/ExecApprovalsStoreRefactorTests.swift

@@ -31,7 +31,7 @@ struct ExecApprovalsStoreRefactorTests {
     }
 
     @Test
-    func `update allowlist reports rejected basename pattern`() async throws {
+    func `update allowlist accepts basename pattern`() async throws {
         try await self.withTempStateDir { _ in
             let rejected = ExecApprovalsStore.updateAllowlist(
                 agentId: "main",
@@ -39,12 +39,10 @@ struct ExecApprovalsStoreRefactorTests {
                     ExecAllowlistEntry(pattern: "echo"),
                     ExecAllowlistEntry(pattern: "/bin/echo"),
                 ])
-            #expect(rejected.count == 1)
-            #expect(rejected.first?.reason == .missingPathComponent)
-            #expect(rejected.first?.pattern == "echo")
+            #expect(rejected.isEmpty)
 
             let resolved = ExecApprovalsStore.resolve(agentId: "main")
-            #expect(resolved.allowlist.map(\.pattern) == ["/bin/echo"])
+            #expect(resolved.allowlist.map(\.pattern) == ["echo", "/bin/echo"])
         }
     }
 

apps/macos/Tests/OpenClawIPCTests/TalkModeRuntimeSpeechTests.swift

@@ -1,3 +1,4 @@
+import OpenClawKit
 import Speech
 import Testing
 @testable import OpenClaw
@@ -16,23 +17,19 @@ struct TalkModeRuntimeSpeechTests {
         let elevenLabsPlan = TalkModeRuntime.playbackPlan(
             provider: "elevenlabs",
             apiKey: "key",
-            voiceId: "voice"
-        )
+            voiceId: "voice")
         let missingKeyPlan = TalkModeRuntime.playbackPlan(
             provider: "elevenlabs",
             apiKey: nil,
-            voiceId: "voice"
-        )
+            voiceId: "voice")
         let missingVoicePlan = TalkModeRuntime.playbackPlan(
             provider: "elevenlabs",
             apiKey: "key",
-            voiceId: nil
-        )
+            voiceId: nil)
         let blankKeyPlan = TalkModeRuntime.playbackPlan(
             provider: "elevenlabs",
             apiKey: "",
-            voiceId: "voice"
-        )
+            voiceId: "voice")
         let mlxPlan = TalkModeRuntime.playbackPlan(provider: "mlx", apiKey: nil, voiceId: nil)
         let systemPlan = TalkModeRuntime.playbackPlan(provider: "system", apiKey: nil, voiceId: nil)
 
@@ -43,4 +40,40 @@ struct TalkModeRuntimeSpeechTests {
         #expect(mlxPlan == .mlxThenSystemVoice)
         #expect(systemPlan == .systemVoiceOnly)
     }
+
+    @Test func `talk speak params carry resolved voice and directive overrides`() {
+        let params = TalkModeRuntime.makeTalkSpeakParams(
+            text: "hello",
+            voiceId: "voice-123",
+            modelId: "eleven_v3",
+            outputFormat: "mp3_44100_128",
+            directive: TalkDirective(
+                modelId: "eleven_turbo_v2_5",
+                speed: 1.1,
+                rateWPM: 180,
+                stability: 0.4,
+                similarity: 0.7,
+                style: 0.2,
+                speakerBoost: true,
+                seed: 42,
+                normalize: "auto",
+                language: "en",
+                outputFormat: "mp3_44100_128",
+                latencyTier: 3))
+
+        #expect(params["text"]?.value as? String == "hello")
+        #expect(params["voiceId"]?.value as? String == "voice-123")
+        #expect(params["modelId"]?.value as? String == "eleven_turbo_v2_5")
+        #expect(params["outputFormat"]?.value as? String == "mp3_44100_128")
+        #expect(params["speed"]?.value as? Double == 1.1)
+        #expect(params["rateWpm"]?.value as? Int == 180)
+        #expect(params["stability"]?.value as? Double == 0.4)
+        #expect(params["similarity"]?.value as? Double == 0.7)
+        #expect(params["style"]?.value as? Double == 0.2)
+        #expect(params["speakerBoost"]?.value as? Bool == true)
+        #expect(params["seed"]?.value as? Int == 42)
+        #expect(params["normalize"]?.value as? String == "auto")
+        #expect(params["language"]?.value as? String == "en")
+        #expect(params["latencyTier"]?.value as? Int == 3)
+    }
 }

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

@@ -723,17 +723,26 @@ public struct AgentIdentityResult: Codable, Sendable {
     public let agentid: String
     public let name: String?
     public let avatar: String?
+    public let avatarsource: String?
+    public let avatarstatus: String?
+    public let avatarreason: String?
     public let emoji: String?
 
     public init(
         agentid: String,
         name: String?,
         avatar: String?,
+        avatarsource: String?,
+        avatarstatus: String?,
+        avatarreason: String?,
         emoji: String?)
     {
         self.agentid = agentid
         self.name = name
         self.avatar = avatar
+        self.avatarsource = avatarsource
+        self.avatarstatus = avatarstatus
+        self.avatarreason = avatarreason
         self.emoji = emoji
     }
 
@@ -741,6 +750,9 @@ public struct AgentIdentityResult: Codable, Sendable {
         case agentid = "agentId"
         case name
         case avatar
+        case avatarsource = "avatarSource"
+        case avatarstatus = "avatarStatus"
+        case avatarreason = "avatarReason"
         case emoji
     }
 }
@@ -2330,20 +2342,17 @@ public struct TalkRealtimeSessionParams: Codable, Sendable {
     public let provider: String?
     public let model: String?
     public let voice: String?
-    public let instructions: String?
 
     public init(
         sessionkey: String?,
         provider: String?,
         model: String?,
-        voice: String?,
-        instructions: String?)
+        voice: String?)
     {
         self.sessionkey = sessionkey
         self.provider = provider
         self.model = model
         self.voice = voice
-        self.instructions = instructions
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -2351,7 +2360,6 @@ public struct TalkRealtimeSessionParams: Codable, Sendable {
         case provider
         case model
         case voice
-        case instructions
     }
 }
 
@@ -2614,18 +2622,22 @@ public struct WebLoginStartParams: Codable, Sendable {
 public struct WebLoginWaitParams: Codable, Sendable {
     public let timeoutms: Int?
     public let accountid: String?
+    public let currentqrdataurl: String?
 
     public init(
         timeoutms: Int?,
-        accountid: String?)
+        accountid: String?,
+        currentqrdataurl: String?)
     {
         self.timeoutms = timeoutms
         self.accountid = accountid
+        self.currentqrdataurl = currentqrdataurl
     }
 
     private enum CodingKeys: String, CodingKey {
         case timeoutms = "timeoutMs"
         case accountid = "accountId"
+        case currentqrdataurl = "currentQrDataUrl"
     }
 }
 

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-d3b5638e205a94e40d07aa1830c8d57135df18ff9388fb7d72ee84c791ac293f  config-baseline.json
-bf00f7910d8f0d8e12592e8a1c6bd0397f8e62fef2c11eb0cbd3b3a3e2a78ffe  config-baseline.core.json
-22d7cd6d8279146b2d79c9531a55b80b52a2c99c81338c508104729154fdd02d  config-baseline.channel.json
-a91304e3566ecc8906f199b88a2e38eaee86130aad799bf4d62921e2f0ddc1b5  config-baseline.plugin.json
+6ed33ef102e7c92816243bfabc3626222a679c3270c12ec5ea47b28b66204b3b  config-baseline.json
+f86cb4d57ec1f5fd75008be0ab86151194945eb013a47ab4bdeaddafd3780da7  config-baseline.core.json
+7cd9c908f066c143eab2a201efbc9640f483ab28bba92ddeca1d18cc2b528bc3  config-baseline.channel.json
+7825b56a5b3fcdbe2e09ef8fe5d9f12ac3598435afebe20413051e45b0d1968e  config-baseline.plugin.json

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

@@ -1,2 +1,2 @@
-96905c33f4498446f612ae17dee6affdf84ef0e2e5a0f25bf7191c315f5b826f  plugin-sdk-api-baseline.json
-d8eb6331562fde29531eaac18409bb7fabcc70623bf25395f8e5710a49765f0f  plugin-sdk-api-baseline.jsonl
+f813474b1623f06e1465daacd56db970e8e92ab1be122faee0fa2a1dc2d4fc43  plugin-sdk-api-baseline.json
+b3ea88c0c9b4cf6d9a46f0d34149063303853e78ef9708224608e4da79b23190  plugin-sdk-api-baseline.jsonl

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

@@ -3,6 +3,18 @@
     "source": "OpenClaw",
     "target": "OpenClaw"
   },
+  {
+    "source": "OpenAI",
+    "target": "OpenAI"
+  },
+  {
+    "source": "OpenAI provider",
+    "target": "OpenAI provider"
+  },
+  {
+    "source": "Status",
+    "target": "Status"
+  },
   {
     "source": "Gateway",
     "target": "Gateway 网关"
@@ -11,6 +23,30 @@
     "source": "Pi",
     "target": "Pi"
   },
+  {
+    "source": "Agent runtimes",
+    "target": "Agent Runtimes"
+  },
+  {
+    "source": "Agent Runtimes",
+    "target": "Agent Runtimes"
+  },
+  {
+    "source": "Codex harness",
+    "target": "Codex harness"
+  },
+  {
+    "source": "Agent harness plugins",
+    "target": "Agent harness plugins"
+  },
+  {
+    "source": "Agent loop",
+    "target": "Agent loop"
+  },
+  {
+    "source": "Models",
+    "target": "Models"
+  },
   {
     "source": "Skills",
     "target": "Skills"
@@ -331,10 +367,18 @@
     "source": "Plugin SDK",
     "target": "插件 SDK"
   },
+  {
+    "source": "Building plugins",
+    "target": "构建插件"
+  },
   {
     "source": "Plugin SDK Overview",
     "target": "插件 SDK 概览"
   },
+  {
+    "source": "Plugin SDK overview",
+    "target": "插件 SDK 概览"
+  },
   {
     "source": "SDK Overview",
     "target": "SDK 概览"
@@ -343,6 +387,22 @@
     "source": "Plugin Entry Points",
     "target": "插件入口点"
   },
+  {
+    "source": "Plugin entry points",
+    "target": "插件入口点"
+  },
+  {
+    "source": "Plugin hooks",
+    "target": "插件钩子"
+  },
+  {
+    "source": "Internal hooks",
+    "target": "内部钩子"
+  },
+  {
+    "source": "Plugin architecture internals",
+    "target": "插件架构内部机制"
+  },
   {
     "source": "Entry Points",
     "target": "入口点"
@@ -403,6 +463,10 @@
     "source": "Tencent Cloud (TokenHub)",
     "target": "腾讯云（TokenHub）"
   },
+  {
+    "source": "Codex Harness Context Engine Port",
+    "target": "Codex Harness Context Engine Port"
+  },
   {
     "source": "/gateway/configuration#strict-validation",
     "target": "/gateway/configuration#strict-validation"

docs/auth-credential-semantics.md

@@ -76,3 +76,8 @@ For script compatibility, probe errors keep this first line unchanged:
 `Auth profile credentials are missing or expired.`
 
 Human-friendly detail and stable reason codes may be added on subsequent lines.
+
+## Related
+
+- [Secrets management](/gateway/secrets)
+- [Auth storage](/concepts/oauth)

docs/automation/cron-jobs.md

@@ -7,8 +7,6 @@ read_when:
 title: "Scheduled tasks"
 ---
 
-# Scheduled Tasks (Cron)
-
 Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can deliver output back to a chat channel or webhook endpoint.
 
 ## Quick start
@@ -88,6 +86,8 @@ This fires ~5–6 times per month instead of 0–1 times per month. OpenClaw use
 
 **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, “fresh session” means a new transcript/session id for each run. OpenClaw may carry safe preferences such as thinking/fast/verbose settings, labels, and explicit user-selected model/auth overrides, but it does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.
+
 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.
 
 Isolated cron runs also dispose any bundled MCP runtime instances created for the job through the shared runtime-cleanup path. This matches how main-session and custom-session MCP clients are torn down, so isolated cron jobs do not leak stdio child processes or long-lived MCP connections across runs.
@@ -96,6 +96,11 @@ When isolated cron runs orchestrate subagents, delivery also prefers the final
 descendant output over stale parent interim text. If descendants are still
 running, OpenClaw suppresses that partial parent update instead of announcing it.
 
+For text-only Discord announce targets, OpenClaw sends the canonical final
+assistant text once instead of replaying both streamed/intermediate text payloads
+and the final answer. Media and structured Discord payloads are still delivered
+as separate payloads so attachments and components are not dropped.
+
 ### Payload options for isolated jobs
 
 - `--message`: prompt text (required for isolated)
@@ -113,7 +118,7 @@ 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
+3. User-selected stored cron session model override
 4. Agent/default model selection
 
 Fast mode follows the resolved live selection too. If the selected model config
@@ -121,10 +126,11 @@ 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.
+switched provider/model and persists that live selection for the active run
+before retrying. When the switch also carries a new auth profile, cron persists
+that auth profile override for the active run too. Retries are bounded: after
+the initial attempt plus 2 switch retries, cron aborts instead of looping
+forever.
 
 ## Delivery and output
 

docs/automation/hooks.md

@@ -106,7 +106,7 @@ const handler = async (event) => {
 export default handler;
 ```
 
-Each event includes: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push to send to user), and `context` (event-specific data).
+Each event includes: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push to send to user), and `context` (event-specific data). Agent and tool plugin hook contexts can also include `trace`, a read-only W3C-compatible diagnostic trace context that plugins may pass into structured logs for OTEL correlation.
 
 ### Event context highlights
 
@@ -205,9 +205,12 @@ Runs `BOOT.md` from the active workspace when the gateway starts.
 
 ## Plugin hooks
 
-Plugins can register hooks through the Plugin SDK for deeper integration: intercepting tool calls, modifying prompts, controlling message flow, and more. The Plugin SDK exposes 28 hooks covering model resolution, agent lifecycle, message flow, tool execution, subagent coordination, and gateway lifecycle.
+Plugins can register typed hooks through the Plugin SDK for deeper integration:
+intercepting tool calls, modifying prompts, controlling message flow, and more.
+Use plugin hooks when you need `before_tool_call`, `before_agent_reply`,
+`before_install`, or other in-process lifecycle hooks.
 
-For the complete plugin hook reference including `before_tool_call`, `before_agent_reply`, `before_install`, and all other plugin hooks, see [Plugin Architecture](/plugins/architecture-internals#provider-runtime-hooks).
+For the complete plugin hook reference, see [Plugin hooks](/plugins/hooks).
 
 ## Configuration
 
@@ -315,5 +318,5 @@ Check for missing binaries (PATH), environment variables, config values, or OS c
 
 - [CLI Reference: hooks](/cli/hooks)
 - [Webhooks](/automation/cron-jobs#webhooks)
-- [Plugin Architecture](/plugins/architecture-internals#provider-runtime-hooks) — full plugin hook reference
+- [Plugin hooks](/plugins/hooks) — in-process plugin lifecycle hooks
 - [Configuration](/gateway/configuration-reference#hooks)

docs/automation/index.md

@@ -40,7 +40,7 @@ flowchart TD
 | Audit what ran and when                 | Background Tasks       | `openclaw tasks list` and `openclaw tasks audit` |
 | Multi-step research then summarize      | Task Flow              | Durable orchestration with revision tracking     |
 | Run a script on session reset           | Hooks                  | Event-driven, fires on lifecycle events          |
-| Execute code on every tool call         | Hooks                  | Hooks can filter by event type                   |
+| Execute code on every tool call         | Plugin hooks           | In-process hooks can intercept tool calls        |
 | Always check compliance before replying | Standing Orders        | Injected into every session automatically        |
 
 ### Scheduled Tasks (Cron) vs Heartbeat
@@ -83,7 +83,11 @@ See [Standing Orders](/automation/standing-orders).
 
 ### Hooks
 
-Hooks are event-driven scripts triggered by agent lifecycle events (`/new`, `/reset`, `/stop`), session compaction, gateway startup, message flow, and tool calls. Hooks are automatically discovered from directories and can be managed with `openclaw hooks`.
+Internal hooks are event-driven scripts triggered by agent lifecycle events
+(`/new`, `/reset`, `/stop`), session compaction, gateway startup, and message
+flow. They are automatically discovered from directories and can be managed
+with `openclaw hooks`. For in-process tool-call interception, use
+[Plugin hooks](/plugins/hooks).
 
 See [Hooks](/automation/hooks).
 
@@ -97,7 +101,7 @@ See [Heartbeat](/gateway/heartbeat).
 
 - **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders. All cron executions create task records.
 - **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
-- **Hooks** react to specific events (tool calls, session resets, compaction) with custom scripts.
+- **Hooks** react to specific events (session resets, compaction, message flow) with custom scripts. Plugin hooks cover tool calls.
 - **Standing orders** give the agent persistent context and authority boundaries.
 - **Task Flow** coordinates multi-step flows above individual tasks.
 - **Tasks** automatically track all detached work so you can inspect and audit it.
@@ -108,6 +112,7 @@ See [Heartbeat](/gateway/heartbeat).
 - [Background Tasks](/automation/tasks) — task ledger for all detached work
 - [Task Flow](/automation/taskflow) — durable multi-step flow orchestration
 - [Hooks](/automation/hooks) — event-driven lifecycle scripts
+- [Plugin hooks](/plugins/hooks) — in-process tool, prompt, message, and lifecycle hooks
 - [Standing Orders](/automation/standing-orders) — persistent agent instructions
 - [Heartbeat](/gateway/heartbeat) — periodic main-session turns
 - [Configuration Reference](/gateway/configuration-reference) — all config keys

docs/automation/standing-orders.md

@@ -27,7 +27,7 @@ This is the difference between telling your assistant "send the weekly report" e
 - You only get involved for exceptions and approvals
 - The agent fills idle time productively
 
-## How They Work
+## How they work
 
 Standing orders are defined in your [agent workspace](/concepts/agent-workspace) files. The recommended approach is to include them directly in `AGENTS.md` (which is auto-injected every session) so the agent always has them in context. For larger configurations, you can also place them in a dedicated file like `standing-orders.md` and reference it from `AGENTS.md`.
 
@@ -198,8 +198,6 @@ This pattern prevents the most common agent failure mode: acknowledging a task w
 For agents managing multiple concerns, organize standing orders as separate programs with clear boundaries:
 
 ```markdown
-# Standing Orders
-
 ## Program 1: [Domain A] (Weekly)
 
 ...

docs/automation/taskflow.md

@@ -20,6 +20,78 @@ Use Task Flow when work spans multiple sequential or branching steps and you nee
 | Observe externally created tasks      | Task Flow (mirrored) |
 | One-shot reminder                     | Cron job             |
 
+## Reliable scheduled workflow pattern
+
+For recurring workflows such as market intelligence briefings, treat the schedule, orchestration, and reliability checks as separate layers:
+
+1. Use [Scheduled Tasks](/automation/cron-jobs) for timing.
+2. Use a persistent cron session when the workflow should build on prior context.
+3. Use [Lobster](/tools/lobster) for deterministic steps, approval gates, and resume tokens.
+4. Use Task Flow to track the multi-step run across child tasks, waits, retries, and gateway restarts.
+
+Example cron shape:
+
+```bash
+openclaw cron add \
+  --name "Market intelligence brief" \
+  --cron "0 7 * * 1-5" \
+  --tz "America/New_York" \
+  --session session:market-intel \
+  --message "Run the market-intel Lobster workflow. Verify source freshness before summarizing." \
+  --announce \
+  --channel slack \
+  --to "channel:C1234567890"
+```
+
+Use `session:<id>` instead of `isolated` when the recurring workflow needs deliberate history, previous run summaries, or standing context. Use `isolated` when each run should start fresh and all required state is explicit in the workflow.
+
+Inside the workflow, put reliability checks before the LLM summary step:
+
+```yaml
+name: market-intel-brief
+steps:
+  - id: preflight
+    command: market-intel check --json
+  - id: collect
+    command: market-intel collect --json
+    stdin: $preflight.json
+  - id: summarize
+    command: market-intel summarize --json
+    stdin: $collect.json
+  - id: approve
+    command: market-intel deliver --preview
+    stdin: $summarize.json
+    approval: required
+  - id: deliver
+    command: market-intel deliver --execute
+    stdin: $summarize.json
+    condition: $approve.approved
+```
+
+Recommended preflight checks:
+
+- Browser availability and profile choice, for example `openclaw` for managed state or `user` when a signed-in Chrome session is required. See [Browser](/tools/browser).
+- API credentials and quota for each source.
+- Network reachability for required endpoints.
+- Required tools enabled for the agent, such as `lobster`, `browser`, and `llm-task`.
+- Failure destination configured for cron so preflight failures are visible. See [Scheduled Tasks](/automation/cron-jobs#delivery-and-output).
+
+Recommended data provenance fields for every collected item:
+
+```json
+{
+  "sourceUrl": "https://example.com/report",
+  "retrievedAt": "2026-04-24T12:00:00Z",
+  "asOf": "2026-04-24",
+  "title": "Example report",
+  "content": "..."
+}
+```
+
+Have the workflow reject or mark stale items before summarization. The LLM step should receive only structured JSON and should be asked to preserve `sourceUrl`, `retrievedAt`, and `asOf` in its output. Use [LLM Task](/tools/llm-task) when you need a schema-validated model step inside the workflow.
+
+For reusable team or community workflows, package the CLI, `.lobster` files, and any setup notes as a skill or plugin and publish it through [ClawHub](/tools/clawhub). Keep workflow-specific guardrails in that package unless the plugin API is missing a needed generic capability.
+
 ## Sync modes
 
 ### Managed mode

docs/brave-search.md

@@ -101,3 +101,7 @@ await web_search({
 - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`).
 
 See [Web tools](/tools/web) for the full web_search configuration.
+
+## Related
+
+- [Brave search](/tools/brave-search)

docs/channels/bluebubbles.md

@@ -7,8 +7,6 @@ read_when:
 title: "BlueBubbles"
 ---
 
-# BlueBubbles (macOS REST)
-
 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

docs/channels/broadcast-groups.md

@@ -433,14 +433,10 @@ Planned features:
 - [ ] Dynamic agent selection (choose agents based on message content)
 - [ ] Agent priorities (some agents respond before others)
 
-## See Also
-
-- [Multi-Agent Configuration](/tools/multi-agent-sandbox-tools)
-- [Routing Configuration](/channels/channel-routing)
-- [Session Management](/concepts/session)
-
 ## Related
 
 - [Groups](/channels/groups)
 - [Channel routing](/channels/channel-routing)
 - [Pairing](/channels/pairing)
+- [Multi-agent sandbox tools](/tools/multi-agent-sandbox-tools)
+- [Session management](/concepts/session)

docs/channels/discord.md

@@ -267,6 +267,9 @@ Now create some channels on your Discord server and start chatting. Your agent c
 - Guild channels are isolated session keys (`agent:<agentId>:discord:channel:<channelId>`).
 - Group DMs are ignored by default (`channels.discord.dm.groupEnabled=false`).
 - Native slash commands run in isolated command sessions (`agent:<agentId>:discord:slash:<userId>`), while still carrying `CommandTargetSessionKey` to the routed conversation session.
+- Text-only cron/heartbeat announce delivery to Discord uses the final
+  assistant-visible answer once. Media and structured component payloads remain
+  multi-message when the agent emits multiple deliverable payloads.
 
 ## Forum channels
 
@@ -305,7 +308,7 @@ By default, components are single use. Set `components.reusable=true` to allow b
 
 To restrict who can click a button, set `allowedUsers` on that button (Discord user IDs, tags, or `*`). When configured, unmatched users receive an ephemeral denial.
 
-The `/model` and `/models` slash commands open an interactive model picker with provider and model dropdowns plus a Submit step. Unless `commands.modelsWrite=false`, `/models add` also supports adding a new provider/model entry from chat, and newly added models show up without restarting the gateway. The picker reply is ephemeral and only the invoking user can use it.
+The `/model` and `/models` slash commands open an interactive model picker with provider, model, and compatible runtime dropdowns plus a Submit step. `/models add` is deprecated and now returns a deprecation message instead of registering models from chat. The picker reply is ephemeral and only the invoking user can use it.
 
 File attachments:
 
@@ -958,14 +961,23 @@ Discord has two distinct voice surfaces: realtime **voice channels** (continuous
 
 ### Voice channels
 
-Requirements:
+Setup checklist:
 
-- Enable native commands (`commands.native` or `channels.discord.commands.native`).
-- Configure `channels.discord.voice`.
-- The bot needs Connect + Speak permissions in the target voice channel.
+1. Enable Message Content Intent in the Discord Developer Portal.
+2. Enable Server Members Intent when role/user allowlists are used.
+3. Invite the bot with `bot` and `applications.commands` scopes.
+4. Grant Connect, Speak, Send Messages, and Read Message History in the target voice channel.
+5. Enable native commands (`commands.native` or `channels.discord.commands.native`).
+6. Configure `channels.discord.voice`.
 
 Use `/vc join|leave|status` to control sessions. The command uses the account default agent and follows the same allowlist and group policy rules as other Discord commands.
 
+```bash
+/vc join channel:<voice-channel-id>
+/vc status
+/vc leave
+```
+
 Auto-join example:
 
 ```json5
@@ -974,6 +986,7 @@ Auto-join example:
     discord: {
       voice: {
         enabled: true,
+        model: "openai/gpt-5.4-mini",
         autoJoin: [
           {
             guildId: "123456789012345678",
@@ -984,7 +997,7 @@ Auto-join example:
         decryptionFailureTolerance: 24,
         tts: {
           provider: "openai",
-          openai: { voice: "alloy" },
+          openai: { voice: "onyx" },
         },
       },
     },
@@ -995,12 +1008,24 @@ Auto-join example:
 Notes:
 
 - `voice.tts` overrides `messages.tts` for voice playback only.
+- `voice.model` overrides the LLM used for Discord voice channel responses only. Leave it unset to inherit the routed agent model.
+- STT uses `tools.media.audio`; `voice.model` does not affect transcription.
 - Voice transcript turns derive owner status from Discord `allowFrom` (or `dm.allowFrom`); non-owner speakers cannot access owner-only tools (for example `gateway` and `cron`).
 - Voice is enabled by default; set `channels.discord.voice.enabled=false` to disable it.
 - `voice.daveEncryption` and `voice.decryptionFailureTolerance` pass through to `@discordjs/voice` join options.
 - `@discordjs/voice` defaults are `daveEncryption=true` and `decryptionFailureTolerance=24` if unset.
 - OpenClaw also watches receive decrypt failures and auto-recovers by leaving/rejoining the voice channel after repeated failures in a short window.
-- If receive logs repeatedly show `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, this may be the upstream `@discordjs/voice` receive bug tracked in [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419).
+- If receive logs repeatedly show `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` after updating, collect a dependency report and logs. The bundled `@discordjs/voice` line includes the upstream padding fix from discord.js PR #11449, which closed discord.js issue #11419.
+
+Voice channel pipeline:
+
+- Discord PCM capture is converted to a WAV temp file.
+- `tools.media.audio` handles STT, for example `openai/gpt-4o-mini-transcribe`.
+- The transcript is sent through normal Discord ingress and routing.
+- `voice.model`, when set, overrides only the response LLM for this voice-channel turn.
+- `voice.tts` is merged over `messages.tts`; the resulting audio is played in the joined channel.
+
+Credentials are resolved per component: LLM route auth for `voice.model`, STT auth for `tools.media.audio`, and TTS auth for `messages.tts`/`voice.tts`.
 
 ### Voice messages
 
@@ -1127,7 +1152,7 @@ openclaw logs --follow
     - watch logs for:
       - `discord voice: DAVE decrypt failures detected`
       - `discord voice: repeated decrypt failures; attempting rejoin`
-    - if failures continue after automatic rejoin, collect logs and compare against [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)
+    - if failures continue after automatic rejoin, collect logs and compare against the upstream DAVE receive history in [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) and [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449)
 
   </Accordion>
 </AccordionGroup>

docs/channels/feishu.md

@@ -16,7 +16,7 @@ Feishu/Lark is an all-in-one collaboration platform where teams chat, share docu
 
 ## Quick start
 
-> **Requires OpenClaw 2026.4.24 or above.** Run `openclaw --version` to check. Upgrade with `openclaw update`.
+> **Requires OpenClaw 2026.4.25 or above.** Run `openclaw --version` to check. Upgrade with `openclaw update`.
 
 <Steps>
   <Step title="Run the channel setup wizard">
@@ -424,12 +424,26 @@ Full configuration: [Gateway configuration](/gateway/configuration)
 - ✅ Interactive cards (including streaming updates)
 - ⚠️ Rich text (post-style formatting; doesn't support full Feishu/Lark authoring capabilities)
 
+Native Feishu/Lark audio bubbles use the Feishu `audio` message type and require
+Ogg/Opus upload media (`file_type: "opus"`). Existing `.opus` and `.ogg` media
+is sent directly as native audio. MP3/WAV/M4A and other likely audio formats are
+transcoded to 48kHz Ogg/Opus with `ffmpeg` only when the reply requests voice
+delivery (`audioAsVoice` / message tool `asVoice`, including TTS voice-note
+replies). Ordinary MP3 attachments stay regular files. If `ffmpeg` is missing or
+conversion fails, OpenClaw falls back to a file attachment and logs the reason.
+
 ### Threads and replies
 
 - ✅ Inline replies
 - ✅ Thread replies
 - ✅ Media replies stay thread-aware when replying to a thread message
 
+For `groupSessionScope: "group_topic"` and `"group_topic_sender"`, native
+Feishu/Lark topic groups use the event `thread_id` (`omt_*`) as the canonical
+topic session key. Normal group replies that OpenClaw turns into threads keep
+using the reply root message ID (`om_*`) so the first turn and follow-up turn
+stay in the same session.
+
 ---
 
 ## Related

docs/channels/group-messages.md

@@ -5,8 +5,6 @@ read_when:
 title: "Group messages"
 ---
 
-# Group messages (WhatsApp web channel)
-
 Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.
 
 Note: `agents.list[].groupChat.mentionPatterns` is now used by Telegram/Discord/Slack/iMessage as well; this doc focuses on WhatsApp-specific behavior. For multi-agent setups, set `agents.list[].groupChat.mentionPatterns` per agent (or use `messages.groupChat.mentionPatterns` as a global fallback).

docs/channels/imessage.md

@@ -6,8 +6,6 @@ read_when:
 title: "iMessage"
 ---
 
-# iMessage (legacy: imsg)
-
 <Warning>
 For new iMessage deployments, use <a href="/channels/bluebubbles">BlueBubbles</a>.
 

docs/channels/index.md

@@ -9,6 +9,16 @@ title: "Chat channels"
 OpenClaw can talk to you on any chat app you already use. Each channel connects via the Gateway.
 Text is supported everywhere; media and reactions vary by channel.
 
+## Delivery notes
+
+- Telegram replies that contain markdown image syntax, such as `![alt](url)`,
+  are converted into media replies on the final outbound path when possible.
+- Slack multi-person DMs route as group chats, so group policy, mention
+  behavior, and group-session rules apply to MPIM conversations.
+- WhatsApp setup is install-on-demand: onboarding can show the setup flow before
+  Baileys runtime dependencies are staged, and the Gateway loads the WhatsApp
+  runtime only when the channel is actually active.
+
 ## Supported channels
 
 - [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).

docs/channels/matrix.md

@@ -310,16 +310,127 @@ Enable encryption:
 
 Verification commands (all take `--verbose` for diagnostics and `--json` for machine-readable output):
 
-| Command                                                        | Purpose                                                                             |
-| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `openclaw matrix verify status`                                | Check cross-signing and device verification state                                   |
-| `openclaw matrix verify status --include-recovery-key --json`  | Include the stored recovery key                                                     |
-| `openclaw matrix verify bootstrap`                             | Bootstrap cross-signing and verification (see below)                                |
-| `openclaw matrix verify bootstrap --force-reset-cross-signing` | Discard the current cross-signing identity and create a new one                     |
-| `openclaw matrix verify device "<recovery-key>"`               | Verify this device with a recovery key                                              |
-| `openclaw matrix verify backup status`                         | Check room-key backup health                                                        |
-| `openclaw matrix verify backup restore`                        | Restore room keys from server backup                                                |
-| `openclaw matrix verify backup reset --yes`                    | Delete the current backup and create a fresh baseline (may recreate secret storage) |
+```bash
+openclaw matrix verify status
+```
+
+Verbose status (full diagnostics):
+
+```bash
+openclaw matrix verify status --verbose
+```
+
+Include the stored recovery key in machine-readable output:
+
+```bash
+openclaw matrix verify status --include-recovery-key --json
+```
+
+Bootstrap cross-signing and verification state:
+
+```bash
+openclaw matrix verify bootstrap
+```
+
+Verbose bootstrap diagnostics:
+
+```bash
+openclaw matrix verify bootstrap --verbose
+```
+
+Force a fresh cross-signing identity reset before bootstrapping:
+
+```bash
+openclaw matrix verify bootstrap --force-reset-cross-signing
+```
+
+Verify this device with a recovery key:
+
+```bash
+openclaw matrix verify device "<your-recovery-key>"
+```
+
+This command reports three separate states:
+
+- `Recovery key accepted`: Matrix accepted the recovery key for secret storage or device trust.
+- `Backup usable`: room-key backup can be loaded with trusted recovery material.
+- `Device verified by owner`: the current OpenClaw device has full Matrix cross-signing identity trust.
+
+`Signed by owner` in verbose or JSON output is diagnostic only. OpenClaw does not
+treat that as sufficient unless `Cross-signing verified` is also `yes`.
+
+The command still exits non-zero when full Matrix identity trust is incomplete,
+even if the recovery key can unlock backup material. In that case, complete
+self-verification from another Matrix client:
+
+```bash
+openclaw matrix verify self
+```
+
+Accept the request in another Matrix client, compare the SAS emoji or decimals,
+and type `yes` only when they match. The command waits for Matrix to report
+`Cross-signing verified: yes` before it exits successfully.
+
+Use `verify bootstrap --force-reset-cross-signing` only when you intentionally
+want to replace the current cross-signing identity.
+
+Verbose device verification details:
+
+```bash
+openclaw matrix verify device "<your-recovery-key>" --verbose
+```
+
+Check room-key backup health:
+
+```bash
+openclaw matrix verify backup status
+```
+
+Verbose backup health diagnostics:
+
+```bash
+openclaw matrix verify backup status --verbose
+```
+
+Restore room keys from server backup:
+
+```bash
+openclaw matrix verify backup restore
+```
+
+Interactive self-verification flow:
+
+```bash
+openclaw matrix verify self
+```
+
+For lower-level or inbound verification requests, use:
+
+```bash
+openclaw matrix verify accept <id>
+openclaw matrix verify start <id>
+openclaw matrix verify sas <id>
+openclaw matrix verify confirm-sas <id>
+```
+
+Use `openclaw matrix verify cancel <id>` to cancel a request.
+
+Verbose restore diagnostics:
+
+```bash
+openclaw matrix verify backup restore --verbose
+```
+
+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
+```
+
+All `verify` commands are concise by default (including quiet internal SDK logging) and show detailed diagnostics only with `--verbose`.
+Use `--json` for full machine-readable output when scripting.
 
 In multi-account setups, Matrix CLI commands use the implicit Matrix default account unless you pass `--account <id>`.
 If you configure multiple named accounts, set `channels.matrix.defaultAccount` first or those implicit CLI operations will stop and ask you to choose an account explicitly.
@@ -341,7 +452,9 @@ When encryption is disabled or unavailable for a named account, Matrix warnings
     - `Cross-signing verified`: the SDK reports verification via cross-signing
     - `Signed by owner`: signed by your own self-signing key
 
-    `Verified by owner` becomes `yes` only when cross-signing or owner-signing is present. Local trust alone is not enough.
+    `Verified by owner` becomes `yes` only when cross-signing verification is present.
+    Local trust or an owner signature by itself is not enough for OpenClaw to treat
+    the device as fully verified.
 
   </Accordion>
 

docs/channels/msteams.md

@@ -75,7 +75,7 @@ Disable with:
 
 - Default: `channels.msteams.dmPolicy = "pairing"`. Unknown senders are ignored until approved.
 - `channels.msteams.allowFrom` should use stable AAD object IDs.
-- UPNs/display names are mutable; direct matching is disabled by default and only enabled with `channels.msteams.dangerouslyAllowNameMatching: true`.
+- Do not rely on UPN/display-name matching for allowlists — they can change. OpenClaw disables direct name matching by default; opt in explicitly with `channels.msteams.dangerouslyAllowNameMatching: true`.
 - The wizard can resolve names to IDs via Microsoft Graph when credentials allow.
 
 **Group access**

docs/channels/nextcloud-talk.md

@@ -44,6 +44,31 @@ Details: [Plugins](/tools/plugin)
 4. Configure OpenClaw:
    - Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
    - Or env: `NEXTCLOUD_TALK_BOT_SECRET` (default account only)
+
+   CLI setup:
+
+   ```bash
+   openclaw channels add --channel nextcloud-talk \
+     --url https://cloud.example.com \
+     --token "<shared-secret>"
+   ```
+
+   Equivalent explicit fields:
+
+   ```bash
+   openclaw channels add --channel nextcloud-talk \
+     --base-url https://cloud.example.com \
+     --secret "<shared-secret>"
+   ```
+
+   File-backed secret:
+
+   ```bash
+   openclaw channels add --channel nextcloud-talk \
+     --base-url https://cloud.example.com \
+     --secret-file /path/to/nextcloud-talk-secret
+   ```
+
 5. Restart the gateway (or finish setup).
 
 Minimal config:

docs/channels/pairing.md

@@ -104,6 +104,28 @@ existing approval as-is and creates a fresh pending upgrade request. Use
 `openclaw devices list` to compare the currently approved access with the newly
 requested access before you approve.
 
+### Optional trusted-CIDR node auto-approve
+
+Device pairing remains manual by default. For tightly controlled node networks,
+you can opt in to first-time node auto-approval with explicit CIDRs or exact IPs:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      pairing: {
+        autoApproveCidrs: ["192.168.1.0/24"],
+      },
+    },
+  },
+}
+```
+
+This only applies to fresh `role: node` pairing requests with no requested
+scopes. Operator, browser, Control UI, and WebChat clients still require manual
+approval. Role, scope, metadata, and public-key changes still require manual
+approval.
+
 ### Node pairing state storage
 
 Stored under `~/.openclaw/devices/`:

docs/channels/qqbot.md

@@ -147,6 +147,11 @@ STT and TTS support two-level configuration with priority fallback:
 
 Set `enabled: false` on either to disable.
 
+Inbound QQ voice attachments are exposed to agents as audio media metadata while
+keeping raw voice files out of generic `MediaPaths`. `[[audio_as_voice]]` plain
+text replies synthesize TTS and send a native QQ voice message when TTS is
+configured.
+
 Outbound audio upload/transcode behavior can also be tuned with
 `channels.qqbot.audioFormatPolicy`:
 

docs/channels/signal.md

@@ -6,8 +6,6 @@ read_when:
 title: "Signal"
 ---
 
-# Signal (signal-cli)
-
 Status: external CLI integration. Gateway talks to `signal-cli` over HTTP JSON-RPC + SSE.
 
 ## Prerequisites
@@ -210,6 +208,7 @@ Groups:
 - Outbound text is chunked to `channels.signal.textChunkLimit` (default 4000).
 - Optional newline chunking: set `channels.signal.chunkMode="newline"` to split on blank lines (paragraph boundaries) before length chunking.
 - Attachments supported (base64 fetched from `signal-cli`).
+- Voice-note attachments use the `signal-cli` filename as a MIME fallback when `contentType` is missing, so audio transcription can still classify AAC voice memos.
 - Default media cap: `channels.signal.mediaMaxMb` (default 8).
 - Use `channels.signal.ignoreAttachments` to skip downloading media.
 - Group history context uses `channels.signal.historyLimit` (or `channels.signal.accounts.*.historyLimit`), falling back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).

docs/channels/slack.md

@@ -301,8 +301,8 @@ Surface different features that extend the above defaults.
       },
       {
         "command": "/models",
-        "description": "List providers/models or add a model",
-        "usage_hint": "[provider] [page] [limit=<n>|size=<n>|all] | add <provider> <modelId>"
+        "description": "List providers/models",
+        "usage_hint": "[provider] [page] [limit=<n>|size=<n>|all]"
       },
       {
         "command": "/help",
@@ -436,7 +436,7 @@ Available action groups in current Slack tooling:
 | 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`.
+Current Slack message actions include `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, and `emoji-list`. `download-file` accepts Slack file IDs shown in inbound file placeholders and returns image previews for images or local file metadata for other file types.
 
 ## Access control and routing
 
@@ -606,7 +606,7 @@ Notes:
 
 <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.
+    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. File placeholders include the Slack `fileId` so agents can fetch the original file with `download-file`.
 
     Runtime inbound size cap defaults to `20MB` unless overridden by `channels.slack.mediaMaxMb`.
 
@@ -773,7 +773,8 @@ Same-chat `/approve` also works in Slack channels and DMs that already support c
 
 ## Events and operational behavior
 
-- Message edits/deletes/thread broadcasts are mapped into system events.
+- Message edits/deletes are mapped into system events.
+- Thread broadcasts ("Also send to channel" thread replies) are processed as normal user messages.
 - 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.
@@ -826,6 +827,9 @@ openclaw doctor
     - `channels.slack.dm.enabled`
     - `channels.slack.dmPolicy` (or legacy `channels.slack.dm.policy`)
     - pairing approvals / allowlist entries
+    - Slack Assistant DM events: verbose logs mentioning `drop message_changed`
+      usually mean Slack sent an edited Assistant-thread event without a
+      recoverable human sender in message metadata
 
 ```bash
 openclaw pairing list slack

docs/channels/telegram.md

@@ -257,6 +257,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 - Group sessions are isolated by group ID. Forum topics append `:topic:<threadId>` to keep topics isolated.
 - DM messages can carry `message_thread_id`; OpenClaw routes them with thread-aware session keys and preserves thread ID for replies.
 - Long polling uses grammY runner with per-chat/per-thread sequencing. Overall runner sink concurrency uses `agents.defaults.maxConcurrent`.
+- Long polling is guarded inside each gateway process so only one active poller can use a bot token at a time. If you still see `getUpdates` 409 conflicts, another OpenClaw gateway, script, or external poller is likely using the same token.
 - Long-polling watchdog restarts trigger after 120 seconds without completed `getUpdates` liveness by default. Increase `channels.telegram.pollingStallThresholdMs` only if your deployment still sees false polling-stall restarts during long-running work. The value is in milliseconds and is allowed from `30000` to `600000`; per-account overrides are supported.
 - Telegram Bot API has no read-receipt support (`sendReadReceipts` does not apply).
 
@@ -273,8 +274,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     - `channels.telegram.streaming` is `off | partial | block | progress` (default: `partial`)
     - `progress` maps to `partial` on Telegram (compat with cross-channel naming)
-    - `streaming.preview.toolProgress` controls whether tool/progress updates reuse the same edited preview message (default: `true`). Set `false` to keep separate tool/progress messages.
-    - legacy `channels.telegram.streamMode` and boolean `streaming` values are auto-mapped
+    - `streaming.preview.toolProgress` controls whether tool/progress updates reuse the same edited preview message (default: `true` when preview streaming is active)
+    - legacy `channels.telegram.streamMode` and boolean `streaming` values are detected; run `openclaw doctor --fix` to migrate them to `channels.telegram.streaming.mode`
+
+    Tool-progress preview updates are the short "Working..." lines shown while tools run, for example command execution, file reads, planning updates, or patch summaries. Telegram keeps these enabled by default to match released OpenClaw behavior from `v2026.4.22` and later. To keep the edited preview for answer text but hide tool-progress lines, set:
+
+    ```json
+    {
+      "channels": {
+        "telegram": {
+          "streaming": {
+            "mode": "partial",
+            "preview": {
+              "toolProgress": false
+            }
+          }
+        }
+      }
+    }
+    ```
+
+    Use `streaming.mode: "off"` only when you want to disable Telegram preview edits entirely. Use `streaming.preview.toolProgress: false` when you only want to disable the tool-progress status lines.
 
     For text-only replies:
 
@@ -526,6 +546,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     - default: audio file behavior
     - tag `[[audio_as_voice]]` in agent reply to force voice-note send
+    - inbound voice-note transcripts are framed as machine-generated,
+      untrusted text in the agent context; mention detection still uses the raw
+      transcript so mention-gated voice messages continue to work.
 
     Message action example:
 
@@ -685,6 +708,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     The local listener binds to `127.0.0.1:8787`. For public ingress, either put a reverse proxy in front of the local port or set `webhookHost: "0.0.0.0"` intentionally.
 
+    Webhook mode validates request guards, the Telegram secret token, and the JSON body before returning `200` to Telegram.
+    OpenClaw then processes the update asynchronously through the same per-chat/per-topic bot lanes used by long polling, so slow agent turns do not hold Telegram's delivery ACK.
+
   </Accordion>
 
   <Accordion title="Limits, retry, and CLI targets">

docs/channels/whatsapp.md

@@ -64,6 +64,13 @@ openclaw channels login --channel whatsapp
 
 ```bash
 openclaw channels login --channel whatsapp --account work
+```
+
+    To attach an existing/custom WhatsApp Web auth directory before login:
+
+```bash
+openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
+openclaw channels login --channel whatsapp --account work
 ```
 
   </Step>
@@ -145,6 +152,46 @@ OpenClaw recommends running WhatsApp on a separate number when possible. (The ch
 - Group sessions are isolated (`agent:<agentId>:whatsapp:group:<jid>`).
 - WhatsApp Web transport honors standard proxy environment variables on the gateway host (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / lowercase variants). Prefer host-level proxy config over channel-specific WhatsApp proxy settings.
 
+## Plugin hooks and privacy
+
+WhatsApp inbound messages can contain personal message content, phone numbers,
+group identifiers, sender names, and session correlation fields. For that reason,
+WhatsApp does not broadcast inbound `message_received` hook payloads to plugins
+unless you explicitly opt in:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      pluginHooks: {
+        messageReceived: true,
+      },
+    },
+  },
+}
+```
+
+You can scope the opt-in to one account:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      accounts: {
+        work: {
+          pluginHooks: {
+            messageReceived: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Only enable this for plugins you trust to receive inbound WhatsApp message
+content and identifiers.
+
 ## Access control and activation
 
 <Tabs>
@@ -164,7 +211,7 @@ OpenClaw recommends running WhatsApp on a separate number when possible. (The ch
 
     - pairings are persisted in channel allow-store and merged with configured `allowFrom`
     - if no allowlist is configured, the linked self number is allowed by default
-    - outbound `fromMe` DMs are never auto-paired
+    - OpenClaw never auto-pairs outbound `fromMe` DMs (messages you send to yourself from the linked device)
 
   </Tab>
 
@@ -314,9 +361,11 @@ When the linked self number is also present in `allowFrom`, WhatsApp self-chat s
 
   <Accordion title="Outbound media behavior">
     - supports image, video, audio (PTT voice-note), and document payloads
-    - `audio/ogg` is rewritten to `audio/ogg; codecs=opus` for voice-note compatibility
+    - reply payloads preserve `audioAsVoice`; WhatsApp sends audio media as Baileys PTT voice notes
+    - non-Ogg audio, including Microsoft Edge TTS MP3/WebM output, is transcoded to Ogg/Opus before PTT delivery
+    - native Ogg/Opus audio is sent with `audio/ogg; codecs=opus` for voice-note compatibility
     - animated GIF playback is supported via `gifPlayback: true` on video sends
-    - captions are applied to the first media item when sending multi-media reply payloads
+    - captions are applied to the first media item when sending multi-media reply payloads, except PTT voice notes send the audio first and visible text separately because WhatsApp clients do not render voice-note captions consistently
     - media source can be HTTP(S), `file://`, or local paths
   </Accordion>
 
@@ -333,19 +382,20 @@ When the linked self number is also present in `allowFrom`, WhatsApp self-chat s
 
 WhatsApp supports native reply quoting, where outbound replies visibly quote the inbound message. Control it with `channels.whatsapp.replyToMode`.
 
-| Value    | Behavior                                                                           |
-| -------- | ---------------------------------------------------------------------------------- |
-| `"auto"` | Quote the inbound message when the provider supports it; skip quoting otherwise    |
-| `"on"`   | Always quote the inbound message; fall back to a plain send if quoting is rejected |
-| `"off"`  | Never quote; send as a plain message                                               |
+| Value       | Behavior                                                              |
+| ----------- | --------------------------------------------------------------------- |
+| `"off"`     | Never quote; send as a plain message                                  |
+| `"first"`   | Quote only the first outbound reply chunk                             |
+| `"all"`     | Quote every outbound reply chunk                                      |
+| `"batched"` | Quote queued batched replies while leaving immediate replies unquoted |
 
-Default is `"auto"`. Per-account overrides use `channels.whatsapp.accounts.<id>.replyToMode`.
+Default is `"off"`. Per-account overrides use `channels.whatsapp.accounts.<id>.replyToMode`.
 
 ```json5
 {
   channels: {
     whatsapp: {
-      replyToMode: "on",
+      replyToMode: "first",
     },
   },
 }
@@ -493,15 +543,15 @@ Resolution hierarchy for group messages:
 
 The effective `groups` map is determined first: if the account defines its own `groups`, it fully replaces the root `groups` map (no deep merge). Prompt lookup then runs on the resulting single map:
 
-1. **Group-specific system prompt** (`groups["<groupId>"].systemPrompt`): used if the specific group entry defines a `systemPrompt`.
-2. **Group wildcard system prompt** (`groups["*"].systemPrompt`): used when the specific group entry is absent or defines no `systemPrompt`.
+1. **Group-specific system prompt** (`groups["<groupId>"].systemPrompt`): used when the specific group entry exists in the map **and** its `systemPrompt` key is defined. If `systemPrompt` is an empty string (`""`), the wildcard is suppressed and no system prompt is applied.
+2. **Group wildcard system prompt** (`groups["*"].systemPrompt`): used when the specific group entry is absent from the map entirely, or when it exists but defines no `systemPrompt` key.
 
 Resolution hierarchy for direct messages:
 
 The effective `direct` map is determined first: if the account defines its own `direct`, it fully replaces the root `direct` map (no deep merge). Prompt lookup then runs on the resulting single map:
 
-1. **Direct-specific system prompt** (`direct["<peerId>"].systemPrompt`): used if the specific peer entry defines a `systemPrompt`.
-2. **Direct wildcard system prompt** (`direct["*"].systemPrompt`): used when the specific peer entry is absent or defines no `systemPrompt`.
+1. **Direct-specific system prompt** (`direct["<peerId>"].systemPrompt`): used when the specific peer entry exists in the map **and** its `systemPrompt` key is defined. If `systemPrompt` is an empty string (`""`), the wildcard is suppressed and no system prompt is applied.
+2. **Direct wildcard system prompt** (`direct["*"].systemPrompt`): used when the specific peer entry is absent from the map entirely, or when it exists but defines no `systemPrompt` key.
 
 Note: `dms` remains the lightweight per-DM history override bucket (`dms.<id>.historyLimit`); prompt overrides live under `direct`.
 

docs/channels/zalo.md

@@ -5,8 +5,6 @@ read_when:
 title: "Zalo"
 ---
 
-# Zalo (Bot API)
-
 Status: experimental. DMs are supported. The [Capabilities](#capabilities) section below reflects current Marketplace-bot behavior.
 
 ## Bundled plugin

docs/channels/zalouser.md

@@ -6,8 +6,6 @@ read_when:
 title: "Zalo personal"
 ---
 
-# Zalo Personal (unofficial)
-
 Status: experimental. This integration automates a **personal Zalo account** via native `zca-js` inside OpenClaw.
 
 > **Warning:** This is an unofficial integration and may result in account suspension/ban. Use at your own risk.

docs/ci.md

@@ -10,7 +10,7 @@ The CI runs on every push to `main` and every pull request. It uses smart scopin
 
 QA Lab has dedicated CI lanes outside the main smart-scoped workflow. The
 `Parity gate` workflow runs on matching PR changes and manual dispatch; it
-builds the private QA runtime and compares the mock GPT-5.4 and Opus 4.6
+builds the private QA runtime and compares the mock GPT-5.5 and Opus 4.6
 agentic packs. The `QA-Lab - All Lanes` workflow runs nightly on `main` and on
 manual dispatch; it fans out the mock parity gate, live Matrix lane, and live
 Telegram lane as parallel jobs. The live jobs use the `qa-live-shared`
@@ -79,7 +79,7 @@ gh workflow run duplicate-after-merge.yml \
 | `android`                        | Android unit tests for both flavors plus one debug APK build                                 | Android-relevant changes             |
 | `test-performance-agent`         | Daily Codex slow-test optimization after trusted activity                                    | Main CI success or manual dispatch   |
 
-## Fail-Fast Order
+## Fail-fast order
 
 Jobs are ordered so cheap checks fail before expensive ones run:
 
@@ -90,14 +90,15 @@ Jobs are ordered so cheap checks fail before expensive ones run:
 
 Scope logic lives in `scripts/ci-changed-scope.mjs` and is covered by unit tests in `src/scripts/ci-changed-scope.test.ts`.
 CI workflow edits validate the Node CI graph plus workflow linting, but do not force Windows, Android, or macOS native builds by themselves; those platform lanes stay scoped to platform source changes.
+CI routing-only edits, selected cheap core-test fixture edits, and narrow plugin contract helper/test-routing edits use a fast Node-only manifest path: preflight, security, and a single `checks-fast-core` task. That path avoids build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards, and additional guard matrices when the changed files are limited to the routing or helper surfaces that the fast task exercises directly.
 Windows Node checks are scoped to Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config, and the CI workflow surfaces that execute that lane; unrelated source, plugin, install-smoke, and test-only changes stay on the Linux Node lanes so they do not reserve a 16-vCPU Windows worker for coverage that is already exercised by the normal test shards.
-The separate `install-smoke` workflow reuses the same scope script through its own `preflight` job. It splits smoke coverage into `run_fast_install_smoke` and `run_full_install_smoke`. Pull requests run the fast path for Docker/package surfaces, bundled plugin package/manifest changes, and core plugin/channel/gateway/Plugin SDK surfaces that the Docker smoke jobs exercise. Source-only bundled plugin changes, test-only edits, and docs-only edits do not reserve Docker workers. The fast path builds the root Dockerfile image once, checks the CLI, runs the container gateway-network e2e, verifies a bundled extension build arg, and runs the bounded bundled-plugin Docker profile under a 120-second command timeout. The full path keeps QR package install and installer Docker/update coverage for nightly scheduled runs, manual dispatches, workflow-call release checks, and pull requests that truly touch installer/package/Docker surfaces. `main` pushes, including merge commits, do not force the full path; when changed-scope logic would request full coverage on a push, the workflow keeps the fast Docker smoke and leaves the full install smoke to nightly or release validation. The slow Bun global install image-provider smoke is separately gated by `run_bun_global_install_smoke`; it runs on the nightly schedule and from the release checks workflow, and manual `install-smoke` dispatches can opt into it, but pull requests and `main` pushes do not run it. QR and installer Docker tests keep their own install-focused Dockerfiles. Local `test:docker:all` prebuilds one shared live-test image and one shared `scripts/e2e/Dockerfile` built-app image, then runs the live/E2E smoke lanes in parallel with `OPENCLAW_SKIP_DOCKER_BUILD=1`; tune the default concurrency of 4 with `OPENCLAW_DOCKER_ALL_PARALLELISM`. The local aggregate stops scheduling new pooled lanes after the first failure by default, and each lane has a 120-minute timeout overrideable with `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Startup- or provider-sensitive lanes run exclusively after the parallel pool. The reusable live/E2E workflow mirrors the shared-image pattern by building and pushing one SHA-tagged GHCR Docker E2E image before the Docker matrix, then running the matrix with `OPENCLAW_SKIP_DOCKER_BUILD=1`. The scheduled live/E2E workflow runs the full release-path Docker suite daily. The full bundled update/channel matrix remains manual/full-suite because it performs repeated real npm update and doctor repair passes.
+The separate `install-smoke` workflow reuses the same scope script through its own `preflight` job. It splits smoke coverage into `run_fast_install_smoke` and `run_full_install_smoke`. Pull requests run the fast path for Docker/package surfaces, bundled plugin package/manifest changes, and core plugin/channel/gateway/Plugin SDK surfaces that the Docker smoke jobs exercise. Source-only bundled plugin changes, test-only edits, and docs-only edits do not reserve Docker workers. The fast path builds the root Dockerfile image once, checks the CLI, runs the agents delete shared-workspace CLI smoke, runs the container gateway-network e2e, verifies a bundled extension build arg, and runs the bounded bundled-plugin Docker profile under a 240-second aggregate command timeout with each scenario's Docker run capped separately. The full path keeps QR package install and installer Docker/update coverage for nightly scheduled runs, manual dispatches, workflow-call release checks, and pull requests that truly touch installer/package/Docker surfaces. `main` pushes, including merge commits, do not force the full path; when changed-scope logic would request full coverage on a push, the workflow keeps the fast Docker smoke and leaves the full install smoke to nightly or release validation. The slow Bun global install image-provider smoke is separately gated by `run_bun_global_install_smoke`; it runs on the nightly schedule and from the release checks workflow, and manual `install-smoke` dispatches can opt into it, but pull requests and `main` pushes do not run it. QR and installer Docker tests keep their own install-focused Dockerfiles. Local `test:docker:all` prebuilds one shared live-test image and one shared `scripts/e2e/Dockerfile` built-app image, then runs the live/E2E smoke lanes with a weighted scheduler and `OPENCLAW_SKIP_DOCKER_BUILD=1`; tune the default main-pool slot count of 10 with `OPENCLAW_DOCKER_ALL_PARALLELISM` and the provider-sensitive tail-pool slot count of 10 with `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Heavy lane caps default to `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8`, and `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` so npm install and multi-service lanes do not overcommit Docker while lighter lanes still fill available slots. Lane starts are staggered by 2 seconds by default to avoid local Docker daemon create storms; override with `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` or another millisecond value. The local aggregate preflights Docker, removes stale OpenClaw E2E containers, emits active-lane status, persists lane timings for longest-first ordering, and supports `OPENCLAW_DOCKER_ALL_DRY_RUN=1` for scheduler inspection. It stops scheduling new pooled lanes after the first failure by default, and each lane has a 120-minute fallback timeout overrideable with `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; selected live/tail lanes use tighter per-lane caps. The reusable live/E2E workflow mirrors the shared-image pattern by building and pushing one SHA-tagged GHCR Docker E2E image before the Docker matrix, then running the matrix with `OPENCLAW_SKIP_DOCKER_BUILD=1`. The scheduled live/E2E workflow runs the full release-path Docker suite daily. The bundled update matrix is split by update target so repeated npm update and doctor repair passes can shard with other bundled checks.
 
 Local changed-lane logic lives in `scripts/changed-lanes.mjs` and is executed by `scripts/check-changed.mjs`. That local gate is stricter about architecture boundaries than the broad CI platform scope: core production changes run core prod typecheck plus core tests, core test-only changes run only core test typecheck/tests, extension production changes run extension prod typecheck plus extension tests, and extension test-only changes run only extension test typecheck/tests. Public Plugin SDK or plugin-contract changes expand to extension validation because extensions depend on those core contracts. Release metadata-only version bumps run targeted version/config/root-dependency checks. Unknown root/config changes fail safe to all lanes.
 
 On pushes, the `checks` matrix adds the push-only `compat-node22` lane. On pull requests, that lane is skipped and the matrix stays focused on the normal test/channel lanes.
 
-The slowest Node test families are split or balanced so each job stays small without over-reserving runners: channel contracts run as three weighted shards, bundled plugin tests balance across six extension workers, small core unit lanes are paired, auto-reply runs as three balanced workers instead of six tiny workers, and agentic gateway/plugin configs are spread across the existing source-only agentic Node jobs instead of waiting on built artifacts. Broad browser, QA, media, and miscellaneous plugin tests use their dedicated Vitest configs instead of the shared plugin catch-all. Extension shard jobs run plugin config groups serially with one Vitest worker and a larger Node heap so import-heavy plugin batches do not overcommit small CI runners. The broad agents lane uses the shared Vitest file-parallel scheduler because it is import/scheduling dominated rather than owned by a single slow test file. `runtime-config` runs with the infra core-runtime shard to keep the shared runtime shard from owning the tail. `check-additional` keeps package-boundary compile/canary work together and separates runtime topology architecture from gateway watch coverage; the boundary guard shard runs its small independent guards concurrently inside one job. Gateway watch, channel tests, and the core support-boundary shard run concurrently inside `build-artifacts` after `dist/` and `dist-runtime/` are already built, keeping their old check names as lightweight verifier jobs while avoiding two extra Blacksmith workers and a second artifact-consumer queue.
+The slowest Node test families are split or balanced so each job stays small without over-reserving runners: channel contracts run as three weighted shards, bundled plugin tests balance across six extension workers, small core unit lanes are paired, auto-reply runs as three balanced workers instead of six tiny workers, and agentic gateway/plugin configs are spread across the existing source-only agentic Node jobs instead of waiting on built artifacts. Broad browser, QA, media, and miscellaneous plugin tests use their dedicated Vitest configs instead of the shared plugin catch-all. Extension shard jobs run up to two plugin config groups at a time with one Vitest worker per group and a larger Node heap so import-heavy plugin batches do not create extra CI jobs. The broad agents lane uses the shared Vitest file-parallel scheduler because it is import/scheduling dominated rather than owned by a single slow test file. `runtime-config` runs with the infra core-runtime shard to keep the shared runtime shard from owning the tail. `check-additional` keeps package-boundary compile/canary work together and separates runtime topology architecture from gateway watch coverage; the boundary guard shard runs its small independent guards concurrently inside one job. Gateway watch, channel tests, and the core support-boundary shard run concurrently inside `build-artifacts` after `dist/` and `dist-runtime/` are already built, keeping their old check names as lightweight verifier jobs while avoiding two extra Blacksmith workers and a second artifact-consumer queue.
 Android CI runs both `testPlayDebugUnitTest` and `testThirdPartyDebugUnitTest`, then builds the Play debug APK. The third-party flavor has no separate source set or manifest; its unit-test lane still compiles that flavor with the SMS/call-log BuildConfig flags, while avoiding a duplicate debug APK packaging job on every Android-relevant push.
 `extension-fast` is PR-only because push runs already execute the full bundled plugin shards. That keeps changed-plugin feedback for reviews without reserving an extra Blacksmith worker on `main` for coverage already present in `checks-node-extensions`.
 
@@ -136,3 +137,8 @@ node scripts/ci-run-timings.mjs --recent 10   # compare recent successful main C
 pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
 pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
 ```
+
+## Related
+
+- [Install overview](/install)
+- [Release channels](/install/development-channels)

docs/cli/acp.md

@@ -314,3 +314,8 @@ Security note:
 - `--server-args <args...>`: extra arguments passed to the ACP server.
 - `--server-verbose`: enable verbose logging on the ACP server.
 - `--verbose, -v`: verbose client logging.
+
+## Related
+
+- [CLI reference](/cli)
+- [ACP agents](/tools/acp-agents)

docs/cli/agent.md

@@ -52,7 +52,9 @@ openclaw agent --agent ops --message "Run locally" --local
 
 - Gateway mode falls back to the embedded agent when the Gateway request fails. Use `--local` to force embedded execution up front.
 - `--local` still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
+- Each `openclaw agent` invocation is treated as a one-shot run. Bundled or user-configured MCP servers opened for that run are retired after the reply, even when the command uses the Gateway path, so stdio MCP child processes do not stay alive between scripted invocations.
 - `--channel`, `--reply-channel`, and `--reply-account` affect reply delivery, not session routing.
+- `--json` keeps stdout reserved for the JSON response. Gateway, plugin, and embedded-fallback diagnostics are routed to stderr so scripts can parse stdout directly.
 - When this command triggers `models.json` regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, `secretref-env:ENV_VAR_NAME`, or `secretref-managed`), not resolved secret plaintext.
 - Marker writes are source-authoritative: OpenClaw persists markers from the active source config snapshot, not from resolved runtime secret values.
 

docs/cli/agents.md

@@ -150,6 +150,9 @@ Notes:
 - `main` cannot be deleted.
 - Without `--force`, interactive confirmation is required.
 - Workspace, agent state, and session transcript directories are moved to Trash, not hard-deleted.
+- If another agent's workspace is the same path, inside this workspace, or contains this workspace,
+  the workspace is retained and `--json` reports `workspaceRetained`,
+  `workspaceRetainedReason`, and `workspaceSharedWith`.
 
 ## Identity files
 

docs/cli/backup.md

@@ -82,3 +82,7 @@ Practical limits come from the local machine and destination filesystem:
 Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.
 
 For the smallest archive, use `--only-config`.
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/browser.md

@@ -33,6 +33,8 @@ openclaw browser --browser-profile openclaw open https://example.com
 openclaw browser --browser-profile openclaw snapshot
 ```
 
+Agents can run the same readiness check with `browser({ action: "doctor" })`.
+
 ## Quick troubleshooting
 
 If `start` fails with `not reachable after start`, troubleshoot CDP readiness first. If `start` and `tabs` succeed but `open` or `navigate` fails, the browser control plane is healthy and the failure is usually navigation SSRF policy.
@@ -40,6 +42,7 @@ If `start` fails with `not reachable after start`, troubleshoot CDP readiness fi
 Minimal sequence:
 
 ```bash
+openclaw browser --browser-profile openclaw doctor
 openclaw browser --browser-profile openclaw start
 openclaw browser --browser-profile openclaw tabs
 openclaw browser --browser-profile openclaw open https://example.com
@@ -51,7 +54,9 @@ Detailed guidance: [Browser troubleshooting](/tools/browser#cdp-startup-failure-
 
 ```bash
 openclaw browser status
+openclaw browser doctor
 openclaw browser start
+openclaw browser start --headless
 openclaw browser stop
 openclaw browser --browser-profile openclaw reset-profile
 ```
@@ -63,6 +68,14 @@ Notes:
   OpenClaw did not launch the browser process itself.
 - For local managed profiles, `openclaw browser stop` stops the spawned browser
   process.
+- `openclaw browser start --headless` applies only to that start request and
+  only when OpenClaw launches a local managed browser. It does not rewrite
+  `browser.headless` or profile config, and it is a no-op for an already-running
+  browser.
+- On Linux hosts without `DISPLAY` or `WAYLAND_DISPLAY`, local managed profiles
+  run headless automatically unless `OPENCLAW_BROWSER_HEADLESS=0`,
+  `browser.headless=false`, or `browser.profiles.<name>.headless=false`
+  explicitly requests a visible browser.
 
 ## If the command is missing
 
@@ -111,20 +124,28 @@ openclaw browser --browser-profile work tabs
 
 ```bash
 openclaw browser tabs
-openclaw browser tab new
+openclaw browser tab new --label docs
+openclaw browser tab label t1 docs
 openclaw browser tab select 2
 openclaw browser tab close 2
-openclaw browser open https://docs.openclaw.ai
-openclaw browser focus <targetId>
-openclaw browser close <targetId>
+openclaw browser open https://docs.openclaw.ai --label docs
+openclaw browser focus docs
+openclaw browser close t1
 ```
 
+`tabs` returns `suggestedTargetId` first, then the stable `tabId` such as `t1`,
+the optional label, and the raw `targetId`. Agents should pass
+`suggestedTargetId` back into `focus`, `close`, snapshots, and actions. You can
+assign a label with `open --label`, `tab new --label`, or `tab label`; labels,
+tab ids, raw target ids, and unique target-id prefixes are all accepted.
+
 ## Snapshot / screenshot / actions
 
 Snapshot:
 
 ```bash
 openclaw browser snapshot
+openclaw browser snapshot --urls
 ```
 
 Screenshot:
@@ -133,6 +154,7 @@ Screenshot:
 openclaw browser screenshot
 openclaw browser screenshot --full-page
 openclaw browser screenshot --ref e12
+openclaw browser screenshot --labels
 ```
 
 Notes:
@@ -141,12 +163,17 @@ Notes:
   or `--element`.
 - `existing-session` / `user` profiles support page screenshots and `--ref`
   screenshots from snapshot output, but not CSS `--element` screenshots.
+- `--labels` overlays current snapshot refs on the screenshot.
+- `snapshot --urls` appends discovered link destinations to AI snapshots so
+  agents can choose direct navigation targets instead of guessing from link
+  text alone.
 
 Navigate/click/type (ref-based UI automation):
 
 ```bash
 openclaw browser navigate https://example.com
 openclaw browser click <ref>
+openclaw browser click-coords 120 340
 openclaw browser type <ref> "hello"
 openclaw browser press Enter
 openclaw browser hover <ref>
@@ -167,6 +194,11 @@ openclaw browser download <ref> report.pdf
 openclaw browser dialog --accept
 ```
 
+Managed Chrome profiles save ordinary click-triggered downloads into the OpenClaw
+downloads directory (`/tmp/openclaw/downloads` by default, or the configured temp
+root). Use `waitfordownload` or `download` when the agent needs to wait for a
+specific file and return its path; those explicit waiters own the next download.
+
 ## State and storage
 
 Viewport + emulation:
@@ -224,6 +256,8 @@ This path is host-only. For Docker, headless servers, Browserless, or other remo
 Current existing-session limits:
 
 - snapshot-driven actions use refs, not CSS selectors
+- `browser.actionTimeoutMs` defaults supported `act` requests to 60000 ms when
+  callers omit `timeoutMs`; per-call `timeoutMs` still wins.
 - `click` is left-click only
 - `type` does not support `slowly=true`
 - `press` does not support `delayMs`
@@ -245,3 +279,8 @@ If the Gateway runs on a different machine than the browser, run a **node host**
 Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if multiple are connected.
 
 Security + remote setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)
+
+## Related
+
+- [CLI reference](/cli)
+- [Browser](/tools/browser)

docs/cli/clawbot.md

@@ -19,3 +19,7 @@ Current supported alias:
 Prefer modern top-level commands directly:
 
 - `openclaw clawbot qr` -> `openclaw qr`
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/completion.md

@@ -33,3 +33,7 @@ openclaw completion --shell bash --write-state
 - `--install` writes a small "OpenClaw Completion" block into your shell profile and points it at the cached script.
 - Without `--install` or `--write-state`, the command prints the script to stdout.
 - Completion generation eagerly loads command trees so nested subcommands are included.
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/config.md

@@ -36,6 +36,7 @@ openclaw config --section gateway --section daemon
 openclaw config schema
 openclaw config get browser.executablePath
 openclaw config set browser.executablePath "/usr/bin/google-chrome"
+openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
 openclaw config set agents.defaults.heartbeat.every "2h"
 openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
 openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
@@ -185,7 +186,7 @@ openclaw config set secrets.providers.vaultfile \
   --strict-json
 ```
 
-## Provider Builder Flags
+## Provider builder flags
 
 Provider builder targets must use `secrets.providers.<alias>` as the path.
 
@@ -278,7 +279,7 @@ Dry-run behavior:
 - `skippedExecRefs`: number of exec refs skipped because `--allow-exec` was not set
 - `errors`: structured schema/resolvability failures when `ok=false`
 
-### JSON Output Shape
+### JSON output shape
 
 ```json5
 {
@@ -385,6 +386,15 @@ untrusted until they validate. Invalid direct edits can be restored from the
 last-known-good backup during startup or hot reload. See
 [Gateway troubleshooting](/gateway/troubleshooting#gateway-restored-last-known-good-config).
 
+Whole-file recovery is reserved for globally broken config, such as parse
+errors, root-level schema failures, legacy migration failures, or mixed plugin
+and root failures. If validation fails only under `plugins.entries.<id>...`,
+OpenClaw keeps the active `openclaw.json` in place and reports the plugin-local
+issue instead of restoring `.last-good`. This prevents plugin schema changes or
+`minHostVersion` skew from rolling back unrelated user settings such as models,
+providers, auth profiles, channels, gateway exposure, tools, memory, browser, or
+cron config.
+
 ## Subcommands
 
 - `config file`: Print the active config file path (resolved from `OPENCLAW_CONFIG_PATH` or default location). The path should name a regular file, not a symlink.

docs/cli/configure.md

@@ -13,6 +13,9 @@ Note: The **Model** section now includes a multi-select for the
 `agents.defaults.models` allowlist (what shows up in `/model` and the model picker).
 Provider-scoped setup choices merge their selected models into the existing
 allowlist instead of replacing unrelated providers already in the config.
+Re-running provider auth from configure preserves an existing
+`agents.defaults.model.primary`; use `openclaw models auth login --provider <id> --set-default`
+or `openclaw models set <model>` when you intentionally want to change the default model.
 
 When configure starts from a provider auth choice, the default-model and
 allowlist pickers prefer that provider automatically. For paired providers such
@@ -70,3 +73,8 @@ openclaw configure --section web
 openclaw configure --section model --section channels
 openclaw configure --section gateway --section daemon
 ```
+
+## Related
+
+- [CLI reference](/cli)
+- [Configuration](/gateway/configuration)

docs/cli/crestodian.md

@@ -0,0 +1,322 @@
+---
+summary: "CLI reference and security model for Crestodian, the configless-safe setup and repair helper"
+read_when:
+  - You run openclaw with no command and want to understand Crestodian
+  - You need a configless-safe way to inspect or repair OpenClaw
+  - You are designing or enabling message-channel rescue mode
+title: "Crestodian"
+---
+
+# `openclaw crestodian`
+
+Crestodian is OpenClaw's local setup, repair, and configuration helper. It is
+designed to stay reachable when the normal agent path is broken.
+
+Running `openclaw` with no command starts Crestodian in an interactive terminal.
+Running `openclaw crestodian` starts the same helper explicitly.
+
+## What Crestodian shows
+
+On startup, interactive Crestodian opens the same TUI shell used by
+`openclaw tui`, with a Crestodian chat backend. The chat log starts with a short
+greeting:
+
+- when to start Crestodian
+- the model or deterministic planner path Crestodian is actually using
+- config validity and the default agent
+- Gateway reachability from the first startup probe
+- the next debug action Crestodian can take
+
+It does not dump secrets or load plugin CLI commands just to start. The TUI
+still provides the normal header, chat log, status line, footer, autocomplete,
+and editor controls.
+
+Use `status` for the detailed inventory with config path, docs/source paths,
+local CLI probes, API-key presence, agents, model, and Gateway details.
+
+Crestodian uses the same OpenClaw reference discovery as regular agents. In a Git checkout,
+it points itself at local `docs/` and the local source tree. In an npm package install, it
+uses the bundled package docs and links to
+[https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw), with explicit
+guidance to review source whenever the docs are not enough.
+
+## Examples
+
+```bash
+openclaw
+openclaw crestodian
+openclaw crestodian --json
+openclaw crestodian --message "models"
+openclaw crestodian --message "validate config"
+openclaw crestodian --message "setup workspace ~/Projects/work model openai/gpt-5.5" --yes
+openclaw crestodian --message "set default model openai/gpt-5.5" --yes
+openclaw onboard --modern
+```
+
+Inside the Crestodian TUI:
+
+```text
+status
+health
+doctor
+doctor fix
+validate config
+setup
+setup workspace ~/Projects/work model openai/gpt-5.5
+config set gateway.port 19001
+config set-ref gateway.auth.token env OPENCLAW_GATEWAY_TOKEN
+gateway status
+restart gateway
+agents
+create agent work workspace ~/Projects/work
+models
+set default model openai/gpt-5.5
+talk to work agent
+talk to agent for ~/Projects/work
+audit
+quit
+```
+
+## Safe startup
+
+Crestodian's startup path is deliberately small. It can run when:
+
+- `openclaw.json` is missing
+- `openclaw.json` is invalid
+- the Gateway is down
+- plugin command registration is unavailable
+- no agent has been configured yet
+
+`openclaw --help` and `openclaw --version` still use the normal fast paths.
+Noninteractive `openclaw` exits with a short message instead of printing root
+help, because the no-command product is Crestodian.
+
+## Operations and approval
+
+Crestodian uses typed operations instead of editing config ad hoc.
+
+Read-only operations can run immediately:
+
+- show overview
+- list agents
+- show model/backend status
+- run status or health checks
+- check Gateway reachability
+- run doctor without interactive fixes
+- validate config
+- show the audit-log path
+
+Persistent operations require conversational approval in interactive mode unless
+you pass `--yes` for a direct command:
+
+- write config
+- run `config set`
+- set supported SecretRef values through `config set-ref`
+- run setup/onboarding bootstrap
+- change the default model
+- start, stop, or restart the Gateway
+- create agents
+- run doctor repairs that rewrite config or state
+
+Applied writes are recorded in:
+
+```text
+~/.openclaw/audit/crestodian.jsonl
+```
+
+Discovery is not audited. Only applied operations and writes are logged.
+
+`openclaw onboard --modern` starts Crestodian as the modern onboarding preview.
+Plain `openclaw onboard` still runs classic onboarding.
+
+## Setup Bootstrap
+
+`setup` is the chat-first onboarding bootstrap. It writes only through typed
+config operations and asks for approval first.
+
+```text
+setup
+setup workspace ~/Projects/work
+setup workspace ~/Projects/work model openai/gpt-5.5
+```
+
+When no model is configured, setup selects the first usable backend in this
+order and tells you what it chose:
+
+- existing explicit model, if already configured
+- `OPENAI_API_KEY` -> `openai/gpt-5.5`
+- `ANTHROPIC_API_KEY` -> `anthropic/claude-opus-4-7`
+- Claude Code CLI -> `claude-cli/claude-opus-4-7`
+- Codex CLI -> `codex-cli/gpt-5.5`
+
+If none are available, setup still writes the default workspace and leaves the
+model unset. Install or log into Codex/Claude Code, or expose
+`OPENAI_API_KEY`/`ANTHROPIC_API_KEY`, then run setup again.
+
+## Model-Assisted Planner
+
+Crestodian always starts in deterministic mode. For fuzzy commands that the
+deterministic parser does not understand, local Crestodian can make one bounded
+planner turn through OpenClaw's normal runtime paths. It first uses the
+configured OpenClaw model. If no configured model is usable yet, it can fall
+back to local runtimes already present on the machine:
+
+- Claude Code CLI: `claude-cli/claude-opus-4-7`
+- Codex app-server harness: `openai/gpt-5.5` with `embeddedHarness.runtime: "codex"`
+- Codex CLI: `codex-cli/gpt-5.5`
+
+The model-assisted planner cannot mutate config directly. It must translate the
+request into one of Crestodian's typed commands, then the normal approval and
+audit rules apply. Crestodian prints the model it used and the interpreted
+command before it runs anything. Configless fallback planner turns are
+temporary, tool-disabled where the runtime supports it, and use a temporary
+workspace/session.
+
+Message-channel rescue mode does not use the model-assisted planner. Remote
+rescue stays deterministic so a broken or compromised normal agent path cannot
+be used as a config editor.
+
+## Switching to an agent
+
+Use a natural-language selector to leave Crestodian and open the normal TUI:
+
+```text
+talk to agent
+talk to work agent
+switch to main agent
+```
+
+`openclaw tui`, `openclaw chat`, and `openclaw terminal` still open the normal
+agent TUI directly. They do not start Crestodian.
+
+After switching into the normal TUI, use `/crestodian` to return to Crestodian.
+You can include a follow-up request:
+
+```text
+/crestodian
+/crestodian restart gateway
+```
+
+Agent switches inside the TUI leave a breadcrumb that `/crestodian` is available.
+
+## Message rescue mode
+
+Message rescue mode is the message-channel entrypoint for Crestodian. It is for
+the case where your normal agent is dead, but a trusted channel such as WhatsApp
+still receives commands.
+
+Supported text command:
+
+- `/crestodian <request>`
+
+Operator flow:
+
+```text
+You, in a trusted owner DM: /crestodian status
+OpenClaw: Crestodian rescue mode. Gateway reachable: no. Config valid: no.
+You: /crestodian restart gateway
+OpenClaw: Plan: restart the Gateway. Reply /crestodian yes to apply.
+You: /crestodian yes
+OpenClaw: Applied. Audit entry written.
+```
+
+Agent creation can also be queued from the local prompt or rescue mode:
+
+```text
+create agent work workspace ~/Projects/work model openai/gpt-5.5
+/crestodian create agent work workspace ~/Projects/work
+```
+
+Remote rescue mode is an admin surface. It must be treated like remote config
+repair, not like normal chat.
+
+Security contract for remote rescue:
+
+- Disabled when sandboxing is active. If an agent/session is sandboxed,
+  Crestodian must refuse remote rescue and explain that local CLI repair is
+  required.
+- Default effective state is `auto`: allow remote rescue only in trusted YOLO
+  operation, where the runtime already has unsandboxed local authority.
+- Require an explicit owner identity. Rescue must not accept wildcard sender
+  rules, open group policy, unauthenticated webhooks, or anonymous channels.
+- Owner DMs only by default. Group/channel rescue requires explicit opt-in and
+  should still route approval prompts to the owner DM.
+- Remote rescue cannot open the local TUI or switch into an interactive agent
+  session. Use local `openclaw` for agent handoff.
+- Persistent writes still require approval, even in rescue mode.
+- Audit every applied rescue operation, including channel, account, sender,
+  session key, operation, config hash before, and config hash after.
+- Never echo secrets. SecretRef inspection should report availability, not
+  values.
+- If the Gateway is alive, prefer Gateway typed operations. If the Gateway is
+  dead, use only the minimal local repair surface that does not depend on the
+  normal agent loop.
+
+Config shape:
+
+```jsonc
+{
+  "crestodian": {
+    "rescue": {
+      "enabled": "auto",
+      "ownerDmOnly": true,
+    },
+  },
+}
+```
+
+`enabled` should accept:
+
+- `"auto"`: default. Allow only when the effective runtime is YOLO and
+  sandboxing is off.
+- `false`: never allow message-channel rescue.
+- `true`: explicitly allow rescue when the owner/channel checks pass. This
+  still must not bypass the sandboxing denial.
+
+The default `"auto"` YOLO posture is:
+
+- sandbox mode resolves to `off`
+- `tools.exec.security` resolves to `full`
+- `tools.exec.ask` resolves to `off`
+
+Remote rescue is covered by the Docker lane:
+
+```bash
+pnpm test:docker:crestodian-rescue
+```
+
+Configless local planner fallback is covered by:
+
+```bash
+pnpm test:docker:crestodian-planner
+```
+
+An opt-in live channel command-surface smoke checks `/crestodian status` plus a
+persistent approval roundtrip through the rescue handler:
+
+```bash
+pnpm test:live:crestodian-rescue-channel
+```
+
+Fresh configless setup through Crestodian is covered by:
+
+```bash
+pnpm test:docker:crestodian-first-run
+```
+
+That lane starts with an empty state dir, routes bare `openclaw` to Crestodian,
+sets the default model, creates an additional agent, configures Discord through
+a plugin enablement plus token SecretRef, validates config, and checks the audit
+log. QA Lab also has a repo-backed scenario for the same Ring 0 flow:
+
+```bash
+pnpm openclaw qa suite --scenario crestodian-ring-zero-setup
+```
+
+## Related
+
+- [CLI reference](/cli)
+- [Doctor](/cli/doctor)
+- [TUI](/cli/tui)
+- [Sandbox](/cli/sandbox)
+- [Security](/cli/security)

docs/cli/cron.md

@@ -33,6 +33,11 @@ Note: `--session` supports `main`, `isolated`, `current`, and `session:<id>`.
 Use `current` to bind to the active session at creation time, or `session:<id>` for
 an explicit persistent session key.
 
+Note: `--session isolated` creates a fresh transcript/session id for each run.
+Safe preferences and explicit user-selected model/auth overrides can carry, but
+ambient conversation context does not: channel/group routing, send/queue policy,
+elevation, origin, and ACP runtime binding are reset for the new isolated run.
+
 Note: for one-shot CLI jobs, offset-less `--at` datetimes are treated as UTC unless you also pass
 `--tz <iana>`, which interprets that local wall-clock time in the given timezone.
 
@@ -59,17 +64,17 @@ model override with no explicit per-job fallback list no longer appends the
 agent primary as a hidden extra retry target.
 
 Note: isolated cron model precedence is Gmail-hook override first, then per-job
-`--model`, then any stored cron-session model override, then the normal
-agent/default selection.
+`--model`, then any user-selected stored cron-session model override, then the
+normal agent/default selection.
 
 Note: isolated cron fast mode follows the resolved live model selection. Model
 config `params.fastMode` applies by default, but a stored session `fastMode`
 override still wins over config.
 
 Note: if an isolated run throws `LiveSessionModelSwitchError`, cron persists the
-switched provider/model (and switched auth profile override when present) before
-retrying. The outer retry loop is bounded to 2 switch retries after the initial
-attempt, then aborts instead of looping forever.
+switched provider/model (and switched auth profile override when present) for
+the active run before retrying. The outer retry loop is bounded to 2 switch
+retries after the initial attempt, then aborts instead of looping forever.
 
 Note: failure notifications use `delivery.failureDestination` first, then
 global `cron.failureDestination`, and finally fall back to the job's primary
@@ -174,3 +179,8 @@ Failure-delivery note:
   delivery mode is `webhook`.
 - If you do not set any failure destination and the job already announces to a
   channel, failure notifications reuse that same announce target.
+
+## Related
+
+- [CLI reference](/cli)
+- [Scheduled tasks](/automation/cron-jobs)

docs/cli/daemon.md

@@ -55,3 +55,8 @@ Notes:
 ## Prefer
 
 Use [`openclaw gateway`](/cli/gateway) for current docs and examples.
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway runbook](/gateway)

docs/cli/dashboard.md

@@ -18,5 +18,12 @@ openclaw dashboard --no-open
 Notes:
 
 - `dashboard` resolves configured `gateway.auth.token` SecretRefs when possible.
+- `dashboard` follows `gateway.tls.enabled`: TLS-enabled gateways print/open
+  `https://` Control UI URLs and connect over `wss://`.
 - For SecretRef-managed tokens (resolved or unresolved), `dashboard` prints/copies/opens a non-tokenized URL to avoid exposing external secrets in terminal output, clipboard history, or browser-launch arguments.
 - If `gateway.auth.token` is SecretRef-managed but unresolved in this command path, the command prints a non-tokenized URL and explicit remediation guidance instead of embedding an invalid token placeholder.
+
+## Related
+
+- [CLI reference](/cli)
+- [Dashboard](/web/dashboard)

docs/cli/devices.md

@@ -66,6 +66,12 @@ request. Review the `Requested` vs `Approved` columns in `openclaw devices list`
 or use `openclaw devices approve --latest` to preview the exact upgrade before
 approving it.
 
+If the Gateway is explicitly configured with
+`gateway.nodes.pairing.autoApproveCidrs`, first-time `role: node` requests from
+matching client IPs can be approved before they appear in this list. That policy
+is disabled by default and never applies to operator/browser clients or upgrade
+requests.
+
 ```
 openclaw devices approve
 openclaw devices approve <requestId>
@@ -127,6 +133,8 @@ Pass `--token` or `--password` explicitly. Missing explicit credentials is an er
 
 - Token rotation returns a new token (sensitive). Treat it like a secret.
 - These commands require `operator.pairing` (or `operator.admin`) scope.
+- `gateway.nodes.pairing.autoApproveCidrs` is an opt-in Gateway policy for
+  fresh node device pairing only; it does not change CLI approval authority.
 - Token rotation stays inside the approved pairing role set and approved scope
   baseline for that device. A stray cached token entry does not grant a new
   rotate target.
@@ -178,3 +186,8 @@ Related:
 
 - [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
 - [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)
+
+## Related
+
+- [CLI reference](/cli)
+- [Nodes](/nodes)