build: prepare 2026.3.11 release

* docs(pi): update dashboard access instructions

* docs(i18n): refresh raspberry pi source hash

* docs: clarify Raspberry Pi dashboard access

* fix: clarify Raspberry Pi dashboard access (#43584) (thanks @neeravmakwana)

---------

Co-authored-by: Neerav Makwana <261249544+neeravmakwana@users.noreply.github.com>
Co-authored-by: Ayaan Zaidi <zaidi@uplause.io>

.detect-secrets.cfg

@@ -41,3 +41,5 @@ pattern = grep -q 'N[O]DE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bash
 pattern = env: \{ MISTRAL_API_K[E]Y: "sk-\.\.\." \},
 pattern = "ap[i]Key": "xxxxx",
 pattern = ap[i]Key: "A[I]za\.\.\.",
+# Sparkle appcast signatures are release metadata, not credentials.
+pattern = sparkle:edSignature="[A-Za-z0-9+/=]+"

.github/FUNDING.yml

@@ -1 +0,0 @@
-custom: ["https://github.com/sponsors/steipete"]

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -76,6 +76,37 @@ body:
       label: Install method
       description: How OpenClaw was installed or launched.
       placeholder: npm global / pnpm dev / docker / mac app
+  - type: input
+    id: model
+    attributes:
+      label: Model
+      description: Effective model under test.
+      placeholder: minimax/text-01 / openrouter/anthropic/claude-opus-4.1 / anthropic/claude-sonnet-4.5
+    validations:
+      required: true
+  - type: input
+    id: provider_chain
+    attributes:
+      label: Provider / routing chain
+      description: Effective request path through gateways, proxies, providers, or model routers.
+      placeholder: openclaw -> cloudflare-ai-gateway -> minimax
+    validations:
+      required: true
+  - type: input
+    id: config_location
+    attributes:
+      label: Config file / key location
+      description: Optional. Relevant config source or key path if this bug depends on overrides or custom provider setup. Redact secrets.
+      placeholder: ~/.openclaw/openclaw.json ; models.providers.cloudflare-ai-gateway.baseUrl ; ~/.openclaw/agents/<agentId>/agent/models.json
+  - type: textarea
+    id: provider_setup_details
+    attributes:
+      label: Additional provider/model setup details
+      description: Optional. Include redacted routing details, per-agent overrides, auth-profile interactions, env/config context, or anything else needed to explain the effective provider/model setup. Do not include API keys, tokens, or passwords.
+      placeholder: |
+        Default route is openclaw -> cloudflare-ai-gateway -> minimax.
+        Previous setup was openclaw -> cloudflare-ai-gateway -> openrouter -> minimax.
+        Relevant config lives in ~/.openclaw/openclaw.json under models.providers.minimax and models.providers.cloudflare-ai-gateway.
   - type: textarea
     id: logs
     attributes:

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

@@ -0,0 +1,18 @@
+name: openclaw-codeql-javascript-typescript
+
+paths:
+  - src
+  - extensions
+  - ui/src
+  - skills
+
+paths-ignore:
+  - apps
+  - dist
+  - docs
+  - "**/node_modules"
+  - "**/coverage"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.e2e.test.ts"
+  - "**/*.e2e.test.tsx"

.github/pull_request_template.md

@@ -87,6 +87,13 @@ What you personally verified (not just CI), and how:
 - Edge cases checked:
 - What you did **not** verify:
 
+## Review Conversations
+
+- [ ] I replied to or resolved every bot review conversation I addressed in this PR.
+- [ ] I left unresolved only the conversations that still need reviewer or maintainer judgment.
+
+If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.
+
 ## Compatibility / Migration
 
 - Backward compatible? (`Yes/No`)

.github/workflows/auto-response.yml

@@ -51,6 +51,7 @@ jobs:
               },
               {
                 label: "r: no-ci-pr",
+                close: true,
                 message:
                   "Please don't make PRs for test failures on main.\n\n" +
                   "The team is aware of those and will handle them directly on the codebase, not only fixing the tests but also investigating what the root cause is. Having to sift through test-fix-PRs (including some that have been out of date for weeks...) on top of that doesn't help. There are already way too many PRs for humans to manage; please don't make the flood worse.\n\n" +
@@ -261,6 +262,8 @@ jobs:
             };
 
             const triggerLabel = "trigger-response";
+            const activePrLimitLabel = "r: too-many-prs";
+            const activePrLimitOverrideLabel = "r: too-many-prs-override";
             const target = context.payload.issue ?? context.payload.pull_request;
             if (!target) {
               return;
@@ -390,6 +393,7 @@ jobs:
             }
 
             const invalidLabel = "invalid";
+            const spamLabel = "r: spam";
             const dirtyLabel = "dirty";
             const noisyPrMessage =
               "Closing this PR because it looks dirty (too many unrelated or unexpected changes). This usually happens when a branch picks up unrelated commits or a merge went sideways. Please recreate the PR from a clean branch.";
@@ -426,6 +430,21 @@ jobs:
                 });
                 return;
               }
+              if (labelSet.has(spamLabel)) {
+                await github.rest.issues.update({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pullRequest.number,
+                  state: "closed",
+                });
+                await github.rest.issues.lock({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pullRequest.number,
+                  lock_reason: "spam",
+                });
+                return;
+              }
               if (labelSet.has(invalidLabel)) {
                 await github.rest.issues.update({
                   owner: context.repo.owner,
@@ -437,6 +456,23 @@ jobs:
               }
             }
 
+            if (issue && labelSet.has(spamLabel)) {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                state: "closed",
+                state_reason: "not_planned",
+              });
+              await github.rest.issues.lock({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                lock_reason: "spam",
+              });
+              return;
+            }
+
             if (issue && labelSet.has(invalidLabel)) {
               await github.rest.issues.update({
                 owner: context.repo.owner,
@@ -448,6 +484,10 @@ jobs:
               return;
             }
 
+            if (pullRequest && labelSet.has(activePrLimitOverrideLabel)) {
+              labelSet.delete(activePrLimitLabel);
+            }
+
             const rule = rules.find((item) => labelSet.has(item.label));
             if (!rule) {
               return;

.github/workflows/ci.yml

@@ -267,6 +267,12 @@ jobs:
         with:
           submodules: false
 
+      - name: Ensure secrets base commit
+        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: Setup Node environment
         uses: ./.github/actions/setup-node-env
         with:
@@ -296,34 +302,6 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install pre-commit
 
-      - name: Detect secrets
-        run: |
-          set -euo pipefail
-
-          if [ "${{ github.event_name }}" = "push" ]; then
-            echo "Running full detect-secrets scan on push."
-            pre-commit run --all-files detect-secrets
-            exit 0
-          fi
-
-          BASE="${{ github.event.pull_request.base.sha }}"
-          changed_files=()
-          if git rev-parse --verify "$BASE^{commit}" >/dev/null 2>&1; then
-            while IFS= read -r path; do
-              [ -n "$path" ] || continue
-              [ -f "$path" ] || continue
-              changed_files+=("$path")
-            done < <(git diff --name-only --diff-filter=ACMR "$BASE" HEAD)
-          fi
-
-          if [ "${#changed_files[@]}" -gt 0 ]; then
-            echo "Running detect-secrets on ${#changed_files[@]} changed file(s)."
-            pre-commit run detect-secrets --files "${changed_files[@]}"
-          else
-            echo "Falling back to full detect-secrets scan."
-            pre-commit run --all-files detect-secrets
-          fi
-
       - name: Detect committed private keys
         run: pre-commit run --all-files detect-private-key
 

.github/workflows/codeql.yml

@@ -28,6 +28,7 @@ jobs:
             needs_swift_tools: false
             needs_manual_build: false
             needs_autobuild: false
+            config_file: ./.github/codeql/codeql-javascript-typescript.yml
           - language: actions
             runs_on: blacksmith-16vcpu-ubuntu-2404
             needs_node: false
@@ -36,6 +37,7 @@ jobs:
             needs_swift_tools: false
             needs_manual_build: false
             needs_autobuild: false
+            config_file: ""
           - language: python
             runs_on: blacksmith-16vcpu-ubuntu-2404
             needs_node: false
@@ -44,6 +46,7 @@ jobs:
             needs_swift_tools: false
             needs_manual_build: false
             needs_autobuild: false
+            config_file: ""
           - language: java-kotlin
             runs_on: blacksmith-16vcpu-ubuntu-2404
             needs_node: false
@@ -52,6 +55,7 @@ jobs:
             needs_swift_tools: false
             needs_manual_build: true
             needs_autobuild: false
+            config_file: ""
           - language: swift
             runs_on: macos-latest
             needs_node: false
@@ -60,6 +64,7 @@ jobs:
             needs_swift_tools: true
             needs_manual_build: true
             needs_autobuild: false
+            config_file: ""
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -88,13 +93,18 @@ jobs:
 
       - name: Setup Swift build tools
         if: matrix.needs_swift_tools
-        run: brew install xcodegen swiftlint swiftformat
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.app
+          xcodebuild -version
+          brew install xcodegen swiftlint swiftformat
+          swift --version
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v4
         with:
           languages: ${{ matrix.language }}
           queries: security-and-quality
+          config-file: ${{ matrix.config_file || '' }}
 
       - name: Autobuild
         if: matrix.needs_autobuild

.github/workflows/install-smoke.yml

@@ -43,6 +43,8 @@ jobs:
       - name: Set up Docker Builder
         uses: useblacksmith/setup-docker-builder@v1
 
+      # Blacksmith can fall back to the local docker driver, which rejects gha
+      # cache export/import. Keep smoke builds driver-agnostic.
       - name: Build root Dockerfile smoke image
         uses: useblacksmith/build-push-action@v2
         with:
@@ -52,8 +54,6 @@ jobs:
           load: true
           push: false
           provenance: false
-          cache-from: type=gha,scope=install-smoke-root-dockerfile
-          cache-to: type=gha,mode=max,scope=install-smoke-root-dockerfile
 
       - name: Run root Dockerfile CLI smoke
         run: |
@@ -73,8 +73,6 @@ jobs:
           load: true
           push: false
           provenance: false
-          cache-from: type=gha,scope=install-smoke-root-dockerfile-ext
-          cache-to: type=gha,mode=max,scope=install-smoke-root-dockerfile-ext
 
       - name: Smoke test Dockerfile with extension build arg
         run: |
@@ -89,8 +87,6 @@ jobs:
           load: true
           push: false
           provenance: false
-          cache-from: type=gha,scope=install-smoke-installer-root
-          cache-to: type=gha,mode=max,scope=install-smoke-installer-root
 
       - name: Build installer non-root image
         if: github.event_name != 'pull_request'
@@ -102,8 +98,6 @@ jobs:
           load: true
           push: false
           provenance: false
-          cache-from: type=gha,scope=install-smoke-installer-nonroot
-          cache-to: type=gha,mode=max,scope=install-smoke-installer-nonroot
 
       - name: Run installer docker tests
         env:

.github/workflows/labeler.yml

@@ -213,6 +213,7 @@ jobs:
             }
 
             const activePrLimitLabel = "r: too-many-prs";
+            const activePrLimitOverrideLabel = "r: too-many-prs-override";
             const activePrLimit = 10;
             const labelColor = "B60205";
             const labelDescription = `Author has more than ${activePrLimit} active PRs in this repo`;
@@ -221,12 +222,37 @@ jobs:
               return;
             }
 
+            const currentLabels = await github.paginate(github.rest.issues.listLabelsOnIssue, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pullRequest.number,
+              per_page: 100,
+            });
+
             const labelNames = new Set(
-              (pullRequest.labels ?? [])
+              currentLabels
                 .map((label) => (typeof label === "string" ? label : label?.name))
                 .filter((name) => typeof name === "string"),
             );
 
+            if (labelNames.has(activePrLimitOverrideLabel)) {
+              if (labelNames.has(activePrLimitLabel)) {
+                try {
+                  await github.rest.issues.removeLabel({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: pullRequest.number,
+                    name: activePrLimitLabel,
+                  });
+                } catch (error) {
+                  if (error?.status !== 404) {
+                    throw error;
+                  }
+                }
+              }
+              return;
+            }
+
             const ensureLabelExists = async () => {
               try {
                 await github.rest.issues.getLabel({

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

@@ -0,0 +1,79 @@
+name: OpenClaw NPM Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: openclaw-npm-release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  NODE_VERSION: "22.x"
+  PNPM_VERSION: "10.23.0"
+
+jobs:
+  publish_openclaw_npm:
+    # npm trusted publishing + provenance requires a GitHub-hosted runner.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+          install-bun: "false"
+          use-sticky-disk: "false"
+
+      - name: Validate release tag and package metadata
+        env:
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          RELEASE_MAIN_REF: origin/main
+        run: |
+          set -euo pipefail
+          # Fetch the full main ref so merge-base ancestry checks keep working
+          # for older tagged commits that are still contained in main.
+          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+          pnpm release:openclaw:npm:check
+
+      - name: Ensure version is not already published
+        run: |
+          set -euo pipefail
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
+          if npm view "openclaw@${PACKAGE_VERSION}" version >/dev/null 2>&1; then
+            echo "openclaw@${PACKAGE_VERSION} is already published on npm."
+            exit 1
+          fi
+
+          echo "Publishing openclaw@${PACKAGE_VERSION}"
+
+      - name: Check
+        run: pnpm check
+
+      - name: Build
+        run: pnpm build
+
+      - name: Verify release contents
+        run: pnpm release:check
+
+      - name: Publish
+        run: |
+          set -euo pipefail
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
+          if [[ "$PACKAGE_VERSION" == *-beta.* ]]; then
+            npm publish --access public --tag beta --provenance
+          else
+            npm publish --access public --provenance
+          fi

.gitignore

@@ -81,6 +81,7 @@ apps/ios/*.mobileprovision
 # Local untracked files
 .local/
 docs/.local/
+tmp/
 IDENTITY.md
 USER.md
 .tgz
@@ -121,3 +122,4 @@ dist/protocol.schema.json
 
 # Synthing
 **/.stfolder/
+.dev-state

.pi/prompts/reviewpr.md

@@ -9,7 +9,19 @@ Input
   - If ambiguous: ask.
 
 Do (review-only)
-Goal: produce a thorough review and a clear recommendation (READY for /landpr vs NEEDS WORK). Do NOT merge, do NOT push, do NOT make changes in the repo as part of this command.
+Goal: produce a thorough review and a clear recommendation (READY FOR /landpr vs NEEDS WORK vs INVALID CLAIM). Do NOT merge, do NOT push, do NOT make changes in the repo as part of this command.
+
+0. Truthfulness + reality gate (required for bug-fix claims)
+   - Do not trust the issue text or PR summary by default; verify in code and evidence.
+   - If the PR claims to fix a bug linked to an issue, confirm the bug exists now (repro steps, logs, failing test, or clear code-path proof).
+   - Prove root cause with exact location (`path/file.ts:line` + explanation of why behavior is wrong).
+   - Verify fix targets the same code path as the root cause.
+   - Require a regression test when feasible (fails before fix, passes after fix). If not feasible, require explicit justification + manual verification evidence.
+   - Hallucination/BS red flags (treat as BLOCKER until disproven):
+     - claimed behavior not present in repo,
+     - issue/PR says "fixes #..." but changed files do not touch implicated path,
+     - only docs/comments changed for a runtime bug claim,
+     - vague AI-generated rationale without concrete evidence.
 
 1. Identify PR meta + context
 
@@ -56,6 +68,7 @@ Goal: produce a thorough review and a clear recommendation (READY for /landpr vs
    - Any deprecations, docs, types, or lint rules we should adjust?
 
 8. Key questions to answer explicitly
+   - Is the core claim substantiated by evidence, or is it likely invalid/hallucinated?
    - Can we fix everything ourselves in a follow-up, or does the contributor need to update this PR?
    - Any blocking concerns (must-fix before merge)?
    - Is this PR ready to land, or does it need work?
@@ -65,18 +78,32 @@ Goal: produce a thorough review and a clear recommendation (READY for /landpr vs
 
 A) TL;DR recommendation
 
-- One of: READY FOR /landpr | NEEDS WORK | NEEDS DISCUSSION
+- One of: READY FOR /landpr | NEEDS WORK | INVALID CLAIM (issue/bug not substantiated) | NEEDS DISCUSSION
 - 1–3 sentence rationale.
 
-B) What changed
+B) Claim verification matrix (required)
+
+- Fill this table:
+
+  | Field                                           | Evidence |
+  | ----------------------------------------------- | -------- |
+  | Claimed problem                                 | ...      |
+  | Evidence observed (repro/log/test/code)         | ...      |
+  | Root cause location (`path:line`)               | ...      |
+  | Why this fix addresses that root cause          | ...      |
+  | Regression coverage (test name or manual proof) | ...      |
+
+- If any row is missing/weak, default to `NEEDS WORK` or `INVALID CLAIM`.
+
+C) What changed
 
 - Brief bullet summary of the diff/behavioral changes.
 
-C) What's good
+D) What's good
 
 - Bullets: correctness, simplicity, tests, docs, ergonomics, etc.
 
-D) Concerns / questions (actionable)
+E) Concerns / questions (actionable)
 
 - Numbered list.
 - Mark each item as:
@@ -84,17 +111,19 @@ D) Concerns / questions (actionable)
   - IMPORTANT (should fix before merge)
   - NIT (optional)
 - For each: point to the file/area and propose a concrete fix or alternative.
+- If evidence for the core bug claim is missing, add a `BLOCKER` explicitly.
 
-E) Tests
+F) Tests
 
 - What exists.
 - What's missing (specific scenarios).
+- State clearly whether there is a regression test for the claimed bug.
 
-F) Follow-ups (optional)
+G) Follow-ups (optional)
 
 - Non-blocking refactors/tickets to open later.
 
-G) Suggested PR comment (optional)
+H) Suggested PR comment (optional)
 
 - Offer: "Want me to draft a PR comment to the author?"
 - If yes, provide a ready-to-paste comment summarizing the above, with clear asks.

.pre-commit-config.yaml

@@ -66,9 +66,13 @@ repos:
           - --exclude-lines
           - 'env: \{ MISTRAL_API_K[E]Y: "sk-\.\.\." \},'
           - --exclude-lines
-          - '"ap[i]Key": "xxxxx",'
+          - '"ap[i]Key": "xxxxx"(,)?'
           - --exclude-lines
           - 'ap[i]Key: "A[I]za\.\.\.",'
+          - --exclude-lines
+          - '"ap[i]Key": "(resolved|normalized|legacy)-key"(,)?'
+          - --exclude-lines
+          - 'sparkle:edSignature="[A-Za-z0-9+/=]+"'
   # Shell script linting
   - repo: https://github.com/koalaman/shellcheck-precommit
     rev: v0.11.0

.secrets.baseline

@@ -151,8 +151,10 @@
         "export CUSTOM_API_K[E]Y=\"your-key\"",
         "grep -q 'N[O]DE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc \\|\\| cat >> ~/.bashrc <<'EOF'",
         "env: \\{ MISTRAL_API_K[E]Y: \"sk-\\.\\.\\.\" \\},",
-        "\"ap[i]Key\": \"xxxxx\",",
-        "ap[i]Key: \"A[I]za\\.\\.\\.\","
+        "\"ap[i]Key\": \"xxxxx\"(,)?",
+        "ap[i]Key: \"A[I]za\\.\\.\\.\",",
+        "\"ap[i]Key\": \"(resolved|normalized|legacy)-key\"(,)?",
+        "sparkle:edSignature=\"[A-Za-z0-9+/=]+\""
       ]
     },
     {
@@ -179,29 +181,6 @@
         "line_number": 15
       }
     ],
-    "appcast.xml": [
-      {
-        "type": "Base64 High Entropy String",
-        "filename": "appcast.xml",
-        "hashed_secret": "7afea670e53d801f1f881c99c40aa177e3395bfa",
-        "is_verified": false,
-        "line_number": 365
-      },
-      {
-        "type": "Base64 High Entropy String",
-        "filename": "appcast.xml",
-        "hashed_secret": "6e1ba26139ac4e73427e68a7eec2abf96bcf1fd4",
-        "is_verified": false,
-        "line_number": 584
-      },
-      {
-        "type": "Base64 High Entropy String",
-        "filename": "appcast.xml",
-        "hashed_secret": "c0baa9660a8d3b11874c63a535d8369f4a8fa8fa",
-        "is_verified": false,
-        "line_number": 723
-      }
-    ],
     "apps/android/app/src/test/java/ai/openclaw/android/node/AppUpdateHandlerTest.kt": [
       {
         "type": "Hex High Entropy String",
@@ -226,7 +205,7 @@
         "filename": "apps/macos/Sources/OpenClawProtocol/GatewayModels.swift",
         "hashed_secret": "7990585255d25249fb1e6eac3d2bd6c37429b2cd",
         "is_verified": false,
-        "line_number": 1749
+        "line_number": 1859
       }
     ],
     "apps/macos/Tests/OpenClawIPCTests/AnthropicAuthResolverTests.swift": [
@@ -251,7 +230,7 @@
         "filename": "apps/macos/Tests/OpenClawIPCTests/GatewayEndpointStoreTests.swift",
         "hashed_secret": "19dad5cecb110281417d1db56b60e1b006d55bb4",
         "is_verified": false,
-        "line_number": 66
+        "line_number": 81
       }
     ],
     "apps/macos/Tests/OpenClawIPCTests/GatewayLaunchAgentManagerTests.swift": [
@@ -287,7 +266,7 @@
         "filename": "apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift",
         "hashed_secret": "7990585255d25249fb1e6eac3d2bd6c37429b2cd",
         "is_verified": false,
-        "line_number": 1749
+        "line_number": 1859
       }
     ],
     "docs/.i18n/zh-CN.tm.jsonl": [
@@ -9619,14 +9598,14 @@
         "filename": "docs/channels/feishu.md",
         "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3",
         "is_verified": false,
-        "line_number": 189
+        "line_number": 187
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/channels/feishu.md",
         "hashed_secret": "186154712b2d5f6791d85b9a0987b98fa231779c",
         "is_verified": false,
-        "line_number": 501
+        "line_number": 499
       }
     ],
     "docs/channels/irc.md": [
@@ -9795,63 +9774,63 @@
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "1188d5a8ed7edcff5144a9472af960243eacf12e",
         "is_verified": false,
-        "line_number": 1612
+        "line_number": 1614
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "bde4db9b4c3be4049adc3b9a69851d7c35119770",
         "is_verified": false,
-        "line_number": 1628
+        "line_number": 1630
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "7f8aaf142ce0552c260f2e546dda43ddd7c9aef3",
         "is_verified": false,
-        "line_number": 1813
+        "line_number": 1817
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "22af290a1a3d5e941193a41a3d3a9e4ca8da5e27",
         "is_verified": false,
-        "line_number": 1986
+        "line_number": 1990
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "ec3810e10fb78db55ce38b9c18d1c3eb1db739e0",
         "is_verified": false,
-        "line_number": 2042
+        "line_number": 2046
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "c1e6ee547fd492df1441ac492e8bb294974712bd",
         "is_verified": false,
-        "line_number": 2274
+        "line_number": 2278
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "45d676e7c6ab44cf4b8fa366ef2d8fccd3e6d6e6",
         "is_verified": false,
-        "line_number": 2402
+        "line_number": 2408
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "a219d7693c25cd2d93313512e200ff3eb374d281",
         "is_verified": false,
-        "line_number": 2655
+        "line_number": 2661
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/gateway/configuration-reference.md",
         "hashed_secret": "b6f56e5e92078ed7c078c46fbfeedcbe5719bc25",
         "is_verified": false,
-        "line_number": 2657
+        "line_number": 2663
       }
     ],
     "docs/gateway/configuration.md": [
@@ -9972,7 +9951,7 @@
         "filename": "docs/perplexity.md",
         "hashed_secret": "6b26c117c66a0c030e239eef595c1e18865132a8",
         "is_verified": false,
-        "line_number": 29
+        "line_number": 43
       }
     ],
     "docs/plugins/voice-call.md": [
@@ -10198,21 +10177,21 @@
         "filename": "docs/tools/web.md",
         "hashed_secret": "6b26c117c66a0c030e239eef595c1e18865132a8",
         "is_verified": false,
-        "line_number": 90
+        "line_number": 135
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/tools/web.md",
         "hashed_secret": "491d458f895b9213facb2ee9375b1b044eaea3ac",
         "is_verified": false,
-        "line_number": 179
+        "line_number": 228
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/tools/web.md",
         "hashed_secret": "674397e2c0c2faaa85961c708d2a96a7cc7af217",
         "is_verified": false,
-        "line_number": 277
+        "line_number": 332
       }
     ],
     "docs/tts.md": [
@@ -10255,14 +10234,14 @@
         "filename": "docs/zh-CN/channels/feishu.md",
         "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3",
         "is_verified": false,
-        "line_number": 195
+        "line_number": 191
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/zh-CN/channels/feishu.md",
         "hashed_secret": "186154712b2d5f6791d85b9a0987b98fa231779c",
         "is_verified": false,
-        "line_number": 509
+        "line_number": 505
       }
     ],
     "docs/zh-CN/channels/line.md": [
@@ -11481,7 +11460,7 @@
         "filename": "src/agents/models-config.e2e-harness.ts",
         "hashed_secret": "7cf31e8b6cda49f70c31f1f25af05d46f924142d",
         "is_verified": false,
-        "line_number": 130
+        "line_number": 157
       }
     ],
     "src/agents/models-config.fills-missing-provider-apikey-from-env-var.e2e.test.ts": [
@@ -11515,14 +11494,14 @@
         "filename": "src/agents/models-config.providers.nvidia.test.ts",
         "hashed_secret": "3acfb2c2b433c0ea7ff107e33df91b18e52f960f",
         "is_verified": false,
-        "line_number": 13
+        "line_number": 14
       },
       {
         "type": "Secret Keyword",
         "filename": "src/agents/models-config.providers.nvidia.test.ts",
         "hashed_secret": "be1a7be9d4d5af417882b267f4db6dddc08507bd",
         "is_verified": false,
-        "line_number": 22
+        "line_number": 23
       }
     ],
     "src/agents/models-config.providers.ollama.e2e.test.ts": [
@@ -11583,7 +11562,7 @@
         "filename": "src/agents/pi-embedded-runner/model.ts",
         "hashed_secret": "e774aaeac31c6272107ba89080295e277050fa7c",
         "is_verified": false,
-        "line_number": 272
+        "line_number": 279
       }
     ],
     "src/agents/pi-embedded-runner/run.overflow-compaction.mocks.shared.ts": [
@@ -11680,7 +11659,7 @@
         "filename": "src/agents/tools/web-search.ts",
         "hashed_secret": "dfba7aade0868074c2861c98e2a9a92f3178a51b",
         "is_verified": false,
-        "line_number": 254
+        "line_number": 291
       }
     ],
     "src/agents/tools/web-tools.enabled-defaults.e2e.test.ts": [
@@ -11746,7 +11725,7 @@
         "filename": "src/auto-reply/status.test.ts",
         "hashed_secret": "3acfb2c2b433c0ea7ff107e33df91b18e52f960f",
         "is_verified": false,
-        "line_number": 36
+        "line_number": 37
       }
     ],
     "src/browser/bridge-server.auth.test.ts": [
@@ -11764,14 +11743,14 @@
         "filename": "src/browser/browser-utils.test.ts",
         "hashed_secret": "4e126c049580d66ca1549fa534d95a7263f27f46",
         "is_verified": false,
-        "line_number": 43
+        "line_number": 47
       },
       {
         "type": "Basic Auth Credentials",
         "filename": "src/browser/browser-utils.test.ts",
         "hashed_secret": "9d4e1e23bd5b727046a9e3b4b7db57bd8d6ee684",
         "is_verified": false,
-        "line_number": 164
+        "line_number": 171
       }
     ],
     "src/browser/cdp.test.ts": [
@@ -11780,7 +11759,7 @@
         "filename": "src/browser/cdp.test.ts",
         "hashed_secret": "9d4e1e23bd5b727046a9e3b4b7db57bd8d6ee684",
         "is_verified": false,
-        "line_number": 243
+        "line_number": 318
       }
     ],
     "src/channels/plugins/plugins-channel.test.ts": [
@@ -12100,21 +12079,21 @@
         "filename": "src/config/config.env-vars.test.ts",
         "hashed_secret": "a24ef9c1a27cac44823571ceef2e8262718eee36",
         "is_verified": false,
-        "line_number": 13
+        "line_number": 17
       },
       {
         "type": "Secret Keyword",
         "filename": "src/config/config.env-vars.test.ts",
         "hashed_secret": "29d5f92e9ee44d4854d6dfaeefc3dc27d779fdf3",
         "is_verified": false,
-        "line_number": 19
+        "line_number": 23
       },
       {
         "type": "Secret Keyword",
         "filename": "src/config/config.env-vars.test.ts",
         "hashed_secret": "1672b6a1e7956c6a70f45d699aa42a351b1f8b80",
         "is_verified": false,
-        "line_number": 27
+        "line_number": 31
       }
     ],
     "src/config/config.irc.test.ts": [
@@ -12335,14 +12314,14 @@
         "filename": "src/config/schema.help.ts",
         "hashed_secret": "9f4cda226d3868676ac7f86f59e4190eb94bd208",
         "is_verified": false,
-        "line_number": 649
+        "line_number": 653
       },
       {
         "type": "Secret Keyword",
         "filename": "src/config/schema.help.ts",
         "hashed_secret": "01822c8bbf6a8b136944b14182cb885100ec2eae",
         "is_verified": false,
-        "line_number": 680
+        "line_number": 686
       }
     ],
     "src/config/schema.irc.ts": [
@@ -12381,14 +12360,14 @@
         "filename": "src/config/schema.labels.ts",
         "hashed_secret": "e73c9fcad85cd4eecc74181ec4bdb31064d68439",
         "is_verified": false,
-        "line_number": 216
+        "line_number": 217
       },
       {
         "type": "Secret Keyword",
         "filename": "src/config/schema.labels.ts",
         "hashed_secret": "2eda7cd978f39eebec3bf03e4410a40e14167fff",
         "is_verified": false,
-        "line_number": 324
+        "line_number": 326
       }
     ],
     "src/config/slack-http-config.test.ts": [
@@ -12932,14 +12911,14 @@
         "filename": "src/telegram/monitor.test.ts",
         "hashed_secret": "e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4",
         "is_verified": false,
-        "line_number": 450
+        "line_number": 497
       },
       {
         "type": "Secret Keyword",
         "filename": "src/telegram/monitor.test.ts",
         "hashed_secret": "5934c4d4a4fa5d66ddb3d3fc0bba84996c17a5b7",
         "is_verified": false,
-        "line_number": 641
+        "line_number": 688
       }
     ],
     "src/telegram/webhook.test.ts": [
@@ -13034,5 +13013,5 @@
       }
     ]
   },
-  "generated_at": "2026-03-08T05:05:36Z"
+  "generated_at": "2026-03-10T03:11:06Z"
 }

.swiftformat

@@ -48,4 +48,4 @@
 --allman false
 
 # Exclusions
---exclude .build,.swiftpm,DerivedData,node_modules,dist,coverage,xcuserdata,Peekaboo,Swabble,apps/android,apps/ios,apps/shared,apps/macos/Sources/MoltbotProtocol
+--exclude .build,.swiftpm,DerivedData,node_modules,dist,coverage,xcuserdata,Peekaboo,Swabble,apps/android,apps/ios,apps/shared,apps/macos/Sources/OpenClawProtocol,apps/macos/Sources/OpenClaw/HostEnvSecurityPolicy.generated.swift

.swiftlint.yml

@@ -18,7 +18,9 @@ excluded:
   - coverage
   - "*.playground"
   # Generated (protocol-gen-swift.ts)
-  - apps/macos/Sources/MoltbotProtocol/GatewayModels.swift
+  - apps/macos/Sources/OpenClawProtocol/GatewayModels.swift
+  # Generated (generate-host-env-security-policy-swift.mjs)
+  - apps/macos/Sources/OpenClaw/HostEnvSecurityPolicy.generated.swift
 
 analyzer_rules:
   - unused_declaration

AGENTS.md

@@ -6,9 +6,40 @@
 - GitHub comment footgun: never use `gh issue/pr comment -b "..."` when body contains backticks or shell chars. Always use single-quoted heredoc (`-F - <<'EOF'`) so no command substitution/escaping corruption.
 - GitHub linking footgun: don’t wrap issue/PR refs like `#24643` in backticks when you want auto-linking. Use plain `#24643` (optionally add full URL).
 - PR landing comments: always make commit SHAs clickable with full commit links (both landed SHA + source SHA when present).
+- PR review conversations: if a bot leaves review conversations on your PR, address them and resolve those conversations yourself once fixed. Leave a conversation unresolved only when reviewer or maintainer judgment is still needed; do not leave bot-conversation cleanup to maintainers.
 - GitHub searching footgun: don't limit yourself to the first 500 issues or PRs when wanting to search all. Unless you're supposed to look at the most recent, keep going until you've reached the last page in the search
 - Security advisory analysis: before triage/severity decisions, read `SECURITY.md` to align with OpenClaw's trust model and design boundaries.
 
+## Auto-close labels (issues and PRs)
+
+- If an issue/PR matches one of the reasons below, apply the label and let `.github/workflows/auto-response.yml` handle comment/close/lock.
+- Do not manually close + manually comment for these reasons.
+- Why: keeps wording consistent, preserves automation behavior (`state_reason`, locking), and keeps triage/reporting searchable by label.
+- `r:*` labels can be used on both issues and PRs.
+
+- `r: skill`: close with guidance to publish skills on Clawhub.
+- `r: support`: close with redirect to Discord support + stuck FAQ.
+- `r: no-ci-pr`: close test-fix-only PRs for failing `main` CI and post the standard explanation.
+- `r: too-many-prs`: close when author exceeds active PR limit.
+- `r: testflight`: close requests asking for TestFlight access/builds. OpenClaw does not provide TestFlight distribution yet, so use the standard response (“Not available, build from source.”) instead of ad-hoc replies.
+- `r: third-party-extension`: close with guidance to ship as third-party plugin.
+- `r: moltbook`: close + lock as off-topic (not affiliated).
+- `r: spam`: close + lock as spam (`lock_reason: spam`).
+- `invalid`: close invalid items (issues are closed as `not_planned`; PRs are closed).
+- `dirty`: close PRs with too many unrelated/unexpected changes (PR-only label).
+
+## PR truthfulness and bug-fix validation
+
+- Never merge a bug-fix PR based only on issue text, PR text, or AI rationale.
+- Before `/landpr`, run `/reviewpr` and require explicit evidence for bug-fix claims.
+- Minimum merge gate for bug-fix PRs:
+  1. symptom evidence (repro/log/failing test),
+  2. verified root cause in code with file/line,
+  3. fix touches the implicated code path,
+  4. regression test (fail before/pass after) when feasible; if not feasible, include manual verification proof and why no test was added.
+- If claim is unsubstantiated or likely hallucinated/BS: do not merge. Request evidence/changes, or close with `invalid` when appropriate.
+- If linked issue appears wrong/outdated, correct triage first; do not merge speculative fixes.
+
 ## Project Structure & Module Organization
 
 - Source code: `src/` (CLI wiring in `src/cli`, commands in `src/commands`, web provider in `src/provider-web.ts`, infra in `src/infra`, media pipeline in `src/media`).
@@ -28,6 +59,7 @@
 - Docs are hosted on Mintlify (docs.openclaw.ai).
 - Internal doc links in `docs/**/*.md`: root-relative, no `.md`/`.mdx` (example: `[Config](/configuration)`).
 - When working with documentation, read the mintlify skill.
+- For docs, UI copy, and picker lists, order services/providers alphabetically unless the section is explicitly describing runtime behavior (for example auto-detection or execution order).
 - Section cross-references: use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`).
 - Doc headings and anchors: avoid em dashes and apostrophes in headings because they break Mintlify anchor links.
 - When Peter asks for links, reply with full `https://docs.openclaw.ai/...` URLs (not root-relative).
@@ -113,6 +145,7 @@
 
 **Full maintainer PR workflow (optional):** If you want the repo's end-to-end maintainer workflow (triage order, quality bar, rebase rules, commit/changelog conventions, co-contributor policy, and the `review-pr` > `prepare-pr` > `merge-pr` pipeline), see `.agents/skills/PR_WORKFLOW.md`. Maintainers may use other workflows; when a maintainer specifies a workflow, follow that. If no workflow is specified, default to PR_WORKFLOW.
 
+- `/landpr` lives in the global Codex prompts (`~/.codex/prompts/landpr.md`); when landing or merging any PR, always follow that `/landpr` process.
 - Create commits with `scripts/committer "<msg>" <file...>`; avoid manual `git add`/`git commit` so staging stays scoped.
 - Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`).
 - Group related changes; avoid bundling unrelated refactors.

CHANGELOG.md

@@ -2,19 +2,208 @@
 
 Docs: https://docs.openclaw.ai
 
+## Unreleased
+
+### Changes
+
+### Fixes
+
+## 2026.3.11
+
+### Security
+
+- Gateway/WebSocket: enforce browser origin validation for all browser-originated connections regardless of whether proxy headers are present, closing a cross-site WebSocket hijacking path in `trusted-proxy` mode that could grant untrusted origins `operator.admin` access. (GHSA-5wcw-8jjv-m286)
+
+### Changes
+
+- OpenRouter/models: add temporary Hunter Alpha and Healer Alpha entries to the built-in catalog so OpenRouter users can try the new free stealth models during their roughly one-week availability window. (#43642) Thanks @ping-Toven.
+- iOS/Home canvas: add a bundled welcome screen with a live agent overview that refreshes on connect, reconnect, and foreground return, and move the compact connection pill off the top-left canvas overlay. (#42456) Thanks @ngutman.
+- iOS/Home canvas: replace floating controls with a docked toolbar, make the bundled home scaffold adapt to smaller phones, and open chat in the resolved main session instead of a synthetic `ios` session. (#42456) Thanks @ngutman.
+- macOS/chat UI: add a chat model picker, persist explicit thinking-level selections across relaunch, and harden provider-aware session model sync for the shared chat composer. (#42314) Thanks @ImLukeF.
+- Onboarding/Ollama: add first-class Ollama setup with Local or Cloud + Local modes, browser-based cloud sign-in, curated model suggestions, and cloud-model handling that skips unnecessary local pulls. (#41529) Thanks @BruceMacD.
+- OpenCode/onboarding: add new OpenCode Go provider, treat Zen and Go as one OpenCode setup in the wizard/docs while keeping the runtime providers split, store one shared OpenCode key for both profiles, and stop overriding the built-in `opencode-go` catalog routing. (#42313) Thanks @ImLukeF and @vincentkoc.
+- Memory: add opt-in multimodal image and audio indexing for `memorySearch.extraPaths` with Gemini `gemini-embedding-2-preview`, strict fallback gating, and scope-based reindexing. (#43460) Thanks @gumadeiras.
+- Memory/Gemini: add `gemini-embedding-2-preview` memory-search support with configurable output dimensions and automatic reindexing when the configured dimensions change. (#42501) Thanks @BillChirico and @gumadeiras.
+- macOS/onboarding: detect when remote gateways need a shared auth token, explain where to find it on the gateway host, and clarify when a successful check used paired-device auth instead. (#43100) Thanks @ngutman.
+- Discord/auto threads: add `autoArchiveDuration` channel config for auto-created threads so Discord thread archiving can stay at 1 hour, 1 day, 3 days, or 1 week instead of always using the 1-hour default. (#35065) Thanks @davidguttman.
+- iOS/TestFlight: add a local beta release flow with Fastlane prepare/archive/upload support, canonical beta bundle IDs, and watch-app archive fixes. (#42991) Thanks @ngutman.
+- ACP/sessions_spawn: add optional `resumeSessionId` for `runtime: "acp"` so spawned ACP sessions can resume an existing ACPX/Codex conversation instead of always starting fresh. (#41847) Thanks @pejmanjohn.
+- Gateway/node pending work: add narrow in-memory pending-work queue primitives (`node.pending.enqueue` / `node.pending.drain`) and wake-helper reuse as a foundation for dormant-node work delivery. (#41409) Thanks @mbelinky.
+- Git/runtime state: ignore the gateway-generated `.dev-state` file so local runtime state does not show up as untracked repo noise. (#41848) Thanks @smysle.
+- Exec/child commands: mark child command environments with `OPENCLAW_CLI` so subprocesses can detect when they were launched from the OpenClaw CLI. (#41411) Thanks @vincentkoc.
+
+### Breaking
+
+- Cron/doctor: tighten isolated cron delivery so cron jobs can no longer notify through ad hoc agent sends or fallback main-session summaries, and add `openclaw doctor --fix` migration for legacy cron storage and legacy notify/webhook delivery metadata. (#40998) Thanks @mbelinky.
+
+### Fixes
+
+- Agents/text sanitization: strip leaked model control tokens (`<|...|>` and full-width `<｜...｜>` variants) from user-facing assistant text, preventing GLM-5 and DeepSeek internal delimiters from reaching end users. (#42173) Thanks @imwyvern.
+- iOS/gateway foreground recovery: reconnect immediately on foreground return after stale background sockets are torn down, so the app no longer stays disconnected until a later wake path happens. (#41384) Thanks @mbelinky.
+- Gateway/Control UI: keep dashboard auth tokens in session-scoped browser storage so same-tab refreshes preserve remote token auth without restoring long-lived localStorage token persistence, while scoping tokens to the selected gateway URL and fragment-only bootstrap flow. (#40892) thanks @velvet-shark.
+- Gateway/macOS launchd restarts: keep the LaunchAgent registered during explicit restarts, hand off self-restarts through a detached launchd helper, and recover config/hot reload restart paths without unloading the service. Fixes #43311, #43406, #43035, and #43049.
+- macOS/LaunchAgent install: tighten LaunchAgent directory and plist permissions during install so launchd bootstrap does not fail when the target home path or generated plist inherited group/world-writable modes.
+- Discord/reply chunking: resolve the effective `maxLinesPerMessage` config across live reply paths and preserve `chunkMode` in the fast send path so long Discord replies no longer split unexpectedly at the default 17-line limit. (#40133) thanks @rbutera.
+- Feishu/local image auto-convert: pass `mediaLocalRoots` through the `sendText` local-image shim so allowed local image paths upload as Feishu images again instead of falling back to raw path text. (#40623) Thanks @ayanesakura.
+- Models/Kimi Coding: send `anthropic-messages` tools in native Anthropic format again so `kimi-coding` stops degrading tool calls into XML/plain-text pseudo invocations instead of real `tool_use` blocks. (#38669, #39907, #40552) Thanks @opriz.
+- Telegram/outbound HTML sends: chunk long HTML-mode messages, preserve plain-text fallback and silent-delivery params across retries, and cut over to plain text when HTML chunk planning cannot safely preserve the full message. (#42240) thanks @obviyus.
+- Telegram/final preview delivery: split active preview lifecycle from cleanup retention so missing archived preview edits avoid duplicate fallback sends without clearing the live preview or blocking later in-place finalization. (#41662) thanks @hougangdev.
+- Telegram/final preview delivery followup: keep ambiguous missing-`message_id` finals only when a preview was already visible, while first-preview/no-id cases still fall back so Telegram users do not lose the final reply. (#41932) thanks @hougangdev.
+- Telegram/final preview cleanup follow-up: clear stale cleanup-retain state only for transient preview finals so archived-preview retains no longer leave a stale partial bubble beside a later fallback-sent final. (#41763) Thanks @obviyus.
+- Gateway/auth: allow one trusted device-token retry on shared-token mismatch with recovery hints to prevent reconnect churn during token drift. (#42507) Thanks @joshavant.
+- Gateway/config errors: surface up to three validation issues in top-level `config.set`, `config.patch`, and `config.apply` error messages while preserving structured issue details. (#42664) Thanks @huntharo.
+- Agents/Azure OpenAI Responses: include the `azure-openai` provider in the Responses API store override so Azure OpenAI multi-turn cron jobs and embedded agent runs no longer fail with HTTP 400 "store is set to false". (#42934, fixes #42800) Thanks @ademczuk.
+- Agents/error rendering: ignore stale assistant `errorMessage` fields on successful turns so background/tool-side failures no longer prepend synthetic billing errors over valid replies. (#40616) Thanks @ingyukoh.
+- Agents/billing recovery: probe single-provider billing cooldowns on the existing throttle so topping up credits can recover without a manual gateway restart. (#41422) thanks @altaywtf.
+- Agents/fallback: treat HTTP 499 responses as transient in both raw-text and structured failover paths so Anthropic-style client-closed overload responses trigger model fallback reliably. (#41468) thanks @zeroasterisk.
+- Agents/fallback: recognize Venice `402 Insufficient USD or Diem balance` billing errors so configured model fallbacks trigger instead of surfacing the raw provider error. (#43205) Thanks @Squabble9.
+- Agents/fallback: recognize Poe `402 You've used up your points!` billing errors so configured model fallbacks trigger instead of surfacing the raw provider error. (#42278) Thanks @CryUshio.
+- Agents/failover: treat Gemini `MALFORMED_RESPONSE` stop reasons as retryable timeouts so preview-model enum drift falls back cleanly instead of crashing the run, without also reclassifying malformed function-call errors. (#42292) Thanks @jnMetaCode.
+- Agents/cooldowns: default cooldown windows with no recorded failure history to `unknown` instead of `rate_limit`, avoiding false API rate-limit warnings while preserving cooldown recovery probes. (#42911) Thanks @VibhorGautam.
+- Auth/cooldowns: reset expired auth-profile cooldown error counters before computing the next backoff so stale on-disk counters do not re-escalate into long cooldown loops after expiry. (#41028) thanks @zerone0x.
+- Agents/memory flush: forward `memoryFlushWritePath` through `runEmbeddedPiAgent` so memory-triggered flush turns keep the append-only write guard without aborting before tool setup. Follows up on #38574. (#41761) Thanks @frankekn.
+- Agents/context pruning: prune image-only tool results during soft-trim, align context-pruning coverage with the new tool-result contract, and extend historical image cleanup to the same screenshot-heavy session path. (#43045) Thanks @MoerAI.
+- Sessions/reset model recompute: clear stale runtime model, context-token, and system-prompt metadata before session resets recompute the replacement session, so resets pick up current defaults and explicit overrides instead of reusing old runtime model state. (#41173) thanks @PonyX-lab.
+- Channels/allowlists: remove stale matcher caching so same-array allowlist edits and wildcard replacements take effect immediately, with regression coverage for in-place mutation cases.
+- Discord/Telegram outbound runtime config: thread runtime-resolved config through Discord and Telegram send paths so SecretRef-based credentials stay resolved during message delivery. (#42352) Thanks @joshavant.
+- Tools/web search: treat Brave `llm-context` grounding snippets as plain strings so `web_search` no longer returns empty snippet arrays in LLM Context mode. (#41387) thanks @zheliu2.
+- Tools/web search: recover OpenRouter Perplexity citation extraction from `message.annotations` when chat-completions responses omit top-level citations. (#40881) Thanks @laurieluo.
+- CLI/skills JSON: strip ANSI and C1 control bytes from `skills list --json`, `skills info --json`, and `skills check --json` so machine-readable output stays valid for terminals and skill metadata with embedded control characters. Fixes #27530. Related #27557. Thanks @Jimmy-xuzimo and @vincentkoc.
+- CLI/tables: default shared tables to ASCII borders on legacy Windows consoles while keeping Unicode borders on modern Windows terminals, so commands like `openclaw skills` stop rendering mojibake under GBK/936 consoles. Fixes #40853. Related #41015. Thanks @ApacheBin and @vincentkoc.
+- CLI/memory teardown: close cached memory search/index managers in the one-shot CLI shutdown path so watcher-backed memory caches no longer keep completed CLI runs alive after output finishes. (#40389) thanks @Julbarth.
+- Control UI/Sessions: restore single-column session table collapse on narrow viewport or container widths by moving the responsive table override next to the base grid rule and enabling inline-size container queries. (#12175) Thanks @benjipeng.
+- Telegram/network env-proxy: apply configured transport policy to proxied HTTPS dispatchers as well as direct `NO_PROXY` bypasses, so resolver-scoped IPv4 fallback and network settings work consistently for env-proxied Telegram traffic. (#40740) Thanks @sircrumpet.
+- Mattermost/Markdown formatting: preserve first-line indentation when stripping bot mentions so nested list items and indented code blocks keep their structure, and render Mattermost tables natively by default instead of fenced-code fallback. (#18655) thanks @echo931.
+- Mattermost/plugin send actions: normalize direct `replyTo` fallback handling so threaded plugin sends trim blank IDs and reuse the correct reply target again. (#41176) Thanks @hnykda.
+- MS Teams/allowlist resolution: use the General channel conversation ID as the resolved team key (with Graph GUID fallback) so Bot Framework runtime `channelData.team.id` matching works for team and team/channel allowlist entries. (#41838) Thanks @BradGroux.
+- Signal/config schema: accept `channels.signal.accountUuid` in strict config validation so loop-protection configs no longer fail with an unrecognized-key error. (#35578) Thanks @ingyukoh.
+- Telegram/config schema: accept `channels.telegram.actions.editMessage` and `createForumTopic` in strict config validation so existing Telegram action toggles no longer fail as unrecognized keys. (#35498) Thanks @ingyukoh.
+- Telegram/docs: clarify that `channels.telegram.groups` allowlists chats while `groupAllowFrom` allowlists users inside those chats, and point invalid negative chat IDs at the right config key. (#42451) Thanks @altaywtf.
+- Discord/config typing: expose channel-level `autoThread` on the canonical guild-channel config type so strict config loading matches the existing Discord schema and runtime behavior. (#35608) Thanks @ingyukoh.
+- fix(models): guard optional model.input capability checks (#42096) thanks @andyliu
+- Models/Alibaba Cloud Model Studio: wire `MODELSTUDIO_API_KEY` through shared env auth, implicit provider discovery, and shell-env fallback so onboarding works outside the wizard too. (#40634) Thanks @pomelo-nwu.
+- Resolve web tool SecretRefs atomically at runtime. (#41599) Thanks @joshavant.
+- Secret files: harden CLI and channel credential file reads against path-swap races by requiring direct regular files for `*File` secret inputs and rejecting symlink-backed secret files.
+- Archive extraction: harden TAR and external `tar.bz2` installs against destination symlink and pre-existing child-symlink escapes by extracting into staging first and merging into the canonical destination with safe file opens.
+- Secrets/SecretRef: reject exec SecretRef traversal ids across schema, runtime, and gateway. (#42370) Thanks @joshavant.
+- Sandbox/fs bridge: pin staged writes to verified parent directories so temporary write files cannot materialize outside the allowed mount before atomic replace. Thanks @tdjackey.
+- Gateway/auth: fail closed when local `gateway.auth.*` SecretRefs are configured but unavailable, instead of silently falling back to `gateway.remote.*` credentials in local mode. (#42672) Thanks @joshavant.
+- Commands/config writes: enforce `configWrites` against both the originating account and the targeted account scope for `/config` and config-backed `/allowlist` edits, blocking sibling-account mutations while preserving gateway `operator.admin` flows. Thanks @tdjackey for reporting.
+- Security/system.run: fail closed for approval-backed interpreter/runtime commands when OpenClaw cannot bind exactly one concrete local file operand, while extending best-effort direct-file binding to additional runtime forms. Thanks @tdjackey for reporting.
+- Gateway/session reset auth: split conversation `/new` and `/reset` handling away from the admin-only `sessions.reset` control-plane RPC so write-scoped gateway callers can no longer reach the privileged reset path through `agent`. Thanks @tdjackey for reporting.
+- Security/plugin runtime: stop unauthenticated plugin HTTP routes from inheriting synthetic admin gateway scopes when they call `runtime.subagent.*`, so admin-only methods like `sessions.delete` stay blocked without gateway auth.
+- Security/session_status: enforce sandbox session-tree visibility and shared agent-to-agent access guards before reading or mutating target session state, so sandboxed subagents can no longer inspect parent session metadata or write parent model overrides via `session_status`.
+- Security/nodes: treat the `nodes` agent tool as owner-only fallback policy so non-owner senders cannot reach paired-node approval or invoke paths through the shared tool set.
+- Security/external content: treat whitespace-delimited `EXTERNAL UNTRUSTED CONTENT` boundary markers like underscore-delimited variants so prompt wrappers cannot bypass marker sanitization. (#35983) Thanks @urianpaul94.
+- Telegram/exec approvals: reject `/approve` commands aimed at other bots, keep deterministic approval prompts visible when tool-result delivery fails, and stop resolved exact IDs from matching other pending approvals by prefix. (#37233) Thanks @huntharo.
+- Subagents/authority: persist leaf vs orchestrator control scope at spawn time and route tool plus slash-command control through shared ownership checks, so leaf sessions cannot regain orchestration privileges after restore or flat-key lookups. Thanks @tdjackey.
+- ACP/ACPX plugin: bump the bundled `acpx` pin to `0.1.16` so plugin-local installs and strict version checks match the latest published CLI. (#41975) Thanks @dutifulbob.
+- ACP/sessions.patch: allow `spawnedBy` and `spawnDepth` lineage fields on ACP session keys so `sessions_spawn` with `runtime: "acp"` no longer fails during child-session setup. Fixes #40971. (#40995) thanks @xaeon2026.
+- ACP/stop reason mapping: resolve gateway chat `state: "error"` completions as ACP `end_turn` instead of `refusal` so transient backend failures are not surfaced as deliberate refusals. (#41187) thanks @pejmanjohn.
+- ACP/setSessionMode: propagate gateway `sessions.patch` failures back to ACP clients so rejected mode changes no longer return silent success. (#41185) thanks @pejmanjohn.
+- ACP/bridge mode: reject unsupported per-session MCP server setup and propagate rejected session-mode changes so IDE clients see explicit bridge limitations instead of silent success. (#41424) Thanks @mbelinky.
+- ACP/session UX: replay stored user and assistant text on `loadSession`, expose Gateway-backed session controls and metadata, and emit approximate session usage updates so IDE clients restore context more faithfully. (#41425) Thanks @mbelinky.
+- ACP/tool streaming: enrich `tool_call` and `tool_call_update` events with best-effort text content and file-location hints so IDE clients can follow bridge tool activity more naturally. (#41442) Thanks @mbelinky.
+- ACP/runtime attachments: forward normalized inbound image attachments into ACP runtime turns so ACPX sessions can preserve image prompt content on the runtime path. (#41427) Thanks @mbelinky.
+- ACP/regressions: add gateway RPC coverage for ACP lineage patching, ACPX runtime coverage for image prompt serialization, and an operator smoke-test procedure for live ACP spawn verification. (#41456) Thanks @mbelinky.
+- ACP/follow-up hardening: make session restore and prompt completion degrade gracefully on transcript/update failures, enforce bounded tool-location traversal, and skip non-image ACPX turns the runtime cannot serialize. (#41464) Thanks @mbelinky.
+- ACP/sessions_spawn: implicitly stream `mode="run"` ACP spawns to parent only for eligible subagent orchestrator sessions (heartbeat `target: "last"` with a usable session-local route), restoring parent progress relays without thread binding. (#42404) Thanks @davidguttman.
+- ACP/main session aliases: canonicalize `main` before ACP session lookup so restarted ACP main sessions rehydrate instead of failing closed with `Session is not ACP-enabled: main`. (#43285, fixes #25692)
+- Plugins/context-engine model auth: expose `runtime.modelAuth` and plugin-sdk auth helpers so plugins can resolve provider/model API keys through the normal auth pipeline. (#41090) thanks @xinhuagu.
+- Hooks/plugin context parity followup: pass `trigger` and `channelId` through embedded `llm_input`, `agent_end`, and `llm_output` hook contexts so plugins receive the same agent metadata across hook phases. (#42362) Thanks @zhoulf1006.
+- Plugins/global hook runner: harden singleton state handling so shared global hook runner reuse does not leak or corrupt runner state across executions. (#40184) Thanks @vincentkoc.
+- Context engine/tests: add bundled-registry regression coverage for cross-chunk resolution, plugin-sdk re-exports, and concurrent chunk registration. (#40460) thanks @dsantoreis.
+- Agents/embedded runner: bound compaction retry waiting and drain embedded runs during SIGUSR1 restart so session lanes recover instead of staying blocked behind compaction. (#40324) thanks @cgdusek.
+- Agents/embedded logs: add structured, sanitized lifecycle and failover observation events so overload and provider failures are easier to tail and filter. (#41336) thanks @altaywtf.
+- Agents/embedded overload logs: include the failing model and provider in error-path console output, with lifecycle regression coverage for the rendered and sanitized `consoleMessage`. (#41236) thanks @jiarung.
+- Agents/fallback observability: add structured, sanitized model-fallback decision and auth-profile failure-state events with correlated run IDs so cooldown probes and failover paths are easier to trace in logs. (#41337) thanks @altaywtf.
+- Logging/probe observations: suppress structured embedded and model-fallback probe warnings on the console without hiding error or fatal output. (#41338) thanks @altaywtf.
+- Agents/context-engine compaction: guard thrown engine-owned overflow compaction attempts and fire compaction hooks for `ownsCompaction` engines so overflow recovery no longer crashes and plugin subscribers still observe compact runs. (#41361) thanks @davidrudduck.
+- Gateway/node pending drain followup: keep `hasMore` true when the deferred baseline status item still needs delivery, and avoid allocating empty pending-work state for drain-only nodes with no queued work. (#41429) Thanks @mbelinky.
+- Protocol/Swift model sync: regenerate pending node work Swift bindings after the landed `node.pending.*` schema additions so generated protocol artifacts are consistent again. (#41477) Thanks @mbelinky.
+- Cron/subagent followup: do not misclassify empty or `NO_REPLY` cron responses as interim acknowledgements that need a rerun, so deliberately silent cron jobs are no longer retried. (#41383) thanks @jackal092927.
+- Cron/state errors: record `lastErrorReason` in cron job state and keep the gateway schema aligned with the full failover-reason set, including regression coverage for protocol conformance. (#14382) thanks @futuremind2026.
+- Browser/Browserbase 429 handling: surface stable no-retry rate-limit guidance without buffering discarded HTTP 429 response bodies from remote browser services. (#40491) thanks @mvanhorn.
+- CI/CodeQL Swift toolchain: select Xcode 26.1 before installing Swift build tools so the CodeQL Swift job uses Swift tools 6.2 on `macos-latest`. (#41787) thanks @BunsDev.
+- Sandbox/subagents: pass the real configured workspace through `sessions_spawn` inheritance when a parent agent runs in a copied-workspace sandbox, so child `/agent` mounts point at the configured workspace instead of the parent sandbox copy. (#40757) Thanks @dsantoreis.
+- Agents/fallback cooldown probing: cap cooldown-bypass probing to one attempt per provider per fallback run so multi-model same-provider cooldown chains can continue to cross-provider fallbacks instead of repeatedly stalling on duplicate cooldown probes. (#41711) Thanks @cgdusek.
+- Telegram/direct delivery: bridge direct delivery sends to internal `message:sent` hooks so internal hook listeners observe successful Telegram deliveries. (#40185) Thanks @vincentkoc.
+- Dependencies: refresh workspace dependencies except the pinned Carbon package, and harden ACP session-config writes against non-string SDK values so newer ACP clients fail fast instead of tripping type/runtime mismatches.
+- Telegram/polling restarts: clear bounded cleanup timeout handles after `runner.stop()` and `bot.stop()` settle so stall recovery no longer leaves stray 15-second timers behind on clean shutdown. (#43188) thanks @kyohwang.
+
 ## 2026.3.8
 
 ### Changes
 
+- CLI/backup: add `openclaw backup create` and `openclaw backup verify` for local state archives, including `--only-config`, `--no-include-workspace`, manifest/payload validation, and backup guidance in destructive flows. (#40163) thanks @shichangs.
+- macOS/onboarding: add a remote gateway token field for remote mode, preserve existing non-plaintext `gateway.remote.token` config values until explicitly replaced, and warn when the loaded token shape cannot be used directly from the macOS app. (#40187, supersedes #34614) Thanks @cgdusek.
+- Talk mode: add top-level `talk.silenceTimeoutMs` config so Talk waits a configurable amount of silence before auto-sending the current transcript, while keeping each platform's existing default pause window when unset. (#39607) Thanks @danodoesdesign. Fixes #17147.
 - TUI: infer the active agent from the current workspace when launched inside a configured agent workspace, while preserving explicit `agent:` session targets. (#39591) thanks @arceus77-7.
+- Tools/Brave web search: add opt-in `tools.web.search.brave.mode: "llm-context"` so `web_search` can call Brave's LLM Context endpoint and return extracted grounding snippets with source metadata, plus config/docs/test coverage. (#33383) Thanks @thirumaleshp.
+- CLI/install: include the short git commit hash in `openclaw --version` output when metadata is available, and keep installer version checks compatible with the decorated format. (#39712) thanks @sourman.
+- CLI/backup: improve archive naming for date sorting, add config-only backup mode, and harden backup planning, publication, and verification edge cases. (#40163) Thanks @gumadeiras.
+- ACP/Provenance: add optional ACP ingress provenance metadata and visible receipt injection (`openclaw acp --provenance off|meta|meta+receipt`) so OpenClaw agents can retain and report ACP-origin context with session trace IDs. (#40473) thanks @mbelinky.
+- Tools/web search: alphabetize provider ordering across runtime selection, onboarding/configure pickers, and config metadata, so provider lists stay neutral and multi-key auto-detect now prefers Grok before Kimi. (#40259) thanks @kesku.
+- Docs/Web search: restore $5/month free-credit details, replace defunct "Data for Search"/"Data for AI" plan names with current "Search" plan, and note legacy subscription validity in Brave setup docs. Follows up on #26860. (#40111) Thanks @remusao.
+- Extensions/ACPX tests: move the shared runtime fixture helper from `src/runtime-internals/` to `src/test-utils/` so the test-only helper no longer looks like shipped runtime code.
 
 ### Fixes
 
+- Update/macOS launchd restart: re-enable disabled LaunchAgent services before updater bootstrap so `openclaw update` can recover from a disabled gateway service instead of leaving the restart step stuck.
 - macOS app/chat UI: route browser proxy through the local node browser service, preserve plain-text paste semantics, strip completed assistant trace/debug wrapper noise from transcripts, refresh permission state after returning from System Settings, and tolerate malformed cron rows in the macOS tab. (#39516) Thanks @Imhermes1.
-- Mattermost replies: keep `root_id` pinned to the existing thread root when an agent replies inside a thread, while still using reply-target threading for top-level posts. (#27744) thanks @hnykda.
-- Agents/failover: detect Amazon Bedrock `Too many tokens per day` quota errors as rate limits across fallback, cron retry, and memory embeddings while keeping context-window `too many tokens per request` errors out of the rate-limit lane. (#39377) Thanks @gambletan.
 - Android/Play distribution: remove self-update, background location, `screen.record`, and background mic capture from the Android app, narrow the foreground service to `dataSync` only, and clean up the legacy `location.enabledMode=always` preference migration. (#39660) Thanks @obviyus.
-- Agents/openai-codex model resolution: fall through from inline `openai-codex` model entries without an `api` so GPT-5.4 keeps the codex transport and still preserves configured `baseUrl` and headers. (#39753) Thanks @justinhuangcode.
+- Telegram/DM routing: dedupe inbound Telegram DMs per agent instead of per session key so the same DM cannot trigger duplicate replies when both `agent:main:main` and `agent:main:telegram:direct:<id>` resolve for one agent. Fixes #40005. Supersedes #40116. (#40519) thanks @obviyus.
+- Cron/Telegram announce delivery: route text-only announce jobs through the real outbound adapters after finalizing descendant output so plain Telegram targets no longer report `delivered: true` when no message actually reached Telegram. (#40575) thanks @obviyus.
+- Matrix/DM routing: add safer fallback detection for broken `m.direct` homeservers, honor explicit room bindings over DM classification, and preserve room-bound agent selection for Matrix DM rooms. (#19736) Thanks @derbronko.
+- Feishu/plugin onboarding: clear the short-lived plugin discovery cache before reloading the registry after installing a channel plugin, so onboarding no longer re-prompts to download Feishu immediately after a successful install. Fixes #39642. (#39752) Thanks @GazeKingNuWu.
+- Plugins/channel onboarding: prefer bundled channel plugins over duplicate npm-installed copies during onboarding and release-channel sync, preventing bundled plugins from being shadowed by npm installs with the same plugin ID. (#40092)
+- Config/runtime snapshots: keep secrets-runtime-resolved config and auth-profile snapshots intact after config writes so follow-up reads still see file-backed secret values while picking up the persisted config update. (#37313) thanks @bbblending.
+- Gateway/Control UI: resolve bundled dashboard assets through symlinked global wrappers and auto-detected package roots, while keeping configured and custom roots on the strict hardlink boundary. (#40385) Thanks @LarytheLord.
+- Browser/extension relay: add `browser.relayBindHost` so the Chrome relay can bind to an explicit non-loopback address for WSL2 and other cross-namespace setups, while preserving loopback-only defaults. (#39364) Thanks @mvanhorn.
+- Browser/CDP: normalize loopback direct WebSocket CDP URLs back to HTTP(S) for `/json/*` tab operations so local `ws://` / `wss://` profiles can still list, focus, open, and close tabs after the new direct-WS support lands. (#31085) Thanks @shrey150.
+- Browser/CDP: rewrite wildcard `ws://0.0.0.0` and `ws://[::]` debugger URLs from remote `/json/version` responses back to the external CDP host/port, fixing Browserless-style container endpoints. (#17760) Thanks @joeharouni.
+- Browser/extension relay: wait briefly for a previously attached Chrome tab to reappear after transient relay drops before failing with `tab not found`, reducing noisy reconnect flakes. (#32461) Thanks @AaronWander.
+- macOS/Tailscale gateway discovery: keep Tailscale Serve probing alive when other remote gateways are already discovered, prefer direct transport for resolved `.ts.net` and Tailscale Serve gateways, and set `TERM=dumb` for GUI-launched Tailscale CLI discovery. (#40167) thanks @ngutman.
+- TUI/theme: detect light terminal backgrounds via `COLORFGBG` and pick a WCAG AA-compliant light palette, with `OPENCLAW_THEME=light|dark` override for terminals without auto-detection. (#38636) Thanks @ademczuk and @vincentkoc.
+- Agents/openai-codex: normalize `gpt-5.4` fallback transport back to `openai-codex-responses` on `chatgpt.com/backend-api` when config drifts to the generic OpenAI responses endpoint. (#38736) Thanks @0xsline.
+- Models/openai-codex GPT-5.4 forward-compat: use the GPT-5.4 1,050,000-token context window and 128,000 max tokens for `openai-codex/gpt-5.4` instead of inheriting stale legacy Codex limits in resolver fallbacks and model listing. (#37876) thanks @yuweuii.
+- Tools/web search: restore Perplexity OpenRouter/Sonar compatibility for legacy `OPENROUTER_API_KEY`, `sk-or-...`, and explicit `perplexity.baseUrl` / `model` setups while keeping direct Perplexity keys on the native Search API path. (#39937) Thanks @obviyus.
+- Agents/failover: detect Amazon Bedrock `Too many tokens per day` quota errors as rate limits across fallback, cron retry, and memory embeddings while keeping context-window `too many tokens per request` errors out of the rate-limit lane. (#39377) Thanks @gambletan.
+- Mattermost replies: keep `root_id` pinned to the existing thread root when an agent replies inside a thread, while still using reply-target threading for top-level posts. (#27744) thanks @hnykda.
+- Telegram/DM partial streaming: keep DM preview lanes on real message edits instead of native draft materialization so final replies no longer flash a second duplicate copy before collapsing back to one.
+- macOS overlays: fix VoiceWake, Talk, and Notify overlay exclusivity crashes by removing shared `inout` visibility mutation from `OverlayPanelFactory.present`, and add a repeated Talk overlay smoke test. (#39275, #39321) Thanks @fellanH.
+- macOS Talk Mode: set the speech recognition request `taskHint` to `.dictation` for mic capture, and add regression coverage for the request defaults. (#38445) Thanks @dmiv.
+- macOS release packaging: default `scripts/package-mac-app.sh` to universal binaries for `BUILD_CONFIG=release`, and clarify that `scripts/package-mac-dist.sh` already produces the release zip + DMG. (#33891) Thanks @cgdusek.
+- Hooks/session-memory: keep `/new` and `/reset` memory artifacts in the bound agent workspace and align saved reset session keys with that workspace when stale main-agent keys leak into the hook path. (#39875) thanks @rbutera.
+- Sessions/model switch: clear stale cached `contextTokens` when a session changes models so status and runtime paths recompute against the active model window. (#38044) thanks @yuweuii.
+- ACP/session history: persist transcripts for successful ACP child runs, preserve exact transcript text, record ACP spawned-session lineage, and keep spawn-time transcript-path persistence best-effort so history storage failures do not block execution. (#40137) thanks @mbelinky.
+- Docs/browser: add a layered WSL2 + Windows remote Chrome CDP troubleshooting guide, including Control UI origin pitfalls and extension-relay bind-address guidance. (#39407) Thanks @Owlock.
+- Context engine registry/bundled builds: share the registry state through a `globalThis` singleton so duplicated bundled module copies can resolve engines registered by each other at runtime, with regression coverage for duplicate-module imports. (#40115) thanks @jalehman.
+- Podman/setup: fix `cannot chdir: Permission denied` in `run_as_user` when `setup-podman.sh` is invoked from a directory the target user cannot access, by wrapping user-switch calls in a subshell that cd's to `/tmp` with `/` fallback. (#39435) Thanks @langdon and @jlcbk.
+- Podman/SELinux: auto-detect SELinux enforcing/permissive mode and add `:Z` relabel to bind mounts in `run-openclaw-podman.sh` and the Quadlet template, fixing `EACCES` on Fedora/RHEL hosts. Supports `OPENCLAW_BIND_MOUNT_OPTIONS` override. (#39449) Thanks @langdon and @githubbzxs.
+- Agents/context-engine plugins: bootstrap runtime plugins once at embedded-run, compaction, and subagent boundaries so plugin-provided context engines and hooks load from the active workspace before runtime resolution. (#40232)
+- Docs/Changelog: correct the contributor credit for the bundled Control UI global-install fix to @LarytheLord. (#40420) Thanks @velvet-shark.
+- Telegram/media downloads: time out only stalled body reads so polling recovers from hung file downloads without aborting slow downloads that are still streaming data. (#40098) thanks @tysoncung.
+- Docker/runtime image: prune dev dependencies, strip build-only dist metadata for smaller Docker images. (#40307) Thanks @vincentkoc.
+- Subagents/sandboxing: restrict leaf subagents to their own spawned runs and remove leaf `subagents` control access so sandboxed leaf workers can no longer steer sibling sessions. Thanks @tdjackey.
+- Gateway/restart timeout recovery: exit non-zero when restart-triggered shutdown drains time out so launchd/systemd restart the gateway instead of treating the failed restart as a clean stop. Landed from contributor PR #40380 by @dsantoreis. Thanks @dsantoreis.
+- Gateway/config restart guard: validate config before service start/restart and keep post-SIGUSR1 startup failures from crashing the gateway process, reducing invalid-config restart loops and macOS permission loss. Landed from contributor PR #38699 by @lml2468. Thanks @lml2468.
+- Gateway/launchd respawn detection: treat `XPC_SERVICE_NAME` as a launchd supervision hint so macOS restarts exit cleanly under launchd instead of attempting detached self-respawn. Landed from contributor PR #20555 by @dimat. Thanks @dimat.
+- Telegram/poll restart cleanup: abort the in-flight Telegram API fetch when shutdown or forced polling restarts stop a runner, preventing stale `getUpdates` long polls from colliding with the replacement runner. Landed from contributor PR #23950 by @Gkinthecodeland. Thanks @Gkinthecodeland.
+- Cron/restart catch-up staggering: limit immediate missed-job replay on startup and reschedule the deferred remainder from the post-catchup clock so restart bursts do not starve the gateway or silently skip overdue recurring jobs. Landed from contributor PR #18925 by @rexlunae. Thanks @rexlunae.
+- Cron/owner-only tools: pass trusted isolated cron runs into the embedded agent with owner context so `cron`/`gateway` tooling remains available after the owner-auth hardening narrowed direct-message ownership inference.
+- Browser/SSRF: block private-network intermediate redirect hops in strict browser navigation flows and fail closed when remote tab-open paths cannot inspect redirect chains. Thanks @zpbrent.
+- MS Teams/authz: keep `groupPolicy: "allowlist"` enforcing sender allowlists even when a team/channel route allowlist is configured, so route matches no longer widen group access to every sender in that route. Thanks @zpbrent.
+- Security/Gateway: block `device.token.rotate` from minting operator scopes broader than the caller session already holds, closing the critical paired-device token privilege escalation reported as GHSA-4jpw-hj22-2xmc.
+- Security/system.run: bind approved `bun` and `deno run` script operands to on-disk file snapshots so post-approval script rewrites are denied before execution.
+- Skills/download installs: pin the validated per-skill tools root before writing downloaded archives, so rebinding the lexical tools path cannot redirect download writes outside the intended tools directory. Thanks @tdjackey.
+- Control UI/Debug: replace the Manual RPC free-text method field with a sorted dropdown sourced from gateway-advertised methods, and stack the form vertically for narrower layouts. (#14967) thanks @rixau.
+- Auth/profile resolution: log debug details when auto-discovered auth profiles fail during provider API-key resolution, so `--debug` output surfaces the real refresh/keychain/credential-store failure instead of only the generic missing-key message. (#41271) thanks @he-yufeng.
+- ACP/cancel scoping: scope `chat.abort` and shared-session ACP event routing by `runId` so one session cannot cancel or consume another session's run when they share the same gateway session key. (#41331) Thanks @pejmanjohn.
+- SecretRef/models: harden custom/provider secret persistence and reuse across models.json snapshots, merge behavior, runtime headers, and secret audits. (#42554) Thanks @joshavant.
+- macOS/browser proxy: serialize non-GET browser proxy request bodies through `AnyCodable.foundationValue` so nested JSON bodies no longer crash the macOS app with `Invalid type in JSON write (__SwiftValue)`. (#43069) Thanks @Effet.
+- CLI/skills tables: keep terminal table borders aligned for wide graphemes, use full reported terminal width, and switch a few ambiguous skill icons to Terminal-safe emoji so `openclaw skills` renders more consistently in Terminal.app and iTerm. Thanks @vincentkoc.
+- Memory/Gemini: normalize returned Gemini embeddings across direct query, direct batch, and async batch paths so memory search uses consistent vector handling for Gemini too. (#43409) Thanks @gumadeiras.
 
 ## 2026.3.7
 
@@ -47,6 +236,7 @@ Docs: https://docs.openclaw.ai
 - Mattermost/model picker: add Telegram-style interactive provider/model browsing for `/oc_model` and `/oc_models`, fix picker callback updates, and emit a normal confirmation reply when a model is selected. (#38767) thanks @mukhtharcm.
 - Docker/multi-stage build: restructure Dockerfile as a multi-stage build to produce a minimal runtime image without build tools, source code, or Bun; add `OPENCLAW_VARIANT=slim` build arg for a bookworm-slim variant. (#38479) Thanks @sallyom.
 - Google/Gemini 3.1 Flash-Lite: add first-class `google/gemini-3.1-flash-lite-preview` support across model-id normalization, default aliases, media-understanding image lookups, Google Gemini CLI forward-compat fallback, and docs.
+- Agents/compaction model override: allow `agents.defaults.compaction.model` to route compaction summarization through a different model than the main session, and document the override across config help/reference surfaces. (#38753) thanks @starbuck100.
 
 ### Breaking
 
@@ -80,6 +270,7 @@ Docs: https://docs.openclaw.ai
 - Onboarding/API key input hardening: strip non-Latin1 Unicode artifacts from normalized secret input (while preserving Latin-1 content and internal spaces) so malformed copied API keys cannot trigger HTTP header `ByteString` construction crashes; adds regression coverage for shared normalization and MiniMax auth header usage. (#24496) Thanks @fa6maalassaf.
 - Kimi Coding/Anthropic tools compatibility: normalize `anthropic-messages` tool payloads to OpenAI-style `tools[].function` + compatible `tool_choice` when targeting Kimi Coding endpoints, restoring tool-call workflows that regressed after v2026.3.2. (#37038) Thanks @mochimochimochi-hub.
 - Heartbeat/workspace-path guardrails: append explicit workspace `HEARTBEAT.md` path guidance (and `docs/heartbeat.md` avoidance) to heartbeat prompts so heartbeat runs target workspace checklists reliably across packaged install layouts. (#37037) Thanks @stofancy.
+- Node/system.run approvals: bind approval prompts to the exact executed argv text and show shell payload only as a secondary preview, closing basename-spoofed wrapper approval mismatches. Thanks @tdjackey.
 - Subagents/kill-complete announce race: when a late `subagent-complete` lifecycle event arrives after an earlier kill marker, clear stale kill suppression/cleanup flags and re-run announce cleanup so finished runs no longer get silently swallowed. (#37024) Thanks @cmfinlan.
 - Agents/tool-result cleanup timeout hardening: on embedded runner teardown idle timeouts, clear pending tool-call state without persisting synthetic `missing tool result` entries, preventing timeout cleanups from poisoning follow-up turns; adds regression coverage for timeout clear-vs-flush behavior. (#37081) Thanks @Coyote-Den.
 - Agents/openai-completions stream timeout hardening: ensure runtime undici global dispatchers use extended streaming body/header timeouts (including env-proxy dispatcher mode) before embedded runs, reducing forced mid-stream `terminated` failures on long generations; adds regression coverage for dispatcher selection and idempotent reconfiguration. (#9708) Thanks @scottchguard.
@@ -99,6 +290,7 @@ Docs: https://docs.openclaw.ai
 - Agents/compaction safeguard pre-check: skip embedded compaction before entering the Pi SDK when a session has no real conversation messages, avoiding unnecessary LLM API calls on idle sessions. (#36451) thanks @Sid-Qin.
 - Config/schema cache key stability: build merged schema cache keys with incremental hashing to avoid large single-string serialization and prevent `RangeError: Invalid string length` on high-cardinality plugin/channel metadata. (#36603) Thanks @powermaster888.
 - iMessage/cron completion announces: strip leaked inline reply tags (for example `[[reply_to:6100]]`) from user-visible completion text so announcement deliveries do not expose threading metadata. (#24600) Thanks @vincentkoc.
+- Cron/manual run enqueue flow: queue `cron.run` requests behind the cron execution lane, return immediate `{ ok: true, enqueued: true, runId }` acknowledgements, preserve `{ ok: true, ran: false, reason }` skip responses for already-running and not-due jobs, and document the asynchronous completion flow. (#40204)
 - Control UI/iMessage duplicate reply routing: keep internal webchat turns on dispatcher delivery (instead of origin-channel reroute) so Control UI chats do not duplicate replies into iMessage, while preserving webchat-provider relayed routing for external surfaces. Fixes #33483. Thanks @alicexmolt.
 - Sessions/daily reset transcript archival: archive prior transcript files during stale-session scheduled/daily resets by capturing the previous session entry before rollover, preventing orphaned transcript files on disk. (#35493) Thanks @byungsker.
 - Feishu/group slash command detection: normalize group mention wrappers before command-authorization probing so mention-prefixed commands (for example `@Bot/model` and `@Bot /reset`) are recognized as gateway commands instead of being forwarded to the agent. (#35994) Thanks @liuxiaopai-ai.
@@ -370,6 +562,9 @@ Docs: https://docs.openclaw.ai
 - Control UI/Telegram sender labels: preserve inbound sender labels in sanitized chat history so dashboard user-message groups split correctly and show real group-member names instead of `You`. (#39414) Thanks @obviyus.
 - Agents/failover 402 recovery: keep temporary spend-limit `402` payloads retryable, preserve explicit insufficient-credit billing detection even in long provider payloads, and allow throttled billing-cooldown probes so single-provider setups can recover instead of staying locked out. (#38533) Thanks @xialonglee.
 - Browser/config schema: accept `browser.profiles.*.driver: "openclaw"` while preserving legacy `"clawd"` compatibility in validated config. (#39374; based on #35621) Thanks @gambletan and @ingyukoh.
+- Memory flush/bootstrap file protection: restrict memory-flush runs to append-only `read`/`write` tools and route host-side memory appends through root-enforced safe file handles so flush turns cannot overwrite bootstrap files via `exec` or unsafe raw rewrites. (#38574) Thanks @frankekn.
+- Mattermost/DM media uploads: resolve bare 26-character Mattermost IDs user-first for direct messages so media sends no longer fail with `403 Forbidden` when targets are configured as unprefixed user IDs. (#29925) Thanks @teconomix.
+- Voice-call/OpenAI TTS config parity: add missing `speed`, `instructions`, and `baseUrl` fields to the OpenAI TTS config schema and gate `instructions` to supported models so voice-call overrides validate and route cleanly through core TTS. (#39226) Thanks @ademczuk.
 
 ## 2026.3.2
 
@@ -728,6 +923,7 @@ Docs: https://docs.openclaw.ai
 ### Fixes
 
 - Gateway/macOS restart: remove self-issued `launchctl kickstart -k` from launchd supervised restart path to prevent race with launchd's async bootout state machine that permanently unloads the LaunchAgent. With `ThrottleInterval=1` (current default), `exit(0)` + `KeepAlive=true` restarts the service within ~1s without the race condition. (#39760) Landed from contributor PR #39763 by @daymade. Thanks @daymade.
+- Plugin SDK/bundled subpath contracts: add regression coverage for newly routed bundled-plugin SDK exports so BlueBubbles, Mattermost, Nextcloud Talk, and Twitch subpath symbols stay pinned during future plugin-sdk cleanup. (#39638)
 - Exec/system.run env sanitization: block dangerous override-only env pivots such as `GIT_SSH_COMMAND`, editor/pager hooks, and `GIT_CONFIG_` / `NPM_CONFIG_` override prefixes so allowlisted tools cannot smuggle helper command execution through subprocess environment overrides. Thanks @tdjackey and @SnailSploit for reporting.
 - Network/fetch guard redirect auth stripping: switch cross-origin redirect handling in `fetchWithSsrFGuard` from a narrow sensitive-header denylist to a safe-header allowlist so custom auth headers like `X-Api-Key` and `Private-Token` no longer leak on origin changes. Thanks @Rickidevs for reporting.
 - Security/Sandbox media reads: eliminate sandbox media TOCTOU symlink-retarget escapes by enforcing root-scoped boundary-safe reads at attachment/image load time and consolidating shared safe-read helpers across sandbox media callsites. This ships in the next npm release. Thanks @tdjackey for reporting.
@@ -876,6 +1072,7 @@ Docs: https://docs.openclaw.ai
 - Browser/Navigate: resolve the correct `targetId` in navigate responses after renderer swaps. (#25326) Thanks @stone-jin and @vincentkoc.
 - FS/Sandbox workspace boundaries: add a dedicated `outside-workspace` safe-open error code for root-escape checks, and propagate specific outside-workspace messages across edit/browser/media consumers instead of generic not-found/invalid-path fallbacks. (#29715) Thanks @YuzuruS.
 - Diagnostics/Stuck session signal: add configurable stuck-session warning threshold via `diagnostics.stuckSessionWarnMs` (default 120000ms) to reduce false-positive warnings on long multi-tool turns. (#31032)
+- Agents/error classification: check billing errors before context overflow heuristics in the agent runner catch block so spend-limit and quota errors show the billing-specific message instead of being misclassified as "Context overflow: prompt too large". (#40409) Thanks @ademczuk.
 
 ## 2026.2.26
 
@@ -3848,6 +4045,7 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Gateway/Daemon/Doctor: atomic config writes; repair gateway service entrypoint + install switches; non-interactive legacy migrations; systemd unit alignment + KillMode=process; node bridge keepalive/pings; Launch at Login persistence; bundle MoltbotKit resources + Swift 6.2 compat dylib; relay version check + remove smoke test; regen Swift GatewayModels + keep agent provider string; cron jobId alias + channel alias migration + main session key normalization; heartbeat Telegram accountId resolution; avoid WhatsApp fallback for internal runs; gateway listener error wording; serveBaseUrl param; honor gateway --dev; fix wide-area discovery updates; align agents.defaults schema; provider account metadata in daemon status; refresh Carbon patch for gateway fixes; restore doctor prompter initialValue handling.
 - Control UI/TUI: persist per-session verbose off + hide tool cards; logs tab opens at bottom; relative asset paths + landing cleanup; session labels lookup/persistence; stop pinning main session in recents; start logs at bottom; TUI status bar refresh + timeout handling + hide reasoning label when off.
 - Onboarding/Configure: QuickStart single-select provider picker; avoid Codex CLI false-expiry warnings; clarify WhatsApp owner prompt; fix Minimax hosted onboarding (agents.defaults + msteams heartbeat target); remove configure Control UI prompt; honor gateway --dev flag.
+- Agent loop: guard overflow compaction throws and restore compaction hooks for engine-owned context engines. (#41361) — thanks @davidrudduck
 
 ### Maintenance
 

CONTRIBUTING.md

@@ -57,9 +57,24 @@ Welcome to the lobster tank! 🦞
   - GitHub: [@joshavant](https://github.com/joshavant) · X: [@joshavant](https://x.com/joshavant)
 
 - **Jonathan Taylor** - ACP subsystem, Gateway features/bugs, Gog/Mog/Sog CLI's, SEDMAT
-  - Github [@visionik](https://github.com/visionik) · X: [@visionik](https://x.com/visionik)
+  - GitHub [@visionik](https://github.com/visionik) · X: [@visionik](https://x.com/visionik)
 - **Josh Lehman** - Compaction, Tlon/Urbit subsystem
-  - Github [@jalehman](https://github.com/jalehman) · X: [@jlehman\_](https://x.com/jlehman_)
+  - GitHub [@jalehman](https://github.com/jalehman) · X: [@jlehman\_](https://x.com/jlehman_)
+
+- **Radek Sienkiewicz** - Control UI + WebChat correctness
+  - GitHub [@velvet-shark](https://github.com/velvet-shark) · X: [@velvet_shark](https://twitter.com/velvet_shark)
+
+- **Muhammed Mukhthar** - Mattermost, CLI
+  - GitHub [@mukhtharcm](https://github.com/mukhtharcm) · X: [@mukhtharcm](https://x.com/mukhtharcm)
+
+- **Altay** - Agents, CLI, error handling
+  - GitHub [@altaywtf](https://github.com/altaywtf) · X: [@altaywtf](https://x.com/altaywtf)
+
+- **Robin Waslander** - Security, PR triage, bug fixes
+  - GitHub: [@hydro13](https://github.com/hydro13) · X: [@Robin_waslander](https://x.com/Robin_waslander)
+
+- **Tengji (George) Zhang** - Chinese model APIs, cloud, pi
+  - GitHub: [@odysseus0](https://github.com/odysseus0) · X: [@odysseus0z](https://x.com/odysseus0z)
 
 ## How to Contribute
 
@@ -71,11 +86,25 @@ Welcome to the lobster tank! 🦞
 
 - Test locally with your OpenClaw instance
 - Run tests: `pnpm build && pnpm check && pnpm test`
+- If you have access to Codex, run `codex review --base origin/main` locally before opening or updating your PR. Treat this as the current highest standard of AI review, even if GitHub Codex review also runs.
 - Ensure CI checks pass
 - Keep PRs focused (one thing per PR; do not mix unrelated concerns)
 - Describe what & why
+- Reply to or resolve bot review conversations you addressed before asking for review again
 - **Include screenshots** — one showing the problem/before, one showing the fix/after (for UI or visual changes)
 
+## Review Conversations Are Author-Owned
+
+If a review bot leaves review conversations on your PR, you are expected to handle the follow-through:
+
+- Resolve the conversation yourself once the code or explanation fully addresses the bot's concern
+- Reply and leave it open only when you need maintainer or reviewer judgment
+- Do not leave "fixed" bot review conversations for maintainers to clean up for you
+- If Codex leaves comments, address every relevant one or resolve it with a short explanation when it is not applicable to your change
+- If GitHub Codex review does not trigger for some reason, run `codex review --base origin/main` locally anyway and treat that output as required review work
+
+This applies to both human-authored and AI-assisted PRs.
+
 ## Control UI Decorators
 
 The Control UI uses Lit with **legacy** decorators (current Rollup parsing does not support
@@ -101,8 +130,10 @@ Please include in your PR:
 - [ ] Note the degree of testing (untested / lightly tested / fully tested)
 - [ ] Include prompts or session logs if possible (super helpful!)
 - [ ] Confirm you understand what the code does
+- [ ] If you have access to Codex, run `codex review --base origin/main` locally and address the findings before asking for review
+- [ ] Resolve or reply to bot review conversations after you address them
 
-AI PRs are first-class citizens here. We just want transparency so reviewers know what to look for.
+AI PRs are first-class citizens here. We just want transparency so reviewers know what to look for. If you are using an LLM coding agent, instruct it to resolve bot review conversations it has addressed instead of leaving them for maintainers.
 
 ## Current Focus & Roadmap 🗺
 

Dockerfile

@@ -1,3 +1,5 @@
+# syntax=docker/dockerfile:1.7
+
 # Opt-in extension dependencies at build time (space-separated directory names).
 # Example: docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix" .
 #
@@ -48,16 +50,25 @@ WORKDIR /app
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
 COPY ui/package.json ./ui/package.json
 COPY patches ./patches
-COPY scripts ./scripts
 
 COPY --from=ext-deps /out/ ./extensions/
 
 # Reduce OOM risk on low-memory hosts during dependency installation.
 # Docker builds on small VMs may otherwise fail with "Killed" (exit 137).
-RUN NODE_OPTIONS=--max-old-space-size=2048 pnpm install --frozen-lockfile
+RUN --mount=type=cache,id=openclaw-pnpm-store,target=/root/.local/share/pnpm/store,sharing=locked \
+    NODE_OPTIONS=--max-old-space-size=2048 pnpm install --frozen-lockfile
 
 COPY . .
 
+# Normalize extension paths now so runtime COPY preserves safe modes
+# without adding a second full extensions layer.
+RUN for dir in /app/extensions /app/.agent /app/.agents; do \
+      if [ -d "$dir" ]; then \
+        find "$dir" -type d -exec chmod 755 {} +; \
+        find "$dir" -type f -exec chmod 644 {} +; \
+      fi; \
+    done
+
 # A2UI bundle may fail under QEMU cross-compilation (e.g. building amd64
 # on Apple Silicon). CI builds natively per-arch so this is a no-op there.
 # Stub it so local cross-arch builds still succeed.
@@ -67,11 +78,17 @@ RUN pnpm canvas:a2ui:bundle || \
      echo "/* A2UI bundle unavailable in this build */" > src/canvas-host/a2ui/a2ui.bundle.js && \
      echo "stub" > src/canvas-host/a2ui/.bundle.hash && \
      rm -rf vendor/a2ui apps/shared/OpenClawKit/Tools/CanvasA2UI)
-RUN pnpm build
+RUN pnpm build:docker
 # Force pnpm for UI build (Bun may fail on ARM/Synology architectures)
 ENV OPENCLAW_PREFER_PNPM=1
 RUN pnpm ui:build
 
+# Prune dev dependencies and strip build-only metadata before copying
+# runtime assets into the final image.
+FROM build AS runtime-assets
+RUN CI=true pnpm prune --prod && \
+    find dist -type f \( -name '*.d.ts' -o -name '*.d.mts' -o -name '*.d.cts' -o -name '*.map' \) -delete
+
 # ── Runtime base images ─────────────────────────────────────────
 FROM ${OPENCLAW_NODE_BOOKWORM_IMAGE} AS base-default
 ARG OPENCLAW_NODE_BOOKWORM_DIGEST
@@ -102,36 +119,39 @@ WORKDIR /app
 
 # Install system utilities present in bookworm but missing in bookworm-slim.
 # On the full bookworm image these are already installed (apt-get is a no-op).
-RUN apt-get update && \
+RUN --mount=type=cache,id=openclaw-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,id=openclaw-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
+    apt-get update && \
     DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
-      procps hostname curl git openssl && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*
+      procps hostname curl git openssl
 
 RUN chown node:node /app
 
-COPY --from=build --chown=node:node /app/dist ./dist
-COPY --from=build --chown=node:node /app/node_modules ./node_modules
-COPY --from=build --chown=node:node /app/package.json .
-COPY --from=build --chown=node:node /app/openclaw.mjs .
-COPY --from=build --chown=node:node /app/extensions ./extensions
-COPY --from=build --chown=node:node /app/skills ./skills
-COPY --from=build --chown=node:node /app/docs ./docs
+COPY --from=runtime-assets --chown=node:node /app/dist ./dist
+COPY --from=runtime-assets --chown=node:node /app/node_modules ./node_modules
+COPY --from=runtime-assets --chown=node:node /app/package.json .
+COPY --from=runtime-assets --chown=node:node /app/openclaw.mjs .
+COPY --from=runtime-assets --chown=node:node /app/extensions ./extensions
+COPY --from=runtime-assets --chown=node:node /app/skills ./skills
+COPY --from=runtime-assets --chown=node:node /app/docs ./docs
 
-# Docker live-test runners invoke `pnpm` inside the runtime image.
-# Activate the exact pinned package manager now so the container does not
-# rely on a first-run network fetch or missing shims under the non-root user.
-RUN corepack enable && \
-    corepack prepare "$(node -p "require('./package.json').packageManager")" --activate
+# Keep pnpm available in the runtime image for container-local workflows.
+# Use a shared Corepack home so the non-root `node` user does not need a
+# first-run network fetch when invoking pnpm.
+ENV COREPACK_HOME=/usr/local/share/corepack
+RUN install -d -m 0755 "$COREPACK_HOME" && \
+    corepack enable && \
+    corepack prepare "$(node -p "require('./package.json').packageManager")" --activate && \
+    chmod -R a+rX "$COREPACK_HOME"
 
 # Install additional system packages needed by your skills or extensions.
 # Example: docker build --build-arg OPENCLAW_DOCKER_APT_PACKAGES="python3 wget" .
 ARG OPENCLAW_DOCKER_APT_PACKAGES=""
-RUN if [ -n "$OPENCLAW_DOCKER_APT_PACKAGES" ]; then \
+RUN --mount=type=cache,id=openclaw-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,id=openclaw-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
+    if [ -n "$OPENCLAW_DOCKER_APT_PACKAGES" ]; then \
       apt-get update && \
-      DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends $OPENCLAW_DOCKER_APT_PACKAGES && \
-      apt-get clean && \
-      rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*; \
+      DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends $OPENCLAW_DOCKER_APT_PACKAGES; \
     fi
 
 # Optionally install Chromium and Xvfb for browser automation.
@@ -139,15 +159,15 @@ RUN if [ -n "$OPENCLAW_DOCKER_APT_PACKAGES" ]; then \
 # Adds ~300MB but eliminates the 60-90s Playwright install on every container start.
 # Must run after node_modules COPY so playwright-core is available.
 ARG OPENCLAW_INSTALL_BROWSER=""
-RUN if [ -n "$OPENCLAW_INSTALL_BROWSER" ]; then \
+RUN --mount=type=cache,id=openclaw-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,id=openclaw-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
+    if [ -n "$OPENCLAW_INSTALL_BROWSER" ]; then \
       apt-get update && \
       DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends xvfb && \
       mkdir -p /home/node/.cache/ms-playwright && \
       PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright \
       node /app/node_modules/playwright-core/cli.js install --with-deps chromium && \
-      chown -R node:node /home/node/.cache/ms-playwright && \
-      apt-get clean && \
-      rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*; \
+      chown -R node:node /home/node/.cache/ms-playwright; \
     fi
 
 # Optionally install Docker CLI for sandbox container management.
@@ -156,7 +176,9 @@ RUN if [ -n "$OPENCLAW_INSTALL_BROWSER" ]; then \
 # Required for agents.defaults.sandbox to function in Docker deployments.
 ARG OPENCLAW_INSTALL_DOCKER_CLI=""
 ARG OPENCLAW_DOCKER_GPG_FINGERPRINT="9DC858229FC7DD38854AE2D88D81803C0EBFCD88"
-RUN if [ -n "$OPENCLAW_INSTALL_DOCKER_CLI" ]; then \
+RUN --mount=type=cache,id=openclaw-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,id=openclaw-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
+    if [ -n "$OPENCLAW_INSTALL_DOCKER_CLI" ]; then \
       apt-get update && \
       DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
         ca-certificates curl gnupg && \
@@ -177,20 +199,9 @@ RUN if [ -n "$OPENCLAW_INSTALL_DOCKER_CLI" ]; then \
         "$(dpkg --print-architecture)" > /etc/apt/sources.list.d/docker.list && \
       apt-get update && \
       DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
-        docker-ce-cli docker-compose-plugin && \
-      apt-get clean && \
-      rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*; \
+        docker-ce-cli docker-compose-plugin; \
     fi
 
-# Normalize extension paths so plugin safety checks do not reject
-# world-writable directories inherited from source file modes.
-RUN for dir in /app/extensions /app/.agent /app/.agents; do \
-      if [ -d "$dir" ]; then \
-        find "$dir" -type d -exec chmod 755 {} +; \
-        find "$dir" -type f -exec chmod 644 {} +; \
-      fi; \
-    done
-
 # Expose the CLI binary without requiring npm global writes as non-root.
 RUN ln -sf /app/openclaw.mjs /usr/local/bin/openclaw \
  && chmod 755 /app/openclaw.mjs

Dockerfile.sandbox

@@ -1,8 +1,12 @@
+# syntax=docker/dockerfile:1.7
+
 FROM debian:bookworm-slim@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
 
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN apt-get update \
+RUN --mount=type=cache,id=openclaw-sandbox-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
+  --mount=type=cache,id=openclaw-sandbox-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
+  apt-get update \
   && apt-get install -y --no-install-recommends \
     bash \
     ca-certificates \
@@ -10,8 +14,7 @@ RUN apt-get update \
     git \
     jq \
     python3 \
-    ripgrep \
-  && rm -rf /var/lib/apt/lists/*
+    ripgrep
 
 RUN useradd --create-home --shell /bin/bash sandbox
 USER sandbox

Dockerfile.sandbox-browser

@@ -1,8 +1,12 @@
+# syntax=docker/dockerfile:1.7
+
 FROM debian:bookworm-slim@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
 
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN apt-get update \
+RUN --mount=type=cache,id=openclaw-sandbox-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
+  --mount=type=cache,id=openclaw-sandbox-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
+  apt-get update \
   && apt-get install -y --no-install-recommends \
     bash \
     ca-certificates \
@@ -17,11 +21,9 @@ RUN apt-get update \
     socat \
     websockify \
     x11vnc \
-    xvfb \
-  && rm -rf /var/lib/apt/lists/*
+    xvfb
 
-COPY scripts/sandbox-browser-entrypoint.sh /usr/local/bin/openclaw-sandbox-browser
-RUN chmod +x /usr/local/bin/openclaw-sandbox-browser
+COPY --chmod=755 scripts/sandbox-browser-entrypoint.sh /usr/local/bin/openclaw-sandbox-browser
 
 RUN useradd --create-home --shell /bin/bash sandbox
 USER sandbox

Dockerfile.sandbox-common

@@ -1,3 +1,5 @@
+# syntax=docker/dockerfile:1.7
+
 ARG BASE_IMAGE=openclaw-sandbox:bookworm-slim
 FROM ${BASE_IMAGE}
 
@@ -19,9 +21,10 @@ ENV HOMEBREW_CELLAR=${BREW_INSTALL_DIR}/Cellar
 ENV HOMEBREW_REPOSITORY=${BREW_INSTALL_DIR}/Homebrew
 ENV PATH=${BUN_INSTALL_DIR}/bin:${BREW_INSTALL_DIR}/bin:${BREW_INSTALL_DIR}/sbin:${PATH}
 
-RUN apt-get update \
-  && apt-get install -y --no-install-recommends ${PACKAGES} \
-  && rm -rf /var/lib/apt/lists/*
+RUN --mount=type=cache,id=openclaw-sandbox-common-apt-cache,target=/var/cache/apt,sharing=locked \
+  --mount=type=cache,id=openclaw-sandbox-common-apt-lists,target=/var/lib/apt,sharing=locked \
+  apt-get update \
+  && apt-get install -y --no-install-recommends ${PACKAGES}
 
 RUN if [ "${INSTALL_PNPM}" = "1" ]; then npm install -g pnpm; fi
 
@@ -42,4 +45,3 @@ fi
 
 # Default is sandbox, but allow BASE_IMAGE overrides to select another final user.
 USER ${FINAL_USER}
-

SECURITY.md

@@ -125,6 +125,7 @@ Plugins/extensions are part of OpenClaw's trusted computing base for a gateway.
 - Any report whose only claim is that an operator-enabled `dangerous*`/`dangerously*` config option weakens defaults (these are explicit break-glass tradeoffs by design)
 - Reports that depend on trusted operator-supplied configuration values to trigger availability impact (for example custom regex patterns). These may still be fixed as defense-in-depth hardening, but are not security-boundary bypasses.
 - Reports whose only claim is heuristic/parity drift in command-risk detection (for example obfuscation-pattern checks) across exec surfaces, without a demonstrated trust-boundary bypass. These are hardening-only findings and are not vulnerabilities; triage may close them as `invalid`/`no-action` or track them separately as low/informational hardening.
+- Reports whose only claim is that exec approvals do not semantically model every interpreter/runtime loader form, subcommand, flag combination, package script, or transitive module/config import. Exec approvals bind exact request context and best-effort direct local file operands; they are not a complete semantic model of everything a runtime may load.
 - Exposed secrets that are third-party/user-controlled credentials (not OpenClaw-owned and not granting access to OpenClaw-operated infrastructure/services) without demonstrated OpenClaw impact
 - Reports whose only claim is host-side exec when sandbox runtime is disabled/unavailable (documented default behavior in the trusted-operator model), without a boundary bypass.
 - Reports whose only claim is that a platform-provided upload destination URL is untrusted (for example Microsoft Teams `fileConsent/invoke` `uploadInfo.uploadUrl`) without proving attacker control in an authenticated production flow.
@@ -165,6 +166,7 @@ OpenClaw separates routing from execution, but both remain inside the same opera
 - **Gateway** is the control plane. If a caller passes Gateway auth, they are treated as a trusted operator for that Gateway.
 - **Node** is an execution extension of the Gateway. Pairing a node grants operator-level remote capability on that node.
 - **Exec approvals** (allowlist/ask UI) are operator guardrails to reduce accidental command execution, not a multi-tenant authorization boundary.
+- Exec approvals bind exact command/cwd/env context and, when OpenClaw can identify one concrete local script/file operand, that file snapshot too. This is best-effort integrity hardening, not a complete semantic model of every interpreter/runtime loader path.
 - Differences in command-risk warning heuristics between exec surfaces (`gateway`, `node`, `sandbox`) do not, by themselves, constitute a security-boundary bypass.
 - For untrusted-user isolation, split by trust boundary: separate gateways and separate OS users/hosts per boundary.
 

appcast.xml

@@ -2,6 +2,80 @@
 <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
     <channel>
         <title>OpenClaw</title>
+        <item>
+            <title>2026.3.8-beta.1</title>
+            <pubDate>Mon, 09 Mar 2026 07:19:57 +0000</pubDate>
+            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
+            <sparkle:version>2026030801</sparkle:version>
+            <sparkle:shortVersionString>2026.3.8-beta.1</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>OpenClaw 2026.3.8-beta.1</h2>
+<h3>Changes</h3>
+<ul>
+<li>CLI/backup: add <code>openclaw backup create</code> and <code>openclaw backup verify</code> for local state archives, including <code>--only-config</code>, <code>--no-include-workspace</code>, manifest/payload validation, and backup guidance in destructive flows. (#40163) thanks @shichangs.</li>
+<li>macOS/onboarding: add a remote gateway token field for remote mode, preserve existing non-plaintext <code>gateway.remote.token</code> config values until explicitly replaced, and warn when the loaded token shape cannot be used directly from the macOS app. (#40187, supersedes #34614) Thanks @cgdusek.</li>
+<li>Talk mode: add top-level <code>talk.silenceTimeoutMs</code> config so Talk waits a configurable amount of silence before auto-sending the current transcript, while keeping each platform's existing default pause window when unset. (#39607) Thanks @danodoesdesign. Fixes #17147.</li>
+<li>TUI: infer the active agent from the current workspace when launched inside a configured agent workspace, while preserving explicit <code>agent:</code> session targets. (#39591) thanks @arceus77-7.</li>
+<li>Tools/Brave web search: add opt-in <code>tools.web.search.brave.mode: "llm-context"</code> so <code>web_search</code> can call Brave's LLM Context endpoint and return extracted grounding snippets with source metadata, plus config/docs/test coverage. (#33383) Thanks @thirumaleshp.</li>
+<li>CLI/install: include the short git commit hash in <code>openclaw --version</code> output when metadata is available, and keep installer version checks compatible with the decorated format. (#39712) thanks @sourman.</li>
+<li>CLI/backup: improve archive naming for date sorting, add config-only backup mode, and harden backup planning, publication, and verification edge cases. (#40163) Thanks @gumadeiras.</li>
+<li>ACP/Provenance: add optional ACP ingress provenance metadata and visible receipt injection (<code>openclaw acp --provenance off|meta|meta+receipt</code>) so OpenClaw agents can retain and report ACP-origin context with session trace IDs. (#40473) thanks @mbelinky.</li>
+<li>Tools/web search: alphabetize provider ordering across runtime selection, onboarding/configure pickers, and config metadata, so provider lists stay neutral and multi-key auto-detect now prefers Grok before Kimi. (#40259) thanks @kesku.</li>
+<li>Docs/Web search: restore $5/month free-credit details, replace defunct "Data for Search"/"Data for AI" plan names with current "Search" plan, and note legacy subscription validity in Brave setup docs. Follows up on #26860. (#40111) Thanks @remusao.</li>
+<li>Extensions/ACPX tests: move the shared runtime fixture helper from <code>src/runtime-internals/</code> to <code>src/test-utils/</code> so the test-only helper no longer looks like shipped runtime code.</li>
+</ul>
+<h3>Fixes</h3>
+<ul>
+<li>macOS app/chat UI: route browser proxy through the local node browser service, preserve plain-text paste semantics, strip completed assistant trace/debug wrapper noise from transcripts, refresh permission state after returning from System Settings, and tolerate malformed cron rows in the macOS tab. (#39516) Thanks @Imhermes1.</li>
+<li>Android/Play distribution: remove self-update, background location, <code>screen.record</code>, and background mic capture from the Android app, narrow the foreground service to <code>dataSync</code> only, and clean up the legacy <code>location.enabledMode=always</code> preference migration. (#39660) Thanks @obviyus.</li>
+<li>Telegram/DM routing: dedupe inbound Telegram DMs per agent instead of per session key so the same DM cannot trigger duplicate replies when both <code>agent:main:main</code> and <code>agent:main:telegram:direct:<id></code> resolve for one agent. Fixes #40005. Supersedes #40116. (#40519) thanks @obviyus.</li>
+<li>Cron/Telegram announce delivery: route text-only announce jobs through the real outbound adapters after finalizing descendant output so plain Telegram targets no longer report <code>delivered: true</code> when no message actually reached Telegram. (#40575) thanks @obviyus.</li>
+<li>Matrix/DM routing: add safer fallback detection for broken <code>m.direct</code> homeservers, honor explicit room bindings over DM classification, and preserve room-bound agent selection for Matrix DM rooms. (#19736) Thanks @derbronko.</li>
+<li>Feishu/plugin onboarding: clear the short-lived plugin discovery cache before reloading the registry after installing a channel plugin, so onboarding no longer re-prompts to download Feishu immediately after a successful install. Fixes #39642. (#39752) Thanks @GazeKingNuWu.</li>
+<li>Plugins/channel onboarding: prefer bundled channel plugins over duplicate npm-installed copies during onboarding and release-channel sync, preventing bundled plugins from being shadowed by npm installs with the same plugin ID. (#40092)</li>
+<li>Config/runtime snapshots: keep secrets-runtime-resolved config and auth-profile snapshots intact after config writes so follow-up reads still see file-backed secret values while picking up the persisted config update. (#37313) thanks @bbblending.</li>
+<li>Gateway/Control UI: resolve bundled dashboard assets through symlinked global wrappers and auto-detected package roots, while keeping configured and custom roots on the strict hardlink boundary. (#40385) Thanks @LarytheLord.</li>
+<li>Browser/extension relay: add <code>browser.relayBindHost</code> so the Chrome relay can bind to an explicit non-loopback address for WSL2 and other cross-namespace setups, while preserving loopback-only defaults. (#39364) Thanks @mvanhorn.</li>
+<li>Browser/CDP: normalize loopback direct WebSocket CDP URLs back to HTTP(S) for <code>/json/*</code> tab operations so local <code>ws://</code> / <code>wss://</code> profiles can still list, focus, open, and close tabs after the new direct-WS support lands. (#31085) Thanks @shrey150.</li>
+<li>Browser/CDP: rewrite wildcard <code>ws://0.0.0.0</code> and <code>ws://[::]</code> debugger URLs from remote <code>/json/version</code> responses back to the external CDP host/port, fixing Browserless-style container endpoints. (#17760) Thanks @joeharouni.</li>
+<li>Browser/extension relay: wait briefly for a previously attached Chrome tab to reappear after transient relay drops before failing with <code>tab not found</code>, reducing noisy reconnect flakes. (#32461) Thanks @AaronWander.</li>
+<li>macOS/Tailscale gateway discovery: keep Tailscale Serve probing alive when other remote gateways are already discovered, prefer direct transport for resolved <code>.ts.net</code> and Tailscale Serve gateways, and set <code>TERM=dumb</code> for GUI-launched Tailscale CLI discovery. (#40167) thanks @ngutman.</li>
+<li>TUI/theme: detect light terminal backgrounds via <code>COLORFGBG</code> and pick a WCAG AA-compliant light palette, with <code>OPENCLAW_THEME=light|dark</code> override for terminals without auto-detection. (#38636) Thanks @ademczuk and @vincentkoc.</li>
+<li>Agents/openai-codex: normalize <code>gpt-5.4</code> fallback transport back to <code>openai-codex-responses</code> on <code>chatgpt.com/backend-api</code> when config drifts to the generic OpenAI responses endpoint. (#38736) Thanks @0xsline.</li>
+<li>Models/openai-codex GPT-5.4 forward-compat: use the GPT-5.4 1,050,000-token context window and 128,000 max tokens for <code>openai-codex/gpt-5.4</code> instead of inheriting stale legacy Codex limits in resolver fallbacks and model listing. (#37876) thanks @yuweuii.</li>
+<li>Tools/web search: restore Perplexity OpenRouter/Sonar compatibility for legacy <code>OPENROUTER_API_KEY</code>, <code>sk-or-...</code>, and explicit <code>perplexity.baseUrl</code> / <code>model</code> setups while keeping direct Perplexity keys on the native Search API path. (#39937) Thanks @obviyus.</li>
+<li>Agents/failover: detect Amazon Bedrock <code>Too many tokens per day</code> quota errors as rate limits across fallback, cron retry, and memory embeddings while keeping context-window <code>too many tokens per request</code> errors out of the rate-limit lane. (#39377) Thanks @gambletan.</li>
+<li>Mattermost replies: keep <code>root_id</code> pinned to the existing thread root when an agent replies inside a thread, while still using reply-target threading for top-level posts. (#27744) thanks @hnykda.</li>
+<li>Telegram/DM partial streaming: keep DM preview lanes on real message edits instead of native draft materialization so final replies no longer flash a second duplicate copy before collapsing back to one.</li>
+<li>macOS overlays: fix VoiceWake, Talk, and Notify overlay exclusivity crashes by removing shared <code>inout</code> visibility mutation from <code>OverlayPanelFactory.present</code>, and add a repeated Talk overlay smoke test. (#39275, #39321) Thanks @fellanH.</li>
+<li>macOS Talk Mode: set the speech recognition request <code>taskHint</code> to <code>.dictation</code> for mic capture, and add regression coverage for the request defaults. (#38445) Thanks @dmiv.</li>
+<li>macOS release packaging: default <code>scripts/package-mac-app.sh</code> to universal binaries for <code>BUILD_CONFIG=release</code>, and clarify that <code>scripts/package-mac-dist.sh</code> already produces the release zip + DMG. (#33891) Thanks @cgdusek.</li>
+<li>Hooks/session-memory: keep <code>/new</code> and <code>/reset</code> memory artifacts in the bound agent workspace and align saved reset session keys with that workspace when stale main-agent keys leak into the hook path. (#39875) thanks @rbutera.</li>
+<li>Sessions/model switch: clear stale cached <code>contextTokens</code> when a session changes models so status and runtime paths recompute against the active model window. (#38044) thanks @yuweuii.</li>
+<li>ACP/session history: persist transcripts for successful ACP child runs, preserve exact transcript text, record ACP spawned-session lineage, and keep spawn-time transcript-path persistence best-effort so history storage failures do not block execution. (#40137) thanks @mbelinky.</li>
+<li>Docs/browser: add a layered WSL2 + Windows remote Chrome CDP troubleshooting guide, including Control UI origin pitfalls and extension-relay bind-address guidance. (#39407) Thanks @Owlock.</li>
+<li>Context engine registry/bundled builds: share the registry state through a <code>globalThis</code> singleton so duplicated bundled module copies can resolve engines registered by each other at runtime, with regression coverage for duplicate-module imports. (#40115) thanks @jalehman.</li>
+<li>Podman/setup: fix <code>cannot chdir: Permission denied</code> in <code>run_as_user</code> when <code>setup-podman.sh</code> is invoked from a directory the target user cannot access, by wrapping user-switch calls in a subshell that cd's to <code>/tmp</code> with <code>/</code> fallback. (#39435) Thanks @langdon and @jlcbk.</li>
+<li>Podman/SELinux: auto-detect SELinux enforcing/permissive mode and add <code>:Z</code> relabel to bind mounts in <code>run-openclaw-podman.sh</code> and the Quadlet template, fixing <code>EACCES</code> on Fedora/RHEL hosts. Supports <code>OPENCLAW_BIND_MOUNT_OPTIONS</code> override. (#39449) Thanks @langdon and @githubbzxs.</li>
+<li>Agents/context-engine plugins: bootstrap runtime plugins once at embedded-run, compaction, and subagent boundaries so plugin-provided context engines and hooks load from the active workspace before runtime resolution. (#40232)</li>
+<li>Docs/Changelog: correct the contributor credit for the bundled Control UI global-install fix to @LarytheLord. (#40420) Thanks @velvet-shark.</li>
+<li>Telegram/media downloads: time out only stalled body reads so polling recovers from hung file downloads without aborting slow downloads that are still streaming data. (#40098) thanks @tysoncung.</li>
+<li>Docker/runtime image: prune dev dependencies, strip build-only dist metadata for smaller Docker images. (#40307) Thanks @vincentkoc.</li>
+<li>Gateway/restart timeout recovery: exit non-zero when restart-triggered shutdown drains time out so launchd/systemd restart the gateway instead of treating the failed restart as a clean stop. Landed from contributor PR #40380 by @dsantoreis. Thanks @dsantoreis.</li>
+<li>Gateway/config restart guard: validate config before service start/restart and keep post-SIGUSR1 startup failures from crashing the gateway process, reducing invalid-config restart loops and macOS permission loss. Landed from contributor PR #38699 by @lml2468. Thanks @lml2468.</li>
+<li>Gateway/launchd respawn detection: treat <code>XPC_SERVICE_NAME</code> as a launchd supervision hint so macOS restarts exit cleanly under launchd instead of attempting detached self-respawn. Landed from contributor PR #20555 by @dimat. Thanks @dimat.</li>
+<li>Telegram/poll restart cleanup: abort the in-flight Telegram API fetch when shutdown or forced polling restarts stop a runner, preventing stale <code>getUpdates</code> long polls from colliding with the replacement runner. Landed from contributor PR #23950 by @Gkinthecodeland. Thanks @Gkinthecodeland.</li>
+<li>Cron/restart catch-up staggering: limit immediate missed-job replay on startup and reschedule the deferred remainder from the post-catchup clock so restart bursts do not starve the gateway or silently skip overdue recurring jobs. Landed from contributor PR #18925 by @rexlunae. Thanks @rexlunae.</li>
+<li>Cron/owner-only tools: pass trusted isolated cron runs into the embedded agent with owner context so <code>cron</code>/<code>gateway</code> tooling remains available after the owner-auth hardening narrowed direct-message ownership inference.</li>
+<li>Browser/SSRF: block private-network intermediate redirect hops in strict browser navigation flows and fail closed when remote tab-open paths cannot inspect redirect chains. Thanks @zpbrent.</li>
+<li>MS Teams/authz: keep <code>groupPolicy: "allowlist"</code> enforcing sender allowlists even when a team/channel route allowlist is configured, so route matches no longer widen group access to every sender in that route. Thanks @zpbrent.</li>
+<li>Security/system.run: bind approved <code>bun</code> and <code>deno run</code> script operands to on-disk file snapshots so post-approval script rewrites are denied before execution.</li>
+<li>Skills/download installs: pin the validated per-skill tools root before writing downloaded archives, so rebinding the lexical tools path cannot redirect download writes outside the intended tools directory. Thanks @tdjackey.</li>
+</ul>
+<p><a href="https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.3.8-beta.1/OpenClaw-2026.3.8-beta.1.zip" length="23407015" type="application/octet-stream" sparkle:edSignature="KCqhSmu4b0tHf55RqcQOHorsc55CgBI5BUmK/NTizxNq04INn/7QvsamHYQou9DbB2IW6B2nawBC4nn4au5yDA=="/>
+        </item>
         <item>
             <title>2026.3.7</title>
             <pubDate>Sun, 08 Mar 2026 04:42:35 +0000</pubDate>
@@ -584,144 +658,5 @@
             <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.3.2/OpenClaw-2026.3.2.zip" length="23181513" type="application/octet-stream" sparkle:edSignature="THMgkcoMgz2vv5zse3Po3K7l3Or2RhBKurXZIi8iYVXN76yJy1YXAY6kXi6ovD+dbYn68JKYDIKA1Ya78bO7BQ=="/>
             <!-- pragma: allowlist secret -->
         </item>
-        <item>
-            <title>2026.3.1</title>
-            <pubDate>Mon, 02 Mar 2026 04:40:59 +0000</pubDate>
-            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
-            <sparkle:version>2026030190</sparkle:version>
-            <sparkle:shortVersionString>2026.3.1</sparkle:shortVersionString>
-            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>OpenClaw 2026.3.1</h2>
-<h3>Changes</h3>
-<ul>
-<li>Agents/Thinking defaults: set <code>adaptive</code> as the default thinking level for Anthropic Claude 4.6 models (including Bedrock Claude 4.6 refs) while keeping other reasoning-capable models at <code>low</code> unless explicitly configured.</li>
-<li>Gateway/Container probes: add built-in HTTP liveness/readiness endpoints (<code>/health</code>, <code>/healthz</code>, <code>/ready</code>, <code>/readyz</code>) for Docker/Kubernetes health checks, with fallback routing so existing handlers on those paths are not shadowed. (#31272) Thanks @vincentkoc.</li>
-<li>Android/Nodes: add <code>camera.list</code>, <code>device.permissions</code>, <code>device.health</code>, and <code>notifications.actions</code> (<code>open</code>/<code>dismiss</code>/<code>reply</code>) on Android nodes, plus first-class node-tool actions for the new device/notification commands. (#28260) Thanks @obviyus.</li>
-<li>Discord/Thread bindings: replace fixed TTL lifecycle with inactivity (<code>idleHours</code>, default 24h) plus optional hard <code>maxAgeHours</code> lifecycle controls, and add <code>/session idle</code> + <code>/session max-age</code> commands for focused thread-bound sessions. (#27845) Thanks @osolmaz.</li>
-<li>Telegram/DM topics: add per-DM <code>direct</code> + topic config (allowlists, <code>dmPolicy</code>, <code>skills</code>, <code>systemPrompt</code>, <code>requireTopic</code>), route DM topics as distinct inbound/outbound sessions, and enforce topic-aware authorization/debounce for messages, callbacks, commands, and reactions. Landed from contributor PR #30579 by @kesor. Thanks @kesor.</li>
-<li>Web UI/Cron i18n: localize cron page labels, filters, form help text, and validation/error messaging in English and zh-CN. (#29315) Thanks @BUGKillerKing.</li>
-<li>OpenAI/Streaming transport: make <code>openai</code> Responses WebSocket-first by default (<code>transport: "auto"</code> with SSE fallback), add shared OpenAI WS stream/connection runtime wiring with per-session cleanup, and preserve server-side compaction payload mutation (<code>store</code> + <code>context_management</code>) on the WS path.</li>
-<li>Android/Gateway capability refresh: add live Android capability integration coverage and node canvas capability refresh wiring, plus runtime hardening for A2UI readiness retries, scoped canvas URL normalization, debug diagnostics JSON, and JavaScript MIME delivery. (#28388) Thanks @obviyus.</li>
-<li>Android/Nodes parity: add <code>system.notify</code>, <code>photos.latest</code>, <code>contacts.search</code>/<code>contacts.add</code>, <code>calendar.events</code>/<code>calendar.add</code>, and <code>motion.activity</code>/<code>motion.pedometer</code>, with motion sensor-aware command gating and improved activity sampling reliability. (#29398) Thanks @obviyus.</li>
-<li>CLI/Config: add <code>openclaw config file</code> to print the active config file path resolved from <code>OPENCLAW_CONFIG_PATH</code> or the default location. (#26256) thanks @cyb1278588254.</li>
-<li>Feishu/Docx tables + uploads: add <code>feishu_doc</code> actions for Docx table creation/cell writing (<code>create_table</code>, <code>write_table_cells</code>, <code>create_table_with_values</code>) and image/file uploads (<code>upload_image</code>, <code>upload_file</code>) with stricter create/upload error handling for missing <code>document_id</code> and placeholder cleanup failures. (#20304) Thanks @xuhao1.</li>
-<li>Feishu/Reactions: add inbound <code>im.message.reaction.created_v1</code> handling, route verified reactions through synthetic inbound turns, and harden verification with timeout + fail-closed filtering so non-bot or unverified reactions are dropped. (#16716) Thanks @schumilin.</li>
-<li>Feishu/Chat tooling: add <code>feishu_chat</code> tool actions for chat info and member queries, with configurable enablement under <code>channels.feishu.tools.chat</code>. (#14674) Thanks @liuweifly.</li>
-<li>Feishu/Doc permissions: support optional owner permission grant fields on <code>feishu_doc</code> create and report permission metadata only when the grant call succeeds, with regression coverage for success/failure/omitted-owner paths. (#28295) Thanks @zhoulongchao77.</li>
-<li>Web UI/i18n: add German (<code>de</code>) locale support and auto-render language options from supported locale constants in Overview settings. (#28495) thanks @dsantoreis.</li>
-<li>Tools/Diffs: add a new optional <code>diffs</code> plugin tool for read-only diff rendering from before/after text or unified patches, with gateway viewer URLs for canvas and PNG image output. Thanks @gumadeiras.</li>
-<li>Memory/LanceDB: support custom OpenAI <code>baseUrl</code> and embedding dimensions for LanceDB memory. (#17874) Thanks @rish2jain and @vincentkoc.</li>
-<li>ACP/ACPX streaming: pin ACPX plugin support to <code>0.1.15</code>, add configurable ACPX command/version probing, and streamline ACP stream delivery (<code>final_only</code> default + reduced tool-event noise) with matching runtime and test updates. (#30036) Thanks @osolmaz.</li>
-<li>Shell env markers: set <code>OPENCLAW_SHELL</code> across shell-like runtimes (<code>exec</code>, <code>acp</code>, <code>acp-client</code>, <code>tui-local</code>) so shell startup/config rules can target OpenClaw contexts consistently, and document the markers in env/exec/acp/TUI docs. Thanks @vincentkoc.</li>
-<li>Cron/Heartbeat light bootstrap context: add opt-in lightweight bootstrap mode for automation runs (<code>--light-context</code> for cron agent turns and <code>agents.*.heartbeat.lightContext</code> for heartbeat), keeping only <code>HEARTBEAT.md</code> for heartbeat runs and skipping bootstrap-file injection for cron lightweight runs. (#26064) Thanks @jose-velez.</li>
-<li>OpenAI/WebSocket warm-up: add optional OpenAI Responses WebSocket warm-up (<code>response.create</code> with <code>generate:false</code>), enable it by default for <code>openai/*</code>, and expose <code>params.openaiWsWarmup</code> for per-model enable/disable control.</li>
-<li>Agents/Subagents runtime events: replace ad-hoc subagent completion system-message handoff with typed internal completion events (<code>task_completion</code>) that are rendered consistently across direct and queued announce paths, with gateway/CLI plumbing for structured <code>internalEvents</code>.</li>
-</ul>
-<h3>Breaking</h3>
-<ul>
-<li><strong>BREAKING:</strong> Node exec approval payloads now require <code>systemRunPlan</code>. <code>host=node</code> approval requests without that plan are rejected.</li>
-<li><strong>BREAKING:</strong> Node <code>system.run</code> execution now pins path-token commands to the canonical executable path (<code>realpath</code>) in both allowlist and approval execution flows. Integrations/tests that asserted token-form argv (for example <code>tr</code>) must now accept canonical paths (for example <code>/usr/bin/tr</code>).</li>
-</ul>
-<h3>Fixes</h3>
-<ul>
-<li>Android/Nodes reliability: reject <code>facing=both</code> when <code>deviceId</code> is set to avoid mislabeled duplicate captures, allow notification <code>open</code>/<code>reply</code> on non-clearable entries while still gating dismiss, trigger listener rebind before notification actions, and scale invoke-result ack timeout to invoke budget for large clip payloads. (#28260) Thanks @obviyus.</li>
-<li>Windows/Plugin install: avoid <code>spawn EINVAL</code> on Windows npm/npx invocations by resolving to <code>node</code> + npm CLI scripts instead of spawning <code>.cmd</code> directly. Landed from contributor PR #31147 by @codertony. Thanks @codertony.</li>
-<li>LINE/Voice transcription: classify M4A voice media as <code>audio/mp4</code> (not <code>video/mp4</code>) by checking the MPEG-4 <code>ftyp</code> major brand (<code>M4A </code> / <code>M4B </code>), restoring voice transcription for LINE voice messages. Landed from contributor PR #31151 by @scoootscooob. Thanks @scoootscooob.</li>
-<li>Slack/Announce target account routing: enable session-backed announce-target lookup for Slack so multi-account announces resolve the correct <code>accountId</code> instead of defaulting to bot-token context. Landed from contributor PR #31028 by @taw0002. Thanks @taw0002.</li>
-<li>Android/Voice screen TTS: stream assistant speech via ElevenLabs WebSocket in Talk Mode, stop cleanly on speaker mute/barge-in, and ignore stale out-of-order stream events. (#29521) Thanks @gregmousseau.</li>
-<li>Android/Photos permissions: declare Android 14+ selected-photo access permission (<code>READ_MEDIA_VISUAL_USER_SELECTED</code>) and align Android permission/settings paths with current minSdk behavior for more reliable permission state handling.</li>
-<li>Web UI/Cron: include configured agent model defaults/fallbacks in cron model suggestions so scheduled-job model autocomplete reflects configured models. (#29709) Thanks @Sid-Qin.</li>
-<li>Cron/Delivery: disable the agent messaging tool when <code>delivery.mode</code> is <code>"none"</code> so cron output is not sent to Telegram or other channels. (#21808) Thanks @lailoo.</li>
-<li>CLI/Cron: clarify <code>cron list</code> output by renaming <code>Agent</code> to <code>Agent ID</code> and adding a <code>Model</code> column for isolated agent-turn jobs. (#26259) Thanks @openperf.</li>
-<li>Feishu/Reply media attachments: send Feishu reply <code>mediaUrl</code>/<code>mediaUrls</code> payloads as attachments alongside text/streamed replies in the reply dispatcher, including legacy fallback when <code>mediaUrls</code> is empty. (#28959) Thanks @icesword0760.</li>
-<li>Slack/User-token resolution: normalize Slack account user-token sourcing through resolved account metadata (<code>SLACK_USER_TOKEN</code> env + config) so monitor reads, Slack actions, directory lookups, onboarding allow-from resolution, and capabilities probing consistently use the effective user token. (#28103) Thanks @Glucksberg.</li>
-<li>Feishu/Outbound session routing: stop assuming bare <code>oc_</code> identifiers are always group chats, honor explicit <code>dm:</code>/<code>group:</code> prefixes for <code>oc_</code> chat IDs, and default ambiguous bare <code>oc_</code> targets to direct routing to avoid DM session misclassification. (#10407) Thanks @Bermudarat.</li>
-<li>Feishu/Group session routing: add configurable group session scopes (<code>group</code>, <code>group_sender</code>, <code>group_topic</code>, <code>group_topic_sender</code>) with legacy <code>topicSessionMode=enabled</code> compatibility so Feishu group conversations can isolate sessions by sender/topic as configured. (#17798) Thanks @yfge.</li>
-<li>Feishu/Reply-in-thread routing: add <code>replyInThread</code> config (<code>disabled|enabled</code>) for group replies, propagate <code>reply_in_thread</code> across text/card/media/streaming sends, and align topic-scoped session routing so newly created reply threads stay on the same session root. (#27325) Thanks @kcinzgg.</li>
-<li>Feishu/Probe status caching: cache successful <code>probeFeishu()</code> bot-info results for 10 minutes (bounded cache with per-account keying) to reduce repeated status/onboarding probe API calls, while bypassing cache for failures and exceptions. (#28907) Thanks @Glucksberg.</li>
-<li>Feishu/Opus media send type: send <code>.opus</code> attachments with <code>msg_type: "audio"</code> (instead of <code>"media"</code>) so Feishu voice messages deliver correctly while <code>.mp4</code> remains <code>msg_type: "media"</code> and documents remain <code>msg_type: "file"</code>. (#28269) Thanks @Glucksberg.</li>
-<li>Feishu/Mobile video media type: treat inbound <code>message_type: "media"</code> as video-equivalent for media key extraction, placeholder inference, and media download resolution so mobile-app video sends ingest correctly. (#25502) Thanks @4ier.</li>
-<li>Feishu/Inbound sender fallback: fall back to <code>sender_id.user_id</code> when <code>sender_id.open_id</code> is missing on inbound events, and use ID-type-aware sender lookup so mobile-delivered messages keep stable sender identity/routing. (#26703) Thanks @NewdlDewdl.</li>
-<li>Feishu/Reply context metadata: include inbound <code>parent_id</code> and <code>root_id</code> as <code>ReplyToId</code>/<code>RootMessageId</code> in inbound context, and parse interactive-card quote bodies into readable text when fetching replied messages. (#18529) Thanks @qiangu.</li>
-<li>Feishu/Post embedded media: extract <code>media</code> tags from inbound rich-text (<code>post</code>) messages and download embedded video/audio files alongside existing embedded-image handling, with regression coverage. (#21786) Thanks @laopuhuluwa.</li>
-<li>Feishu/Local media sends: propagate <code>mediaLocalRoots</code> through Feishu outbound media sending into <code>loadWebMedia</code> so local path attachments work with post-CVE local-root enforcement. (#27884) Thanks @joelnishanth.</li>
-<li>Feishu/Group wildcard policy fallback: honor <code>channels.feishu.groups["*"]</code> when no explicit group match exists so unmatched groups inherit wildcard reply-policy settings instead of falling back to global defaults. (#29456) Thanks @WaynePika.</li>
-<li>Feishu/Inbound media regression coverage: add explicit tests for message resource type mapping (<code>image</code> stays <code>image</code>, non-image maps to <code>file</code>) to prevent reintroducing unsupported Feishu <code>type=audio</code> fetches. (#16311, #8746) Thanks @Yaxuan42.</li>
-<li>TTS/Voice bubbles: use opus output and enable <code>audioAsVoice</code> routing for Feishu and WhatsApp (in addition to Telegram) so supported channels receive voice-bubble playback instead of file-style audio attachments. (#27366) Thanks @smthfoxy.</li>
-<li>Telegram/Reply media context: include replied media files in inbound context when replying to media, defer reply-media downloads to debounce flush, gate reply-media fetch behind DM authorization, and preserve replied media when non-vision sticker fallback runs (including cached-sticker paths). (#28488) Thanks @obviyus.</li>
-<li>Android/Nodes notification wake flow: enable Android <code>system.notify</code> default allowlist, emit <code>notifications.changed</code> events for posted/removed notifications (excluding OpenClaw app-owned notifications), canonicalize notification session keys before enqueue/wake routing, and skip heartbeat wakes when consecutive notification summaries dedupe. (#29440) Thanks @obviyus.</li>
-<li>Telegram/Voice fallback reply chunking: apply reply reference, quote text, and inline buttons only to the first fallback text chunk when voice delivery is blocked, preventing over-quoted multi-chunk replies. Landed from contributor PR #31067 by @xdanger. Thanks @xdanger.</li>
-<li>Feishu/Multi-account + reply reliability: add <code>channels.feishu.defaultAccount</code> outbound routing support with schema validation, keep quoted-message extraction text-first (post/interactive/file placeholders instead of raw JSON), route Feishu video sends as <code>msg_type: "file"</code>, and avoid websocket event blocking by using non-blocking event handling in monitor dispatch. Landed from contributor PRs #29610, #30432, #30331, and #29501. Thanks @hclsys, @bmendonca3, @patrick-yingxi-pan, and @zwffff.</li>
-<li>Cron/Delivery: disable the agent messaging tool when <code>delivery.mode</code> is <code>"none"</code> so cron output is not sent to Telegram or other channels. (#21808) Thanks @lailoo.</li>
-<li>Feishu/Inbound rich-text parsing: preserve <code>share_chat</code> payload summaries when available and add explicit parsing for rich-text <code>code</code>/<code>code_block</code>/<code>pre</code> tags so forwarded and code-heavy messages keep useful context in agent input. (#28591) Thanks @kevinWangSheng.</li>
-<li>Feishu/Post markdown parsing: parse rich-text <code>post</code> payloads through a shared markdown-aware parser with locale-wrapper support, preserved mention/image metadata extraction, and inline/fenced code fidelity for agent input rendering. (#12755) Thanks @WilsonLiu95.</li>
-<li>Telegram/Outbound chunking: route oversize splitting through the shared outbound pipeline (including subagents), retry Telegram sends when escaped HTML exceeds limits, and preserve boundary whitespace when retry re-splitting rendered chunks so plain-text/transcript fidelity is retained. (#29342, #27317; follow-up to #27461) Thanks @obviyus.</li>
-<li>Slack/Native commands: register Slack native status as <code>/agentstatus</code> (Slack-reserved <code>/status</code>) so manifest slash command registration stays valid while text <code>/status</code> still works. Landed from contributor PR #29032 by @maloqab. Thanks @maloqab.</li>
-<li>Android/Camera clip: remove <code>camera.clip</code> HTTP-upload fallback to base64 so clip transport is deterministic and fail-loud, and reject non-positive <code>maxWidth</code> values so invalid inputs fall back to the safe resize default. (#28229) Thanks @obviyus.</li>
-<li>Android/Gateway canvas capability refresh: send <code>node.canvas.capability.refresh</code> with object <code>params</code> (<code>{}</code>) from Android node runtime so gateway object-schema validation accepts refresh retries and A2UI host recovery works after scoped capability expiry. (#28413) Thanks @obviyus.</li>
-<li>Gateway/Control UI origins: honor <code>gateway.controlUi.allowedOrigins: ["*"]</code> wildcard entries (including trimmed values) and lock behavior with regression tests. Landed from contributor PR #31058 by @byungsker. Thanks @byungsker.</li>
-<li>Web UI/Cron: include configured agent model defaults/fallbacks in cron model suggestions so scheduled-job model autocomplete reflects configured models. (#29709) Thanks @Sid-Qin.</li>
-<li>Agents/Sessions list transcript paths: handle missing/non-string/relative <code>sessions.list.path</code> values and per-agent <code>{agentId}</code> templates when deriving <code>transcriptPath</code>, so cross-agent session listings resolve to concrete agent session files instead of workspace-relative paths. (#24775) Thanks @martinfrancois.</li>
-<li>Gateway/Control UI CSP: allow required Google Fonts origins in Control UI CSP. (#29279) Thanks @Glucksberg and @vincentkoc.</li>
-<li>CLI/Install: add an npm-link fallback to fix CLI startup <code>Permission denied</code> failures (<code>exit 127</code>) on affected installs. (#17151) Thanks @sskyu and @vincentkoc.</li>
-<li>Onboarding/Custom providers: improve verification reliability for slower local endpoints (for example Ollama) during setup. (#27380) Thanks @Sid-Qin.</li>
-<li>Plugins/NPM spec install: fix npm-spec plugin installs when <code>npm pack</code> output is empty by detecting newly created <code>.tgz</code> archives in the pack directory. (#21039) Thanks @graysurf and @vincentkoc.</li>
-<li>Plugins/Install: clear stale install errors when an npm package is not found so follow-up install attempts report current state correctly. (#25073) Thanks @dalefrieswthat.</li>
-<li>Security/Feishu webhook ingress: bound unauthenticated webhook rate-limit state with stale-window pruning and a hard key cap to prevent unbounded pre-auth memory growth from rotating source keys. (#26050) Thanks @bmendonca3.</li>
-<li>Gateway/macOS supervised restart: actively <code>launchctl kickstart -k</code> during intentional supervised restarts to bypass LaunchAgent <code>ThrottleInterval</code> delays, and fall back to in-process restart when kickstart fails. Landed from contributor PR #29078 by @cathrynlavery. Thanks @cathrynlavery.</li>
-<li>Daemon/macOS TLS certs: default LaunchAgent service env <code>NODE_EXTRA_CA_CERTS</code> to <code>/etc/ssl/cert.pem</code> (while preserving explicit overrides) so HTTPS clients no longer fail with local-issuer errors under launchd. (#27915) Thanks @Lukavyi.</li>
-<li>Discord/Components wildcard handlers: use distinct internal registration sentinel IDs and parse those sentinels as wildcard keys so select/user/role/channel/mentionable/modal interactions are not dropped by raw customId dedupe paths. Landed from contributor PR #29459 by @Sid-Qin. Thanks @Sid-Qin.</li>
-<li>Feishu/Reaction notifications: add <code>channels.feishu.reactionNotifications</code> (<code>off | own | all</code>, default <code>own</code>) so operators can disable reaction ingress or allow all verified reaction events (not only bot-authored message reactions). (#28529) Thanks @cowboy129.</li>
-<li>Feishu/Typing backoff: re-throw Feishu typing add/remove rate-limit and quota errors (<code>429</code>, <code>99991400</code>, <code>99991403</code>) and detect SDK non-throwing backoff responses so the typing keepalive circuit breaker can stop retries instead of looping indefinitely. (#28494) Thanks @guoqunabc.</li>
-<li>Feishu/Zalo runtime logging: replace direct <code>console.log/error</code> usage in Feishu typing-indicator paths and Zalo monitor paths with runtime-gated logger calls so verbosity controls are respected while preserving typing backoff behavior. (#18841) Thanks @Clawborn.</li>
-<li>Feishu/Group sender allowlist fallback: add global <code>channels.feishu.groupSenderAllowFrom</code> sender authorization for group chats, with per-group <code>groups.<id>.allowFrom</code> precedence and regression coverage for allow/block/precedence behavior. (#29174) Thanks @1MoreBuild.</li>
-<li>Feishu/Docx append/write ordering: insert converted Docx blocks sequentially (single-block creates) so Feishu append/write preserves markdown block order instead of returning shuffled sections in asynchronous batch inserts. (#26172, #26022) Thanks @echoVic.</li>
-<li>Feishu/Docx convert fallback chunking: recursively split oversized markdown chunks (including long no-heading sections) when <code>document.convert</code> hits content limits, while keeping fenced-code-aware split boundaries whenever possible. (#14402) Thanks @lml2468.</li>
-<li>Feishu/API quota controls: add <code>typingIndicator</code> and <code>resolveSenderNames</code> config flags (top-level and per-account) so operators can disable typing reactions and sender-name lookup requests while keeping default behavior unchanged. (#10513) Thanks @BigUncle.</li>
-<li>Feishu/System preview prompt leakage: stop enqueuing inbound Feishu message previews as system events so user preview text is not injected into later turns as trusted <code>System:</code> context. Landed from contributor PR #31209 by @stakeswky. Thanks @stakeswky.</li>
-<li>Feishu/Typing replay suppression: skip typing indicators for stale replayed inbound messages after compaction using message-age checks with second/millisecond timestamp normalization, preventing old-message reaction floods while preserving typing for fresh messages. Landed from contributor PR #30709 by @arkyu2077. Thanks @arkyu2077.</li>
-<li>Sessions/Internal routing: preserve established external <code>lastTo</code>/<code>lastChannel</code> routes for internal/non-deliverable turns, with added coverage for no-fallback internal routing behavior. Landed from contributor PR #30941 by @graysurf. Thanks @graysurf.</li>
-<li>Control UI/Debug log layout: render Debug Event Log payloads at full width to prevent payload JSON from being squeezed into a narrow side column. Landed from contributor PR #30978 by @stozo04. Thanks @stozo04.</li>
-<li>Auto-reply/NO_REPLY: strip <code>NO_REPLY</code> token from mixed-content messages instead of leaking raw control text to end users. Landed from contributor PR #31080 by @scoootscooob. Thanks @scoootscooob.</li>
-<li>Install/npm: fix npm global install deprecation warnings. (#28318) Thanks @vincentkoc.</li>
-<li>Update/Global npm: fallback to <code>--omit=optional</code> when global <code>npm update</code> fails so optional dependency install failures no longer abort update flows. (#24896) Thanks @xinhuagu and @vincentkoc.</li>
-<li>Inbound metadata/Multi-account routing: include <code>account_id</code> in trusted inbound metadata so multi-account channel sessions can reliably disambiguate the receiving account in prompt context. Landed from contributor PR #30984 by @Stxle2. Thanks @Stxle2.</li>
-<li>Model directives/Auth profiles: split <code>/model</code> profile suffixes at the first <code>@</code> after the last slash so email-based auth profile IDs (for example OAuth profile IDs) resolve correctly. Landed from contributor PR #30932 by @haosenwang1018. Thanks @haosenwang1018.</li>
-<li>Cron/Delivery mode none: send explicit <code>delivery: { mode: "none" }</code> from cron editor for both add and update flows so previous announce delivery is actually cleared. Landed from contributor PR #31145 by @byungsker. Thanks @byungsker.</li>
-<li>Cron editor viewport: make the sticky cron edit form independently scrollable with viewport-bounded height so lower fields/actions are reachable on shorter screens. Landed from contributor PR #31133 by @Sid-Qin. Thanks @Sid-Qin.</li>
-<li>Agents/Thinking fallback: when providers reject unsupported thinking levels without enumerating alternatives, retry with <code>think=off</code> to avoid hard failure during model/provider fallback chains. Landed from contributor PR #31002 by @yfge. Thanks @yfge.</li>
-<li>Ollama/Embedded runner base URL precedence: prioritize configured provider <code>baseUrl</code> over model defaults for embedded Ollama runs so Docker and remote-host setups avoid localhost fetch failures. (#30964) Thanks @stakeswky.</li>
-<li>Agents/Failover reason classification: avoid false rate-limit classification from incidental <code>tpm</code> substrings by matching TPM as a standalone token/phrase and keeping auth-context errors on the auth path. Landed from contributor PR #31007 by @HOYALIM. Thanks @HOYALIM.</li>
-<li>CLI/Cron: clarify <code>cron list</code> output by renaming <code>Agent</code> to <code>Agent ID</code> and adding a <code>Model</code> column for isolated agent-turn jobs. (#26259) Thanks @openperf.</li>
-<li>Gateway/WS: close repeated post-handshake <code>unauthorized role:*</code> request floods per connection and sample duplicate rejection logs, preventing a single misbehaving client from degrading gateway responsiveness. (#20168) Thanks @acy103, @vibecodooor, and @vincentkoc.</li>
-<li>Gateway/Auth: improve device-auth v2 migration diagnostics so operators get clearer guidance when legacy clients connect. (#28305) Thanks @vincentkoc.</li>
-<li>CLI/Ollama config: allow <code>config set</code> for Ollama <code>apiKey</code> without predeclared provider config. (#29299) Thanks @vincentkoc.</li>
-<li>Ollama/Autodiscovery: harden autodiscovery and warning behavior. (#29201) Thanks @marcodelpin and @vincentkoc.</li>
-<li>Ollama/Context window: unify context window handling across discovery, merge, and OpenAI-compatible transport paths. (#29205) Thanks @Sid-Qin, @jimmielightner, and @vincentkoc.</li>
-<li>Agents/Ollama: demote empty-discovery logging from <code>warn</code> to <code>debug</code> to reduce noisy warnings in normal edge-case discovery flows. (#26379) Thanks @byungsker.</li>
-<li>fix(model): preserve reasoning in provider fallback resolution. (#29285) Fixes #25636. Thanks @vincentkoc.</li>
-<li>Docker/Image permissions: normalize <code>/app/extensions</code>, <code>/app/.agent</code>, and <code>/app/.agents</code> to directory mode <code>755</code> and file mode <code>644</code> during image build so plugin discovery does not block inherited world-writable paths. (#30191) Fixes #30139. Thanks @edincampara.</li>
-<li>OpenAI Responses/Compaction: rewrite and unify the OpenAI Responses store patches to treat empty <code>baseUrl</code> as non-direct, honor <code>compat.supportsStore=false</code>, and auto-inject server-side compaction <code>context_management</code> for compatible direct OpenAI models (with per-model opt-out/threshold overrides). Landed from contributor PRs #16930 (@OiPunk), #22441 (@EdwardWu7), and #25088 (@MoerAI). Thanks @OiPunk, @EdwardWu7, and @MoerAI.</li>
-<li>Sandbox/Browser Docker: pass <code>OPENCLAW_BROWSER_NO_SANDBOX=1</code> to sandbox browser containers and bump sandbox browser security hash epoch so existing containers are recreated and pick up the env on upgrade. (#29879) Thanks @Lukavyi.</li>
-<li>Usage normalization: clamp negative prompt/input token values to zero (including <code>prompt_tokens</code> alias inputs) so <code>/usage</code> and TUI usage displays cannot show nonsensical negative counts. Landed from contributor PR #31211 by @scoootscooob. Thanks @scoootscooob.</li>
-<li>Secrets/Auth profiles: normalize inline SecretRef <code>token</code>/<code>key</code> values to canonical <code>tokenRef</code>/<code>keyRef</code> before persistence, and keep explicit <code>keyRef</code> precedence when inline refs are also present. Landed from contributor PR #31047 by @minupla. Thanks @minupla.</li>
-<li>Tools/Edit workspace boundary errors: preserve the real <code>Path escapes workspace root</code> failure path instead of surfacing a misleading access/file-not-found error when editing outside workspace roots. Landed from contributor PR #31015 by @haosenwang1018. Thanks @haosenwang1018.</li>
-<li>Browser/Open & navigate: accept <code>url</code> as an alias parameter for <code>open</code> and <code>navigate</code>. (#29260) Thanks @vincentkoc.</li>
-<li>Codex/Usage window: label weekly usage window as <code>Week</code> instead of <code>Day</code>. (#26267) Thanks @Sid-Qin.</li>
-<li>Signal/Sync message null-handling: treat <code>syncMessage</code> presence (including <code>null</code>) as sync envelope traffic so replayed sentTranscript payloads cannot bypass loop guards after daemon restart. Landed from contributor PR #31138 by @Sid-Qin. Thanks @Sid-Qin.</li>
-<li>Infra/fs-safe: sanitize directory-read failures so raw <code>EISDIR</code> text never leaks to messaging surfaces, with regression tests for both root-scoped and direct safe reads. Landed from contributor PR #31205 by @polooooo. Thanks @polooooo.</li>
-<li>Sandbox/mkdirp boundary checks: allow directory-safe boundary validation for existing in-boundary subdirectories, preventing false <code>cannot create directories</code> failures in sandbox write mode. (#30610) Thanks @glitch418x.</li>
-<li>Security/Compaction audit: remove the post-compaction audit injection message. (#28507) Thanks @fuller-stack-dev and @vincentkoc.</li>
-<li>Web tools/RFC2544 fake-IP compatibility: allow RFC2544 benchmark range (<code>198.18.0.0/15</code>) for trusted web-tool fetch endpoints so proxy fake-IP networking modes do not trigger false SSRF blocks. Landed from contributor PR #31176 by @sunkinux. Thanks @sunkinux.</li>
-<li>Telegram/Voice fallback reply chunking: apply reply reference, quote text, and inline buttons only to the first fallback text chunk when voice delivery is blocked, preventing over-quoted multi-chunk replies. Landed from contributor PR #31067 by @xdanger. Thanks @xdanger.</li>
-<li>Feishu/System preview prompt leakage: stop enqueuing inbound Feishu message previews as system events so user preview text is not injected into later turns as trusted <code>System:</code> context. Landed from contributor PR #31209 by @stakeswky. Thanks @stakeswky.</li>
-<li>Feishu/Multi-account + reply reliability: add <code>channels.feishu.defaultAccount</code> outbound routing support with schema validation, keep quoted-message extraction text-first (post/interactive/file placeholders instead of raw JSON), route Feishu video sends as <code>msg_type: "file"</code>, and avoid websocket event blocking by using non-blocking event handling in monitor dispatch. Landed from contributor PRs #29610, #30432, #30331, and #29501. Thanks @hclsys, @bmendonca3, @patrick-yingxi-pan, and @zwffff.</li>
-<li>Feishu/Typing replay suppression: skip typing indicators for stale replayed inbound messages after compaction using message-age checks with second/millisecond timestamp normalization, preventing old-message reaction floods while preserving typing for fresh messages. Landed from contributor PR #30709 by @arkyu2077. Thanks @arkyu2077.</li>
-</ul>
-<p><a href="https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md">View full changelog</a></p>
-]]></description>
-            <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.3.1/OpenClaw-2026.3.1.zip" length="12804155" type="application/octet-stream" sparkle:edSignature="TF1otD4Vk3pG0iViX7mvix5DQEgAsk4JkSFvH7opjf9aawV16f29SUa2wRmiCFU6HEgyNgnGI/078O+A27eXCA=="/>
-            <!-- pragma: allowlist secret -->
-        </item>
     </channel>
 </rss>

apps/android/app/build.gradle.kts

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

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

@@ -0,0 +1,5 @@
+package ai.openclaw.app.voice
+
+internal object TalkDefaults {
+  const val defaultSilenceTimeoutMs = 700L
+}

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

@@ -0,0 +1,161 @@
+package ai.openclaw.app.voice
+
+import ai.openclaw.app.normalizeMainKey
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.contentOrNull
+
+internal data class TalkProviderConfigSelection(
+  val provider: String,
+  val config: JsonObject,
+  val normalizedPayload: Boolean,
+)
+
+internal data class TalkModeGatewayConfigState(
+  val activeProvider: String,
+  val normalizedPayload: Boolean,
+  val missingResolvedPayload: Boolean,
+  val mainSessionKey: String,
+  val defaultVoiceId: String?,
+  val voiceAliases: Map<String, String>,
+  val defaultModelId: String,
+  val defaultOutputFormat: String,
+  val apiKey: String?,
+  val interruptOnSpeech: Boolean?,
+  val silenceTimeoutMs: Long,
+)
+
+internal object TalkModeGatewayConfigParser {
+  private const val defaultTalkProvider = "elevenlabs"
+
+  fun parse(
+    config: JsonObject?,
+    defaultProvider: String,
+    defaultModelIdFallback: String,
+    defaultOutputFormatFallback: String,
+    envVoice: String?,
+    sagVoice: String?,
+    envKey: String?,
+  ): TalkModeGatewayConfigState {
+    val talk = config?.get("talk").asObjectOrNull()
+    val selection = selectTalkProviderConfig(talk)
+    val activeProvider = selection?.provider ?: defaultProvider
+    val activeConfig = selection?.config
+    val sessionCfg = config?.get("session").asObjectOrNull()
+    val mainKey = normalizeMainKey(sessionCfg?.get("mainKey").asStringOrNull())
+    val voice = activeConfig?.get("voiceId")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
+    val aliases =
+      activeConfig?.get("voiceAliases").asObjectOrNull()?.entries?.mapNotNull { (key, value) ->
+        val id = value.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() } ?: return@mapNotNull null
+        normalizeTalkAliasKey(key).takeIf { it.isNotEmpty() }?.let { it to id }
+      }?.toMap().orEmpty()
+    val model = activeConfig?.get("modelId")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
+    val outputFormat =
+      activeConfig?.get("outputFormat")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
+    val key = activeConfig?.get("apiKey")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
+    val interrupt = talk?.get("interruptOnSpeech")?.asBooleanOrNull()
+    val silenceTimeoutMs = resolvedSilenceTimeoutMs(talk)
+
+    return TalkModeGatewayConfigState(
+      activeProvider = activeProvider,
+      normalizedPayload = selection?.normalizedPayload == true,
+      missingResolvedPayload = talk != null && selection == null,
+      mainSessionKey = mainKey,
+      defaultVoiceId =
+        if (activeProvider == defaultProvider) {
+          voice ?: envVoice?.takeIf { it.isNotEmpty() } ?: sagVoice?.takeIf { it.isNotEmpty() }
+        } else {
+          voice
+        },
+      voiceAliases = aliases,
+      defaultModelId = model ?: defaultModelIdFallback,
+      defaultOutputFormat = outputFormat ?: defaultOutputFormatFallback,
+      apiKey = key ?: envKey?.takeIf { it.isNotEmpty() },
+      interruptOnSpeech = interrupt,
+      silenceTimeoutMs = silenceTimeoutMs,
+    )
+  }
+
+  fun fallback(
+    defaultProvider: String,
+    defaultModelIdFallback: String,
+    defaultOutputFormatFallback: String,
+    envVoice: String?,
+    sagVoice: String?,
+    envKey: String?,
+  ): TalkModeGatewayConfigState =
+    TalkModeGatewayConfigState(
+      activeProvider = defaultProvider,
+      normalizedPayload = false,
+      missingResolvedPayload = false,
+      mainSessionKey = "main",
+      defaultVoiceId = envVoice?.takeIf { it.isNotEmpty() } ?: sagVoice?.takeIf { it.isNotEmpty() },
+      voiceAliases = emptyMap(),
+      defaultModelId = defaultModelIdFallback,
+      defaultOutputFormat = defaultOutputFormatFallback,
+      apiKey = envKey?.takeIf { it.isNotEmpty() },
+      interruptOnSpeech = null,
+      silenceTimeoutMs = TalkDefaults.defaultSilenceTimeoutMs,
+    )
+
+  fun selectTalkProviderConfig(talk: JsonObject?): TalkProviderConfigSelection? {
+    if (talk == null) return null
+    selectResolvedTalkProviderConfig(talk)?.let { return it }
+    val rawProvider = talk["provider"].asStringOrNull()
+    val rawProviders = talk["providers"].asObjectOrNull()
+    val hasNormalizedPayload = rawProvider != null || rawProviders != null
+    if (hasNormalizedPayload) {
+      return null
+    }
+    return TalkProviderConfigSelection(
+      provider = defaultTalkProvider,
+      config = talk,
+      normalizedPayload = false,
+    )
+  }
+
+  fun resolvedSilenceTimeoutMs(talk: JsonObject?): Long {
+    val fallback = TalkDefaults.defaultSilenceTimeoutMs
+    val primitive = talk?.get("silenceTimeoutMs") as? JsonPrimitive ?: return fallback
+    if (primitive.isString) return fallback
+    val timeout = primitive.content.toDoubleOrNull() ?: return fallback
+    if (timeout <= 0 || timeout % 1.0 != 0.0 || timeout > Long.MAX_VALUE.toDouble()) {
+      return fallback
+    }
+    return timeout.toLong()
+  }
+
+  private fun selectResolvedTalkProviderConfig(talk: JsonObject): TalkProviderConfigSelection? {
+    val resolved = talk["resolved"].asObjectOrNull() ?: return null
+    val providerId = normalizeTalkProviderId(resolved["provider"].asStringOrNull()) ?: return null
+    return TalkProviderConfigSelection(
+      provider = providerId,
+      config = resolved["config"].asObjectOrNull() ?: buildJsonObject {},
+      normalizedPayload = true,
+    )
+  }
+
+  private fun normalizeTalkProviderId(raw: String?): String? {
+    val trimmed = raw?.trim()?.lowercase().orEmpty()
+    return trimmed.takeIf { it.isNotEmpty() }
+  }
+}
+
+private fun normalizeTalkAliasKey(value: String): String =
+  value.trim().lowercase()
+
+private fun JsonElement?.asStringOrNull(): String? =
+  this?.let { element ->
+    element as? JsonPrimitive
+  }?.contentOrNull
+
+private fun JsonElement?.asBooleanOrNull(): Boolean? {
+  val primitive = this as? JsonPrimitive ?: return null
+  return primitive.booleanOrNull
+}
+
+private fun JsonElement?.asObjectOrNull(): JsonObject? =
+  this as? JsonObject

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

@@ -59,52 +59,11 @@ class TalkModeManager(
     private const val tag = "TalkMode"
     private const val defaultModelIdFallback = "eleven_v3"
     private const val defaultOutputFormatFallback = "pcm_24000"
-private const val defaultTalkProvider = "elevenlabs"
-    private const val silenceWindowMs = 500L
+    private const val defaultTalkProvider = "elevenlabs"
     private const val listenWatchdogMs = 12_000L
     private const val chatFinalWaitWithSubscribeMs = 45_000L
     private const val chatFinalWaitWithoutSubscribeMs = 6_000L
     private const val maxCachedRunCompletions = 128
-
-    internal data class TalkProviderConfigSelection(
-      val provider: String,
-      val config: JsonObject,
-      val normalizedPayload: Boolean,
-    )
-
-    private fun normalizeTalkProviderId(raw: String?): String? {
-      val trimmed = raw?.trim()?.lowercase().orEmpty()
-      return trimmed.takeIf { it.isNotEmpty() }
-    }
-
-    internal fun selectTalkProviderConfig(talk: JsonObject?): TalkProviderConfigSelection? {
-      if (talk == null) return null
-      val rawProvider = talk["provider"].asStringOrNull()
-      val rawProviders = talk["providers"].asObjectOrNull()
-      val hasNormalizedPayload = rawProvider != null || rawProviders != null
-      if (hasNormalizedPayload) {
-        val providers =
-          rawProviders?.entries?.mapNotNull { (key, value) ->
-            val providerId = normalizeTalkProviderId(key) ?: return@mapNotNull null
-            val providerConfig = value.asObjectOrNull() ?: return@mapNotNull null
-            providerId to providerConfig
-          }?.toMap().orEmpty()
-        val providerId =
-          normalizeTalkProviderId(rawProvider)
-            ?: providers.keys.sorted().firstOrNull()
-            ?: defaultTalkProvider
-        return TalkProviderConfigSelection(
-          provider = providerId,
-          config = providers[providerId] ?: buildJsonObject {},
-          normalizedPayload = true,
-        )
-      }
-      return TalkProviderConfigSelection(
-        provider = defaultTalkProvider,
-        config = talk,
-        normalizedPayload = false,
-      )
-    }
   }
 
   private val mainHandler = Handler(Looper.getMainLooper())
@@ -134,7 +93,7 @@ private const val defaultTalkProvider = "elevenlabs"
   private var listeningMode = false
 
   private var silenceJob: Job? = null
-  private val silenceWindowMs = 700L
+  private var silenceWindowMs = TalkDefaults.defaultSilenceTimeoutMs
   private var lastTranscript: String = ""
   private var lastHeardAtMs: Long? = null
   private var lastSpokenText: String? = null
@@ -854,7 +813,7 @@ private const val defaultTalkProvider = "elevenlabs"
     _lastAssistantText.value = cleaned
 
     val requestedVoice = directive?.voiceId?.trim()?.takeIf { it.isNotEmpty() }
-    val resolvedVoice = resolveVoiceAlias(requestedVoice)
+    val resolvedVoice = TalkModeVoiceResolver.resolveVoiceAlias(requestedVoice, voiceAliases)
     if (requestedVoice != null && resolvedVoice == null) {
       Log.w(tag, "unknown voice alias: $requestedVoice")
     }
@@ -877,12 +836,35 @@ private const val defaultTalkProvider = "elevenlabs"
       apiKey?.trim()?.takeIf { it.isNotEmpty() }
         ?: System.getenv("ELEVENLABS_API_KEY")?.trim()
     val preferredVoice = resolvedVoice ?: currentVoiceId ?: defaultVoiceId
-    val voiceId =
+    val resolvedPlaybackVoice =
       if (!apiKey.isNullOrEmpty()) {
-        resolveVoiceId(preferredVoice, apiKey)
+        try {
+          TalkModeVoiceResolver.resolveVoiceId(
+            preferred = preferredVoice,
+            fallbackVoiceId = fallbackVoiceId,
+            defaultVoiceId = defaultVoiceId,
+            currentVoiceId = currentVoiceId,
+            voiceOverrideActive = voiceOverrideActive,
+            listVoices = { TalkModeVoiceResolver.listVoices(apiKey, json) },
+          )
+        } catch (err: Throwable) {
+          Log.w(tag, "list voices failed: ${err.message ?: err::class.simpleName}")
+          null
+        }
       } else {
         null
       }
+    resolvedPlaybackVoice?.let { resolved ->
+      fallbackVoiceId = resolved.fallbackVoiceId
+      defaultVoiceId = resolved.defaultVoiceId
+      currentVoiceId = resolved.currentVoiceId
+      resolved.selectedVoiceName?.let { name ->
+        resolved.voiceId?.let { voiceId ->
+          Log.d(tag, "default voice selected $name ($voiceId)")
+        }
+      }
+    }
+    val voiceId = resolvedPlaybackVoice?.voiceId
 
     _statusText.value = "Speaking…"
     _isSpeaking.value = true
@@ -1393,60 +1375,64 @@ private const val defaultTalkProvider = "elevenlabs"
     try {
       val res = session.request("talk.config", """{"includeSecrets":true}""")
       val root = json.parseToJsonElement(res).asObjectOrNull()
-      val config = root?.get("config").asObjectOrNull()
-      val talk = config?.get("talk").asObjectOrNull()
-      val selection = selectTalkProviderConfig(talk)
-      val activeProvider = selection?.provider ?: defaultTalkProvider
-      val activeConfig = selection?.config
-      val sessionCfg = config?.get("session").asObjectOrNull()
-      val mainKey = normalizeMainKey(sessionCfg?.get("mainKey").asStringOrNull())
-      val voice = activeConfig?.get("voiceId")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
-      val aliases =
-        activeConfig?.get("voiceAliases").asObjectOrNull()?.entries?.mapNotNull { (key, value) ->
-          val id = value.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() } ?: return@mapNotNull null
-          normalizeAliasKey(key).takeIf { it.isNotEmpty() }?.let { it to id }
-        }?.toMap().orEmpty()
-      val model = activeConfig?.get("modelId")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
-      val outputFormat =
-        activeConfig?.get("outputFormat")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
-      val key = activeConfig?.get("apiKey")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
-      val interrupt = talk?.get("interruptOnSpeech")?.asBooleanOrNull()
+      val parsed =
+        TalkModeGatewayConfigParser.parse(
+          config = root?.get("config").asObjectOrNull(),
+          defaultProvider = defaultTalkProvider,
+          defaultModelIdFallback = defaultModelIdFallback,
+          defaultOutputFormatFallback = defaultOutputFormatFallback,
+          envVoice = envVoice,
+          sagVoice = sagVoice,
+          envKey = envKey,
+        )
+      if (parsed.missingResolvedPayload) {
+        Log.w(tag, "talk config ignored: normalized payload missing talk.resolved")
+      }
 
       if (!isCanonicalMainSessionKey(mainSessionKey)) {
-        mainSessionKey = mainKey
+        mainSessionKey = parsed.mainSessionKey
       }
-      defaultVoiceId =
-        if (activeProvider == defaultTalkProvider) {
-          voice ?: envVoice?.takeIf { it.isNotEmpty() } ?: sagVoice?.takeIf { it.isNotEmpty() }
-        } else {
-          voice
-        }
-      voiceAliases = aliases
+      defaultVoiceId = parsed.defaultVoiceId
+      voiceAliases = parsed.voiceAliases
       if (!voiceOverrideActive) currentVoiceId = defaultVoiceId
-      defaultModelId = model ?: defaultModelIdFallback
+      defaultModelId = parsed.defaultModelId
       if (!modelOverrideActive) currentModelId = defaultModelId
-      defaultOutputFormat = outputFormat ?: defaultOutputFormatFallback
-      apiKey = key ?: envKey?.takeIf { it.isNotEmpty() }
-      Log.d(tag, "reloadConfig apiKey=${if (apiKey != null) "set" else "null"} voiceId=$defaultVoiceId")
-      if (interrupt != null) interruptOnSpeech = interrupt
-      activeProviderIsElevenLabs = activeProvider == defaultTalkProvider
+      defaultOutputFormat = parsed.defaultOutputFormat
+      apiKey = parsed.apiKey
+      silenceWindowMs = parsed.silenceTimeoutMs
+      Log.d(
+        tag,
+        "reloadConfig apiKey=${if (apiKey != null) "set" else "null"} voiceId=$defaultVoiceId silenceTimeoutMs=${parsed.silenceTimeoutMs}",
+      )
+      if (parsed.interruptOnSpeech != null) interruptOnSpeech = parsed.interruptOnSpeech
+      activeProviderIsElevenLabs = parsed.activeProvider == defaultTalkProvider
       if (!activeProviderIsElevenLabs) {
         // Clear ElevenLabs credentials so playAssistant won't attempt ElevenLabs calls
         apiKey = null
         defaultVoiceId = null
         if (!voiceOverrideActive) currentVoiceId = null
-        Log.w(tag, "talk provider $activeProvider unsupported; using system voice fallback")
-      } else if (selection?.normalizedPayload == true) {
+        Log.w(tag, "talk provider ${parsed.activeProvider} unsupported; using system voice fallback")
+      } else if (parsed.normalizedPayload) {
         Log.d(tag, "talk config provider=elevenlabs")
       }
       configLoaded = true
     } catch (_: Throwable) {
-      defaultVoiceId = envVoice?.takeIf { it.isNotEmpty() } ?: sagVoice?.takeIf { it.isNotEmpty() }
-      defaultModelId = defaultModelIdFallback
+      val fallback =
+        TalkModeGatewayConfigParser.fallback(
+          defaultProvider = defaultTalkProvider,
+          defaultModelIdFallback = defaultModelIdFallback,
+          defaultOutputFormatFallback = defaultOutputFormatFallback,
+          envVoice = envVoice,
+          sagVoice = sagVoice,
+          envKey = envKey,
+        )
+      silenceWindowMs = fallback.silenceTimeoutMs
+      defaultVoiceId = fallback.defaultVoiceId
+      defaultModelId = fallback.defaultModelId
       if (!modelOverrideActive) currentModelId = defaultModelId
-      apiKey = envKey?.takeIf { it.isNotEmpty() }
-      voiceAliases = emptyMap()
-      defaultOutputFormat = defaultOutputFormatFallback
+      apiKey = fallback.apiKey
+      voiceAliases = fallback.voiceAliases
+      defaultOutputFormat = fallback.defaultOutputFormat
       // Keep config load retryable after transient fetch failures.
       configLoaded = false
     }
@@ -1740,82 +1726,6 @@ private const val defaultTalkProvider = "elevenlabs"
     }
   }
 
-  private fun resolveVoiceAlias(value: String?): String? {
-    val trimmed = value?.trim().orEmpty()
-    if (trimmed.isEmpty()) return null
-    val normalized = normalizeAliasKey(trimmed)
-    voiceAliases[normalized]?.let { return it }
-    if (voiceAliases.values.any { it.equals(trimmed, ignoreCase = true) }) return trimmed
-    return if (isLikelyVoiceId(trimmed)) trimmed else null
-  }
-
-  private suspend fun resolveVoiceId(preferred: String?, apiKey: String): String? {
-    val trimmed = preferred?.trim().orEmpty()
-    if (trimmed.isNotEmpty()) {
-      val resolved = resolveVoiceAlias(trimmed)
-      // If it resolves as an alias, use the alias target.
-      // Otherwise treat it as a direct voice ID (e.g. "21m00Tcm4TlvDq8ikWAM").
-      return resolved ?: trimmed
-    }
-    fallbackVoiceId?.let { return it }
-
-    return try {
-      val voices = listVoices(apiKey)
-      val first = voices.firstOrNull() ?: return null
-      fallbackVoiceId = first.voiceId
-      if (defaultVoiceId.isNullOrBlank()) {
-        defaultVoiceId = first.voiceId
-      }
-      if (!voiceOverrideActive) {
-        currentVoiceId = first.voiceId
-      }
-      val name = first.name ?: "unknown"
-      Log.d(tag, "default voice selected $name (${first.voiceId})")
-      first.voiceId
-    } catch (err: Throwable) {
-      Log.w(tag, "list voices failed: ${err.message ?: err::class.simpleName}")
-      null
-    }
-  }
-
-  private suspend fun listVoices(apiKey: String): List<ElevenLabsVoice> {
-    return withContext(Dispatchers.IO) {
-      val url = URL("https://api.elevenlabs.io/v1/voices")
-      val conn = url.openConnection() as HttpURLConnection
-      conn.requestMethod = "GET"
-      conn.connectTimeout = 15_000
-      conn.readTimeout = 15_000
-      conn.setRequestProperty("xi-api-key", apiKey)
-
-      val code = conn.responseCode
-      val stream = if (code >= 400) conn.errorStream else conn.inputStream
-      val data = stream.readBytes()
-      if (code >= 400) {
-        val message = data.toString(Charsets.UTF_8)
-        throw IllegalStateException("ElevenLabs voices failed: $code $message")
-      }
-
-      val root = json.parseToJsonElement(data.toString(Charsets.UTF_8)).asObjectOrNull()
-      val voices = (root?.get("voices") as? JsonArray) ?: JsonArray(emptyList())
-      voices.mapNotNull { entry ->
-        val obj = entry.asObjectOrNull() ?: return@mapNotNull null
-        val voiceId = obj["voice_id"].asStringOrNull() ?: return@mapNotNull null
-        val name = obj["name"].asStringOrNull()
-        ElevenLabsVoice(voiceId, name)
-      }
-    }
-  }
-
-  private fun isLikelyVoiceId(value: String): Boolean {
-    if (value.length < 10) return false
-    return value.all { it.isLetterOrDigit() || it == '-' || it == '_' }
-  }
-
-  private fun normalizeAliasKey(value: String): String =
-    value.trim().lowercase()
-
-  private data class ElevenLabsVoice(val voiceId: String, val name: String?)
-
   private val listener =
     object : RecognitionListener {
       override fun onReadyForSpeech(params: Bundle?) {

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

@@ -0,0 +1,118 @@
+package ai.openclaw.app.voice
+
+import java.net.HttpURLConnection
+import java.net.URL
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+
+internal data class ElevenLabsVoice(val voiceId: String, val name: String?)
+
+internal data class TalkModeResolvedVoice(
+  val voiceId: String?,
+  val fallbackVoiceId: String?,
+  val defaultVoiceId: String?,
+  val currentVoiceId: String?,
+  val selectedVoiceName: String? = null,
+)
+
+internal object TalkModeVoiceResolver {
+  fun resolveVoiceAlias(value: String?, voiceAliases: Map<String, String>): String? {
+    val trimmed = value?.trim().orEmpty()
+    if (trimmed.isEmpty()) return null
+    val normalized = normalizeAliasKey(trimmed)
+    voiceAliases[normalized]?.let { return it }
+    if (voiceAliases.values.any { it.equals(trimmed, ignoreCase = true) }) return trimmed
+    return if (isLikelyVoiceId(trimmed)) trimmed else null
+  }
+
+  suspend fun resolveVoiceId(
+    preferred: String?,
+    fallbackVoiceId: String?,
+    defaultVoiceId: String?,
+    currentVoiceId: String?,
+    voiceOverrideActive: Boolean,
+    listVoices: suspend () -> List<ElevenLabsVoice>,
+  ): TalkModeResolvedVoice {
+    val trimmed = preferred?.trim().orEmpty()
+    if (trimmed.isNotEmpty()) {
+      return TalkModeResolvedVoice(
+        voiceId = trimmed,
+        fallbackVoiceId = fallbackVoiceId,
+        defaultVoiceId = defaultVoiceId,
+        currentVoiceId = currentVoiceId,
+      )
+    }
+    if (!fallbackVoiceId.isNullOrBlank()) {
+      return TalkModeResolvedVoice(
+        voiceId = fallbackVoiceId,
+        fallbackVoiceId = fallbackVoiceId,
+        defaultVoiceId = defaultVoiceId,
+        currentVoiceId = currentVoiceId,
+      )
+    }
+
+    val first = listVoices().firstOrNull()
+    if (first == null) {
+      return TalkModeResolvedVoice(
+        voiceId = null,
+        fallbackVoiceId = fallbackVoiceId,
+        defaultVoiceId = defaultVoiceId,
+        currentVoiceId = currentVoiceId,
+      )
+    }
+
+    return TalkModeResolvedVoice(
+      voiceId = first.voiceId,
+      fallbackVoiceId = first.voiceId,
+      defaultVoiceId = if (defaultVoiceId.isNullOrBlank()) first.voiceId else defaultVoiceId,
+      currentVoiceId = if (voiceOverrideActive) currentVoiceId else first.voiceId,
+      selectedVoiceName = first.name,
+    )
+  }
+
+  suspend fun listVoices(apiKey: String, json: Json): List<ElevenLabsVoice> {
+    return withContext(Dispatchers.IO) {
+      val url = URL("https://api.elevenlabs.io/v1/voices")
+      val conn = url.openConnection() as HttpURLConnection
+      conn.requestMethod = "GET"
+      conn.connectTimeout = 15_000
+      conn.readTimeout = 15_000
+      conn.setRequestProperty("xi-api-key", apiKey)
+
+      val code = conn.responseCode
+      val stream = if (code >= 400) conn.errorStream else conn.inputStream
+      val data = stream.readBytes()
+      if (code >= 400) {
+        val message = data.toString(Charsets.UTF_8)
+        throw IllegalStateException("ElevenLabs voices failed: $code $message")
+      }
+
+      val root = json.parseToJsonElement(data.toString(Charsets.UTF_8)).asObjectOrNull()
+      val voices = (root?.get("voices") as? JsonArray) ?: JsonArray(emptyList())
+      voices.mapNotNull { entry ->
+        val obj = entry.asObjectOrNull() ?: return@mapNotNull null
+        val voiceId = obj["voice_id"].asStringOrNull() ?: return@mapNotNull null
+        val name = obj["name"].asStringOrNull()
+        ElevenLabsVoice(voiceId, name)
+      }
+    }
+  }
+
+  private fun isLikelyVoiceId(value: String): Boolean {
+    if (value.length < 10) return false
+    return value.all { it.isLetterOrDigit() || it == '-' || it == '_' }
+  }
+
+  private fun normalizeAliasKey(value: String): String =
+    value.trim().lowercase()
+}
+
+private fun JsonElement?.asObjectOrNull(): JsonObject? = this as? JsonObject
+
+private fun JsonElement?.asStringOrNull(): String? =
+  (this as? JsonPrimitive)?.takeIf { it.isString }?.content

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

@@ -0,0 +1,100 @@
+package ai.openclaw.app.voice
+
+import java.io.File
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+@Serializable
+private data class TalkConfigContractFixture(
+  @SerialName("selectionCases") val selectionCases: List<SelectionCase>,
+  @SerialName("timeoutCases") val timeoutCases: List<TimeoutCase>,
+) {
+  @Serializable
+  data class SelectionCase(
+    val id: String,
+    val defaultProvider: String,
+    val payloadValid: Boolean,
+    val expectedSelection: ExpectedSelection? = null,
+    val talk: JsonObject,
+  )
+
+  @Serializable
+  data class ExpectedSelection(
+    val provider: String,
+    val normalizedPayload: Boolean,
+    val voiceId: String? = null,
+    val apiKey: String? = null,
+  )
+
+  @Serializable
+  data class TimeoutCase(
+    val id: String,
+    val fallback: Long,
+    val expectedTimeoutMs: Long,
+    val talk: JsonObject,
+  )
+}
+
+class TalkModeConfigContractTest {
+  private val json = Json { ignoreUnknownKeys = true }
+
+  @Test
+  fun selectionFixtures() {
+    for (fixture in loadFixtures().selectionCases) {
+      val selection = TalkModeGatewayConfigParser.selectTalkProviderConfig(fixture.talk)
+      val expected = fixture.expectedSelection
+      if (expected == null) {
+        assertNull(fixture.id, selection)
+        continue
+      }
+      assertNotNull(fixture.id, selection)
+      assertEquals(fixture.id, expected.provider, selection?.provider)
+      assertEquals(fixture.id, expected.normalizedPayload, selection?.normalizedPayload)
+      assertEquals(
+        fixture.id,
+        expected.voiceId,
+        (selection?.config?.get("voiceId") as? JsonPrimitive)?.content,
+      )
+      assertEquals(
+        fixture.id,
+        expected.apiKey,
+        (selection?.config?.get("apiKey") as? JsonPrimitive)?.content,
+      )
+      assertEquals(fixture.id, true, fixture.payloadValid)
+    }
+  }
+
+  @Test
+  fun timeoutFixtures() {
+    for (fixture in loadFixtures().timeoutCases) {
+      val timeout = TalkModeGatewayConfigParser.resolvedSilenceTimeoutMs(fixture.talk)
+      assertEquals(fixture.id, fixture.expectedTimeoutMs, timeout)
+      assertEquals(fixture.id, TalkDefaults.defaultSilenceTimeoutMs, fixture.fallback)
+    }
+  }
+
+  private fun loadFixtures(): TalkConfigContractFixture {
+    val fixturePath = findFixtureFile()
+    return json.decodeFromString(File(fixturePath).readText())
+  }
+
+  private fun findFixtureFile(): String {
+    val startDir = System.getProperty("user.dir") ?: error("user.dir unavailable")
+    var current = File(startDir).absoluteFile
+    while (true) {
+      val candidate = File(current, "test-fixtures/talk-config-contract.json")
+      if (candidate.exists()) {
+        return candidate.absolutePath
+      }
+      current = current.parentFile ?: break
+    }
+    error("talk-config-contract.json not found from $startDir")
+  }
+}

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

@@ -13,6 +13,36 @@ import org.junit.Test
 class TalkModeConfigParsingTest {
   private val json = Json { ignoreUnknownKeys = true }
 
+  @Test
+  fun prefersCanonicalResolvedTalkProviderPayload() {
+    val talk =
+      json.parseToJsonElement(
+          """
+          {
+            "resolved": {
+              "provider": "elevenlabs",
+              "config": {
+                "voiceId": "voice-resolved"
+              }
+            },
+            "provider": "elevenlabs",
+            "providers": {
+              "elevenlabs": {
+                "voiceId": "voice-normalized"
+              }
+            }
+          }
+          """.trimIndent(),
+        )
+        .jsonObject
+
+    val selection = TalkModeGatewayConfigParser.selectTalkProviderConfig(talk)
+    assertNotNull(selection)
+    assertEquals("elevenlabs", selection?.provider)
+    assertTrue(selection?.normalizedPayload == true)
+    assertEquals("voice-resolved", selection?.config?.get("voiceId")?.jsonPrimitive?.content)
+  }
+
   @Test
   fun prefersNormalizedTalkProviderPayload() {
     val talk =
@@ -31,11 +61,52 @@ class TalkModeConfigParsingTest {
         )
         .jsonObject
 
-    val selection = TalkModeManager.selectTalkProviderConfig(talk)
-    assertNotNull(selection)
-    assertEquals("elevenlabs", selection?.provider)
-    assertTrue(selection?.normalizedPayload == true)
-    assertEquals("voice-normalized", selection?.config?.get("voiceId")?.jsonPrimitive?.content)
+    val selection = TalkModeGatewayConfigParser.selectTalkProviderConfig(talk)
+    assertEquals(null, selection)
+  }
+
+  @Test
+  fun rejectsNormalizedTalkProviderPayloadWhenProviderMissingFromProviders() {
+    val talk =
+      json.parseToJsonElement(
+          """
+          {
+            "provider": "acme",
+            "providers": {
+              "elevenlabs": {
+                "voiceId": "voice-normalized"
+              }
+            }
+          }
+          """.trimIndent(),
+        )
+        .jsonObject
+
+    val selection = TalkModeGatewayConfigParser.selectTalkProviderConfig(talk)
+    assertEquals(null, selection)
+  }
+
+  @Test
+  fun rejectsNormalizedTalkProviderPayloadWhenProviderIsAmbiguous() {
+    val talk =
+      json.parseToJsonElement(
+          """
+          {
+            "providers": {
+              "acme": {
+                "voiceId": "voice-acme"
+              },
+              "elevenlabs": {
+                "voiceId": "voice-normalized"
+              }
+            }
+          }
+          """.trimIndent(),
+        )
+        .jsonObject
+
+    val selection = TalkModeGatewayConfigParser.selectTalkProviderConfig(talk)
+    assertEquals(null, selection)
   }
 
   @Test
@@ -47,11 +118,46 @@ class TalkModeConfigParsingTest {
         put("apiKey", legacyApiKey) // pragma: allowlist secret
       }
 
-    val selection = TalkModeManager.selectTalkProviderConfig(talk)
+    val selection = TalkModeGatewayConfigParser.selectTalkProviderConfig(talk)
     assertNotNull(selection)
     assertEquals("elevenlabs", selection?.provider)
     assertTrue(selection?.normalizedPayload == false)
     assertEquals("voice-legacy", selection?.config?.get("voiceId")?.jsonPrimitive?.content)
     assertEquals("legacy-key", selection?.config?.get("apiKey")?.jsonPrimitive?.content)
   }
+
+  @Test
+  fun readsConfiguredSilenceTimeoutMs() {
+    val talk = buildJsonObject { put("silenceTimeoutMs", 1500) }
+
+    assertEquals(1500L, TalkModeGatewayConfigParser.resolvedSilenceTimeoutMs(talk))
+  }
+
+  @Test
+  fun defaultsSilenceTimeoutMsWhenMissing() {
+    assertEquals(
+      TalkDefaults.defaultSilenceTimeoutMs,
+      TalkModeGatewayConfigParser.resolvedSilenceTimeoutMs(null),
+    )
+  }
+
+  @Test
+  fun defaultsSilenceTimeoutMsWhenInvalid() {
+    val talk = buildJsonObject { put("silenceTimeoutMs", 0) }
+
+    assertEquals(
+      TalkDefaults.defaultSilenceTimeoutMs,
+      TalkModeGatewayConfigParser.resolvedSilenceTimeoutMs(talk),
+    )
+  }
+
+  @Test
+  fun defaultsSilenceTimeoutMsWhenString() {
+    val talk = buildJsonObject { put("silenceTimeoutMs", "1500") }
+
+    assertEquals(
+      TalkDefaults.defaultSilenceTimeoutMs,
+      TalkModeGatewayConfigParser.resolvedSilenceTimeoutMs(talk),
+    )
+  }
 }

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

@@ -0,0 +1,92 @@
+package ai.openclaw.app.voice
+
+import kotlinx.coroutines.runBlocking
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class TalkModeVoiceResolverTest {
+  @Test
+  fun resolvesVoiceAliasCaseInsensitively() {
+    val resolved =
+      TalkModeVoiceResolver.resolveVoiceAlias(
+        " Clawd ",
+        mapOf("clawd" to "voice-123"),
+      )
+
+    assertEquals("voice-123", resolved)
+  }
+
+  @Test
+  fun acceptsDirectVoiceIds() {
+    val resolved = TalkModeVoiceResolver.resolveVoiceAlias("21m00Tcm4TlvDq8ikWAM", emptyMap())
+
+    assertEquals("21m00Tcm4TlvDq8ikWAM", resolved)
+  }
+
+  @Test
+  fun rejectsUnknownAliases() {
+    val resolved = TalkModeVoiceResolver.resolveVoiceAlias("nickname", emptyMap())
+
+    assertNull(resolved)
+  }
+
+  @Test
+  fun reusesCachedFallbackVoiceBeforeFetchingCatalog() =
+    runBlocking {
+      var fetchCount = 0
+
+      val resolved =
+        TalkModeVoiceResolver.resolveVoiceId(
+          preferred = null,
+          fallbackVoiceId = "cached-voice",
+          defaultVoiceId = null,
+          currentVoiceId = null,
+          voiceOverrideActive = false,
+          listVoices = {
+            fetchCount += 1
+            emptyList()
+          },
+        )
+
+      assertEquals("cached-voice", resolved.voiceId)
+      assertEquals(0, fetchCount)
+    }
+
+  @Test
+  fun seedsDefaultVoiceFromCatalogWhenNeeded() =
+    runBlocking {
+      val resolved =
+        TalkModeVoiceResolver.resolveVoiceId(
+          preferred = null,
+          fallbackVoiceId = null,
+          defaultVoiceId = null,
+          currentVoiceId = null,
+          voiceOverrideActive = false,
+          listVoices = { listOf(ElevenLabsVoice("voice-1", "First")) },
+        )
+
+      assertEquals("voice-1", resolved.voiceId)
+      assertEquals("voice-1", resolved.fallbackVoiceId)
+      assertEquals("voice-1", resolved.defaultVoiceId)
+      assertEquals("voice-1", resolved.currentVoiceId)
+      assertEquals("First", resolved.selectedVoiceName)
+    }
+
+  @Test
+  fun preservesCurrentVoiceWhenOverrideIsActive() =
+    runBlocking {
+      val resolved =
+        TalkModeVoiceResolver.resolveVoiceId(
+          preferred = null,
+          fallbackVoiceId = null,
+          defaultVoiceId = null,
+          currentVoiceId = null,
+          voiceOverrideActive = true,
+          listVoices = { listOf(ElevenLabsVoice("voice-1", "First")) },
+        )
+
+      assertEquals("voice-1", resolved.voiceId)
+      assertNull(resolved.currentVoiceId)
+    }
+}

apps/ios/ActivityWidget/Info.plist

@@ -17,9 +17,9 @@
 	<key>CFBundlePackageType</key>
 	<string>XPC!</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.3.8</string>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
 	<key>CFBundleVersion</key>
-	<string>20260308</string>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
 	<key>NSExtension</key>
 	<dict>
 		<key>NSExtensionPointIdentifier</key>

apps/ios/Config/Signing.xcconfig

@@ -1,10 +1,12 @@
 // Shared iOS signing defaults for local development + CI.
+#include "Version.xcconfig"
+
 OPENCLAW_IOS_DEFAULT_TEAM = Y5PE65HELJ
 OPENCLAW_IOS_SELECTED_TEAM = $(OPENCLAW_IOS_DEFAULT_TEAM)
-OPENCLAW_APP_BUNDLE_ID = ai.openclaw.ios
-OPENCLAW_WATCH_APP_BUNDLE_ID = ai.openclaw.ios.watchkitapp
-OPENCLAW_WATCH_EXTENSION_BUNDLE_ID = ai.openclaw.ios.watchkitapp.extension
-OPENCLAW_ACTIVITY_WIDGET_BUNDLE_ID = ai.openclaw.ios.activitywidget
+OPENCLAW_APP_BUNDLE_ID = ai.openclaw.client
+OPENCLAW_WATCH_APP_BUNDLE_ID = ai.openclaw.client.watchkitapp
+OPENCLAW_WATCH_EXTENSION_BUNDLE_ID = ai.openclaw.client.watchkitapp.extension
+OPENCLAW_ACTIVITY_WIDGET_BUNDLE_ID = ai.openclaw.client.activitywidget
 
 // Local contributors can override this by running scripts/ios-configure-signing.sh.
 // Keep include after defaults: xcconfig is evaluated top-to-bottom.

apps/ios/Config/Version.xcconfig

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

apps/ios/README.md

@@ -1,15 +1,12 @@
 # OpenClaw iOS (Super Alpha)
 
-NO TEST FLIGHT AVAILABLE AT THIS POINT
-
 This iPhone app is super-alpha and internal-use only. It connects to an OpenClaw Gateway as a `role: node`.
 
 ## Distribution Status
 
-NO TEST FLIGHT AVAILABLE AT THIS POINT
-
-- Current distribution: local/manual deploy from source via Xcode.
-- App Store flow is not part of the current internal development path.
+- Public distribution: not available.
+- Internal beta distribution: local archive + TestFlight upload via Fastlane.
+- Local/manual deploy from source via Xcode remains the default development path.
 
 ## Super-Alpha Disclaimer
 
@@ -50,6 +47,45 @@ Shortcut command (same flow + open project):
 pnpm ios:open
 ```
 
+## Local Beta Release Flow
+
+Prereqs:
+
+- Xcode 16+
+- `pnpm`
+- `xcodegen`
+- `fastlane`
+- Apple account signed into Xcode for automatic signing/provisioning
+- App Store Connect API key set up in Keychain via `scripts/ios-asc-keychain-setup.sh` when auto-resolving a beta build number or uploading to TestFlight
+
+Release behavior:
+
+- Local development keeps using unique per-developer bundle IDs from `scripts/ios-configure-signing.sh`.
+- Beta release uses canonical `ai.openclaw.client*` bundle IDs through a temporary generated xcconfig in `apps/ios/build/BetaRelease.xcconfig`.
+- The beta flow does not modify `apps/ios/.local-signing.xcconfig` or `apps/ios/LocalSigning.xcconfig`.
+- Root `package.json.version` is the only version source for iOS.
+- A root version like `2026.3.11-beta.1` becomes:
+  - `CFBundleShortVersionString = 2026.3.11`
+  - `CFBundleVersion = next TestFlight build number for 2026.3.11`
+
+Archive without upload:
+
+```bash
+pnpm ios:beta:archive
+```
+
+Archive and upload to TestFlight:
+
+```bash
+pnpm ios:beta
+```
+
+If you need to force a specific build number:
+
+```bash
+pnpm ios:beta -- --build-number 7
+```
+
 ## APNs Expectations For Local/Manual Builds
 
 - The app calls `registerForRemoteNotifications()` at launch.

apps/ios/ShareExtension/Info.plist

@@ -17,9 +17,9 @@
 	<key>CFBundlePackageType</key>
 	<string>XPC!</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.3.8</string>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
 	<key>CFBundleVersion</key>
-	<string>20260308</string>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
 	<key>NSExtension</key>
 	<dict>
 		<key>NSExtensionAttributes</key>

apps/ios/Signing.xcconfig

@@ -2,6 +2,8 @@
 // Auto-selected local team overrides live in .local-signing.xcconfig (git-ignored).
 // Manual local overrides can go in LocalSigning.xcconfig (git-ignored).
 
+#include "Config/Version.xcconfig"
+
 OPENCLAW_CODE_SIGN_STYLE = Manual
 OPENCLAW_DEVELOPMENT_TEAM = Y5PE65HELJ
 

apps/ios/Sources/HomeToolbar.swift

@@ -0,0 +1,223 @@
+import SwiftUI
+
+struct HomeToolbar: View {
+    var gateway: StatusPill.GatewayState
+    var voiceWakeEnabled: Bool
+    var activity: StatusPill.Activity?
+    var brighten: Bool
+    var talkButtonEnabled: Bool
+    var talkActive: Bool
+    var talkTint: Color
+    var onStatusTap: () -> Void
+    var onChatTap: () -> Void
+    var onTalkTap: () -> Void
+    var onSettingsTap: () -> Void
+
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    var body: some View {
+        VStack(spacing: 0) {
+            Rectangle()
+                .fill(.white.opacity(self.contrast == .increased ? 0.46 : (self.brighten ? 0.18 : 0.12)))
+                .frame(height: self.contrast == .increased ? 1.0 : 0.6)
+                .allowsHitTesting(false)
+
+            HStack(spacing: 12) {
+                HomeToolbarStatusButton(
+                    gateway: self.gateway,
+                    voiceWakeEnabled: self.voiceWakeEnabled,
+                    activity: self.activity,
+                    brighten: self.brighten,
+                    onTap: self.onStatusTap)
+
+                Spacer(minLength: 0)
+
+                HStack(spacing: 8) {
+                    HomeToolbarActionButton(
+                        systemImage: "text.bubble.fill",
+                        accessibilityLabel: "Chat",
+                        brighten: self.brighten,
+                        action: self.onChatTap)
+
+                    if self.talkButtonEnabled {
+                        HomeToolbarActionButton(
+                            systemImage: self.talkActive ? "waveform.circle.fill" : "waveform.circle",
+                            accessibilityLabel: self.talkActive ? "Talk Mode On" : "Talk Mode Off",
+                            brighten: self.brighten,
+                            tint: self.talkTint,
+                            isActive: self.talkActive,
+                            action: self.onTalkTap)
+                    }
+
+                    HomeToolbarActionButton(
+                        systemImage: "gearshape.fill",
+                        accessibilityLabel: "Settings",
+                        brighten: self.brighten,
+                        action: self.onSettingsTap)
+                }
+            }
+            .padding(.horizontal, 12)
+            .padding(.top, 10)
+            .padding(.bottom, 8)
+        }
+        .frame(maxWidth: .infinity)
+        .background(.ultraThinMaterial)
+        .overlay(alignment: .top) {
+            LinearGradient(
+                colors: [
+                    .white.opacity(self.brighten ? 0.10 : 0.06),
+                    .clear,
+                ],
+                startPoint: .top,
+                endPoint: .bottom)
+                .allowsHitTesting(false)
+        }
+    }
+}
+
+private struct HomeToolbarStatusButton: View {
+    @Environment(\.scenePhase) private var scenePhase
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    var gateway: StatusPill.GatewayState
+    var voiceWakeEnabled: Bool
+    var activity: StatusPill.Activity?
+    var brighten: Bool
+    var onTap: () -> Void
+
+    @State private var pulse: Bool = false
+
+    var body: some View {
+        Button(action: self.onTap) {
+            HStack(spacing: 8) {
+                HStack(spacing: 6) {
+                    Circle()
+                        .fill(self.gateway.color)
+                        .frame(width: 8, height: 8)
+                        .scaleEffect(
+                            self.gateway == .connecting && !self.reduceMotion
+                                ? (self.pulse ? 1.15 : 0.85)
+                                : 1.0
+                        )
+                        .opacity(self.gateway == .connecting && !self.reduceMotion ? (self.pulse ? 1.0 : 0.6) : 1.0)
+
+                    Text(self.gateway.title)
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(.primary)
+                        .lineLimit(1)
+                }
+
+                if let activity {
+                    Image(systemName: activity.systemImage)
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(activity.tint ?? .primary)
+                        .transition(.opacity.combined(with: .move(edge: .top)))
+                } else {
+                    Image(systemName: self.voiceWakeEnabled ? "mic.fill" : "mic.slash")
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(self.voiceWakeEnabled ? .primary : .secondary)
+                        .transition(.opacity.combined(with: .move(edge: .top)))
+                }
+            }
+            .padding(.horizontal, 12)
+            .padding(.vertical, 8)
+            .background {
+                RoundedRectangle(cornerRadius: 14, style: .continuous)
+                    .fill(Color.black.opacity(self.brighten ? 0.12 : 0.18))
+                    .overlay {
+                        RoundedRectangle(cornerRadius: 14, style: .continuous)
+                            .strokeBorder(
+                                .white.opacity(self.contrast == .increased ? 0.46 : (self.brighten ? 0.22 : 0.16)),
+                                lineWidth: self.contrast == .increased ? 1.0 : 0.6)
+                    }
+            }
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel("Connection Status")
+        .accessibilityValue(self.accessibilityValue)
+        .accessibilityHint(self.gateway == .connected ? "Double tap for gateway actions" : "Double tap to open settings")
+        .onAppear { self.updatePulse(for: self.gateway, scenePhase: self.scenePhase, reduceMotion: self.reduceMotion) }
+        .onDisappear { self.pulse = false }
+        .onChange(of: self.gateway) { _, newValue in
+            self.updatePulse(for: newValue, scenePhase: self.scenePhase, reduceMotion: self.reduceMotion)
+        }
+        .onChange(of: self.scenePhase) { _, newValue in
+            self.updatePulse(for: self.gateway, scenePhase: newValue, reduceMotion: self.reduceMotion)
+        }
+        .onChange(of: self.reduceMotion) { _, newValue in
+            self.updatePulse(for: self.gateway, scenePhase: self.scenePhase, reduceMotion: newValue)
+        }
+        .animation(.easeInOut(duration: 0.18), value: self.activity?.title)
+    }
+
+    private var accessibilityValue: String {
+        if let activity {
+            return "\(self.gateway.title), \(activity.title)"
+        }
+        return "\(self.gateway.title), Voice Wake \(self.voiceWakeEnabled ? "enabled" : "disabled")"
+    }
+
+    private func updatePulse(for gateway: StatusPill.GatewayState, scenePhase: ScenePhase, reduceMotion: Bool) {
+        guard gateway == .connecting, scenePhase == .active, !reduceMotion else {
+            withAnimation(reduceMotion ? .none : .easeOut(duration: 0.2)) { self.pulse = false }
+            return
+        }
+
+        guard !self.pulse else { return }
+        withAnimation(.easeInOut(duration: 0.9).repeatForever(autoreverses: true)) {
+            self.pulse = true
+        }
+    }
+}
+
+private struct HomeToolbarActionButton: View {
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    let systemImage: String
+    let accessibilityLabel: String
+    let brighten: Bool
+    var tint: Color?
+    var isActive: Bool = false
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: self.action) {
+            Image(systemName: self.systemImage)
+                .font(.system(size: 16, weight: .semibold))
+                .foregroundStyle(self.isActive ? (self.tint ?? .primary) : .primary)
+                .frame(width: 40, height: 40)
+                .background {
+                    RoundedRectangle(cornerRadius: 12, style: .continuous)
+                        .fill(Color.black.opacity(self.brighten ? 0.12 : 0.18))
+                        .overlay {
+                            if let tint {
+                                RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                    .fill(
+                                        LinearGradient(
+                                            colors: [
+                                                tint.opacity(self.isActive ? 0.22 : 0.14),
+                                                tint.opacity(self.isActive ? 0.08 : 0.04),
+                                                .clear,
+                                            ],
+                                            startPoint: .topLeading,
+                                            endPoint: .bottomTrailing))
+                                    .blendMode(.overlay)
+                            }
+                        }
+                        .overlay {
+                            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                .strokeBorder(
+                                    (self.tint ?? .white).opacity(
+                                        self.isActive
+                                            ? 0.34
+                                            : (self.contrast == .increased ? 0.4 : (self.brighten ? 0.22 : 0.16))
+                                    ),
+                                    lineWidth: self.contrast == .increased ? 1.0 : (self.isActive ? 0.8 : 0.6))
+                        }
+                }
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel(self.accessibilityLabel)
+    }
+}

apps/ios/Sources/Info.plist

@@ -23,7 +23,7 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.3.8</string>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
 	<key>CFBundleURLTypes</key>
 	<array>
 		<dict>
@@ -36,7 +36,7 @@
 		</dict>
 	</array>
 	<key>CFBundleVersion</key>
-	<string>20260308</string>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
 	<key>ITSAppUsesNonExemptEncryption</key>
 	<false/>
 	<key>NSAppTransportSecurity</key>

apps/ios/Sources/Model/NodeAppModel+Canvas.swift

@@ -1,9 +1,24 @@
 import Foundation
 import Network
 import OpenClawKit
-import os
+
+enum A2UIReadyState {
+    case ready(String)
+    case hostNotConfigured
+    case hostUnavailable
+}
 
 extension NodeAppModel {
+    func resolveCanvasHostURL() async -> String? {
+        guard let raw = await self.gatewaySession.currentCanvasHostUrl() else { return nil }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, let base = URL(string: trimmed) else { return nil }
+        if let host = base.host, LoopbackHost.isLoopback(host) {
+            return nil
+        }
+        return base.appendingPathComponent("__openclaw__/canvas/").absoluteString
+    }
+
     func _test_resolveA2UIHostURL() async -> String? {
         await self.resolveA2UIHostURL()
     }
@@ -19,27 +34,31 @@ extension NodeAppModel {
     }
 
     func showA2UIOnConnectIfNeeded() async {
-        guard let a2uiUrl = await self.resolveA2UIHostURL() else {
-            await MainActor.run {
-                self.lastAutoA2uiURL = nil
-                self.screen.showDefaultCanvas()
-            }
-            return
+        await MainActor.run {
+            // Keep the bundled home canvas as the default connected view.
+            // Agents can still explicitly present a remote or local canvas later.
+            self.lastAutoA2uiURL = nil
+            self.screen.showDefaultCanvas()
         }
-        let current = self.screen.urlString.trimmingCharacters(in: .whitespacesAndNewlines)
-        if current.isEmpty || current == self.lastAutoA2uiURL {
-            // Avoid navigating the WKWebView to an unreachable host: it leaves a persistent
-            // "could not connect to the server" overlay even when the gateway is connected.
-            if let url = URL(string: a2uiUrl),
-               await Self.probeTCP(url: url, timeoutSeconds: 2.5)
-            {
-                self.screen.navigate(to: a2uiUrl)
-                self.lastAutoA2uiURL = a2uiUrl
-            } else {
-                self.lastAutoA2uiURL = nil
-                self.screen.showDefaultCanvas()
-            }
+    }
+
+    func ensureA2UIReadyWithCapabilityRefresh(timeoutMs: Int = 5000) async -> A2UIReadyState {
+        guard let initialUrl = await self.resolveA2UIHostURLWithCapabilityRefresh() else {
+            return .hostNotConfigured
         }
+        self.screen.navigate(to: initialUrl)
+        if await self.screen.waitForA2UIReady(timeoutMs: timeoutMs) {
+            return .ready(initialUrl)
+        }
+
+        // First render can fail when scoped capability rotates between reconnects.
+        guard await self.gatewaySession.refreshNodeCanvasCapability() else { return .hostUnavailable }
+        guard let refreshedUrl = await self.resolveA2UIHostURL() else { return .hostUnavailable }
+        self.screen.navigate(to: refreshedUrl)
+        if await self.screen.waitForA2UIReady(timeoutMs: timeoutMs) {
+            return .ready(refreshedUrl)
+        }
+        return .hostUnavailable
     }
 
     func showLocalCanvasOnDisconnect() {
@@ -47,6 +66,22 @@ extension NodeAppModel {
         self.screen.showDefaultCanvas()
     }
 
+    private func resolveA2UIHostURLWithCapabilityRefresh() async -> String? {
+        if let url = await self.resolveA2UIHostURL() {
+            return url
+        }
+        guard await self.gatewaySession.refreshNodeCanvasCapability() else { return nil }
+        return await self.resolveA2UIHostURL()
+    }
+
+    private func resolveCanvasHostURLWithCapabilityRefresh() async -> String? {
+        if let url = await self.resolveCanvasHostURL() {
+            return url
+        }
+        guard await self.gatewaySession.refreshNodeCanvasCapability() else { return nil }
+        return await self.resolveCanvasHostURL()
+    }
+
     private static func probeTCP(url: URL, timeoutSeconds: Double) async -> Bool {
         guard let host = url.host, !host.isEmpty else { return false }
         let portInt = url.port ?? ((url.scheme ?? "").lowercased() == "wss" ? 443 : 80)

apps/ios/Sources/Model/NodeAppModel.swift

@@ -57,6 +57,7 @@ final class NodeAppModel {
 
     private let deepLinkLogger = Logger(subsystem: "ai.openclaw.ios", category: "DeepLink")
     private let pushWakeLogger = Logger(subsystem: "ai.openclaw.ios", category: "PushWake")
+    private let pendingActionLogger = Logger(subsystem: "ai.openclaw.ios", category: "PendingAction")
     private let locationWakeLogger = Logger(subsystem: "ai.openclaw.ios", category: "LocationWake")
     private let watchReplyLogger = Logger(subsystem: "ai.openclaw.ios", category: "WatchReply")
     enum CameraHUDKind {
@@ -87,6 +88,7 @@ final class NodeAppModel {
     var selectedAgentId: String?
     var gatewayDefaultAgentId: String?
     var gatewayAgents: [AgentSummary] = []
+    var homeCanvasRevision: Int = 0
     var lastShareEventText: String = "No share events yet."
     var openChatRequestID: Int = 0
     private(set) var pendingAgentDeepLinkPrompt: AgentDeepLinkPrompt?
@@ -129,8 +131,8 @@ final class NodeAppModel {
     private var backgroundReconnectSuppressed = false
     private var backgroundReconnectLeaseUntil: Date?
     private var lastSignificantLocationWakeAt: Date?
-    private var queuedWatchReplies: [WatchQuickReplyEvent] = []
-    private var seenWatchReplyIds = Set<String>()
+    @ObservationIgnored private let watchReplyCoordinator = WatchReplyCoordinator()
+    private var pendingForegroundActionDrainInFlight = false
 
     private var gatewayConnected = false
     private var operatorConnected = false
@@ -330,6 +332,9 @@ final class NodeAppModel {
                     }
                     await self.talkMode.resumeAfterBackground(wasSuspended: suspended, wasKeptActive: keptActive)
                 }
+                Task { [weak self] in
+                    await self?.resumePendingForegroundNodeActionsIfNeeded(trigger: "scene_active")
+                }
             }
             if phase == .active, self.reconnectAfterBackgroundArmed {
                 self.reconnectAfterBackgroundArmed = false
@@ -358,7 +363,14 @@ final class NodeAppModel {
                         await MainActor.run {
                             self.operatorConnected = false
                             self.gatewayConnected = false
+                            // Foreground recovery must actively restart the saved gateway config.
+                            // Disconnecting stale sockets alone can leave us idle if the old
+                            // reconnect tasks were suppressed or otherwise got stuck in background.
+                            self.gatewayStatusText = "Reconnecting…"
                             self.talkMode.updateGatewayConnected(false)
+                            if let cfg = self.activeGatewayConnectConfig {
+                                self.applyGatewayConnectConfig(cfg)
+                            }
                         }
                     }
                 }
@@ -537,6 +549,7 @@ final class NodeAppModel {
                 self.seamColorHex = raw.isEmpty ? nil : raw
                 self.mainSessionBaseKey = mainKey
                 self.talkMode.updateMainSessionKey(self.mainSessionKey)
+                self.homeCanvasRevision &+= 1
             }
         } catch {
             if let gatewayError = error as? GatewayResponseError {
@@ -563,12 +576,19 @@ final class NodeAppModel {
                     self.selectedAgentId = nil
                 }
                 self.talkMode.updateMainSessionKey(self.mainSessionKey)
+                self.homeCanvasRevision &+= 1
             }
         } catch {
             // Best-effort only.
         }
     }
 
+    func refreshGatewayOverviewIfConnected() async {
+        guard await self.isOperatorConnected() else { return }
+        await self.refreshBrandingFromGateway()
+        await self.refreshAgentsFromGateway()
+    }
+
     func setSelectedAgentId(_ agentId: String?) {
         let trimmed = (agentId ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
         let stableID = (self.connectedGatewayID ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
@@ -579,6 +599,7 @@ final class NodeAppModel {
             GatewaySettingsStore.saveGatewaySelectedAgentId(stableID: stableID, agentId: self.selectedAgentId)
         }
         self.talkMode.updateMainSessionKey(self.mainSessionKey)
+        self.homeCanvasRevision &+= 1
         if let relay = ShareGatewayRelaySettings.loadConfig() {
             ShareGatewayRelaySettings.saveConfig(
                 ShareGatewayRelayConfig(
@@ -878,16 +899,17 @@ final class NodeAppModel {
         let command = req.command
         switch command {
         case OpenClawCanvasA2UICommand.reset.rawValue:
-            guard let a2uiUrl = await self.resolveA2UIHostURL() else {
+            switch await self.ensureA2UIReadyWithCapabilityRefresh(timeoutMs: 5000) {
+            case .ready:
+                break
+            case .hostNotConfigured:
                 return BridgeInvokeResponse(
                     id: req.id,
                     ok: false,
                     error: OpenClawNodeError(
                         code: .unavailable,
                         message: "A2UI_HOST_NOT_CONFIGURED: gateway did not advertise canvas host"))
-            }
-            self.screen.navigate(to: a2uiUrl)
-            if await !self.screen.waitForA2UIReady(timeoutMs: 5000) {
+            case .hostUnavailable:
                 return BridgeInvokeResponse(
                     id: req.id,
                     ok: false,
@@ -895,7 +917,6 @@ final class NodeAppModel {
                         code: .unavailable,
                         message: "A2UI_HOST_UNAVAILABLE: A2UI host not reachable"))
             }
-
             let json = try await self.screen.eval(javaScript: """
             (() => {
               const host = globalThis.openclawA2UI;
@@ -904,6 +925,7 @@ final class NodeAppModel {
             })()
             """)
             return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: json)
+
         case OpenClawCanvasA2UICommand.push.rawValue, OpenClawCanvasA2UICommand.pushJSONL.rawValue:
             let messages: [OpenClawKit.AnyCodable]
             if command == OpenClawCanvasA2UICommand.pushJSONL.rawValue {
@@ -920,16 +942,17 @@ final class NodeAppModel {
                 }
             }
 
-            guard let a2uiUrl = await self.resolveA2UIHostURL() else {
+            switch await self.ensureA2UIReadyWithCapabilityRefresh(timeoutMs: 5000) {
+            case .ready:
+                break
+            case .hostNotConfigured:
                 return BridgeInvokeResponse(
                     id: req.id,
                     ok: false,
                     error: OpenClawNodeError(
                         code: .unavailable,
                         message: "A2UI_HOST_NOT_CONFIGURED: gateway did not advertise canvas host"))
-            }
-            self.screen.navigate(to: a2uiUrl)
-            if await !self.screen.waitForA2UIReady(timeoutMs: 5000) {
+            case .hostUnavailable:
                 return BridgeInvokeResponse(
                     id: req.id,
                     ok: false,
@@ -1616,11 +1639,9 @@ extension NodeAppModel {
     }
 
     var chatSessionKey: String {
-        let base = "ios"
-        let agentId = (self.selectedAgentId ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
-        let defaultId = (self.gatewayDefaultAgentId ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
-        if agentId.isEmpty || (!defaultId.isEmpty && agentId == defaultId) { return base }
-        return SessionKey.makeAgentSessionKey(agentId: agentId, baseKey: base)
+        // Keep chat aligned with the gateway's resolved main session key.
+        // A hardcoded "ios" base creates synthetic placeholder sessions in the chat UI.
+        self.mainSessionKey
     }
 
     var activeAgentName: String {
@@ -1736,6 +1757,7 @@ private extension NodeAppModel {
         self.gatewayDefaultAgentId = nil
         self.gatewayAgents = []
         self.selectedAgentId = GatewaySettingsStore.loadGatewaySelectedAgentId(stableID: stableID)
+        self.homeCanvasRevision &+= 1
         self.apnsLastRegisteredTokenHex = nil
     }
 
@@ -2099,6 +2121,22 @@ private extension NodeAppModel {
 }
 
 extension NodeAppModel {
+    private struct PendingForegroundNodeAction: Decodable {
+        var id: String
+        var command: String
+        var paramsJSON: String?
+        var enqueuedAtMs: Int?
+    }
+
+    private struct PendingForegroundNodeActionsResponse: Decodable {
+        var nodeId: String?
+        var actions: [PendingForegroundNodeAction]
+    }
+
+    private struct PendingForegroundNodeActionsAckRequest: Encodable {
+        var ids: [String]
+    }
+
     private func refreshShareRouteFromGateway() async {
         struct Params: Codable {
             var includeGlobal: Bool
@@ -2196,40 +2234,97 @@ extension NodeAppModel {
     func onNodeGatewayConnected() async {
         await self.registerAPNsTokenIfNeeded()
         await self.flushQueuedWatchRepliesIfConnected()
+        await self.resumePendingForegroundNodeActionsIfNeeded(trigger: "node_connected")
+    }
+
+    private func resumePendingForegroundNodeActionsIfNeeded(trigger: String) async {
+        guard !self.isBackgrounded else { return }
+        guard await self.isGatewayConnected() else { return }
+        guard !self.pendingForegroundActionDrainInFlight else { return }
+
+        self.pendingForegroundActionDrainInFlight = true
+        defer { self.pendingForegroundActionDrainInFlight = false }
+
+        do {
+            let payload = try await self.nodeGateway.request(
+                method: "node.pending.pull",
+                paramsJSON: "{}",
+                timeoutSeconds: 6)
+            let decoded = try JSONDecoder().decode(
+                PendingForegroundNodeActionsResponse.self,
+                from: payload)
+            guard !decoded.actions.isEmpty else { return }
+            self.pendingActionLogger.info(
+                "Pending actions pulled trigger=\(trigger, privacy: .public) count=\(decoded.actions.count, privacy: .public)")
+            await self.applyPendingForegroundNodeActions(decoded.actions, trigger: trigger)
+        } catch {
+            // Best-effort only.
+        }
+    }
+
+    private func applyPendingForegroundNodeActions(
+        _ actions: [PendingForegroundNodeAction],
+        trigger: String) async
+    {
+        for action in actions {
+            guard !self.isBackgrounded else {
+                self.pendingActionLogger.info(
+                    "Pending action replay paused trigger=\(trigger, privacy: .public): app backgrounded")
+                return
+            }
+            let req = BridgeInvokeRequest(
+                id: action.id,
+                command: action.command,
+                paramsJSON: action.paramsJSON)
+            let result = await self.handleInvoke(req)
+            self.pendingActionLogger.info(
+                "Pending action replay trigger=\(trigger, privacy: .public) id=\(action.id, privacy: .public) command=\(action.command, privacy: .public) ok=\(result.ok, privacy: .public)")
+            guard result.ok else { return }
+            let acked = await self.ackPendingForegroundNodeAction(
+                id: action.id,
+                trigger: trigger,
+                command: action.command)
+            guard acked else { return }
+        }
+    }
+
+    private func ackPendingForegroundNodeAction(
+        id: String,
+        trigger: String,
+        command: String) async -> Bool
+    {
+        do {
+            let payload = try JSONEncoder().encode(PendingForegroundNodeActionsAckRequest(ids: [id]))
+            let paramsJSON = String(decoding: payload, as: UTF8.self)
+            _ = try await self.nodeGateway.request(
+                method: "node.pending.ack",
+                paramsJSON: paramsJSON,
+                timeoutSeconds: 6)
+            return true
+        } catch {
+            self.pendingActionLogger.error(
+                "Pending action ack failed trigger=\(trigger, privacy: .public) id=\(id, privacy: .public) command=\(command, privacy: .public) error=\(String(describing: error), privacy: .public)")
+            return false
+        }
     }
 
     private func handleWatchQuickReply(_ event: WatchQuickReplyEvent) async {
-        let replyId = event.replyId.trimmingCharacters(in: .whitespacesAndNewlines)
-        let actionId = event.actionId.trimmingCharacters(in: .whitespacesAndNewlines)
-        if replyId.isEmpty || actionId.isEmpty {
+        switch self.watchReplyCoordinator.ingest(event, isGatewayConnected: await self.isGatewayConnected()) {
+        case .dropMissingFields:
             self.watchReplyLogger.info("watch reply dropped: missing replyId/actionId")
-            return
-        }
-
-        if self.seenWatchReplyIds.contains(replyId) {
+        case .deduped(let replyId):
             self.watchReplyLogger.debug(
                 "watch reply deduped replyId=\(replyId, privacy: .public)")
-            return
-        }
-        self.seenWatchReplyIds.insert(replyId)
-
-        if await !self.isGatewayConnected() {
-            self.queuedWatchReplies.append(event)
+        case .queue(let replyId, let actionId):
             self.watchReplyLogger.info(
                 "watch reply queued replyId=\(replyId, privacy: .public) action=\(actionId, privacy: .public)")
-            return
+        case .forward:
+            await self.forwardWatchReplyToAgent(event)
         }
-
-        await self.forwardWatchReplyToAgent(event)
     }
 
     private func flushQueuedWatchRepliesIfConnected() async {
-        guard await self.isGatewayConnected() else { return }
-        guard !self.queuedWatchReplies.isEmpty else { return }
-
-        let pending = self.queuedWatchReplies
-        self.queuedWatchReplies.removeAll()
-        for event in pending {
+        for event in self.watchReplyCoordinator.drainIfConnected(await self.isGatewayConnected()) {
             await self.forwardWatchReplyToAgent(event)
         }
     }
@@ -2259,7 +2354,7 @@ extension NodeAppModel {
                 "watch reply forwarding failed replyId=\(event.replyId) "
                 + "error=\(error.localizedDescription)"
             self.watchReplyLogger.error("\(failedMessage, privacy: .public)")
-            self.queuedWatchReplies.insert(event, at: 0)
+            self.watchReplyCoordinator.requeueFront(event)
         }
     }
 
@@ -2852,13 +2947,26 @@ extension NodeAppModel {
     }
 
     func _test_queuedWatchReplyCount() -> Int {
-        self.queuedWatchReplies.count
+        self.watchReplyCoordinator.queuedCount
     }
 
     func _test_setGatewayConnected(_ connected: Bool) {
         self.gatewayConnected = connected
     }
 
+    func _test_applyPendingForegroundNodeActions(
+        _ actions: [(id: String, command: String, paramsJSON: String?)]) async
+    {
+        let mapped = actions.map { action in
+            PendingForegroundNodeAction(
+                id: action.id,
+                command: action.command,
+                paramsJSON: action.paramsJSON,
+                enqueuedAtMs: nil)
+        }
+        await self.applyPendingForegroundNodeActions(mapped, trigger: "test")
+    }
+
     static func _test_currentDeepLinkKey() -> String {
         self.expectedDeepLinkKey()
     }

apps/ios/Sources/Model/WatchReplyCoordinator.swift

@@ -0,0 +1,46 @@
+import Foundation
+
+@MainActor
+final class WatchReplyCoordinator {
+    enum Decision {
+        case dropMissingFields
+        case deduped(replyId: String)
+        case queue(replyId: String, actionId: String)
+        case forward
+    }
+
+    private var queuedReplies: [WatchQuickReplyEvent] = []
+    private var seenReplyIds = Set<String>()
+
+    func ingest(_ event: WatchQuickReplyEvent, isGatewayConnected: Bool) -> Decision {
+        let replyId = event.replyId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let actionId = event.actionId.trimmingCharacters(in: .whitespacesAndNewlines)
+        if replyId.isEmpty || actionId.isEmpty {
+            return .dropMissingFields
+        }
+        if self.seenReplyIds.contains(replyId) {
+            return .deduped(replyId: replyId)
+        }
+        self.seenReplyIds.insert(replyId)
+        if !isGatewayConnected {
+            self.queuedReplies.append(event)
+            return .queue(replyId: replyId, actionId: actionId)
+        }
+        return .forward
+    }
+
+    func drainIfConnected(_ isGatewayConnected: Bool) -> [WatchQuickReplyEvent] {
+        guard isGatewayConnected, !self.queuedReplies.isEmpty else { return [] }
+        let pending = self.queuedReplies
+        self.queuedReplies.removeAll()
+        return pending
+    }
+
+    func requeueFront(_ event: WatchQuickReplyEvent) {
+        self.queuedReplies.insert(event, at: 0)
+    }
+
+    var queuedCount: Int {
+        self.queuedReplies.count
+    }
+}

apps/ios/Sources/Onboarding/OnboardingWizardView.swift

@@ -536,7 +536,7 @@ struct OnboardingWizardView: View {
                     Text(
                         "Approve this device on the gateway.\n"
                             + "1) `openclaw devices approve` (or `openclaw devices approve <requestId>`)\n"
-                            + "2) `/pair approve` in Telegram\n"
+                            + "2) `/pair approve` in your OpenClaw chat\n"
                             + "\(requestLine)\n"
                             + "OpenClaw will also retry automatically when you return to this app.")
                 }

apps/ios/Sources/RootCanvas.swift

@@ -1,5 +1,6 @@
 import SwiftUI
 import UIKit
+import OpenClawProtocol
 
 struct RootCanvas: View {
     @Environment(NodeAppModel.self) private var appModel
@@ -137,16 +138,33 @@ struct RootCanvas: View {
                 .environment(self.gatewayController)
         }
         .onAppear { self.updateIdleTimer() }
+        .onAppear { self.updateHomeCanvasState() }
         .onAppear { self.evaluateOnboardingPresentation(force: false) }
         .onAppear { self.maybeAutoOpenSettings() }
         .onChange(of: self.preventSleep) { _, _ in self.updateIdleTimer() }
-        .onChange(of: self.scenePhase) { _, _ in self.updateIdleTimer() }
+        .onChange(of: self.scenePhase) { _, newValue in
+            self.updateIdleTimer()
+            self.updateHomeCanvasState()
+            guard newValue == .active else { return }
+            Task {
+                await self.appModel.refreshGatewayOverviewIfConnected()
+                await MainActor.run {
+                    self.updateHomeCanvasState()
+                }
+            }
+        }
         .onAppear { self.maybeShowQuickSetup() }
         .onChange(of: self.gatewayController.gateways.count) { _, _ in self.maybeShowQuickSetup() }
         .onAppear { self.updateCanvasDebugStatus() }
         .onChange(of: self.canvasDebugStatusEnabled) { _, _ in self.updateCanvasDebugStatus() }
-        .onChange(of: self.appModel.gatewayStatusText) { _, _ in self.updateCanvasDebugStatus() }
-        .onChange(of: self.appModel.gatewayServerName) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayStatusText) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
+        .onChange(of: self.appModel.gatewayServerName) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
         .onChange(of: self.appModel.gatewayServerName) { _, newValue in
             if newValue != nil {
                 self.showOnboarding = false
@@ -155,7 +173,13 @@ struct RootCanvas: View {
         .onChange(of: self.onboardingRequestID) { _, _ in
             self.evaluateOnboardingPresentation(force: true)
         }
-        .onChange(of: self.appModel.gatewayRemoteAddress) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayRemoteAddress) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
+        .onChange(of: self.appModel.homeCanvasRevision) { _, _ in
+            self.updateHomeCanvasState()
+        }
         .onChange(of: self.appModel.gatewayServerName) { _, newValue in
             if newValue != nil {
                 self.onboardingComplete = true
@@ -209,6 +233,134 @@ struct RootCanvas: View {
         self.appModel.screen.updateDebugStatus(title: title, subtitle: subtitle)
     }
 
+    private func updateHomeCanvasState() {
+        let payload = self.makeHomeCanvasPayload()
+        guard let data = try? JSONEncoder().encode(payload),
+              let json = String(data: data, encoding: .utf8)
+        else {
+            self.appModel.screen.updateHomeCanvasState(json: nil)
+            return
+        }
+        self.appModel.screen.updateHomeCanvasState(json: json)
+    }
+
+    private func makeHomeCanvasPayload() -> HomeCanvasPayload {
+        let gatewayName = self.normalized(self.appModel.gatewayServerName)
+        let gatewayAddress = self.normalized(self.appModel.gatewayRemoteAddress)
+        let gatewayLabel = gatewayName ?? gatewayAddress ?? "Gateway"
+        let activeAgentID = self.resolveActiveAgentID()
+        let agents = self.homeCanvasAgents(activeAgentID: activeAgentID)
+
+        switch self.gatewayStatus {
+        case .connected:
+            return HomeCanvasPayload(
+                gatewayState: "connected",
+                eyebrow: "Connected to \(gatewayLabel)",
+                title: "Your agents are ready",
+                subtitle:
+                    "This phone stays dormant until the gateway needs it, then wakes, syncs, and goes back to sleep.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: self.appModel.activeAgentName,
+                activeAgentBadge: agents.first(where: { $0.isActive })?.badge ?? "OC",
+                activeAgentCaption: "Selected on this phone",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(6)),
+                footer: "The overview refreshes on reconnect and when the app returns to foreground.")
+        case .connecting:
+            return HomeCanvasPayload(
+                gatewayState: "connecting",
+                eyebrow: "Reconnecting",
+                title: "OpenClaw is syncing back up",
+                subtitle:
+                    "The gateway session is coming back online. "
+                    + "Agent shortcuts should settle automatically in a moment.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: self.appModel.activeAgentName,
+                activeAgentBadge: "OC",
+                activeAgentCaption: "Gateway session in progress",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(4)),
+                footer: "If the gateway is reachable, reconnect should complete without intervention.")
+        case .error, .disconnected:
+            return HomeCanvasPayload(
+                gatewayState: self.gatewayStatus == .error ? "error" : "offline",
+                eyebrow: "Welcome to OpenClaw",
+                title: "Your phone stays quiet until it is needed",
+                subtitle:
+                    "Pair this device to your gateway to wake it only for real work, "
+                    + "keep a live agent overview handy, and avoid battery-draining background loops.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: "Main",
+                activeAgentBadge: "OC",
+                activeAgentCaption: "Connect to load your agents",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(4)),
+                footer:
+                    "When connected, the gateway can wake the phone with a silent push "
+                    + "instead of holding an always-on session.")
+        }
+    }
+
+    private func resolveActiveAgentID() -> String {
+        let selected = self.normalized(self.appModel.selectedAgentId) ?? ""
+        if !selected.isEmpty {
+            return selected
+        }
+        return self.resolveDefaultAgentID()
+    }
+
+    private func resolveDefaultAgentID() -> String {
+        self.normalized(self.appModel.gatewayDefaultAgentId) ?? ""
+    }
+
+    private func homeCanvasAgents(activeAgentID: String) -> [HomeCanvasAgentCard] {
+        let defaultAgentID = self.resolveDefaultAgentID()
+        let cards = self.appModel.gatewayAgents.map { agent -> HomeCanvasAgentCard in
+            let isActive = !activeAgentID.isEmpty && agent.id == activeAgentID
+            let isDefault = !defaultAgentID.isEmpty && agent.id == defaultAgentID
+            return HomeCanvasAgentCard(
+                id: agent.id,
+                name: self.homeCanvasName(for: agent),
+                badge: self.homeCanvasBadge(for: agent),
+                caption: isActive ? "Active on this phone" : (isDefault ? "Default agent" : "Ready"),
+                isActive: isActive)
+        }
+
+        return cards.sorted { lhs, rhs in
+            if lhs.isActive != rhs.isActive {
+                return lhs.isActive
+            }
+            return lhs.name.localizedCaseInsensitiveCompare(rhs.name) == .orderedAscending
+        }
+    }
+
+    private func homeCanvasName(for agent: AgentSummary) -> String {
+        self.normalized(agent.name) ?? agent.id
+    }
+
+    private func homeCanvasBadge(for agent: AgentSummary) -> String {
+        if let identity = agent.identity,
+           let emoji = identity["emoji"]?.value as? String,
+           let normalizedEmoji = self.normalized(emoji)
+        {
+            return normalizedEmoji
+        }
+        let words = self.homeCanvasName(for: agent)
+            .split(whereSeparator: { $0.isWhitespace || $0 == "-" || $0 == "_" })
+            .prefix(2)
+        let initials = words.compactMap { $0.first }.map(String.init).joined()
+        if !initials.isEmpty {
+            return initials.uppercased()
+        }
+        return "OC"
+    }
+
+    private func normalized(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
     private func evaluateOnboardingPresentation(force: Bool) {
         if force {
             self.onboardingAllowSkip = true
@@ -274,6 +426,28 @@ struct RootCanvas: View {
     }
 }
 
+private struct HomeCanvasPayload: Codable {
+    var gatewayState: String
+    var eyebrow: String
+    var title: String
+    var subtitle: String
+    var gatewayLabel: String
+    var activeAgentName: String
+    var activeAgentBadge: String
+    var activeAgentCaption: String
+    var agentCount: Int
+    var agents: [HomeCanvasAgentCard]
+    var footer: String
+}
+
+private struct HomeCanvasAgentCard: Codable {
+    var id: String
+    var name: String
+    var badge: String
+    var caption: String
+    var isActive: Bool
+}
+
 private struct CanvasContent: View {
     @Environment(NodeAppModel.self) private var appModel
     @AppStorage("talk.enabled") private var talkEnabled: Bool = false
@@ -301,53 +475,33 @@ private struct CanvasContent: View {
                     .transition(.opacity)
             }
         }
-        .overlay(alignment: .topLeading) {
-            HStack(alignment: .top, spacing: 8) {
-                StatusPill(
-                    gateway: self.gatewayStatus,
-                    voiceWakeEnabled: self.voiceWakeEnabled,
-                    activity: self.statusActivity,
-                    brighten: self.brightenButtons,
-                    onTap: {
-                        if self.gatewayStatus == .connected {
-                            self.showGatewayActions = true
-                        } else {
-                            self.openSettings()
-                        }
-                    })
-                    .layoutPriority(1)
-
-                Spacer(minLength: 8)
-
-                HStack(spacing: 8) {
-                    OverlayButton(systemImage: "text.bubble.fill", brighten: self.brightenButtons) {
-                        self.openChat()
-                    }
-                    .accessibilityLabel("Chat")
-
-                    if self.talkButtonEnabled {
-                        // Keep Talk mode near status controls while freeing right-side screen real estate.
-                        OverlayButton(
-                            systemImage: self.talkActive ? "waveform.circle.fill" : "waveform.circle",
-                            brighten: self.brightenButtons,
-                            tint: self.appModel.seamColor,
-                            isActive: self.talkActive)
-                        {
-                            let next = !self.talkActive
-                            self.talkEnabled = next
-                            self.appModel.setTalkEnabled(next)
-                        }
-                        .accessibilityLabel("Talk Mode")
-                    }
-
-                    OverlayButton(systemImage: "gearshape.fill", brighten: self.brightenButtons) {
+        .safeAreaInset(edge: .bottom, spacing: 0) {
+            HomeToolbar(
+                gateway: self.gatewayStatus,
+                voiceWakeEnabled: self.voiceWakeEnabled,
+                activity: self.statusActivity,
+                brighten: self.brightenButtons,
+                talkButtonEnabled: self.talkButtonEnabled,
+                talkActive: self.talkActive,
+                talkTint: self.appModel.seamColor,
+                onStatusTap: {
+                    if self.gatewayStatus == .connected {
+                        self.showGatewayActions = true
+                    } else {
                         self.openSettings()
                     }
-                    .accessibilityLabel("Settings")
-                }
-            }
-            .padding(.horizontal, 10)
-            .safeAreaPadding(.top, 10)
+                },
+                onChatTap: {
+                    self.openChat()
+                },
+                onTalkTap: {
+                    let next = !self.talkActive
+                    self.talkEnabled = next
+                    self.appModel.setTalkEnabled(next)
+                },
+                onSettingsTap: {
+                    self.openSettings()
+                })
         }
         .overlay(alignment: .topLeading) {
             if let voiceWakeToastText, !voiceWakeToastText.isEmpty {
@@ -380,63 +534,6 @@ private struct CanvasContent: View {
     }
 }
 
-private struct OverlayButton: View {
-    let systemImage: String
-    let brighten: Bool
-    var tint: Color?
-    var isActive: Bool = false
-    let action: () -> Void
-
-    var body: some View {
-        Button(action: self.action) {
-            Image(systemName: self.systemImage)
-                .font(.system(size: 16, weight: .semibold))
-                .foregroundStyle(self.isActive ? (self.tint ?? .primary) : .primary)
-                .padding(10)
-                .background {
-                    RoundedRectangle(cornerRadius: 12, style: .continuous)
-                        .fill(.ultraThinMaterial)
-                        .overlay {
-                            RoundedRectangle(cornerRadius: 12, style: .continuous)
-                                .fill(
-                                    LinearGradient(
-                                        colors: [
-                                            .white.opacity(self.brighten ? 0.26 : 0.18),
-                                            .white.opacity(self.brighten ? 0.08 : 0.04),
-                                            .clear,
-                                        ],
-                                        startPoint: .topLeading,
-                                        endPoint: .bottomTrailing))
-                                .blendMode(.overlay)
-                        }
-                        .overlay {
-                            if let tint {
-                                RoundedRectangle(cornerRadius: 12, style: .continuous)
-                                    .fill(
-                                        LinearGradient(
-                                            colors: [
-                                                tint.opacity(self.isActive ? 0.22 : 0.14),
-                                                tint.opacity(self.isActive ? 0.10 : 0.06),
-                                                .clear,
-                                            ],
-                                            startPoint: .topLeading,
-                                            endPoint: .bottomTrailing))
-                                    .blendMode(.overlay)
-                            }
-                        }
-                        .overlay {
-                            RoundedRectangle(cornerRadius: 12, style: .continuous)
-                                .strokeBorder(
-                                    (self.tint ?? .white).opacity(self.isActive ? 0.34 : (self.brighten ? 0.24 : 0.18)),
-                                    lineWidth: self.isActive ? 0.7 : 0.5)
-                        }
-                        .shadow(color: .black.opacity(0.35), radius: 12, y: 6)
-                }
-        }
-        .buttonStyle(.plain)
-    }
-}
-
 private struct CameraFlashOverlay: View {
     var nonce: Int
 

apps/ios/Sources/Screen/ScreenController.swift

@@ -20,6 +20,7 @@ final class ScreenController {
     private var debugStatusEnabled: Bool = false
     private var debugStatusTitle: String?
     private var debugStatusSubtitle: String?
+    private var homeCanvasStateJSON: String?
 
     init() {
         self.reload()
@@ -94,6 +95,26 @@ final class ScreenController {
             subtitle: self.debugStatusSubtitle)
     }
 
+    func updateHomeCanvasState(json: String?) {
+        self.homeCanvasStateJSON = json
+        self.applyHomeCanvasStateIfNeeded()
+    }
+
+    func applyHomeCanvasStateIfNeeded() {
+        guard let webView = self.activeWebView else { return }
+        let payload = self.homeCanvasStateJSON ?? "null"
+        let js = """
+        (() => {
+          try {
+            const api = globalThis.__openclaw;
+            if (!api || typeof api.renderHome !== 'function') return;
+            api.renderHome(\(payload));
+          } catch (_) {}
+        })()
+        """
+        webView.evaluateJavaScript(js) { _, _ in }
+    }
+
     func waitForA2UIReady(timeoutMs: Int) async -> Bool {
         let clock = ContinuousClock()
         let deadline = clock.now.advanced(by: .milliseconds(timeoutMs))
@@ -191,6 +212,7 @@ final class ScreenController {
         self.activeWebView = webView
         self.reload()
         self.applyDebugStatusIfNeeded()
+        self.applyHomeCanvasStateIfNeeded()
     }
 
     func detachWebView(_ webView: WKWebView) {

apps/ios/Sources/Screen/ScreenTab.swift

@@ -7,7 +7,7 @@ struct ScreenTab: View {
     var body: some View {
         ZStack(alignment: .top) {
             ScreenWebView(controller: self.appModel.screen)
-                .ignoresSafeArea()
+                .ignoresSafeArea(.container, edges: [.top, .leading, .trailing])
                 .overlay(alignment: .top) {
                     if let errorText = self.appModel.screen.errorText,
                        self.appModel.gatewayServerName == nil

apps/ios/Sources/Screen/ScreenWebView.swift

@@ -161,6 +161,7 @@ private final class ScreenNavigationDelegate: NSObject, WKNavigationDelegate {
     func webView(_: WKWebView, didFinish _: WKNavigation?) {
         self.controller?.errorText = nil
         self.controller?.applyDebugStatusIfNeeded()
+        self.controller?.applyHomeCanvasStateIfNeeded()
     }
 
     func webView(_: WKWebView, didFail _: WKNavigation?, withError error: any Error) {

apps/ios/Sources/Settings/SettingsTab.swift

@@ -65,10 +65,10 @@ struct SettingsTab: View {
                     DisclosureGroup(isExpanded: self.$gatewayExpanded) {
                         if !self.isGatewayConnected {
                             Text(
-                                "1. Open Telegram and message your bot: /pair\n"
+                                "1. Open a chat with your OpenClaw agent and send /pair\n"
                                     + "2. Copy the setup code it returns\n"
                                     + "3. Paste here and tap Connect\n"
-                                    + "4. Back in Telegram, run /pair approve")
+                                    + "4. Back in that chat, run /pair approve")
                                 .font(.footnote)
                                 .foregroundStyle(.secondary)
 
@@ -340,9 +340,9 @@ struct SettingsTab: View {
                                     .foregroundStyle(.secondary)
                             }
                             self.featureToggle(
-                                "Show Talk Button",
+                                "Show Talk Control",
                                 isOn: self.$talkButtonEnabled,
-                                help: "Shows the floating Talk button in the main interface.")
+                                help: "Shows the Talk control in the main toolbar.")
                             TextField("Default Share Instruction", text: self.$defaultShareInstruction, axis: .vertical)
                                 .lineLimit(2 ... 6)
                                 .textInputAutocapitalization(.sentences)
@@ -896,7 +896,7 @@ struct SettingsTab: View {
         guard !trimmed.isEmpty else { return nil }
         let lower = trimmed.lowercased()
         if lower.contains("pairing required") {
-            return "Pairing required. Go back to Telegram and run /pair approve, then tap Connect again."
+            return "Pairing required. Go back to your OpenClaw chat and run /pair approve, then tap Connect again."
         }
         if lower.contains("device nonce required") || lower.contains("device nonce mismatch") {
             return "Secure handshake failed. Make sure Tailscale is connected, then tap Connect again."

apps/ios/Sources/Status/StatusPill.swift

@@ -38,6 +38,7 @@ struct StatusPill: View {
     var gateway: GatewayState
     var voiceWakeEnabled: Bool
     var activity: Activity?
+    var compact: Bool = false
     var brighten: Bool = false
     var onTap: () -> Void
 
@@ -45,11 +46,11 @@ struct StatusPill: View {
 
     var body: some View {
         Button(action: self.onTap) {
-            HStack(spacing: 10) {
-                HStack(spacing: 8) {
+            HStack(spacing: self.compact ? 8 : 10) {
+                HStack(spacing: self.compact ? 6 : 8) {
                     Circle()
                         .fill(self.gateway.color)
-                        .frame(width: 9, height: 9)
+                        .frame(width: self.compact ? 8 : 9, height: self.compact ? 8 : 9)
                         .scaleEffect(
                             self.gateway == .connecting && !self.reduceMotion
                                 ? (self.pulse ? 1.15 : 0.85)
@@ -58,34 +59,38 @@ struct StatusPill: View {
                         .opacity(self.gateway == .connecting && !self.reduceMotion ? (self.pulse ? 1.0 : 0.6) : 1.0)
 
                     Text(self.gateway.title)
-                        .font(.subheadline.weight(.semibold))
+                        .font((self.compact ? Font.footnote : Font.subheadline).weight(.semibold))
                         .foregroundStyle(.primary)
                 }
 
-                Divider()
-                    .frame(height: 14)
-                    .opacity(0.35)
-
                 if let activity {
-                    HStack(spacing: 6) {
+                    if !self.compact {
+                        Divider()
+                            .frame(height: 14)
+                            .opacity(0.35)
+                    }
+
+                    HStack(spacing: self.compact ? 4 : 6) {
                         Image(systemName: activity.systemImage)
-                            .font(.subheadline.weight(.semibold))
+                            .font((self.compact ? Font.footnote : Font.subheadline).weight(.semibold))
                             .foregroundStyle(activity.tint ?? .primary)
-                        Text(activity.title)
-                            .font(.subheadline.weight(.semibold))
-                            .foregroundStyle(.primary)
-                            .lineLimit(1)
+                        if !self.compact {
+                            Text(activity.title)
+                                .font(.subheadline.weight(.semibold))
+                                .foregroundStyle(.primary)
+                                .lineLimit(1)
+                        }
                     }
                     .transition(.opacity.combined(with: .move(edge: .top)))
                 } else {
                     Image(systemName: self.voiceWakeEnabled ? "mic.fill" : "mic.slash")
-                        .font(.subheadline.weight(.semibold))
+                        .font((self.compact ? Font.footnote : Font.subheadline).weight(.semibold))
                         .foregroundStyle(self.voiceWakeEnabled ? .primary : .secondary)
                         .accessibilityLabel(self.voiceWakeEnabled ? "Voice Wake enabled" : "Voice Wake disabled")
                         .transition(.opacity.combined(with: .move(edge: .top)))
                 }
             }
-            .statusGlassCard(brighten: self.brighten, verticalPadding: 8)
+            .statusGlassCard(brighten: self.brighten, verticalPadding: self.compact ? 6 : 8)
         }
         .buttonStyle(.plain)
         .accessibilityLabel("Connection Status")

apps/ios/Sources/Voice/TalkDefaults.swift

@@ -0,0 +1,3 @@
+enum TalkDefaults {
+    static let silenceTimeoutMs = 900
+}

apps/ios/Sources/Voice/TalkModeGatewayConfig.swift

@@ -0,0 +1,69 @@
+import Foundation
+import OpenClawKit
+
+struct TalkModeGatewayConfigState {
+    let activeProvider: String
+    let normalizedPayload: Bool
+    let missingResolvedPayload: Bool
+    let defaultVoiceId: String?
+    let voiceAliases: [String: String]
+    let defaultModelId: String
+    let defaultOutputFormat: String?
+    let rawConfigApiKey: String?
+    let interruptOnSpeech: Bool?
+    let silenceTimeoutMs: Int
+}
+
+enum TalkModeGatewayConfigParser {
+    static func parse(
+        config: [String: Any],
+        defaultProvider: String,
+        defaultModelIdFallback: String,
+        defaultSilenceTimeoutMs: Int
+    ) -> TalkModeGatewayConfigState {
+        let talk = TalkConfigParsing.bridgeFoundationDictionary(config["talk"] as? [String: Any])
+        let selection = TalkConfigParsing.selectProviderConfig(
+            talk,
+            defaultProvider: defaultProvider,
+            allowLegacyFallback: false)
+        let activeProvider = selection?.provider ?? defaultProvider
+        let activeConfig = selection?.config
+        let defaultVoiceId = activeConfig?["voiceId"]?.stringValue?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let voiceAliases: [String: String]
+        if let aliases = activeConfig?["voiceAliases"]?.dictionaryValue {
+            var resolved: [String: String] = [:]
+            for (key, value) in aliases {
+                guard let id = value.stringValue else { continue }
+                let normalizedKey = key.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+                let trimmedId = id.trimmingCharacters(in: .whitespacesAndNewlines)
+                guard !normalizedKey.isEmpty, !trimmedId.isEmpty else { continue }
+                resolved[normalizedKey] = trimmedId
+            }
+            voiceAliases = resolved
+        } else {
+            voiceAliases = [:]
+        }
+        let model = activeConfig?["modelId"]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let defaultModelId = (model?.isEmpty == false) ? model! : defaultModelIdFallback
+        let defaultOutputFormat = activeConfig?["outputFormat"]?.stringValue?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let rawConfigApiKey = activeConfig?["apiKey"]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let interruptOnSpeech = talk?["interruptOnSpeech"]?.boolValue
+        let silenceTimeoutMs = TalkConfigParsing.resolvedSilenceTimeoutMs(
+            talk,
+            fallback: defaultSilenceTimeoutMs)
+
+        return TalkModeGatewayConfigState(
+            activeProvider: activeProvider,
+            normalizedPayload: selection?.normalizedPayload == true,
+            missingResolvedPayload: talk != nil && selection == nil,
+            defaultVoiceId: defaultVoiceId,
+            voiceAliases: voiceAliases,
+            defaultModelId: defaultModelId,
+            defaultOutputFormat: defaultOutputFormat,
+            rawConfigApiKey: rawConfigApiKey,
+            interruptOnSpeech: interruptOnSpeech,
+            silenceTimeoutMs: silenceTimeoutMs)
+    }
+}

apps/ios/Sources/Voice/TalkModeManager.swift

@@ -34,6 +34,7 @@ final class TalkModeManager: NSObject {
     private typealias SpeechRequest = SFSpeechAudioBufferRecognitionRequest
     private static let defaultModelIdFallback = "eleven_v3"
     private static let defaultTalkProvider = "elevenlabs"
+    private static let defaultSilenceTimeoutMs = TalkDefaults.silenceTimeoutMs
     private static let redactedConfigSentinel = "__OPENCLAW_REDACTED__"
     var isEnabled: Bool = false
     var isListening: Bool = false
@@ -97,7 +98,7 @@ final class TalkModeManager: NSObject {
 
     private var gateway: GatewayNodeSession?
     private var gatewayConnected = false
-    private let silenceWindow: TimeInterval = 0.9
+    private var silenceWindow: TimeInterval = TimeInterval(TalkModeManager.defaultSilenceTimeoutMs) / 1000
     private var lastAudioActivity: Date?
     private var noiseFloorSamples: [Double] = []
     private var noiseFloor: Double?
@@ -1969,38 +1970,6 @@ extension TalkModeManager {
         return trimmed
     }
 
-    struct TalkProviderConfigSelection {
-        let provider: String
-        let config: [String: Any]
-    }
-
-    private static func normalizedTalkProviderID(_ raw: String?) -> String? {
-        let trimmed = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-        return trimmed.isEmpty ? nil : trimmed
-    }
-
-    static func selectTalkProviderConfig(_ talk: [String: Any]?) -> TalkProviderConfigSelection? {
-        guard let talk else { return nil }
-        let rawProvider = talk["provider"] as? String
-        let rawProviders = talk["providers"] as? [String: Any]
-        guard rawProvider != nil || rawProviders != nil else { return nil }
-        let providers = rawProviders ?? [:]
-        let normalizedProviders = providers.reduce(into: [String: [String: Any]]()) { acc, entry in
-            guard
-                let providerID = Self.normalizedTalkProviderID(entry.key),
-                let config = entry.value as? [String: Any]
-            else { return }
-            acc[providerID] = config
-        }
-        let providerID =
-            Self.normalizedTalkProviderID(rawProvider) ??
-            normalizedProviders.keys.min() ??
-            Self.defaultTalkProvider
-        return TalkProviderConfigSelection(
-            provider: providerID,
-            config: normalizedProviders[providerID] ?? [:])
-    }
-
     func reloadConfig() async {
         guard let gateway else { return }
         self.pcmFormatUnavailable = false
@@ -2012,40 +1981,27 @@ extension TalkModeManager {
             )
             guard let json = try JSONSerialization.jsonObject(with: res) as? [String: Any] else { return }
             guard let config = json["config"] as? [String: Any] else { return }
-            let talk = config["talk"] as? [String: Any]
-            let selection = Self.selectTalkProviderConfig(talk)
-            if talk != nil, selection == nil {
+            let parsed = TalkModeGatewayConfigParser.parse(
+                config: config,
+                defaultProvider: Self.defaultTalkProvider,
+                defaultModelIdFallback: Self.defaultModelIdFallback,
+                defaultSilenceTimeoutMs: Self.defaultSilenceTimeoutMs)
+            if parsed.missingResolvedPayload {
                 GatewayDiagnostics.log(
-                    "talk config ignored: legacy payload unsupported on iOS beta; expected talk.provider/providers")
-            }
-            let activeProvider = selection?.provider ?? Self.defaultTalkProvider
-            let activeConfig = selection?.config
-            self.defaultVoiceId = (activeConfig?["voiceId"] as? String)?
-                .trimmingCharacters(in: .whitespacesAndNewlines)
-            if let aliases = activeConfig?["voiceAliases"] as? [String: Any] {
-                var resolved: [String: String] = [:]
-                for (key, value) in aliases {
-                    guard let id = value as? String else { continue }
-                    let normalizedKey = key.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-                    let trimmedId = id.trimmingCharacters(in: .whitespacesAndNewlines)
-                    guard !normalizedKey.isEmpty, !trimmedId.isEmpty else { continue }
-                    resolved[normalizedKey] = trimmedId
-                }
-                self.voiceAliases = resolved
-            } else {
-                self.voiceAliases = [:]
+                    "talk config ignored: normalized payload missing talk.resolved")
             }
+            let activeProvider = parsed.activeProvider
+            self.defaultVoiceId = parsed.defaultVoiceId
+            self.voiceAliases = parsed.voiceAliases
             if !self.voiceOverrideActive {
                 self.currentVoiceId = self.defaultVoiceId
             }
-            let model = (activeConfig?["modelId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
-            self.defaultModelId = (model?.isEmpty == false) ? model : Self.defaultModelIdFallback
+            self.defaultModelId = parsed.defaultModelId
             if !self.modelOverrideActive {
                 self.currentModelId = self.defaultModelId
             }
-            self.defaultOutputFormat = (activeConfig?["outputFormat"] as? String)?
-                .trimmingCharacters(in: .whitespacesAndNewlines)
-            let rawConfigApiKey = (activeConfig?["apiKey"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+            self.defaultOutputFormat = parsed.defaultOutputFormat
+            let rawConfigApiKey = parsed.rawConfigApiKey
             let configApiKey = Self.normalizedTalkApiKey(rawConfigApiKey)
             let localApiKey = Self.normalizedTalkApiKey(
                 GatewaySettingsStore.loadTalkProviderApiKey(provider: activeProvider))
@@ -2064,11 +2020,13 @@ extension TalkModeManager {
             self.gatewayTalkDefaultModelId = self.defaultModelId
             self.gatewayTalkApiKeyConfigured = (self.apiKey?.isEmpty == false)
             self.gatewayTalkConfigLoaded = true
-            if let interrupt = talk?["interruptOnSpeech"] as? Bool {
+            if let interrupt = parsed.interruptOnSpeech {
                 self.interruptOnSpeech = interrupt
             }
-            if selection != nil {
-                GatewayDiagnostics.log("talk config provider=\(activeProvider)")
+            self.silenceWindow = TimeInterval(parsed.silenceTimeoutMs) / 1000
+            if parsed.normalizedPayload || parsed.defaultVoiceId != nil || parsed.rawConfigApiKey != nil {
+                GatewayDiagnostics.log(
+                    "talk config provider=\(activeProvider) silenceTimeoutMs=\(parsed.silenceTimeoutMs)")
             }
         } catch {
             self.defaultModelId = Self.defaultModelIdFallback
@@ -2079,6 +2037,7 @@ extension TalkModeManager {
             self.gatewayTalkDefaultModelId = nil
             self.gatewayTalkApiKeyConfigured = false
             self.gatewayTalkConfigLoaded = false
+            self.silenceWindow = TimeInterval(Self.defaultSilenceTimeoutMs) / 1000
         }
     }
 

apps/ios/SwiftSources.input.xcfilelist

@@ -13,6 +13,7 @@ Sources/OpenClawApp.swift
 Sources/Location/LocationService.swift
 Sources/Model/NodeAppModel.swift
 Sources/Model/NodeAppModel+Canvas.swift
+Sources/Model/WatchReplyCoordinator.swift
 Sources/RootCanvas.swift
 Sources/RootTabs.swift
 Sources/Screen/ScreenController.swift

apps/ios/Tests/Info.plist

@@ -17,8 +17,8 @@
 	<key>CFBundlePackageType</key>
 	<string>BNDL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.3.8</string>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
 	<key>CFBundleVersion</key>
-	<string>20260308</string>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
 </dict>
 </plist>

apps/ios/Tests/Logic/TalkConfigParsingTests.swift

@@ -0,0 +1,75 @@
+import Foundation
+import OpenClawKit
+import Testing
+
+private let iOSSilenceTimeoutMs = 900
+
+@Suite struct TalkConfigParsingTests {
+    @Test func rejectsNormalizedTalkProviderPayloadWithoutResolved() {
+        let talk: [String: Any] = [
+            "provider": "elevenlabs",
+            "providers": [
+                "elevenlabs": [
+                    "voiceId": "voice-normalized",
+                ],
+            ],
+            "voiceId": "voice-legacy",
+        ]
+
+        let selection = TalkConfigParsing.selectProviderConfig(
+            TalkConfigParsing.bridgeFoundationDictionary(talk),
+            defaultProvider: "elevenlabs",
+            allowLegacyFallback: false)
+        #expect(selection == nil)
+    }
+
+    @Test func ignoresLegacyTalkFieldsWhenNormalizedPayloadMissing() {
+        let talk: [String: Any] = [
+            "voiceId": "voice-legacy",
+            "apiKey": "legacy-key", // pragma: allowlist secret
+        ]
+
+        let selection = TalkConfigParsing.selectProviderConfig(
+            TalkConfigParsing.bridgeFoundationDictionary(talk),
+            defaultProvider: "elevenlabs",
+            allowLegacyFallback: false)
+        #expect(selection == nil)
+    }
+
+    @Test func readsConfiguredSilenceTimeoutMs() {
+        let talk: [String: Any] = [
+            "silenceTimeoutMs": 1500,
+        ]
+
+        #expect(
+            TalkConfigParsing.resolvedSilenceTimeoutMs(
+                TalkConfigParsing.bridgeFoundationDictionary(talk),
+                fallback: iOSSilenceTimeoutMs) == 1500)
+    }
+
+    @Test func defaultsSilenceTimeoutMsWhenMissing() {
+        #expect(TalkConfigParsing.resolvedSilenceTimeoutMs(nil, fallback: iOSSilenceTimeoutMs) == iOSSilenceTimeoutMs)
+    }
+
+    @Test func defaultsSilenceTimeoutMsWhenInvalid() {
+        let talk: [String: Any] = [
+            "silenceTimeoutMs": 0,
+        ]
+
+        #expect(
+            TalkConfigParsing.resolvedSilenceTimeoutMs(
+                TalkConfigParsing.bridgeFoundationDictionary(talk),
+                fallback: iOSSilenceTimeoutMs) == iOSSilenceTimeoutMs)
+    }
+
+    @Test func defaultsSilenceTimeoutMsWhenBool() {
+        let talk: [String: Any] = [
+            "silenceTimeoutMs": true,
+        ]
+
+        #expect(
+            TalkConfigParsing.resolvedSilenceTimeoutMs(
+                TalkConfigParsing.bridgeFoundationDictionary(talk),
+                fallback: iOSSilenceTimeoutMs) == iOSSilenceTimeoutMs)
+    }
+}

apps/ios/Tests/NodeAppModelInvokeTests.swift

@@ -83,16 +83,16 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
         #expect(json.contains("\"value\""))
     }
 
-    @Test @MainActor func chatSessionKeyDefaultsToIOSBase() {
+    @Test @MainActor func chatSessionKeyDefaultsToMainBase() {
         let appModel = NodeAppModel()
-        #expect(appModel.chatSessionKey == "ios")
+        #expect(appModel.chatSessionKey == "main")
     }
 
     @Test @MainActor func chatSessionKeyUsesAgentScopedKeyForNonDefaultAgent() {
         let appModel = NodeAppModel()
         appModel.gatewayDefaultAgentId = "main"
         appModel.setSelectedAgentId("agent-123")
-        #expect(appModel.chatSessionKey == SessionKey.makeAgentSessionKey(agentId: "agent-123", baseKey: "ios"))
+        #expect(appModel.chatSessionKey == SessionKey.makeAgentSessionKey(agentId: "agent-123", baseKey: "main"))
         #expect(appModel.mainSessionKey == "agent:agent-123:main")
     }
 
@@ -179,6 +179,41 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
         #expect(payload?["result"] as? String == "2")
     }
 
+    @Test @MainActor func pendingForegroundActionsReplayCanvasNavigate() async throws {
+        let appModel = NodeAppModel()
+        let navigateParams = OpenClawCanvasNavigateParams(url: "http://example.com/")
+        let navData = try JSONEncoder().encode(navigateParams)
+        let navJSON = String(decoding: navData, as: UTF8.self)
+
+        await appModel._test_applyPendingForegroundNodeActions([
+            (
+                id: "pending-nav-1",
+                command: OpenClawCanvasCommand.navigate.rawValue,
+                paramsJSON: navJSON
+            ),
+        ])
+
+        #expect(appModel.screen.urlString == "http://example.com/")
+    }
+
+    @Test @MainActor func pendingForegroundActionsDoNotApplyWhileBackgrounded() async throws {
+        let appModel = NodeAppModel()
+        appModel.setScenePhase(.background)
+        let navigateParams = OpenClawCanvasNavigateParams(url: "http://example.com/")
+        let navData = try JSONEncoder().encode(navigateParams)
+        let navJSON = String(decoding: navData, as: UTF8.self)
+
+        await appModel._test_applyPendingForegroundNodeActions([
+            (
+                id: "pending-nav-bg",
+                command: OpenClawCanvasCommand.navigate.rawValue,
+                paramsJSON: navJSON
+            ),
+        ])
+
+        #expect(appModel.screen.urlString.isEmpty)
+    }
+
     @Test @MainActor func handleInvokeA2UICommandsFailWhenHostMissing() async throws {
         let appModel = NodeAppModel()
 

apps/ios/Tests/TalkModeConfigParsingTests.swift

@@ -3,33 +3,7 @@ import Testing
 @testable import OpenClaw
 
 @MainActor
-@Suite struct TalkModeConfigParsingTests {
-    @Test func prefersNormalizedTalkProviderPayload() {
-        let talk: [String: Any] = [
-            "provider": "elevenlabs",
-            "providers": [
-                "elevenlabs": [
-                    "voiceId": "voice-normalized",
-                ],
-            ],
-            "voiceId": "voice-legacy",
-        ]
-
-        let selection = TalkModeManager.selectTalkProviderConfig(talk)
-        #expect(selection?.provider == "elevenlabs")
-        #expect(selection?.config["voiceId"] as? String == "voice-normalized")
-    }
-
-    @Test func ignoresLegacyTalkFieldsWhenNormalizedPayloadMissing() {
-        let talk: [String: Any] = [
-            "voiceId": "voice-legacy",
-            "apiKey": "legacy-key", // pragma: allowlist secret
-        ]
-
-        let selection = TalkModeManager.selectTalkProviderConfig(talk)
-        #expect(selection == nil)
-    }
-
+@Suite struct TalkModeManagerTests {
     @Test func detectsPCMFormatRejectionFromElevenLabsError() {
         let error = NSError(
             domain: "ElevenLabsTTS",

apps/ios/WatchApp/Info.plist

@@ -17,9 +17,9 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.3.8</string>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
 	<key>CFBundleVersion</key>
-	<string>20260308</string>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
 	<key>WKCompanionAppBundleIdentifier</key>
 	<string>$(OPENCLAW_APP_BUNDLE_ID)</string>
 	<key>WKWatchKitApp</key>

apps/ios/WatchExtension/Info.plist

@@ -15,9 +15,9 @@
 	<key>CFBundleName</key>
 	<string>$(PRODUCT_NAME)</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.3.8</string>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
 	<key>CFBundleVersion</key>
-	<string>20260308</string>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
 	<key>NSExtension</key>
 	<dict>
 		<key>NSExtensionAttributes</key>

apps/ios/fastlane/Fastfile

@@ -1,8 +1,11 @@
 require "shellwords"
 require "open3"
+require "json"
 
 default_platform(:ios)
 
+BETA_APP_IDENTIFIER = "ai.openclaw.client"
+
 def load_env_file(path)
   return unless File.exist?(path)
 
@@ -84,6 +87,111 @@ def read_asc_key_content_from_keychain
   end
 end
 
+def repo_root
+  File.expand_path("../../..", __dir__)
+end
+
+def ios_root
+  File.expand_path("..", __dir__)
+end
+
+def normalize_release_version(raw_value)
+  version = raw_value.to_s.strip.sub(/\Av/, "")
+  UI.user_error!("Missing root package.json version.") unless env_present?(version)
+  unless version.match?(/\A\d+\.\d+\.\d+(?:[.-]?beta[.-]\d+)?\z/i)
+    UI.user_error!("Invalid package.json version '#{raw_value}'. Expected 2026.3.11 or 2026.3.11-beta.1.")
+  end
+
+  version
+end
+
+def read_root_package_version
+  package_json_path = File.join(repo_root, "package.json")
+  UI.user_error!("Missing package.json at #{package_json_path}.") unless File.exist?(package_json_path)
+
+  parsed = JSON.parse(File.read(package_json_path))
+  normalize_release_version(parsed["version"])
+rescue JSON::ParserError => e
+  UI.user_error!("Invalid package.json at #{package_json_path}: #{e.message}")
+end
+
+def short_release_version(version)
+  normalize_release_version(version).sub(/([.-]?beta[.-]\d+)\z/i, "")
+end
+
+def shell_join(parts)
+  Shellwords.join(parts.compact)
+end
+
+def resolve_beta_build_number(api_key:, version:)
+  explicit = ENV["IOS_BETA_BUILD_NUMBER"]
+  if env_present?(explicit)
+    UI.user_error!("Invalid IOS_BETA_BUILD_NUMBER '#{explicit}'. Expected digits only.") unless explicit.match?(/\A\d+\z/)
+    UI.message("Using explicit iOS beta build number #{explicit}.")
+    return explicit
+  end
+
+  short_version = short_release_version(version)
+  latest_build = latest_testflight_build_number(
+    api_key: api_key,
+    app_identifier: BETA_APP_IDENTIFIER,
+    version: short_version,
+    initial_build_number: 0
+  )
+  next_build = latest_build.to_i + 1
+  UI.message("Resolved iOS beta build number #{next_build} for #{short_version} (latest TestFlight build: #{latest_build}).")
+  next_build.to_s
+end
+
+def beta_build_number_needs_asc_auth?
+  explicit = ENV["IOS_BETA_BUILD_NUMBER"]
+  !env_present?(explicit)
+end
+
+def prepare_beta_release!(version:, build_number:)
+  script_path = File.join(repo_root, "scripts", "ios-beta-prepare.sh")
+  UI.message("Preparing iOS beta release #{version} (build #{build_number}).")
+  sh(shell_join(["bash", script_path, "--build-number", build_number]))
+
+  beta_xcconfig = File.join(ios_root, "build", "BetaRelease.xcconfig")
+  UI.user_error!("Missing beta xcconfig at #{beta_xcconfig}.") unless File.exist?(beta_xcconfig)
+
+  ENV["XCODE_XCCONFIG_FILE"] = beta_xcconfig
+  beta_xcconfig
+end
+
+def build_beta_release(context)
+  version = context[:version]
+  output_directory = File.join("build", "beta")
+  archive_path = File.join(output_directory, "OpenClaw-#{version}.xcarchive")
+
+  build_app(
+    project: "OpenClaw.xcodeproj",
+    scheme: "OpenClaw",
+    configuration: "Release",
+    export_method: "app-store",
+    clean: true,
+    skip_profile_detection: true,
+    build_path: "build",
+    archive_path: archive_path,
+    output_directory: output_directory,
+    output_name: "OpenClaw-#{version}.ipa",
+    xcargs: "-allowProvisioningUpdates",
+    export_xcargs: "-allowProvisioningUpdates",
+    export_options: {
+      signingStyle: "automatic"
+    }
+  )
+
+  {
+    archive_path: archive_path,
+    build_number: context[:build_number],
+    ipa_path: lane_context[SharedValues::IPA_OUTPUT_PATH],
+    short_version: context[:short_version],
+    version: version
+  }
+end
+
 platform :ios do
   private_lane :asc_api_key do
     load_env_file(File.join(__dir__, ".env"))
@@ -132,38 +240,48 @@ platform :ios do
     api_key
   end
 
-  desc "Build + upload to TestFlight"
+  private_lane :prepare_beta_context do |options|
+    require_api_key = options[:require_api_key] == true
+    needs_api_key = require_api_key || beta_build_number_needs_asc_auth?
+    api_key = needs_api_key ? asc_api_key : nil
+    version = read_root_package_version
+    build_number = resolve_beta_build_number(api_key: api_key, version: version)
+    beta_xcconfig = prepare_beta_release!(version: version, build_number: build_number)
+
+    {
+      api_key: api_key,
+      beta_xcconfig: beta_xcconfig,
+      build_number: build_number,
+      short_version: short_release_version(version),
+      version: version
+    }
+  end
+
+  desc "Build a beta archive locally without uploading"
+  lane :beta_archive do
+    context = prepare_beta_context(require_api_key: false)
+    build = build_beta_release(context)
+    UI.success("Built iOS beta archive: version=#{build[:version]} short=#{build[:short_version]} build=#{build[:build_number]}")
+    build
+  ensure
+    ENV.delete("XCODE_XCCONFIG_FILE")
+  end
+
+  desc "Build + upload a beta to TestFlight"
   lane :beta do
-    api_key = asc_api_key
-
-    team_id = ENV["IOS_DEVELOPMENT_TEAM"]
-    if team_id.nil? || team_id.strip.empty?
-      helper_path = File.expand_path("../../../scripts/ios-team-id.sh", __dir__)
-      if File.exist?(helper_path)
-        # Keep CI/local compatibility where teams are present in keychain but not Xcode account metadata.
-        team_id = sh("IOS_ALLOW_KEYCHAIN_TEAM_FALLBACK=1 bash #{helper_path.shellescape}").strip
-      end
-    end
-    UI.user_error!("Missing IOS_DEVELOPMENT_TEAM (Apple Team ID). Add it to fastlane/.env or export it in your shell.") if team_id.nil? || team_id.strip.empty?
-
-    build_app(
-      project: "OpenClaw.xcodeproj",
-      scheme: "OpenClaw",
-      export_method: "app-store",
-      clean: true,
-      skip_profile_detection: true,
-      xcargs: "DEVELOPMENT_TEAM=#{team_id} -allowProvisioningUpdates",
-      export_xcargs: "-allowProvisioningUpdates",
-      export_options: {
-        signingStyle: "automatic"
-      }
-    )
+    context = prepare_beta_context(require_api_key: true)
+    build = build_beta_release(context)
 
     upload_to_testflight(
-      api_key: api_key,
+      api_key: context[:api_key],
+      ipa: build[:ipa_path],
       skip_waiting_for_build_processing: true,
       uses_non_exempt_encryption: false
     )
+
+    UI.success("Uploaded iOS beta: version=#{build[:version]} short=#{build[:short_version]} build=#{build[:build_number]}")
+  ensure
+    ENV.delete("XCODE_XCCONFIG_FILE")
   end
 
   desc "Upload App Store metadata (and optionally screenshots)"

apps/ios/fastlane/SETUP.md

@@ -32,9 +32,9 @@ ASC_KEYCHAIN_ACCOUNT=YOUR_MAC_USERNAME
 Optional app targeting variables (helpful if Fastlane cannot auto-resolve app by bundle):
 
 ```bash
-ASC_APP_IDENTIFIER=ai.openclaw.ios
+ASC_APP_IDENTIFIER=ai.openclaw.client
 # or
-ASC_APP_ID=6760218713
+ASC_APP_ID=YOUR_APP_STORE_CONNECT_APP_ID
 ```
 
 File-based fallback (CI/non-macOS):
@@ -60,9 +60,37 @@ cd apps/ios
 fastlane ios auth_check
 ```
 
-Run:
+ASC auth is only required when:
+
+- uploading to TestFlight
+- auto-resolving the next build number from App Store Connect
+
+If you pass `--build-number` to `pnpm ios:beta:archive`, the local archive path does not need ASC auth.
+
+Archive locally without upload:
+
+```bash
+pnpm ios:beta:archive
+```
+
+Upload to TestFlight:
+
+```bash
+pnpm ios:beta
+```
+
+Direct Fastlane entry point:
 
 ```bash
 cd apps/ios
-fastlane beta
+fastlane ios beta
 ```
+
+Versioning rules:
+
+- Root `package.json.version` is the single source of truth for iOS
+- Use `YYYY.M.D` for stable versions and `YYYY.M.D-beta.N` for beta versions
+- Fastlane stamps `CFBundleShortVersionString` to `YYYY.M.D`
+- Fastlane resolves `CFBundleVersion` as the next integer TestFlight build number for that short version
+- The beta flow regenerates `apps/ios/OpenClaw.xcodeproj` from `apps/ios/project.yml` before archiving
+- Local beta signing uses a temporary generated xcconfig and leaves local development signing overrides untouched

apps/ios/fastlane/metadata/README.md

@@ -6,7 +6,7 @@ This directory is used by `fastlane deliver` for App Store Connect text metadata
 
 ```bash
 cd apps/ios
-ASC_APP_ID=6760218713 \
+ASC_APP_ID=YOUR_APP_STORE_CONNECT_APP_ID \
 DELIVER_METADATA=1 fastlane ios metadata
 ```
 

apps/ios/project.yml

@@ -25,6 +25,15 @@ schemes:
     test:
       targets:
         - OpenClawTests
+        - OpenClawLogicTests
+  OpenClawLogicTests:
+    shared: true
+    build:
+      targets:
+        OpenClawLogicTests: all
+    test:
+      targets:
+        - OpenClawLogicTests
 
 targets:
   OpenClaw:
@@ -98,8 +107,8 @@ targets:
           - CFBundleURLName: ai.openclaw.ios
             CFBundleURLSchemes:
               - openclaw
-        CFBundleShortVersionString: "2026.3.8"
-        CFBundleVersion: "20260308"
+        CFBundleShortVersionString: "$(OPENCLAW_MARKETING_VERSION)"
+        CFBundleVersion: "$(OPENCLAW_BUILD_VERSION)"
         UILaunchScreen: {}
         UIApplicationSceneManifest:
           UIApplicationSupportsMultipleScenes: false
@@ -117,8 +126,11 @@ targets:
         NSLocationWhenInUseUsageDescription: OpenClaw uses your location when you allow location sharing.
         NSLocationAlwaysAndWhenInUseUsageDescription: OpenClaw can share your location in the background when you enable Always.
         NSMicrophoneUsageDescription: OpenClaw needs microphone access for voice wake.
+        NSMotionUsageDescription: OpenClaw may use motion data to support device-aware interactions and automations.
+        NSPhotoLibraryUsageDescription: OpenClaw needs photo library access when you choose existing photos to share with your assistant.
         NSSpeechRecognitionUsageDescription: OpenClaw uses on-device speech recognition for voice wake.
         NSSupportsLiveActivities: true
+        ITSAppUsesNonExemptEncryption: false
         UISupportedInterfaceOrientations:
           - UIInterfaceOrientationPortrait
           - UIInterfaceOrientationPortraitUpsideDown
@@ -156,8 +168,8 @@ targets:
       path: ShareExtension/Info.plist
       properties:
         CFBundleDisplayName: OpenClaw Share
-        CFBundleShortVersionString: "2026.3.8"
-        CFBundleVersion: "20260308"
+        CFBundleShortVersionString: "$(OPENCLAW_MARKETING_VERSION)"
+        CFBundleVersion: "$(OPENCLAW_BUILD_VERSION)"
         NSExtension:
           NSExtensionPointIdentifier: com.apple.share-services
           NSExtensionPrincipalClass: "$(PRODUCT_MODULE_NAME).ShareViewController"
@@ -193,8 +205,8 @@ targets:
       path: ActivityWidget/Info.plist
       properties:
         CFBundleDisplayName: OpenClaw Activity
-        CFBundleShortVersionString: "2026.3.8"
-        CFBundleVersion: "20260308"
+        CFBundleShortVersionString: "$(OPENCLAW_MARKETING_VERSION)"
+        CFBundleVersion: "$(OPENCLAW_BUILD_VERSION)"
         NSSupportsLiveActivities: true
         NSExtension:
           NSExtensionPointIdentifier: com.apple.widgetkit-extension
@@ -212,6 +224,7 @@ targets:
       Release: Config/Signing.xcconfig
     settings:
       base:
+        ASSETCATALOG_COMPILER_APPICON_NAME: AppIcon
         ENABLE_APPINTENTS_METADATA: NO
         ENABLE_APP_INTENTS_METADATA_GENERATION: NO
         PRODUCT_BUNDLE_IDENTIFIER: "$(OPENCLAW_WATCH_APP_BUNDLE_ID)"
@@ -219,8 +232,8 @@ targets:
       path: WatchApp/Info.plist
       properties:
         CFBundleDisplayName: OpenClaw
-        CFBundleShortVersionString: "2026.3.8"
-        CFBundleVersion: "20260308"
+        CFBundleShortVersionString: "$(OPENCLAW_MARKETING_VERSION)"
+        CFBundleVersion: "$(OPENCLAW_BUILD_VERSION)"
         WKCompanionAppBundleIdentifier: "$(OPENCLAW_APP_BUNDLE_ID)"
         WKWatchKitApp: true
 
@@ -244,8 +257,8 @@ targets:
       path: WatchExtension/Info.plist
       properties:
         CFBundleDisplayName: OpenClaw
-        CFBundleShortVersionString: "2026.3.8"
-        CFBundleVersion: "20260308"
+        CFBundleShortVersionString: "$(OPENCLAW_MARKETING_VERSION)"
+        CFBundleVersion: "$(OPENCLAW_BUILD_VERSION)"
         NSExtension:
           NSExtensionAttributes:
             WKAppBundleIdentifier: "$(OPENCLAW_WATCH_APP_BUNDLE_ID)"
@@ -259,6 +272,8 @@ targets:
       Release: Signing.xcconfig
     sources:
       - path: Tests
+        excludes:
+          - Logic
     dependencies:
       - target: OpenClaw
       - package: Swabble
@@ -279,5 +294,31 @@ targets:
       path: Tests/Info.plist
       properties:
         CFBundleDisplayName: OpenClawTests
-        CFBundleShortVersionString: "2026.3.8"
-        CFBundleVersion: "20260308"
+        CFBundleShortVersionString: "$(OPENCLAW_MARKETING_VERSION)"
+        CFBundleVersion: "$(OPENCLAW_BUILD_VERSION)"
+
+  OpenClawLogicTests:
+    type: bundle.unit-test
+    platform: iOS
+    configFiles:
+      Debug: Signing.xcconfig
+      Release: Signing.xcconfig
+    sources:
+      - path: Tests/Logic
+    dependencies:
+      - package: OpenClawKit
+    settings:
+      base:
+        CODE_SIGN_IDENTITY: "Apple Development"
+        CODE_SIGN_STYLE: "$(OPENCLAW_CODE_SIGN_STYLE)"
+        DEVELOPMENT_TEAM: "$(OPENCLAW_DEVELOPMENT_TEAM)"
+        PRODUCT_BUNDLE_IDENTIFIER: ai.openclaw.ios.logic-tests
+        ENABLE_APP_INTENTS_METADATA_GENERATION: NO
+        SWIFT_VERSION: "6.0"
+        SWIFT_STRICT_CONCURRENCY: complete
+    info:
+      path: Tests/Info.plist
+      properties:
+        CFBundleDisplayName: OpenClawLogicTests
+        CFBundleShortVersionString: "$(OPENCLAW_MARKETING_VERSION)"
+        CFBundleVersion: "$(OPENCLAW_BUILD_VERSION)"

apps/macos/Sources/OpenClaw/AnyCodable+Helpers.swift

@@ -4,40 +4,3 @@ import OpenClawKit
 // Prefer the OpenClawKit wrapper to keep gateway request payloads consistent.
 typealias AnyCodable = OpenClawKit.AnyCodable
 typealias InstanceIdentity = OpenClawKit.InstanceIdentity
-
-extension AnyCodable {
-    var stringValue: String? {
-        self.value as? String
-    }
-
-    var boolValue: Bool? {
-        self.value as? Bool
-    }
-
-    var intValue: Int? {
-        self.value as? Int
-    }
-
-    var doubleValue: Double? {
-        self.value as? Double
-    }
-
-    var dictionaryValue: [String: AnyCodable]? {
-        self.value as? [String: AnyCodable]
-    }
-
-    var arrayValue: [AnyCodable]? {
-        self.value as? [AnyCodable]
-    }
-
-    var foundationValue: Any {
-        switch self.value {
-        case let dict as [String: AnyCodable]:
-            dict.mapValues { $0.foundationValue }
-        case let array as [AnyCodable]:
-            array.map(\.foundationValue)
-        default:
-            self.value
-        }
-    }
-}

apps/macos/Sources/OpenClaw/AppState.swift

@@ -9,6 +9,7 @@ import SwiftUI
 final class AppState {
     private let isPreview: Bool
     private var isInitializing = true
+    private var isApplyingRemoteTokenConfig = false
     private var configWatcher: ConfigFileWatcher?
     private var suppressVoiceWakeGlobalSync = false
     private var voiceWakeGlobalSyncTask: Task<Void, Never>?
@@ -213,6 +214,18 @@ final class AppState {
         didSet { self.syncGatewayConfigIfNeeded() }
     }
 
+    var remoteToken: String {
+        didSet {
+            guard !self.isApplyingRemoteTokenConfig else { return }
+            self.remoteTokenDirty = true
+            self.remoteTokenUnsupported = false
+            self.syncGatewayConfigIfNeeded()
+        }
+    }
+
+    private(set) var remoteTokenDirty = false
+    private(set) var remoteTokenUnsupported = false
+
     var remoteIdentity: String {
         didSet { self.ifNotPreview { UserDefaults.standard.set(self.remoteIdentity, forKey: remoteIdentityKey) } }
     }
@@ -281,6 +294,7 @@ final class AppState {
 
         let configRoot = OpenClawConfigFile.loadDict()
         let configRemoteUrl = GatewayRemoteConfig.resolveUrlString(root: configRoot)
+        let configRemoteToken = GatewayRemoteConfig.resolveTokenValue(root: configRoot)
         let configRemoteTransport = GatewayRemoteConfig.resolveTransport(root: configRoot)
         let resolvedConnectionMode = ConnectionModeResolver.resolve(root: configRoot).mode
         self.remoteTransport = configRemoteTransport
@@ -297,6 +311,9 @@ final class AppState {
             self.remoteTarget = storedRemoteTarget
         }
         self.remoteUrl = configRemoteUrl ?? ""
+        self.remoteToken = configRemoteToken.textFieldValue
+        self.remoteTokenDirty = false
+        self.remoteTokenUnsupported = configRemoteToken.isUnsupportedNonString
         self.remoteIdentity = UserDefaults.standard.string(forKey: remoteIdentityKey) ?? ""
         self.remoteProjectRoot = UserDefaults.standard.string(forKey: remoteProjectRootKey) ?? ""
         self.remoteCliPath = UserDefaults.standard.string(forKey: remoteCliPathKey) ?? ""
@@ -374,13 +391,29 @@ final class AppState {
         return false
     }
 
+    private func applyRemoteTokenState(_ tokenValue: GatewayRemoteConfig.TokenValue) {
+        let nextToken = tokenValue.textFieldValue
+        let unsupported = tokenValue.isUnsupportedNonString
+        guard self.remoteToken != nextToken || self.remoteTokenDirty || self.remoteTokenUnsupported != unsupported
+        else {
+            return
+        }
+        self.isApplyingRemoteTokenConfig = true
+        self.remoteToken = nextToken
+        self.isApplyingRemoteTokenConfig = false
+        self.remoteTokenDirty = false
+        self.remoteTokenUnsupported = unsupported
+    }
+
     private static func updatedRemoteGatewayConfig(
         current: [String: Any],
         transport: RemoteTransport,
         remoteUrl: String,
         remoteHost: String?,
         remoteTarget: String,
-        remoteIdentity: String) -> (remote: [String: Any], changed: Bool)
+        remoteIdentity: String,
+        remoteToken: String,
+        remoteTokenDirty: Bool) -> (remote: [String: Any], changed: Bool)
     {
         var remote = current
         var changed = false
@@ -417,6 +450,10 @@ final class AppState {
             changed = Self.updateGatewayString(&remote, key: "sshIdentity", value: remoteIdentity) || changed
         }
 
+        if remoteTokenDirty {
+            changed = Self.updateGatewayString(&remote, key: "token", value: remoteToken) || changed
+        }
+
         return (remote, changed)
     }
 
@@ -439,6 +476,7 @@ final class AppState {
         let gateway = root["gateway"] as? [String: Any]
         let modeRaw = (gateway?["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
         let remoteUrl = GatewayRemoteConfig.resolveUrlString(root: root)
+        let remoteToken = GatewayRemoteConfig.resolveTokenValue(root: root)
         let hasRemoteUrl = !(remoteUrl?
             .trimmingCharacters(in: .whitespacesAndNewlines)
             .isEmpty ?? true)
@@ -470,6 +508,7 @@ final class AppState {
         if remoteUrlText != self.remoteUrl {
             self.remoteUrl = remoteUrlText
         }
+        self.applyRemoteTokenState(remoteToken)
 
         let targetMode = desiredMode ?? self.connectionMode
         if targetMode == .remote,
@@ -496,14 +535,20 @@ final class AppState {
         }
     }
 
-    private func syncGatewayConfigIfNeeded() {
-        guard !self.isPreview, !self.isInitializing else { return }
+    private static func syncedGatewayRoot(
+        currentRoot: [String: Any],
+        connectionMode: ConnectionMode,
+        remoteTransport: RemoteTransport,
+        remoteTarget: String,
+        remoteIdentity: String,
+        remoteUrl: String,
+        remoteToken: String,
+        remoteTokenDirty: Bool) -> (root: [String: Any], changed: Bool)
+    {
+        var root = currentRoot
+        var gateway = root["gateway"] as? [String: Any] ?? [:]
+        var changed = false
 
-        let connectionMode = self.connectionMode
-        let remoteTarget = self.remoteTarget
-        let remoteIdentity = self.remoteIdentity
-        let remoteTransport = self.remoteTransport
-        let remoteUrl = self.remoteUrl
         let desiredMode: String? = switch connectionMode {
         case .local:
             "local"
@@ -512,50 +557,70 @@ final class AppState {
         case .unconfigured:
             nil
         }
-        let remoteHost = connectionMode == .remote
-            ? CommandResolver.parseSSHTarget(remoteTarget)?.host
-            : nil
 
-        Task { @MainActor in
-            // Keep app-only connection settings local to avoid overwriting remote gateway config.
-            var root = OpenClawConfigFile.loadDict()
-            var gateway = root["gateway"] as? [String: Any] ?? [:]
-            var changed = false
-
-            let currentMode = (gateway["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
-            if let desiredMode {
-                if currentMode != desiredMode {
-                    gateway["mode"] = desiredMode
-                    changed = true
-                }
-            } else if currentMode != nil {
-                gateway.removeValue(forKey: "mode")
+        let currentMode = (gateway["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let desiredMode {
+            if currentMode != desiredMode {
+                gateway["mode"] = desiredMode
                 changed = true
             }
-
-            if connectionMode == .remote {
-                let currentRemote = gateway["remote"] as? [String: Any] ?? [:]
-                let updated = Self.updatedRemoteGatewayConfig(
-                    current: currentRemote,
-                    transport: remoteTransport,
-                    remoteUrl: remoteUrl,
-                    remoteHost: remoteHost,
-                    remoteTarget: remoteTarget,
-                    remoteIdentity: remoteIdentity)
-                if updated.changed {
-                    gateway["remote"] = updated.remote
-                    changed = true
-                }
-            }
-
-            guard changed else { return }
-            if gateway.isEmpty {
-                root.removeValue(forKey: "gateway")
-            } else {
-                root["gateway"] = gateway
-            }
-            OpenClawConfigFile.saveDict(root)
+        } else if currentMode != nil {
+            gateway.removeValue(forKey: "mode")
+            changed = true
         }
+
+        if connectionMode == .remote {
+            let remoteHost = CommandResolver.parseSSHTarget(remoteTarget)?.host
+            let currentRemote = gateway["remote"] as? [String: Any] ?? [:]
+            let updated = Self.updatedRemoteGatewayConfig(
+                current: currentRemote,
+                transport: remoteTransport,
+                remoteUrl: remoteUrl,
+                remoteHost: remoteHost,
+                remoteTarget: remoteTarget,
+                remoteIdentity: remoteIdentity,
+                remoteToken: remoteToken,
+                remoteTokenDirty: remoteTokenDirty)
+            if updated.changed {
+                gateway["remote"] = updated.remote
+                changed = true
+            }
+        }
+
+        guard changed else { return (currentRoot, false) }
+
+        if gateway.isEmpty {
+            root.removeValue(forKey: "gateway")
+        } else {
+            root["gateway"] = gateway
+        }
+        return (root, true)
+    }
+
+    private func syncGatewayConfigIfNeeded() {
+        guard !self.isPreview, !self.isInitializing else { return }
+
+        Task { @MainActor in
+            self.syncGatewayConfigNow()
+        }
+    }
+
+    @MainActor
+    func syncGatewayConfigNow() {
+        guard !self.isPreview, !self.isInitializing else { return }
+
+        // Keep app-only connection settings local to avoid overwriting remote gateway config.
+        let synced = Self.syncedGatewayRoot(
+            currentRoot: OpenClawConfigFile.loadDict(),
+            connectionMode: self.connectionMode,
+            remoteTransport: self.remoteTransport,
+            remoteTarget: self.remoteTarget,
+            remoteIdentity: self.remoteIdentity,
+            remoteUrl: self.remoteUrl,
+            remoteToken: self.remoteToken,
+            remoteTokenDirty: self.remoteTokenDirty)
+        guard synced.changed else { return }
+        OpenClawConfigFile.saveDict(synced.root)
     }
 
     func triggerVoiceEars(ttl: TimeInterval? = 5) {
@@ -697,6 +762,7 @@ extension AppState {
         state.canvasEnabled = true
         state.remoteTarget = "user@example.com"
         state.remoteUrl = "wss://gateway.example.ts.net"
+        state.remoteToken = "example-token"
         state.remoteIdentity = "~/.ssh/id_ed25519"
         state.remoteProjectRoot = "~/Projects/openclaw"
         state.remoteCliPath = ""
@@ -704,6 +770,53 @@ extension AppState {
     }
 }
 
+#if DEBUG
+@MainActor
+extension AppState {
+    static func _testUpdatedRemoteGatewayConfig(
+        current: [String: Any],
+        transport: RemoteTransport,
+        remoteUrl: String,
+        remoteHost: String?,
+        remoteTarget: String,
+        remoteIdentity: String,
+        remoteToken: String,
+        remoteTokenDirty: Bool) -> [String: Any]
+    {
+        Self.updatedRemoteGatewayConfig(
+            current: current,
+            transport: transport,
+            remoteUrl: remoteUrl,
+            remoteHost: remoteHost,
+            remoteTarget: remoteTarget,
+            remoteIdentity: remoteIdentity,
+            remoteToken: remoteToken,
+            remoteTokenDirty: remoteTokenDirty).remote
+    }
+
+    static func _testSyncedGatewayRoot(
+        currentRoot: [String: Any],
+        connectionMode: ConnectionMode,
+        remoteTransport: RemoteTransport,
+        remoteTarget: String,
+        remoteIdentity: String,
+        remoteUrl: String,
+        remoteToken: String,
+        remoteTokenDirty: Bool) -> [String: Any]
+    {
+        Self.syncedGatewayRoot(
+            currentRoot: currentRoot,
+            connectionMode: connectionMode,
+            remoteTransport: remoteTransport,
+            remoteTarget: remoteTarget,
+            remoteIdentity: remoteIdentity,
+            remoteUrl: remoteUrl,
+            remoteToken: remoteToken,
+            remoteTokenDirty: remoteTokenDirty).root
+    }
+}
+#endif
+
 @MainActor
 enum AppStateStore {
     static let shared = AppState()

apps/macos/Sources/OpenClaw/ControlChannel.swift

@@ -188,6 +188,10 @@ final class ControlChannel {
             return desc
         }
 
+        if let authIssue = RemoteGatewayAuthIssue(error: error) {
+            return authIssue.statusMessage
+        }
+
         // If the gateway explicitly rejects the hello (e.g., auth/token mismatch), surface it.
         if let urlErr = error as? URLError,
            urlErr.code == .dataNotAllowed // used for WS close 1008 auth failures

apps/macos/Sources/OpenClaw/GatewayDiscoverySelectionSupport.swift

@@ -6,11 +6,16 @@ enum GatewayDiscoverySelectionSupport {
         gateway: GatewayDiscoveryModel.DiscoveredGateway,
         state: AppState)
     {
-        if state.remoteTransport == .direct {
-            state.remoteUrl = GatewayDiscoveryHelpers.directUrl(for: gateway) ?? ""
-        } else {
-            state.remoteTarget = GatewayDiscoveryHelpers.sshTarget(for: gateway) ?? ""
+        let preferredTransport = self.preferredTransport(
+            for: gateway,
+            current: state.remoteTransport)
+        if preferredTransport != state.remoteTransport {
+            state.remoteTransport = preferredTransport
         }
+
+        state.remoteUrl = GatewayDiscoveryHelpers.directUrl(for: gateway) ?? ""
+        state.remoteTarget = GatewayDiscoveryHelpers.sshTarget(for: gateway) ?? ""
+
         if let endpoint = GatewayDiscoveryHelpers.serviceEndpoint(for: gateway) {
             OpenClawConfigFile.setRemoteGatewayUrl(
                 host: endpoint.host,
@@ -19,4 +24,30 @@ enum GatewayDiscoverySelectionSupport {
             OpenClawConfigFile.clearRemoteGatewayUrl()
         }
     }
+
+    static func preferredTransport(
+        for gateway: GatewayDiscoveryModel.DiscoveredGateway,
+        current: AppState.RemoteTransport) -> AppState.RemoteTransport
+    {
+        if self.shouldPreferDirectTransport(for: gateway) {
+            return .direct
+        }
+        return current
+    }
+
+    static func shouldPreferDirectTransport(
+        for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> Bool
+    {
+        guard GatewayDiscoveryHelpers.directUrl(for: gateway) != nil else { return false }
+        if gateway.stableID.hasPrefix("tailscale-serve|") {
+            return true
+        }
+        guard let host = GatewayDiscoveryHelpers.resolvedServiceHost(for: gateway)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+        else {
+            return false
+        }
+        return host.hasSuffix(".ts.net")
+    }
 }

apps/macos/Sources/OpenClaw/GatewayEndpointStore.swift

@@ -188,13 +188,7 @@ actor GatewayEndpointStore {
 
     private static func resolveConfigToken(isRemote: Bool, root: [String: Any]) -> String? {
         if isRemote {
-            if let gateway = root["gateway"] as? [String: Any],
-               let remote = gateway["remote"] as? [String: Any],
-               let token = remote["token"] as? String
-            {
-                return token.trimmingCharacters(in: .whitespacesAndNewlines)
-            }
-            return nil
+            return GatewayRemoteConfig.resolveTokenString(root: root)
         }
 
         if let gateway = root["gateway"] as? [String: Any],

apps/macos/Sources/OpenClaw/GatewayRemoteConfig.swift

@@ -2,6 +2,28 @@ import Foundation
 import OpenClawKit
 
 enum GatewayRemoteConfig {
+    enum TokenValue: Equatable {
+        case missing
+        case plaintext(String)
+        case unsupportedNonString
+
+        var textFieldValue: String {
+            switch self {
+            case let .plaintext(token):
+                token
+            case .missing, .unsupportedNonString:
+                ""
+            }
+        }
+
+        var isUnsupportedNonString: Bool {
+            if case .unsupportedNonString = self {
+                return true
+            }
+            return false
+        }
+    }
+
     static func resolveTransport(root: [String: Any]) -> AppState.RemoteTransport {
         guard let gateway = root["gateway"] as? [String: Any],
               let remote = gateway["remote"] as? [String: Any],
@@ -24,6 +46,29 @@ enum GatewayRemoteConfig {
         return trimmed.isEmpty ? nil : trimmed
     }
 
+    static func resolveTokenValue(root: [String: Any]) -> TokenValue {
+        guard let gateway = root["gateway"] as? [String: Any],
+              let remote = gateway["remote"] as? [String: Any],
+              let tokenRaw = remote["token"]
+        else {
+            return .missing
+        }
+        guard let tokenString = tokenRaw as? String else {
+            return .unsupportedNonString
+        }
+        let trimmed = tokenString.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? .missing : .plaintext(trimmed)
+    }
+
+    static func resolveTokenString(root: [String: Any]) -> String? {
+        switch self.resolveTokenValue(root: root) {
+        case let .plaintext(token):
+            token
+        case .missing, .unsupportedNonString:
+            nil
+        }
+    }
+
     static func resolveGatewayUrl(root: [String: Any]) -> URL? {
         guard let raw = self.resolveUrlString(root: root) else { return nil }
         return self.normalizeGatewayUrl(raw)

apps/macos/Sources/OpenClaw/GeneralSettings.swift

@@ -149,6 +149,7 @@ struct GeneralSettings: View {
             } else {
                 self.remoteDirectRow
             }
+            self.remoteTokenRow
 
             GatewayDiscoveryInlineList(
                 discovery: self.gatewayDiscovery,
@@ -291,6 +292,30 @@ struct GeneralSettings: View {
         }
     }
 
+    private var remoteTokenRow: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(alignment: .center, spacing: 10) {
+                Text("Gateway token")
+                    .font(.callout.weight(.semibold))
+                    .frame(width: self.remoteLabelWidth, alignment: .leading)
+                SecureField("remote gateway auth token (gateway.remote.token)", text: self.$state.remoteToken)
+                    .textFieldStyle(.roundedBorder)
+                    .frame(maxWidth: .infinity)
+            }
+            Text("Used when the remote gateway requires token auth.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .padding(.leading, self.remoteLabelWidth + 10)
+            if self.state.remoteTokenUnsupported {
+                Text(
+                    "The current gateway.remote.token value is not plain text. OpenClaw for macOS cannot use it directly; enter a plaintext token here to replace it.")
+                    .font(.caption)
+                    .foregroundStyle(.orange)
+                    .padding(.leading, self.remoteLabelWidth + 10)
+            }
+        }
+    }
+
     private func remoteTestButton(disabled: Bool) -> some View {
         Button {
             Task { await self.testRemote() }
@@ -323,10 +348,18 @@ struct GeneralSettings: View {
             Text("Testing…")
                 .font(.caption)
                 .foregroundStyle(.secondary)
-        case .ok:
-            Label("Ready", systemImage: "checkmark.circle.fill")
-                .font(.caption)
-                .foregroundStyle(.green)
+        case let .ok(success):
+            VStack(alignment: .leading, spacing: 2) {
+                Label(success.title, systemImage: "checkmark.circle.fill")
+                    .font(.caption)
+                    .foregroundStyle(.green)
+                if let detail = success.detail {
+                    Text(detail)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+            }
         case let .failed(message):
             Text(message)
                 .font(.caption)
@@ -493,7 +526,7 @@ struct GeneralSettings: View {
 private enum RemoteStatus: Equatable {
     case idle
     case checking
-    case ok
+    case ok(RemoteGatewayProbeSuccess)
     case failed(String)
 }
 
@@ -533,114 +566,14 @@ extension GeneralSettings {
     @MainActor
     func testRemote() async {
         self.remoteStatus = .checking
-        let settings = CommandResolver.connectionSettings()
-        if self.state.remoteTransport == .direct {
-            let trimmedUrl = self.state.remoteUrl.trimmingCharacters(in: .whitespacesAndNewlines)
-            guard !trimmedUrl.isEmpty else {
-                self.remoteStatus = .failed("Set a gateway URL first")
-                return
-            }
-            guard Self.isValidWsUrl(trimmedUrl) else {
-                self.remoteStatus = .failed(
-                    "Gateway URL must use wss:// for remote hosts (ws:// only for localhost)")
-                return
-            }
-        } else {
-            guard !settings.target.isEmpty else {
-                self.remoteStatus = .failed("Set an SSH target first")
-                return
-            }
-
-            // Step 1: basic SSH reachability check
-            guard let sshCommand = Self.sshCheckCommand(
-                target: settings.target,
-                identity: settings.identity)
-            else {
-                self.remoteStatus = .failed("SSH target is invalid")
-                return
-            }
-            let sshResult = await ShellExecutor.run(
-                command: sshCommand,
-                cwd: nil,
-                env: nil,
-                timeout: 8)
-
-            guard sshResult.ok else {
-                self.remoteStatus = .failed(self.formatSSHFailure(sshResult, target: settings.target))
-                return
-            }
+        switch await RemoteGatewayProbe.run() {
+        case let .ready(success):
+            self.remoteStatus = .ok(success)
+        case let .authIssue(issue):
+            self.remoteStatus = .failed(issue.statusMessage)
+        case let .failed(message):
+            self.remoteStatus = .failed(message)
         }
-
-        // Step 2: control channel health check
-        let originalMode = AppStateStore.shared.connectionMode
-        do {
-            try await ControlChannel.shared.configure(mode: .remote(
-                target: settings.target,
-                identity: settings.identity))
-            let data = try await ControlChannel.shared.health(timeout: 10)
-            if decodeHealthSnapshot(from: data) != nil {
-                self.remoteStatus = .ok
-            } else {
-                self.remoteStatus = .failed("Control channel returned invalid health JSON")
-            }
-        } catch {
-            self.remoteStatus = .failed(error.localizedDescription)
-        }
-
-        // Restore original mode if we temporarily switched
-        switch originalMode {
-        case .remote:
-            break
-        case .local:
-            try? await ControlChannel.shared.configure(mode: .local)
-        case .unconfigured:
-            await ControlChannel.shared.disconnect()
-        }
-    }
-
-    private static func isValidWsUrl(_ raw: String) -> Bool {
-        GatewayRemoteConfig.normalizeGatewayUrl(raw) != nil
-    }
-
-    private static func sshCheckCommand(target: String, identity: String) -> [String]? {
-        guard let parsed = CommandResolver.parseSSHTarget(target) else { return nil }
-        let options = [
-            "-o", "BatchMode=yes",
-            "-o", "ConnectTimeout=5",
-            "-o", "StrictHostKeyChecking=accept-new",
-            "-o", "UpdateHostKeys=yes",
-        ]
-        let args = CommandResolver.sshArguments(
-            target: parsed,
-            identity: identity,
-            options: options,
-            remoteCommand: ["echo", "ok"])
-        return ["/usr/bin/ssh"] + args
-    }
-
-    private func formatSSHFailure(_ response: Response, target: String) -> String {
-        let payload = response.payload.flatMap { String(data: $0, encoding: .utf8) }
-        let trimmed = payload?
-            .trimmingCharacters(in: .whitespacesAndNewlines)
-            .split(whereSeparator: \.isNewline)
-            .joined(separator: " ")
-        if let trimmed,
-           trimmed.localizedCaseInsensitiveContains("host key verification failed")
-        {
-            let host = CommandResolver.parseSSHTarget(target)?.host ?? target
-            return "SSH check failed: Host key verification failed. Remove the old key with " +
-                "`ssh-keygen -R \(host)` and try again."
-        }
-        if let trimmed, !trimmed.isEmpty {
-            if let message = response.message, message.hasPrefix("exit ") {
-                return "SSH check failed: \(trimmed) (\(message))"
-            }
-            return "SSH check failed: \(trimmed)"
-        }
-        if let message = response.message {
-            return "SSH check failed (\(message))"
-        }
-        return "SSH check failed"
     }
 
     private func revealLogs() {
@@ -692,6 +625,7 @@ extension GeneralSettings {
         state.remoteTransport = .ssh
         state.remoteTarget = "user@host:2222"
         state.remoteUrl = "wss://gateway.example.ts.net"
+        state.remoteToken = "example-token"
         state.remoteIdentity = "/tmp/id_ed25519"
         state.remoteProjectRoot = "/tmp/openclaw"
         state.remoteCliPath = "/tmp/openclaw"

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

@@ -146,8 +146,8 @@ actor MacNodeBrowserProxy {
             request.setValue(password, forHTTPHeaderField: "x-openclaw-password")
         }
 
-        if method != "GET", let body = params.body?.value {
-            request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [.fragmentsAllowed])
+        if method != "GET", let body = params.body {
+            request.httpBody = try JSONSerialization.data(withJSONObject: body.foundationValue, options: [.fragmentsAllowed])
             request.setValue("application/json", forHTTPHeaderField: "Content-Type")
         }
 

apps/macos/Sources/OpenClaw/Onboarding.swift

@@ -9,6 +9,13 @@ enum UIStrings {
     static let welcomeTitle = "Welcome to OpenClaw"
 }
 
+enum RemoteOnboardingProbeState: Equatable {
+    case idle
+    case checking
+    case ok(RemoteGatewayProbeSuccess)
+    case failed(String)
+}
+
 @MainActor
 final class OnboardingController {
     static let shared = OnboardingController()
@@ -72,6 +79,9 @@ struct OnboardingView: View {
     @State var didAutoKickoff = false
     @State var showAdvancedConnection = false
     @State var preferredGatewayID: String?
+    @State var remoteProbeState: RemoteOnboardingProbeState = .idle
+    @State var remoteAuthIssue: RemoteGatewayAuthIssue?
+    @State var suppressRemoteProbeReset = false
     @State var gatewayDiscovery: GatewayDiscoveryModel
     @State var onboardingChatModel: OpenClawChatViewModel
     @State var onboardingSkillsModel = SkillsSettingsModel()

apps/macos/Sources/OpenClaw/OnboardingView+Pages.swift

@@ -2,6 +2,7 @@ import AppKit
 import OpenClawChatUI
 import OpenClawDiscovery
 import OpenClawIPC
+import OpenClawKit
 import SwiftUI
 
 extension OnboardingView {
@@ -97,6 +98,11 @@ extension OnboardingView {
 
                     self.gatewayDiscoverySection()
 
+                    if self.shouldShowRemoteConnectionSection {
+                        Divider().padding(.vertical, 4)
+                        self.remoteConnectionSection()
+                    }
+
                     self.connectionChoiceButton(
                         title: "Configure later",
                         subtitle: "Don’t start the Gateway yet.",
@@ -109,6 +115,22 @@ extension OnboardingView {
                 }
             }
         }
+        .onChange(of: self.state.connectionMode) { _, newValue in
+            guard Self.shouldResetRemoteProbeFeedback(
+                for: newValue,
+                suppressReset: self.suppressRemoteProbeReset)
+            else { return }
+            self.resetRemoteProbeFeedback()
+        }
+        .onChange(of: self.state.remoteTransport) { _, _ in
+            self.resetRemoteProbeFeedback()
+        }
+        .onChange(of: self.state.remoteTarget) { _, _ in
+            self.resetRemoteProbeFeedback()
+        }
+        .onChange(of: self.state.remoteUrl) { _, _ in
+            self.resetRemoteProbeFeedback()
+        }
     }
 
     private var localGatewaySubtitle: String {
@@ -270,6 +292,248 @@ extension OnboardingView {
         }
     }
 
+    private var shouldShowRemoteConnectionSection: Bool {
+        self.state.connectionMode == .remote ||
+            self.showAdvancedConnection ||
+            self.remoteProbeState != .idle ||
+            self.remoteAuthIssue != nil ||
+            Self.shouldShowRemoteTokenField(
+                showAdvancedConnection: self.showAdvancedConnection,
+                remoteToken: self.state.remoteToken,
+                remoteTokenUnsupported: self.state.remoteTokenUnsupported,
+                authIssue: self.remoteAuthIssue)
+    }
+
+    private var shouldShowRemoteTokenField: Bool {
+        guard self.shouldShowRemoteConnectionSection else { return false }
+        return Self.shouldShowRemoteTokenField(
+            showAdvancedConnection: self.showAdvancedConnection,
+            remoteToken: self.state.remoteToken,
+            remoteTokenUnsupported: self.state.remoteTokenUnsupported,
+            authIssue: self.remoteAuthIssue)
+    }
+
+    private var remoteProbePreflightMessage: String? {
+        switch self.state.remoteTransport {
+        case .direct:
+            let trimmedUrl = self.state.remoteUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+            if trimmedUrl.isEmpty {
+                return "Select a nearby gateway or open Advanced to enter a gateway URL."
+            }
+            if GatewayRemoteConfig.normalizeGatewayUrl(trimmedUrl) == nil {
+                return "Gateway URL must use wss:// for remote hosts (ws:// only for localhost)."
+            }
+            return nil
+        case .ssh:
+            let trimmedTarget = self.state.remoteTarget.trimmingCharacters(in: .whitespacesAndNewlines)
+            if trimmedTarget.isEmpty {
+                return "Select a nearby gateway or open Advanced to enter an SSH target."
+            }
+            return CommandResolver.sshTargetValidationMessage(trimmedTarget)
+        }
+    }
+
+    private var canProbeRemoteConnection: Bool {
+        self.remoteProbePreflightMessage == nil && self.remoteProbeState != .checking
+    }
+
+    @ViewBuilder
+    private func remoteConnectionSection() -> some View {
+        VStack(alignment: .leading, spacing: 10) {
+            HStack(alignment: .top, spacing: 12) {
+                VStack(alignment: .leading, spacing: 2) {
+                    Text("Remote connection")
+                        .font(.callout.weight(.semibold))
+                    Text("Checks the real remote websocket and auth handshake.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer(minLength: 0)
+                Button {
+                    Task { await self.probeRemoteConnection() }
+                } label: {
+                    if self.remoteProbeState == .checking {
+                        ProgressView()
+                            .controlSize(.small)
+                            .frame(minWidth: 120)
+                    } else {
+                        Text("Check connection")
+                            .frame(minWidth: 120)
+                    }
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(!self.canProbeRemoteConnection)
+            }
+
+            if self.shouldShowRemoteTokenField {
+                self.remoteTokenField()
+            }
+
+            if let message = self.remoteProbePreflightMessage, self.remoteProbeState != .checking {
+                Text(message)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+
+            self.remoteProbeStatusView()
+
+            if let issue = self.remoteAuthIssue {
+                self.remoteAuthPromptView(issue: issue)
+            }
+        }
+    }
+
+    private func remoteTokenField() -> some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(alignment: .center, spacing: 12) {
+                Text("Gateway token")
+                    .font(.callout.weight(.semibold))
+                    .frame(width: 110, alignment: .leading)
+                SecureField("remote gateway auth token (gateway.remote.token)", text: self.$state.remoteToken)
+                    .textFieldStyle(.roundedBorder)
+                    .frame(maxWidth: 320)
+            }
+            Text("Used when the remote gateway requires token auth.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            if self.state.remoteTokenUnsupported {
+                Text(
+                    "The current gateway.remote.token value is not plain text. OpenClaw for macOS cannot use it directly; enter a plaintext token here to replace it.")
+                    .font(.caption)
+                    .foregroundStyle(.orange)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func remoteProbeStatusView() -> some View {
+        switch self.remoteProbeState {
+        case .idle:
+            EmptyView()
+        case .checking:
+            Text("Checking remote gateway…")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        case let .ok(success):
+            VStack(alignment: .leading, spacing: 2) {
+                Label(success.title, systemImage: "checkmark.circle.fill")
+                    .font(.caption)
+                    .foregroundStyle(.green)
+                if let detail = success.detail {
+                    Text(detail)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+            }
+        case let .failed(message):
+            if self.remoteAuthIssue == nil {
+                Text(message)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        }
+    }
+
+    private func remoteAuthPromptView(issue: RemoteGatewayAuthIssue) -> some View {
+        let promptStyle = Self.remoteAuthPromptStyle(for: issue)
+        return HStack(alignment: .top, spacing: 10) {
+            Image(systemName: promptStyle.systemImage)
+                .font(.caption.weight(.semibold))
+                .foregroundStyle(promptStyle.tint)
+                .frame(width: 16, alignment: .center)
+                .padding(.top, 1)
+            VStack(alignment: .leading, spacing: 4) {
+                Text(issue.title)
+                    .font(.caption.weight(.semibold))
+                Text(.init(issue.body))
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+                if let footnote = issue.footnote {
+                    Text(.init(footnote))
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+            }
+        }
+    }
+
+    @MainActor
+    private func probeRemoteConnection() async {
+        let originalMode = self.state.connectionMode
+        let shouldRestoreMode = originalMode != .remote
+        if shouldRestoreMode {
+            // Reuse the shared remote endpoint stack for probing without committing the user's mode choice.
+            self.state.connectionMode = .remote
+        }
+        self.remoteProbeState = .checking
+        self.remoteAuthIssue = nil
+        defer {
+            if shouldRestoreMode {
+                self.suppressRemoteProbeReset = true
+                self.state.connectionMode = originalMode
+                self.suppressRemoteProbeReset = false
+            }
+        }
+
+        switch await RemoteGatewayProbe.run() {
+        case let .ready(success):
+            self.remoteProbeState = .ok(success)
+        case let .authIssue(issue):
+            self.remoteAuthIssue = issue
+            self.remoteProbeState = .failed(issue.statusMessage)
+        case let .failed(message):
+            self.remoteProbeState = .failed(message)
+        }
+    }
+
+    private func resetRemoteProbeFeedback() {
+        self.remoteProbeState = .idle
+        self.remoteAuthIssue = nil
+    }
+
+    static func remoteAuthPromptStyle(
+        for issue: RemoteGatewayAuthIssue)
+        -> (systemImage: String, tint: Color)
+    {
+        switch issue {
+        case .tokenRequired:
+            return ("key.fill", .orange)
+        case .tokenMismatch:
+            return ("exclamationmark.triangle.fill", .orange)
+        case .gatewayTokenNotConfigured:
+            return ("wrench.and.screwdriver.fill", .orange)
+        case .passwordRequired:
+            return ("lock.slash.fill", .orange)
+        case .pairingRequired:
+            return ("link.badge.plus", .orange)
+        }
+    }
+
+    static func shouldShowRemoteTokenField(
+        showAdvancedConnection: Bool,
+        remoteToken: String,
+        remoteTokenUnsupported: Bool,
+        authIssue: RemoteGatewayAuthIssue?) -> Bool
+    {
+        showAdvancedConnection ||
+            remoteTokenUnsupported ||
+            !remoteToken.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ||
+            authIssue?.showsTokenField == true
+    }
+
+    static func shouldResetRemoteProbeFeedback(
+        for connectionMode: AppState.ConnectionMode,
+        suppressReset: Bool) -> Bool
+    {
+        !suppressReset && connectionMode != .remote
+    }
+
     func gatewaySubtitle(for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String? {
         if self.state.remoteTransport == .direct {
             return GatewayDiscoveryHelpers.directUrl(for: gateway) ?? "Gateway pairing only"

apps/macos/Sources/OpenClaw/RemoteGatewayProbe.swift

@@ -0,0 +1,222 @@
+import Foundation
+import OpenClawIPC
+import OpenClawKit
+
+enum RemoteGatewayAuthIssue: Equatable {
+    case tokenRequired
+    case tokenMismatch
+    case gatewayTokenNotConfigured
+    case passwordRequired
+    case pairingRequired
+
+    init?(error: Error) {
+        guard let authError = error as? GatewayConnectAuthError else {
+            return nil
+        }
+        switch authError.detail {
+        case .authTokenMissing:
+            self = .tokenRequired
+        case .authTokenMismatch:
+            self = .tokenMismatch
+        case .authTokenNotConfigured:
+            self = .gatewayTokenNotConfigured
+        case .authPasswordMissing, .authPasswordMismatch, .authPasswordNotConfigured:
+            self = .passwordRequired
+        case .pairingRequired:
+            self = .pairingRequired
+        default:
+            return nil
+        }
+    }
+
+    var showsTokenField: Bool {
+        switch self {
+        case .tokenRequired, .tokenMismatch:
+            true
+        case .gatewayTokenNotConfigured, .passwordRequired, .pairingRequired:
+            false
+        }
+    }
+
+    var title: String {
+        switch self {
+        case .tokenRequired:
+            "This gateway requires an auth token"
+        case .tokenMismatch:
+            "That token did not match the gateway"
+        case .gatewayTokenNotConfigured:
+            "This gateway host needs token setup"
+        case .passwordRequired:
+            "This gateway is using unsupported auth"
+        case .pairingRequired:
+            "This device needs pairing approval"
+        }
+    }
+
+    var body: String {
+        switch self {
+        case .tokenRequired:
+            "Paste the token configured on the gateway host. On the gateway host, run `openclaw config get gateway.auth.token`. If the gateway uses an environment variable instead, use `OPENCLAW_GATEWAY_TOKEN`."
+        case .tokenMismatch:
+            "Check `gateway.auth.token` or `OPENCLAW_GATEWAY_TOKEN` on the gateway host and try again."
+        case .gatewayTokenNotConfigured:
+            "This gateway is set to token auth, but no `gateway.auth.token` is configured on the gateway host. If the gateway uses an environment variable instead, set `OPENCLAW_GATEWAY_TOKEN` before starting the gateway."
+        case .passwordRequired:
+            "This onboarding flow does not support password auth yet. Reconfigure the gateway to use token auth, then retry."
+        case .pairingRequired:
+            "Approve this device from an already-paired OpenClaw client. In your OpenClaw chat, run `/pair approve`, then click **Check connection** again."
+        }
+    }
+
+    var footnote: String? {
+        switch self {
+        case .tokenRequired, .gatewayTokenNotConfigured:
+            "No token yet? Generate one on the gateway host with `openclaw doctor --generate-gateway-token`, then set it as `gateway.auth.token`."
+        case .pairingRequired:
+            "If you do not have another paired OpenClaw client yet, approve the pending request on the gateway host with `openclaw devices approve`."
+        case .tokenMismatch, .passwordRequired:
+            nil
+        }
+    }
+
+    var statusMessage: String {
+        switch self {
+        case .tokenRequired:
+            "This gateway requires an auth token from the gateway host."
+        case .tokenMismatch:
+            "Gateway token mismatch. Check gateway.auth.token or OPENCLAW_GATEWAY_TOKEN on the gateway host."
+        case .gatewayTokenNotConfigured:
+            "This gateway has token auth enabled, but no gateway.auth.token is configured on the host."
+        case .passwordRequired:
+            "This gateway uses password auth. Remote onboarding on macOS cannot collect gateway passwords yet."
+        case .pairingRequired:
+            "Pairing required. In an already-paired OpenClaw client, run /pair approve, then check the connection again."
+        }
+    }
+}
+
+enum RemoteGatewayProbeResult: Equatable {
+    case ready(RemoteGatewayProbeSuccess)
+    case authIssue(RemoteGatewayAuthIssue)
+    case failed(String)
+}
+
+struct RemoteGatewayProbeSuccess: Equatable {
+    let authSource: GatewayAuthSource?
+
+    var title: String {
+        switch self.authSource {
+        case .some(.deviceToken):
+            "Connected via paired device"
+        case .some(.sharedToken):
+            "Connected with gateway token"
+        case .some(.password):
+            "Connected with password"
+        case .some(GatewayAuthSource.none), nil:
+            "Remote gateway ready"
+        }
+    }
+
+    var detail: String? {
+        switch self.authSource {
+        case .some(.deviceToken):
+            "This Mac used a stored device token. New or unpaired devices may still need the gateway token."
+        case .some(.sharedToken), .some(.password), .some(GatewayAuthSource.none), nil:
+            nil
+        }
+    }
+}
+
+enum RemoteGatewayProbe {
+    @MainActor
+    static func run() async -> RemoteGatewayProbeResult {
+        AppStateStore.shared.syncGatewayConfigNow()
+        let settings = CommandResolver.connectionSettings()
+        let transport = AppStateStore.shared.remoteTransport
+
+        if transport == .direct {
+            let trimmedUrl = AppStateStore.shared.remoteUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmedUrl.isEmpty else {
+                return .failed("Set a gateway URL first")
+            }
+            guard self.isValidWsUrl(trimmedUrl) else {
+                return .failed("Gateway URL must use wss:// for remote hosts (ws:// only for localhost)")
+            }
+        } else {
+            let trimmedTarget = settings.target.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmedTarget.isEmpty else {
+                return .failed("Set an SSH target first")
+            }
+            if let validationMessage = CommandResolver.sshTargetValidationMessage(trimmedTarget) {
+                return .failed(validationMessage)
+            }
+            guard let sshCommand = self.sshCheckCommand(target: settings.target, identity: settings.identity) else {
+                return .failed("SSH target is invalid")
+            }
+
+            let sshResult = await ShellExecutor.run(
+                command: sshCommand,
+                cwd: nil,
+                env: nil,
+                timeout: 8)
+            guard sshResult.ok else {
+                return .failed(self.formatSSHFailure(sshResult, target: settings.target))
+            }
+        }
+
+        do {
+            _ = try await GatewayConnection.shared.healthSnapshot(timeoutMs: 10_000)
+            let authSource = await GatewayConnection.shared.authSource()
+            return .ready(RemoteGatewayProbeSuccess(authSource: authSource))
+        } catch {
+            if let authIssue = RemoteGatewayAuthIssue(error: error) {
+                return .authIssue(authIssue)
+            }
+            return .failed(error.localizedDescription)
+        }
+    }
+
+    private static func isValidWsUrl(_ raw: String) -> Bool {
+        GatewayRemoteConfig.normalizeGatewayUrl(raw) != nil
+    }
+
+    private static func sshCheckCommand(target: String, identity: String) -> [String]? {
+        guard let parsed = CommandResolver.parseSSHTarget(target) else { return nil }
+        let options = [
+            "-o", "BatchMode=yes",
+            "-o", "ConnectTimeout=5",
+            "-o", "StrictHostKeyChecking=accept-new",
+            "-o", "UpdateHostKeys=yes",
+        ]
+        let args = CommandResolver.sshArguments(
+            target: parsed,
+            identity: identity,
+            options: options,
+            remoteCommand: ["echo", "ok"])
+        return ["/usr/bin/ssh"] + args
+    }
+
+    private static func formatSSHFailure(_ response: Response, target: String) -> String {
+        let payload = response.payload.flatMap { String(data: $0, encoding: .utf8) }
+        let trimmed = payload?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .split(whereSeparator: \.isNewline)
+            .joined(separator: " ")
+        if let trimmed,
+           trimmed.localizedCaseInsensitiveContains("host key verification failed")
+        {
+            let host = CommandResolver.parseSSHTarget(target)?.host ?? target
+            return "SSH check failed: Host key verification failed. Remove the old key with ssh-keygen -R \(host) and try again."
+        }
+        if let trimmed, !trimmed.isEmpty {
+            if let message = response.message, message.hasPrefix("exit ") {
+                return "SSH check failed: \(trimmed) (\(message))"
+            }
+            return "SSH check failed: \(trimmed)"
+        }
+        if let message = response.message {
+            return "SSH check failed (\(message))"
+        }
+        return "SSH check failed"
+    }
+}

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

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.3.8</string>
+    <string>2026.3.11</string>
     <key>CFBundleVersion</key>
-    <string>202603080</string>
+    <string>202603110</string>
     <key>CFBundleIconFile</key>
     <string>OpenClaw</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/OpenClaw/TalkDefaults.swift

@@ -0,0 +1,3 @@
+enum TalkDefaults {
+    static let silenceTimeoutMs = 700
+}

apps/macos/Sources/OpenClaw/TalkModeGatewayConfig.swift

@@ -0,0 +1,104 @@
+import Foundation
+import OpenClawKit
+
+struct TalkModeGatewayConfigState {
+    let activeProvider: String
+    let normalizedPayload: Bool
+    let missingResolvedPayload: Bool
+    let voiceId: String?
+    let voiceAliases: [String: String]
+    let modelId: String?
+    let outputFormat: String?
+    let interruptOnSpeech: Bool
+    let silenceTimeoutMs: Int
+    let apiKey: String?
+    let seamColorHex: String?
+}
+
+enum TalkModeGatewayConfigParser {
+    static func parse(
+        snapshot: ConfigSnapshot,
+        defaultProvider: String,
+        defaultModelIdFallback: String,
+        defaultSilenceTimeoutMs: Int,
+        envVoice: String?,
+        sagVoice: String?,
+        envApiKey: String?
+    ) -> TalkModeGatewayConfigState {
+        let talk = snapshot.config?["talk"]?.dictionaryValue
+        let selection = TalkConfigParsing.selectProviderConfig(talk, defaultProvider: defaultProvider)
+        let activeProvider = selection?.provider ?? defaultProvider
+        let activeConfig = selection?.config
+        let silenceTimeoutMs = TalkConfigParsing.resolvedSilenceTimeoutMs(
+            talk,
+            fallback: defaultSilenceTimeoutMs)
+        let ui = snapshot.config?["ui"]?.dictionaryValue
+        let rawSeam = ui?["seamColor"]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let voice = activeConfig?["voiceId"]?.stringValue
+        let rawAliases = activeConfig?["voiceAliases"]?.dictionaryValue
+        let resolvedAliases: [String: String] =
+            rawAliases?.reduce(into: [:]) { acc, entry in
+                let key = entry.key.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+                let value = entry.value.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+                guard !key.isEmpty, !value.isEmpty else { return }
+                acc[key] = value
+            } ?? [:]
+        let model = activeConfig?["modelId"]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let resolvedModel = (model?.isEmpty == false) ? model! : defaultModelIdFallback
+        let outputFormat = activeConfig?["outputFormat"]?.stringValue
+        let interrupt = talk?["interruptOnSpeech"]?.boolValue
+        let apiKey = activeConfig?["apiKey"]?.stringValue
+        let resolvedVoice: String? = if activeProvider == defaultProvider {
+            (voice?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false ? voice : nil) ??
+                (envVoice?.isEmpty == false ? envVoice : nil) ??
+                (sagVoice?.isEmpty == false ? sagVoice : nil)
+        } else {
+            (voice?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false ? voice : nil)
+        }
+        let resolvedApiKey: String? = if activeProvider == defaultProvider {
+            (envApiKey?.isEmpty == false ? envApiKey : nil) ??
+                (apiKey?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false ? apiKey : nil)
+        } else {
+            nil
+        }
+
+        return TalkModeGatewayConfigState(
+            activeProvider: activeProvider,
+            normalizedPayload: selection?.normalizedPayload == true,
+            missingResolvedPayload: talk != nil && selection == nil,
+            voiceId: resolvedVoice,
+            voiceAliases: resolvedAliases,
+            modelId: resolvedModel,
+            outputFormat: outputFormat,
+            interruptOnSpeech: interrupt ?? true,
+            silenceTimeoutMs: silenceTimeoutMs,
+            apiKey: resolvedApiKey,
+            seamColorHex: rawSeam.isEmpty ? nil : rawSeam)
+    }
+
+    static func fallback(
+        defaultModelIdFallback: String,
+        defaultSilenceTimeoutMs: Int,
+        envVoice: String?,
+        sagVoice: String?,
+        envApiKey: String?
+    ) -> TalkModeGatewayConfigState {
+        let resolvedVoice =
+            (envVoice?.isEmpty == false ? envVoice : nil) ??
+            (sagVoice?.isEmpty == false ? sagVoice : nil)
+        let resolvedApiKey = envApiKey?.isEmpty == false ? envApiKey : nil
+
+        return TalkModeGatewayConfigState(
+            activeProvider: "elevenlabs",
+            normalizedPayload: false,
+            missingResolvedPayload: false,
+            voiceId: resolvedVoice,
+            voiceAliases: [:],
+            modelId: defaultModelIdFallback,
+            outputFormat: nil,
+            interruptOnSpeech: true,
+            silenceTimeoutMs: defaultSilenceTimeoutMs,
+            apiKey: resolvedApiKey,
+            seamColorHex: nil)
+    }
+}

apps/macos/Sources/OpenClaw/TalkModeRuntime.swift

@@ -12,6 +12,7 @@ actor TalkModeRuntime {
     private let ttsLogger = Logger(subsystem: "ai.openclaw", category: "talk.tts")
     private static let defaultModelIdFallback = "eleven_v3"
     private static let defaultTalkProvider = "elevenlabs"
+    private static let defaultSilenceTimeoutMs = TalkDefaults.silenceTimeoutMs
 
     private final class RMSMeter: @unchecked Sendable {
         private let lock = NSLock()
@@ -66,10 +67,15 @@ actor TalkModeRuntime {
     private var fallbackVoiceId: String?
     private var lastPlaybackWasPCM: Bool = false
 
-    private let silenceWindow: TimeInterval = 0.7
+    private var silenceWindow: TimeInterval = .init(TalkModeRuntime.defaultSilenceTimeoutMs) / 1000
     private let minSpeechRMS: Double = 1e-3
     private let speechBoostFactor: Double = 6.0
 
+    static func configureRecognitionRequest(_ request: SFSpeechAudioBufferRecognitionRequest) {
+        request.shouldReportPartialResults = true
+        request.taskHint = .dictation
+    }
+
     // MARK: - Lifecycle
 
     func setEnabled(_ enabled: Bool) async {
@@ -176,9 +182,9 @@ actor TalkModeRuntime {
             return
         }
 
-        self.recognitionRequest = SFSpeechAudioBufferRecognitionRequest()
-        self.recognitionRequest?.shouldReportPartialResults = true
-        guard let request = self.recognitionRequest else { return }
+        let request = SFSpeechAudioBufferRecognitionRequest()
+        Self.configureRecognitionRequest(request)
+        self.recognitionRequest = request
 
         if self.audioEngine == nil {
             self.audioEngine = AVAudioEngine()
@@ -778,6 +784,7 @@ extension TalkModeRuntime {
         }
         self.defaultOutputFormat = cfg.outputFormat
         self.interruptOnSpeech = cfg.interruptOnSpeech
+        self.silenceWindow = TimeInterval(cfg.silenceTimeoutMs) / 1000
         self.apiKey = cfg.apiKey
         let hasApiKey = (cfg.apiKey?.isEmpty == false)
         let voiceLabel = (cfg.voiceId?.isEmpty == false) ? cfg.voiceId! : "none"
@@ -787,95 +794,21 @@ extension TalkModeRuntime {
                 "talk config voiceId=\(voiceLabel, privacy: .public) " +
                     "modelId=\(modelLabel, privacy: .public) " +
                     "apiKey=\(hasApiKey, privacy: .public) " +
-                    "interrupt=\(cfg.interruptOnSpeech, privacy: .public)")
-    }
-
-    private struct TalkRuntimeConfig {
-        let voiceId: String?
-        let voiceAliases: [String: String]
-        let modelId: String?
-        let outputFormat: String?
-        let interruptOnSpeech: Bool
-        let apiKey: String?
-    }
-
-    struct TalkProviderConfigSelection {
-        let provider: String
-        let config: [String: AnyCodable]
-        let normalizedPayload: Bool
-    }
-
-    private static func normalizedTalkProviderID(_ raw: String?) -> String? {
-        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() ?? ""
-        return trimmed.isEmpty ? nil : trimmed
-    }
-
-    private static func normalizedTalkProviderConfig(_ value: AnyCodable) -> [String: AnyCodable]? {
-        if let typed = value.value as? [String: AnyCodable] {
-            return typed
-        }
-        if let foundation = value.value as? [String: Any] {
-            return foundation.mapValues(AnyCodable.init)
-        }
-        if let nsDict = value.value as? NSDictionary {
-            var converted: [String: AnyCodable] = [:]
-            for case let (key as String, raw) in nsDict {
-                converted[key] = AnyCodable(raw)
-            }
-            return converted
-        }
-        return nil
-    }
-
-    private static func normalizedTalkProviders(_ raw: AnyCodable?) -> [String: [String: AnyCodable]] {
-        guard let raw else { return [:] }
-        var providerMap: [String: AnyCodable] = [:]
-        if let typed = raw.value as? [String: AnyCodable] {
-            providerMap = typed
-        } else if let foundation = raw.value as? [String: Any] {
-            providerMap = foundation.mapValues(AnyCodable.init)
-        } else if let nsDict = raw.value as? NSDictionary {
-            for case let (key as String, value) in nsDict {
-                providerMap[key] = AnyCodable(value)
-            }
-        } else {
-            return [:]
-        }
-
-        return providerMap.reduce(into: [String: [String: AnyCodable]]()) { acc, entry in
-            guard
-                let providerID = Self.normalizedTalkProviderID(entry.key),
-                let providerConfig = Self.normalizedTalkProviderConfig(entry.value)
-            else { return }
-            acc[providerID] = providerConfig
-        }
+                    "interrupt=\(cfg.interruptOnSpeech, privacy: .public) " +
+                    "silenceTimeoutMs=\(cfg.silenceTimeoutMs, privacy: .public)")
     }
 
     static func selectTalkProviderConfig(
         _ talk: [String: AnyCodable]?) -> TalkProviderConfigSelection?
     {
-        guard let talk else { return nil }
-        let rawProvider = talk["provider"]?.stringValue
-        let rawProviders = talk["providers"]
-        let hasNormalizedPayload = rawProvider != nil || rawProviders != nil
-        if hasNormalizedPayload {
-            let normalizedProviders = Self.normalizedTalkProviders(rawProviders)
-            let providerID =
-                Self.normalizedTalkProviderID(rawProvider) ??
-                normalizedProviders.keys.min() ??
-                Self.defaultTalkProvider
-            return TalkProviderConfigSelection(
-                provider: providerID,
-                config: normalizedProviders[providerID] ?? [:],
-                normalizedPayload: true)
-        }
-        return TalkProviderConfigSelection(
-            provider: Self.defaultTalkProvider,
-            config: talk,
-            normalizedPayload: false)
+        TalkConfigParsing.selectProviderConfig(talk, defaultProvider: self.defaultTalkProvider)
     }
 
-    private func fetchTalkConfig() async -> TalkRuntimeConfig {
+    static func resolvedSilenceTimeoutMs(_ talk: [String: AnyCodable]?) -> Int {
+        TalkConfigParsing.resolvedSilenceTimeoutMs(talk, fallback: self.defaultSilenceTimeoutMs)
+    }
+
+    private func fetchTalkConfig() async -> TalkModeGatewayConfigState {
         let env = ProcessInfo.processInfo.environment
         let envVoice = env["ELEVENLABS_VOICE_ID"]?.trimmingCharacters(in: .whitespacesAndNewlines)
         let sagVoice = env["SAG_VOICE_ID"]?.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -886,67 +819,34 @@ extension TalkModeRuntime {
                 method: .talkConfig,
                 params: ["includeSecrets": AnyCodable(true)],
                 timeoutMs: 8000)
-            let talk = snap.config?["talk"]?.dictionaryValue
-            let selection = Self.selectTalkProviderConfig(talk)
-            let activeProvider = selection?.provider ?? Self.defaultTalkProvider
-            let activeConfig = selection?.config
-            let ui = snap.config?["ui"]?.dictionaryValue
-            let rawSeam = ui?["seamColor"]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            let parsed = TalkModeGatewayConfigParser.parse(
+                snapshot: snap,
+                defaultProvider: Self.defaultTalkProvider,
+                defaultModelIdFallback: Self.defaultModelIdFallback,
+                defaultSilenceTimeoutMs: Self.defaultSilenceTimeoutMs,
+                envVoice: envVoice,
+                sagVoice: sagVoice,
+                envApiKey: envApiKey)
+            if parsed.missingResolvedPayload {
+                self.ttsLogger.info("talk config ignored: normalized payload missing talk.resolved")
+            }
             await MainActor.run {
-                AppStateStore.shared.seamColorHex = rawSeam.isEmpty ? nil : rawSeam
+                AppStateStore.shared.seamColorHex = parsed.seamColorHex
             }
-            let voice = activeConfig?["voiceId"]?.stringValue
-            let rawAliases = activeConfig?["voiceAliases"]?.dictionaryValue
-            let resolvedAliases: [String: String] =
-                rawAliases?.reduce(into: [:]) { acc, entry in
-                    let key = entry.key.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-                    let value = entry.value.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-                    guard !key.isEmpty, !value.isEmpty else { return }
-                    acc[key] = value
-                } ?? [:]
-            let model = activeConfig?["modelId"]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines)
-            let resolvedModel = (model?.isEmpty == false) ? model! : Self.defaultModelIdFallback
-            let outputFormat = activeConfig?["outputFormat"]?.stringValue
-            let interrupt = talk?["interruptOnSpeech"]?.boolValue
-            let apiKey = activeConfig?["apiKey"]?.stringValue
-            let resolvedVoice: String? = if activeProvider == Self.defaultTalkProvider {
-                (voice?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false ? voice : nil) ??
-                    (envVoice?.isEmpty == false ? envVoice : nil) ??
-                    (sagVoice?.isEmpty == false ? sagVoice : nil)
-            } else {
-                (voice?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false ? voice : nil)
-            }
-            let resolvedApiKey: String? = if activeProvider == Self.defaultTalkProvider {
-                (envApiKey?.isEmpty == false ? envApiKey : nil) ??
-                    (apiKey?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false ? apiKey : nil)
-            } else {
-                nil
-            }
-            if activeProvider != Self.defaultTalkProvider {
+            if parsed.activeProvider != Self.defaultTalkProvider {
                 self.ttsLogger
-                    .info("talk provider \(activeProvider, privacy: .public) unsupported; using system voice")
-            } else if selection?.normalizedPayload == true {
-                self.ttsLogger.info("talk config provider elevenlabs")
+                    .info("talk provider \(parsed.activeProvider, privacy: .public) unsupported; using system voice")
+            } else if parsed.normalizedPayload {
+                self.ttsLogger.info("talk config provider from talk.resolved")
             }
-            return TalkRuntimeConfig(
-                voiceId: resolvedVoice,
-                voiceAliases: resolvedAliases,
-                modelId: resolvedModel,
-                outputFormat: outputFormat,
-                interruptOnSpeech: interrupt ?? true,
-                apiKey: resolvedApiKey)
+            return parsed
         } catch {
-            let resolvedVoice =
-                (envVoice?.isEmpty == false ? envVoice : nil) ??
-                (sagVoice?.isEmpty == false ? sagVoice : nil)
-            let resolvedApiKey = envApiKey?.isEmpty == false ? envApiKey : nil
-            return TalkRuntimeConfig(
-                voiceId: resolvedVoice,
-                voiceAliases: [:],
-                modelId: Self.defaultModelIdFallback,
-                outputFormat: nil,
-                interruptOnSpeech: true,
-                apiKey: resolvedApiKey)
+            return TalkModeGatewayConfigParser.fallback(
+                defaultModelIdFallback: Self.defaultModelIdFallback,
+                defaultSilenceTimeoutMs: Self.defaultSilenceTimeoutMs,
+                envVoice: envVoice,
+                sagVoice: sagVoice,
+                envApiKey: envApiKey)
         }
     }
 

apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift

@@ -8,6 +8,7 @@ import QuartzCore
 import SwiftUI
 
 private let webChatSwiftLogger = Logger(subsystem: "ai.openclaw", category: "WebChatSwiftUI")
+private let webChatThinkingLevelDefaultsKey = "openclaw.webchat.thinkingLevel"
 
 private enum WebChatSwiftUILayout {
     static let windowSize = NSSize(width: 500, height: 840)
@@ -21,6 +22,21 @@ struct MacGatewayChatTransport: OpenClawChatTransport {
         try await GatewayConnection.shared.chatHistory(sessionKey: sessionKey)
     }
 
+    func listModels() async throws -> [OpenClawChatModelChoice] {
+        do {
+            let data = try await GatewayConnection.shared.request(
+                method: "models.list",
+                params: [:],
+                timeoutMs: 15000)
+            let result = try JSONDecoder().decode(ModelsListResult.self, from: data)
+            return result.models.map(Self.mapModelChoice)
+        } catch {
+            webChatSwiftLogger.warning(
+                "models.list failed; hiding model picker: \(error.localizedDescription, privacy: .public)")
+            return []
+        }
+    }
+
     func abortRun(sessionKey: String, runId: String) async throws {
         _ = try await GatewayConnection.shared.request(
             method: "chat.abort",
@@ -46,6 +62,28 @@ struct MacGatewayChatTransport: OpenClawChatTransport {
         return try JSONDecoder().decode(OpenClawChatSessionsListResponse.self, from: data)
     }
 
+    func setSessionModel(sessionKey: String, model: String?) async throws {
+        var params: [String: AnyCodable] = [
+            "key": AnyCodable(sessionKey),
+        ]
+        params["model"] = model.map(AnyCodable.init) ?? AnyCodable(NSNull())
+        _ = try await GatewayConnection.shared.request(
+            method: "sessions.patch",
+            params: params,
+            timeoutMs: 15000)
+    }
+
+    func setSessionThinking(sessionKey: String, thinkingLevel: String) async throws {
+        let params: [String: AnyCodable] = [
+            "key": AnyCodable(sessionKey),
+            "thinkingLevel": AnyCodable(thinkingLevel),
+        ]
+        _ = try await GatewayConnection.shared.request(
+            method: "sessions.patch",
+            params: params,
+            timeoutMs: 15000)
+    }
+
     func sendMessage(
         sessionKey: String,
         message: String,
@@ -133,6 +171,14 @@ struct MacGatewayChatTransport: OpenClawChatTransport {
             return .seqGap
         }
     }
+
+    private static func mapModelChoice(_ model: OpenClawProtocol.ModelChoice) -> OpenClawChatModelChoice {
+        OpenClawChatModelChoice(
+            modelID: model.id,
+            name: model.name,
+            provider: model.provider,
+            contextWindow: model.contextwindow)
+    }
 }
 
 // MARK: - Window controller
@@ -155,7 +201,13 @@ final class WebChatSwiftUIWindowController {
     init(sessionKey: String, presentation: WebChatPresentation, transport: any OpenClawChatTransport) {
         self.sessionKey = sessionKey
         self.presentation = presentation
-        let vm = OpenClawChatViewModel(sessionKey: sessionKey, transport: transport)
+        let vm = OpenClawChatViewModel(
+            sessionKey: sessionKey,
+            transport: transport,
+            initialThinkingLevel: Self.persistedThinkingLevel(),
+            onThinkingLevelChanged: { level in
+                UserDefaults.standard.set(level, forKey: webChatThinkingLevelDefaultsKey)
+            })
         let accent = Self.color(fromHex: AppStateStore.shared.seamColorHex)
         self.hosting = NSHostingController(rootView: OpenClawChatView(
             viewModel: vm,
@@ -254,6 +306,16 @@ final class WebChatSwiftUIWindowController {
         OverlayPanelFactory.clearGlobalEventMonitor(&self.dismissMonitor)
     }
 
+    private static func persistedThinkingLevel() -> String? {
+        let stored = UserDefaults.standard.string(forKey: webChatThinkingLevelDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+        guard let stored, ["off", "minimal", "low", "medium", "high", "xhigh", "adaptive"].contains(stored) else {
+            return nil
+        }
+        return stored
+    }
+
     private static func makeWindow(
         for presentation: WebChatPresentation,
         contentViewController: NSViewController) -> NSWindow

apps/macos/Sources/OpenClawDiscovery/GatewayDiscoveryModel.swift

@@ -338,13 +338,12 @@ public final class GatewayDiscoveryModel {
             var attempt = 0
             let startedAt = Date()
             while !Task.isCancelled, Date().timeIntervalSince(startedAt) < 35.0 {
-                let hasResults = await MainActor.run {
-                    if self.filterLocalGateways {
-                        return !self.gateways.isEmpty
-                    }
-                    return self.gateways.contains(where: { !$0.isLocal })
+                let shouldContinue = await MainActor.run {
+                    Self.shouldContinueTailscaleServeDiscovery(
+                        currentGateways: self.gateways,
+                        tailscaleServeGateways: self.tailscaleServeFallbackGateways)
                 }
-                if hasResults { return }
+                if !shouldContinue { return }
 
                 let beacons = await TailscaleServeGatewayDiscovery.discover(timeoutSeconds: 2.4)
                 if !beacons.isEmpty {
@@ -363,6 +362,15 @@ public final class GatewayDiscoveryModel {
         }
     }
 
+    static func shouldContinueTailscaleServeDiscovery(
+        currentGateways _: [DiscoveredGateway],
+        tailscaleServeGateways: [DiscoveredGateway]) -> Bool
+    {
+        // Tailscale Serve is a parallel discovery source. DNS-SD results should not suppress the
+        // probe, otherwise Serve-only gateways disappear as soon as any other remote gateway is found.
+        tailscaleServeGateways.isEmpty
+    }
+
     private var hasUsableWideAreaResults: Bool {
         guard let domain = OpenClawBonjour.wideAreaGatewayServiceDomain else { return false }
         guard let gateways = self.gatewaysByDomain[domain], !gateways.isEmpty else { return false }

apps/macos/Sources/OpenClawDiscovery/TailscaleServeGatewayDiscovery.swift

@@ -203,6 +203,7 @@ enum TailscaleServeGatewayDiscovery {
         let process = Process()
         process.executableURL = URL(fileURLWithPath: path)
         process.arguments = args
+        process.environment = self.commandEnvironment()
         let outPipe = Pipe()
         process.standardOutput = outPipe
         process.standardError = FileHandle.nullDevice
@@ -227,6 +228,19 @@ enum TailscaleServeGatewayDiscovery {
         return output?.isEmpty == false ? output : nil
     }
 
+    static func commandEnvironment(
+        base: [String: String] = ProcessInfo.processInfo.environment) -> [String: String]
+    {
+        var env = base
+        let term = env["TERM"]?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if term.isEmpty {
+            // The macOS Tailscale app binary exits with CLIError error 3 when TERM is missing,
+            // which is common for GUI-launched app environments.
+            env["TERM"] = "dumb"
+        }
+        return env
+    }
+
     private static func parseStatus(_ raw: String) -> TailscaleStatus? {
         guard let data = raw.data(using: .utf8) else { return nil }
         return try? JSONDecoder().decode(TailscaleStatus.self, from: data)

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -836,6 +836,20 @@ public struct NodeRenameParams: Codable, Sendable {
 
 public struct NodeListParams: Codable, Sendable {}
 
+public struct NodePendingAckParams: Codable, Sendable {
+    public let ids: [String]
+
+    public init(
+        ids: [String])
+    {
+        self.ids = ids
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case ids
+    }
+}
+
 public struct NodeDescribeParams: Codable, Sendable {
     public let nodeid: String
 
@@ -936,6 +950,102 @@ public struct NodeEventParams: Codable, Sendable {
     }
 }
 
+public struct NodePendingDrainParams: Codable, Sendable {
+    public let maxitems: Int?
+
+    public init(
+        maxitems: Int?)
+    {
+        self.maxitems = maxitems
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case maxitems = "maxItems"
+    }
+}
+
+public struct NodePendingDrainResult: Codable, Sendable {
+    public let nodeid: String
+    public let revision: Int
+    public let items: [[String: AnyCodable]]
+    public let hasmore: Bool
+
+    public init(
+        nodeid: String,
+        revision: Int,
+        items: [[String: AnyCodable]],
+        hasmore: Bool)
+    {
+        self.nodeid = nodeid
+        self.revision = revision
+        self.items = items
+        self.hasmore = hasmore
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case nodeid = "nodeId"
+        case revision
+        case items
+        case hasmore = "hasMore"
+    }
+}
+
+public struct NodePendingEnqueueParams: Codable, Sendable {
+    public let nodeid: String
+    public let type: String
+    public let priority: String?
+    public let expiresinms: Int?
+    public let wake: Bool?
+
+    public init(
+        nodeid: String,
+        type: String,
+        priority: String?,
+        expiresinms: Int?,
+        wake: Bool?)
+    {
+        self.nodeid = nodeid
+        self.type = type
+        self.priority = priority
+        self.expiresinms = expiresinms
+        self.wake = wake
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case nodeid = "nodeId"
+        case type
+        case priority
+        case expiresinms = "expiresInMs"
+        case wake
+    }
+}
+
+public struct NodePendingEnqueueResult: Codable, Sendable {
+    public let nodeid: String
+    public let revision: Int
+    public let queued: [String: AnyCodable]
+    public let waketriggered: Bool
+
+    public init(
+        nodeid: String,
+        revision: Int,
+        queued: [String: AnyCodable],
+        waketriggered: Bool)
+    {
+        self.nodeid = nodeid
+        self.revision = revision
+        self.queued = queued
+        self.waketriggered = waketriggered
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case nodeid = "nodeId"
+        case revision
+        case queued
+        case waketriggered = "wakeTriggered"
+    }
+}
+
 public struct NodeInvokeRequestEvent: Codable, Sendable {
     public let id: String
     public let nodeid: String
@@ -1227,6 +1337,8 @@ public struct SessionsPatchParams: Codable, Sendable {
     public let model: AnyCodable?
     public let spawnedby: AnyCodable?
     public let spawndepth: AnyCodable?
+    public let subagentrole: AnyCodable?
+    public let subagentcontrolscope: AnyCodable?
     public let sendpolicy: AnyCodable?
     public let groupactivation: AnyCodable?
 
@@ -1245,6 +1357,8 @@ public struct SessionsPatchParams: Codable, Sendable {
         model: AnyCodable?,
         spawnedby: AnyCodable?,
         spawndepth: AnyCodable?,
+        subagentrole: AnyCodable?,
+        subagentcontrolscope: AnyCodable?,
         sendpolicy: AnyCodable?,
         groupactivation: AnyCodable?)
     {
@@ -1262,6 +1376,8 @@ public struct SessionsPatchParams: Codable, Sendable {
         self.model = model
         self.spawnedby = spawnedby
         self.spawndepth = spawndepth
+        self.subagentrole = subagentrole
+        self.subagentcontrolscope = subagentcontrolscope
         self.sendpolicy = sendpolicy
         self.groupactivation = groupactivation
     }
@@ -1281,6 +1397,8 @@ public struct SessionsPatchParams: Codable, Sendable {
         case model
         case spawnedby = "spawnedBy"
         case spawndepth = "spawnDepth"
+        case subagentrole = "subagentRole"
+        case subagentcontrolscope = "subagentControlScope"
         case sendpolicy = "sendPolicy"
         case groupactivation = "groupActivation"
     }
@@ -2936,7 +3054,7 @@ public struct ExecApprovalsSnapshot: Codable, Sendable {
 
 public struct ExecApprovalRequestParams: Codable, Sendable {
     public let id: String?
-    public let command: String
+    public let command: String?
     public let commandargv: [String]?
     public let systemrunplan: [String: AnyCodable]?
     public let env: [String: AnyCodable]?
@@ -2957,7 +3075,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
 
     public init(
         id: String?,
-        command: String,
+        command: String?,
         commandargv: [String]?,
         systemrunplan: [String: AnyCodable]?,
         env: [String: AnyCodable]?,
@@ -3243,6 +3361,8 @@ public struct ChatSendParams: Codable, Sendable {
     public let deliver: Bool?
     public let attachments: [AnyCodable]?
     public let timeoutms: Int?
+    public let systeminputprovenance: [String: AnyCodable]?
+    public let systemprovenancereceipt: String?
     public let idempotencykey: String
 
     public init(
@@ -3252,6 +3372,8 @@ public struct ChatSendParams: Codable, Sendable {
         deliver: Bool?,
         attachments: [AnyCodable]?,
         timeoutms: Int?,
+        systeminputprovenance: [String: AnyCodable]?,
+        systemprovenancereceipt: String?,
         idempotencykey: String)
     {
         self.sessionkey = sessionkey
@@ -3260,6 +3382,8 @@ public struct ChatSendParams: Codable, Sendable {
         self.deliver = deliver
         self.attachments = attachments
         self.timeoutms = timeoutms
+        self.systeminputprovenance = systeminputprovenance
+        self.systemprovenancereceipt = systemprovenancereceipt
         self.idempotencykey = idempotencykey
     }
 
@@ -3270,6 +3394,8 @@ public struct ChatSendParams: Codable, Sendable {
         case deliver
         case attachments
         case timeoutms = "timeoutMs"
+        case systeminputprovenance = "systemInputProvenance"
+        case systemprovenancereceipt = "systemProvenanceReceipt"
         case idempotencykey = "idempotencyKey"
     }
 }

apps/macos/Tests/OpenClawIPCTests/AppStateRemoteConfigTests.swift

@@ -0,0 +1,128 @@
+import Testing
+@testable import OpenClaw
+
+@Suite(.serialized)
+@MainActor
+struct AppStateRemoteConfigTests {
+    @Test
+    func updatedRemoteGatewayConfigSetsTrimmedToken() {
+        let remote = AppState._testUpdatedRemoteGatewayConfig(
+            current: [:],
+            transport: .ssh,
+            remoteUrl: "",
+            remoteHost: "gateway.example",
+            remoteTarget: "alice@gateway.example",
+            remoteIdentity: "/tmp/id_ed25519",
+            remoteToken: "  secret-token  ",
+            remoteTokenDirty: true)
+
+        #expect(remote["token"] as? String == "secret-token")
+    }
+
+    @Test
+    func updatedRemoteGatewayConfigClearsTokenWhenBlank() {
+        let remote = AppState._testUpdatedRemoteGatewayConfig(
+            current: ["token": "old-token"],
+            transport: .direct,
+            remoteUrl: "wss://gateway.example",
+            remoteHost: nil,
+            remoteTarget: "",
+            remoteIdentity: "",
+            remoteToken: "   ",
+            remoteTokenDirty: true)
+
+        #expect((remote["token"] as? String) == nil)
+    }
+
+    @Test
+    func syncedGatewayRootPreservesObjectTokenAcrossModeAndTransportChangesWhenUntouched() {
+        let initialRoot: [String: Any] = [
+            "gateway": [
+                "mode": "remote",
+                "remote": [
+                    "transport": "direct",
+                    "url": "wss://old-gateway.example",
+                    "token": [
+                        "$secretRef": "gateway-token", // pragma: allowlist secret
+                    ],
+                ],
+            ],
+        ]
+
+        let sshRoot = AppState._testSyncedGatewayRoot(
+            currentRoot: initialRoot,
+            connectionMode: .remote,
+            remoteTransport: .ssh,
+            remoteTarget: "alice@gateway.example",
+            remoteIdentity: "",
+            remoteUrl: "",
+            remoteToken: "",
+            remoteTokenDirty: false)
+        let sshRemote = (sshRoot["gateway"] as? [String: Any])?["remote"] as? [String: Any]
+        #expect((sshRemote?["token"] as? [String: String])?["$secretRef"] == "gateway-token") // pragma: allowlist secret
+
+        let localRoot = AppState._testSyncedGatewayRoot(
+            currentRoot: sshRoot,
+            connectionMode: .local,
+            remoteTransport: .ssh,
+            remoteTarget: "",
+            remoteIdentity: "",
+            remoteUrl: "",
+            remoteToken: "",
+            remoteTokenDirty: false)
+        let localGateway = localRoot["gateway"] as? [String: Any]
+        let localRemote = localGateway?["remote"] as? [String: Any]
+        #expect(localGateway?["mode"] as? String == "local")
+        #expect((localRemote?["token"] as? [String: String])?["$secretRef"] == "gateway-token") // pragma: allowlist secret
+    }
+
+    @Test
+    func updatedRemoteGatewayConfigReplacesObjectTokenWhenUserEntersPlaintext() {
+        let remote = AppState._testUpdatedRemoteGatewayConfig(
+            current: [
+                "token": [
+                    "$secretRef": "gateway-token", // pragma: allowlist secret
+                ],
+            ],
+            transport: .direct,
+            remoteUrl: "wss://gateway.example",
+            remoteHost: nil,
+            remoteTarget: "",
+            remoteIdentity: "",
+            remoteToken: "  fresh-token  ",
+            remoteTokenDirty: true)
+
+        #expect(remote["token"] as? String == "fresh-token")
+    }
+
+    @Test
+    func updatedRemoteGatewayConfigClearsObjectTokenOnlyAfterExplicitEdit() {
+        let current: [String: Any] = [
+            "token": [
+                "$secretRef": "gateway-token", // pragma: allowlist secret
+            ],
+        ]
+
+        let preserved = AppState._testUpdatedRemoteGatewayConfig(
+            current: current,
+            transport: .direct,
+            remoteUrl: "wss://gateway.example",
+            remoteHost: nil,
+            remoteTarget: "",
+            remoteIdentity: "",
+            remoteToken: "",
+            remoteTokenDirty: false)
+        #expect((preserved["token"] as? [String: String])?["$secretRef"] == "gateway-token") // pragma: allowlist secret
+
+        let cleared = AppState._testUpdatedRemoteGatewayConfig(
+            current: current,
+            transport: .direct,
+            remoteUrl: "wss://gateway.example",
+            remoteHost: nil,
+            remoteTarget: "",
+            remoteIdentity: "",
+            remoteToken: "   ",
+            remoteTokenDirty: true)
+        #expect((cleared["token"] as? String) == nil)
+    }
+}

apps/macos/Tests/OpenClawIPCTests/GatewayChannelConnectTests.swift

@@ -7,6 +7,11 @@ struct GatewayChannelConnectTests {
     private enum FakeResponse {
         case helloOk(delayMs: Int)
         case invalid(delayMs: Int)
+        case authFailed(
+            delayMs: Int,
+            detailCode: String,
+            canRetryWithDeviceToken: Bool,
+            recommendedNextStep: String?)
     }
 
     private func makeSession(response: FakeResponse) -> GatewayTestWebSocketSession {
@@ -27,6 +32,14 @@ struct GatewayChannelConnectTests {
                         case let .invalid(ms):
                             delayMs = ms
                             message = .string("not json")
+                        case let .authFailed(ms, detailCode, canRetryWithDeviceToken, recommendedNextStep):
+                            delayMs = ms
+                            let id = task.snapshotConnectRequestID() ?? "connect"
+                            message = .data(GatewayWebSocketTestSupport.connectAuthFailureData(
+                                id: id,
+                                detailCode: detailCode,
+                                canRetryWithDeviceToken: canRetryWithDeviceToken,
+                                recommendedNextStep: recommendedNextStep))
                         }
                         try await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
                         return message
@@ -71,4 +84,29 @@ struct GatewayChannelConnectTests {
         }())
         #expect(session.snapshotMakeCount() == 1)
     }
+
+    @Test func `connect surfaces structured auth failure`() async throws {
+        let session = self.makeSession(response: .authFailed(
+            delayMs: 0,
+            detailCode: GatewayConnectAuthDetailCode.authTokenMissing.rawValue,
+            canRetryWithDeviceToken: true,
+            recommendedNextStep: GatewayConnectRecoveryNextStep.updateAuthConfiguration.rawValue))
+        let channel = try GatewayChannelActor(
+            url: #require(URL(string: "ws://example.invalid")),
+            token: nil,
+            session: WebSocketSessionBox(session: session))
+
+        do {
+            try await channel.connect()
+            Issue.record("expected GatewayConnectAuthError")
+        } catch let error as GatewayConnectAuthError {
+            #expect(error.detail == .authTokenMissing)
+            #expect(error.detailCode == GatewayConnectAuthDetailCode.authTokenMissing.rawValue)
+            #expect(error.canRetryWithDeviceToken)
+            #expect(error.recommendedNextStep == .updateAuthConfiguration)
+            #expect(error.recommendedNextStepCode == GatewayConnectRecoveryNextStep.updateAuthConfiguration.rawValue)
+        } catch {
+            Issue.record("unexpected error: \(error)")
+        }
+    }
 }

apps/macos/Tests/OpenClawIPCTests/GatewayDiscoveryModelTests.swift

@@ -121,6 +121,56 @@ struct GatewayDiscoveryModelTests {
             port: 2201) == "peter@studio.local:2201")
     }
 
+    @Test func `tailscale serve discovery continues when DNS-SD already found a remote gateway`() {
+        let dnsSdGateway = GatewayDiscoveryModel.DiscoveredGateway(
+            displayName: "Nearby Gateway",
+            serviceHost: "nearby-gateway.local",
+            servicePort: 18789,
+            lanHost: "nearby-gateway.local",
+            tailnetDns: nil,
+            sshPort: 22,
+            gatewayPort: 18789,
+            cliPath: nil,
+            stableID: "bonjour|nearby-gateway",
+            debugID: "bonjour",
+            isLocal: false)
+
+        #expect(GatewayDiscoveryModel.shouldContinueTailscaleServeDiscovery(
+            currentGateways: [dnsSdGateway],
+            tailscaleServeGateways: []))
+    }
+
+    @Test func `tailscale serve discovery stops after serve result is found`() {
+        let dnsSdGateway = GatewayDiscoveryModel.DiscoveredGateway(
+            displayName: "Nearby Gateway",
+            serviceHost: "nearby-gateway.local",
+            servicePort: 18789,
+            lanHost: "nearby-gateway.local",
+            tailnetDns: nil,
+            sshPort: 22,
+            gatewayPort: 18789,
+            cliPath: nil,
+            stableID: "bonjour|nearby-gateway",
+            debugID: "bonjour",
+            isLocal: false)
+        let serveGateway = GatewayDiscoveryModel.DiscoveredGateway(
+            displayName: "Tailscale Gateway",
+            serviceHost: "gateway-host.tailnet-example.ts.net",
+            servicePort: 443,
+            lanHost: nil,
+            tailnetDns: "gateway-host.tailnet-example.ts.net",
+            sshPort: 22,
+            gatewayPort: 443,
+            cliPath: nil,
+            stableID: "tailscale-serve|gateway-host.tailnet-example.ts.net",
+            debugID: "serve",
+            isLocal: false)
+
+        #expect(!GatewayDiscoveryModel.shouldContinueTailscaleServeDiscovery(
+            currentGateways: [dnsSdGateway],
+            tailscaleServeGateways: [serveGateway]))
+    }
+
     @Test func `dedupe key prefers resolved endpoint across sources`() {
         let wideArea = GatewayDiscoveryModel.DiscoveredGateway(
             displayName: "Gateway",

apps/macos/Tests/OpenClawIPCTests/GatewayDiscoverySelectionSupportTests.swift

@@ -0,0 +1,90 @@
+import Foundation
+import OpenClawDiscovery
+import Testing
+@testable import OpenClaw
+
+@Suite(.serialized)
+@MainActor
+struct GatewayDiscoverySelectionSupportTests {
+    private func makeGateway(
+        serviceHost: String?,
+        servicePort: Int?,
+        tailnetDns: String? = nil,
+        sshPort: Int = 22,
+        stableID: String) -> GatewayDiscoveryModel.DiscoveredGateway
+    {
+        GatewayDiscoveryModel.DiscoveredGateway(
+            displayName: "Gateway",
+            serviceHost: serviceHost,
+            servicePort: servicePort,
+            lanHost: nil,
+            tailnetDns: tailnetDns,
+            sshPort: sshPort,
+            gatewayPort: servicePort,
+            cliPath: nil,
+            stableID: stableID,
+            debugID: UUID().uuidString,
+            isLocal: false)
+    }
+
+    @Test func `selecting tailscale serve gateway switches to direct transport`() async {
+        let tailnetHost = "gateway-host.tailnet-example.ts.net"
+        let configPath = TestIsolation.tempConfigPath()
+        await TestIsolation.withEnvValues(["OPENCLAW_CONFIG_PATH": configPath]) {
+            let state = AppState(preview: true)
+            state.remoteTransport = .ssh
+            state.remoteTarget = "user@old-host"
+
+            GatewayDiscoverySelectionSupport.applyRemoteSelection(
+                gateway: self.makeGateway(
+                    serviceHost: tailnetHost,
+                    servicePort: 443,
+                    tailnetDns: tailnetHost,
+                    stableID: "tailscale-serve|\(tailnetHost)"),
+                state: state)
+
+            #expect(state.remoteTransport == .direct)
+            #expect(state.remoteUrl == "wss://\(tailnetHost)")
+            #expect(CommandResolver.parseSSHTarget(state.remoteTarget)?.host == tailnetHost)
+        }
+    }
+
+    @Test func `selecting merged tailnet gateway still switches to direct transport`() async {
+        let tailnetHost = "gateway-host.tailnet-example.ts.net"
+        let configPath = TestIsolation.tempConfigPath()
+        await TestIsolation.withEnvValues(["OPENCLAW_CONFIG_PATH": configPath]) {
+            let state = AppState(preview: true)
+            state.remoteTransport = .ssh
+
+            GatewayDiscoverySelectionSupport.applyRemoteSelection(
+                gateway: self.makeGateway(
+                    serviceHost: tailnetHost,
+                    servicePort: 443,
+                    tailnetDns: tailnetHost,
+                    stableID: "wide-area|openclaw.internal.|gateway-host"),
+                state: state)
+
+            #expect(state.remoteTransport == .direct)
+            #expect(state.remoteUrl == "wss://\(tailnetHost)")
+        }
+    }
+
+    @Test func `selecting nearby lan gateway keeps ssh transport`() async {
+        let configPath = TestIsolation.tempConfigPath()
+        await TestIsolation.withEnvValues(["OPENCLAW_CONFIG_PATH": configPath]) {
+            let state = AppState(preview: true)
+            state.remoteTransport = .ssh
+            state.remoteTarget = "user@old-host"
+
+            GatewayDiscoverySelectionSupport.applyRemoteSelection(
+                gateway: self.makeGateway(
+                    serviceHost: "nearby-gateway.local",
+                    servicePort: 18789,
+                    stableID: "bonjour|nearby-gateway"),
+                state: state)
+
+            #expect(state.remoteTransport == .ssh)
+            #expect(CommandResolver.parseSSHTarget(state.remoteTarget)?.host == "nearby-gateway.local")
+        }
+    }
+}

apps/macos/Tests/OpenClawIPCTests/GatewayEndpointStoreTests.swift

@@ -61,7 +61,22 @@ struct GatewayEndpointStoreTests {
         #expect(token == nil)
     }
 
-    @Test func `resolve gateway password falls back to launchd`() {
+    @Test func resolveGatewayTokenUsesRemoteConfigToken() {
+        let token = GatewayEndpointStore._testResolveGatewayToken(
+            isRemote: true,
+            root: [
+                "gateway": [
+                    "remote": [
+                        "token": "  remote-token  ",
+                    ],
+                ],
+            ],
+            env: [:],
+            launchdSnapshot: nil)
+        #expect(token == "remote-token")
+    }
+
+    @Test func resolveGatewayPasswordFallsBackToLaunchd() {
         let snapshot = self.makeLaunchAgentSnapshot(
             env: ["OPENCLAW_GATEWAY_PASSWORD": "launchd-pass"],
             token: nil,

apps/macos/Tests/OpenClawIPCTests/GatewayWebSocketTestSupport.swift

@@ -52,6 +52,40 @@ enum GatewayWebSocketTestSupport {
         return Data(json.utf8)
     }
 
+    static func connectAuthFailureData(
+        id: String,
+        detailCode: String,
+        message: String = "gateway auth rejected",
+        canRetryWithDeviceToken: Bool = false,
+        recommendedNextStep: String? = nil) -> Data
+    {
+        let recommendedNextStepJson: String
+        if let recommendedNextStep {
+            recommendedNextStepJson = """
+            ,
+                          "recommendedNextStep": "\(recommendedNextStep)"
+            """
+        } else {
+            recommendedNextStepJson = ""
+        }
+        let json = """
+        {
+          "type": "res",
+          "id": "\(id)",
+          "ok": false,
+          "error": {
+            "message": "\(message)",
+            "details": {
+              "code": "\(detailCode)",
+              "canRetryWithDeviceToken": \(canRetryWithDeviceToken ? "true" : "false")
+              \(recommendedNextStepJson)
+            }
+          }
+        }
+        """
+        return Data(json.utf8)
+    }
+
     static func requestID(from message: URLSessionWebSocketTask.Message) -> String? {
         guard let obj = self.requestFrameObject(from: message) else { return nil }
         guard (obj["type"] as? String) == "req" else {

apps/macos/Tests/OpenClawIPCTests/LowCoverageViewSmokeTests.swift

@@ -66,6 +66,15 @@ struct LowCoverageViewSmokeTests {
         try? await Task.sleep(nanoseconds: 250_000_000)
     }
 
+    @Test func `talk overlay presents twice and dismisses`() async {
+        let controller = TalkOverlayController()
+        controller.present()
+        controller.updateLevel(0.4)
+        controller.present()
+        controller.dismiss()
+        try? await Task.sleep(nanoseconds: 250_000_000)
+    }
+
     @Test func `visual effect view hosts in NS hosting view`() {
         let hosting = NSHostingView(rootView: VisualEffectView(material: .sidebar))
         _ = hosting.fittingSize

apps/macos/Tests/OpenClawIPCTests/MacNodeBrowserProxyTests.swift

@@ -38,4 +38,49 @@ struct MacNodeBrowserProxyTests {
         #expect(tabs.count == 1)
         #expect(tabs[0]["id"] as? String == "tab-1")
     }
+
+    // Regression test: nested POST bodies must serialize without __SwiftValue crashes.
+    @Test func postRequestSerializesNestedBodyWithoutCrash() async throws {
+        actor BodyCapture {
+            private var body: Data?
+
+            func set(_ body: Data?) {
+                self.body = body
+            }
+
+            func get() -> Data? {
+                self.body
+            }
+        }
+
+        let capturedBody = BodyCapture()
+        let proxy = MacNodeBrowserProxy(
+            endpointProvider: {
+                MacNodeBrowserProxy.Endpoint(
+                    baseURL: URL(string: "http://127.0.0.1:18791")!,
+                    token: nil,
+                    password: nil)
+            },
+            performRequest: { request in
+                await capturedBody.set(request.httpBody)
+                let url = try #require(request.url)
+                let response = try #require(
+                    HTTPURLResponse(
+                        url: url,
+                        statusCode: 200,
+                        httpVersion: nil,
+                        headerFields: nil))
+                return (Data(#"{"ok":true}"#.utf8), response)
+            })
+
+        _ = try await proxy.request(
+            paramsJSON: #"{"method":"POST","path":"/action","body":{"nested":{"key":"val"},"arr":[1,2]}}"#)
+
+        let bodyData = try #require(await capturedBody.get())
+        let parsed = try #require(JSONSerialization.jsonObject(with: bodyData) as? [String: Any])
+        let nested = try #require(parsed["nested"] as? [String: Any])
+        #expect(nested["key"] as? String == "val")
+        let arr = try #require(parsed["arr"] as? [Any])
+        #expect(arr.count == 2)
+    }
 }

apps/macos/Tests/OpenClawIPCTests/OnboardingRemoteAuthPromptTests.swift

@@ -0,0 +1,126 @@
+import OpenClawKit
+import Testing
+@testable import OpenClaw
+
+@MainActor
+struct OnboardingRemoteAuthPromptTests {
+    @Test func `auth detail codes map to remote auth issues`() {
+        let tokenMissing = GatewayConnectAuthError(
+            message: "token missing",
+            detailCode: GatewayConnectAuthDetailCode.authTokenMissing.rawValue,
+            canRetryWithDeviceToken: false)
+        let tokenMismatch = GatewayConnectAuthError(
+            message: "token mismatch",
+            detailCode: GatewayConnectAuthDetailCode.authTokenMismatch.rawValue,
+            canRetryWithDeviceToken: false)
+        let tokenNotConfigured = GatewayConnectAuthError(
+            message: "token not configured",
+            detailCode: GatewayConnectAuthDetailCode.authTokenNotConfigured.rawValue,
+            canRetryWithDeviceToken: false)
+        let passwordMissing = GatewayConnectAuthError(
+            message: "password missing",
+            detailCode: GatewayConnectAuthDetailCode.authPasswordMissing.rawValue,
+            canRetryWithDeviceToken: false)
+        let pairingRequired = GatewayConnectAuthError(
+            message: "pairing required",
+            detailCode: GatewayConnectAuthDetailCode.pairingRequired.rawValue,
+            canRetryWithDeviceToken: false)
+        let unknown = GatewayConnectAuthError(
+            message: "other",
+            detailCode: "SOMETHING_ELSE",
+            canRetryWithDeviceToken: false)
+
+        #expect(RemoteGatewayAuthIssue(error: tokenMissing) == .tokenRequired)
+        #expect(RemoteGatewayAuthIssue(error: tokenMismatch) == .tokenMismatch)
+        #expect(RemoteGatewayAuthIssue(error: tokenNotConfigured) == .gatewayTokenNotConfigured)
+        #expect(RemoteGatewayAuthIssue(error: passwordMissing) == .passwordRequired)
+        #expect(RemoteGatewayAuthIssue(error: pairingRequired) == .pairingRequired)
+        #expect(RemoteGatewayAuthIssue(error: unknown) == nil)
+    }
+
+    @Test func `password detail family maps to password required issue`() {
+        let mismatch = GatewayConnectAuthError(
+            message: "password mismatch",
+            detailCode: GatewayConnectAuthDetailCode.authPasswordMismatch.rawValue,
+            canRetryWithDeviceToken: false)
+        let notConfigured = GatewayConnectAuthError(
+            message: "password not configured",
+            detailCode: GatewayConnectAuthDetailCode.authPasswordNotConfigured.rawValue,
+            canRetryWithDeviceToken: false)
+
+        #expect(RemoteGatewayAuthIssue(error: mismatch) == .passwordRequired)
+        #expect(RemoteGatewayAuthIssue(error: notConfigured) == .passwordRequired)
+    }
+
+    @Test func `token field visibility follows onboarding rules`() {
+        #expect(OnboardingView.shouldShowRemoteTokenField(
+            showAdvancedConnection: false,
+            remoteToken: "",
+            remoteTokenUnsupported: false,
+            authIssue: nil) == false)
+        #expect(OnboardingView.shouldShowRemoteTokenField(
+            showAdvancedConnection: true,
+            remoteToken: "",
+            remoteTokenUnsupported: false,
+            authIssue: nil))
+        #expect(OnboardingView.shouldShowRemoteTokenField(
+            showAdvancedConnection: false,
+            remoteToken: "secret",
+            remoteTokenUnsupported: false,
+            authIssue: nil))
+        #expect(OnboardingView.shouldShowRemoteTokenField(
+            showAdvancedConnection: false,
+            remoteToken: "",
+            remoteTokenUnsupported: true,
+            authIssue: nil))
+        #expect(OnboardingView.shouldShowRemoteTokenField(
+            showAdvancedConnection: false,
+            remoteToken: "",
+            remoteTokenUnsupported: false,
+            authIssue: .tokenRequired))
+        #expect(OnboardingView.shouldShowRemoteTokenField(
+            showAdvancedConnection: false,
+            remoteToken: "",
+            remoteTokenUnsupported: false,
+            authIssue: .tokenMismatch))
+        #expect(OnboardingView.shouldShowRemoteTokenField(
+            showAdvancedConnection: false,
+            remoteToken: "",
+            remoteTokenUnsupported: false,
+            authIssue: .gatewayTokenNotConfigured) == false)
+        #expect(OnboardingView.shouldShowRemoteTokenField(
+            showAdvancedConnection: false,
+            remoteToken: "",
+            remoteTokenUnsupported: false,
+            authIssue: .pairingRequired) == false)
+    }
+
+    @Test func `pairing required copy points users to pair approve`() {
+        let issue = RemoteGatewayAuthIssue.pairingRequired
+
+        #expect(issue.title == "This device needs pairing approval")
+        #expect(issue.body.contains("`/pair approve`"))
+        #expect(issue.statusMessage.contains("/pair approve"))
+        #expect(issue.footnote?.contains("`openclaw devices approve`") == true)
+    }
+
+    @Test func `paired device success copy explains auth source`() {
+        let pairedDevice = RemoteGatewayProbeSuccess(authSource: .deviceToken)
+        let sharedToken = RemoteGatewayProbeSuccess(authSource: .sharedToken)
+        let noAuth = RemoteGatewayProbeSuccess(authSource: GatewayAuthSource.none)
+
+        #expect(pairedDevice.title == "Connected via paired device")
+        #expect(pairedDevice.detail == "This Mac used a stored device token. New or unpaired devices may still need the gateway token.")
+        #expect(sharedToken.title == "Connected with gateway token")
+        #expect(sharedToken.detail == nil)
+        #expect(noAuth.title == "Remote gateway ready")
+        #expect(noAuth.detail == nil)
+    }
+
+    @Test func `transient probe mode restore does not clear probe feedback`() {
+        #expect(OnboardingView.shouldResetRemoteProbeFeedback(for: .local, suppressReset: false))
+        #expect(OnboardingView.shouldResetRemoteProbeFeedback(for: .unconfigured, suppressReset: false))
+        #expect(OnboardingView.shouldResetRemoteProbeFeedback(for: .remote, suppressReset: false) == false)
+        #expect(OnboardingView.shouldResetRemoteProbeFeedback(for: .local, suppressReset: true) == false)
+    }
+}

apps/macos/Tests/OpenClawIPCTests/TailscaleServeGatewayDiscoveryTests.swift

@@ -74,4 +74,25 @@ struct TailscaleServeGatewayDiscoveryTests {
         #expect(TailscaleServeGatewayDiscovery
             .resolveExecutablePath("definitely-not-here", env: ["PATH": "/tmp"]) == nil)
     }
+
+    @Test func `adds TERM for GUI-launched tailscale subprocesses`() {
+        let env = TailscaleServeGatewayDiscovery.commandEnvironment(base: [
+            "HOME": "/Users/tester",
+            "PATH": "/usr/bin:/bin",
+        ])
+
+        #expect(env["TERM"] == "dumb")
+        #expect(env["HOME"] == "/Users/tester")
+        #expect(env["PATH"] == "/usr/bin:/bin")
+    }
+
+    @Test func `preserves existing TERM when building tailscale subprocess environment`() {
+        let env = TailscaleServeGatewayDiscovery.commandEnvironment(base: [
+            "TERM": "xterm-256color",
+            "HOME": "/Users/tester",
+        ])
+
+        #expect(env["TERM"] == "xterm-256color")
+        #expect(env["HOME"] == "/Users/tester")
+    }
 }

apps/macos/Tests/OpenClawIPCTests/TalkModeConfigParsingTests.swift

@@ -3,7 +3,7 @@ import Testing
 @testable import OpenClaw
 
 struct TalkModeConfigParsingTests {
-    @Test func `prefers normalized talk provider payload`() {
+    @Test func `rejects normalized talk provider payload without resolved`() {
         let talk: [String: AnyCodable] = [
             "provider": AnyCodable("elevenlabs"),
             "providers": AnyCodable([
@@ -15,9 +15,7 @@ struct TalkModeConfigParsingTests {
         ]
 
         let selection = TalkModeRuntime.selectTalkProviderConfig(talk)
-        #expect(selection?.provider == "elevenlabs")
-        #expect(selection?.normalizedPayload == true)
-        #expect(selection?.config["voiceId"]?.stringValue == "voice-normalized")
+        #expect(selection == nil)
     }
 
     @Test func `falls back to legacy talk fields when normalized payload missing`() {
@@ -32,4 +30,24 @@ struct TalkModeConfigParsingTests {
         #expect(selection?.config["voiceId"]?.stringValue == "voice-legacy")
         #expect(selection?.config["apiKey"]?.stringValue == "legacy-key")
     }
+
+    @Test func `reads configured silence timeout ms`() {
+        let talk: [String: AnyCodable] = [
+            "silenceTimeoutMs": AnyCodable(1500),
+        ]
+
+        #expect(TalkModeRuntime.resolvedSilenceTimeoutMs(talk) == 1500)
+    }
+
+    @Test func `defaults silence timeout ms when missing`() {
+        #expect(TalkModeRuntime.resolvedSilenceTimeoutMs(nil) == TalkDefaults.silenceTimeoutMs)
+    }
+
+    @Test func `defaults silence timeout ms when invalid`() {
+        let talk: [String: AnyCodable] = [
+            "silenceTimeoutMs": AnyCodable(0),
+        ]
+
+        #expect(TalkModeRuntime.resolvedSilenceTimeoutMs(talk) == TalkDefaults.silenceTimeoutMs)
+    }
 }

apps/macos/Tests/OpenClawIPCTests/TalkModeRuntimeSpeechTests.swift

@@ -0,0 +1,14 @@
+import Speech
+import Testing
+@testable import OpenClaw
+
+struct TalkModeRuntimeSpeechTests {
+    @Test func `speech request uses dictation defaults`() {
+        let request = SFSpeechAudioBufferRecognitionRequest()
+
+        TalkModeRuntime.configureRecognitionRequest(request)
+
+        #expect(request.shouldReportPartialResults)
+        #expect(request.taskHint == .dictation)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatComposer.swift

@@ -9,6 +9,8 @@ import UniformTypeIdentifiers
 
 @MainActor
 struct OpenClawChatComposer: View {
+    private static let menuThinkingLevels = ["off", "low", "medium", "high"]
+
     @Bindable var viewModel: OpenClawChatViewModel
     let style: OpenClawChatView.Style
     let showsSessionSwitcher: Bool
@@ -27,11 +29,15 @@ struct OpenClawChatComposer: View {
                     if self.showsSessionSwitcher {
                         self.sessionPicker
                     }
+                    if self.viewModel.showsModelPicker {
+                        self.modelPicker
+                    }
                     self.thinkingPicker
                     Spacer()
                     self.refreshButton
                     self.attachmentPicker
                 }
+                .padding(.horizontal, 10)
             }
 
             if self.showsAttachments, !self.viewModel.attachments.isEmpty {
@@ -83,11 +89,19 @@ struct OpenClawChatComposer: View {
     }
 
     private var thinkingPicker: some View {
-        Picker("Thinking", selection: self.$viewModel.thinkingLevel) {
+        Picker(
+            "Thinking",
+            selection: Binding(
+                get: { self.viewModel.thinkingLevel },
+                set: { next in self.viewModel.selectThinkingLevel(next) }))
+        {
             Text("Off").tag("off")
             Text("Low").tag("low")
             Text("Medium").tag("medium")
             Text("High").tag("high")
+            if !Self.menuThinkingLevels.contains(self.viewModel.thinkingLevel) {
+                Text(self.viewModel.thinkingLevel.capitalized).tag(self.viewModel.thinkingLevel)
+            }
         }
         .labelsHidden()
         .pickerStyle(.menu)
@@ -95,6 +109,25 @@ struct OpenClawChatComposer: View {
         .frame(maxWidth: 140, alignment: .leading)
     }
 
+    private var modelPicker: some View {
+        Picker(
+            "Model",
+            selection: Binding(
+                get: { self.viewModel.modelSelectionID },
+                set: { next in self.viewModel.selectModel(next) }))
+        {
+            Text(self.viewModel.defaultModelLabel).tag(OpenClawChatViewModel.defaultModelSelectionID)
+            ForEach(self.viewModel.modelChoices) { model in
+                Text(model.displayLabel).tag(model.selectionID)
+            }
+        }
+        .labelsHidden()
+        .pickerStyle(.menu)
+        .controlSize(.small)
+        .frame(maxWidth: 240, alignment: .leading)
+        .help("Model")
+    }
+
     private var sessionPicker: some View {
         Picker(
             "Session",

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessions.swift

@@ -1,5 +1,36 @@
 import Foundation
 
+public struct OpenClawChatModelChoice: Identifiable, Codable, Sendable, Hashable {
+    public var id: String { self.selectionID }
+
+    public let modelID: String
+    public let name: String
+    public let provider: String
+    public let contextWindow: Int?
+
+    public init(modelID: String, name: String, provider: String, contextWindow: Int?) {
+        self.modelID = modelID
+        self.name = name
+        self.provider = provider
+        self.contextWindow = contextWindow
+    }
+
+    /// Provider-qualified model ref used for picker identity and selection tags.
+    public var selectionID: String {
+        let trimmedProvider = self.provider.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedProvider.isEmpty else { return self.modelID }
+        let providerPrefix = "\(trimmedProvider)/"
+        if self.modelID.hasPrefix(providerPrefix) {
+            return self.modelID
+        }
+        return "\(trimmedProvider)/\(self.modelID)"
+    }
+
+    public var displayLabel: String {
+        self.selectionID
+    }
+}
+
 public struct OpenClawChatSessionsDefaults: Codable, Sendable {
     public let model: String?
     public let contextTokens: Int?
@@ -27,6 +58,7 @@ public struct OpenClawChatSessionEntry: Codable, Identifiable, Sendable, Hashabl
     public let outputTokens: Int?
     public let totalTokens: Int?
 
+    public let modelProvider: String?
     public let model: String?
     public let contextTokens: Int?
 }

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatTransport.swift

@@ -10,6 +10,7 @@ public enum OpenClawChatTransportEvent: Sendable {
 
 public protocol OpenClawChatTransport: Sendable {
     func requestHistory(sessionKey: String) async throws -> OpenClawChatHistoryPayload
+    func listModels() async throws -> [OpenClawChatModelChoice]
     func sendMessage(
         sessionKey: String,
         message: String,
@@ -19,6 +20,8 @@ public protocol OpenClawChatTransport: Sendable {
 
     func abortRun(sessionKey: String, runId: String) async throws
     func listSessions(limit: Int?) async throws -> OpenClawChatSessionsListResponse
+    func setSessionModel(sessionKey: String, model: String?) async throws
+    func setSessionThinking(sessionKey: String, thinkingLevel: String) async throws
 
     func requestHealth(timeoutMs: Int) async throws -> Bool
     func events() -> AsyncStream<OpenClawChatTransportEvent>
@@ -42,4 +45,25 @@ extension OpenClawChatTransport {
             code: 0,
             userInfo: [NSLocalizedDescriptionKey: "sessions.list not supported by this transport"])
     }
+
+    public func listModels() async throws -> [OpenClawChatModelChoice] {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "models.list not supported by this transport"])
+    }
+
+    public func setSessionModel(sessionKey _: String, model _: String?) async throws {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.patch(model) not supported by this transport"])
+    }
+
+    public func setSessionThinking(sessionKey _: String, thinkingLevel _: String) async throws {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.patch(thinkingLevel) not supported by this transport"])
+    }
 }