CLI: unify interactive root argv scanning

Merged via /review-pr -> /prepare-pr -> /merge-pr.

Prepared head SHA: 27a343cd4d
Co-authored-by: theSamPadilla <35386211+theSamPadilla@users.noreply.github.com>
Co-authored-by: obviyus <22031114+obviyus@users.noreply.github.com>
Reviewed-by: @obviyus

.github/workflows/auto-response.yml

@@ -13,7 +13,7 @@ jobs:
     permissions:
       issues: write
       pull-requests: write
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
         id: app-token

.github/workflows/ci.yml

@@ -6,14 +6,14 @@ on:
   pull_request:
 
 concurrency:
-  group: ci-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   # Detect docs-only changes to skip heavy jobs (test, build, Windows, macOS, Android).
   # Lint and format always run. Fail-safe: if detection fails, run everything.
   docs-scope:
-    runs-on: ubuntu-latest
+    runs-on: blacksmith-4vcpu-ubuntu-2404
     outputs:
       docs_only: ${{ steps.check.outputs.docs_only }}
       docs_changed: ${{ steps.check.outputs.docs_changed }}
@@ -33,7 +33,7 @@ jobs:
   changed-scope:
     needs: [docs-scope]
     if: needs.docs-scope.outputs.docs_only != 'true'
-    runs-on: ubuntu-latest
+    runs-on: blacksmith-4vcpu-ubuntu-2404
     outputs:
       run_node: ${{ steps.scope.outputs.run_node }}
       run_macos: ${{ steps.scope.outputs.run_macos }}
@@ -204,6 +204,14 @@ jobs:
         if: matrix.task == 'test' && matrix.runtime == 'node'
         run: echo "OPENCLAW_VITEST_REPORT_DIR=$RUNNER_TEMP/vitest-reports" >> "$GITHUB_ENV"
 
+      - name: Configure Node test resources
+        if: matrix.task == 'test' && matrix.runtime == 'node'
+        run: |
+          # `pnpm test` runs `scripts/test-parallel.mjs`, which spawns multiple Node processes.
+          # Default heap limits have been too low on Linux CI (V8 OOM near 4GB).
+          echo "OPENCLAW_TEST_WORKERS=2" >> "$GITHUB_ENV"
+          echo "OPENCLAW_TEST_MAX_OLD_SPACE_SIZE_MB=6144" >> "$GITHUB_ENV"
+
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         run: ${{ matrix.command }}
 
@@ -664,7 +672,8 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: 21
+          # setup-android's sdkmanager currently crashes on JDK 21 in CI.
+          java-version: 17
 
       - name: Setup Android SDK
         uses: android-actions/setup-android@v3

.github/workflows/docker-release.yml

@@ -13,6 +13,10 @@ on:
       - ".agents/**"
       - "skills/**"
 
+concurrency:
+  group: docker-release-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}

.github/workflows/formal-conformance.yml

@@ -1,138 +0,0 @@
-name: Formal models (informational conformance)
-
-on:
-  pull_request:
-
-concurrency:
-  group: formal-conformance-${{ github.event.pull_request.number || github.ref_name }}
-  cancel-in-progress: true
-
-jobs:
-  formal_conformance:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    permissions:
-      contents: read
-      pull-requests: write
-
-    steps:
-      - name: Checkout openclaw (PR)
-        uses: actions/checkout@v4
-        with:
-          path: openclaw
-
-      - name: Checkout formal models
-        uses: actions/checkout@v4
-        with:
-          repository: vignesh07/clawdbot-formal-models
-          ref: main
-          path: clawdbot-formal-models
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-
-      - name: Regenerate extracted constants from openclaw
-        run: |
-          set -euo pipefail
-          cd clawdbot-formal-models
-          export OPENCLAW_REPO_DIR="${GITHUB_WORKSPACE}/openclaw"
-          node scripts/extract-tool-groups.mjs
-          node scripts/check-tool-group-alias.mjs
-
-      # Drift is about extracted artifacts only; compute it before model checking
-      # to avoid any incidental file touches affecting the result.
-      - name: Compute drift (generated/*)
-        id: drift
-        run: |
-          set -euo pipefail
-          cd clawdbot-formal-models
-
-          if git diff --quiet -- generated; then
-            echo "drift=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          echo "drift=true" >> "$GITHUB_OUTPUT"
-          git diff -- generated > "${GITHUB_WORKSPACE}/formal-models-drift.diff"
-
-      - name: Model check (green suite)
-        run: |
-          set -euo pipefail
-          cd clawdbot-formal-models
-          make \
-            precedence groups elevated nodes-policy \
-            attacker approvals approvals-token nodes-pipeline \
-            gateway-exposure gateway-exposure-v2 gateway-exposure-v2-protected \
-            gateway-auth-conformance gateway-auth-tailscale gateway-auth-proxy \
-            pairing pairing-cap pairing-idempotency pairing-refresh pairing-refresh-race \
-            ingress-gating ingress-idempotency ingress-dedupe-fallback ingress-trace ingress-trace2 \
-            routing-isolation routing-precedence routing-identitylinks routing-identity-transitive routing-identity-symmetry routing-identity-channel-override \
-            routing-thread-parent discord-pluralkit \
-            ingress-retry session-key-stability session-explosion-bound config-normalization \
-            queue-drain delivery-route-stability delivery-pipeline retry-termination retry-eventual-success \
-            no-cross-stream multi-event-eventual-emission \
-            dedupe-collision-fallback crash-restart-dedupe two-worker-dedupe openclaw-session-key-conformance \
-            routing-thread-parent-channel-override routing-trirule gateway-auth-proxy-header-spoof \
-            group-alias-check
-
-      - name: Model check (negative suite, expected violations)
-        continue-on-error: true
-        run: |
-          set -euo pipefail
-          cd clawdbot-formal-models
-          make -k \
-            precedence-negative groups-negative elevated-negative nodes-policy-negative \
-            attacker-negative attacker-nodes-negative attacker-nodes-allowlist-negative attacker-nodes-allowlist-negative \
-            approvals-negative approvals-token-negative nodes-pipeline-negative \
-            gateway-exposure-negative gateway-exposure-v2-negative gateway-exposure-v2-protected-negative \
-            gateway-exposure-v2-unsafe-custom gateway-exposure-v2-unsafe-tailnet gateway-exposure-v2-unsafe-auto \
-            gateway-auth-conformance-negative gateway-auth-tailscale-negative gateway-auth-proxy-negative \
-            pairing-negative pairing-cap-negative pairing-idempotency-negative pairing-refresh-negative pairing-refresh-race-negative \
-            ingress-gating-negative ingress-idempotency-negative ingress-dedupe-fallback-negative ingress-trace-negative ingress-trace2-negative \
-            routing-isolation-negative routing-precedence-negative routing-identitylinks-negative routing-identity-transitive-negative routing-identity-symmetry-negative routing-identity-channel-override-negative \
-            routing-thread-parent-negative discord-pluralkit-negative \
-            ingress-retry-negative session-key-stability-negative config-normalization-negative \
-            queue-drain delivery-route-stability-negative delivery-pipeline-negative retry-termination-negative retry-eventual-success-negative \
-            no-cross-stream-negative multi-event-eventual-emission-negative \
-            dedupe-collision-fallback-negative crash-restart-dedupe-negative two-worker-dedupe-negative openclaw-session-key-conformance-negative \
-            routing-thread-parent-channel-override-negative routing-trirule-negative gateway-auth-proxy-header-spoof-negative
-
-      - name: Upload drift diff artifact
-        if: steps.drift.outputs.drift == 'true'
-        uses: actions/upload-artifact@v4
-        with:
-          name: formal-models-conformance-drift
-          path: formal-models-drift.diff
-
-      - name: Comment on PR (informational)
-        if: steps.drift.outputs.drift == 'true'
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const body = [
-              '⚠️ **Formal models conformance drift detected**',
-              '',
-              'The formal models extracted constants (`generated/*`) do not match this openclaw PR.',
-              '',
-              'This check is **informational** (not blocking merges yet).',
-              'See the `formal-models-conformance-drift` artifact for the diff.',
-              '',
-              'If this change is intentional, follow up by updating the formal models repo or regenerating the extracted artifacts there.',
-            ].join('\n');
-
-            await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.payload.pull_request.number,
-              body,
-            });
-
-      - name: Summary
-        run: |
-          if [ "${{ steps.drift.outputs.drift }}" = "true" ]; then
-            echo "Formal conformance drift detected (informational)."
-          else
-            echo "Formal conformance: no drift."
-          fi

.github/workflows/install-smoke.yml

@@ -7,8 +7,8 @@ on:
   workflow_dispatch:
 
 concurrency:
-  group: install-smoke-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
+  group: install-smoke-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   docs-scope:
@@ -33,19 +33,17 @@ jobs:
       - name: Checkout CLI
         uses: actions/checkout@v4
 
-      - name: Setup pnpm (corepack retry)
-        run: |
-          set -euo pipefail
-          corepack enable
-          for attempt in 1 2 3; do
-            if corepack prepare pnpm@10.23.0 --activate; then
-              pnpm -v
-              exit 0
-            fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
-            sleep $((attempt * 10))
-          done
-          exit 1
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Install pnpm deps (minimal)
         run: pnpm install --ignore-scripts --frozen-lockfile

.github/workflows/labeler.yml

@@ -23,7 +23,7 @@ jobs:
     permissions:
       contents: read
       pull-requests: write
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
         id: app-token
@@ -200,7 +200,7 @@ jobs:
     permissions:
       contents: read
       pull-requests: write
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
         id: app-token
@@ -440,7 +440,7 @@ jobs:
   label-issues:
     permissions:
       issues: write
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
         id: app-token

.github/workflows/sandbox-common-smoke.yml

@@ -14,8 +14,8 @@ on:
       - scripts/sandbox-common-setup.sh
 
 concurrency:
-  group: sandbox-common-smoke-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
+  group: sandbox-common-smoke-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   sandbox-common-smoke:

.github/workflows/stale.yml

@@ -12,7 +12,7 @@ jobs:
     permissions:
       issues: write
       pull-requests: write
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
         id: app-token
@@ -31,7 +31,7 @@ jobs:
           stale-pr-label: stale
           exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale
           exempt-pr-labels: maintainer,no-stale
-          operations-per-run: 500
+          operations-per-run: 10000
           exempt-all-assignees: true
           remove-stale-when-updated: true
           stale-issue-message: |

.github/workflows/workflow-sanity.yml

@@ -6,8 +6,8 @@ on:
     branches: [main]
 
 concurrency:
-  group: workflow-sanity-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
+  group: workflow-sanity-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   no-tabs:

.gitignore

@@ -27,6 +27,8 @@ apps/android/.cxx/
 *.bun-build
 apps/macos/.build/
 apps/shared/MoltbotKit/.build/
+apps/shared/OpenClawKit/.build/
+apps/shared/OpenClawKit/Package.resolved
 **/ModuleCache/
 bin/
 bin/clawdbot-mac

.oxfmtrc.jsonc

@@ -14,6 +14,7 @@
     "node_modules/",
     "patches/",
     "pnpm-lock.yaml/",
+    "src/auto-reply/reply/export-html/",
     "Swabble/",
     "vendor/",
   ],

.oxlintrc.json

@@ -11,6 +11,8 @@
     "eslint-plugin-unicorn/prefer-array-find": "off",
     "eslint/no-await-in-loop": "off",
     "eslint/no-new": "off",
+    "eslint/no-shadow": "off",
+    "eslint/no-unmodified-loop-condition": "off",
     "oxc/no-accumulating-spread": "off",
     "oxc/no-async-endpoint-handlers": "off",
     "oxc/no-map-spread": "off",
@@ -27,8 +29,9 @@
     "extensions/",
     "node_modules/",
     "patches/",
-    "pnpm-lock.yaml/",
+    "pnpm-lock.yaml",
     "skills/",
+    "src/auto-reply/reply/export-html/template.js",
     "src/canvas-host/a2ui/a2ui.bundle.js",
     "Swabble/",
     "vendor/"

AGENTS.md

@@ -70,6 +70,10 @@
 
 - Language: TypeScript (ESM). Prefer strict typing; avoid `any`.
 - Formatting/linting via Oxlint and Oxfmt; run `pnpm check` before commits.
+- Never add `@ts-nocheck` and do not disable `no-explicit-any`; fix root causes and update Oxlint/Oxfmt config only when required.
+- Never share class behavior via prototype mutation (`applyPrototypeMixins`, `Object.defineProperty` on `.prototype`, or exporting `Class.prototype` for merges). Use explicit inheritance/composition (`A extends B extends C`) or helper composition so TypeScript can typecheck.
+- If this pattern is needed, stop and get explicit approval before shipping; default behavior is to split/refactor into an explicit class hierarchy and keep members strongly typed.
+- In tests, prefer per-instance stubs over prototype mutation (`SomeClass.prototype.method = ...`) unless a test explicitly documents why prototype-level patching is required.
 - Add brief code comments for tricky or non-obvious logic.
 - Keep files concise; extract helpers instead of “V2” copies. Use existing patterns for CLI options and dependency injection via `createDefaultDeps`.
 - Aim to keep files under ~700 LOC; guideline only (not a hard guardrail). Split/refactor when it improves clarity or testability.
@@ -119,6 +123,19 @@
 - Never commit or publish real phone numbers, videos, or live configuration values. Use obviously fake placeholders in docs, tests, and examples.
 - Release flow: always read `docs/reference/RELEASING.md` and `docs/platforms/mac/release.md` before any release work; do not ask routine questions once those docs answer them.
 
+## GHSA (Repo Advisory) Patch/Publish
+
+- Fetch: `gh api /repos/openclaw/openclaw/security-advisories/<GHSA>`
+- Latest npm: `npm view openclaw version --userconfig "$(mktemp)"`
+- Private fork PRs must be closed:
+  `fork=$(gh api /repos/openclaw/openclaw/security-advisories/<GHSA> | jq -r .private_fork.full_name)`
+  `gh pr list -R "$fork" --state open` (must be empty)
+- Description newline footgun: write Markdown via heredoc to `/tmp/ghsa.desc.md` (no `"\\n"` strings)
+- Build patch JSON via jq: `jq -n --rawfile desc /tmp/ghsa.desc.md '{summary,severity,description:$desc,vulnerabilities:[...]}' > /tmp/ghsa.patch.json`
+- Patch + publish: `gh api -X PATCH /repos/openclaw/openclaw/security-advisories/<GHSA> --input /tmp/ghsa.patch.json` (publish = include `"state":"published"`; no `/publish` endpoint)
+- If publish fails (HTTP 422): missing `severity`/`description`/`vulnerabilities[]`, or private fork has open PRs
+- Verify: re-fetch; ensure `state=published`, `published_at` set; `jq -r .description | rg '\\\\n'` returns nothing
+
 ## Troubleshooting
 
 - Rebrand/migration issues or legacy config/service warnings: run `openclaw doctor` (see `docs/gateway/doctor.md`).
@@ -182,3 +199,39 @@
 - Publish: `npm publish --access public --otp="<otp>"` (run from the package dir).
 - Verify without local npmrc side effects: `npm view <pkg> version --userconfig "$(mktemp)"`.
 - Kill the tmux session after publish.
+
+## Plugin Release Fast Path (no core `openclaw` publish)
+
+- Release only already-on-npm plugins. Source list is in `docs/reference/RELEASING.md` under "Current npm plugin list".
+- Run all CLI `op` calls and `npm publish` inside tmux to avoid hangs/interruption:
+  - `tmux new -d -s release-plugins-$(date +%Y%m%d-%H%M%S)`
+  - `eval "$(op signin --account my.1password.com)"`
+- 1Password helpers:
+  - password used by `npm login`:
+    `op item get Npmjs --format=json | jq -r '.fields[] | select(.id=="password").value'`
+  - OTP:
+    `op read 'op://Private/Npmjs/one-time password?attribute=otp'`
+- Fast publish loop (local helper script in `/tmp` is fine; keep repo clean):
+  - compare local plugin `version` to `npm view <name> version`
+  - only run `npm publish --access public --otp="<otp>"` when versions differ
+  - skip if package is missing on npm or version already matches.
+- Keep `openclaw` untouched: never run publish from repo root unless explicitly requested.
+- Post-check for each release:
+  - per-plugin: `npm view @openclaw/<name> version --userconfig "$(mktemp)"` should be `2026.2.16`
+  - core guard: `npm view openclaw version --userconfig "$(mktemp)"` should stay at previous version unless explicitly requested.
+
+## Changelog Release Notes
+
+- When cutting a mac release with beta GitHub prerelease:
+  - Tag `vYYYY.M.D-beta.N` from the release commit (example: `v2026.2.15-beta.1`).
+  - Create prerelease with title `openclaw YYYY.M.D-beta.N`.
+  - Use release notes from `CHANGELOG.md` version section (`Changes` + `Fixes`, no title duplicate).
+  - Attach at least `OpenClaw-YYYY.M.D.zip` and `OpenClaw-YYYY.M.D.dSYM.zip`; include `.dmg` if available.
+
+- Keep top version entries in `CHANGELOG.md` sorted by impact:
+  - `### Changes` first.
+  - `### Fixes` deduped and ranked with user-facing fixes first.
+- Before tagging/publishing, run:
+  - `node --import tsx scripts/release-check.ts`
+  - `pnpm release:check`
+  - `pnpm test:install:smoke` or `OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke` for non-root smoke path.

CHANGELOG.md

@@ -2,26 +2,155 @@
 
 Docs: https://docs.openclaw.ai
 
-## 2026.2.15 (Unreleased)
+## 2026.2.16 (Unreleased)
 
 ### Changes
 
-- Subagents: nested sub-agents (sub-sub-agents) with configurable depth. Set `agents.defaults.subagents.maxSpawnDepth: 2` to allow sub-agents to spawn their own children. Includes `maxChildrenPerAgent` limit (default 5), depth-aware tool policy, and proper announce chain routing. (#14447) Thanks @tyler6204.
+- iOS/Talk: add a `Background Listening` toggle that keeps Talk Mode active while the app is backgrounded (off by default for battery safety). Thanks @zeulewan.
+- iOS/Talk: harden barge-in behavior by disabling interrupt-on-speech when output route is built-in speaker/receiver, reducing false interruptions from local TTS bleed-through. Thanks @zeulewan.
+- iOS/Talk: add a `Voice Directive Hint` toggle for Talk Mode prompts so users can disable ElevenLabs voice-switching instructions to save tokens when not needed. (#18250) Thanks @zeulewan.
+- Telegram/Agents: add inline button `style` support (`primary|success|danger`) across message tool schema, Telegram action parsing, send pipeline, and runtime prompt guidance. (#18241) Thanks @obviyus.
+- Discord: expose native `/exec` command options (host/security/ask/node) so Discord slash commands get autocomplete and structured inputs. Thanks @thewilloftheshadow.
+- Discord: allow reusable interactive components with `components.reusable=true` so buttons, selects, and forms can be used multiple times before expiring. Thanks @thewilloftheshadow.
+- Cron/Gateway: separate per-job webhook delivery (`delivery.mode = "webhook"`) from announce delivery, enforce valid HTTP(S) webhook URLs, and keep a temporary legacy `notify + cron.webhook` fallback for stored jobs. (#17901) Thanks @advaitpaliwal.
+- Discord: add per-button `allowedUsers` allowlist for interactive components to restrict who can click buttons. Thanks @thewilloftheshadow.
+- Docker: add optional `OPENCLAW_INSTALL_BROWSER` build arg to preinstall Chromium + Xvfb in the Docker image, avoiding runtime Playwright installs. (#18449)
 
 ### Fixes
 
+- Fix types in all tests. Typecheck the whole repository.
+- Voice-call: auto-end calls when media streams disconnect to prevent stuck active calls. (#18435) Thanks @JayMishra-source.
+- Gateway/Channels: wire `gateway.channelHealthCheckMinutes` into strict config validation, treat implicit account status as managed for health checks, and harden channel auto-restart flow (preserve restart-attempt caps across crash loops, propagate enabled/configured runtime flags, and stop pending restart backoff after manual stop). Thanks @steipete.
+- Gateway/WebChat: hard-cap `chat.history` oversized payloads by truncating high-cost fields and replacing over-budget entries with placeholders, so history fetches stay within configured byte limits and avoid chat UI freezes. (#18505)
+- UI/Usage: replace lingering undefined `var(--text-muted)` usage with `var(--muted)` in usage date-range and chart styles to keep muted text visible across themes. (#17975) Thanks @jogelin.
+- UI/Usage: preserve selected-range totals when timeline data is downsampled by bucket-aggregating timeseries points (instead of dropping intermediate points), so filtered tokens/cost stay accurate. (#17959) Thanks @jogelin.
+- UI/Sessions: refresh the sessions table only after successful deletes and preserve delete errors on cancel/failure paths, so deleted sessions disappear automatically without masking delete failures. (#18507)
+- Mattermost: harden reaction handling by requiring an explicit boolean `remove` flag and routing reaction websocket events to the reaction handler, preventing string `"true"` values from being treated as removes and avoiding double-processing of reaction events as posts. (#18608) Thanks @echo931.
+- Scripts/UI/Windows: fix `pnpm ui:*` spawn `EINVAL` failures by restoring shell-backed launch for `.cmd`/`.bat` runners, narrowing shell usage to launcher types that require it, and rejecting unsafe forwarded shell metacharacters in UI script args. (#18594)
+- Hooks/Session-memory: recover `/new` conversation summaries when session pointers are reset-path or missing `sessionFile`, and consistently prefer the newest `.jsonl.reset.*` transcript candidate for fallback extraction. (#18088)
+- Auto-reply/Sessions: prevent stale thread ID leakage into non-thread sessions so replies stay in the main DM after topic interactions. (#18528) Thanks @j2h4u.
+- Slack: restrict forwarded-attachment ingestion to explicit shared-message attachments and skip non-Slack forwarded `image_url` fetches, preventing non-forward attachment unfurls from polluting inbound agent context while preserving forwarded message handling.
+- Agents/Sessions: align session lock watchdog hold windows with run and compaction timeout budgets (plus grace), preventing valid long-running turns from being force-unlocked mid-run while still recovering hung lock owners. (#18060)
+- Cron/Heartbeat: canonicalize session-scoped reminder `sessionKey` routing and preserve explicit flat `sessionKey` cron tool inputs, preventing enqueue/wake namespace drift for session-targeted reminders. (#18637) Thanks @vignesh07.
+- OpenClawKit/iOS ChatUI: accept canonical session-key completion events for local pending runs and preserve message IDs across history refreshes, preventing stuck "thinking" state and message flicker after gateway replies. (#18165) Thanks @mbelinky.
+- iOS/Onboarding: add QR-first onboarding wizard with setup-code deep link support, pairing/auth issue guidance, and device-pair QR generation improvements for Telegram/Web/TUI fallback flows. (#18162) Thanks @mbelinky and @Marvae.
+- iOS/Gateway: stabilize connect/discovery state handling, add onboarding reset recovery in Settings, and fix iOS gateway-controller coverage for command-surface and last-connection persistence behavior. (#18164) Thanks @mbelinky.
+- iOS/Talk: harden mobile talk config handling by ignoring redacted/env-placeholder API keys, support secure local keychain override, improve accessibility motion/contrast behavior in status UI, and tighten ATS to local-network allowance. (#18163) Thanks @mbelinky.
+- iOS/Location: restore the significant location monitor implementation (service hooks + protocol surface + ATS key alignment) after merge drift so iOS builds compile again. (#18260) Thanks @ngutman.
+- Discord/Telegram: make per-account message action gates effective for both action listing and execution, and preserve top-level gate restrictions when account overrides only specify a subset of `actions` keys (account key -> base key -> default fallback). (#18494)
+- Telegram: keep DM-topic replies and draft previews in the originating private-chat topic by preserving positive `message_thread_id` values for DM threads. (#18586) Thanks @sebslight.
+- Telegram: preserve private-chat topic `message_thread_id` on outbound sends (message/sticker/poll), keep thread-not-found retry fallback, and avoid masking `chat not found` routing errors. (#18993) Thanks @obviyus.
+- Discord: prevent duplicate media delivery when the model uses the `message send` tool with media, by skipping media extraction from messaging tool results since the tool already sent the message directly. (#18270)
+- Telegram: keep draft-stream preview replies attached to the user message for `replyToMode: "all"` in groups and DMs, preserving threaded reply context from preview through finalization. (#17880) Thanks @yinghaosang.
+- Telegram: prevent streaming final replies from being overwritten by later final/error payloads, and suppress fallback tool-error warnings when a recovered assistant answer already exists after tool calls. (#17883) Thanks @Marvae and @obviyus.
+- Telegram: debounce the first draft-stream preview update (30-char threshold) and finalize short responses by editing the stop-time preview message, improving first push notifications and avoiding duplicate final sends. (#18148) Thanks @Marvae.
+- Telegram: disable block streaming when `channels.telegram.streamMode` is `off`, preventing newline/content-block replies from splitting into multiple messages. (#17679) Thanks @saivarunk.
+- Telegram: keep `streamMode: "partial"` draft previews in a single message across assistant-message/reasoning boundaries, preventing duplicate preview bubbles during partial-mode tool-call turns. (#18956) Thanks @obviyus.
+- Telegram: route non-abort slash commands on the normal chat/topic sequential lane while keeping true abort requests (`/stop`, `stop`) on the control lane, preventing command/reply race conditions from control-lane bypass. (#17899) Thanks @obviyus.
+- Telegram: ignore `<media:...>` placeholder lines when extracting `MEDIA:` tool-result paths, preventing false local-file reads and dropped replies. (#18510) Thanks @yinghaosang.
+- Telegram: skip retries when inbound media `getFile` fails with Telegram's 20MB limit and continue processing message text, avoiding dropped messages for oversized attachments. (#18531) Thanks @brandonwise.
+- Telegram: clear stored polling offsets when bot tokens change or accounts are deleted, preventing stale offsets after token rotations. (#18233)
+- Auto-reply/TTS: keep tool-result media delivery enabled in group chats and native command sessions (while still suppressing tool summary text) so `NO_REPLY` follow-ups do not drop successful TTS audio. (#17991) Thanks @zerone0x.
+- Agents/Tools: deliver tool-result media even when verbose tool output is off so media attachments are not dropped. (#16679)
+- Discord: optimize reaction notification handling to skip unnecessary message fetches in `off`/`all`/`allowlist` modes, streamline reaction routing, and improve reaction emoji formatting. (#18248) Thanks @thewilloftheshadow and @victorGPT.
+- CLI/Pairing: make `openclaw qr --remote` prefer `gateway.remote.url` over tailscale/public URL resolution and register the `openclaw clawbot qr` legacy alias path. (#18091)
+- CLI/QR: restore fail-fast validation for `openclaw qr --remote` when neither `gateway.remote.url` nor tailscale `serve`/`funnel` is configured, preventing unusable remote pairing QR flows. (#18166) Thanks @mbelinky.
+- CLI/Doctor: ensure `openclaw doctor --fix --non-interactive --yes` exits promptly after completion so one-shot automation no longer hangs. (#18502)
+- CLI/Doctor: auto-repair `dmPolicy="open"` configs missing wildcard allowlists and write channel-correct repair paths (including `channels.googlechat.dm.allowFrom`) so `openclaw doctor --fix` no longer leaves Google Chat configs invalid after attempted repair. (#18544)
+- CLI/Doctor: detect gateway service token drift when the gateway token is only provided via environment variables, keeping service repairs aligned after token rotation.
+- CLI/Status: fix `openclaw status --all` token summaries for bot-token-only channels so Mattermost/Zalo no longer show a bot+app warning. (#18527) Thanks @echo931.
+- CLI/Configure: make the `/model picker` allowlist prompt searchable with tokenized matching in `openclaw configure` so users can filter huge model lists by typing terms like `gpt-5.2 openai/`. (#19010) Thanks @bjesuiter.
+- Voice Call: add an optional stale call reaper (`staleCallReaperSeconds`) to end stuck calls when enabled. (#18437)
+- Auto-reply/Subagents: propagate group context (`groupId`, `groupChannel`, `space`) when spawning via `/subagents spawn`, matching tool-triggered subagent spawn behavior.
+- Subagents: cap announce retry loops with max attempts and expiry to prevent infinite retry spam after deferred announces. (#18444)
+- Agents/Tools/exec: add a preflight guard that detects likely shell env var injection (e.g. `$DM_JSON`, `$TMPDIR`) in Python/Node scripts before execution, preventing recurring cron failures and wasted tokens when models emit mixed shell+language source. (#12836)
+- Agents/Tools/exec: treat normal non-zero exit codes as completed and append the exit code to tool output to avoid false tool-failure warnings. (#18425)
+- Agents/Tools: make loop detection progress-aware and phased by hard-blocking known `process(action=poll|log)` no-progress loops, warning on generic identical-call repeats, warning + no-progress-blocking ping-pong alternation loops (10/20), coalescing repeated warning spam into threshold buckets (including canonical ping-pong pairs), adding a global circuit breaker at 30 no-progress repeats, and emitting structured diagnostic `tool.loop` warning/error events for loop actions. (#16808) Thanks @akramcodez and @beca-oc.
+- Agents/Hooks: preserve the `before_tool_call` wrapped-marker across abort-signal tool wrapping so the hook runs once per tool call in normal agent sessions. (#16852) Thanks @sreuter.
+- Agents/Tools: scope the `message` tool schema to the active channel so Telegram uses `buttons` and Discord uses `components`. (#18215) Thanks @obviyus.
+- Agents/Image tool: replace Anthropic-incompatible union schema with explicit `image` (single) and `images` (multi) parameters, keeping tool schemas `anyOf`/`oneOf`/`allOf`-free while preserving multi-image analysis support. (#18551, #18566) Thanks @aldoeliacim.
+- Agents/Models: probe the primary model when its auth-profile cooldown is near expiry (with per-provider throttling), so runs recover from temporary rate limits without staying on fallback models until restart. (#17478) Thanks @PlayerGhost.
+- Agents/Failover: classify provider abort stop-reason errors (`Unhandled stop reason: abort`, `stop reason: abort`, `reason: abort`) as timeout-class failures so configured model fallback chains trigger instead of surfacing raw abort failures. (#18618) Thanks @sauerdaniel.
+- Models/CLI: sync auth-profiles credentials into agent `auth.json` before registry availability checks so `openclaw models list --all` reports auth correctly for API-key/token providers, normalize provider-id aliases when bridging credentials, and skip expired token mirrors. (#18610, #18615)
+- Agents/Context: raise default total bootstrap prompt cap from `24000` to `150000` chars (keeping `bootstrapMaxChars` at `20000`), include total-cap visibility in `/context`, and mark truncation from injected-vs-raw sizes so total-cap clipping is reflected accurately.
+- Memory/QMD: scope managed collection names per agent and precreate glob-backed collection directories before registration, preventing cross-agent collection clobbering and startup ENOENT failures in fresh workspaces. (#17194) Thanks @jonathanadams96.
+- Cron: preserve per-job schedule-error isolation in post-run maintenance recompute so malformed sibling jobs no longer abort persistence of successful runs. (#17852) Thanks @pierreeurope.
+- Gateway/Config: prevent `config.patch` object-array merges from falling back to full-array replacement when some patch entries lack `id`, so partial `agents.list` updates no longer drop unrelated agents. (#17989) Thanks @stakeswky.
+- Config/Discord: require string IDs in Discord allowlists, keep onboarding inputs string-only, and add doctor repair for numeric entries. (#18220) Thanks @thewilloftheshadow.
+- Security/Sessions: create new session transcript JSONL files with user-only (`0o600`) permissions and extend `openclaw security audit --fix` to remediate existing transcript file permissions.
+- Sessions/Maintenance: archive transcripts when pruning stale sessions, clean expired media in subdirectories, and purge `.deleted` transcript archives after the prune window to prevent disk leaks. (#18538)
+- Infra/Fetch: ensure foreign abort-signal listener cleanup never masks original fetch successes/failures, while still preventing detached-finally unhandled rejection noise in `wrapFetchWithAbortSignal`. Thanks @Jackten.
+- Heartbeat: allow suppressing tool error warning payloads during heartbeat runs via a new heartbeat config flag. (#18497) Thanks @thewilloftheshadow.
+- Heartbeat: include sender metadata (From/To/Provider) in heartbeat prompts so model context matches the delivery target. (#18532) Thanks @dinakars777.
+- Heartbeat/Telegram: strip configured `responsePrefix` before heartbeat ack detection (with boundary-safe matching) so prefixed `HEARTBEAT_OK` replies are correctly suppressed instead of leaking into DMs. (#18602)
+
+## 2026.2.15
+
+### Changes
+
+- Discord: unlock rich interactive agent prompts with Components v2 (buttons, selects, modals, and attachment-backed file blocks) so for native interaction through Discord. Thanks @thewilloftheshadow.
+- Discord: components v2 UI + embeds passthrough + exec approval UX refinements (CV2 containers, button layout, Discord-forwarding skip). Thanks @thewilloftheshadow.
+- Plugins: expose `llm_input` and `llm_output` hook payloads so extensions can observe prompt/input context and model output usage details. (#16724) Thanks @SecondThread.
+- Subagents: nested sub-agents (sub-sub-agents) with configurable depth. Set `agents.defaults.subagents.maxSpawnDepth: 2` to allow sub-agents to spawn their own children. Includes `maxChildrenPerAgent` limit (default 5), depth-aware tool policy, and proper announce chain routing. (#14447) Thanks @tyler6204.
+- Slack/Discord/Telegram: add per-channel ack reaction overrides (account/channel-level) to support platform-specific emoji formats. (#17092) Thanks @zerone0x.
+- Telegram: add `channel_post` inbound support for channel-based bot-to-bot wake/trigger flows, with channel allowlist gating and message/media batching parity.
+- Cron/Gateway: add finished-run webhook delivery toggle (`notify`) and dedicated webhook auth token support (`cron.webhookToken`) for outbound cron webhook posts. (#14535) Thanks @advaitpaliwal.
+- Channels: deduplicate probe/token resolution base types across core + extensions while preserving per-channel error typing. (#16986) Thanks @iyoda and @thewilloftheshadow.
+- Memory: add MMR (Maximal Marginal Relevance) re-ranking for hybrid search diversity. Configurable via `memorySearch.query.hybrid.mmr`. Thanks @rodrigouroz.
+- Memory: add opt-in temporal decay for hybrid search scoring, with configurable half-life via `memorySearch.query.hybrid.temporalDecay`. Thanks @rodrigouroz.
+
+### Fixes
+
+- Discord: send initial content when creating non-forum threads so `thread-create` content is delivered. (#18117) Thanks @zerone0x.
+- Security: replace deprecated SHA-1 sandbox configuration hashing with SHA-256 for deterministic sandbox cache identity and recreation checks. Thanks @kexinoh.
+- Security/Logging: redact Telegram bot tokens from error messages and uncaught stack traces to prevent accidental secret leakage into logs. Thanks @aether-ai-agent.
+- Sandbox/Security: block dangerous sandbox Docker config (bind mounts, host networking, unconfined seccomp/apparmor) to prevent container escape via config injection. Thanks @aether-ai-agent.
+- Sandbox: preserve array order in config hashing so order-sensitive Docker/browser settings trigger container recreation correctly. Thanks @kexinoh.
+- Gateway/Security: redact sensitive session/path details from `status` responses for non-admin clients; full details remain available to `operator.admin`. (#8590) Thanks @fr33d3m0n.
+- Gateway/Control UI: preserve requested operator scopes for Control UI bypass modes (`allowInsecureAuth` / `dangerouslyDisableDeviceAuth`) when device identity is unavailable, preventing false `missing scope` failures on authenticated LAN/HTTP operator sessions. (#17682) Thanks @leafbird.
+- LINE/Security: fail closed on webhook startup when channel token or channel secret is missing, and treat LINE accounts as configured only when both are present. (#17587) Thanks @davidahmann.
+- Skills/Security: restrict `download` installer `targetDir` to the per-skill tools directory to prevent arbitrary file writes. Thanks @Adam55A-code.
+- Skills/Linux: harden go installer fallback on apt-based systems by handling root/no-sudo environments safely, doing best-effort apt index refresh, and returning actionable errors instead of failing with spawn errors. (#17687) Thanks @mcrolly.
+- Web Fetch/Security: cap downloaded response body size before HTML parsing to prevent memory exhaustion from oversized or deeply nested pages. Thanks @xuemian168.
+- Config/Gateway: make sensitive-key whitelist suffix matching case-insensitive while preserving `passwordFile` path exemptions, preventing accidental redaction of non-secret config values like `maxTokens` and IRC password-file paths. (#16042) Thanks @akramcodez.
+- Dev tooling: harden git `pre-commit` hook against option injection from malicious filenames (for example `--force`), preventing accidental staging of ignored files. Thanks @mrthankyou.
+- Gateway/Agent: reject malformed `agent:`-prefixed session keys (for example, `agent:main`) in `agent` and `agent.identity.get` instead of silently resolving them to the default agent, preventing accidental cross-session routing. (#15707) Thanks @rodrigouroz.
+- Gateway/Chat: harden `chat.send` inbound message handling by rejecting null bytes, stripping unsafe control characters, and normalizing Unicode to NFC before dispatch. (#8593) Thanks @fr33d3m0n.
+- Gateway/Send: return an actionable error when `send` targets internal-only `webchat`, guiding callers to use `chat.send` or a deliverable channel. (#15703) Thanks @rodrigouroz.
+- Gateway/Commands: keep webchat command authorization on the internal `webchat` context instead of inferring another provider from channel allowlists, fixing dropped `/new`/`/status` commands in Control UI when channel allowlists are configured. (#7189) Thanks @karlisbergmanis-lv.
+- Control UI: prevent stored XSS via assistant name/avatar by removing inline script injection, serving bootstrap config as JSON, and enforcing `script-src 'self'`. Thanks @Adam55A-code.
+- Agents/Security: sanitize workspace paths before embedding into LLM prompts (strip Unicode control/format chars) to prevent instruction injection via malicious directory names. Thanks @aether-ai-agent.
+- Agents/Sandbox: clarify system prompt path guidance so sandbox `bash/exec` uses container paths (for example `/workspace`) while file tools keep host-bridge mapping, avoiding first-attempt path misses from host-only absolute paths in sandbox command execution. (#17693) Thanks @app/juniordevbot.
+- Agents/Context: apply configured model `contextWindow` overrides after provider discovery so `lookupContextTokens()` honors operator config values (including discovery-failure paths). (#17404) Thanks @michaelbship and @vignesh07.
+- Agents/Context: derive `lookupContextTokens()` from auth-available model metadata and keep the smallest discovered context window for duplicate model ids, preventing cross-provider cache collisions from overestimating session context limits. (#17586) Thanks @githabideri and @vignesh07.
+- Agents/OpenAI: force `store=true` for direct OpenAI Responses/Codex runs to preserve multi-turn server-side conversation state, while leaving proxy/non-OpenAI endpoints unchanged. (#16803) Thanks @mark9232 and @vignesh07.
+- Memory/FTS: make `buildFtsQuery` Unicode-aware so non-ASCII queries (including CJK) produce keyword tokens instead of falling back to vector-only search. (#17672) Thanks @KinGP5471.
+- Auto-reply/Compaction: resolve `memory/YYYY-MM-DD.md` placeholders with timezone-aware runtime dates and append a `Current time:` line to memory-flush turns, preventing wrong-year memory filenames without making the system prompt time-variant. (#17603, #17633) Thanks @nicholaspapadam-wq and @vignesh07.
+- Auth/Cooldowns: auto-expire stale auth profile cooldowns when `cooldownUntil` or `disabledUntil` timestamps have passed, and reset `errorCount` so the next transient failure does not immediately escalate to a disproportionately long cooldown. Handles `cooldownUntil` and `disabledUntil` independently. (#3604) Thanks @nabbilkhan.
+- Agents: return an explicit timeout error reply when an embedded run times out before producing any payloads, preventing silent dropped turns during slow cache-refresh transitions. (#16659) Thanks @liaosvcaf and @vignesh07.
 - Group chats: always inject group chat context (name, participants, reply guidance) into the system prompt on every turn, not just the first. Prevents the model from losing awareness of which group it's in and incorrectly using the message tool to send to the same group. (#14447) Thanks @tyler6204.
+- Browser/Agents: when browser control service is unavailable, return explicit non-retry guidance (instead of "try again") so models do not loop on repeated browser tool calls until timeout. (#17673) Thanks @austenstone.
+- Subagents: use child-run-based deterministic announce idempotency keys across direct and queued delivery paths (with legacy queued-item fallback) to prevent duplicate announce retries without collapsing distinct same-millisecond announces. (#17150) Thanks @widingmarcus-cyber.
+- Subagents/Models: preserve `agents.defaults.model.fallbacks` when subagent sessions carry a model override, so subagent runs fail over to configured fallback models instead of retrying only the overridden primary model.
+- Agents/Tools: scope the `message` tool schema to the active channel so Telegram uses `buttons` and Discord uses `components`. (#18215) Thanks @obviyus.
+- Telegram: omit `message_thread_id` for DM sends/draft previews and keep forum-topic handling (`id=1` general omitted, non-general kept), preventing DM failures with `400 Bad Request: message thread not found`. (#10942) Thanks @garnetlyx.
+- Telegram: replace inbound `<media:audio>` placeholder with successful preflight voice transcript in message body context, preventing placeholder-only prompt bodies for mention-gated voice messages. (#16789) Thanks @Limitless2023.
+- Telegram: retry inbound media `getFile` calls (3 attempts with backoff) and gracefully fall back to placeholder-only processing when retries fail, preventing dropped voice/media messages on transient Telegram network errors. (#16154) Thanks @yinghaosang.
+- Telegram: finalize streaming preview replies in place instead of sending a second final message, preventing duplicate Telegram assistant outputs at stream completion. (#17218) Thanks @obviyus.
+- Discord: preserve channel session continuity when runtime payloads omit `message.channelId` by falling back to event/raw `channel_id` values for routing/session keys, so same-channel messages keep history across turns/restarts. Also align diagnostics so active Discord runs no longer appear as `sessionKey=unknown`. (#17622) Thanks @shakkernerd.
+- Discord: dedupe native skill commands by skill name in multi-agent setups to prevent duplicated slash commands with `_2` suffixes. (#17365) Thanks @seewhyme.
+- Discord: ensure role allowlist matching uses raw role IDs for message routing authorization. Thanks @xinhuagu.
+- Discord: skip text-based exec approval forwarding in favor of Discord's component-based approval UI. Thanks @thewilloftheshadow.
+- Web UI/Agents: hide `BOOTSTRAP.md` in the Agents Files list after onboarding is completed, avoiding confusing missing-file warnings for completed workspaces. (#17491) Thanks @gumadeiras.
+- Memory/QMD: scope managed collection names per agent and precreate glob-backed collection directories before registration, preventing cross-agent collection clobbering and startup ENOENT failures in fresh workspaces. (#17194) Thanks @jonathanadams96.
+- Gateway/Memory: initialize QMD startup sync for every configured agent (not just the default agent), so `memory.qmd.update.onBoot` is effective across multi-agent setups. (#17663) Thanks @HenryLoenwind.
+- Auto-reply/WhatsApp/TUI/Web: when a final assistant message is `NO_REPLY` and a messaging tool send succeeded, mirror the delivered messaging-tool text into session-visible assistant output so TUI/Web no longer show `NO_REPLY` placeholders. (#7010) Thanks @Morrowind-Xie.
+- Cron: infer `payload.kind="agentTurn"` for model-only `cron.update` payload patches, so partial agent-turn updates do not fail validation when `kind` is omitted. (#15664) Thanks @rodrigouroz.
 - TUI: make searchable-select filtering and highlight rendering ANSI-aware so queries ignore hidden escape codes and no longer corrupt ANSI styling sequences during match highlighting. (#4519) Thanks @bee4come.
 - TUI/Windows: coalesce rapid single-line submit bursts in Git Bash into one multiline message as a fallback when bracketed paste is unavailable, preventing pasted multiline text from being split into multiple sends. (#4986) Thanks @adamkane.
 - TUI: suppress false `(no output)` placeholders for non-local empty final events during concurrent runs, preventing external-channel replies from showing empty assistant bubbles while a local run is still streaming. (#5782) Thanks @LagWizard and @vignesh07.
-- Auto-reply/WhatsApp/TUI/Web: when a final assistant message is `NO_REPLY` and a messaging tool send succeeded, mirror the delivered messaging-tool text into session-visible assistant output so TUI/Web no longer show `NO_REPLY` placeholders. (#7010) Thanks @Morrowind-Xie.
-- Gateway/Chat: harden `chat.send` inbound message handling by rejecting null bytes, stripping unsafe control characters, and normalizing Unicode to NFC before dispatch. (#8593) Thanks @fr33d3m0n.
-- Gateway/Security: redact sensitive session/path details from `status` responses for non-admin clients; full details remain available to `operator.admin`. (#8590) Thanks @fr33d3m0n.
-- Agents: return an explicit timeout error reply when an embedded run times out before producing any payloads, preventing silent dropped turns during slow cache-refresh transitions. (#16659) Thanks @liaosvcaf and @vignesh07.
-- Agents/OpenAI: force `store=true` for direct OpenAI Responses/Codex runs to preserve multi-turn server-side conversation state, while leaving proxy/non-OpenAI endpoints unchanged. (#16803) Thanks @mark9232 and @vignesh07.
+- TUI: preserve copy-sensitive long tokens (URLs/paths/file-like identifiers) during wrapping and overflow sanitization so wrapped output no longer inserts spaces that corrupt copy/paste values. (#17515, #17466, #17505) Thanks @abe238, @trevorpan, and @JasonCry.
 - CLI/Build: make legacy daemon CLI compatibility shim generation tolerant of minimal tsdown daemon export sets, while preserving restart/register compatibility aliases and surfacing explicit errors for unavailable legacy daemon commands. Thanks @vignesh07.
-- Telegram: replace inbound `<media:audio>` placeholder with successful preflight voice transcript in message body context, preventing placeholder-only prompt bodies for mention-gated voice messages. (#16789) Thanks @Limitless2023.
-- Telegram: retry inbound media `getFile` calls (3 attempts with backoff) and gracefully fall back to placeholder-only processing when retries fail, preventing dropped voice/media messages on transient Telegram network errors. (#16154) Thanks @yinghaosang.
 
 ## 2026.2.14
 
@@ -36,6 +165,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Security/Sessions/Telegram: restrict session tool targeting by default to the current session tree (`tools.sessions.visibility`, default `tree`) with sandbox clamping, and pass configured per-account Telegram webhook secrets in webhook mode when no explicit override is provided. Thanks @aether-ai-agent.
 - CLI/Plugins: ensure `openclaw message send` exits after successful delivery across plugin-backed channels so one-shot sends do not hang. (#16491) Thanks @yinghaosang.
 - CLI/Plugins: run registered plugin `gateway_stop` hooks before `openclaw message` exits (success and failure paths), so plugin-backed channels can clean up one-shot CLI resources. (#16580) Thanks @gumadeiras.
 - WhatsApp: honor per-account `dmPolicy` overrides (account-level settings now take precedence over channel defaults for inbound DMs). (#10082) Thanks @mcaxtr.
@@ -75,9 +205,11 @@ Docs: https://docs.openclaw.ai
 - Gateway/Subagents: preserve queued announce items and summary state on delivery errors, retry failed announce drains, and avoid dropping unsent announcements on timeout/failure. (#16729) Thanks @Clawdette-Workspace.
 - Gateway/Config: make `config.patch` merge object arrays by `id` (for example `agents.list`) instead of replacing the whole array, so partial agent updates do not silently delete unrelated agents. (#6766) Thanks @lightclient.
 - Webchat/Prompts: stop injecting direct-chat `conversation_label` into inbound untrusted metadata context blocks, preventing internal label noise from leaking into visible chat replies. (#16556) Thanks @nberardi.
+- Auto-reply/Prompts: include trusted inbound `message_id`, `chat_id`, `reply_to_id`, and optional `message_id_full` metadata fields so action tools (for example reactions) can target the triggering message without relying on user text. (#17662) Thanks @MaikiMolto.
 - Gateway/Sessions: abort active embedded runs and clear queued session work before `sessions.reset`, returning unavailable if the run does not stop in time. (#16576) Thanks @Grynn.
 - Sessions/Agents: harden transcript path resolution for mismatched agent context by preserving explicit store roots and adding safe absolute-path fallback to the correct agent sessions directory. (#16288) Thanks @robbyczgw-cla.
 - Agents: add a safety timeout around embedded `session.compact()` to ensure stalled compaction runs settle and release blocked session lanes. (#16331) Thanks @BinHPdev.
+- Agents/Tools: make required-parameter validation errors list missing fields and instruct: "Supply correct parameters before retrying," reducing repeated invalid tool-call loops (for example `read({})`). (#14729)
 - Agents: keep unresolved mutating tool failures visible until the same action retry succeeds, scope mutation-error surfacing to mutating calls (including `session_status` model changes), and dedupe duplicate failure warnings in outbound replies. (#16131) Thanks @Swader.
 - Agents/Process/Bootstrap: preserve unbounded `process log` offset-only pagination (default tail applies only when both `offset` and `limit` are omitted) and enforce strict `bootstrapTotalMaxChars` budgeting across injected bootstrap content (including markers), skipping additional injection when remaining budget is too small. (#16539) Thanks @CharlieGreenman.
 - Agents/Workspace: persist bootstrap onboarding state so partially initialized workspaces recover missing `BOOTSTRAP.md` once, while completed onboarding keeps BOOTSTRAP deleted even if runtime files are later recreated. Thanks @gumadeiras.
@@ -89,6 +221,7 @@ Docs: https://docs.openclaw.ai
 - Tools/Write/Edit: normalize structured text-block arguments for `content`/`oldText`/`newText` before filesystem edits, preventing JSON-like file corruption and false “exact text not found” misses from block-form params. (#16778) Thanks @danielpipernz.
 - Ollama/Agents: avoid forcing `<final>` tag enforcement for Ollama models, which could suppress all output as `(no output)`. (#16191) Thanks @Glucksberg.
 - Plugins: suppress false duplicate plugin id warnings when the same extension is discovered via multiple paths (config/workspace/global vs bundled), while still warning on genuine duplicates. (#16222) Thanks @shadril238.
+- Agents/Process: supervise PTY/child process lifecycles with explicit ownership, cancellation, timeouts, and deterministic cleanup, preventing Codex/Pi PTY sessions from dying or stalling on resume. (#14257) Thanks @onutc.
 - Skills: watch `SKILL.md` only when refreshing skills snapshot to avoid file-descriptor exhaustion in large data trees. (#11325) Thanks @household-bard.
 - Memory/QMD: make `memory status` read-only by skipping QMD boot update/embed side effects for status-only manager checks.
 - Memory/QMD: keep original QMD failures when builtin fallback initialization fails (for example missing embedding API keys), instead of replacing them with fallback init errors.
@@ -102,6 +235,7 @@ Docs: https://docs.openclaw.ai
 - Memory/QMD: make QMD result JSON parsing resilient to noisy command output by extracting the first JSON array from noisy `stdout`.
 - Memory/QMD: treat prefixed `no results found` marker output as an empty result set in qmd JSON parsing. (#11302) Thanks @blazerui.
 - Memory/QMD: avoid multi-collection `query` ranking corruption by running one `qmd query -c <collection>` per managed collection and merging by best score (also used for `search`/`vsearch` fallback-to-query). (#16740) Thanks @volarian-vai.
+- Memory/QMD: rebind managed collections when existing collection metadata drifts (including sessions name-only listings), preventing non-default agents from reusing another agent's `sessions` collection path. (#17194) Thanks @jonathanadams96.
 - Memory/QMD: make `openclaw memory index` verify and print the active QMD index file path/size, and fail when QMD leaves a missing or zero-byte index artifact after an update. (#16775) Thanks @Shunamxiao.
 - Memory/QMD: detect null-byte `ENOTDIR` update failures, rebuild managed collections once, and retry update to self-heal corrupted collection metadata. (#12919) Thanks @jorgejhms.
 - Memory/QMD/Security: add `rawKeyPrefix` support for QMD scope rules and preserve legacy `keyPrefix: "agent:..."` matching, preventing scoped deny bypass when operators match agent-prefixed session keys.
@@ -118,6 +252,8 @@ Docs: https://docs.openclaw.ai
 - Sandbox/Prompts: show the sandbox container workdir as the prompt working directory and clarify host-path usage for file tools, preventing host-path `exec` failures in sandbox sessions. (#16790) Thanks @carrotRakko.
 - Media/Security: allow local media reads from OpenClaw state `workspace/` and `sandboxes/` roots by default so generated workspace media can be delivered without unsafe global path bypasses. (#15541) Thanks @lanceji.
 - Media/Security: harden local media allowlist bypasses by requiring an explicit `readFile` override when callers mark paths as validated, and reject filesystem-root `localRoots` entries. (#16739)
+- Media/Security: allow outbound local media reads from the active agent workspace (including `workspace-<agentId>`) via agent-scoped local roots, avoiding broad global allowlisting of all per-agent workspaces. (#17136) Thanks @MisterGuy420.
+- Outbound/Media: thread explicit `agentId` through core `sendMessage` direct-delivery path so agent-scoped local media roots apply even when mirror metadata is absent. (#17268) Thanks @gumadeiras.
 - Discord/Security: harden voice message media loading (SSRF + allowed-local-root checks) so tool-supplied paths/URLs cannot be used to probe internal URLs or read arbitrary local files.
 - Security/BlueBubbles: require explicit `mediaLocalRoots` allowlists for local outbound media path reads to prevent local file disclosure. (#16322) Thanks @mbelinky.
 - Security/BlueBubbles: reject ambiguous shared-path webhook routing when multiple webhook targets match the same guid/password.
@@ -133,6 +269,7 @@ Docs: https://docs.openclaw.ai
 - Security/Media: stream and bound URL-backed input media fetches to prevent memory exhaustion from oversized responses. Thanks @vincentkoc.
 - Security/Skills: harden archive extraction for download-installed skills to prevent path traversal outside the target directory. Thanks @markmusson.
 - Security/Slack: compute command authorization for DM slash commands even when `dmPolicy=open`, preventing unauthorized users from running privileged commands via DM. Thanks @christos-eth.
+- Security/Pairing: scope pairing allowlist writes/reads to channel accounts (for example `telegram:yy`), and propagate account-aware pairing approvals so multi-account channels do not share a single per-channel pairing allowFrom store. (#17631) Thanks @crazytan.
 - Security/iMessage: keep DM pairing-store identities out of group allowlist authorization (prevents cross-context command authorization). Thanks @vincentkoc.
 - Security/Google Chat: deprecate `users/<email>` allowlists (treat `users/...` as immutable user id only); keep raw email allowlists for usability. Thanks @vincentkoc.
 - Security/Google Chat: reject ambiguous shared-path webhook routing when multiple webhook targets verify successfully (prevents cross-account policy-context misrouting). Thanks @vincentkoc.
@@ -188,6 +325,7 @@ Docs: https://docs.openclaw.ai
 - Docs/Hooks: update hooks documentation URLs to the new `/automation/hooks` location. (#16165) Thanks @nicholascyh.
 - Security/Audit: warn when `gateway.tools.allow` re-enables default-denied tools over HTTP `POST /tools/invoke`, since this can increase RCE blast radius if the gateway is reachable.
 - Security/Plugins/Hooks: harden npm-based installs by restricting specs to registry packages only, passing `--ignore-scripts` to `npm pack`, and cleaning up temp install directories.
+- Security/Sessions: preserve inter-session input provenance for routed prompts so delegated/internal sessions are not treated as direct external user instructions. Thanks @anbecker.
 - Feishu: stop persistent Typing reaction on NO_REPLY/suppressed runs by wiring reply-dispatcher cleanup to remove typing indicators. (#15464) Thanks @arosstale.
 - Agents: strip leading empty lines from `sanitizeUserFacingText` output and normalize whitespace-only outputs to empty text. (#16158) Thanks @mcinteerj.
 - BlueBubbles: gracefully degrade when Private API is disabled by filtering private-only actions, skipping private-only reactions/reply effects, and avoiding private reply markers so non-private flows remain usable. (#16002) Thanks @L-U-C-K-Y.
@@ -318,6 +456,7 @@ Docs: https://docs.openclaw.ai
 - Configure/Gateway: reject literal `"undefined"`/`"null"` token input and validate gateway password prompt values to avoid invalid password-mode configs. (#13767) Thanks @omair445.
 - Gateway: handle async `EPIPE` on stdout/stderr during shutdown. (#13414) Thanks @keshav55.
 - Gateway/Control UI: resolve missing dashboard assets when `openclaw` is installed globally via symlink-based Node managers (nvm/fnm/n/Homebrew). (#14919) Thanks @aynorica.
+- Gateway/Control UI: keep partial assistant output visible when runs are aborted, and persist aborted partials to session transcripts for follow-up context.
 - Cron: use requested `agentId` for isolated job auth resolution. (#13983) Thanks @0xRaini.
 - Cron: prevent cron jobs from skipping execution when `nextRunAtMs` advances. (#14068) Thanks @WalterSumbon.
 - Cron: pass `agentId` to `runHeartbeatOnce` for main-session jobs. (#14140) Thanks @ishikawa-pro.
@@ -347,6 +486,7 @@ Docs: https://docs.openclaw.ai
 - Browser: add Chrome launch flag `--disable-blink-features=AutomationControlled` to reduce `navigator.webdriver` automation detection issues on reCAPTCHA-protected sites. (#10735) Thanks @Milofax.
 - Heartbeat: filter noise-only system events so scheduled reminder notifications do not fire when cron runs carry only heartbeat markers. (#13317) Thanks @pvtclawn.
 - Signal: render mention placeholders as `@uuid`/`@phone` so mention gating and Clawdbot targeting work. (#2013) Thanks @alexgleason.
+- Agents/Reminders: guard reminder promises by appending a note when no `cron.add` succeeded in the turn, so users know nothing was scheduled. (#18588) Thanks @vignesh07.
 - Discord: omit empty content fields for media-only messages while preserving caption whitespace. (#9507) Thanks @leszekszpunar.
 - Onboarding/Providers: add Z.AI endpoint-specific auth choices (`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`) and expand default Z.AI model wiring. (#13456) Thanks @tomsun28.
 - Onboarding/Providers: update MiniMax API default/recommended models from M2.1 to M2.5, add M2.5/M2.5-Lightning model entries, and include `minimax-m2.5` in modern model filtering. (#14865) Thanks @adao-max.
@@ -390,6 +530,7 @@ Docs: https://docs.openclaw.ai
 
 - Commands: add `commands.allowFrom` config for separate command authorization, allowing operators to restrict slash commands to specific users while keeping chat open to others. (#12430) Thanks @thewilloftheshadow.
 - Docker: add ClawDock shell helpers for Docker workflows. (#12817) Thanks @Olshansk.
+- Gateway: periodic channel health monitor auto-restarts stuck, crashed, or silently-stopped channels. Configurable via `gateway.channelHealthCheckMinutes` (default: 5, set to 0 to disable). (#7053, #4302)
 - iOS: alpha node app + setup-code onboarding. (#11756) Thanks @mbelinky.
 - Channels: comprehensive BlueBubbles and channel cleanup. (#11093) Thanks @tyler6204.
 - Channels: IRC first-class channel support. (#11482) Thanks @vignesh07.
@@ -453,6 +594,7 @@ Docs: https://docs.openclaw.ai
 - Thinking: allow xhigh for `github-copilot/gpt-5.2-codex` and `github-copilot/gpt-5.2`. (#11646) Thanks @LatencyTDH.
 - Thinking: honor `/think off` for reasoning-capable models. (#9564) Thanks @liuy.
 - Discord: support forum/media thread-create starter messages, wire `message thread create --message`, and harden routing. (#10062) Thanks @jarvis89757.
+- Discord: download attachments from forwarded messages. (#17049) Thanks @pip-nomel, @thewilloftheshadow.
 - Paths: structurally resolve `OPENCLAW_HOME`-derived home paths and fix Windows drive-letter handling in tool meta shortening. (#12125) Thanks @mcaxtr.
 - Memory: set Voyage embeddings `input_type` for improved retrieval. (#10818) Thanks @mcinteerj.
 - Memory: disable async batch embeddings by default for memory indexing (opt-in via `agents.defaults.memorySearch.remote.batch.enabled`). (#13069) Thanks @mcinteerj.

CONTRIBUTING.md

@@ -13,24 +13,33 @@ Welcome to the lobster tank! 🦞
 - **Peter Steinberger** - Benevolent Dictator
   - GitHub: [@steipete](https://github.com/steipete) · X: [@steipete](https://x.com/steipete)
 
-- **Shadow** - Discord + Slack subsystem
+- **Shadow** - Discord subsystem, Discord admin
   - GitHub: [@thewilloftheshadow](https://github.com/thewilloftheshadow) · X: [@4shad0wed](https://x.com/4shad0wed)
 
-- **Vignesh** - Memory (QMD), formal modeling, TUI, and Lobster
+- **Vignesh** - Memory (QMD), formal modeling, TUI, IRC, and Lobster
   - GitHub: [@vignesh07](https://github.com/vignesh07) · X: [@\_vgnsh](https://x.com/_vgnsh)
 
 - **Jos** - Telegram, API, Nix mode
   - GitHub: [@joshp123](https://github.com/joshp123) · X: [@jjpcodes](https://x.com/jjpcodes)
 
+- **Ayaan Zaidi** - Telegram subsystem, iOS app
+  - GitHub: [@obviyus](https://github.com/obviyus) · X: [@0bviyus](https://x.com/0bviyus)
+
+- **Tyler Yust** - Agents/subagents, cron, BlueBubbles, macOS app
+  - GitHub: [@tyler6204](https://github.com/tyler6204) · X: [@tyleryust](https://x.com/tyleryust)
+
+- **Mariano Belinky** - iOS app, Security
+  - GitHub: [@mbelinky](https://github.com/mbelinky) · X: [@belimad](https://x.com/belimad)
+
+- **Seb Slight** - Docs, Agent Reliability, Runtime Hardening
+  - GitHub: [@sebslight](https://github.com/sebslight) · X: [@sebslig](https://x.com/sebslig)
+
 - **Christoph Nakazawa** - JS Infra
   - GitHub: [@cpojer](https://github.com/cpojer) · X: [@cnakazawa](https://x.com/cnakazawa)
 
 - **Gustavo Madeira Santana** - Multi-agents, CLI, web UI
   - GitHub: [@gumadeiras](https://github.com/gumadeiras) · X: [@gumadeiras](https://x.com/gumadeiras)
 
-- **Maximilian Nussbaumer** - DevOps, CI, Code Sanity
-  - GitHub: [@quotentiroler](https://github.com/quotentiroler) · X: [@quotentiroler](https://x.com/quotentiroler)
-
 ## How to Contribute
 
 1. **Bugs & small fixes** → Open a PR!

Dockerfile

@@ -23,6 +23,19 @@ COPY scripts ./scripts
 
 RUN pnpm install --frozen-lockfile
 
+# Optionally install Chromium and Xvfb for browser automation.
+# Build with: docker build --build-arg OPENCLAW_INSTALL_BROWSER=1 ...
+# Adds ~300MB but eliminates the 60-90s Playwright install on every container start.
+# Must run after pnpm install so playwright-core is available in node_modules.
+ARG OPENCLAW_INSTALL_BROWSER=""
+RUN if [ -n "$OPENCLAW_INSTALL_BROWSER" ]; then \
+      apt-get update && \
+      DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends xvfb && \
+      node /app/node_modules/playwright-core/cli.js install --with-deps chromium && \
+      apt-get clean && \
+      rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*; \
+    fi
+
 COPY . .
 RUN pnpm build
 # Force pnpm for UI build (Bun may fail on ARM/Synology architectures)

README.md

@@ -267,6 +267,7 @@ ClawHub is a minimal skill registry. With ClawHub enabled, the agent can search
 Send these in WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat (group commands are owner-only):
 
 - `/status` — compact session status (model + tokens, cost when available)
+- `/mesh <goal>` — auto-plan + run a multi-step workflow (`/mesh plan|run|status|retry` available)
 - `/new` or `/reset` — reset the session
 - `/compact` — compact session context (summary)
 - `/think <level>` — off|minimal|low|medium|high|xhigh (GPT-5.2 + Codex models only)
@@ -303,6 +304,7 @@ Runbook: [iOS connect](https://docs.openclaw.ai/platforms/ios).
 - Pairs via the same Bridge + pairing flow as iOS.
 - Exposes Canvas, Camera, and Screen capture commands.
 - Runbook: [Android connect](https://docs.openclaw.ai/platforms/android).
+- Install: [OpenClaw for Android](https://github.com/irtiq7/OpenClaw-Android).
 
 ## Agent workspace + skills
 
@@ -546,4 +548,5 @@ Thanks to all clawtributors:
   <a href="https://github.com/0xJonHoldsCrypto"><img src="https://avatars.githubusercontent.com/u/81202085?v=4&s=48" width="48" height="48" alt="0xJonHoldsCrypto" title="0xJonHoldsCrypto"/></a> <a href="https://github.com/aaronn"><img src="https://avatars.githubusercontent.com/u/1653630?v=4&s=48" width="48" height="48" alt="aaronn" title="aaronn"/></a> <a href="https://github.com/Alphonse-arianee"><img src="https://avatars.githubusercontent.com/u/254457365?v=4&s=48" width="48" height="48" alt="Alphonse-arianee" title="Alphonse-arianee"/></a> <a href="https://github.com/atalovesyou"><img src="https://avatars.githubusercontent.com/u/3534502?v=4&s=48" width="48" height="48" alt="atalovesyou" title="atalovesyou"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/jiulingyun"><img src="https://avatars.githubusercontent.com/u/126459548?v=4&s=48" width="48" height="48" alt="jiulingyun" title="jiulingyun"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a>
   <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/odrobnik"><img src="https://avatars.githubusercontent.com/u/333270?v=4&s=48" width="48" height="48" alt="odrobnik" title="odrobnik"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/rhjoh"><img src="https://avatars.githubusercontent.com/u/105699450?v=4&s=48" width="48" height="48" alt="rhjoh" title="rhjoh"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a>
   <a href="https://github.com/ronak-guliani"><img src="https://avatars.githubusercontent.com/u/23518228?v=4&s=48" width="48" height="48" alt="ronak-guliani" title="ronak-guliani"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
+     <a href="https://github.com/AkashKobal"><img src="https://avatars.githubusercontent.com/u/98216083?v=4" width="48" height="48" alt="Akash Kobal" title="Akash Kobal"/></a>
 </p>

appcast.xml

@@ -140,6 +140,74 @@
 ]]></description>
             <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.14/OpenClaw-2026.2.14.zip" length="22914034" type="application/octet-stream" sparkle:edSignature="lR3nuq46/akMIN8RFDpMkTE0VOVoDVG53Xts589LryMGEtUvJxRQDtHBXfx7ZvToTq6CFKG+L5Kq/4rUspMoAQ=="/>
         </item>
+        <item>
+            <title>2026.2.15</title>
+            <pubDate>Mon, 16 Feb 2026 05:04:34 +0100</pubDate>
+            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
+            <sparkle:version>202602150</sparkle:version>
+            <sparkle:shortVersionString>2026.2.15</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>OpenClaw 2026.2.15</h2>
+<h3>Changes</h3>
+<ul>
+<li>Discord: unlock rich interactive agent prompts with Components v2 (buttons, selects, modals, and attachment-backed file blocks) so for native interaction through Discord. Thanks @thewilloftheshadow.</li>
+<li>Discord: components v2 UI + embeds passthrough + exec approval UX refinements (CV2 containers, button layout, Discord-forwarding skip). Thanks @thewilloftheshadow.</li>
+<li>Plugins: expose <code>llm_input</code> and <code>llm_output</code> hook payloads so extensions can observe prompt/input context and model output usage details. (#16724) Thanks @SecondThread.</li>
+<li>Subagents: nested sub-agents (sub-sub-agents) with configurable depth. Set <code>agents.defaults.subagents.maxSpawnDepth: 2</code> to allow sub-agents to spawn their own children. Includes <code>maxChildrenPerAgent</code> limit (default 5), depth-aware tool policy, and proper announce chain routing. (#14447) Thanks @tyler6204.</li>
+<li>Slack/Discord/Telegram: add per-channel ack reaction overrides (account/channel-level) to support platform-specific emoji formats. (#17092) Thanks @zerone0x.</li>
+<li>Cron/Gateway: add finished-run webhook delivery toggle (<code>notify</code>) and dedicated webhook auth token support (<code>cron.webhookToken</code>) for outbound cron webhook posts. (#14535) Thanks @advaitpaliwal.</li>
+<li>Channels: deduplicate probe/token resolution base types across core + extensions while preserving per-channel error typing. (#16986) Thanks @iyoda and @thewilloftheshadow.</li>
+</ul>
+<h3>Fixes</h3>
+<ul>
+<li>Security: replace deprecated SHA-1 sandbox configuration hashing with SHA-256 for deterministic sandbox cache identity and recreation checks. Thanks @kexinoh.</li>
+<li>Security/Logging: redact Telegram bot tokens from error messages and uncaught stack traces to prevent accidental secret leakage into logs. Thanks @aether-ai-agent.</li>
+<li>Sandbox/Security: block dangerous sandbox Docker config (bind mounts, host networking, unconfined seccomp/apparmor) to prevent container escape via config injection. Thanks @aether-ai-agent.</li>
+<li>Sandbox: preserve array order in config hashing so order-sensitive Docker/browser settings trigger container recreation correctly. Thanks @kexinoh.</li>
+<li>Gateway/Security: redact sensitive session/path details from <code>status</code> responses for non-admin clients; full details remain available to <code>operator.admin</code>. (#8590) Thanks @fr33d3m0n.</li>
+<li>Gateway/Control UI: preserve requested operator scopes for Control UI bypass modes (<code>allowInsecureAuth</code> / <code>dangerouslyDisableDeviceAuth</code>) when device identity is unavailable, preventing false <code>missing scope</code> failures on authenticated LAN/HTTP operator sessions. (#17682) Thanks @leafbird.</li>
+<li>LINE/Security: fail closed on webhook startup when channel token or channel secret is missing, and treat LINE accounts as configured only when both are present. (#17587) Thanks @davidahmann.</li>
+<li>Skills/Security: restrict <code>download</code> installer <code>targetDir</code> to the per-skill tools directory to prevent arbitrary file writes. Thanks @Adam55A-code.</li>
+<li>Skills/Linux: harden go installer fallback on apt-based systems by handling root/no-sudo environments safely, doing best-effort apt index refresh, and returning actionable errors instead of failing with spawn errors. (#17687) Thanks @mcrolly.</li>
+<li>Web Fetch/Security: cap downloaded response body size before HTML parsing to prevent memory exhaustion from oversized or deeply nested pages. Thanks @xuemian168.</li>
+<li>Config/Gateway: make sensitive-key whitelist suffix matching case-insensitive while preserving <code>passwordFile</code> path exemptions, preventing accidental redaction of non-secret config values like <code>maxTokens</code> and IRC password-file paths. (#16042) Thanks @akramcodez.</li>
+<li>Dev tooling: harden git <code>pre-commit</code> hook against option injection from malicious filenames (for example <code>--force</code>), preventing accidental staging of ignored files. Thanks @mrthankyou.</li>
+<li>Gateway/Agent: reject malformed <code>agent:</code>-prefixed session keys (for example, <code>agent:main</code>) in <code>agent</code> and <code>agent.identity.get</code> instead of silently resolving them to the default agent, preventing accidental cross-session routing. (#15707) Thanks @rodrigouroz.</li>
+<li>Gateway/Chat: harden <code>chat.send</code> inbound message handling by rejecting null bytes, stripping unsafe control characters, and normalizing Unicode to NFC before dispatch. (#8593) Thanks @fr33d3m0n.</li>
+<li>Gateway/Send: return an actionable error when <code>send</code> targets internal-only <code>webchat</code>, guiding callers to use <code>chat.send</code> or a deliverable channel. (#15703) Thanks @rodrigouroz.</li>
+<li>Control UI: prevent stored XSS via assistant name/avatar by removing inline script injection, serving bootstrap config as JSON, and enforcing <code>script-src 'self'</code>. Thanks @Adam55A-code.</li>
+<li>Agents/Security: sanitize workspace paths before embedding into LLM prompts (strip Unicode control/format chars) to prevent instruction injection via malicious directory names. Thanks @aether-ai-agent.</li>
+<li>Agents/Sandbox: clarify system prompt path guidance so sandbox <code>bash/exec</code> uses container paths (for example <code>/workspace</code>) while file tools keep host-bridge mapping, avoiding first-attempt path misses from host-only absolute paths in sandbox command execution. (#17693) Thanks @app/juniordevbot.</li>
+<li>Agents/Context: apply configured model <code>contextWindow</code> overrides after provider discovery so <code>lookupContextTokens()</code> honors operator config values (including discovery-failure paths). (#17404) Thanks @michaelbship and @vignesh07.</li>
+<li>Agents/Context: derive <code>lookupContextTokens()</code> from auth-available model metadata and keep the smallest discovered context window for duplicate model ids, preventing cross-provider cache collisions from overestimating session context limits. (#17586) Thanks @githabideri and @vignesh07.</li>
+<li>Agents/OpenAI: force <code>store=true</code> for direct OpenAI Responses/Codex runs to preserve multi-turn server-side conversation state, while leaving proxy/non-OpenAI endpoints unchanged. (#16803) Thanks @mark9232 and @vignesh07.</li>
+<li>Memory/FTS: make <code>buildFtsQuery</code> Unicode-aware so non-ASCII queries (including CJK) produce keyword tokens instead of falling back to vector-only search. (#17672) Thanks @KinGP5471.</li>
+<li>Auto-reply/Compaction: resolve <code>memory/YYYY-MM-DD.md</code> placeholders with timezone-aware runtime dates and append a <code>Current time:</code> line to memory-flush turns, preventing wrong-year memory filenames without making the system prompt time-variant. (#17603, #17633) Thanks @nicholaspapadam-wq and @vignesh07.</li>
+<li>Agents: return an explicit timeout error reply when an embedded run times out before producing any payloads, preventing silent dropped turns during slow cache-refresh transitions. (#16659) Thanks @liaosvcaf and @vignesh07.</li>
+<li>Group chats: always inject group chat context (name, participants, reply guidance) into the system prompt on every turn, not just the first. Prevents the model from losing awareness of which group it's in and incorrectly using the message tool to send to the same group. (#14447) Thanks @tyler6204.</li>
+<li>Browser/Agents: when browser control service is unavailable, return explicit non-retry guidance (instead of "try again") so models do not loop on repeated browser tool calls until timeout. (#17673) Thanks @austenstone.</li>
+<li>Subagents: use child-run-based deterministic announce idempotency keys across direct and queued delivery paths (with legacy queued-item fallback) to prevent duplicate announce retries without collapsing distinct same-millisecond announces. (#17150) Thanks @widingmarcus-cyber.</li>
+<li>Subagents/Models: preserve <code>agents.defaults.model.fallbacks</code> when subagent sessions carry a model override, so subagent runs fail over to configured fallback models instead of retrying only the overridden primary model.</li>
+<li>Telegram: omit <code>message_thread_id</code> for DM sends/draft previews and keep forum-topic handling (<code>id=1</code> general omitted, non-general kept), preventing DM failures with <code>400 Bad Request: message thread not found</code>. (#10942) Thanks @garnetlyx.</li>
+<li>Telegram: replace inbound <code><media:audio></code> placeholder with successful preflight voice transcript in message body context, preventing placeholder-only prompt bodies for mention-gated voice messages. (#16789) Thanks @Limitless2023.</li>
+<li>Telegram: retry inbound media <code>getFile</code> calls (3 attempts with backoff) and gracefully fall back to placeholder-only processing when retries fail, preventing dropped voice/media messages on transient Telegram network errors. (#16154) Thanks @yinghaosang.</li>
+<li>Telegram: finalize streaming preview replies in place instead of sending a second final message, preventing duplicate Telegram assistant outputs at stream completion. (#17218) Thanks @obviyus.</li>
+<li>Discord: preserve channel session continuity when runtime payloads omit <code>message.channelId</code> by falling back to event/raw <code>channel_id</code> values for routing/session keys, so same-channel messages keep history across turns/restarts. Also align diagnostics so active Discord runs no longer appear as <code>sessionKey=unknown</code>. (#17622) Thanks @shakkernerd.</li>
+<li>Discord: dedupe native skill commands by skill name in multi-agent setups to prevent duplicated slash commands with <code>_2</code> suffixes. (#17365) Thanks @seewhyme.</li>
+<li>Discord: ensure role allowlist matching uses raw role IDs for message routing authorization. Thanks @xinhuagu.</li>
+<li>Web UI/Agents: hide <code>BOOTSTRAP.md</code> in the Agents Files list after onboarding is completed, avoiding confusing missing-file warnings for completed workspaces. (#17491) Thanks @gumadeiras.</li>
+<li>Auto-reply/WhatsApp/TUI/Web: when a final assistant message is <code>NO_REPLY</code> and a messaging tool send succeeded, mirror the delivered messaging-tool text into session-visible assistant output so TUI/Web no longer show <code>NO_REPLY</code> placeholders. (#7010) Thanks @Morrowind-Xie.</li>
+<li>Cron: infer <code>payload.kind="agentTurn"</code> for model-only <code>cron.update</code> payload patches, so partial agent-turn updates do not fail validation when <code>kind</code> is omitted. (#15664) Thanks @rodrigouroz.</li>
+<li>TUI: make searchable-select filtering and highlight rendering ANSI-aware so queries ignore hidden escape codes and no longer corrupt ANSI styling sequences during match highlighting. (#4519) Thanks @bee4come.</li>
+<li>TUI/Windows: coalesce rapid single-line submit bursts in Git Bash into one multiline message as a fallback when bracketed paste is unavailable, preventing pasted multiline text from being split into multiple sends. (#4986) Thanks @adamkane.</li>
+<li>TUI: suppress false <code>(no output)</code> placeholders for non-local empty final events during concurrent runs, preventing external-channel replies from showing empty assistant bubbles while a local run is still streaming. (#5782) Thanks @LagWizard and @vignesh07.</li>
+<li>TUI: preserve copy-sensitive long tokens (URLs/paths/file-like identifiers) during wrapping and overflow sanitization so wrapped output no longer inserts spaces that corrupt copy/paste values. (#17515, #17466, #17505) Thanks @abe238, @trevorpan, and @JasonCry.</li>
+<li>CLI/Build: make legacy daemon CLI compatibility shim generation tolerant of minimal tsdown daemon export sets, while preserving restart/register compatibility aliases and surfacing explicit errors for unavailable legacy daemon commands. Thanks @vignesh07.</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.2.15/OpenClaw-2026.2.15.zip" length="22896513" type="application/octet-stream" sparkle:edSignature="MLGsd2NeHXFRH1Or0bFQnAjqfuuJDuhl1mvKFIqTQcRvwbeyvOyyLXrqSbmaOgJR3wBQBKLs6jYQ9dQ/3R8RCg=="/>
+        </item>
         <item>
             <title>2026.2.13</title>
             <pubDate>Sat, 14 Feb 2026 04:30:23 +0100</pubDate>
@@ -241,101 +309,5 @@
 ]]></description>
             <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.13/OpenClaw-2026.2.13.zip" length="22902077" type="application/octet-stream" sparkle:edSignature="RpkwlPtB2yN7UOYZWfthV5grhDUcbhcHMeicdRA864Vo/P0Hnq5aHKmSvcbWkjHut96TC57bX+AeUrL7txpLCg=="/>
         </item>
-        <item>
-            <title>2026.2.12</title>
-            <pubDate>Fri, 13 Feb 2026 03:17:54 +0100</pubDate>
-            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
-            <sparkle:version>9500</sparkle:version>
-            <sparkle:shortVersionString>2026.2.12</sparkle:shortVersionString>
-            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>OpenClaw 2026.2.12</h2>
-<h3>Changes</h3>
-<ul>
-<li>CLI: add <code>openclaw logs --local-time</code> to display log timestamps in local timezone. (#13818) Thanks @xialonglee.</li>
-<li>Telegram: render blockquotes as native <code><blockquote></code> tags instead of stripping them. (#14608)</li>
-<li>Config: avoid redacting <code>maxTokens</code>-like fields during config snapshot redaction, preventing round-trip validation failures in <code>/config</code>. (#14006) Thanks @constansino.</li>
-</ul>
-<h3>Breaking</h3>
-<ul>
-<li>Hooks: <code>POST /hooks/agent</code> now rejects payload <code>sessionKey</code> overrides by default. To keep fixed hook context, set <code>hooks.defaultSessionKey</code> (recommended with <code>hooks.allowedSessionKeyPrefixes: ["hook:"]</code>). If you need legacy behavior, explicitly set <code>hooks.allowRequestSessionKey: true</code>. Thanks @alpernae for reporting.</li>
-</ul>
-<h3>Fixes</h3>
-<ul>
-<li>Gateway/OpenResponses: harden URL-based <code>input_file</code>/<code>input_image</code> handling with explicit SSRF deny policy, hostname allowlists (<code>files.urlAllowlist</code> / <code>images.urlAllowlist</code>), per-request URL input caps (<code>maxUrlParts</code>), blocked-fetch audit logging, and regression coverage/docs updates.</li>
-<li>Security: fix unauthenticated Nostr profile API remote config tampering. (#13719) Thanks @coygeek.</li>
-<li>Security: remove bundled soul-evil hook. (#14757) Thanks @Imccccc.</li>
-<li>Security/Audit: add hook session-routing hardening checks (<code>hooks.defaultSessionKey</code>, <code>hooks.allowRequestSessionKey</code>, and prefix allowlists), and warn when HTTP API endpoints allow explicit session-key routing.</li>
-<li>Security/Sandbox: confine mirrored skill sync destinations to the sandbox <code>skills/</code> root and stop using frontmatter-controlled skill names as filesystem destination paths. Thanks @1seal.</li>
-<li>Security/Web tools: treat browser/web content as untrusted by default (wrapped outputs for browser snapshot/tabs/console and structured external-content metadata for web tools), and strip <code>toolResult.details</code> from model-facing transcript/compaction inputs to reduce prompt-injection replay risk.</li>
-<li>Security/Hooks: harden webhook and device token verification with shared constant-time secret comparison, and add per-client auth-failure throttling for hook endpoints (<code>429</code> + <code>Retry-After</code>). Thanks @akhmittra.</li>
-<li>Security/Browser: require auth for loopback browser control HTTP routes, auto-generate <code>gateway.auth.token</code> when browser control starts without auth, and add a security-audit check for unauthenticated browser control. Thanks @tcusolle.</li>
-<li>Sessions/Gateway: harden transcript path resolution and reject unsafe session IDs/file paths so session operations stay within agent sessions directories. Thanks @akhmittra.</li>
-<li>Gateway: raise WS payload/buffer limits so 5,000,000-byte image attachments work reliably. (#14486) Thanks @0xRaini.</li>
-<li>Logging/CLI: use local timezone timestamps for console prefixing, and include <code>±HH:MM</code> offsets when using <code>openclaw logs --local-time</code> to avoid ambiguity. (#14771) Thanks @0xRaini.</li>
-<li>Gateway: drain active turns before restart to prevent message loss. (#13931) Thanks @0xRaini.</li>
-<li>Gateway: auto-generate auth token during install to prevent launchd restart loops. (#13813) Thanks @cathrynlavery.</li>
-<li>Gateway: prevent <code>undefined</code>/missing token in auth config. (#13809) Thanks @asklee-klawd.</li>
-<li>Gateway: handle async <code>EPIPE</code> on stdout/stderr during shutdown. (#13414) Thanks @keshav55.</li>
-<li>Gateway/Control UI: resolve missing dashboard assets when <code>openclaw</code> is installed globally via symlink-based Node managers (nvm/fnm/n/Homebrew). (#14919) Thanks @aynorica.</li>
-<li>Cron: use requested <code>agentId</code> for isolated job auth resolution. (#13983) Thanks @0xRaini.</li>
-<li>Cron: prevent cron jobs from skipping execution when <code>nextRunAtMs</code> advances. (#14068) Thanks @WalterSumbon.</li>
-<li>Cron: pass <code>agentId</code> to <code>runHeartbeatOnce</code> for main-session jobs. (#14140) Thanks @ishikawa-pro.</li>
-<li>Cron: re-arm timers when <code>onTimer</code> fires while a job is still executing. (#14233) Thanks @tomron87.</li>
-<li>Cron: prevent duplicate fires when multiple jobs trigger simultaneously. (#14256) Thanks @xinhuagu.</li>
-<li>Cron: isolate scheduler errors so one bad job does not break all jobs. (#14385) Thanks @MarvinDontPanic.</li>
-<li>Cron: prevent one-shot <code>at</code> jobs from re-firing on restart after skipped/errored runs. (#13878) Thanks @lailoo.</li>
-<li>Heartbeat: prevent scheduler stalls on unexpected run errors and avoid immediate rerun loops after <code>requests-in-flight</code> skips. (#14901) Thanks @joeykrug.</li>
-<li>Cron: honor stored session model overrides for isolated-agent runs while preserving <code>hooks.gmail.model</code> precedence for Gmail hook sessions. (#14983) Thanks @shtse8.</li>
-<li>Logging/Browser: fall back to <code>os.tmpdir()/openclaw</code> for default log, browser trace, and browser download temp paths when <code>/tmp/openclaw</code> is unavailable.</li>
-<li>WhatsApp: convert Markdown bold/strikethrough to WhatsApp formatting. (#14285) Thanks @Raikan10.</li>
-<li>WhatsApp: allow media-only sends and normalize leading blank payloads. (#14408) Thanks @karimnaguib.</li>
-<li>WhatsApp: default MIME type for voice messages when Baileys omits it. (#14444) Thanks @mcaxtr.</li>
-<li>Telegram: handle no-text message in model picker editMessageText. (#14397) Thanks @0xRaini.</li>
-<li>Telegram: surface REACTION_INVALID as non-fatal warning. (#14340) Thanks @0xRaini.</li>
-<li>BlueBubbles: fix webhook auth bypass via loopback proxy trust. (#13787) Thanks @coygeek.</li>
-<li>Slack: change default replyToMode from "off" to "all". (#14364) Thanks @nm-de.</li>
-<li>Slack: detect control commands when channel messages start with bot mention prefixes (for example, <code>@Bot /new</code>). (#14142) Thanks @beefiker.</li>
-<li>Signal: enforce E.164 validation for the Signal bot account prompt so mistyped numbers are caught early. (#15063) Thanks @Duartemartins.</li>
-<li>Discord: process DM reactions instead of silently dropping them. (#10418) Thanks @mcaxtr.</li>
-<li>Discord: respect replyToMode in threads. (#11062) Thanks @cordx56.</li>
-<li>Heartbeat: filter noise-only system events so scheduled reminder notifications do not fire when cron runs carry only heartbeat markers. (#13317) Thanks @pvtclawn.</li>
-<li>Signal: render mention placeholders as <code>@uuid</code>/<code>@phone</code> so mention gating and Clawdbot targeting work. (#2013) Thanks @alexgleason.</li>
-<li>Discord: omit empty content fields for media-only messages while preserving caption whitespace. (#9507) Thanks @leszekszpunar.</li>
-<li>Onboarding/Providers: add Z.AI endpoint-specific auth choices (<code>zai-coding-global</code>, <code>zai-coding-cn</code>, <code>zai-global</code>, <code>zai-cn</code>) and expand default Z.AI model wiring. (#13456) Thanks @tomsun28.</li>
-<li>Onboarding/Providers: update MiniMax API default/recommended models from M2.1 to M2.5, add M2.5/M2.5-Lightning model entries, and include <code>minimax-m2.5</code> in modern model filtering. (#14865) Thanks @adao-max.</li>
-<li>Ollama: use configured <code>models.providers.ollama.baseUrl</code> for model discovery and normalize <code>/v1</code> endpoints to the native Ollama API root. (#14131) Thanks @shtse8.</li>
-<li>Voice Call: pass Twilio stream auth token via <code><Parameter></code> instead of query string. (#14029) Thanks @mcwigglesmcgee.</li>
-<li>Feishu: pass <code>Buffer</code> directly to the Feishu SDK upload APIs instead of <code>Readable.from(...)</code> to avoid form-data upload failures. (#10345) Thanks @youngerstyle.</li>
-<li>Feishu: trigger mention-gated group handling only when the bot itself is mentioned (not just any mention). (#11088) Thanks @openperf.</li>
-<li>Feishu: probe status uses the resolved account context for multi-account credential checks. (#11233) Thanks @onevcat.</li>
-<li>Feishu DocX: preserve top-level converted block order using <code>firstLevelBlockIds</code> when writing/appending documents. (#13994) Thanks @Cynosure159.</li>
-<li>Feishu plugin packaging: remove <code>workspace:*</code> <code>openclaw</code> dependency from <code>extensions/feishu</code> and sync lockfile for install compatibility. (#14423) Thanks @jackcooper2015.</li>
-<li>CLI/Wizard: exit with code 1 when <code>configure</code>, <code>agents add</code>, or interactive <code>onboard</code> wizards are canceled, so <code>set -e</code> automation stops correctly. (#14156) Thanks @0xRaini.</li>
-<li>Media: strip <code>MEDIA:</code> lines with local paths instead of leaking as visible text. (#14399) Thanks @0xRaini.</li>
-<li>Config/Cron: exclude <code>maxTokens</code> from config redaction and honor <code>deleteAfterRun</code> on skipped cron jobs. (#13342) Thanks @niceysam.</li>
-<li>Config: ignore <code>meta</code> field changes in config file watcher. (#13460) Thanks @brandonwise.</li>
-<li>Cron: use requested <code>agentId</code> for isolated job auth resolution. (#13983) Thanks @0xRaini.</li>
-<li>Cron: pass <code>agentId</code> to <code>runHeartbeatOnce</code> for main-session jobs. (#14140) Thanks @ishikawa-pro.</li>
-<li>Cron: prevent cron jobs from skipping execution when <code>nextRunAtMs</code> advances. (#14068) Thanks @WalterSumbon.</li>
-<li>Cron: re-arm timers when <code>onTimer</code> fires while a job is still executing. (#14233) Thanks @tomron87.</li>
-<li>Cron: prevent duplicate fires when multiple jobs trigger simultaneously. (#14256) Thanks @xinhuagu.</li>
-<li>Cron: isolate scheduler errors so one bad job does not break all jobs. (#14385) Thanks @MarvinDontPanic.</li>
-<li>Cron: prevent one-shot <code>at</code> jobs from re-firing on restart after skipped/errored runs. (#13878) Thanks @lailoo.</li>
-<li>Daemon: suppress <code>EPIPE</code> error when restarting LaunchAgent. (#14343) Thanks @0xRaini.</li>
-<li>Antigravity: add opus 4.6 forward-compat model and bypass thinking signature sanitization. (#14218) Thanks @jg-noncelogic.</li>
-<li>Agents: prevent file descriptor leaks in child process cleanup. (#13565) Thanks @KyleChen26.</li>
-<li>Agents: prevent double compaction caused by cache TTL bypassing guard. (#13514) Thanks @taw0002.</li>
-<li>Agents: use last API call's cache tokens for context display instead of accumulated sum. (#13805) Thanks @akari-musubi.</li>
-<li>Agents: keep followup-runner session <code>totalTokens</code> aligned with post-compaction context by using last-call usage and shared token-accounting logic. (#14979) Thanks @shtse8.</li>
-<li>Hooks/Plugins: wire 9 previously unwired plugin lifecycle hooks into core runtime paths (session, compaction, gateway, and outbound message hooks). (#14882) Thanks @shtse8.</li>
-<li>Hooks/Tools: dispatch <code>before_tool_call</code> and <code>after_tool_call</code> hooks from both tool execution paths with rebased conflict fixes. (#15012) Thanks @Patrick-Barletta, @Takhoffman.</li>
-<li>Discord: allow channel-edit to archive/lock threads and set auto-archive duration. (#5542) Thanks @stumct.</li>
-<li>Discord tests: use a partial @buape/carbon mock in slash command coverage. (#13262) Thanks @arosstale.</li>
-<li>Tests: update thread ID handling in Slack message collection tests. (#14108) Thanks @swizzmagik.</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.2.12/OpenClaw-2026.2.12.zip" length="22877692" type="application/octet-stream" sparkle:edSignature="TGylTM4/7Lab+qp1nuPeOAmEVV1WkafXUPub8ws0z/0mYfbVygRuiev+u3zdPjQWhLnGYTgRgKVyW+kB2+Q2BQ=="/>
-        </item>
     </channel>
 </rss>

apps/android/app/build.gradle.kts

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

apps/ios/Sources/Calendar/CalendarService.swift

@@ -6,7 +6,7 @@ final class CalendarService: CalendarServicing {
     func events(params: OpenClawCalendarEventsParams) async throws -> OpenClawCalendarEventsPayload {
         let store = EKEventStore()
         let status = EKEventStore.authorizationStatus(for: .event)
-        let authorized = await Self.ensureAuthorization(store: store, status: status)
+        let authorized = EventKitAuthorization.allowsRead(status: status)
         guard authorized else {
             throw NSError(domain: "Calendar", code: 1, userInfo: [
                 NSLocalizedDescriptionKey: "CALENDAR_PERMISSION_REQUIRED: grant Calendar permission",
@@ -39,7 +39,7 @@ final class CalendarService: CalendarServicing {
     func add(params: OpenClawCalendarAddParams) async throws -> OpenClawCalendarAddPayload {
         let store = EKEventStore()
         let status = EKEventStore.authorizationStatus(for: .event)
-        let authorized = await Self.ensureWriteAuthorization(store: store, status: status)
+        let authorized = EventKitAuthorization.allowsWrite(status: status)
         guard authorized else {
             throw NSError(domain: "Calendar", code: 2, userInfo: [
                 NSLocalizedDescriptionKey: "CALENDAR_PERMISSION_REQUIRED: grant Calendar permission",
@@ -95,38 +95,6 @@ final class CalendarService: CalendarServicing {
         return OpenClawCalendarAddPayload(event: payload)
     }
 
-    private static func ensureAuthorization(store: EKEventStore, status: EKAuthorizationStatus) async -> Bool {
-        switch status {
-        case .authorized:
-            return true
-        case .notDetermined:
-            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
-            return false
-        case .restricted, .denied:
-            return false
-        case .fullAccess:
-            return true
-        case .writeOnly:
-            return false
-        @unknown default:
-            return false
-        }
-    }
-
-    private static func ensureWriteAuthorization(store: EKEventStore, status: EKAuthorizationStatus) async -> Bool {
-        switch status {
-        case .authorized, .fullAccess, .writeOnly:
-            return true
-        case .notDetermined:
-            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
-            return false
-        case .restricted, .denied:
-            return false
-        @unknown default:
-            return false
-        }
-    }
-
     private static func resolveCalendar(
         store: EKEventStore,
         calendarId: String?,

apps/ios/Sources/Camera/CameraController.swift

@@ -93,14 +93,10 @@ actor CameraController {
         }
         withExtendedLifetime(delegate) {}
 
-        let maxPayloadBytes = 5 * 1024 * 1024
-        // Base64 inflates payloads by ~4/3; cap encoded bytes so the payload stays under 5MB (API limit).
-        let maxEncodedBytes = (maxPayloadBytes / 4) * 3
-        let res = try JPEGTranscoder.transcodeToJPEG(
-            imageData: rawData,
+        let res = try PhotoCapture.transcodeJPEGForGateway(
+            rawData: rawData,
             maxWidthPx: maxWidth,
-            quality: quality,
-            maxBytes: maxEncodedBytes)
+            quality: quality)
 
         return (
             format: format.rawValue,
@@ -335,8 +331,8 @@ private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegat
     func photoOutput(
         _ output: AVCapturePhotoOutput,
         didFinishProcessingPhoto photo: AVCapturePhoto,
-        error: Error?)
-    {
+        error: Error?
+    ) {
         guard !self.didResume else { return }
         self.didResume = true
 
@@ -364,8 +360,8 @@ private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegat
     func photoOutput(
         _ output: AVCapturePhotoOutput,
         didFinishCaptureFor resolvedSettings: AVCaptureResolvedPhotoSettings,
-        error: Error?)
-    {
+        error: Error?
+    ) {
         guard let error else { return }
         guard !self.didResume else { return }
         self.didResume = true

apps/ios/Sources/Chat/IOSGatewayChatTransport.swift

@@ -2,8 +2,10 @@ import OpenClawChatUI
 import OpenClawKit
 import OpenClawProtocol
 import Foundation
+import OSLog
 
 struct IOSGatewayChatTransport: OpenClawChatTransport, Sendable {
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "ios.chat.transport")
     private let gateway: GatewayNodeSession
 
     init(gateway: GatewayNodeSession) {
@@ -33,10 +35,8 @@ struct IOSGatewayChatTransport: OpenClawChatTransport, Sendable {
     }
 
     func setActiveSessionKey(_ sessionKey: String) async throws {
-        struct Subscribe: Codable { var sessionKey: String }
-        let data = try JSONEncoder().encode(Subscribe(sessionKey: sessionKey))
-        let json = String(data: data, encoding: .utf8)
-        await self.gateway.sendEvent(event: "chat.subscribe", payloadJSON: json)
+        // Operator clients receive chat events without node-style subscriptions.
+        // (chat.subscribe is a node event, not an operator RPC method.)
     }
 
     func requestHistory(sessionKey: String) async throws -> OpenClawChatHistoryPayload {
@@ -54,6 +54,7 @@ struct IOSGatewayChatTransport: OpenClawChatTransport, Sendable {
         idempotencyKey: String,
         attachments: [OpenClawChatAttachmentPayload]) async throws -> OpenClawChatSendResponse
     {
+        Self.logger.info("chat.send start sessionKey=\(sessionKey, privacy: .public) len=\(message.count, privacy: .public) attachments=\(attachments.count, privacy: .public)")
         struct Params: Codable {
             var sessionKey: String
             var message: String
@@ -72,8 +73,15 @@ struct IOSGatewayChatTransport: OpenClawChatTransport, Sendable {
             idempotencyKey: idempotencyKey)
         let data = try JSONEncoder().encode(params)
         let json = String(data: data, encoding: .utf8)
-        let res = try await self.gateway.request(method: "chat.send", paramsJSON: json, timeoutSeconds: 35)
-        return try JSONDecoder().decode(OpenClawChatSendResponse.self, from: res)
+        do {
+            let res = try await self.gateway.request(method: "chat.send", paramsJSON: json, timeoutSeconds: 35)
+            let decoded = try JSONDecoder().decode(OpenClawChatSendResponse.self, from: res)
+            Self.logger.info("chat.send ok runId=\(decoded.runId, privacy: .public)")
+            return decoded
+        } catch {
+            Self.logger.error("chat.send failed \(error.localizedDescription, privacy: .public)")
+            throw error
+        }
     }
 
     func requestHealth(timeoutMs: Int) async throws -> Bool {

apps/ios/Sources/EventKit/EventKitAuthorization.swift

@@ -0,0 +1,34 @@
+import EventKit
+
+enum EventKitAuthorization {
+    static func allowsRead(status: EKAuthorizationStatus) -> Bool {
+        switch status {
+        case .authorized, .fullAccess:
+            return true
+        case .writeOnly:
+            return false
+        case .notDetermined:
+            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
+            return false
+        case .restricted, .denied:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+
+    static func allowsWrite(status: EKAuthorizationStatus) -> Bool {
+        switch status {
+        case .authorized, .fullAccess, .writeOnly:
+            return true
+        case .notDetermined:
+            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
+            return false
+        case .restricted, .denied:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+}
+

apps/ios/Sources/Gateway/GatewayConnectionController.swift

@@ -72,32 +72,55 @@ final class GatewayConnectionController {
         }
     }
 
-    func connect(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) async {
+    func allowAutoConnectAgain() {
+        self.didAutoConnect = false
+        self.maybeAutoConnect()
+    }
+
+    func restartDiscovery() {
+        self.discovery.stop()
+        self.didAutoConnect = false
+        self.discovery.start()
+        self.updateFromDiscovery()
+    }
+
+
+    /// Returns `nil` when a connect attempt was started, otherwise returns a user-facing error.
+    func connectWithDiagnostics(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) async -> String? {
         await self.connectDiscoveredGateway(gateway)
     }
 
     private func connectDiscoveredGateway(
-        _ gateway: GatewayDiscoveryModel.DiscoveredGateway) async
+        _ gateway: GatewayDiscoveryModel.DiscoveredGateway) async -> String?
     {
         let instanceId = UserDefaults.standard.string(forKey: "node.instanceId")?
             .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if instanceId.isEmpty {
+            return "Missing instanceId (node.instanceId). Try restarting the app."
+        }
         let token = GatewaySettingsStore.loadGatewayToken(instanceId: instanceId)
         let password = GatewaySettingsStore.loadGatewayPassword(instanceId: instanceId)
 
         // Resolve the service endpoint (SRV/A/AAAA). TXT is unauthenticated; do not route via TXT.
-        guard let target = await self.resolveServiceEndpoint(gateway.endpoint) else { return }
+        guard let target = await self.resolveServiceEndpoint(gateway.endpoint) else {
+            return "Failed to resolve the discovered gateway endpoint."
+        }
 
         let stableID = gateway.stableID
         // Discovery is a LAN operation; refuse unauthenticated plaintext connects.
         let tlsRequired = true
         let stored = GatewayTLSStore.loadFingerprint(stableID: stableID)
 
-        guard gateway.tlsEnabled || stored != nil else { return }
+        guard gateway.tlsEnabled || stored != nil else {
+            return "Discovered gateway is missing TLS and no trusted fingerprint is stored."
+        }
 
         if tlsRequired, stored == nil {
             guard let url = self.buildGatewayURL(host: target.host, port: target.port, useTLS: true)
-            else { return }
-            guard let fp = await self.probeTLSFingerprint(url: url) else { return }
+            else { return "Failed to build TLS URL for trust verification." }
+            guard let fp = await self.probeTLSFingerprint(url: url) else {
+                return "Failed to read TLS fingerprint from discovered gateway."
+            }
             self.pendingTrustConnect = (url: url, stableID: stableID, isManual: false)
             self.pendingTrustPrompt = TrustPrompt(
                 stableID: stableID,
@@ -107,7 +130,7 @@ final class GatewayConnectionController {
                 fingerprintSha256: fp,
                 isManual: false)
             self.appModel?.gatewayStatusText = "Verify gateway TLS fingerprint"
-            return
+            return nil
         }
 
         let tlsParams = stored.map { fp in
@@ -118,7 +141,7 @@ final class GatewayConnectionController {
             host: target.host,
             port: target.port,
             useTLS: tlsParams?.required == true)
-        else { return }
+        else { return "Failed to build discovered gateway URL." }
         GatewaySettingsStore.saveLastGatewayConnectionDiscovered(stableID: stableID, useTLS: true)
         self.didAutoConnect = true
         self.startAutoConnect(
@@ -127,6 +150,11 @@ final class GatewayConnectionController {
             tls: tlsParams,
             token: token,
             password: password)
+        return nil
+    }
+
+    func connect(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) async {
+        _ = await self.connectWithDiagnostics(gateway)
     }
 
     func connectManual(host: String, port: Int, useTLS: Bool) async {
@@ -490,6 +518,125 @@ final class GatewayConnectionController {
         }
     }
 
+    private func resolveHostPortFromBonjourEndpoint(_ endpoint: NWEndpoint) async -> (host: String, port: Int)? {
+        switch endpoint {
+        case let .hostPort(host, port):
+            return (host: host.debugDescription, port: Int(port.rawValue))
+        case let .service(name, type, domain, _):
+            return await Self.resolveBonjourServiceToHostPort(name: name, type: type, domain: domain)
+        default:
+            return nil
+        }
+    }
+
+    private static func resolveBonjourServiceToHostPort(
+        name: String,
+        type: String,
+        domain: String,
+        timeoutSeconds: TimeInterval = 3.0
+    ) async -> (host: String, port: Int)? {
+        // NetService callbacks are delivered via a run loop. If we resolve from a thread without one,
+        // we can end up never receiving callbacks, which in turn leaks the continuation and leaves
+        // the UI stuck "connecting". Keep the whole lifecycle on the main run loop and always
+        // resume the continuation exactly once (timeout/cancel safe).
+        @MainActor
+        final class Resolver: NSObject, @preconcurrency NetServiceDelegate {
+            private var cont: CheckedContinuation<(host: String, port: Int)?, Never>?
+            private let service: NetService
+            private var timeoutTask: Task<Void, Never>?
+            private var finished = false
+
+            init(cont: CheckedContinuation<(host: String, port: Int)?, Never>, service: NetService) {
+                self.cont = cont
+                self.service = service
+                super.init()
+            }
+
+            func start(timeoutSeconds: TimeInterval) {
+                self.service.delegate = self
+                self.service.schedule(in: .main, forMode: .default)
+
+                // NetService has its own timeout, but we keep a manual one as a backstop in case
+                // callbacks never arrive (e.g. local network permission issues).
+                self.timeoutTask = Task { @MainActor [weak self] in
+                    guard let self else { return }
+                    let ns = UInt64(max(0.1, timeoutSeconds) * 1_000_000_000)
+                    try? await Task.sleep(nanoseconds: ns)
+                    self.finish(nil)
+                }
+
+                self.service.resolve(withTimeout: timeoutSeconds)
+            }
+
+            func netServiceDidResolveAddress(_ sender: NetService) {
+                self.finish(Self.extractHostPort(sender))
+            }
+
+            func netService(_ sender: NetService, didNotResolve errorDict: [String: NSNumber]) {
+                _ = errorDict // currently best-effort; callers surface a generic failure
+                self.finish(nil)
+            }
+
+            private func finish(_ result: (host: String, port: Int)?) {
+                guard !self.finished else { return }
+                self.finished = true
+
+                self.timeoutTask?.cancel()
+                self.timeoutTask = nil
+
+                self.service.stop()
+                self.service.remove(from: .main, forMode: .default)
+
+                let c = self.cont
+                self.cont = nil
+                c?.resume(returning: result)
+            }
+
+            private static func extractHostPort(_ svc: NetService) -> (host: String, port: Int)? {
+                let port = svc.port
+
+                if let host = svc.hostName?.trimmingCharacters(in: .whitespacesAndNewlines), !host.isEmpty {
+                    return (host: host, port: port)
+                }
+
+                guard let addrs = svc.addresses else { return nil }
+                    for addrData in addrs {
+                        let host = addrData.withUnsafeBytes { ptr -> String? in
+                        guard let base = ptr.baseAddress, !ptr.isEmpty else { return nil }
+                        var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
+
+                        let rc = getnameinfo(
+                            base.assumingMemoryBound(to: sockaddr.self),
+                            socklen_t(ptr.count),
+                            &buffer,
+                            socklen_t(buffer.count),
+                            nil,
+                            0,
+                            NI_NUMERICHOST)
+                        guard rc == 0 else { return nil }
+                        return String(cString: buffer)
+                    }
+
+                    if let host, !host.isEmpty {
+                        return (host: host, port: port)
+                    }
+                }
+
+                return nil
+            }
+        }
+
+        return await withCheckedContinuation { cont in
+            Task { @MainActor in
+                let service = NetService(domain: domain, type: type, name: name)
+                let resolver = Resolver(cont: cont, service: service)
+                // Keep the resolver alive for the lifetime of the NetService resolve.
+                objc_setAssociatedObject(service, "resolver", resolver, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+                resolver.start(timeoutSeconds: timeoutSeconds)
+            }
+        }
+    }
+
     private func buildGatewayURL(host: String, port: Int, useTLS: Bool) -> URL? {
         let scheme = useTLS ? "wss" : "ws"
         var components = URLComponents()

apps/ios/Sources/Gateway/GatewayConnectionIssue.swift

@@ -0,0 +1,71 @@
+import Foundation
+
+enum GatewayConnectionIssue: Equatable {
+    case none
+    case tokenMissing
+    case unauthorized
+    case pairingRequired(requestId: String?)
+    case network
+    case unknown(String)
+
+    var requestId: String? {
+        if case let .pairingRequired(requestId) = self {
+            return requestId
+        }
+        return nil
+    }
+
+    var needsAuthToken: Bool {
+        switch self {
+        case .tokenMissing, .unauthorized:
+            return true
+        default:
+            return false
+        }
+    }
+
+    var needsPairing: Bool {
+        if case .pairingRequired = self { return true }
+        return false
+    }
+
+    static func detect(from statusText: String) -> Self {
+        let trimmed = statusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return .none }
+        let lower = trimmed.lowercased()
+
+        if lower.contains("pairing required") || lower.contains("not_paired") || lower.contains("not paired") {
+            return .pairingRequired(requestId: self.extractRequestId(from: trimmed))
+        }
+        if lower.contains("gateway token missing") {
+            return .tokenMissing
+        }
+        if lower.contains("unauthorized") {
+            return .unauthorized
+        }
+        if lower.contains("connection refused") ||
+            lower.contains("timed out") ||
+            lower.contains("network is unreachable") ||
+            lower.contains("cannot find host") ||
+            lower.contains("could not connect")
+        {
+            return .network
+        }
+        if lower.hasPrefix("gateway error:") {
+            return .unknown(trimmed)
+        }
+        return .none
+    }
+
+    private static func extractRequestId(from statusText: String) -> String? {
+        let marker = "requestId:"
+        guard let range = statusText.range(of: marker) else { return nil }
+        let suffix = statusText[range.upperBound...]
+        let trimmed = suffix.trimmingCharacters(in: .whitespacesAndNewlines)
+        let end = trimmed.firstIndex(where: { ch in
+            ch == ")" || ch.isWhitespace || ch == "," || ch == ";"
+        }) ?? trimmed.endIndex
+        let id = String(trimmed[..<end]).trimmingCharacters(in: .whitespacesAndNewlines)
+        return id.isEmpty ? nil : id
+    }
+}

apps/ios/Sources/Gateway/GatewayDiscoveryModel.swift

@@ -136,43 +136,9 @@ final class GatewayDiscoveryModel {
     }
 
     private func updateStatusText() {
-        let states = Array(self.statesByDomain.values)
-        if states.isEmpty {
-            self.statusText = self.browsers.isEmpty ? "Idle" : "Setup"
-            return
-        }
-
-        if let failed = states.first(where: { state in
-            if case .failed = state { return true }
-            return false
-        }) {
-            if case let .failed(err) = failed {
-                self.statusText = "Failed: \(err)"
-                return
-            }
-        }
-
-        if let waiting = states.first(where: { state in
-            if case .waiting = state { return true }
-            return false
-        }) {
-            if case let .waiting(err) = waiting {
-                self.statusText = "Waiting: \(err)"
-                return
-            }
-        }
-
-        if states.contains(where: { if case .ready = $0 { true } else { false } }) {
-            self.statusText = "Searching…"
-            return
-        }
-
-        if states.contains(where: { if case .setup = $0 { true } else { false } }) {
-            self.statusText = "Setup"
-            return
-        }
-
-        self.statusText = "Searching…"
+        self.statusText = GatewayDiscoveryStatusText.make(
+            states: Array(self.statesByDomain.values),
+            hasBrowsers: !self.browsers.isEmpty)
     }
 
     private static func prettyState(_ state: NWBrowser.State) -> String {

apps/ios/Sources/Gateway/GatewayQuickSetupSheet.swift

@@ -0,0 +1,113 @@
+import SwiftUI
+
+struct GatewayQuickSetupSheet: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @Environment(GatewayConnectionController.self) private var gatewayController
+    @Environment(\.dismiss) private var dismiss
+
+    @AppStorage("onboarding.quickSetupDismissed") private var quickSetupDismissed: Bool = false
+    @State private var connecting: Bool = false
+    @State private var connectError: String?
+
+    var body: some View {
+        NavigationStack {
+            VStack(alignment: .leading, spacing: 16) {
+                Text("Connect to a Gateway?")
+                    .font(.title2.bold())
+
+                if let candidate = self.bestCandidate {
+                    VStack(alignment: .leading, spacing: 6) {
+                        Text(verbatim: candidate.name)
+                            .font(.headline)
+                        Text(verbatim: candidate.debugID)
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+
+                        VStack(alignment: .leading, spacing: 2) {
+                            // Use verbatim strings so Bonjour-provided values can't be interpreted as
+                            // localized format strings (which can crash with Objective-C exceptions).
+                            Text(verbatim: "Discovery: \(self.gatewayController.discoveryStatusText)")
+                            Text(verbatim: "Status: \(self.appModel.gatewayStatusText)")
+                            Text(verbatim: "Node: \(self.appModel.nodeStatusText)")
+                            Text(verbatim: "Operator: \(self.appModel.operatorStatusText)")
+                        }
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                    }
+                    .padding(12)
+                    .background(.thinMaterial)
+                    .clipShape(RoundedRectangle(cornerRadius: 14))
+
+                    Button {
+                        self.connectError = nil
+                        self.connecting = true
+                        Task {
+                            let err = await self.gatewayController.connectWithDiagnostics(candidate)
+                            await MainActor.run {
+                                self.connecting = false
+                                self.connectError = err
+                                // If we kicked off a connect, leave the sheet up so the user can see status evolve.
+                            }
+                        }
+                    } label: {
+                        Group {
+                            if self.connecting {
+                                HStack(spacing: 8) {
+                                    ProgressView().progressViewStyle(.circular)
+                                    Text("Connecting…")
+                                }
+                            } else {
+                                Text("Connect")
+                            }
+                        }
+                        .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(self.connecting)
+
+                    if let connectError {
+                        Text(connectError)
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+                            .textSelection(.enabled)
+                    }
+
+                    Button {
+                        self.dismiss()
+                    } label: {
+                        Text("Not now")
+                            .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.connecting)
+
+                    Toggle("Don’t show this again", isOn: self.$quickSetupDismissed)
+                        .padding(.top, 4)
+                } else {
+                    Text("No gateways found yet. Make sure your gateway is running and Bonjour discovery is enabled.")
+                        .foregroundStyle(.secondary)
+                }
+
+                Spacer()
+            }
+            .padding()
+            .navigationTitle("Quick Setup")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button {
+                        self.quickSetupDismissed = true
+                        self.dismiss()
+                    } label: {
+                        Text("Close")
+                    }
+                }
+            }
+        }
+    }
+
+    private var bestCandidate: GatewayDiscoveryModel.DiscoveredGateway? {
+        // Prefer whatever discovery says is first; the list is already name-sorted.
+        self.gatewayController.gateways.first
+    }
+}

apps/ios/Sources/Gateway/GatewaySettingsStore.swift

@@ -4,6 +4,7 @@ import os
 enum GatewaySettingsStore {
     private static let gatewayService = "ai.openclaw.gateway"
     private static let nodeService = "ai.openclaw.node"
+    private static let talkService = "ai.openclaw.talk"
 
     private static let instanceIdDefaultsKey = "node.instanceId"
     private static let preferredGatewayStableIDDefaultsKey = "gateway.preferredStableID"
@@ -24,6 +25,7 @@ enum GatewaySettingsStore {
     private static let instanceIdAccount = "instanceId"
     private static let preferredGatewayStableIDAccount = "preferredStableID"
     private static let lastDiscoveredGatewayStableIDAccount = "lastDiscoveredStableID"
+    private static let talkElevenLabsApiKeyAccount = "elevenlabs.apiKey"
 
     static func bootstrapPersistence() {
         self.ensureStableInstanceID()
@@ -143,6 +145,27 @@ enum GatewaySettingsStore {
         case discovered
     }
 
+    static func loadTalkElevenLabsApiKey() -> String? {
+        let value = KeychainStore.loadString(
+            service: self.talkService,
+            account: self.talkElevenLabsApiKeyAccount)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if value?.isEmpty == false { return value }
+        return nil
+    }
+
+    static func saveTalkElevenLabsApiKey(_ apiKey: String?) {
+        let trimmed = apiKey?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmed.isEmpty {
+            _ = KeychainStore.delete(service: self.talkService, account: self.talkElevenLabsApiKeyAccount)
+            return
+        }
+        _ = KeychainStore.saveString(
+            trimmed,
+            service: self.talkService,
+            account: self.talkElevenLabsApiKeyAccount)
+    }
+
     static func saveLastGatewayConnectionManual(host: String, port: Int, useTLS: Bool, stableID: String) {
         let defaults = UserDefaults.standard
         defaults.set(LastGatewayKind.manual.rawValue, forKey: self.lastGatewayKindDefaultsKey)
@@ -184,6 +207,25 @@ enum GatewaySettingsStore {
         return .manual(host: host, port: port, useTLS: useTLS, stableID: stableID)
     }
 
+    static func clearLastGatewayConnection(defaults: UserDefaults = .standard) {
+        defaults.removeObject(forKey: self.lastGatewayKindDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayHostDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayPortDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayTlsDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayStableIDDefaultsKey)
+    }
+
+    static func deleteGatewayCredentials(instanceId: String) {
+        let trimmed = instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.gatewayTokenAccount(instanceId: trimmed))
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.gatewayPasswordAccount(instanceId: trimmed))
+    }
+
     static func loadGatewayClientIdOverride(stableID: String) -> String? {
         let trimmedID = stableID.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !trimmedID.isEmpty else { return nil }

apps/ios/Sources/Gateway/GatewaySetupCode.swift

@@ -0,0 +1,42 @@
+import Foundation
+
+struct GatewaySetupPayload: Codable {
+    var url: String?
+    var host: String?
+    var port: Int?
+    var tls: Bool?
+    var token: String?
+    var password: String?
+}
+
+enum GatewaySetupCode {
+    static func decode(raw: String) -> GatewaySetupPayload? {
+        if let payload = decodeFromJSON(raw) {
+            return payload
+        }
+        if let decoded = decodeBase64Payload(raw),
+           let payload = decodeFromJSON(decoded)
+        {
+            return payload
+        }
+        return nil
+    }
+
+    private static func decodeFromJSON(_ json: String) -> GatewaySetupPayload? {
+        guard let data = json.data(using: .utf8) else { return nil }
+        return try? JSONDecoder().decode(GatewaySetupPayload.self, from: data)
+    }
+
+    private static func decodeBase64Payload(_ raw: String) -> String? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        let normalized = trimmed
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+        let padding = normalized.count % 4
+        let padded = padding == 0 ? normalized : normalized + String(repeating: "=", count: 4 - padding)
+        guard let data = Data(base64Encoded: padded) else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+}
+

apps/ios/Sources/Gateway/GatewayTrustPromptAlert.swift

@@ -6,10 +6,10 @@ struct GatewayTrustPromptAlert: ViewModifier {
     private var promptBinding: Binding<GatewayConnectionController.TrustPrompt?> {
         Binding(
             get: { self.gatewayController.pendingTrustPrompt },
-            set: { newValue in
-                if newValue == nil {
-                    self.gatewayController.clearPendingTrustPrompt()
-                }
+            set: { _ in
+                // Keep pending trust state until explicit user action.
+                // `alert(item:)` may set the binding to nil during dismissal, which can race with
+                // the button handler and cause accept to no-op.
             })
     }
 
@@ -39,4 +39,3 @@ extension View {
         self.modifier(GatewayTrustPromptAlert())
     }
 }
-

apps/ios/Sources/Gateway/TCPProbe.swift

@@ -0,0 +1,43 @@
+import Foundation
+import Network
+import os
+
+enum TCPProbe {
+    static func probe(host: String, port: Int, timeoutSeconds: Double, queueLabel: String) async -> Bool {
+        guard port >= 1, port <= 65535 else { return false }
+        guard let nwPort = NWEndpoint.Port(rawValue: UInt16(port)) else { return false }
+
+        let endpointHost = NWEndpoint.Host(host)
+        let connection = NWConnection(host: endpointHost, port: nwPort, using: .tcp)
+
+        return await withCheckedContinuation { cont in
+            let queue = DispatchQueue(label: queueLabel)
+            let finished = OSAllocatedUnfairLock(initialState: false)
+            let finish: @Sendable (Bool) -> Void = { ok in
+                let shouldResume = finished.withLock { flag -> Bool in
+                    if flag { return false }
+                    flag = true
+                    return true
+                }
+                guard shouldResume else { return }
+                connection.cancel()
+                cont.resume(returning: ok)
+            }
+
+            connection.stateUpdateHandler = { state in
+                switch state {
+                case .ready:
+                    finish(true)
+                case .failed, .cancelled:
+                    finish(false)
+                default:
+                    break
+                }
+            }
+
+            connection.start(queue: queue)
+            queue.asyncAfter(deadline: .now() + timeoutSeconds) { finish(false) }
+        }
+    }
+}
+

apps/ios/Sources/Info.plist

@@ -17,15 +17,15 @@
 	<key>CFBundleName</key>
 	<string>$(PRODUCT_NAME)</string>
 	<key>CFBundlePackageType</key>
-			<string>APPL</string>
-			<key>CFBundleShortVersionString</key>
-			<string>2026.2.15</string>
-			<key>CFBundleVersion</key>
-			<string>20260215</string>
-			<key>NSAppTransportSecurity</key>
-			<dict>
-			<key>NSAllowsArbitraryLoadsInWebContent</key>
-			<true/>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>2026.2.16</string>
+	<key>CFBundleVersion</key>
+	<string>20260216</string>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoadsInWebContent</key>
+		<true/>
 	</dict>
 	<key>NSBonjourServices</key>
 	<array>

apps/ios/Sources/Location/LocationService.swift

@@ -12,6 +12,10 @@ final class LocationService: NSObject, CLLocationManagerDelegate {
     private let manager = CLLocationManager()
     private var authContinuation: CheckedContinuation<CLAuthorizationStatus, Never>?
     private var locationContinuation: CheckedContinuation<CLLocation, Swift.Error>?
+    private var updatesContinuation: AsyncStream<CLLocation>.Continuation?
+    private var isStreaming = false
+    private var significantLocationCallback: (@Sendable (CLLocation) -> Void)?
+    private var isMonitoringSignificantChanges = false
 
     override init() {
         super.init()
@@ -104,6 +108,56 @@ final class LocationService: NSObject, CLLocationManagerDelegate {
         }
     }
 
+    func startLocationUpdates(
+        desiredAccuracy: OpenClawLocationAccuracy,
+        significantChangesOnly: Bool) -> AsyncStream<CLLocation>
+    {
+        self.stopLocationUpdates()
+
+        self.manager.desiredAccuracy = Self.accuracyValue(desiredAccuracy)
+        self.manager.pausesLocationUpdatesAutomatically = true
+        self.manager.allowsBackgroundLocationUpdates = true
+
+        self.isStreaming = true
+        if significantChangesOnly {
+            self.manager.startMonitoringSignificantLocationChanges()
+        } else {
+            self.manager.startUpdatingLocation()
+        }
+
+        return AsyncStream(bufferingPolicy: .bufferingNewest(1)) { continuation in
+            self.updatesContinuation = continuation
+            continuation.onTermination = { @Sendable _ in
+                Task { @MainActor in
+                    self.stopLocationUpdates()
+                }
+            }
+        }
+    }
+
+    func stopLocationUpdates() {
+        guard self.isStreaming else { return }
+        self.isStreaming = false
+        self.manager.stopUpdatingLocation()
+        self.manager.stopMonitoringSignificantLocationChanges()
+        self.updatesContinuation?.finish()
+        self.updatesContinuation = nil
+    }
+
+    func startMonitoringSignificantLocationChanges(onUpdate: @escaping @Sendable (CLLocation) -> Void) {
+        self.significantLocationCallback = onUpdate
+        guard !self.isMonitoringSignificantChanges else { return }
+        self.isMonitoringSignificantChanges = true
+        self.manager.startMonitoringSignificantLocationChanges()
+    }
+
+    func stopMonitoringSignificantLocationChanges() {
+        guard self.isMonitoringSignificantChanges else { return }
+        self.isMonitoringSignificantChanges = false
+        self.significantLocationCallback = nil
+        self.manager.stopMonitoringSignificantLocationChanges()
+    }
+
     nonisolated func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
         let status = manager.authorizationStatus
         Task { @MainActor in
@@ -117,12 +171,22 @@ final class LocationService: NSObject, CLLocationManagerDelegate {
     nonisolated func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
         let locs = locations
         Task { @MainActor in
-            guard let cont = self.locationContinuation else { return }
-            self.locationContinuation = nil
-            if let latest = locs.last {
-                cont.resume(returning: latest)
-            } else {
-                cont.resume(throwing: Error.unavailable)
+            // Resolve the one-shot continuation first (if any).
+            if let cont = self.locationContinuation {
+                self.locationContinuation = nil
+                if let latest = locs.last {
+                    cont.resume(returning: latest)
+                } else {
+                    cont.resume(throwing: Error.unavailable)
+                }
+                // Don't return — also forward to significant-change callback below
+                // so both consumers receive updates when both are active.
+            }
+            if let callback = self.significantLocationCallback, let latest = locs.last {
+                callback(latest)
+            }
+            if let latest = locs.last, let updates = self.updatesContinuation {
+                updates.yield(latest)
             }
         }
     }

apps/ios/Sources/Location/SignificantLocationMonitor.swift

@@ -0,0 +1,38 @@
+import CoreLocation
+import Foundation
+import OpenClawKit
+
+/// Monitors significant location changes and pushes `location.update`
+/// events to the gateway so the severance hook can determine whether
+/// the user is at their configured work location.
+@MainActor
+enum SignificantLocationMonitor {
+    static func startIfNeeded(
+        locationService: any LocationServicing,
+        locationMode: OpenClawLocationMode,
+        gateway: GatewayNodeSession
+    ) {
+        guard locationMode == .always else { return }
+        let status = locationService.authorizationStatus()
+        guard status == .authorizedAlways else { return }
+        locationService.startMonitoringSignificantLocationChanges { location in
+            struct Payload: Codable {
+                var lat: Double
+                var lon: Double
+                var accuracyMeters: Double
+                var source: String?
+            }
+            let payload = Payload(
+                lat: location.coordinate.latitude,
+                lon: location.coordinate.longitude,
+                accuracyMeters: location.horizontalAccuracy,
+                source: "ios-significant-location")
+            guard let data = try? JSONEncoder().encode(payload),
+                  let json = String(data: data, encoding: .utf8)
+            else { return }
+            Task { @MainActor in
+                await gateway.sendEvent(event: "location.update", payloadJSON: json)
+            }
+        }
+    }
+}

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

@@ -61,37 +61,10 @@ extension NodeAppModel {
     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)
-        guard portInt >= 1, portInt <= 65535 else { return false }
-        guard let nwPort = NWEndpoint.Port(rawValue: UInt16(portInt)) else { return false }
-
-        let endpointHost = NWEndpoint.Host(host)
-        let connection = NWConnection(host: endpointHost, port: nwPort, using: .tcp)
-        return await withCheckedContinuation { cont in
-            let queue = DispatchQueue(label: "a2ui.preflight")
-            let finished = OSAllocatedUnfairLock(initialState: false)
-            let finish: @Sendable (Bool) -> Void = { ok in
-                let shouldResume = finished.withLock { flag -> Bool in
-                    if flag { return false }
-                    flag = true
-                    return true
-                }
-                guard shouldResume else { return }
-                connection.cancel()
-                cont.resume(returning: ok)
-            }
-
-            connection.stateUpdateHandler = { state in
-                switch state {
-                case .ready:
-                    finish(true)
-                case .failed, .cancelled:
-                    finish(false)
-                default:
-                    break
-                }
-            }
-            connection.start(queue: queue)
-            queue.asyncAfter(deadline: .now() + timeoutSeconds) { finish(false) }
-        }
+        return await TCPProbe.probe(
+            host: host,
+            port: portInt,
+            timeoutSeconds: timeoutSeconds,
+            queueLabel: "a2ui.preflight")
     }
 }

apps/ios/Sources/Model/NodeAppModel.swift

@@ -10,7 +10,6 @@ import UserNotifications
 private struct NotificationCallError: Error, Sendable {
     let message: String
 }
-
 // Ensures notification requests return promptly even if the system prompt blocks.
 private final class NotificationInvokeLatch<T: Sendable>: @unchecked Sendable {
     private let lock = NSLock()
@@ -37,7 +36,6 @@ private final class NotificationInvokeLatch<T: Sendable>: @unchecked Sendable {
         cont?.resume(returning: response)
     }
 }
-
 @MainActor
 @Observable
 final class NodeAppModel {
@@ -53,10 +51,17 @@ final class NodeAppModel {
     private let camera: any CameraServicing
     private let screenRecorder: any ScreenRecordingServicing
     var gatewayStatusText: String = "Offline"
+    var nodeStatusText: String = "Offline"
+    var operatorStatusText: String = "Offline"
     var gatewayServerName: String?
     var gatewayRemoteAddress: String?
     var connectedGatewayID: String?
     var gatewayAutoReconnectEnabled: Bool = true
+    // When the gateway requires pairing approval, we pause reconnect churn and show a stable UX.
+    // Reconnect loops (both our own and the underlying WebSocket watchdog) can otherwise generate
+    // multiple pending requests and cause the onboarding UI to "flip-flop".
+    var gatewayPairingPaused: Bool = false
+    var gatewayPairingRequestId: String?
     var seamColorHex: String?
     private var mainSessionBaseKey: String = "main"
     var selectedAgentId: String?
@@ -109,6 +114,7 @@ final class NodeAppModel {
     private var talkVoiceWakeSuspended = false
     private var backgroundVoiceWakeSuspended = false
     private var backgroundTalkSuspended = false
+    private var backgroundTalkKeptActive = false
     private var backgroundedAt: Date?
     private var reconnectAfterBackgroundArmed = false
 
@@ -264,15 +270,18 @@ final class NodeAppModel {
 
 
     func setScenePhase(_ phase: ScenePhase) {
+        let keepTalkActive = UserDefaults.standard.bool(forKey: "talk.background.enabled")
         switch phase {
         case .background:
             self.isBackgrounded = true
             self.stopGatewayHealthMonitor()
             self.backgroundedAt = Date()
             self.reconnectAfterBackgroundArmed = true
-            // Be conservative: release the mic when the app backgrounds.
+            // Release voice wake mic in background.
             self.backgroundVoiceWakeSuspended = self.voiceWake.suspendForExternalAudioCapture()
-            self.backgroundTalkSuspended = self.talkMode.suspendForBackground()
+            let shouldKeepTalkActive = keepTalkActive && self.talkMode.isEnabled
+            self.backgroundTalkKeptActive = shouldKeepTalkActive
+            self.backgroundTalkSuspended = self.talkMode.suspendForBackground(keepActive: shouldKeepTalkActive)
         case .active, .inactive:
             self.isBackgrounded = false
             if self.operatorConnected {
@@ -284,8 +293,12 @@ final class NodeAppModel {
                 Task { [weak self] in
                     guard let self else { return }
                     let suspended = await MainActor.run { self.backgroundTalkSuspended }
-                    await MainActor.run { self.backgroundTalkSuspended = false }
-                    await self.talkMode.resumeAfterBackground(wasSuspended: suspended)
+                    let keptActive = await MainActor.run { self.backgroundTalkKeptActive }
+                    await MainActor.run {
+                        self.backgroundTalkSuspended = false
+                        self.backgroundTalkKeptActive = false
+                    }
+                    await self.talkMode.resumeAfterBackground(wasSuspended: suspended, wasKeptActive: keptActive)
                 }
             }
             if phase == .active, self.reconnectAfterBackgroundArmed {
@@ -340,6 +353,7 @@ final class NodeAppModel {
     }
 
     func setTalkEnabled(_ enabled: Bool) {
+        UserDefaults.standard.set(enabled, forKey: "talk.enabled")
         if enabled {
             // Voice wake holds the microphone continuously; talk mode needs exclusive access for STT.
             // When talk is enabled from the UI, prioritize talk and pause voice wake.
@@ -351,6 +365,11 @@ final class NodeAppModel {
             self.talkVoiceWakeSuspended = false
         }
         self.talkMode.setEnabled(enabled)
+        Task { [weak self] in
+            await self?.pushTalkModeToGateway(
+                enabled: enabled,
+                phase: enabled ? "enabled" : "disabled")
+        }
     }
 
     func requestLocationPermissions(mode: OpenClawLocationMode) async -> Bool {
@@ -479,16 +498,49 @@ final class NodeAppModel {
             let stream = await self.operatorGateway.subscribeServerEvents(bufferingNewest: 200)
             for await evt in stream {
                 if Task.isCancelled { return }
-                guard evt.event == "voicewake.changed" else { continue }
                 guard let payload = evt.payload else { continue }
-                struct Payload: Decodable { var triggers: [String] }
-                guard let decoded = try? GatewayPayloadDecoding.decode(payload, as: Payload.self) else { continue }
-                let triggers = VoiceWakePreferences.sanitizeTriggerWords(decoded.triggers)
-                VoiceWakePreferences.saveTriggerWords(triggers)
+                switch evt.event {
+                case "voicewake.changed":
+                    struct Payload: Decodable { var triggers: [String] }
+                    guard let decoded = try? GatewayPayloadDecoding.decode(payload, as: Payload.self) else { continue }
+                    let triggers = VoiceWakePreferences.sanitizeTriggerWords(decoded.triggers)
+                    VoiceWakePreferences.saveTriggerWords(triggers)
+                case "talk.mode":
+                    struct Payload: Decodable {
+                        var enabled: Bool
+                        var phase: String?
+                    }
+                    guard let decoded = try? GatewayPayloadDecoding.decode(payload, as: Payload.self) else { continue }
+                    self.applyTalkModeSync(enabled: decoded.enabled, phase: decoded.phase)
+                default:
+                    continue
+                }
             }
         }
     }
 
+    private func applyTalkModeSync(enabled: Bool, phase: String?) {
+        _ = phase
+        guard self.talkMode.isEnabled != enabled else { return }
+        self.setTalkEnabled(enabled)
+    }
+
+    private func pushTalkModeToGateway(enabled: Bool, phase: String?) async {
+        guard await self.isOperatorConnected() else { return }
+        struct TalkModePayload: Encodable {
+            var enabled: Bool
+            var phase: String?
+        }
+        let payload = TalkModePayload(enabled: enabled, phase: phase)
+        guard let data = try? JSONEncoder().encode(payload),
+              let json = String(data: data, encoding: .utf8)
+        else { return }
+        _ = try? await self.operatorGateway.request(
+            method: "talk.mode",
+            paramsJSON: json,
+            timeoutSeconds: 8)
+    }
+
     private func startGatewayHealthMonitor() {
         self.gatewayHealthMonitorDisabled = false
         self.gatewayHealthMonitor.start(
@@ -577,6 +629,8 @@ final class NodeAppModel {
         switch route {
         case let .agent(link):
             await self.handleAgentDeepLink(link, originalURL: url)
+        case .gateway:
+            break
         }
     }
 
@@ -1506,6 +1560,8 @@ extension NodeAppModel {
 
     func disconnectGateway() {
         self.gatewayAutoReconnectEnabled = false
+        self.gatewayPairingPaused = false
+        self.gatewayPairingRequestId = nil
         self.nodeGatewayTask?.cancel()
         self.nodeGatewayTask = nil
         self.operatorGatewayTask?.cancel()
@@ -1535,6 +1591,8 @@ extension NodeAppModel {
 private extension NodeAppModel {
     func prepareForGatewayConnect(url: URL, stableID: String) {
         self.gatewayAutoReconnectEnabled = true
+        self.gatewayPairingPaused = false
+        self.gatewayPairingRequestId = nil
         self.nodeGatewayTask?.cancel()
         self.operatorGatewayTask?.cancel()
         self.gatewayHealthMonitor.stop()
@@ -1564,6 +1622,10 @@ private extension NodeAppModel {
             guard let self else { return }
             var attempt = 0
             while !Task.isCancelled {
+                if self.gatewayPairingPaused {
+                    try? await Task.sleep(nanoseconds: 1_000_000_000)
+                    continue
+                }
                 if await self.isOperatorConnected() {
                     try? await Task.sleep(nanoseconds: 1_000_000_000)
                     continue
@@ -1639,8 +1701,13 @@ private extension NodeAppModel {
             var attempt = 0
             var currentOptions = nodeOptions
             var didFallbackClientId = false
+            var pausedForPairingApproval = false
 
             while !Task.isCancelled {
+                if self.gatewayPairingPaused {
+                    try? await Task.sleep(nanoseconds: 1_000_000_000)
+                    continue
+                }
                 if await self.isGatewayConnected() {
                     try? await Task.sleep(nanoseconds: 1_000_000_000)
                     continue
@@ -1669,12 +1736,13 @@ private extension NodeAppModel {
                                 self.screen.errorText = nil
                                 UserDefaults.standard.set(true, forKey: "gateway.autoconnect")
                             }
-                            GatewayDiagnostics.log(
-                                "gateway connected host=\(url.host ?? "?") scheme=\(url.scheme ?? "?")")
+                            GatewayDiagnostics.log("gateway connected host=\(url.host ?? "?") scheme=\(url.scheme ?? "?")")
                             if let addr = await self.nodeGateway.currentRemoteAddress() {
                                 await MainActor.run { self.gatewayRemoteAddress = addr }
                             }
                             await self.showA2UIOnConnectIfNeeded()
+                            await self.onNodeGatewayConnected()
+                            await MainActor.run { SignificantLocationMonitor.startIfNeeded(locationService: self.locationService, locationMode: self.locationMode(), gateway: self.nodeGateway) }
                         },
                         onDisconnected: { [weak self] reason in
                             guard let self else { return }
@@ -1726,11 +1794,52 @@ private extension NodeAppModel {
                         self.showLocalCanvasOnDisconnect()
                     }
                     GatewayDiagnostics.log("gateway connect error: \(error.localizedDescription)")
+
+                    // If pairing is required, stop reconnect churn. The user must approve the request
+                    // on the gateway before another connect attempt will succeed, and retry loops can
+                    // generate multiple pending requests.
+                    let lower = error.localizedDescription.lowercased()
+                    if lower.contains("not_paired") || lower.contains("pairing required") {
+                        let requestId: String? = {
+                            // GatewayResponseError for connect decorates the message with `(requestId: ...)`.
+                            // Keep this resilient since other layers may wrap the text.
+                            let text = error.localizedDescription
+                            guard let start = text.range(of: "(requestId: ")?.upperBound else { return nil }
+                            guard let end = text[start...].firstIndex(of: ")") else { return nil }
+                            let raw = String(text[start..<end]).trimmingCharacters(in: .whitespacesAndNewlines)
+                            return raw.isEmpty ? nil : raw
+                        }()
+                        await MainActor.run {
+                            self.gatewayAutoReconnectEnabled = false
+                            self.gatewayPairingPaused = true
+                            self.gatewayPairingRequestId = requestId
+                            if let requestId, !requestId.isEmpty {
+                                self.gatewayStatusText =
+                                    "Pairing required (requestId: \(requestId)). Approve on gateway, then tap Resume."
+                            } else {
+                                self.gatewayStatusText = "Pairing required. Approve on gateway, then tap Resume."
+                            }
+                        }
+                        // Hard stop the underlying WebSocket watchdog reconnects so the UI stays stable and
+                        // we don't generate multiple pending requests while waiting for approval.
+                        pausedForPairingApproval = true
+                        self.operatorGatewayTask?.cancel()
+                        self.operatorGatewayTask = nil
+                        await self.operatorGateway.disconnect()
+                        await self.nodeGateway.disconnect()
+                        break
+                    }
+
                     let sleepSeconds = min(8.0, 0.5 * pow(1.7, Double(attempt)))
                     try? await Task.sleep(nanoseconds: UInt64(sleepSeconds * 1_000_000_000))
                 }
             }
 
+            if pausedForPairingApproval {
+                // Leave the status text + request id intact so onboarding can guide the user.
+                return
+            }
+
             await MainActor.run {
                 self.gatewayStatusText = "Offline"
                 self.gatewayServerName = nil
@@ -1757,7 +1866,7 @@ private extension NodeAppModel {
             clientId: clientId,
             clientMode: "ui",
             clientDisplayName: displayName,
-            includeDeviceIdentity: false)
+            includeDeviceIdentity: true)
     }
 
     func legacyClientIdFallback(currentClientId: String, error: Error) -> String? {
@@ -1775,6 +1884,17 @@ private extension NodeAppModel {
     }
 }
 
+extension NodeAppModel {
+    func reloadTalkConfig() {
+        Task { [weak self] in
+            await self?.talkMode.reloadConfig()
+        }
+    }
+
+    /// Back-compat hook retained for older gateway-connect flows.
+    func onNodeGatewayConnected() async {}
+}
+
 #if DEBUG
 extension NodeAppModel {
     func _test_handleInvoke(_ req: BridgeInvokeRequest) async -> BridgeInvokeResponse {
@@ -1808,5 +1928,9 @@ extension NodeAppModel {
     func _test_showLocalCanvasOnDisconnect() {
         self.showLocalCanvasOnDisconnect()
     }
+
+    func _test_applyTalkModeSync(enabled: Bool, phase: String? = nil) {
+        self.applyTalkModeSync(enabled: enabled, phase: phase)
+    }
 }
 #endif

apps/ios/Sources/Onboarding/GatewayOnboardingView.swift

@@ -257,15 +257,6 @@ private struct ManualEntryStep: View {
         self.manualPassword = ""
     }
 
-    private struct SetupPayload: Codable {
-        var url: String?
-        var host: String?
-        var port: Int?
-        var tls: Bool?
-        var token: String?
-        var password: String?
-    }
-
     private func applySetupCode() {
         let raw = self.setupCode.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !raw.isEmpty else {
@@ -273,7 +264,7 @@ private struct ManualEntryStep: View {
             return
         }
 
-        guard let payload = self.decodeSetupPayload(raw: raw) else {
+        guard let payload = GatewaySetupCode.decode(raw: raw) else {
             self.setupStatusText = "Setup code not recognized."
             return
         }
@@ -323,34 +314,7 @@ private struct ManualEntryStep: View {
         }
     }
 
-    private func decodeSetupPayload(raw: String) -> SetupPayload? {
-        if let payload = decodeSetupPayloadFromJSON(raw) {
-            return payload
-        }
-        if let decoded = decodeBase64Payload(raw),
-           let payload = decodeSetupPayloadFromJSON(decoded)
-        {
-            return payload
-        }
-        return nil
-    }
-
-    private func decodeSetupPayloadFromJSON(_ json: String) -> SetupPayload? {
-        guard let data = json.data(using: .utf8) else { return nil }
-        return try? JSONDecoder().decode(SetupPayload.self, from: data)
-    }
-
-    private func decodeBase64Payload(_ raw: String) -> String? {
-        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return nil }
-        let normalized = trimmed
-            .replacingOccurrences(of: "-", with: "+")
-            .replacingOccurrences(of: "_", with: "/")
-        let padding = normalized.count % 4
-        let padded = padding == 0 ? normalized : normalized + String(repeating: "=", count: 4 - padding)
-        guard let data = Data(base64Encoded: padded) else { return nil }
-        return String(data: data, encoding: .utf8)
-    }
+    // (GatewaySetupCode) decode raw setup codes.
 }
 
 private struct ConnectionStatusBox: View {

apps/ios/Sources/Onboarding/OnboardingStateStore.swift

@@ -0,0 +1,52 @@
+import Foundation
+
+enum OnboardingConnectionMode: String, CaseIterable {
+    case homeNetwork = "home_network"
+    case remoteDomain = "remote_domain"
+    case developerLocal = "developer_local"
+
+    var title: String {
+        switch self {
+        case .homeNetwork:
+            "Home Network"
+        case .remoteDomain:
+            "Remote Domain"
+        case .developerLocal:
+            "Same Machine (Dev)"
+        }
+    }
+}
+
+enum OnboardingStateStore {
+    private static let completedDefaultsKey = "onboarding.completed"
+    private static let lastModeDefaultsKey = "onboarding.last_mode"
+    private static let lastSuccessTimeDefaultsKey = "onboarding.last_success_time"
+
+    @MainActor
+    static func shouldPresentOnLaunch(appModel: NodeAppModel, defaults: UserDefaults = .standard) -> Bool {
+        if defaults.bool(forKey: Self.completedDefaultsKey) { return false }
+        // If we have a last-known connection config, don't force onboarding on launch. Auto-connect
+        // should handle reconnecting, and users can always open onboarding manually if needed.
+        if GatewaySettingsStore.loadLastGatewayConnection() != nil { return false }
+        return appModel.gatewayServerName == nil
+    }
+
+    static func markCompleted(mode: OnboardingConnectionMode? = nil, defaults: UserDefaults = .standard) {
+        defaults.set(true, forKey: Self.completedDefaultsKey)
+        if let mode {
+            defaults.set(mode.rawValue, forKey: Self.lastModeDefaultsKey)
+        }
+        defaults.set(Int(Date().timeIntervalSince1970), forKey: Self.lastSuccessTimeDefaultsKey)
+    }
+
+    static func markIncomplete(defaults: UserDefaults = .standard) {
+        defaults.set(false, forKey: Self.completedDefaultsKey)
+    }
+
+    static func lastMode(defaults: UserDefaults = .standard) -> OnboardingConnectionMode? {
+        let raw = defaults.string(forKey: Self.lastModeDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !raw.isEmpty else { return nil }
+        return OnboardingConnectionMode(rawValue: raw)
+    }
+}

apps/ios/Sources/Onboarding/OnboardingWizardView.swift

@@ -0,0 +1,852 @@
+import CoreImage
+import OpenClawKit
+import PhotosUI
+import SwiftUI
+import UIKit
+
+private enum OnboardingStep: Int, CaseIterable {
+    case welcome
+    case mode
+    case connect
+    case auth
+    case success
+
+    var previous: Self? {
+        Self(rawValue: self.rawValue - 1)
+    }
+
+    var next: Self? {
+        Self(rawValue: self.rawValue + 1)
+    }
+
+    /// Progress label for the manual setup flow (mode → connect → auth → success).
+    var manualProgressTitle: String {
+        let manualSteps: [OnboardingStep] = [.mode, .connect, .auth, .success]
+        guard let idx = manualSteps.firstIndex(of: self) else { return "" }
+        return "Step \(idx + 1) of \(manualSteps.count)"
+    }
+
+    var title: String {
+        switch self {
+        case .welcome: "Welcome"
+        case .mode: "Connection Mode"
+        case .connect: "Connect"
+        case .auth: "Authentication"
+        case .success: "Connected"
+        }
+    }
+
+    var canGoBack: Bool {
+        self != .welcome && self != .success
+    }
+}
+
+struct OnboardingWizardView: View {
+    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+    @Environment(GatewayConnectionController.self) private var gatewayController: GatewayConnectionController
+    @AppStorage("node.instanceId") private var instanceId: String = UUID().uuidString
+    @AppStorage("gateway.discovery.domain") private var discoveryDomain: String = ""
+    @AppStorage("onboarding.developerMode") private var developerModeEnabled: Bool = false
+    @State private var step: OnboardingStep = .welcome
+    @State private var selectedMode: OnboardingConnectionMode?
+    @State private var manualHost: String = ""
+    @State private var manualPort: Int = 18789
+    @State private var manualPortText: String = "18789"
+    @State private var manualTLS: Bool = true
+    @State private var gatewayToken: String = ""
+    @State private var gatewayPassword: String = ""
+    @State private var connectMessage: String?
+    @State private var statusLine: String = "Scan the QR code from your gateway to connect."
+    @State private var connectingGatewayID: String?
+    @State private var issue: GatewayConnectionIssue = .none
+    @State private var didMarkCompleted = false
+    @State private var didAutoPresentQR = false
+    @State private var pairingRequestId: String?
+    @State private var discoveryRestartTask: Task<Void, Never>?
+    @State private var showQRScanner: Bool = false
+    @State private var scannerError: String?
+    @State private var selectedPhoto: PhotosPickerItem?
+
+    let allowSkip: Bool
+    let onClose: () -> Void
+
+    private var isFullScreenStep: Bool {
+        self.step == .welcome || self.step == .success
+    }
+
+    var body: some View {
+        NavigationStack {
+            Group {
+                switch self.step {
+                case .welcome:
+                    self.welcomeStep
+                case .success:
+                    self.successStep
+                default:
+                    Form {
+                        switch self.step {
+                        case .mode:
+                            self.modeStep
+                        case .connect:
+                            self.connectStep
+                        case .auth:
+                            self.authStep
+                        default:
+                            EmptyView()
+                        }
+                    }
+                    .scrollDismissesKeyboard(.interactively)
+                }
+            }
+            .navigationTitle(self.isFullScreenStep ? "" : self.step.title)
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                if !self.isFullScreenStep {
+                    ToolbarItem(placement: .principal) {
+                        VStack(spacing: 2) {
+                            Text(self.step.title)
+                                .font(.headline)
+                            Text(self.step.manualProgressTitle)
+                                .font(.caption2)
+                                .foregroundStyle(.secondary)
+                        }
+                    }
+                }
+                ToolbarItem(placement: .topBarLeading) {
+                    if self.step.canGoBack {
+                        Button {
+                            self.navigateBack()
+                        } label: {
+                            Label("Back", systemImage: "chevron.left")
+                        }
+                    } else if self.allowSkip {
+                        Button("Close") {
+                            self.onClose()
+                        }
+                    }
+                }
+                ToolbarItemGroup(placement: .keyboard) {
+                    Spacer()
+                    Button("Done") {
+                        UIApplication.shared.sendAction(
+                            #selector(UIResponder.resignFirstResponder),
+                            to: nil, from: nil, for: nil)
+                    }
+                }
+            }
+        }
+        .gatewayTrustPromptAlert()
+        .alert("QR Scanner Unavailable", isPresented: Binding(
+            get: { self.scannerError != nil },
+            set: { if !$0 { self.scannerError = nil } }
+        )) {
+            Button("OK", role: .cancel) {}
+        } message: {
+            Text(self.scannerError ?? "")
+        }
+        .sheet(isPresented: self.$showQRScanner) {
+            NavigationStack {
+                QRScannerView(
+                    onGatewayLink: { link in
+                        self.handleScannedLink(link)
+                    },
+                    onError: { error in
+                        self.showQRScanner = false
+                        self.statusLine = "Scanner error: \(error)"
+                        self.scannerError = error
+                    },
+                    onDismiss: {
+                        self.showQRScanner = false
+                    })
+                    .ignoresSafeArea()
+                    .navigationTitle("Scan QR Code")
+                    .navigationBarTitleDisplayMode(.inline)
+                    .toolbar {
+                        ToolbarItem(placement: .topBarLeading) {
+                            Button("Cancel") { self.showQRScanner = false }
+                        }
+                        ToolbarItem(placement: .topBarTrailing) {
+                            PhotosPicker(selection: self.$selectedPhoto, matching: .images) {
+                                Label("Photos", systemImage: "photo")
+                            }
+                        }
+                    }
+            }
+            .onChange(of: self.selectedPhoto) { _, newValue in
+                guard let item = newValue else { return }
+                self.selectedPhoto = nil
+                Task {
+                    guard let data = try? await item.loadTransferable(type: Data.self) else {
+                        self.showQRScanner = false
+                        self.scannerError = "Could not load the selected image."
+                        return
+                    }
+                    if let message = self.detectQRCode(from: data) {
+                        if let link = GatewayConnectDeepLink.fromSetupCode(message) {
+                            self.handleScannedLink(link)
+                            return
+                        }
+                        if let url = URL(string: message),
+                           let route = DeepLinkParser.parse(url),
+                           case let .gateway(link) = route
+                        {
+                            self.handleScannedLink(link)
+                            return
+                        }
+                    }
+                    self.showQRScanner = false
+                    self.scannerError = "No valid QR code found in the selected image."
+                }
+            }
+        }
+        .onAppear {
+            self.initializeState()
+        }
+        .onDisappear {
+            self.discoveryRestartTask?.cancel()
+            self.discoveryRestartTask = nil
+        }
+        .onChange(of: self.discoveryDomain) { _, _ in
+            self.scheduleDiscoveryRestart()
+        }
+        .onChange(of: self.manualPortText) { _, newValue in
+            let digits = newValue.filter(\.isNumber)
+            if digits != newValue {
+                self.manualPortText = digits
+                return
+            }
+            guard let parsed = Int(digits), parsed > 0 else {
+                self.manualPort = 0
+                return
+            }
+            self.manualPort = min(parsed, 65535)
+        }
+        .onChange(of: self.manualPort) { _, newValue in
+            let normalized = newValue > 0 ? String(newValue) : ""
+            if self.manualPortText != normalized {
+                self.manualPortText = normalized
+            }
+        }
+        .onChange(of: self.gatewayToken) { _, newValue in
+            self.saveGatewayCredentials(token: newValue, password: self.gatewayPassword)
+        }
+        .onChange(of: self.gatewayPassword) { _, newValue in
+            self.saveGatewayCredentials(token: self.gatewayToken, password: newValue)
+        }
+        .onChange(of: self.appModel.gatewayStatusText) { _, newValue in
+            let next = GatewayConnectionIssue.detect(from: newValue)
+            // Avoid "flip-flopping" the UI by clearing actionable issues when the underlying connection
+            // transitions through intermediate statuses (e.g. Offline/Connecting while reconnect churns).
+            if self.issue.needsPairing, next.needsPairing {
+                // Keep the requestId sticky even if the status line omits it after we pause.
+                let mergedRequestId = next.requestId ?? self.issue.requestId ?? self.pairingRequestId
+                self.issue = .pairingRequired(requestId: mergedRequestId)
+            } else if self.issue.needsPairing, !next.needsPairing {
+                // Ignore non-pairing statuses until the user explicitly retries/scans again, or we connect.
+            } else if self.issue.needsAuthToken, !next.needsAuthToken, !next.needsPairing {
+                // Same idea for auth: once we learn credentials are missing/rejected, keep that sticky until
+                // the user retries/scans again or we successfully connect.
+            } else {
+                self.issue = next
+            }
+
+            if let requestId = next.requestId, !requestId.isEmpty {
+                self.pairingRequestId = requestId
+            }
+
+            // If the gateway tells us auth is missing/rejected, stop reconnect churn until the user intervenes.
+            if next.needsAuthToken {
+                self.appModel.gatewayAutoReconnectEnabled = false
+            }
+
+            if self.issue.needsAuthToken || self.issue.needsPairing {
+                self.step = .auth
+            }
+            if !newValue.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                self.connectMessage = newValue
+                self.statusLine = newValue
+            }
+        }
+        .onChange(of: self.appModel.gatewayServerName) { _, newValue in
+            guard newValue != nil else { return }
+            self.statusLine = "Connected."
+            if !self.didMarkCompleted, let selectedMode {
+                OnboardingStateStore.markCompleted(mode: selectedMode)
+                self.didMarkCompleted = true
+            }
+            self.onClose()
+        }
+    }
+
+    @ViewBuilder
+    private var welcomeStep: some View {
+        VStack(spacing: 0) {
+            Spacer()
+
+            Image(systemName: "qrcode.viewfinder")
+                .font(.system(size: 64))
+                .foregroundStyle(.tint)
+                .padding(.bottom, 20)
+
+            Text("Welcome")
+                .font(.largeTitle.weight(.bold))
+                .padding(.bottom, 8)
+
+            Text("Connect to your OpenClaw gateway")
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+                .padding(.horizontal, 32)
+
+            Spacer()
+
+            VStack(spacing: 12) {
+                Button {
+                    self.statusLine = "Opening QR scanner…"
+                    self.showQRScanner = true
+                } label: {
+                    Label("Scan QR Code", systemImage: "qrcode")
+                        .frame(maxWidth: .infinity)
+                }
+                .buttonStyle(.borderedProminent)
+                .controlSize(.large)
+
+                Button {
+                    self.step = .mode
+                } label: {
+                    Text("Set Up Manually")
+                        .frame(maxWidth: .infinity)
+                }
+                .buttonStyle(.bordered)
+                .controlSize(.large)
+            }
+            .padding(.bottom, 12)
+
+            Text(self.statusLine)
+                .font(.footnote)
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+                .padding(.horizontal, 24)
+            .padding(.horizontal, 24)
+            .padding(.bottom, 48)
+        }
+    }
+
+    @ViewBuilder
+    private var modeStep: some View {
+        Section("Connection Mode") {
+            OnboardingModeRow(
+                title: OnboardingConnectionMode.homeNetwork.title,
+                subtitle: "LAN or Tailscale host",
+                selected: self.selectedMode == .homeNetwork)
+            {
+                self.selectMode(.homeNetwork)
+            }
+
+            OnboardingModeRow(
+                title: OnboardingConnectionMode.remoteDomain.title,
+                subtitle: "VPS with domain",
+                selected: self.selectedMode == .remoteDomain)
+            {
+                self.selectMode(.remoteDomain)
+            }
+
+            Toggle(
+                "Developer mode",
+                isOn: Binding(
+                    get: { self.developerModeEnabled },
+                    set: { newValue in
+                        self.developerModeEnabled = newValue
+                        if !newValue, self.selectedMode == .developerLocal {
+                            self.selectedMode = nil
+                        }
+                    }))
+
+            if self.developerModeEnabled {
+                OnboardingModeRow(
+                    title: OnboardingConnectionMode.developerLocal.title,
+                    subtitle: "For local iOS app development",
+                    selected: self.selectedMode == .developerLocal)
+                {
+                    self.selectMode(.developerLocal)
+                }
+            }
+        }
+
+        Section {
+            Button("Continue") {
+                self.step = .connect
+            }
+            .disabled(self.selectedMode == nil)
+        }
+    }
+
+    @ViewBuilder
+    private var connectStep: some View {
+        if let selectedMode {
+            Section {
+                LabeledContent("Mode", value: selectedMode.title)
+                LabeledContent("Discovery", value: self.gatewayController.discoveryStatusText)
+                LabeledContent("Status", value: self.appModel.gatewayStatusText)
+                LabeledContent("Progress", value: self.statusLine)
+            } header: {
+                Text("Status")
+            } footer: {
+                if let connectMessage {
+                    Text(connectMessage)
+                }
+            }
+
+            switch selectedMode {
+            case .homeNetwork:
+                self.homeNetworkConnectSection
+            case .remoteDomain:
+                self.remoteDomainConnectSection
+            case .developerLocal:
+                self.developerConnectSection
+            }
+        } else {
+            Section {
+                Text("Choose a mode first.")
+                Button("Back to Mode Selection") {
+                    self.step = .mode
+                }
+            }
+        }
+    }
+
+    private var homeNetworkConnectSection: some View {
+        Group {
+            Section("Discovered Gateways") {
+                if self.gatewayController.gateways.isEmpty {
+                    Text("No gateways found yet.")
+                        .foregroundStyle(.secondary)
+                } else {
+                    ForEach(self.gatewayController.gateways) { gateway in
+                        let hasHost = self.gatewayHasResolvableHost(gateway)
+
+                        HStack {
+                            VStack(alignment: .leading, spacing: 4) {
+                                Text(gateway.name)
+                                if let host = gateway.lanHost ?? gateway.tailnetDns {
+                                    Text(host)
+                                        .font(.footnote)
+                                        .foregroundStyle(.secondary)
+                                }
+                            }
+                            Spacer()
+                            Button {
+                                Task { await self.connectDiscoveredGateway(gateway) }
+                            } label: {
+                                if self.connectingGatewayID == gateway.id {
+                                    ProgressView()
+                                        .progressViewStyle(.circular)
+                                } else if !hasHost {
+                                    Text("Resolving…")
+                                } else {
+                                    Text("Connect")
+                                }
+                            }
+                            .disabled(self.connectingGatewayID != nil || !hasHost)
+                        }
+                    }
+                }
+
+                Button("Restart Discovery") {
+                    self.gatewayController.restartDiscovery()
+                }
+                .disabled(self.connectingGatewayID != nil)
+            }
+
+            self.manualConnectionFieldsSection(title: "Manual Fallback")
+        }
+    }
+
+    private var remoteDomainConnectSection: some View {
+        self.manualConnectionFieldsSection(title: "Domain Settings")
+    }
+
+    private var developerConnectSection: some View {
+        Section {
+            TextField("Host", text: self.$manualHost)
+                .textInputAutocapitalization(.never)
+                .autocorrectionDisabled()
+            TextField("Port", text: self.$manualPortText)
+                .keyboardType(.numberPad)
+            Toggle("Use TLS", isOn: self.$manualTLS)
+
+            Button {
+                Task { await self.connectManual() }
+            } label: {
+                if self.connectingGatewayID == "manual" {
+                    HStack(spacing: 8) {
+                        ProgressView()
+                            .progressViewStyle(.circular)
+                        Text("Connecting…")
+                    }
+                } else {
+                    Text("Connect")
+                }
+            }
+            .disabled(!self.canConnectManual || self.connectingGatewayID != nil)
+        } header: {
+            Text("Developer Local")
+        } footer: {
+            Text("Default host is localhost. Use your Mac LAN IP if simulator networking requires it.")
+        }
+    }
+
+    private var authStep: some View {
+        Group {
+            Section("Authentication") {
+                TextField("Gateway Auth Token", text: self.$gatewayToken)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+                SecureField("Gateway Password", text: self.$gatewayPassword)
+
+                if self.issue.needsAuthToken {
+                    Text("Gateway rejected credentials. Scan a fresh QR code or update token/password.")
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                } else {
+                    Text("Auth token looks valid.")
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+            }
+
+            if self.issue.needsPairing {
+                Section {
+                    Button("Copy: openclaw devices list") {
+                        UIPasteboard.general.string = "openclaw devices list"
+                    }
+
+                    if let id = self.issue.requestId {
+                        Button("Copy: openclaw devices approve \(id)") {
+                            UIPasteboard.general.string = "openclaw devices approve \(id)"
+                        }
+                    } else {
+                        Button("Copy: openclaw devices approve <requestId>") {
+                            UIPasteboard.general.string = "openclaw devices approve <requestId>"
+                        }
+                    }
+                } header: {
+                    Text("Pairing Approval")
+                } footer: {
+                    Text("Approve this device on the gateway, then tap \"Resume After Approval\" below.")
+                }
+            }
+
+            Section {
+                Button {
+                    Task { await self.retryLastAttempt() }
+                } label: {
+                    if self.connectingGatewayID == "retry" {
+                        ProgressView()
+                            .progressViewStyle(.circular)
+                    } else {
+                        Text("Retry Connection")
+                    }
+                }
+                .disabled(self.connectingGatewayID != nil)
+
+                Button {
+                    self.resumeAfterPairingApproval()
+                } label: {
+                    Label("Resume After Approval", systemImage: "arrow.clockwise")
+                }
+                .disabled(self.connectingGatewayID != nil || !self.issue.needsPairing)
+
+                Button {
+                    self.openQRScannerFromOnboarding()
+                } label: {
+                    Label("Scan QR Code Again", systemImage: "qrcode.viewfinder")
+                }
+                .disabled(self.connectingGatewayID != nil)
+            }
+        }
+    }
+
+    private var successStep: some View {
+        VStack(spacing: 0) {
+            Spacer()
+
+            Image(systemName: "checkmark.circle.fill")
+                .font(.system(size: 64))
+                .foregroundStyle(.green)
+                .padding(.bottom, 20)
+
+            Text("Connected")
+                .font(.largeTitle.weight(.bold))
+                .padding(.bottom, 8)
+
+            let server = self.appModel.gatewayServerName ?? "gateway"
+            Text(server)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+                .padding(.bottom, 4)
+
+            if let addr = self.appModel.gatewayRemoteAddress {
+                Text(addr)
+                    .font(.subheadline)
+                    .foregroundStyle(.secondary)
+            }
+
+            Spacer()
+
+            Button {
+                self.onClose()
+            } label: {
+                Text("Open OpenClaw")
+                    .frame(maxWidth: .infinity)
+            }
+            .buttonStyle(.borderedProminent)
+            .controlSize(.large)
+            .padding(.horizontal, 24)
+            .padding(.bottom, 48)
+        }
+    }
+
+    @ViewBuilder
+    private func manualConnectionFieldsSection(title: String) -> some View {
+        Section(title) {
+            TextField("Host", text: self.$manualHost)
+                .textInputAutocapitalization(.never)
+                .autocorrectionDisabled()
+            TextField("Port", text: self.$manualPortText)
+                .keyboardType(.numberPad)
+            Toggle("Use TLS", isOn: self.$manualTLS)
+            TextField("Discovery Domain (optional)", text: self.$discoveryDomain)
+                .textInputAutocapitalization(.never)
+                .autocorrectionDisabled()
+
+            Button {
+                Task { await self.connectManual() }
+            } label: {
+                if self.connectingGatewayID == "manual" {
+                    HStack(spacing: 8) {
+                        ProgressView()
+                            .progressViewStyle(.circular)
+                        Text("Connecting…")
+                    }
+                } else {
+                    Text("Connect")
+                }
+            }
+            .disabled(!self.canConnectManual || self.connectingGatewayID != nil)
+        }
+    }
+
+    private func handleScannedLink(_ link: GatewayConnectDeepLink) {
+        self.manualHost = link.host
+        self.manualPort = link.port
+        self.manualTLS = link.tls
+        if let token = link.token {
+            self.gatewayToken = token
+        }
+        if let password = link.password {
+            self.gatewayPassword = password
+        }
+        self.saveGatewayCredentials(token: self.gatewayToken, password: self.gatewayPassword)
+        self.showQRScanner = false
+        self.connectMessage = "Connecting via QR code…"
+        self.statusLine = "QR loaded. Connecting to \(link.host):\(link.port)…"
+        if self.selectedMode == nil {
+            self.selectedMode = link.tls ? .remoteDomain : .homeNetwork
+        }
+        Task { await self.connectManual() }
+    }
+
+    private func openQRScannerFromOnboarding() {
+        // Stop active reconnect loops before scanning new credentials.
+        self.appModel.disconnectGateway()
+        self.connectingGatewayID = nil
+        self.connectMessage = nil
+        self.issue = .none
+        self.pairingRequestId = nil
+        self.statusLine = "Opening QR scanner…"
+        self.showQRScanner = true
+    }
+
+    private func resumeAfterPairingApproval() {
+        // We intentionally stop reconnect churn while unpaired to avoid generating multiple pending requests.
+        self.appModel.gatewayAutoReconnectEnabled = true
+        self.appModel.gatewayPairingPaused = false
+        self.connectMessage = "Retrying after approval…"
+        self.statusLine = "Retrying after approval…"
+        Task { await self.retryLastAttempt() }
+    }
+
+    private func detectQRCode(from data: Data) -> String? {
+        guard let ciImage = CIImage(data: data) else { return nil }
+        let detector = CIDetector(
+            ofType: CIDetectorTypeQRCode, context: nil,
+            options: [CIDetectorAccuracy: CIDetectorAccuracyHigh])
+        let features = detector?.features(in: ciImage) ?? []
+        for feature in features {
+            if let qr = feature as? CIQRCodeFeature, let message = qr.messageString {
+                return message
+            }
+        }
+        return nil
+    }
+
+    private func navigateBack() {
+        guard let target = self.step.previous else { return }
+        self.connectingGatewayID = nil
+        self.connectMessage = nil
+        self.step = target
+    }
+    private var canConnectManual: Bool {
+        let host = self.manualHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        return !host.isEmpty && self.manualPort > 0 && self.manualPort <= 65535
+    }
+
+    private func initializeState() {
+        if self.manualHost.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            if let last = GatewaySettingsStore.loadLastGatewayConnection() {
+                switch last {
+                case let .manual(host, port, useTLS, _):
+                    self.manualHost = host
+                    self.manualPort = port
+                    self.manualTLS = useTLS
+                case .discovered:
+                    self.manualHost = "openclaw.local"
+                    self.manualPort = 18789
+                    self.manualTLS = true
+                }
+            } else {
+                self.manualHost = "openclaw.local"
+                self.manualPort = 18789
+                self.manualTLS = true
+            }
+        }
+        self.manualPortText = self.manualPort > 0 ? String(self.manualPort) : ""
+        if self.selectedMode == nil {
+            self.selectedMode = OnboardingStateStore.lastMode()
+        }
+        if self.selectedMode == .developerLocal && self.manualHost == "openclaw.local" {
+            self.manualHost = "localhost"
+            self.manualTLS = false
+        }
+
+        let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmedInstanceId.isEmpty {
+            self.gatewayToken = GatewaySettingsStore.loadGatewayToken(instanceId: trimmedInstanceId) ?? ""
+            self.gatewayPassword = GatewaySettingsStore.loadGatewayPassword(instanceId: trimmedInstanceId) ?? ""
+        }
+
+        let hasSavedGateway = GatewaySettingsStore.loadLastGatewayConnection() != nil
+        let hasToken = !self.gatewayToken.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        let hasPassword = !self.gatewayPassword.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        if !self.didAutoPresentQR, !hasSavedGateway, !hasToken, !hasPassword {
+            self.didAutoPresentQR = true
+            self.statusLine = "No saved pairing found. Scan QR code to connect."
+            self.showQRScanner = true
+        }
+    }
+
+    private func scheduleDiscoveryRestart() {
+        self.discoveryRestartTask?.cancel()
+        self.discoveryRestartTask = Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 350_000_000)
+            guard !Task.isCancelled else { return }
+            self.gatewayController.restartDiscovery()
+        }
+    }
+
+    private func saveGatewayCredentials(token: String, password: String) {
+        let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedInstanceId.isEmpty else { return }
+        let trimmedToken = token.trimmingCharacters(in: .whitespacesAndNewlines)
+        GatewaySettingsStore.saveGatewayToken(trimmedToken, instanceId: trimmedInstanceId)
+        let trimmedPassword = password.trimmingCharacters(in: .whitespacesAndNewlines)
+        GatewaySettingsStore.saveGatewayPassword(trimmedPassword, instanceId: trimmedInstanceId)
+    }
+
+    private func connectDiscoveredGateway(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) async {
+        self.connectingGatewayID = gateway.id
+        self.issue = .none
+        self.connectMessage = "Connecting to \(gateway.name)…"
+        self.statusLine = "Connecting to \(gateway.name)…"
+        defer { self.connectingGatewayID = nil }
+        await self.gatewayController.connect(gateway)
+    }
+
+    private func selectMode(_ mode: OnboardingConnectionMode) {
+        self.selectedMode = mode
+        self.applyModeDefaults(mode)
+    }
+
+    private func applyModeDefaults(_ mode: OnboardingConnectionMode) {
+        let host = self.manualHost.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        let hostIsDefaultLike = host.isEmpty || host == "openclaw.local" || host == "localhost"
+
+        switch mode {
+        case .homeNetwork:
+            if hostIsDefaultLike { self.manualHost = "openclaw.local" }
+            self.manualTLS = true
+            if self.manualPort <= 0 || self.manualPort > 65535 { self.manualPort = 18789 }
+        case .remoteDomain:
+            if host == "openclaw.local" || host == "localhost" { self.manualHost = "" }
+            self.manualTLS = true
+            if self.manualPort <= 0 || self.manualPort > 65535 { self.manualPort = 18789 }
+        case .developerLocal:
+            if hostIsDefaultLike { self.manualHost = "localhost" }
+            self.manualTLS = false
+            if self.manualPort <= 0 || self.manualPort > 65535 { self.manualPort = 18789 }
+        }
+    }
+
+    private func gatewayHasResolvableHost(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) -> Bool {
+        let lanHost = gateway.lanHost?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !lanHost.isEmpty { return true }
+        let tailnetDns = gateway.tailnetDns?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return !tailnetDns.isEmpty
+    }
+
+    private func connectManual() async {
+        let host = self.manualHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !host.isEmpty, self.manualPort > 0, self.manualPort <= 65535 else { return }
+        self.connectingGatewayID = "manual"
+        self.issue = .none
+        self.connectMessage = "Connecting to \(host)…"
+        self.statusLine = "Connecting to \(host):\(self.manualPort)…"
+        defer { self.connectingGatewayID = nil }
+        await self.gatewayController.connectManual(host: host, port: self.manualPort, useTLS: self.manualTLS)
+    }
+
+    private func retryLastAttempt() async {
+        self.connectingGatewayID = "retry"
+        self.issue = .none
+        self.connectMessage = "Retrying…"
+        self.statusLine = "Retrying last connection…"
+        defer { self.connectingGatewayID = nil }
+        await self.gatewayController.connectLastKnown()
+    }
+}
+
+private struct OnboardingModeRow: View {
+    let title: String
+    let subtitle: String
+    let selected: Bool
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: self.action) {
+            HStack {
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(self.title)
+                        .font(.body.weight(.semibold))
+                    Text(self.subtitle)
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer()
+                Image(systemName: self.selected ? "checkmark.circle.fill" : "circle")
+                    .foregroundStyle(self.selected ? Color.accentColor : Color.secondary)
+            }
+        }
+        .buttonStyle(.plain)
+    }
+}

apps/ios/Sources/Onboarding/QRScannerView.swift

@@ -0,0 +1,96 @@
+import OpenClawKit
+import SwiftUI
+import VisionKit
+
+struct QRScannerView: UIViewControllerRepresentable {
+    let onGatewayLink: (GatewayConnectDeepLink) -> Void
+    let onError: (String) -> Void
+    let onDismiss: () -> Void
+
+    func makeUIViewController(context: Context) -> UIViewController {
+        guard DataScannerViewController.isSupported else {
+            context.coordinator.reportError("QR scanning is not supported on this device.")
+            return UIViewController()
+        }
+        guard DataScannerViewController.isAvailable else {
+            context.coordinator.reportError("Camera scanning is currently unavailable.")
+            return UIViewController()
+        }
+        let scanner = DataScannerViewController(
+            recognizedDataTypes: [.barcode(symbologies: [.qr])],
+            isHighlightingEnabled: true)
+        scanner.delegate = context.coordinator
+        do {
+            try scanner.startScanning()
+        } catch {
+            context.coordinator.reportError("Could not start QR scanner.")
+        }
+        return scanner
+    }
+
+    func updateUIViewController(_: UIViewController, context _: Context) {}
+
+    static func dismantleUIViewController(_ uiViewController: UIViewController, coordinator: Coordinator) {
+        if let scanner = uiViewController as? DataScannerViewController {
+            scanner.stopScanning()
+        }
+        coordinator.parent.onDismiss()
+    }
+
+    func makeCoordinator() -> Coordinator {
+        Coordinator(parent: self)
+    }
+
+    final class Coordinator: NSObject, DataScannerViewControllerDelegate {
+        let parent: QRScannerView
+        private var handled = false
+        private var reportedError = false
+
+        init(parent: QRScannerView) {
+            self.parent = parent
+        }
+
+        func reportError(_ message: String) {
+            guard !self.reportedError else { return }
+            self.reportedError = true
+            Task { @MainActor in
+                self.parent.onError(message)
+            }
+        }
+
+        func dataScanner(_: DataScannerViewController, didAdd items: [RecognizedItem], allItems _: [RecognizedItem]) {
+            guard !self.handled else { return }
+            for item in items {
+                guard case let .barcode(barcode) = item,
+                      let payload = barcode.payloadStringValue
+                else { continue }
+
+                // Try setup code format first (base64url JSON from /pair qr).
+                if let link = GatewayConnectDeepLink.fromSetupCode(payload) {
+                    self.handled = true
+                    self.parent.onGatewayLink(link)
+                    return
+                }
+
+                // Fall back to deep link URL format (openclaw://gateway?...).
+                if let url = URL(string: payload),
+                   let route = DeepLinkParser.parse(url),
+                   case let .gateway(link) = route
+                {
+                    self.handled = true
+                    self.parent.onGatewayLink(link)
+                    return
+                }
+            }
+        }
+
+        func dataScanner(_: DataScannerViewController, didRemove _: [RecognizedItem], allItems _: [RecognizedItem]) {}
+
+        func dataScanner(
+            _: DataScannerViewController,
+            becameUnavailableWithError _: DataScannerViewController.ScanningUnavailable)
+        {
+            self.reportError("Camera is not available on this device.")
+        }
+    }
+}

apps/ios/Sources/OpenClawApp.swift

@@ -1,4 +1,5 @@
 import SwiftUI
+import Foundation
 
 @main
 struct OpenClawApp: App {
@@ -7,6 +8,7 @@ struct OpenClawApp: App {
     @Environment(\.scenePhase) private var scenePhase
 
     init() {
+        Self.installUncaughtExceptionLogger()
         GatewaySettingsStore.bootstrapPersistence()
         let appModel = NodeAppModel()
         _appModel = State(initialValue: appModel)
@@ -29,3 +31,18 @@ struct OpenClawApp: App {
         }
     }
 }
+
+extension OpenClawApp {
+    private static func installUncaughtExceptionLogger() {
+        NSLog("OpenClaw: installing uncaught exception handler")
+        NSSetUncaughtExceptionHandler { exception in
+            // Useful when the app hits NSExceptions from SwiftUI/WebKit internals; these do not
+            // produce a normal Swift error backtrace.
+            let reason = exception.reason ?? "(no reason)"
+            NSLog("UNCAUGHT EXCEPTION: %@ %@", exception.name.rawValue, reason)
+            for line in exception.callStackSymbols {
+                NSLog("  %@", line)
+            }
+        }
+    }
+}

apps/ios/Sources/Reminders/RemindersService.swift

@@ -6,7 +6,7 @@ final class RemindersService: RemindersServicing {
     func list(params: OpenClawRemindersListParams) async throws -> OpenClawRemindersListPayload {
         let store = EKEventStore()
         let status = EKEventStore.authorizationStatus(for: .reminder)
-        let authorized = await Self.ensureAuthorization(store: store, status: status)
+        let authorized = EventKitAuthorization.allowsRead(status: status)
         guard authorized else {
             throw NSError(domain: "Reminders", code: 1, userInfo: [
                 NSLocalizedDescriptionKey: "REMINDERS_PERMISSION_REQUIRED: grant Reminders permission",
@@ -50,7 +50,7 @@ final class RemindersService: RemindersServicing {
     func add(params: OpenClawRemindersAddParams) async throws -> OpenClawRemindersAddPayload {
         let store = EKEventStore()
         let status = EKEventStore.authorizationStatus(for: .reminder)
-        let authorized = await Self.ensureWriteAuthorization(store: store, status: status)
+        let authorized = EventKitAuthorization.allowsWrite(status: status)
         guard authorized else {
             throw NSError(domain: "Reminders", code: 2, userInfo: [
                 NSLocalizedDescriptionKey: "REMINDERS_PERMISSION_REQUIRED: grant Reminders permission",
@@ -100,38 +100,6 @@ final class RemindersService: RemindersServicing {
         return OpenClawRemindersAddPayload(reminder: payload)
     }
 
-    private static func ensureAuthorization(store: EKEventStore, status: EKAuthorizationStatus) async -> Bool {
-        switch status {
-        case .authorized:
-            return true
-        case .notDetermined:
-            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
-            return false
-        case .restricted, .denied:
-            return false
-        case .fullAccess:
-            return true
-        case .writeOnly:
-            return false
-        @unknown default:
-            return false
-        }
-    }
-
-    private static func ensureWriteAuthorization(store: EKEventStore, status: EKAuthorizationStatus) async -> Bool {
-        switch status {
-        case .authorized, .fullAccess, .writeOnly:
-            return true
-        case .notDetermined:
-            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
-            return false
-        case .restricted, .denied:
-            return false
-        @unknown default:
-            return false
-        }
-    }
-
     private static func resolveList(
         store: EKEventStore,
         listId: String?,

apps/ios/Sources/RootCanvas.swift

@@ -3,34 +3,69 @@ import UIKit
 
 struct RootCanvas: View {
     @Environment(NodeAppModel.self) private var appModel
+    @Environment(GatewayConnectionController.self) private var gatewayController
     @Environment(VoiceWakeManager.self) private var voiceWake
     @Environment(\.colorScheme) private var systemColorScheme
     @Environment(\.scenePhase) private var scenePhase
     @AppStorage(VoiceWakePreferences.enabledKey) private var voiceWakeEnabled: Bool = false
     @AppStorage("screen.preventSleep") private var preventSleep: Bool = true
     @AppStorage("canvas.debugStatusEnabled") private var canvasDebugStatusEnabled: Bool = false
+    @AppStorage("onboarding.requestID") private var onboardingRequestID: Int = 0
     @AppStorage("gateway.onboardingComplete") private var onboardingComplete: Bool = false
     @AppStorage("gateway.hasConnectedOnce") private var hasConnectedOnce: Bool = false
     @AppStorage("gateway.preferredStableID") private var preferredGatewayStableID: String = ""
     @AppStorage("gateway.manual.enabled") private var manualGatewayEnabled: Bool = false
     @AppStorage("gateway.manual.host") private var manualGatewayHost: String = ""
+    @AppStorage("onboarding.quickSetupDismissed") private var quickSetupDismissed: Bool = false
     @State private var presentedSheet: PresentedSheet?
     @State private var voiceWakeToastText: String?
     @State private var toastDismissTask: Task<Void, Never>?
+    @State private var showOnboarding: Bool = false
+    @State private var onboardingAllowSkip: Bool = true
+    @State private var didEvaluateOnboarding: Bool = false
     @State private var didAutoOpenSettings: Bool = false
 
     private enum PresentedSheet: Identifiable {
         case settings
         case chat
+        case quickSetup
 
         var id: Int {
             switch self {
             case .settings: 0
             case .chat: 1
+            case .quickSetup: 2
             }
         }
     }
 
+    enum StartupPresentationRoute: Equatable {
+        case none
+        case onboarding
+        case settings
+    }
+
+    static func startupPresentationRoute(
+        gatewayConnected: Bool,
+        hasConnectedOnce: Bool,
+        onboardingComplete: Bool,
+        hasExistingGatewayConfig: Bool,
+        shouldPresentOnLaunch: Bool) -> StartupPresentationRoute
+    {
+        if gatewayConnected {
+            return .none
+        }
+        // On first run or explicit launch onboarding state, onboarding always wins.
+        if shouldPresentOnLaunch || !hasConnectedOnce || !onboardingComplete {
+            return .onboarding
+        }
+        // Settings auto-open is a recovery path for previously-connected installs only.
+        if !hasExistingGatewayConfig {
+            return .settings
+        }
+        return .none
+    }
+
     var body: some View {
         ZStack {
             CanvasContent(
@@ -57,27 +92,58 @@ struct RootCanvas: View {
             switch sheet {
             case .settings:
                 SettingsTab()
+                    .environment(self.appModel)
+                    .environment(self.appModel.voiceWake)
+                    .environment(self.gatewayController)
             case .chat:
                 ChatSheet(
-                    gateway: self.appModel.operatorSession,
+                    // Mobile chat UI should use the node role RPC surface (chat.* / sessions.*)
+                    // to avoid requiring operator scopes like operator.read.
+                    gateway: self.appModel.gatewaySession,
                     sessionKey: self.appModel.mainSessionKey,
                     agentName: self.appModel.activeAgentName,
                     userAccent: self.appModel.seamColor)
+            case .quickSetup:
+                GatewayQuickSetupSheet()
+                    .environment(self.appModel)
+                    .environment(self.gatewayController)
             }
         }
+        .fullScreenCover(isPresented: self.$showOnboarding) {
+            OnboardingWizardView(
+                allowSkip: self.onboardingAllowSkip,
+                onClose: {
+                    self.showOnboarding = false
+                })
+                .environment(self.appModel)
+                .environment(self.appModel.voiceWake)
+                .environment(self.gatewayController)
+        }
         .onAppear { self.updateIdleTimer() }
+        .onAppear { self.evaluateOnboardingPresentation(force: false) }
         .onAppear { self.maybeAutoOpenSettings() }
         .onChange(of: self.preventSleep) { _, _ in self.updateIdleTimer() }
         .onChange(of: self.scenePhase) { _, _ in self.updateIdleTimer() }
+        .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.gatewayServerName) { _, newValue in
+            if newValue != nil {
+                self.showOnboarding = false
+            }
+        }
+        .onChange(of: self.onboardingRequestID) { _, _ in
+            self.evaluateOnboardingPresentation(force: true)
+        }
         .onChange(of: self.appModel.gatewayRemoteAddress) { _, _ in self.updateCanvasDebugStatus() }
         .onChange(of: self.appModel.gatewayServerName) { _, newValue in
             if newValue != nil {
                 self.onboardingComplete = true
                 self.hasConnectedOnce = true
+                OnboardingStateStore.markCompleted(mode: nil)
             }
             self.maybeAutoOpenSettings()
         }
@@ -136,11 +202,31 @@ struct RootCanvas: View {
         self.appModel.screen.updateDebugStatus(title: title, subtitle: subtitle)
     }
 
-    private func shouldAutoOpenSettings() -> Bool {
-        if self.appModel.gatewayServerName != nil { return false }
-        if !self.hasConnectedOnce { return true }
-        if !self.onboardingComplete { return true }
-        return !self.hasExistingGatewayConfig()
+    private func evaluateOnboardingPresentation(force: Bool) {
+        if force {
+            self.onboardingAllowSkip = true
+            self.showOnboarding = true
+            return
+        }
+
+        guard !self.didEvaluateOnboarding else { return }
+        self.didEvaluateOnboarding = true
+        let route = Self.startupPresentationRoute(
+            gatewayConnected: self.appModel.gatewayServerName != nil,
+            hasConnectedOnce: self.hasConnectedOnce,
+            onboardingComplete: self.onboardingComplete,
+            hasExistingGatewayConfig: self.hasExistingGatewayConfig(),
+            shouldPresentOnLaunch: OnboardingStateStore.shouldPresentOnLaunch(appModel: self.appModel))
+        switch route {
+        case .none:
+            break
+        case .onboarding:
+            self.onboardingAllowSkip = true
+            self.showOnboarding = true
+        case .settings:
+            self.didAutoOpenSettings = true
+            self.presentedSheet = .settings
+        }
     }
 
     private func hasExistingGatewayConfig() -> Bool {
@@ -151,10 +237,26 @@ struct RootCanvas: View {
 
     private func maybeAutoOpenSettings() {
         guard !self.didAutoOpenSettings else { return }
-        guard self.shouldAutoOpenSettings() else { return }
+        guard !self.showOnboarding else { return }
+        let route = Self.startupPresentationRoute(
+            gatewayConnected: self.appModel.gatewayServerName != nil,
+            hasConnectedOnce: self.hasConnectedOnce,
+            onboardingComplete: self.onboardingComplete,
+            hasExistingGatewayConfig: self.hasExistingGatewayConfig(),
+            shouldPresentOnLaunch: false)
+        guard route == .settings else { return }
         self.didAutoOpenSettings = true
         self.presentedSheet = .settings
     }
+
+    private func maybeShowQuickSetup() {
+        guard !self.quickSetupDismissed else { return }
+        guard !self.showOnboarding else { return }
+        guard self.presentedSheet == nil else { return }
+        guard self.appModel.gatewayServerName == nil else { return }
+        guard !self.gatewayController.gateways.isEmpty else { return }
+        self.presentedSheet = .quickSetup
+    }
 }
 
 private struct CanvasContent: View {

apps/ios/Sources/RootTabs.swift

@@ -3,6 +3,7 @@ import SwiftUI
 struct RootTabs: View {
     @Environment(NodeAppModel.self) private var appModel
     @Environment(VoiceWakeManager.self) private var voiceWake
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
     @AppStorage(VoiceWakePreferences.enabledKey) private var voiceWakeEnabled: Bool = false
     @State private var selectedTab: Int = 0
     @State private var voiceWakeToastText: String?
@@ -52,14 +53,14 @@ struct RootTabs: View {
             guard !trimmed.isEmpty else { return }
 
             self.toastDismissTask?.cancel()
-            withAnimation(.spring(response: 0.25, dampingFraction: 0.85)) {
+            withAnimation(self.reduceMotion ? .none : .spring(response: 0.25, dampingFraction: 0.85)) {
                 self.voiceWakeToastText = trimmed
             }
 
             self.toastDismissTask = Task {
                 try? await Task.sleep(nanoseconds: 2_300_000_000)
                 await MainActor.run {
-                    withAnimation(.easeOut(duration: 0.25)) {
+                    withAnimation(self.reduceMotion ? .none : .easeOut(duration: 0.25)) {
                         self.voiceWakeToastText = nil
                     }
                 }
@@ -104,66 +105,10 @@ struct RootTabs: View {
     }
 
     private var statusActivity: StatusPill.Activity? {
-        // Keep the top pill consistent across tabs (camera + voice wake + pairing states).
-        if self.appModel.isBackgrounded {
-            return StatusPill.Activity(
-                title: "Foreground required",
-                systemImage: "exclamationmark.triangle.fill",
-                tint: .orange)
-        }
-
-        let gatewayStatus = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
-        let gatewayLower = gatewayStatus.lowercased()
-        if gatewayLower.contains("repair") {
-            return StatusPill.Activity(title: "Repairing…", systemImage: "wrench.and.screwdriver", tint: .orange)
-        }
-        if gatewayLower.contains("approval") || gatewayLower.contains("pairing") {
-            return StatusPill.Activity(title: "Approval pending", systemImage: "person.crop.circle.badge.clock")
-        }
-        // Avoid duplicating the primary gateway status ("Connecting…") in the activity slot.
-
-        if self.appModel.screenRecordActive {
-            return StatusPill.Activity(title: "Recording screen…", systemImage: "record.circle.fill", tint: .red)
-        }
-
-        if let cameraHUDText = self.appModel.cameraHUDText,
-           let cameraHUDKind = self.appModel.cameraHUDKind,
-           !cameraHUDText.isEmpty
-        {
-            let systemImage: String
-            let tint: Color?
-            switch cameraHUDKind {
-            case .photo:
-                systemImage = "camera.fill"
-                tint = nil
-            case .recording:
-                systemImage = "video.fill"
-                tint = .red
-            case .success:
-                systemImage = "checkmark.circle.fill"
-                tint = .green
-            case .error:
-                systemImage = "exclamationmark.triangle.fill"
-                tint = .red
-            }
-            return StatusPill.Activity(title: cameraHUDText, systemImage: systemImage, tint: tint)
-        }
-
-        if self.voiceWakeEnabled {
-            let voiceStatus = self.appModel.voiceWake.statusText
-            if voiceStatus.localizedCaseInsensitiveContains("microphone permission") {
-                return StatusPill.Activity(title: "Mic permission", systemImage: "mic.slash", tint: .orange)
-            }
-            if voiceStatus == "Paused" {
-                // Talk mode intentionally pauses voice wake to release the mic. Don't spam the HUD for that case.
-                if self.appModel.talkMode.isEnabled {
-                    return nil
-                }
-                let suffix = self.appModel.isBackgrounded ? " (background)" : ""
-                return StatusPill.Activity(title: "Voice Wake paused\(suffix)", systemImage: "pause.circle.fill")
-            }
-        }
-
-        return nil
+        StatusActivityBuilder.build(
+            appModel: self.appModel,
+            voiceWakeEnabled: self.voiceWakeEnabled,
+            cameraHUDText: self.appModel.cameraHUDText,
+            cameraHUDKind: self.appModel.cameraHUDKind)
     }
 }

apps/ios/Sources/Services/NodeServiceProtocols.swift

@@ -28,6 +28,12 @@ protocol LocationServicing: Sendable {
         desiredAccuracy: OpenClawLocationAccuracy,
         maxAgeMs: Int?,
         timeoutMs: Int?) async throws -> CLLocation
+    func startLocationUpdates(
+        desiredAccuracy: OpenClawLocationAccuracy,
+        significantChangesOnly: Bool) -> AsyncStream<CLLocation>
+    func stopLocationUpdates()
+    func startMonitoringSignificantLocationChanges(onUpdate: @escaping @Sendable (CLLocation) -> Void)
+    func stopMonitoringSignificantLocationChanges()
 }
 
 protocol DeviceStatusServicing: Sendable {

apps/ios/Sources/Settings/SettingsTab.swift

@@ -15,6 +15,8 @@ struct SettingsTab: View {
     @AppStorage("voiceWake.enabled") private var voiceWakeEnabled: Bool = false
     @AppStorage("talk.enabled") private var talkEnabled: Bool = false
     @AppStorage("talk.button.enabled") private var talkButtonEnabled: Bool = true
+    @AppStorage("talk.background.enabled") private var talkBackgroundEnabled: Bool = false
+    @AppStorage("talk.voiceDirectiveHint.enabled") private var talkVoiceDirectiveHintEnabled: Bool = true
     @AppStorage("camera.enabled") private var cameraEnabled: Bool = true
     @AppStorage("location.enabledMode") private var locationEnabledModeRaw: String = OpenClawLocationMode.off.rawValue
     @AppStorage("location.preciseEnabled") private var locationPreciseEnabled: Bool = true
@@ -28,17 +30,27 @@ struct SettingsTab: View {
     @AppStorage("gateway.manual.tls") private var manualGatewayTLS: Bool = true
     @AppStorage("gateway.discovery.debugLogs") private var discoveryDebugLogsEnabled: Bool = false
     @AppStorage("canvas.debugStatusEnabled") private var canvasDebugStatusEnabled: Bool = false
+
+    // Onboarding control (RootCanvas listens to onboarding.requestID and force-opens the wizard).
+    @AppStorage("onboarding.requestID") private var onboardingRequestID: Int = 0
+    @AppStorage("gateway.onboardingComplete") private var onboardingComplete: Bool = false
+    @AppStorage("gateway.hasConnectedOnce") private var hasConnectedOnce: Bool = false
+
     @State private var connectingGatewayID: String?
     @State private var localIPAddress: String?
     @State private var lastLocationModeRaw: String = OpenClawLocationMode.off.rawValue
     @State private var gatewayToken: String = ""
     @State private var gatewayPassword: String = ""
+    @State private var talkElevenLabsApiKey: String = ""
     @AppStorage("gateway.setupCode") private var setupCode: String = ""
     @State private var setupStatusText: String?
     @State private var manualGatewayPortText: String = ""
     @State private var gatewayExpanded: Bool = true
     @State private var selectedAgentPickerId: String = ""
 
+    @State private var showResetOnboardingAlert: Bool = false
+    @State private var suppressCredentialPersist: Bool = false
+
     private let gatewayLogger = Logger(subsystem: "ai.openclaw.ios", category: "GatewaySettings")
 
     var body: some View {
@@ -103,7 +115,6 @@ struct SettingsTab: View {
                                 .foregroundStyle(.secondary)
                         }
 
-                        DisclosureGroup("Advanced") {
                         if self.appModel.gatewayServerName == nil {
                             LabeledContent("Discovery", value: self.gatewayController.discoveryStatusText)
                         }
@@ -148,69 +159,74 @@ struct SettingsTab: View {
                             self.gatewayList(showing: .all)
                         }
 
-                        Toggle("Use Manual Gateway", isOn: self.$manualGatewayEnabled)
+                        DisclosureGroup("Advanced") {
+                            Toggle("Use Manual Gateway", isOn: self.$manualGatewayEnabled)
 
-                        TextField("Host", text: self.$manualGatewayHost)
-                            .textInputAutocapitalization(.never)
-                            .autocorrectionDisabled()
+                            TextField("Host", text: self.$manualGatewayHost)
+                                .textInputAutocapitalization(.never)
+                                .autocorrectionDisabled()
 
-                        TextField("Port (optional)", text: self.manualPortBinding)
-                            .keyboardType(.numberPad)
+                            TextField("Port (optional)", text: self.manualPortBinding)
+                                .keyboardType(.numberPad)
 
-                        Toggle("Use TLS", isOn: self.$manualGatewayTLS)
+                            Toggle("Use TLS", isOn: self.$manualGatewayTLS)
 
-                        Button {
-                            Task { await self.connectManual() }
-                        } label: {
-                            if self.connectingGatewayID == "manual" {
-                                HStack(spacing: 8) {
-                                    ProgressView()
-                                        .progressViewStyle(.circular)
-                                    Text("Connecting…")
+                            Button {
+                                Task { await self.connectManual() }
+                            } label: {
+                                if self.connectingGatewayID == "manual" {
+                                    HStack(spacing: 8) {
+                                        ProgressView()
+                                            .progressViewStyle(.circular)
+                                        Text("Connecting…")
+                                    }
+                                } else {
+                                    Text("Connect (Manual)")
                                 }
-                            } else {
-                                Text("Connect (Manual)")
                             }
-                        }
-                        .disabled(self.connectingGatewayID != nil || self.manualGatewayHost
-                            .trimmingCharacters(in: .whitespacesAndNewlines)
-                            .isEmpty || !self.manualPortIsValid)
+                            .disabled(self.connectingGatewayID != nil || self.manualGatewayHost
+                                .trimmingCharacters(in: .whitespacesAndNewlines)
+                                .isEmpty || !self.manualPortIsValid)
 
-                        Text(
-                            "Use this when mDNS/Bonjour discovery is blocked. "
-                                + "Leave port empty for 443 on tailnet DNS (TLS) or 18789 otherwise.")
-                            .font(.footnote)
-                            .foregroundStyle(.secondary)
+                            Text(
+                                "Use this when mDNS/Bonjour discovery is blocked. "
+                                    + "Leave port empty for 443 on tailnet DNS (TLS) or 18789 otherwise.")
+                                .font(.footnote)
+                                .foregroundStyle(.secondary)
 
-                        Toggle("Discovery Debug Logs", isOn: self.$discoveryDebugLogsEnabled)
-                            .onChange(of: self.discoveryDebugLogsEnabled) { _, newValue in
-                                self.gatewayController.setDiscoveryDebugLoggingEnabled(newValue)
+                            Toggle("Discovery Debug Logs", isOn: self.$discoveryDebugLogsEnabled)
+                                .onChange(of: self.discoveryDebugLogsEnabled) { _, newValue in
+                                    self.gatewayController.setDiscoveryDebugLoggingEnabled(newValue)
+                                }
+
+                            NavigationLink("Discovery Logs") {
+                                GatewayDiscoveryDebugLogView()
                             }
 
-                        NavigationLink("Discovery Logs") {
-                            GatewayDiscoveryDebugLogView()
+                            Toggle("Debug Canvas Status", isOn: self.$canvasDebugStatusEnabled)
+
+                            TextField("Gateway Auth Token", text: self.$gatewayToken)
+                                .textInputAutocapitalization(.never)
+                                .autocorrectionDisabled()
+
+                            SecureField("Gateway Password", text: self.$gatewayPassword)
+
+                            Button("Reset Onboarding", role: .destructive) {
+                                self.showResetOnboardingAlert = true
+                            }
+
+                            VStack(alignment: .leading, spacing: 6) {
+                                Text("Debug")
+                                    .font(.footnote.weight(.semibold))
+                                    .foregroundStyle(.secondary)
+                                Text(self.gatewayDebugText())
+                                    .font(.system(size: 12, weight: .regular, design: .monospaced))
+                                    .foregroundStyle(.secondary)
+                                    .frame(maxWidth: .infinity, alignment: .leading)
+                                    .padding(10)
+                                    .background(.thinMaterial, in: RoundedRectangle(cornerRadius: 10, style: .continuous))
+                            }
                         }
-
-                        Toggle("Debug Canvas Status", isOn: self.$canvasDebugStatusEnabled)
-
-                        TextField("Gateway Token", text: self.$gatewayToken)
-                            .textInputAutocapitalization(.never)
-                            .autocorrectionDisabled()
-
-                        SecureField("Gateway Password", text: self.$gatewayPassword)
-
-                        VStack(alignment: .leading, spacing: 6) {
-                            Text("Debug")
-                                .font(.footnote.weight(.semibold))
-                                .foregroundStyle(.secondary)
-                            Text(self.gatewayDebugText())
-                                .font(.system(size: 12, weight: .regular, design: .monospaced))
-                                .foregroundStyle(.secondary)
-                                .frame(maxWidth: .infinity, alignment: .leading)
-                                .padding(10)
-                                .background(.thinMaterial, in: RoundedRectangle(cornerRadius: 10, style: .continuous))
-                        }
-                    }
                     } label: {
                         HStack(spacing: 10) {
                             Circle()
@@ -235,6 +251,20 @@ struct SettingsTab: View {
                             .onChange(of: self.talkEnabled) { _, newValue in
                                 self.appModel.setTalkEnabled(newValue)
                             }
+                        SecureField("Talk ElevenLabs API Key (optional)", text: self.$talkElevenLabsApiKey)
+                            .textInputAutocapitalization(.never)
+                            .autocorrectionDisabled()
+                        Text("Use this local override when gateway config redacts talk.apiKey for mobile clients.")
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+                        Toggle("Background Listening", isOn: self.$talkBackgroundEnabled)
+                        Text("Keep listening when the app is in the background. Uses more battery.")
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+                        Toggle("Voice Directive Hint", isOn: self.$talkVoiceDirectiveHintEnabled)
+                        Text("Include ElevenLabs voice switching instructions in the Talk Mode prompt. Disable to save tokens.")
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
                         // Keep this separate so users can hide the side bubble without disabling Talk Mode.
                         Toggle("Show Talk Button", isOn: self.$talkButtonEnabled)
 
@@ -303,8 +333,17 @@ struct SettingsTab: View {
                     .accessibilityLabel("Close")
                 }
             }
+            .alert("Reset Onboarding?", isPresented: self.$showResetOnboardingAlert) {
+                Button("Reset", role: .destructive) {
+                    self.resetOnboarding()
+                }
+                Button("Cancel", role: .cancel) {}
+            } message: {
+                Text(
+                    "This will disconnect, clear saved gateway connection + credentials, and reopen the onboarding wizard.")
+            }
             .onAppear {
-                self.localIPAddress = Self.primaryIPv4Address()
+                self.localIPAddress = NetworkInterfaces.primaryIPv4Address()
                 self.lastLocationModeRaw = self.locationEnabledModeRaw
                 self.syncManualPortText()
                 let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -312,6 +351,7 @@ struct SettingsTab: View {
                     self.gatewayToken = GatewaySettingsStore.loadGatewayToken(instanceId: trimmedInstanceId) ?? ""
                     self.gatewayPassword = GatewaySettingsStore.loadGatewayPassword(instanceId: trimmedInstanceId) ?? ""
                 }
+                self.talkElevenLabsApiKey = GatewaySettingsStore.loadTalkElevenLabsApiKey() ?? ""
                 // Keep setup front-and-center when disconnected; keep things compact once connected.
                 self.gatewayExpanded = !self.isGatewayConnected
                 self.selectedAgentPickerId = self.appModel.selectedAgentId ?? ""
@@ -331,17 +371,22 @@ struct SettingsTab: View {
                 GatewaySettingsStore.savePreferredGatewayStableID(trimmed)
             }
             .onChange(of: self.gatewayToken) { _, newValue in
+                guard !self.suppressCredentialPersist else { return }
                 let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
                 let instanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
                 guard !instanceId.isEmpty else { return }
                 GatewaySettingsStore.saveGatewayToken(trimmed, instanceId: instanceId)
             }
             .onChange(of: self.gatewayPassword) { _, newValue in
+                guard !self.suppressCredentialPersist else { return }
                 let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
                 let instanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
                 guard !instanceId.isEmpty else { return }
                 GatewaySettingsStore.saveGatewayPassword(trimmed, instanceId: instanceId)
             }
+            .onChange(of: self.talkElevenLabsApiKey) { _, newValue in
+                GatewaySettingsStore.saveTalkElevenLabsApiKey(newValue)
+            }
             .onChange(of: self.manualGatewayPort) { _, _ in
                 self.syncManualPortText()
             }
@@ -421,10 +466,11 @@ struct SettingsTab: View {
                 ForEach(rows) { gateway in
                     HStack {
                         VStack(alignment: .leading, spacing: 2) {
-                            Text(gateway.name)
+                            // Avoid localized-string formatting edge cases from Bonjour-advertised names.
+                            Text(verbatim: gateway.name)
                             let detailLines = self.gatewayDetailLines(gateway)
                             ForEach(detailLines, id: \.self) { line in
-                                Text(line)
+                                Text(verbatim: line)
                                     .font(.footnote)
                                     .foregroundStyle(.secondary)
                             }
@@ -510,7 +556,10 @@ struct SettingsTab: View {
         GatewaySettingsStore.saveLastDiscoveredGatewayStableID(gateway.stableID)
         defer { self.connectingGatewayID = nil }
 
-        await self.gatewayController.connect(gateway)
+        let err = await self.gatewayController.connectWithDiagnostics(gateway)
+        if let err {
+            self.setupStatusText = err
+        }
     }
 
     private func connectLastKnown() async {
@@ -590,15 +639,6 @@ struct SettingsTab: View {
         }
     }
 
-    private struct SetupPayload: Codable {
-        var url: String?
-        var host: String?
-        var port: Int?
-        var tls: Bool?
-        var token: String?
-        var password: String?
-    }
-
     private func applySetupCodeAndConnect() async {
         self.setupStatusText = nil
         guard self.applySetupCode() else { return }
@@ -626,7 +666,7 @@ struct SettingsTab: View {
             return false
         }
 
-        guard let payload = self.decodeSetupPayload(raw: raw) else {
+        guard let payload = GatewaySetupCode.decode(raw: raw) else {
             self.setupStatusText = "Setup code not recognized."
             return false
         }
@@ -727,67 +767,14 @@ struct SettingsTab: View {
     }
 
     private static func probeTCP(host: String, port: Int, timeoutSeconds: Double) async -> Bool {
-        guard let nwPort = NWEndpoint.Port(rawValue: UInt16(port)) else { return false }
-        let endpointHost = NWEndpoint.Host(host)
-        let connection = NWConnection(host: endpointHost, port: nwPort, using: .tcp)
-        return await withCheckedContinuation { cont in
-            let queue = DispatchQueue(label: "gateway.preflight")
-            let finished = OSAllocatedUnfairLock(initialState: false)
-            let finish: @Sendable (Bool) -> Void = { ok in
-                let shouldResume = finished.withLock { flag -> Bool in
-                    if flag { return false }
-                    flag = true
-                    return true
-                }
-                guard shouldResume else { return }
-                connection.cancel()
-                cont.resume(returning: ok)
-            }
-            connection.stateUpdateHandler = { state in
-                switch state {
-                case .ready:
-                    finish(true)
-                case .failed, .cancelled:
-                    finish(false)
-                default:
-                    break
-                }
-            }
-            connection.start(queue: queue)
-            queue.asyncAfter(deadline: .now() + timeoutSeconds) {
-                finish(false)
-            }
-        }
+        await TCPProbe.probe(
+            host: host,
+            port: port,
+            timeoutSeconds: timeoutSeconds,
+            queueLabel: "gateway.preflight")
     }
 
-    private func decodeSetupPayload(raw: String) -> SetupPayload? {
-        if let payload = decodeSetupPayloadFromJSON(raw) {
-            return payload
-        }
-        if let decoded = decodeBase64Payload(raw),
-           let payload = decodeSetupPayloadFromJSON(decoded)
-        {
-            return payload
-        }
-        return nil
-    }
-
-    private func decodeSetupPayloadFromJSON(_ json: String) -> SetupPayload? {
-        guard let data = json.data(using: .utf8) else { return nil }
-        return try? JSONDecoder().decode(SetupPayload.self, from: data)
-    }
-
-    private func decodeBase64Payload(_ raw: String) -> String? {
-        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return nil }
-        let normalized = trimmed
-            .replacingOccurrences(of: "-", with: "+")
-            .replacingOccurrences(of: "_", with: "/")
-        let padding = normalized.count % 4
-        let padded = padding == 0 ? normalized : normalized + String(repeating: "=", count: 4 - padding)
-        guard let data = Data(base64Encoded: padded) else { return nil }
-        return String(data: data, encoding: .utf8)
-    }
+    // (GatewaySetupCode) decode raw setup codes.
 
     private func connectManual() async {
         let host = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -852,44 +839,6 @@ struct SettingsTab: View {
         return nil
     }
 
-    private static func primaryIPv4Address() -> String? {
-        var addrList: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-        defer { freeifaddrs(addrList) }
-
-        var fallback: String?
-        var en0: String?
-
-        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-            let flags = Int32(ptr.pointee.ifa_flags)
-            let isUp = (flags & IFF_UP) != 0
-            let isLoopback = (flags & IFF_LOOPBACK) != 0
-            let name = String(cString: ptr.pointee.ifa_name)
-            let family = ptr.pointee.ifa_addr.pointee.sa_family
-            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-            var addr = ptr.pointee.ifa_addr.pointee
-            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-            let result = getnameinfo(
-                &addr,
-                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-                &buffer,
-                socklen_t(buffer.count),
-                nil,
-                0,
-                NI_NUMERICHOST)
-            guard result == 0 else { continue }
-            let len = buffer.prefix { $0 != 0 }
-            let bytes = len.map { UInt8(bitPattern: $0) }
-            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-
-            if name == "en0" { en0 = ip; break }
-            if fallback == nil { fallback = ip }
-        }
-
-        return en0 ?? fallback
-    }
-
     private static func hasTailnetIPv4() -> Bool {
         var addrList: UnsafeMutablePointer<ifaddrs>?
         guard getifaddrs(&addrList) == 0, let first = addrList else { return false }
@@ -949,6 +898,43 @@ struct SettingsTab: View {
         SettingsNetworkingHelpers.httpURLString(host: host, port: port, fallback: fallback)
     }
 
+    private func resetOnboarding() {
+        // Disconnect first so RootCanvas doesn't instantly mark onboarding complete again.
+        self.appModel.disconnectGateway()
+        self.connectingGatewayID = nil
+        self.setupStatusText = nil
+        self.setupCode = ""
+        self.gatewayAutoConnect = false
+
+        self.suppressCredentialPersist = true
+        defer { self.suppressCredentialPersist = false }
+
+        self.gatewayToken = ""
+        self.gatewayPassword = ""
+
+        let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmedInstanceId.isEmpty {
+            GatewaySettingsStore.deleteGatewayCredentials(instanceId: trimmedInstanceId)
+        }
+
+        // Reset onboarding state + clear saved gateway connection (the two things RootCanvas checks).
+        GatewaySettingsStore.clearLastGatewayConnection()
+
+        // RootCanvas also short-circuits onboarding when these are true.
+        self.onboardingComplete = false
+        self.hasConnectedOnce = false
+
+        // Clear manual override so it doesn't count as an existing gateway config.
+        self.manualGatewayEnabled = false
+        self.manualGatewayHost = ""
+
+        // Force re-present even without app restart.
+        self.onboardingRequestID += 1
+
+        // The onboarding wizard is presented from RootCanvas; dismiss Settings so it can show.
+        self.dismiss()
+    }
+
     private func gatewayDetailLines(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) -> [String] {
         var lines: [String] = []
         if let lanHost = gateway.lanHost { lines.append("LAN: \(lanHost)") }

apps/ios/Sources/Status/StatusActivityBuilder.swift

@@ -0,0 +1,71 @@
+import SwiftUI
+
+enum StatusActivityBuilder {
+    @MainActor
+    static func build(
+        appModel: NodeAppModel,
+        voiceWakeEnabled: Bool,
+        cameraHUDText: String?,
+        cameraHUDKind: NodeAppModel.CameraHUDKind?
+    ) -> StatusPill.Activity? {
+        // Keep the top pill consistent across tabs (camera + voice wake + pairing states).
+        if appModel.isBackgrounded {
+            return StatusPill.Activity(
+                title: "Foreground required",
+                systemImage: "exclamationmark.triangle.fill",
+                tint: .orange)
+        }
+
+        let gatewayStatus = appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        let gatewayLower = gatewayStatus.lowercased()
+        if gatewayLower.contains("repair") {
+            return StatusPill.Activity(title: "Repairing…", systemImage: "wrench.and.screwdriver", tint: .orange)
+        }
+        if gatewayLower.contains("approval") || gatewayLower.contains("pairing") {
+            return StatusPill.Activity(title: "Approval pending", systemImage: "person.crop.circle.badge.clock")
+        }
+        // Avoid duplicating the primary gateway status ("Connecting…") in the activity slot.
+
+        if appModel.screenRecordActive {
+            return StatusPill.Activity(title: "Recording screen…", systemImage: "record.circle.fill", tint: .red)
+        }
+
+        if let cameraHUDText, !cameraHUDText.isEmpty, let cameraHUDKind {
+            let systemImage: String
+            let tint: Color?
+            switch cameraHUDKind {
+            case .photo:
+                systemImage = "camera.fill"
+                tint = nil
+            case .recording:
+                systemImage = "video.fill"
+                tint = .red
+            case .success:
+                systemImage = "checkmark.circle.fill"
+                tint = .green
+            case .error:
+                systemImage = "exclamationmark.triangle.fill"
+                tint = .red
+            }
+            return StatusPill.Activity(title: cameraHUDText, systemImage: systemImage, tint: tint)
+        }
+
+        if voiceWakeEnabled {
+            let voiceStatus = appModel.voiceWake.statusText
+            if voiceStatus.localizedCaseInsensitiveContains("microphone permission") {
+                return StatusPill.Activity(title: "Mic permission", systemImage: "mic.slash", tint: .orange)
+            }
+            if voiceStatus == "Paused" {
+                // Talk mode intentionally pauses voice wake to release the mic. Don't spam the HUD for that case.
+                if appModel.talkMode.isEnabled {
+                    return nil
+                }
+                let suffix = appModel.isBackgrounded ? " (background)" : ""
+                return StatusPill.Activity(title: "Voice Wake paused\(suffix)", systemImage: "pause.circle.fill")
+            }
+        }
+
+        return nil
+    }
+}
+

apps/ios/Sources/Status/StatusPill.swift

@@ -2,6 +2,8 @@ import SwiftUI
 
 struct StatusPill: View {
     @Environment(\.scenePhase) private var scenePhase
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @Environment(\.colorSchemeContrast) private var contrast
 
     enum GatewayState: Equatable {
         case connected
@@ -49,11 +51,11 @@ struct StatusPill: View {
                     Circle()
                         .fill(self.gateway.color)
                         .frame(width: 9, height: 9)
-                        .scaleEffect(self.gateway == .connecting ? (self.pulse ? 1.15 : 0.85) : 1.0)
-                        .opacity(self.gateway == .connecting ? (self.pulse ? 1.0 : 0.6) : 1.0)
+                        .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(.system(size: 13, weight: .semibold))
+                        .font(.subheadline.weight(.semibold))
                         .foregroundStyle(.primary)
                 }
 
@@ -64,17 +66,17 @@ struct StatusPill: View {
                 if let activity {
                     HStack(spacing: 6) {
                         Image(systemName: activity.systemImage)
-                            .font(.system(size: 13, weight: .semibold))
+                            .font(.subheadline.weight(.semibold))
                             .foregroundStyle(activity.tint ?? .primary)
                         Text(activity.title)
-                            .font(.system(size: 13, weight: .semibold))
+                            .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(.system(size: 13, weight: .semibold))
+                        .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)))
@@ -87,21 +89,28 @@ struct StatusPill: View {
                     .fill(.ultraThinMaterial)
                     .overlay {
                         RoundedRectangle(cornerRadius: 14, style: .continuous)
-                            .strokeBorder(.white.opacity(self.brighten ? 0.24 : 0.18), lineWidth: 0.5)
+                            .strokeBorder(
+                                .white.opacity(self.contrast == .increased ? 0.5 : (self.brighten ? 0.24 : 0.18)),
+                                lineWidth: self.contrast == .increased ? 1.0 : 0.5
+                            )
                     }
                     .shadow(color: .black.opacity(0.25), radius: 12, y: 6)
             }
         }
         .buttonStyle(.plain)
-        .accessibilityLabel("Status")
+        .accessibilityLabel("Connection Status")
         .accessibilityValue(self.accessibilityValue)
-        .onAppear { self.updatePulse(for: self.gateway, scenePhase: self.scenePhase) }
+        .accessibilityHint("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)
+            self.updatePulse(for: newValue, scenePhase: self.scenePhase, reduceMotion: self.reduceMotion)
         }
         .onChange(of: self.scenePhase) { _, newValue in
-            self.updatePulse(for: self.gateway, scenePhase: newValue)
+            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)
     }
@@ -113,9 +122,9 @@ struct StatusPill: View {
         return "\(self.gateway.title), Voice Wake \(self.voiceWakeEnabled ? "enabled" : "disabled")"
     }
 
-    private func updatePulse(for gateway: GatewayState, scenePhase: ScenePhase) {
-        guard gateway == .connecting, scenePhase == .active else {
-            withAnimation(.easeOut(duration: 0.2)) { self.pulse = false }
+    private func updatePulse(for gateway: GatewayState, scenePhase: ScenePhase, reduceMotion: Bool) {
+        guard gateway == .connecting, scenePhase == .active, !reduceMotion else {
+            withAnimation(reduceMotion ? .none : .easeOut(duration: 0.2)) { self.pulse = false }
             return
         }
 

apps/ios/Sources/Status/VoiceWakeToast.swift

@@ -1,17 +1,19 @@
 import SwiftUI
 
 struct VoiceWakeToast: View {
+    @Environment(\.colorSchemeContrast) private var contrast
+
     var command: String
     var brighten: Bool = false
 
     var body: some View {
         HStack(spacing: 10) {
             Image(systemName: "mic.fill")
-                .font(.system(size: 14, weight: .semibold))
+                .font(.subheadline.weight(.semibold))
                 .foregroundStyle(.primary)
 
             Text(self.command)
-                .font(.system(size: 14, weight: .semibold))
+                .font(.subheadline.weight(.semibold))
                 .foregroundStyle(.primary)
                 .lineLimit(1)
                 .truncationMode(.tail)
@@ -23,11 +25,14 @@ struct VoiceWakeToast: View {
                 .fill(.ultraThinMaterial)
                 .overlay {
                     RoundedRectangle(cornerRadius: 14, style: .continuous)
-                        .strokeBorder(.white.opacity(self.brighten ? 0.24 : 0.18), lineWidth: 0.5)
+                        .strokeBorder(
+                            .white.opacity(self.contrast == .increased ? 0.5 : (self.brighten ? 0.24 : 0.18)),
+                            lineWidth: self.contrast == .increased ? 1.0 : 0.5
+                        )
                 }
                 .shadow(color: .black.opacity(0.25), radius: 12, y: 6)
         }
-        .accessibilityLabel("Voice Wake")
-        .accessibilityValue(self.command)
+        .accessibilityLabel("Voice Wake triggered")
+        .accessibilityValue("Command: \(self.command)")
     }
 }

apps/ios/Sources/Voice/TalkModeManager.swift

@@ -16,6 +16,7 @@ import Speech
 final class TalkModeManager: NSObject {
     private typealias SpeechRequest = SFSpeechAudioBufferRecognitionRequest
     private static let defaultModelIdFallback = "eleven_v3"
+    private static let redactedConfigSentinel = "__OPENCLAW_REDACTED__"
     var isEnabled: Bool = false
     var isListening: Bool = false
     var isSpeaking: Bool = false
@@ -218,8 +219,12 @@ final class TalkModeManager: NSObject {
 
     /// Suspends microphone usage without disabling Talk Mode.
     /// Used when the app backgrounds (or when we need to temporarily release the mic).
-    func suspendForBackground() -> Bool {
+    func suspendForBackground(keepActive: Bool = false) -> Bool {
         guard self.isEnabled else { return false }
+        if keepActive {
+            self.statusText = self.isListening ? "Listening" : self.statusText
+            return false
+        }
         let wasActive = self.isListening || self.isSpeaking || self.isPushToTalkActive
 
         self.isListening = false
@@ -246,7 +251,8 @@ final class TalkModeManager: NSObject {
         return wasActive
     }
 
-    func resumeAfterBackground(wasSuspended: Bool) async {
+    func resumeAfterBackground(wasSuspended: Bool, wasKeptActive: Bool = false) async {
+        if wasKeptActive { return }
         guard wasSuspended else { return }
         guard self.isEnabled else { return }
         await self.start()
@@ -814,29 +820,24 @@ final class TalkModeManager: NSObject {
     private func subscribeChatIfNeeded(sessionKey: String) async {
         let key = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !key.isEmpty else { return }
-        guard let gateway else { return }
         guard !self.chatSubscribedSessionKeys.contains(key) else { return }
 
-        let payload = "{\"sessionKey\":\"\(key)\"}"
-        await gateway.sendEvent(event: "chat.subscribe", payloadJSON: payload)
+        // Operator clients receive chat events without node-style subscriptions.
         self.chatSubscribedSessionKeys.insert(key)
-        self.logger.info("chat.subscribe ok sessionKey=\(key, privacy: .public)")
     }
 
     private func unsubscribeAllChats() async {
-        guard let gateway else { return }
-        let keys = self.chatSubscribedSessionKeys
         self.chatSubscribedSessionKeys.removeAll()
-        for key in keys {
-            let payload = "{\"sessionKey\":\"\(key)\"}"
-            await gateway.sendEvent(event: "chat.unsubscribe", payloadJSON: payload)
-        }
     }
 
     private func buildPrompt(transcript: String) -> String {
         let interrupted = self.lastInterruptedAtSeconds
         self.lastInterruptedAtSeconds = nil
-        return TalkPromptBuilder.build(transcript: transcript, interruptedAtSeconds: interrupted)
+        let includeVoiceDirectiveHint = (UserDefaults.standard.object(forKey: "talk.voiceDirectiveHint.enabled") as? Bool) ?? true
+        return TalkPromptBuilder.build(
+            transcript: transcript,
+            interruptedAtSeconds: interrupted,
+            includeVoiceDirectiveHint: includeVoiceDirectiveHint)
     }
 
     private enum ChatCompletionState: CustomStringConvertible {
@@ -1114,6 +1115,7 @@ final class TalkModeManager: NSObject {
     }
 
     private func shouldInterrupt(with transcript: String) -> Bool {
+        guard self.shouldAllowSpeechInterruptForCurrentRoute() else { return false }
         let trimmed = transcript.trimmingCharacters(in: .whitespacesAndNewlines)
         guard trimmed.count >= 3 else { return false }
         if let spoken = self.lastSpokenText?.lowercased(), spoken.contains(trimmed.lowercased()) {
@@ -1122,6 +1124,20 @@ final class TalkModeManager: NSObject {
         return true
     }
 
+    private func shouldAllowSpeechInterruptForCurrentRoute() -> Bool {
+        let route = AVAudioSession.sharedInstance().currentRoute
+        // Built-in speaker/receiver often feeds TTS back into STT, causing false interrupts.
+        // Allow barge-in for isolated outputs (headphones/Bluetooth/USB/CarPlay/AirPlay).
+        return !route.outputs.contains { output in
+            switch output.portType {
+            case .builtInSpeaker, .builtInReceiver:
+                return true
+            default:
+                return false
+            }
+        }
+    }
+
     private func shouldUseIncrementalTTS() -> Bool {
         true
     }
@@ -1668,6 +1684,15 @@ extension TalkModeManager {
         return value.allSatisfy { $0.isLetter || $0.isNumber || $0 == "-" || $0 == "_" }
     }
 
+    private static func normalizedTalkApiKey(_ raw: String?) -> String? {
+        let trimmed = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        guard trimmed != Self.redactedConfigSentinel else { return nil }
+        // Config values may be env placeholders (for example `${ELEVENLABS_API_KEY}`).
+        if trimmed.hasPrefix("${"), trimmed.hasSuffix("}") { return nil }
+        return trimmed
+    }
+
     func reloadConfig() async {
         guard let gateway else { return }
         do {
@@ -1699,7 +1724,15 @@ extension TalkModeManager {
             }
             self.defaultOutputFormat = (talk?["outputFormat"] as? String)?
                 .trimmingCharacters(in: .whitespacesAndNewlines)
-            self.apiKey = (talk?["apiKey"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+            let rawConfigApiKey = (talk?["apiKey"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+            let configApiKey = Self.normalizedTalkApiKey(rawConfigApiKey)
+            let localApiKey = Self.normalizedTalkApiKey(GatewaySettingsStore.loadTalkElevenLabsApiKey())
+            if rawConfigApiKey == Self.redactedConfigSentinel {
+                self.apiKey = (localApiKey?.isEmpty == false) ? localApiKey : nil
+                GatewayDiagnostics.log("talk config apiKey redacted; using local override if present")
+            } else {
+                self.apiKey = (localApiKey?.isEmpty == false) ? localApiKey : configApiKey
+            }
             if let interrupt = talk?["interruptOnSpeech"] as? Bool {
                 self.interruptOnSpeech = interrupt
             }

apps/ios/Tests/DeepLinkParserTests.swift

@@ -76,4 +76,52 @@ import Testing
             timeoutSeconds: nil,
             key: nil)))
     }
+
+    @Test func parseGatewayLinkParsesCommonFields() {
+        let url = URL(
+            string: "openclaw://gateway?host=openclaw.local&port=18789&tls=1&token=abc&password=def")!
+        #expect(
+            DeepLinkParser.parse(url) == .gateway(
+                .init(host: "openclaw.local", port: 18789, tls: true, token: "abc", password: "def")))
+    }
+
+    @Test func parseGatewaySetupCodeParsesBase64UrlPayload() {
+        let payload = #"{"url":"wss://gateway.example.com:443","token":"tok","password":"pw"}"#
+        let encoded = Data(payload.utf8)
+            .base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+
+        let link = GatewayConnectDeepLink.fromSetupCode(encoded)
+
+        #expect(link == .init(
+            host: "gateway.example.com",
+            port: 443,
+            tls: true,
+            token: "tok",
+            password: "pw"))
+    }
+
+    @Test func parseGatewaySetupCodeRejectsInvalidInput() {
+        #expect(GatewayConnectDeepLink.fromSetupCode("not-a-valid-setup-code") == nil)
+    }
+
+    @Test func parseGatewaySetupCodeDefaultsTo443ForWssWithoutPort() {
+        let payload = #"{"url":"wss://gateway.example.com","token":"tok"}"#
+        let encoded = Data(payload.utf8)
+            .base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+
+        let link = GatewayConnectDeepLink.fromSetupCode(encoded)
+
+        #expect(link == .init(
+            host: "gateway.example.com",
+            port: 443,
+            tls: true,
+            token: "tok",
+            password: nil))
+    }
 }

apps/ios/Tests/GatewayConnectionControllerTests.swift

@@ -76,4 +76,47 @@ private func withUserDefaults<T>(_ updates: [String: Any?], _ body: () throws ->
             #expect(commands.contains(OpenClawLocationCommand.get.rawValue))
         }
     }
+    @Test @MainActor func currentCommandsExcludeDangerousSystemExecCommands() {
+        withUserDefaults([
+            "node.instanceId": "ios-test",
+            "camera.enabled": true,
+            "location.enabledMode": OpenClawLocationMode.whileUsing.rawValue,
+        ]) {
+            let appModel = NodeAppModel()
+            let controller = GatewayConnectionController(appModel: appModel, startDiscovery: false)
+            let commands = Set(controller._test_currentCommands())
+
+            // iOS should expose notify, but not host shell/exec-approval commands.
+            #expect(commands.contains(OpenClawSystemCommand.notify.rawValue))
+            #expect(!commands.contains(OpenClawSystemCommand.run.rawValue))
+            #expect(!commands.contains(OpenClawSystemCommand.which.rawValue))
+            #expect(!commands.contains(OpenClawSystemCommand.execApprovalsGet.rawValue))
+            #expect(!commands.contains(OpenClawSystemCommand.execApprovalsSet.rawValue))
+        }
+    }
+
+    @Test @MainActor func loadLastConnectionReadsSavedValues() {
+        withUserDefaults([:]) {
+            GatewaySettingsStore.saveLastGatewayConnectionManual(
+                host: "gateway.example.com",
+                port: 443,
+                useTLS: true,
+                stableID: "manual|gateway.example.com|443")
+            let loaded = GatewaySettingsStore.loadLastGatewayConnection()
+            #expect(loaded == .manual(host: "gateway.example.com", port: 443, useTLS: true, stableID: "manual|gateway.example.com|443"))
+        }
+    }
+
+    @Test @MainActor func loadLastConnectionReturnsNilForInvalidData() {
+        withUserDefaults([
+            "gateway.last.kind": "manual",
+            "gateway.last.host": "",
+            "gateway.last.port": 0,
+            "gateway.last.tls": false,
+            "gateway.last.stableID": "manual|invalid|0",
+        ]) {
+            let loaded = GatewaySettingsStore.loadLastGatewayConnection()
+            #expect(loaded == nil)
+        }
+    }
 }

apps/ios/Tests/GatewayConnectionIssueTests.swift

@@ -0,0 +1,33 @@
+import Testing
+@testable import OpenClaw
+
+@Suite(.serialized) struct GatewayConnectionIssueTests {
+    @Test func detectsTokenMissing() {
+        let issue = GatewayConnectionIssue.detect(from: "unauthorized: gateway token missing")
+        #expect(issue == .tokenMissing)
+        #expect(issue.needsAuthToken)
+    }
+
+    @Test func detectsUnauthorized() {
+        let issue = GatewayConnectionIssue.detect(from: "Gateway error: unauthorized role")
+        #expect(issue == .unauthorized)
+        #expect(issue.needsAuthToken)
+    }
+
+    @Test func detectsPairingWithRequestId() {
+        let issue = GatewayConnectionIssue.detect(from: "pairing required (requestId: abc123)")
+        #expect(issue == .pairingRequired(requestId: "abc123"))
+        #expect(issue.needsPairing)
+        #expect(issue.requestId == "abc123")
+    }
+
+    @Test func detectsNetworkError() {
+        let issue = GatewayConnectionIssue.detect(from: "Gateway error: Connection refused")
+        #expect(issue == .network)
+    }
+
+    @Test func returnsNoneForBenignStatus() {
+        let issue = GatewayConnectionIssue.detect(from: "Connected")
+        #expect(issue == .none)
+    }
+}

apps/ios/Tests/Info.plist

@@ -17,8 +17,8 @@
 	<key>CFBundlePackageType</key>
 			<string>BNDL</string>
 			<key>CFBundleShortVersionString</key>
-			<string>2026.2.15</string>
+			<string>2026.2.16</string>
 			<key>CFBundleVersion</key>
-			<string>20260215</string>
+			<string>20260216</string>
 		</dict>
 	</plist>

apps/ios/Tests/OnboardingStateStoreTests.swift

@@ -0,0 +1,57 @@
+import Foundation
+import Testing
+@testable import OpenClaw
+
+@Suite(.serialized) struct OnboardingStateStoreTests {
+    @Test @MainActor func shouldPresentWhenFreshAndDisconnected() {
+        let testDefaults = self.makeDefaults()
+        let defaults = testDefaults.defaults
+        defer { self.reset(testDefaults) }
+
+        let appModel = NodeAppModel()
+        appModel.gatewayServerName = nil
+        #expect(OnboardingStateStore.shouldPresentOnLaunch(appModel: appModel, defaults: defaults))
+    }
+
+    @Test @MainActor func doesNotPresentWhenConnected() {
+        let testDefaults = self.makeDefaults()
+        let defaults = testDefaults.defaults
+        defer { self.reset(testDefaults) }
+
+        let appModel = NodeAppModel()
+        appModel.gatewayServerName = "gateway"
+        #expect(!OnboardingStateStore.shouldPresentOnLaunch(appModel: appModel, defaults: defaults))
+    }
+
+    @Test @MainActor func markCompletedPersistsMode() {
+        let testDefaults = self.makeDefaults()
+        let defaults = testDefaults.defaults
+        defer { self.reset(testDefaults) }
+
+        let appModel = NodeAppModel()
+        appModel.gatewayServerName = nil
+
+        OnboardingStateStore.markCompleted(mode: .remoteDomain, defaults: defaults)
+        #expect(OnboardingStateStore.lastMode(defaults: defaults) == .remoteDomain)
+        #expect(!OnboardingStateStore.shouldPresentOnLaunch(appModel: appModel, defaults: defaults))
+
+        OnboardingStateStore.markIncomplete(defaults: defaults)
+        #expect(OnboardingStateStore.shouldPresentOnLaunch(appModel: appModel, defaults: defaults))
+    }
+
+    private struct TestDefaults {
+        var suiteName: String
+        var defaults: UserDefaults
+    }
+
+    private func makeDefaults() -> TestDefaults {
+        let suiteName = "OnboardingStateStoreTests.\(UUID().uuidString)"
+        return TestDefaults(
+            suiteName: suiteName,
+            defaults: UserDefaults(suiteName: suiteName) ?? .standard)
+    }
+
+    private func reset(_ defaults: TestDefaults) {
+        defaults.defaults.removePersistentDomain(forName: defaults.suiteName)
+    }
+}

apps/ios/project.yml

@@ -81,8 +81,8 @@ targets:
       properties:
         CFBundleDisplayName: OpenClaw
         CFBundleIconName: AppIcon
-        CFBundleShortVersionString: "2026.2.15"
-        CFBundleVersion: "20260215"
+        CFBundleShortVersionString: "2026.2.16"
+        CFBundleVersion: "20260216"
         UILaunchScreen: {}
         UIApplicationSceneManifest:
           UIApplicationSupportsMultipleScenes: false
@@ -130,5 +130,5 @@ targets:
       path: Tests/Info.plist
       properties:
         CFBundleDisplayName: OpenClawTests
-        CFBundleShortVersionString: "2026.2.15"
-        CFBundleVersion: "20260215"
+        CFBundleShortVersionString: "2026.2.16"
+        CFBundleVersion: "20260216"

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

@@ -1,6 +1,5 @@
 import Foundation
 import OpenClawKit
-import OpenClawProtocol
 
 // Prefer the OpenClawKit wrapper to keep gateway request payloads consistent.
 typealias AnyCodable = OpenClawKit.AnyCodable
@@ -42,40 +41,3 @@ extension AnyCodable {
         }
     }
 }
-
-extension OpenClawProtocol.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: OpenClawProtocol.AnyCodable]? {
-        self.value as? [String: OpenClawProtocol.AnyCodable]
-    }
-
-    var arrayValue: [OpenClawProtocol.AnyCodable]? {
-        self.value as? [OpenClawProtocol.AnyCodable]
-    }
-
-    var foundationValue: Any {
-        switch self.value {
-        case let dict as [String: OpenClawProtocol.AnyCodable]:
-            dict.mapValues { $0.foundationValue }
-        case let array as [OpenClawProtocol.AnyCodable]:
-            array.map(\.foundationValue)
-        default:
-            self.value
-        }
-    }
-}

apps/macos/Sources/OpenClaw/CameraCaptureService.swift

@@ -106,14 +106,16 @@ actor CameraCaptureService {
         }
         withExtendedLifetime(delegate) {}
 
-        let maxPayloadBytes = 5 * 1024 * 1024
-        // Base64 inflates payloads by ~4/3; cap encoded bytes so the payload stays under 5MB (API limit).
-        let maxEncodedBytes = (maxPayloadBytes / 4) * 3
-        let res = try JPEGTranscoder.transcodeToJPEG(
-            imageData: rawData,
-            maxWidthPx: maxWidth,
-            quality: quality,
-            maxBytes: maxEncodedBytes)
+        let res: (data: Data, widthPx: Int, heightPx: Int)
+        do {
+            res = try PhotoCapture.transcodeJPEGForGateway(
+                rawData: rawData,
+                maxWidthPx: maxWidth,
+                quality: quality)
+        } catch {
+            throw CameraError.captureFailed(error.localizedDescription)
+        }
+
         return (data: res.data, size: CGSize(width: res.widthPx, height: res.heightPx))
     }
 
@@ -355,8 +357,8 @@ private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegat
     func photoOutput(
         _ output: AVCapturePhotoOutput,
         didFinishProcessingPhoto photo: AVCapturePhoto,
-        error: Error?)
-    {
+        error: Error?
+    ) {
         guard !self.didResume, let cont else { return }
         self.didResume = true
         self.cont = nil
@@ -378,8 +380,8 @@ private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegat
     func photoOutput(
         _ output: AVCapturePhotoOutput,
         didFinishCaptureFor resolvedSettings: AVCaptureResolvedPhotoSettings,
-        error: Error?)
-    {
+        error: Error?
+    ) {
         guard let error else { return }
         guard !self.didResume, let cont else { return }
         self.didResume = true

apps/macos/Sources/OpenClaw/CanvasFileWatcher.swift

@@ -1,17 +1,13 @@
-import CoreServices
 import Foundation
 
 final class CanvasFileWatcher: @unchecked Sendable {
-    private let url: URL
-    private let queue: DispatchQueue
-    private var stream: FSEventStreamRef?
-    private var pending = false
-    private let onChange: () -> Void
+    private let watcher: CoalescingFSEventsWatcher
 
     init(url: URL, onChange: @escaping () -> Void) {
-        self.url = url
-        self.queue = DispatchQueue(label: "ai.openclaw.canvaswatcher")
-        self.onChange = onChange
+        self.watcher = CoalescingFSEventsWatcher(
+            paths: [url.path],
+            queueLabel: "ai.openclaw.canvaswatcher",
+            onChange: onChange)
     }
 
     deinit {
@@ -19,76 +15,10 @@ final class CanvasFileWatcher: @unchecked Sendable {
     }
 
     func start() {
-        guard self.stream == nil else { return }
-
-        let retainedSelf = Unmanaged.passRetained(self)
-        var context = FSEventStreamContext(
-            version: 0,
-            info: retainedSelf.toOpaque(),
-            retain: nil,
-            release: { pointer in
-                guard let pointer else { return }
-                Unmanaged<CanvasFileWatcher>.fromOpaque(pointer).release()
-            },
-            copyDescription: nil)
-
-        let paths = [self.url.path] as CFArray
-        let flags = FSEventStreamCreateFlags(
-            kFSEventStreamCreateFlagFileEvents |
-                kFSEventStreamCreateFlagUseCFTypes |
-                kFSEventStreamCreateFlagNoDefer)
-
-        guard let stream = FSEventStreamCreate(
-            kCFAllocatorDefault,
-            Self.callback,
-            &context,
-            paths,
-            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
-            0.05,
-            flags)
-        else {
-            retainedSelf.release()
-            return
-        }
-
-        self.stream = stream
-        FSEventStreamSetDispatchQueue(stream, self.queue)
-        if FSEventStreamStart(stream) == false {
-            self.stream = nil
-            FSEventStreamSetDispatchQueue(stream, nil)
-            FSEventStreamInvalidate(stream)
-            FSEventStreamRelease(stream)
-        }
+        self.watcher.start()
     }
 
     func stop() {
-        guard let stream = self.stream else { return }
-        self.stream = nil
-        FSEventStreamStop(stream)
-        FSEventStreamSetDispatchQueue(stream, nil)
-        FSEventStreamInvalidate(stream)
-        FSEventStreamRelease(stream)
-    }
-}
-
-extension CanvasFileWatcher {
-    private static let callback: FSEventStreamCallback = { _, info, numEvents, _, eventFlags, _ in
-        guard let info else { return }
-        let watcher = Unmanaged<CanvasFileWatcher>.fromOpaque(info).takeUnretainedValue()
-        watcher.handleEvents(numEvents: numEvents, eventFlags: eventFlags)
-    }
-
-    private func handleEvents(numEvents: Int, eventFlags: UnsafePointer<FSEventStreamEventFlags>?) {
-        guard numEvents > 0 else { return }
-        guard eventFlags != nil else { return }
-
-        // Coalesce rapid changes (common during builds/atomic saves).
-        if self.pending { return }
-        self.pending = true
-        self.queue.asyncAfter(deadline: .now() + 0.12) { [weak self] in
-            guard let self else { return }
-            self.pending = false
-            self.onChange()
-        }
+        self.watcher.stop()
     }
 }

apps/macos/Sources/OpenClaw/CoalescingFSEventsWatcher.swift

@@ -0,0 +1,111 @@
+import CoreServices
+import Foundation
+
+final class CoalescingFSEventsWatcher: @unchecked Sendable {
+    private let queue: DispatchQueue
+    private var stream: FSEventStreamRef?
+    private var pending = false
+
+    private let paths: [String]
+    private let shouldNotify: (Int, UnsafeMutableRawPointer?) -> Bool
+    private let onChange: () -> Void
+    private let coalesceDelay: TimeInterval
+
+    init(
+        paths: [String],
+        queueLabel: String,
+        coalesceDelay: TimeInterval = 0.12,
+        shouldNotify: @escaping (Int, UnsafeMutableRawPointer?) -> Bool = { _, _ in true },
+        onChange: @escaping () -> Void
+    ) {
+        self.paths = paths
+        self.queue = DispatchQueue(label: queueLabel)
+        self.coalesceDelay = coalesceDelay
+        self.shouldNotify = shouldNotify
+        self.onChange = onChange
+    }
+
+    deinit {
+        self.stop()
+    }
+
+    func start() {
+        guard self.stream == nil else { return }
+
+        let retainedSelf = Unmanaged.passRetained(self)
+        var context = FSEventStreamContext(
+            version: 0,
+            info: retainedSelf.toOpaque(),
+            retain: nil,
+            release: { pointer in
+                guard let pointer else { return }
+                Unmanaged<CoalescingFSEventsWatcher>.fromOpaque(pointer).release()
+            },
+            copyDescription: nil)
+
+        let paths = self.paths as CFArray
+        let flags = FSEventStreamCreateFlags(
+            kFSEventStreamCreateFlagFileEvents |
+                kFSEventStreamCreateFlagUseCFTypes |
+                kFSEventStreamCreateFlagNoDefer)
+
+        guard let stream = FSEventStreamCreate(
+            kCFAllocatorDefault,
+            Self.callback,
+            &context,
+            paths,
+            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+            0.05,
+            flags)
+        else {
+            retainedSelf.release()
+            return
+        }
+
+        self.stream = stream
+        FSEventStreamSetDispatchQueue(stream, self.queue)
+        if FSEventStreamStart(stream) == false {
+            self.stream = nil
+            FSEventStreamSetDispatchQueue(stream, nil)
+            FSEventStreamInvalidate(stream)
+            FSEventStreamRelease(stream)
+        }
+    }
+
+    func stop() {
+        guard let stream = self.stream else { return }
+        self.stream = nil
+        FSEventStreamStop(stream)
+        FSEventStreamSetDispatchQueue(stream, nil)
+        FSEventStreamInvalidate(stream)
+        FSEventStreamRelease(stream)
+    }
+}
+
+extension CoalescingFSEventsWatcher {
+    private static let callback: FSEventStreamCallback = { _, info, numEvents, eventPaths, eventFlags, _ in
+        guard let info else { return }
+        let watcher = Unmanaged<CoalescingFSEventsWatcher>.fromOpaque(info).takeUnretainedValue()
+        watcher.handleEvents(numEvents: numEvents, eventPaths: eventPaths, eventFlags: eventFlags)
+    }
+
+    private func handleEvents(
+        numEvents: Int,
+        eventPaths: UnsafeMutableRawPointer?,
+        eventFlags: UnsafePointer<FSEventStreamEventFlags>?
+    ) {
+        guard numEvents > 0 else { return }
+        guard eventFlags != nil else { return }
+        guard self.shouldNotify(numEvents, eventPaths) else { return }
+
+        // Coalesce rapid changes (common during builds/atomic saves).
+        if self.pending { return }
+        self.pending = true
+        self.queue.asyncAfter(deadline: .now() + self.coalesceDelay) { [weak self] in
+            guard let self else { return }
+            self.pending = false
+            self.onChange()
+        }
+    }
+}
+

apps/macos/Sources/OpenClaw/ConfigFileWatcher.swift

@@ -1,23 +1,34 @@
-import CoreServices
 import Foundation
 
 final class ConfigFileWatcher: @unchecked Sendable {
     private let url: URL
-    private let queue: DispatchQueue
-    private var stream: FSEventStreamRef?
-    private var pending = false
-    private let onChange: () -> Void
     private let watchedDir: URL
     private let targetPath: String
     private let targetName: String
+    private let watcher: CoalescingFSEventsWatcher
 
     init(url: URL, onChange: @escaping () -> Void) {
         self.url = url
-        self.queue = DispatchQueue(label: "ai.openclaw.configwatcher")
-        self.onChange = onChange
         self.watchedDir = url.deletingLastPathComponent()
         self.targetPath = url.path
         self.targetName = url.lastPathComponent
+        let watchedDirPath = self.watchedDir.path
+        let targetPath = self.targetPath
+        let targetName = self.targetName
+        self.watcher = CoalescingFSEventsWatcher(
+            paths: [watchedDirPath],
+            queueLabel: "ai.openclaw.configwatcher",
+            shouldNotify: { _, eventPaths in
+                guard let eventPaths else { return true }
+                let paths = unsafeBitCast(eventPaths, to: NSArray.self)
+                for case let path as String in paths {
+                    if path == targetPath { return true }
+                    if path.hasSuffix("/\(targetName)") { return true }
+                    if path == watchedDirPath { return true }
+                }
+                return false
+            },
+            onChange: onChange)
     }
 
     deinit {
@@ -25,94 +36,10 @@ final class ConfigFileWatcher: @unchecked Sendable {
     }
 
     func start() {
-        guard self.stream == nil else { return }
-
-        let retainedSelf = Unmanaged.passRetained(self)
-        var context = FSEventStreamContext(
-            version: 0,
-            info: retainedSelf.toOpaque(),
-            retain: nil,
-            release: { pointer in
-                guard let pointer else { return }
-                Unmanaged<ConfigFileWatcher>.fromOpaque(pointer).release()
-            },
-            copyDescription: nil)
-
-        let paths = [self.watchedDir.path] as CFArray
-        let flags = FSEventStreamCreateFlags(
-            kFSEventStreamCreateFlagFileEvents |
-                kFSEventStreamCreateFlagUseCFTypes |
-                kFSEventStreamCreateFlagNoDefer)
-
-        guard let stream = FSEventStreamCreate(
-            kCFAllocatorDefault,
-            Self.callback,
-            &context,
-            paths,
-            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
-            0.05,
-            flags)
-        else {
-            retainedSelf.release()
-            return
-        }
-
-        self.stream = stream
-        FSEventStreamSetDispatchQueue(stream, self.queue)
-        if FSEventStreamStart(stream) == false {
-            self.stream = nil
-            FSEventStreamSetDispatchQueue(stream, nil)
-            FSEventStreamInvalidate(stream)
-            FSEventStreamRelease(stream)
-        }
+        self.watcher.start()
     }
 
     func stop() {
-        guard let stream = self.stream else { return }
-        self.stream = nil
-        FSEventStreamStop(stream)
-        FSEventStreamSetDispatchQueue(stream, nil)
-        FSEventStreamInvalidate(stream)
-        FSEventStreamRelease(stream)
-    }
-}
-
-extension ConfigFileWatcher {
-    private static let callback: FSEventStreamCallback = { _, info, numEvents, eventPaths, eventFlags, _ in
-        guard let info else { return }
-        let watcher = Unmanaged<ConfigFileWatcher>.fromOpaque(info).takeUnretainedValue()
-        watcher.handleEvents(
-            numEvents: numEvents,
-            eventPaths: eventPaths,
-            eventFlags: eventFlags)
-    }
-
-    private func handleEvents(
-        numEvents: Int,
-        eventPaths: UnsafeMutableRawPointer?,
-        eventFlags: UnsafePointer<FSEventStreamEventFlags>?)
-    {
-        guard numEvents > 0 else { return }
-        guard eventFlags != nil else { return }
-        guard self.matchesTarget(eventPaths: eventPaths) else { return }
-
-        if self.pending { return }
-        self.pending = true
-        self.queue.asyncAfter(deadline: .now() + 0.12) { [weak self] in
-            guard let self else { return }
-            self.pending = false
-            self.onChange()
-        }
-    }
-
-    private func matchesTarget(eventPaths: UnsafeMutableRawPointer?) -> Bool {
-        guard let eventPaths else { return true }
-        let paths = unsafeBitCast(eventPaths, to: NSArray.self)
-        for case let path as String in paths {
-            if path == self.targetPath { return true }
-            if path.hasSuffix("/\(self.targetName)") { return true }
-            if path == self.watchedDir.path { return true }
-        }
-        return false
+        self.watcher.stop()
     }
 }

apps/macos/Sources/OpenClaw/CronModels.swift

@@ -21,6 +21,7 @@ enum CronWakeMode: String, CaseIterable, Identifiable, Codable {
 enum CronDeliveryMode: String, CaseIterable, Identifiable, Codable {
     case none
     case announce
+    case webhook
 
     var id: String {
         self.rawValue

apps/macos/Sources/OpenClaw/DevicePairingApprovalPrompter.swift

@@ -22,16 +22,6 @@ final class DevicePairingApprovalPrompter {
     private var alertHostWindow: NSWindow?
     private var resolvedByRequestId: Set<String> = []
 
-    private final class AlertHostWindow: NSWindow {
-        override var canBecomeKey: Bool {
-            true
-        }
-
-        override var canBecomeMain: Bool {
-            true
-        }
-    }
-
     private struct PairingList: Codable {
         let pending: [PendingRequest]
         let paired: [PairedDevice]?
@@ -238,35 +228,11 @@ final class DevicePairingApprovalPrompter {
     }
 
     private func endActiveAlert() {
-        guard let alert = self.activeAlert else { return }
-        if let parent = alert.window.sheetParent {
-            parent.endSheet(alert.window, returnCode: .abort)
-        }
-        self.activeAlert = nil
-        self.activeRequestId = nil
+        PairingAlertSupport.endActiveAlert(activeAlert: &self.activeAlert, activeRequestId: &self.activeRequestId)
     }
 
     private func requireAlertHostWindow() -> NSWindow {
-        if let alertHostWindow {
-            return alertHostWindow
-        }
-
-        let window = AlertHostWindow(
-            contentRect: NSRect(x: 0, y: 0, width: 520, height: 1),
-            styleMask: [.borderless],
-            backing: .buffered,
-            defer: false)
-        window.title = ""
-        window.isReleasedWhenClosed = false
-        window.level = .floating
-        window.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
-        window.isOpaque = false
-        window.hasShadow = false
-        window.backgroundColor = .clear
-        window.ignoresMouseEvents = true
-
-        self.alertHostWindow = window
-        return window
+        PairingAlertSupport.requireAlertHostWindow(alertHostWindow: &self.alertHostWindow)
     }
 
     private func handle(push: GatewayPush) {

apps/macos/Sources/OpenClaw/InstancesStore.swift

@@ -158,7 +158,7 @@ final class InstancesStore {
 
     private func localFallbackInstance(reason: String) -> InstanceInfo {
         let host = Host.current().localizedName ?? "this-mac"
-        let ip = Self.primaryIPv4Address()
+        let ip = SystemPresenceInfo.primaryIPv4Address()
         let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
         let osVersion = ProcessInfo.processInfo.operatingSystemVersion
         let platform = "macos \(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)"
@@ -172,58 +172,13 @@ final class InstancesStore {
             platform: platform,
             deviceFamily: "Mac",
             modelIdentifier: InstanceIdentity.modelIdentifier,
-            lastInputSeconds: Self.lastInputSeconds(),
+            lastInputSeconds: SystemPresenceInfo.lastInputSeconds(),
             mode: "local",
             reason: reason,
             text: text,
             ts: ts)
     }
 
-    private static func lastInputSeconds() -> Int? {
-        let anyEvent = CGEventType(rawValue: UInt32.max) ?? .null
-        let seconds = CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: anyEvent)
-        if seconds.isNaN || seconds.isInfinite || seconds < 0 { return nil }
-        return Int(seconds.rounded())
-    }
-
-    private static func primaryIPv4Address() -> String? {
-        var addrList: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-        defer { freeifaddrs(addrList) }
-
-        var fallback: String?
-        var en0: String?
-
-        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-            let flags = Int32(ptr.pointee.ifa_flags)
-            let isUp = (flags & IFF_UP) != 0
-            let isLoopback = (flags & IFF_LOOPBACK) != 0
-            let name = String(cString: ptr.pointee.ifa_name)
-            let family = ptr.pointee.ifa_addr.pointee.sa_family
-            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-            var addr = ptr.pointee.ifa_addr.pointee
-            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-            let result = getnameinfo(
-                &addr,
-                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-                &buffer,
-                socklen_t(buffer.count),
-                nil,
-                0,
-                NI_NUMERICHOST)
-            guard result == 0 else { continue }
-            let len = buffer.prefix { $0 != 0 }
-            let bytes = len.map { UInt8(bitPattern: $0) }
-            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-
-            if name == "en0" { en0 = ip; break }
-            if fallback == nil { fallback = ip }
-        }
-
-        return en0 ?? fallback
-    }
-
     // MARK: - Helpers
 
     /// Keep the last raw payload for logging.

apps/macos/Sources/OpenClaw/NodePairingApprovalPrompter.swift

@@ -38,16 +38,6 @@ final class NodePairingApprovalPrompter {
     private var remoteResolutionsByRequestId: [String: PairingResolution] = [:]
     private var autoApproveAttempts: Set<String> = []
 
-    private final class AlertHostWindow: NSWindow {
-        override var canBecomeKey: Bool {
-            true
-        }
-
-        override var canBecomeMain: Bool {
-            true
-        }
-    }
-
     private struct PairingList: Codable {
         let pending: [PendingRequest]
         let paired: [PairedNode]?
@@ -242,35 +232,11 @@ final class NodePairingApprovalPrompter {
     }
 
     private func endActiveAlert() {
-        guard let alert = self.activeAlert else { return }
-        if let parent = alert.window.sheetParent {
-            parent.endSheet(alert.window, returnCode: .abort)
-        }
-        self.activeAlert = nil
-        self.activeRequestId = nil
+        PairingAlertSupport.endActiveAlert(activeAlert: &self.activeAlert, activeRequestId: &self.activeRequestId)
     }
 
     private func requireAlertHostWindow() -> NSWindow {
-        if let alertHostWindow {
-            return alertHostWindow
-        }
-
-        let window = AlertHostWindow(
-            contentRect: NSRect(x: 0, y: 0, width: 520, height: 1),
-            styleMask: [.borderless],
-            backing: .buffered,
-            defer: false)
-        window.title = ""
-        window.isReleasedWhenClosed = false
-        window.level = .floating
-        window.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
-        window.isOpaque = false
-        window.hasShadow = false
-        window.backgroundColor = .clear
-        window.ignoresMouseEvents = true
-
-        self.alertHostWindow = window
-        return window
+        PairingAlertSupport.requireAlertHostWindow(alertHostWindow: &self.alertHostWindow)
     }
 
     private func handle(push: GatewayPush) {

apps/macos/Sources/OpenClaw/PairingAlertSupport.swift

@@ -0,0 +1,46 @@
+import AppKit
+
+final class PairingAlertHostWindow: NSWindow {
+    override var canBecomeKey: Bool {
+        true
+    }
+
+    override var canBecomeMain: Bool {
+        true
+    }
+}
+
+@MainActor
+enum PairingAlertSupport {
+    static func endActiveAlert(activeAlert: inout NSAlert?, activeRequestId: inout String?) {
+        guard let alert = activeAlert else { return }
+        if let parent = alert.window.sheetParent {
+            parent.endSheet(alert.window, returnCode: .abort)
+        }
+        activeAlert = nil
+        activeRequestId = nil
+    }
+
+    static func requireAlertHostWindow(alertHostWindow: inout NSWindow?) -> NSWindow {
+        if let alertHostWindow {
+            return alertHostWindow
+        }
+
+        let window = PairingAlertHostWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 520, height: 1),
+            styleMask: [.borderless],
+            backing: .buffered,
+            defer: false)
+        window.title = ""
+        window.isReleasedWhenClosed = false
+        window.level = .floating
+        window.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
+        window.isOpaque = false
+        window.hasShadow = false
+        window.backgroundColor = .clear
+        window.ignoresMouseEvents = true
+
+        alertHostWindow = window
+        return window
+    }
+}

apps/macos/Sources/OpenClaw/PresenceReporter.swift

@@ -1,5 +1,4 @@
 import Cocoa
-import Darwin
 import Foundation
 import OSLog
 
@@ -33,10 +32,10 @@ final class PresenceReporter {
     private func push(reason: String) async {
         let mode = await MainActor.run { AppStateStore.shared.connectionMode.rawValue }
         let host = InstanceIdentity.displayName
-        let ip = Self.primaryIPv4Address() ?? "ip-unknown"
+        let ip = SystemPresenceInfo.primaryIPv4Address() ?? "ip-unknown"
         let version = Self.appVersionString()
         let platform = Self.platformString()
-        let lastInput = Self.lastInputSeconds()
+        let lastInput = SystemPresenceInfo.lastInputSeconds()
         let text = Self.composePresenceSummary(mode: mode, reason: reason)
         var params: [String: AnyHashable] = [
             "instanceId": AnyHashable(self.instanceId),
@@ -64,9 +63,9 @@ final class PresenceReporter {
 
     private static func composePresenceSummary(mode: String, reason: String) -> String {
         let host = InstanceIdentity.displayName
-        let ip = Self.primaryIPv4Address() ?? "ip-unknown"
+        let ip = SystemPresenceInfo.primaryIPv4Address() ?? "ip-unknown"
         let version = Self.appVersionString()
-        let lastInput = Self.lastInputSeconds()
+        let lastInput = SystemPresenceInfo.lastInputSeconds()
         let lastLabel = lastInput.map { "last input \($0)s ago" } ?? "last input unknown"
         return "Node: \(host) (\(ip)) · app \(version) · \(lastLabel) · mode \(mode) · reason \(reason)"
     }
@@ -87,50 +86,7 @@ final class PresenceReporter {
         return "macos \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
     }
 
-    private static func lastInputSeconds() -> Int? {
-        let anyEvent = CGEventType(rawValue: UInt32.max) ?? .null
-        let seconds = CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: anyEvent)
-        if seconds.isNaN || seconds.isInfinite || seconds < 0 { return nil }
-        return Int(seconds.rounded())
-    }
-
-    private static func primaryIPv4Address() -> String? {
-        var addrList: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-        defer { freeifaddrs(addrList) }
-
-        var fallback: String?
-        var en0: String?
-
-        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-            let flags = Int32(ptr.pointee.ifa_flags)
-            let isUp = (flags & IFF_UP) != 0
-            let isLoopback = (flags & IFF_LOOPBACK) != 0
-            let name = String(cString: ptr.pointee.ifa_name)
-            let family = ptr.pointee.ifa_addr.pointee.sa_family
-            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-            var addr = ptr.pointee.ifa_addr.pointee
-            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-            let result = getnameinfo(
-                &addr,
-                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-                &buffer,
-                socklen_t(buffer.count),
-                nil,
-                0,
-                NI_NUMERICHOST)
-            guard result == 0 else { continue }
-            let len = buffer.prefix { $0 != 0 }
-            let bytes = len.map { UInt8(bitPattern: $0) }
-            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-
-            if name == "en0" { en0 = ip; break }
-            if fallback == nil { fallback = ip }
-        }
-
-        return en0 ?? fallback
-    }
+    // (SystemPresenceInfo) last input + primary IPv4.
 }
 
 #if DEBUG
@@ -148,11 +104,11 @@ extension PresenceReporter {
     }
 
     static func _testLastInputSeconds() -> Int? {
-        self.lastInputSeconds()
+        SystemPresenceInfo.lastInputSeconds()
     }
 
     static func _testPrimaryIPv4Address() -> String? {
-        self.primaryIPv4Address()
+        SystemPresenceInfo.primaryIPv4Address()
     }
 }
 #endif

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

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.2.15</string>
+    <string>2026.2.16</string>
     <key>CFBundleVersion</key>
-    <string>202602150</string>
+    <string>202602160</string>
     <key>CFBundleIconFile</key>
     <string>OpenClaw</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/OpenClaw/SystemPresenceInfo.swift

@@ -0,0 +1,16 @@
+import CoreGraphics
+import Foundation
+import OpenClawKit
+
+enum SystemPresenceInfo {
+    static func lastInputSeconds() -> Int? {
+        let anyEvent = CGEventType(rawValue: UInt32.max) ?? .null
+        let seconds = CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: anyEvent)
+        if seconds.isNaN || seconds.isInfinite || seconds < 0 { return nil }
+        return Int(seconds.rounded())
+    }
+
+    static func primaryIPv4Address() -> String? {
+        NetworkInterfaces.primaryIPv4Address()
+    }
+}

apps/macos/Sources/OpenClaw/TailscaleService.swift

@@ -1,10 +1,8 @@
 import AppKit
 import Foundation
 import Observation
+import OpenClawDiscovery
 import os
-#if canImport(Darwin)
-import Darwin
-#endif
 
 /// Manages Tailscale integration and status checking.
 @Observable
@@ -140,7 +138,7 @@ final class TailscaleService {
             self.logger.info("Tailscale API not responding; app likely not running")
         }
 
-        if self.tailscaleIP == nil, let fallback = Self.detectTailnetIPv4() {
+        if self.tailscaleIP == nil, let fallback = TailscaleNetwork.detectTailnetIPv4() {
             self.tailscaleIP = fallback
             if !self.isRunning {
                 self.isRunning = true
@@ -178,49 +176,7 @@ final class TailscaleService {
         }
     }
 
-    private nonisolated static func isTailnetIPv4(_ address: String) -> Bool {
-        let parts = address.split(separator: ".")
-        guard parts.count == 4 else { return false }
-        let octets = parts.compactMap { Int($0) }
-        guard octets.count == 4 else { return false }
-        let a = octets[0]
-        let b = octets[1]
-        return a == 100 && b >= 64 && b <= 127
-    }
-
-    private nonisolated static func detectTailnetIPv4() -> String? {
-        var addrList: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-        defer { freeifaddrs(addrList) }
-
-        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-            let flags = Int32(ptr.pointee.ifa_flags)
-            let isUp = (flags & IFF_UP) != 0
-            let isLoopback = (flags & IFF_LOOPBACK) != 0
-            let family = ptr.pointee.ifa_addr.pointee.sa_family
-            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-            var addr = ptr.pointee.ifa_addr.pointee
-            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-            let result = getnameinfo(
-                &addr,
-                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-                &buffer,
-                socklen_t(buffer.count),
-                nil,
-                0,
-                NI_NUMERICHOST)
-            guard result == 0 else { continue }
-            let len = buffer.prefix { $0 != 0 }
-            let bytes = len.map { UInt8(bitPattern: $0) }
-            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-            if Self.isTailnetIPv4(ip) { return ip }
-        }
-
-        return nil
-    }
-
     nonisolated static func fallbackTailnetIPv4() -> String? {
-        self.detectTailnetIPv4()
+        TailscaleNetwork.detectTailnetIPv4()
     }
 }

apps/macos/Sources/OpenClawDiscovery/GatewayDiscoveryModel.swift

@@ -329,43 +329,9 @@ public final class GatewayDiscoveryModel {
     }
 
     private func updateStatusText() {
-        let states = Array(self.statesByDomain.values)
-        if states.isEmpty {
-            self.statusText = self.browsers.isEmpty ? "Idle" : "Setup"
-            return
-        }
-
-        if let failed = states.first(where: { state in
-            if case .failed = state { return true }
-            return false
-        }) {
-            if case let .failed(err) = failed {
-                self.statusText = "Failed: \(err)"
-                return
-            }
-        }
-
-        if let waiting = states.first(where: { state in
-            if case .waiting = state { return true }
-            return false
-        }) {
-            if case let .waiting(err) = waiting {
-                self.statusText = "Waiting: \(err)"
-                return
-            }
-        }
-
-        if states.contains(where: { if case .ready = $0 { true } else { false } }) {
-            self.statusText = "Searching…"
-            return
-        }
-
-        if states.contains(where: { if case .setup = $0 { true } else { false } }) {
-            self.statusText = "Setup"
-            return
-        }
-
-        self.statusText = "Searching…"
+        self.statusText = GatewayDiscoveryStatusText.make(
+            states: Array(self.statesByDomain.values),
+            hasBrowsers: !self.browsers.isEmpty)
     }
 
     private static func txtDictionary(from result: NWBrowser.Result) -> [String: String] {

apps/macos/Sources/OpenClawDiscovery/TailscaleNetwork.swift

@@ -0,0 +1,47 @@
+import Darwin
+import Foundation
+
+public enum TailscaleNetwork {
+    public static func isTailnetIPv4(_ address: String) -> Bool {
+        let parts = address.split(separator: ".")
+        guard parts.count == 4 else { return false }
+        let octets = parts.compactMap { Int($0) }
+        guard octets.count == 4 else { return false }
+        let a = octets[0]
+        let b = octets[1]
+        return a == 100 && b >= 64 && b <= 127
+    }
+
+    public static func detectTailnetIPv4() -> String? {
+        var addrList: UnsafeMutablePointer<ifaddrs>?
+        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
+        defer { freeifaddrs(addrList) }
+
+        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
+            let flags = Int32(ptr.pointee.ifa_flags)
+            let isUp = (flags & IFF_UP) != 0
+            let isLoopback = (flags & IFF_LOOPBACK) != 0
+            let family = ptr.pointee.ifa_addr.pointee.sa_family
+            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
+
+            var addr = ptr.pointee.ifa_addr.pointee
+            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
+            let result = getnameinfo(
+                &addr,
+                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
+                &buffer,
+                socklen_t(buffer.count),
+                nil,
+                0,
+                NI_NUMERICHOST)
+            guard result == 0 else { continue }
+            let len = buffer.prefix { $0 != 0 }
+            let bytes = len.map { UInt8(bitPattern: $0) }
+            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
+            if self.isTailnetIPv4(ip) { return ip }
+        }
+
+        return nil
+    }
+}
+

apps/macos/Sources/OpenClawMacCLI/ConnectCommand.swift

@@ -1,9 +1,7 @@
 import Foundation
+import OpenClawDiscovery
 import OpenClawKit
 import OpenClawProtocol
-#if canImport(Darwin)
-import Darwin
-#endif
 
 struct ConnectOptions {
     var url: String?
@@ -301,7 +299,7 @@ private func resolvedPassword(opts: ConnectOptions, mode: String, config: Gatewa
 
 private func resolveLocalHost(bind: String?) -> String {
     let normalized = (bind ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-    let tailnetIP = detectTailnetIPv4()
+    let tailnetIP = TailscaleNetwork.detectTailnetIPv4()
     switch normalized {
     case "tailnet":
         return tailnetIP ?? "127.0.0.1"
@@ -309,45 +307,3 @@ private func resolveLocalHost(bind: String?) -> String {
         return "127.0.0.1"
     }
 }
-
-private func detectTailnetIPv4() -> String? {
-    var addrList: UnsafeMutablePointer<ifaddrs>?
-    guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-    defer { freeifaddrs(addrList) }
-
-    for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-        let flags = Int32(ptr.pointee.ifa_flags)
-        let isUp = (flags & IFF_UP) != 0
-        let isLoopback = (flags & IFF_LOOPBACK) != 0
-        let family = ptr.pointee.ifa_addr.pointee.sa_family
-        if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-        var addr = ptr.pointee.ifa_addr.pointee
-        var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-        let result = getnameinfo(
-            &addr,
-            socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-            &buffer,
-            socklen_t(buffer.count),
-            nil,
-            0,
-            NI_NUMERICHOST)
-        guard result == 0 else { continue }
-        let len = buffer.prefix { $0 != 0 }
-        let bytes = len.map { UInt8(bitPattern: $0) }
-        guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-        if isTailnetIPv4(ip) { return ip }
-    }
-
-    return nil
-}
-
-private func isTailnetIPv4(_ address: String) -> Bool {
-    let parts = address.split(separator: ".")
-    guard parts.count == 4 else { return false }
-    let octets = parts.compactMap { Int($0) }
-    guard octets.count == 4 else { return false }
-    let a = octets[0]
-    let b = octets[1]
-    return a == 100 && b >= 64 && b <= 127
-}

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2084,6 +2084,7 @@ public struct SkillsUpdateParams: Codable, Sendable {
 public struct CronJob: Codable, Sendable {
     public let id: String
     public let agentid: String?
+    public let sessionkey: String?
     public let name: String
     public let description: String?
     public let enabled: Bool
@@ -2094,12 +2095,13 @@ public struct CronJob: Codable, Sendable {
     public let sessiontarget: AnyCodable
     public let wakemode: AnyCodable
     public let payload: AnyCodable
-    public let delivery: [String: AnyCodable]?
+    public let delivery: AnyCodable?
     public let state: [String: AnyCodable]
 
     public init(
         id: String,
         agentid: String?,
+        sessionkey: String?,
         name: String,
         description: String?,
         enabled: Bool,
@@ -2110,11 +2112,12 @@ public struct CronJob: Codable, Sendable {
         sessiontarget: AnyCodable,
         wakemode: AnyCodable,
         payload: AnyCodable,
-        delivery: [String: AnyCodable]?,
+        delivery: AnyCodable?,
         state: [String: AnyCodable]
     ) {
         self.id = id
         self.agentid = agentid
+        self.sessionkey = sessionkey
         self.name = name
         self.description = description
         self.enabled = enabled
@@ -2131,6 +2134,7 @@ public struct CronJob: Codable, Sendable {
     private enum CodingKeys: String, CodingKey {
         case id
         case agentid = "agentId"
+        case sessionkey = "sessionKey"
         case name
         case description
         case enabled
@@ -2165,6 +2169,7 @@ public struct CronStatusParams: Codable, Sendable {
 public struct CronAddParams: Codable, Sendable {
     public let name: String
     public let agentid: AnyCodable?
+    public let sessionkey: AnyCodable?
     public let description: String?
     public let enabled: Bool?
     public let deleteafterrun: Bool?
@@ -2172,11 +2177,12 @@ public struct CronAddParams: Codable, Sendable {
     public let sessiontarget: AnyCodable
     public let wakemode: AnyCodable
     public let payload: AnyCodable
-    public let delivery: [String: AnyCodable]?
+    public let delivery: AnyCodable?
 
     public init(
         name: String,
         agentid: AnyCodable?,
+        sessionkey: AnyCodable?,
         description: String?,
         enabled: Bool?,
         deleteafterrun: Bool?,
@@ -2184,10 +2190,11 @@ public struct CronAddParams: Codable, Sendable {
         sessiontarget: AnyCodable,
         wakemode: AnyCodable,
         payload: AnyCodable,
-        delivery: [String: AnyCodable]?
+        delivery: AnyCodable?
     ) {
         self.name = name
         self.agentid = agentid
+        self.sessionkey = sessionkey
         self.description = description
         self.enabled = enabled
         self.deleteafterrun = deleteafterrun
@@ -2200,6 +2207,7 @@ public struct CronAddParams: Codable, Sendable {
     private enum CodingKeys: String, CodingKey {
         case name
         case agentid = "agentId"
+        case sessionkey = "sessionKey"
         case description
         case enabled
         case deleteafterrun = "deleteAfterRun"
@@ -2757,6 +2765,144 @@ public struct ChatEvent: Codable, Sendable {
     }
 }
 
+public struct MeshPlanParams: Codable, Sendable {
+    public let goal: String
+    public let steps: [[String: AnyCodable]]?
+
+    public init(
+        goal: String,
+        steps: [[String: AnyCodable]]?
+    ) {
+        self.goal = goal
+        self.steps = steps
+    }
+    private enum CodingKeys: String, CodingKey {
+        case goal
+        case steps
+    }
+}
+
+public struct MeshPlanAutoParams: Codable, Sendable {
+    public let goal: String
+    public let maxsteps: Int?
+    public let agentid: String?
+    public let sessionkey: String?
+    public let thinking: String?
+    public let timeoutms: Int?
+    public let lane: String?
+
+    public init(
+        goal: String,
+        maxsteps: Int?,
+        agentid: String?,
+        sessionkey: String?,
+        thinking: String?,
+        timeoutms: Int?,
+        lane: String?
+    ) {
+        self.goal = goal
+        self.maxsteps = maxsteps
+        self.agentid = agentid
+        self.sessionkey = sessionkey
+        self.thinking = thinking
+        self.timeoutms = timeoutms
+        self.lane = lane
+    }
+    private enum CodingKeys: String, CodingKey {
+        case goal
+        case maxsteps = "maxSteps"
+        case agentid = "agentId"
+        case sessionkey = "sessionKey"
+        case thinking
+        case timeoutms = "timeoutMs"
+        case lane
+    }
+}
+
+public struct MeshWorkflowPlan: Codable, Sendable {
+    public let planid: String
+    public let goal: String
+    public let createdat: Int
+    public let steps: [[String: AnyCodable]]
+
+    public init(
+        planid: String,
+        goal: String,
+        createdat: Int,
+        steps: [[String: AnyCodable]]
+    ) {
+        self.planid = planid
+        self.goal = goal
+        self.createdat = createdat
+        self.steps = steps
+    }
+    private enum CodingKeys: String, CodingKey {
+        case planid = "planId"
+        case goal
+        case createdat = "createdAt"
+        case steps
+    }
+}
+
+public struct MeshRunParams: Codable, Sendable {
+    public let plan: MeshWorkflowPlan
+    public let continueonerror: Bool?
+    public let maxparallel: Int?
+    public let defaultsteptimeoutms: Int?
+    public let lane: String?
+
+    public init(
+        plan: MeshWorkflowPlan,
+        continueonerror: Bool?,
+        maxparallel: Int?,
+        defaultsteptimeoutms: Int?,
+        lane: String?
+    ) {
+        self.plan = plan
+        self.continueonerror = continueonerror
+        self.maxparallel = maxparallel
+        self.defaultsteptimeoutms = defaultsteptimeoutms
+        self.lane = lane
+    }
+    private enum CodingKeys: String, CodingKey {
+        case plan
+        case continueonerror = "continueOnError"
+        case maxparallel = "maxParallel"
+        case defaultsteptimeoutms = "defaultStepTimeoutMs"
+        case lane
+    }
+}
+
+public struct MeshStatusParams: Codable, Sendable {
+    public let runid: String
+
+    public init(
+        runid: String
+    ) {
+        self.runid = runid
+    }
+    private enum CodingKeys: String, CodingKey {
+        case runid = "runId"
+    }
+}
+
+public struct MeshRetryParams: Codable, Sendable {
+    public let runid: String
+    public let stepids: [String]?
+
+    public init(
+        runid: String,
+        stepids: [String]?
+    ) {
+        self.runid = runid
+        self.stepids = stepids
+    }
+    private enum CodingKeys: String, CodingKey {
+        case runid = "runId"
+        case stepids = "stepIds"
+    }
+}
+
 public struct UpdateRunParams: Codable, Sendable {
     public let sessionkey: String?
     public let note: String?

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

@@ -103,18 +103,22 @@ public final class OpenClawChatViewModel {
         let now = Date().timeIntervalSince1970 * 1000
         let cutoff = now - (24 * 60 * 60 * 1000)
         let sorted = self.sessions.sorted { ($0.updatedAt ?? 0) > ($1.updatedAt ?? 0) }
-        var seen = Set<String>()
-        var recent: [OpenClawChatSessionEntry] = []
-        for entry in sorted {
-            guard !seen.contains(entry.key) else { continue }
-            seen.insert(entry.key)
-            guard (entry.updatedAt ?? 0) >= cutoff else { continue }
-            recent.append(entry)
-        }
 
         var result: [OpenClawChatSessionEntry] = []
         var included = Set<String>()
-        for entry in recent where !included.contains(entry.key) {
+
+        // Always show the main session first, even if it hasn't been updated recently.
+        if let main = sorted.first(where: { $0.key == "main" }) {
+            result.append(main)
+            included.insert(main.key)
+        } else {
+            result.append(self.placeholderSession(key: "main"))
+            included.insert("main")
+        }
+
+        for entry in sorted {
+            guard !included.contains(entry.key) else { continue }
+            guard (entry.updatedAt ?? 0) >= cutoff else { continue }
             result.append(entry)
             included.insert(entry.key)
         }
@@ -166,7 +170,9 @@ public final class OpenClawChatViewModel {
             }
 
             let payload = try await self.transport.requestHistory(sessionKey: self.sessionKey)
-            self.messages = Self.decodeMessages(payload.messages ?? [])
+            self.messages = Self.reconcileMessageIDs(
+                previous: self.messages,
+                incoming: Self.decodeMessages(payload.messages ?? []))
             self.sessionId = payload.sessionId
             if let level = payload.thinkingLevel, !level.isEmpty {
                 self.thinkingLevel = level
@@ -187,6 +193,70 @@ public final class OpenClawChatViewModel {
         return Self.dedupeMessages(decoded)
     }
 
+    private static func messageIdentityKey(for message: OpenClawChatMessage) -> String? {
+        let role = message.role.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        guard !role.isEmpty else { return nil }
+
+        let timestamp: String = {
+            guard let value = message.timestamp, value.isFinite else { return "" }
+            return String(format: "%.3f", value)
+        }()
+
+        let contentFingerprint = message.content.map { item in
+            let type = (item.type ?? "text").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            let text = (item.text ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+            let id = (item.id ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+            let name = (item.name ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+            let fileName = (item.fileName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+            return [type, text, id, name, fileName].joined(separator: "\\u{001F}")
+        }.joined(separator: "\\u{001E}")
+
+        let toolCallId = (message.toolCallId ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        let toolName = (message.toolName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if timestamp.isEmpty, contentFingerprint.isEmpty, toolCallId.isEmpty, toolName.isEmpty {
+            return nil
+        }
+        return [role, timestamp, toolCallId, toolName, contentFingerprint].joined(separator: "|")
+    }
+
+    private static func reconcileMessageIDs(
+        previous: [OpenClawChatMessage],
+        incoming: [OpenClawChatMessage]) -> [OpenClawChatMessage]
+    {
+        guard !previous.isEmpty, !incoming.isEmpty else { return incoming }
+
+        var idsByKey: [String: [UUID]] = [:]
+        for message in previous {
+            guard let key = Self.messageIdentityKey(for: message) else { continue }
+            idsByKey[key, default: []].append(message.id)
+        }
+
+        return incoming.map { message in
+            guard let key = Self.messageIdentityKey(for: message),
+                  var ids = idsByKey[key],
+                  let reusedId = ids.first
+            else {
+                return message
+            }
+            ids.removeFirst()
+            if ids.isEmpty {
+                idsByKey.removeValue(forKey: key)
+            } else {
+                idsByKey[key] = ids
+            }
+            guard reusedId != message.id else { return message }
+            return OpenClawChatMessage(
+                id: reusedId,
+                role: message.role,
+                content: message.content,
+                timestamp: message.timestamp,
+                toolCallId: message.toolCallId,
+                toolName: message.toolName,
+                usage: message.usage,
+                stopReason: message.stopReason)
+        }
+    }
+
     private static func dedupeMessages(_ messages: [OpenClawChatMessage]) -> [OpenClawChatMessage] {
         var result: [OpenClawChatMessage] = []
         result.reserveCapacity(messages.count)
@@ -371,11 +441,15 @@ public final class OpenClawChatViewModel {
     }
 
     private func handleChatEvent(_ chat: OpenClawChatEventPayload) {
-        if let sessionKey = chat.sessionKey, sessionKey != self.sessionKey {
+        let isOurRun = chat.runId.flatMap { self.pendingRuns.contains($0) } ?? false
+
+        // Gateway may publish canonical session keys (for example "agent:main:main")
+        // even when this view currently uses an alias key (for example "main").
+        // Never drop events for our own pending run on key mismatch, or the UI can stay
+        // stuck at "thinking" until the user reopens and forces a history reload.
+        if let sessionKey = chat.sessionKey, sessionKey != self.sessionKey, !isOurRun {
             return
         }
-
-        let isOurRun = chat.runId.flatMap { self.pendingRuns.contains($0) } ?? false
         if !isOurRun {
             // Keep multiple clients in sync: if another client finishes a run for our session, refresh history.
             switch chat.state {
@@ -440,7 +514,9 @@ public final class OpenClawChatViewModel {
     private func refreshHistoryAfterRun() async {
         do {
             let payload = try await self.transport.requestHistory(sessionKey: self.sessionKey)
-            self.messages = Self.decodeMessages(payload.messages ?? [])
+            self.messages = Self.reconcileMessageIDs(
+                previous: self.messages,
+                incoming: Self.decodeMessages(payload.messages ?? []))
             self.sessionId = payload.sessionId
             if let level = payload.thinkingLevel, !level.isEmpty {
                 self.thinkingLevel = level

apps/shared/OpenClawKit/Sources/OpenClawKit/AnyCodable.swift

@@ -1,93 +1,4 @@
-import Foundation
+import OpenClawProtocol
 
-/// Lightweight `Codable` wrapper that round-trips heterogeneous JSON payloads.
-///
-/// Marked `@unchecked Sendable` because it can hold reference types.
-public struct AnyCodable: Codable, @unchecked Sendable, Hashable {
-    public let value: Any
+public typealias AnyCodable = OpenClawProtocol.AnyCodable
 
-    public init(_ value: Any) { self.value = value }
-
-    public init(from decoder: Decoder) throws {
-        let container = try decoder.singleValueContainer()
-        if let intVal = try? container.decode(Int.self) { self.value = intVal; return }
-        if let doubleVal = try? container.decode(Double.self) { self.value = doubleVal; return }
-        if let boolVal = try? container.decode(Bool.self) { self.value = boolVal; return }
-        if let stringVal = try? container.decode(String.self) { self.value = stringVal; return }
-        if container.decodeNil() { self.value = NSNull(); return }
-        if let dict = try? container.decode([String: AnyCodable].self) { self.value = dict; return }
-        if let array = try? container.decode([AnyCodable].self) { self.value = array; return }
-        throw DecodingError.dataCorruptedError(in: container, debugDescription: "Unsupported type")
-    }
-
-    public func encode(to encoder: Encoder) throws {
-        var container = encoder.singleValueContainer()
-        switch self.value {
-        case let intVal as Int: try container.encode(intVal)
-        case let doubleVal as Double: try container.encode(doubleVal)
-        case let boolVal as Bool: try container.encode(boolVal)
-        case let stringVal as String: try container.encode(stringVal)
-        case is NSNull: try container.encodeNil()
-        case let dict as [String: AnyCodable]: try container.encode(dict)
-        case let array as [AnyCodable]: try container.encode(array)
-        case let dict as [String: Any]:
-            try container.encode(dict.mapValues { AnyCodable($0) })
-        case let array as [Any]:
-            try container.encode(array.map { AnyCodable($0) })
-        case let dict as NSDictionary:
-            var converted: [String: AnyCodable] = [:]
-            for (k, v) in dict {
-                guard let key = k as? String else { continue }
-                converted[key] = AnyCodable(v)
-            }
-            try container.encode(converted)
-        case let array as NSArray:
-            try container.encode(array.map { AnyCodable($0) })
-        default:
-            let context = EncodingError.Context(codingPath: encoder.codingPath, debugDescription: "Unsupported type")
-            throw EncodingError.invalidValue(self.value, context)
-        }
-    }
-
-    public static func == (lhs: AnyCodable, rhs: AnyCodable) -> Bool {
-        switch (lhs.value, rhs.value) {
-        case let (l as Int, r as Int): l == r
-        case let (l as Double, r as Double): l == r
-        case let (l as Bool, r as Bool): l == r
-        case let (l as String, r as String): l == r
-        case (_ as NSNull, _ as NSNull): true
-        case let (l as [String: AnyCodable], r as [String: AnyCodable]): l == r
-        case let (l as [AnyCodable], r as [AnyCodable]): l == r
-        default:
-            false
-        }
-    }
-
-    public func hash(into hasher: inout Hasher) {
-        switch self.value {
-        case let v as Int:
-            hasher.combine(0); hasher.combine(v)
-        case let v as Double:
-            hasher.combine(1); hasher.combine(v)
-        case let v as Bool:
-            hasher.combine(2); hasher.combine(v)
-        case let v as String:
-            hasher.combine(3); hasher.combine(v)
-        case _ as NSNull:
-            hasher.combine(4)
-        case let v as [String: AnyCodable]:
-            hasher.combine(5)
-            for (k, val) in v.sorted(by: { $0.key < $1.key }) {
-                hasher.combine(k)
-                hasher.combine(val)
-            }
-        case let v as [AnyCodable]:
-            hasher.combine(6)
-            for item in v {
-                hasher.combine(item)
-            }
-        default:
-            hasher.combine(999)
-        }
-    }
-}

apps/shared/OpenClawKit/Sources/OpenClawKit/DeepLinks.swift

@@ -2,6 +2,56 @@ import Foundation
 
 public enum DeepLinkRoute: Sendable, Equatable {
     case agent(AgentDeepLink)
+    case gateway(GatewayConnectDeepLink)
+}
+
+public struct GatewayConnectDeepLink: Codable, Sendable, Equatable {
+    public let host: String
+    public let port: Int
+    public let tls: Bool
+    public let token: String?
+    public let password: String?
+
+    public init(host: String, port: Int, tls: Bool, token: String?, password: String?) {
+        self.host = host
+        self.port = port
+        self.tls = tls
+        self.token = token
+        self.password = password
+    }
+
+    public var websocketURL: URL? {
+        let scheme = self.tls ? "wss" : "ws"
+        return URL(string: "\(scheme)://\(self.host):\(self.port)")
+    }
+
+    /// Parse a device-pair setup code (base64url-encoded JSON: `{url, token?, password?}`).
+    public static func fromSetupCode(_ code: String) -> GatewayConnectDeepLink? {
+        guard let data = Self.decodeBase64Url(code) else { return nil }
+        guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil }
+        guard let urlString = json["url"] as? String,
+              let parsed = URLComponents(string: urlString),
+              let hostname = parsed.host, !hostname.isEmpty
+        else { return nil }
+
+        let scheme = (parsed.scheme ?? "ws").lowercased()
+        let tls = scheme == "wss"
+        let port = parsed.port ?? (tls ? 443 : 18789)
+        let token = json["token"] as? String
+        let password = json["password"] as? String
+        return GatewayConnectDeepLink(host: hostname, port: port, tls: tls, token: token, password: password)
+    }
+
+    private static func decodeBase64Url(_ input: String) -> Data? {
+        var base64 = input
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+        let remainder = base64.count % 4
+        if remainder > 0 {
+            base64.append(contentsOf: String(repeating: "=", count: 4 - remainder))
+        }
+        return Data(base64Encoded: base64)
+    }
 }
 
 public struct AgentDeepLink: Codable, Sendable, Equatable {
@@ -69,6 +119,23 @@ public enum DeepLinkParser {
                     channel: query["channel"],
                     timeoutSeconds: timeoutSeconds,
                     key: query["key"]))
+
+        case "gateway":
+            guard let hostParam = query["host"],
+                  !hostParam.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            else {
+                return nil
+            }
+            let port = query["port"].flatMap { Int($0) } ?? 18789
+            let tls = (query["tls"] as NSString?)?.boolValue ?? false
+            return .gateway(
+                .init(
+                    host: hostParam,
+                    port: port,
+                    tls: tls,
+                    token: query["token"],
+                    password: query["password"]))
+
         default:
             return nil
         }

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

@@ -133,10 +133,16 @@ public actor GatewayChannelActor {
     private var lastAuthSource: GatewayAuthSource = .none
     private let decoder = JSONDecoder()
     private let encoder = JSONEncoder()
-    private let connectTimeoutSeconds: Double = 6
-    private let connectChallengeTimeoutSeconds: Double = 3.0
+    // Remote gateways (tailscale/wan) can take a bit longer to deliver the connect.challenge event,
+    // and we must include the nonce once the gateway requires v2 signing.
+    private let connectTimeoutSeconds: Double = 12
+    private let connectChallengeTimeoutSeconds: Double = 6.0
+    // Some networks will silently drop idle TCP/TLS flows around ~30s. The gateway tick is server->client,
+    // but NATs/proxies often require outbound traffic to keep the connection alive.
+    private let keepaliveIntervalSeconds: Double = 15.0
     private var watchdogTask: Task<Void, Never>?
     private var tickTask: Task<Void, Never>?
+    private var keepaliveTask: Task<Void, Never>?
     private let defaultRequestTimeoutMs: Double = 15000
     private let pushHandler: (@Sendable (GatewayPush) async -> Void)?
     private let connectOptions: GatewayConnectOptions?
@@ -175,6 +181,9 @@ public actor GatewayChannelActor {
         self.tickTask?.cancel()
         self.tickTask = nil
 
+        self.keepaliveTask?.cancel()
+        self.keepaliveTask = nil
+
         self.task?.cancel(with: .goingAway, reason: nil)
         self.task = nil
 
@@ -257,6 +266,7 @@ public actor GatewayChannelActor {
         self.connected = true
         self.backoffMs = 500
         self.lastSeq = nil
+        self.startKeepalive()
 
         let waiters = self.connectWaiters
         self.connectWaiters.removeAll()
@@ -265,6 +275,29 @@ public actor GatewayChannelActor {
         }
     }
 
+    private func startKeepalive() {
+        self.keepaliveTask?.cancel()
+        self.keepaliveTask = Task { [weak self] in
+            guard let self else { return }
+            await self.keepaliveLoop()
+        }
+    }
+
+    private func keepaliveLoop() async {
+        while self.shouldReconnect {
+            try? await Task.sleep(nanoseconds: UInt64(self.keepaliveIntervalSeconds * 1_000_000_000))
+            guard self.shouldReconnect else { return }
+            guard self.connected else { continue }
+            // Best-effort outbound message to keep intermediate NAT/proxy state alive.
+            // We intentionally ignore the response.
+            do {
+                try await self.send(method: "health", params: nil)
+            } catch {
+                // Avoid spamming logs; the reconnect paths will surface meaningful errors.
+            }
+        }
+    }
+
     private func sendConnect() async throws {
         let platform = InstanceIdentity.platformString
         let primaryLocale = Locale.preferredLanguages.first ?? Locale.current.identifier
@@ -458,6 +491,8 @@ public actor GatewayChannelActor {
         let wrapped = self.wrap(err, context: "gateway receive")
         self.logger.error("gateway ws receive failed \(wrapped.localizedDescription, privacy: .public)")
         self.connected = false
+        self.keepaliveTask?.cancel()
+        self.keepaliveTask = nil
         await self.disconnectHandler?("receive failed: \(wrapped.localizedDescription)")
         await self.failPending(wrapped)
         await self.scheduleReconnect()

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayDiscoveryStatusText.swift

@@ -0,0 +1,39 @@
+import Foundation
+import Network
+
+public enum GatewayDiscoveryStatusText {
+    public static func make(states: [NWBrowser.State], hasBrowsers: Bool) -> String {
+        if states.isEmpty {
+            return hasBrowsers ? "Setup" : "Idle"
+        }
+
+        if let failed = states.first(where: { state in
+            if case .failed = state { return true }
+            return false
+        }) {
+            if case let .failed(err) = failed {
+                return "Failed: \(err)"
+            }
+        }
+
+        if let waiting = states.first(where: { state in
+            if case .waiting = state { return true }
+            return false
+        }) {
+            if case let .waiting(err) = waiting {
+                return "Waiting: \(err)"
+            }
+        }
+
+        if states.contains(where: { if case .ready = $0 { true } else { false } }) {
+            return "Searching…"
+        }
+
+        if states.contains(where: { if case .setup = $0 { true } else { false } }) {
+            return "Setup"
+        }
+
+        return "Searching…"
+    }
+}
+

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayNodeSession.swift

@@ -85,7 +85,13 @@ public actor GatewayNodeSession {
                 latch.resume(result)
             }
             timeoutTask = Task.detached {
-                try? await Task.sleep(nanoseconds: UInt64(timeout) * 1_000_000)
+                do {
+                    try await Task.sleep(nanoseconds: UInt64(timeout) * 1_000_000)
+                } catch {
+                    // Expected when invoke finishes first and cancels the timeout task.
+                    return
+                }
+                guard !Task.isCancelled else { return }
                 timeoutLogger.info("node invoke timeout fired id=\(request.id, privacy: .public)")
                 latch.resume(BridgeInvokeResponse(
                     id: request.id,

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayPayloadDecoding.swift

@@ -2,14 +2,6 @@ import OpenClawProtocol
 import Foundation
 
 public enum GatewayPayloadDecoding {
-    public static func decode<T: Decodable>(
-        _ payload: OpenClawProtocol.AnyCodable,
-        as _: T.Type = T.self) throws -> T
-    {
-        let data = try JSONEncoder().encode(payload)
-        return try JSONDecoder().decode(T.self, from: data)
-    }
-
     public static func decode<T: Decodable>(
         _ payload: AnyCodable,
         as _: T.Type = T.self) throws -> T
@@ -18,14 +10,6 @@ public enum GatewayPayloadDecoding {
         return try JSONDecoder().decode(T.self, from: data)
     }
 
-    public static func decodeIfPresent<T: Decodable>(
-        _ payload: OpenClawProtocol.AnyCodable?,
-        as _: T.Type = T.self) throws -> T?
-    {
-        guard let payload else { return nil }
-        return try self.decode(payload, as: T.self)
-    }
-
     public static func decodeIfPresent<T: Decodable>(
         _ payload: AnyCodable?,
         as _: T.Type = T.self) throws -> T?

apps/shared/OpenClawKit/Sources/OpenClawKit/NetworkInterfaces.swift

@@ -0,0 +1,43 @@
+import Darwin
+import Foundation
+
+public enum NetworkInterfaces {
+    public static func primaryIPv4Address() -> String? {
+        var addrList: UnsafeMutablePointer<ifaddrs>?
+        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
+        defer { freeifaddrs(addrList) }
+
+        var fallback: String?
+        var en0: String?
+
+        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
+            let flags = Int32(ptr.pointee.ifa_flags)
+            let isUp = (flags & IFF_UP) != 0
+            let isLoopback = (flags & IFF_LOOPBACK) != 0
+            let name = String(cString: ptr.pointee.ifa_name)
+            let family = ptr.pointee.ifa_addr.pointee.sa_family
+            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
+
+            var addr = ptr.pointee.ifa_addr.pointee
+            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
+            let result = getnameinfo(
+                &addr,
+                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
+                &buffer,
+                socklen_t(buffer.count),
+                nil,
+                0,
+                NI_NUMERICHOST)
+            guard result == 0 else { continue }
+            let len = buffer.prefix { $0 != 0 }
+            let bytes = len.map { UInt8(bitPattern: $0) }
+            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
+
+            if name == "en0" { en0 = ip; break }
+            if fallback == nil { fallback = ip }
+        }
+
+        return en0 ?? fallback
+    }
+}
+

apps/shared/OpenClawKit/Sources/OpenClawKit/OpenClawKitResources.swift

@@ -52,18 +52,26 @@ public enum OpenClawKitResources {
         for candidate in candidates {
             guard let baseURL = candidate else { continue }
 
-            // Direct path
-            let directURL = baseURL.appendingPathComponent("\(bundleName).bundle")
-            if let bundle = Bundle(url: directURL) {
-                return bundle
+            // SwiftPM often places the resource bundle next to (or near) the test runner bundle,
+            // not inside it. Walk up a few levels and check common container paths.
+            var roots: [URL] = []
+            roots.append(baseURL)
+            roots.append(baseURL.appendingPathComponent("Resources"))
+            roots.append(baseURL.appendingPathComponent("Contents/Resources"))
+
+            var current = baseURL
+            for _ in 0 ..< 5 {
+                current = current.deletingLastPathComponent()
+                roots.append(current)
+                roots.append(current.appendingPathComponent("Resources"))
+                roots.append(current.appendingPathComponent("Contents/Resources"))
             }
 
-            // Inside Resources/
-            let resourcesURL = baseURL
-                .appendingPathComponent("Resources")
-                .appendingPathComponent("\(bundleName).bundle")
-            if let bundle = Bundle(url: resourcesURL) {
-                return bundle
+            for root in roots {
+                let bundleURL = root.appendingPathComponent("\(bundleName).bundle")
+                if let bundle = Bundle(url: bundleURL) {
+                    return bundle
+                }
             }
         }
 

apps/shared/OpenClawKit/Sources/OpenClawKit/PhotoCapture.swift

@@ -0,0 +1,19 @@
+import Foundation
+
+public enum PhotoCapture {
+    public static func transcodeJPEGForGateway(
+        rawData: Data,
+        maxWidthPx: Int,
+        quality: Double,
+        maxPayloadBytes: Int = 5 * 1024 * 1024
+    ) throws -> (data: Data, widthPx: Int, heightPx: Int) {
+        // Base64 inflates payloads by ~4/3; cap encoded bytes so the payload stays under maxPayloadBytes (API limit).
+        let maxEncodedBytes = (maxPayloadBytes / 4) * 3
+        return try JPEGTranscoder.transcodeToJPEG(
+            imageData: rawData,
+            maxWidthPx: maxWidthPx,
+            quality: quality,
+            maxBytes: maxEncodedBytes)
+    }
+}
+

apps/shared/OpenClawKit/Sources/OpenClawKit/TalkPromptBuilder.swift

@@ -1,10 +1,19 @@
 public enum TalkPromptBuilder: Sendable {
-    public static func build(transcript: String, interruptedAtSeconds: Double?) -> String {
+    public static func build(
+        transcript: String,
+        interruptedAtSeconds: Double?,
+        includeVoiceDirectiveHint: Bool = true
+    ) -> String {
         var lines: [String] = [
             "Talk Mode active. Reply in a concise, spoken tone.",
-            "You may optionally prefix the response with JSON (first line) to set ElevenLabs voice (id or alias), e.g. {\"voice\":\"<id>\",\"once\":true}.",
         ]
 
+        if includeVoiceDirectiveHint {
+            lines.append(
+                "You may optionally prefix the response with JSON (first line) to set ElevenLabs voice (id or alias), e.g. {\"voice\":\"<id>\",\"once\":true}."
+            )
+        }
+
         if let interruptedAtSeconds {
             let formatted = String(format: "%.1f", interruptedAtSeconds)
             lines.append("Assistant speech interrupted at \(formatted)s.")

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

@@ -1,8 +1,9 @@
 import Foundation
 
 /// Lightweight `Codable` wrapper that round-trips heterogeneous JSON payloads.
+///
 /// Marked `@unchecked Sendable` because it can hold reference types.
-public struct AnyCodable: Codable, @unchecked Sendable {
+public struct AnyCodable: Codable, @unchecked Sendable, Hashable {
     public let value: Any
 
     public init(_ value: Any) { self.value = value }
@@ -16,9 +17,7 @@ public struct AnyCodable: Codable, @unchecked Sendable {
         if container.decodeNil() { self.value = NSNull(); return }
         if let dict = try? container.decode([String: AnyCodable].self) { self.value = dict; return }
         if let array = try? container.decode([AnyCodable].self) { self.value = array; return }
-        throw DecodingError.dataCorruptedError(
-            in: container,
-            debugDescription: "Unsupported type")
+        throw DecodingError.dataCorruptedError(in: container, debugDescription: "Unsupported type")
     }
 
     public func encode(to encoder: Encoder) throws {
@@ -51,4 +50,46 @@ public struct AnyCodable: Codable, @unchecked Sendable {
             throw EncodingError.invalidValue(self.value, context)
         }
     }
+
+    public static func == (lhs: AnyCodable, rhs: AnyCodable) -> Bool {
+        switch (lhs.value, rhs.value) {
+        case let (l as Int, r as Int): l == r
+        case let (l as Double, r as Double): l == r
+        case let (l as Bool, r as Bool): l == r
+        case let (l as String, r as String): l == r
+        case (_ as NSNull, _ as NSNull): true
+        case let (l as [String: AnyCodable], r as [String: AnyCodable]): l == r
+        case let (l as [AnyCodable], r as [AnyCodable]): l == r
+        default:
+            false
+        }
+    }
+
+    public func hash(into hasher: inout Hasher) {
+        switch self.value {
+        case let v as Int:
+            hasher.combine(0); hasher.combine(v)
+        case let v as Double:
+            hasher.combine(1); hasher.combine(v)
+        case let v as Bool:
+            hasher.combine(2); hasher.combine(v)
+        case let v as String:
+            hasher.combine(3); hasher.combine(v)
+        case _ as NSNull:
+            hasher.combine(4)
+        case let v as [String: AnyCodable]:
+            hasher.combine(5)
+            for (k, val) in v.sorted(by: { $0.key < $1.key }) {
+                hasher.combine(k)
+                hasher.combine(val)
+            }
+        case let v as [AnyCodable]:
+            hasher.combine(6)
+            for item in v {
+                hasher.combine(item)
+            }
+        default:
+            hasher.combine(999)
+        }
+    }
 }

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

@@ -2084,6 +2084,7 @@ public struct SkillsUpdateParams: Codable, Sendable {
 public struct CronJob: Codable, Sendable {
     public let id: String
     public let agentid: String?
+    public let sessionkey: String?
     public let name: String
     public let description: String?
     public let enabled: Bool
@@ -2094,12 +2095,13 @@ public struct CronJob: Codable, Sendable {
     public let sessiontarget: AnyCodable
     public let wakemode: AnyCodable
     public let payload: AnyCodable
-    public let delivery: [String: AnyCodable]?
+    public let delivery: AnyCodable?
     public let state: [String: AnyCodable]
 
     public init(
         id: String,
         agentid: String?,
+        sessionkey: String?,
         name: String,
         description: String?,
         enabled: Bool,
@@ -2110,11 +2112,12 @@ public struct CronJob: Codable, Sendable {
         sessiontarget: AnyCodable,
         wakemode: AnyCodable,
         payload: AnyCodable,
-        delivery: [String: AnyCodable]?,
+        delivery: AnyCodable?,
         state: [String: AnyCodable]
     ) {
         self.id = id
         self.agentid = agentid
+        self.sessionkey = sessionkey
         self.name = name
         self.description = description
         self.enabled = enabled
@@ -2131,6 +2134,7 @@ public struct CronJob: Codable, Sendable {
     private enum CodingKeys: String, CodingKey {
         case id
         case agentid = "agentId"
+        case sessionkey = "sessionKey"
         case name
         case description
         case enabled
@@ -2165,6 +2169,7 @@ public struct CronStatusParams: Codable, Sendable {
 public struct CronAddParams: Codable, Sendable {
     public let name: String
     public let agentid: AnyCodable?
+    public let sessionkey: AnyCodable?
     public let description: String?
     public let enabled: Bool?
     public let deleteafterrun: Bool?
@@ -2172,11 +2177,12 @@ public struct CronAddParams: Codable, Sendable {
     public let sessiontarget: AnyCodable
     public let wakemode: AnyCodable
     public let payload: AnyCodable
-    public let delivery: [String: AnyCodable]?
+    public let delivery: AnyCodable?
 
     public init(
         name: String,
         agentid: AnyCodable?,
+        sessionkey: AnyCodable?,
         description: String?,
         enabled: Bool?,
         deleteafterrun: Bool?,
@@ -2184,10 +2190,11 @@ public struct CronAddParams: Codable, Sendable {
         sessiontarget: AnyCodable,
         wakemode: AnyCodable,
         payload: AnyCodable,
-        delivery: [String: AnyCodable]?
+        delivery: AnyCodable?
     ) {
         self.name = name
         self.agentid = agentid
+        self.sessionkey = sessionkey
         self.description = description
         self.enabled = enabled
         self.deleteafterrun = deleteafterrun
@@ -2200,6 +2207,7 @@ public struct CronAddParams: Codable, Sendable {
     private enum CodingKeys: String, CodingKey {
         case name
         case agentid = "agentId"
+        case sessionkey = "sessionKey"
         case description
         case enabled
         case deleteafterrun = "deleteAfterRun"
@@ -2757,6 +2765,144 @@ public struct ChatEvent: Codable, Sendable {
     }
 }
 
+public struct MeshPlanParams: Codable, Sendable {
+    public let goal: String
+    public let steps: [[String: AnyCodable]]?
+
+    public init(
+        goal: String,
+        steps: [[String: AnyCodable]]?
+    ) {
+        self.goal = goal
+        self.steps = steps
+    }
+    private enum CodingKeys: String, CodingKey {
+        case goal
+        case steps
+    }
+}
+
+public struct MeshPlanAutoParams: Codable, Sendable {
+    public let goal: String
+    public let maxsteps: Int?
+    public let agentid: String?
+    public let sessionkey: String?
+    public let thinking: String?
+    public let timeoutms: Int?
+    public let lane: String?
+
+    public init(
+        goal: String,
+        maxsteps: Int?,
+        agentid: String?,
+        sessionkey: String?,
+        thinking: String?,
+        timeoutms: Int?,
+        lane: String?
+    ) {
+        self.goal = goal
+        self.maxsteps = maxsteps
+        self.agentid = agentid
+        self.sessionkey = sessionkey
+        self.thinking = thinking
+        self.timeoutms = timeoutms
+        self.lane = lane
+    }
+    private enum CodingKeys: String, CodingKey {
+        case goal
+        case maxsteps = "maxSteps"
+        case agentid = "agentId"
+        case sessionkey = "sessionKey"
+        case thinking
+        case timeoutms = "timeoutMs"
+        case lane
+    }
+}
+
+public struct MeshWorkflowPlan: Codable, Sendable {
+    public let planid: String
+    public let goal: String
+    public let createdat: Int
+    public let steps: [[String: AnyCodable]]
+
+    public init(
+        planid: String,
+        goal: String,
+        createdat: Int,
+        steps: [[String: AnyCodable]]
+    ) {
+        self.planid = planid
+        self.goal = goal
+        self.createdat = createdat
+        self.steps = steps
+    }
+    private enum CodingKeys: String, CodingKey {
+        case planid = "planId"
+        case goal
+        case createdat = "createdAt"
+        case steps
+    }
+}
+
+public struct MeshRunParams: Codable, Sendable {
+    public let plan: MeshWorkflowPlan
+    public let continueonerror: Bool?
+    public let maxparallel: Int?
+    public let defaultsteptimeoutms: Int?
+    public let lane: String?
+
+    public init(
+        plan: MeshWorkflowPlan,
+        continueonerror: Bool?,
+        maxparallel: Int?,
+        defaultsteptimeoutms: Int?,
+        lane: String?
+    ) {
+        self.plan = plan
+        self.continueonerror = continueonerror
+        self.maxparallel = maxparallel
+        self.defaultsteptimeoutms = defaultsteptimeoutms
+        self.lane = lane
+    }
+    private enum CodingKeys: String, CodingKey {
+        case plan
+        case continueonerror = "continueOnError"
+        case maxparallel = "maxParallel"
+        case defaultsteptimeoutms = "defaultStepTimeoutMs"
+        case lane
+    }
+}
+
+public struct MeshStatusParams: Codable, Sendable {
+    public let runid: String
+
+    public init(
+        runid: String
+    ) {
+        self.runid = runid
+    }
+    private enum CodingKeys: String, CodingKey {
+        case runid = "runId"
+    }
+}
+
+public struct MeshRetryParams: Codable, Sendable {
+    public let runid: String
+    public let stepids: [String]?
+
+    public init(
+        runid: String,
+        stepids: [String]?
+    ) {
+        self.runid = runid
+        self.stepids = stepids
+    }
+    private enum CodingKeys: String, CodingKey {
+        case runid = "runId"
+        case stepids = "stepIds"
+    }
+}
+
 public struct UpdateRunParams: Codable, Sendable {
     public let sessionkey: String?
     public let note: String?

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

@@ -215,6 +215,103 @@ extension TestChatTransportState {
         #expect(await MainActor.run { vm.pendingToolCalls.isEmpty })
     }
 
+    @Test func acceptsCanonicalSessionKeyEventsForOwnPendingRun() async throws {
+        let history1 = OpenClawChatHistoryPayload(
+            sessionKey: "main",
+            sessionId: "sess-main",
+            messages: [],
+            thinkingLevel: "off")
+        let history2 = OpenClawChatHistoryPayload(
+            sessionKey: "main",
+            sessionId: "sess-main",
+            messages: [
+                AnyCodable([
+                    "role": "assistant",
+                    "content": [["type": "text", "text": "from history"]],
+                    "timestamp": Date().timeIntervalSince1970 * 1000,
+                ]),
+            ],
+            thinkingLevel: "off")
+
+        let transport = TestChatTransport(historyResponses: [history1, history2])
+        let vm = await MainActor.run { OpenClawChatViewModel(sessionKey: "main", transport: transport) }
+
+        await MainActor.run { vm.load() }
+        try await waitUntil("bootstrap") { await MainActor.run { vm.healthOK } }
+
+        await MainActor.run {
+            vm.input = "hi"
+            vm.send()
+        }
+        try await waitUntil("pending run starts") { await MainActor.run { vm.pendingRunCount == 1 } }
+
+        let runId = try #require(await transport.lastSentRunId())
+        transport.emit(
+            .chat(
+                OpenClawChatEventPayload(
+                    runId: runId,
+                    sessionKey: "agent:main:main",
+                    state: "final",
+                    message: nil,
+                    errorMessage: nil)))
+
+        try await waitUntil("pending run clears") { await MainActor.run { vm.pendingRunCount == 0 } }
+        try await waitUntil("history refresh") {
+            await MainActor.run { vm.messages.contains(where: { $0.role == "assistant" }) }
+        }
+    }
+
+    @Test func preservesMessageIDsAcrossHistoryRefreshes() async throws {
+        let now = Date().timeIntervalSince1970 * 1000
+        let history1 = OpenClawChatHistoryPayload(
+            sessionKey: "main",
+            sessionId: "sess-main",
+            messages: [
+                AnyCodable([
+                    "role": "user",
+                    "content": [["type": "text", "text": "hello"]],
+                    "timestamp": now,
+                ]),
+            ],
+            thinkingLevel: "off")
+        let history2 = OpenClawChatHistoryPayload(
+            sessionKey: "main",
+            sessionId: "sess-main",
+            messages: [
+                AnyCodable([
+                    "role": "user",
+                    "content": [["type": "text", "text": "hello"]],
+                    "timestamp": now,
+                ]),
+                AnyCodable([
+                    "role": "assistant",
+                    "content": [["type": "text", "text": "world"]],
+                    "timestamp": now + 1,
+                ]),
+            ],
+            thinkingLevel: "off")
+
+        let transport = TestChatTransport(historyResponses: [history1, history2])
+        let vm = await MainActor.run { OpenClawChatViewModel(sessionKey: "main", transport: transport) }
+
+        await MainActor.run { vm.load() }
+        try await waitUntil("bootstrap") { await MainActor.run { vm.messages.count == 1 } }
+        let firstIdBefore = try #require(await MainActor.run { vm.messages.first?.id })
+
+        transport.emit(
+            .chat(
+                OpenClawChatEventPayload(
+                    runId: "other-run",
+                    sessionKey: "main",
+                    state: "final",
+                    message: nil,
+                    errorMessage: nil)))
+
+        try await waitUntil("history refresh") { await MainActor.run { vm.messages.count == 2 } }
+        let firstIdAfter = try #require(await MainActor.run { vm.messages.first?.id })
+        #expect(firstIdAfter == firstIdBefore)
+    }
+
     @Test func clearsStreamingOnExternalFinalEvent() async throws {
         let sessionId = "sess-main"
         let history = OpenClawChatHistoryPayload(

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

@@ -12,4 +12,18 @@ final class TalkPromptBuilderTests: XCTestCase {
         let prompt = TalkPromptBuilder.build(transcript: "Hi", interruptedAtSeconds: 1.234)
         XCTAssertTrue(prompt.contains("Assistant speech interrupted at 1.2s."))
     }
+
+    func testBuildIncludesVoiceDirectiveHintByDefault() {
+        let prompt = TalkPromptBuilder.build(transcript: "Hello", interruptedAtSeconds: nil)
+        XCTAssertTrue(prompt.contains("ElevenLabs voice"))
+    }
+
+    func testBuildExcludesVoiceDirectiveHintWhenDisabled() {
+        let prompt = TalkPromptBuilder.build(
+            transcript: "Hello",
+            interruptedAtSeconds: nil,
+            includeVoiceDirectiveHint: false)
+        XCTAssertFalse(prompt.contains("ElevenLabs voice"))
+        XCTAssertTrue(prompt.contains("Talk Mode active."))
+    }
 }

docs/automation/cron-jobs.md

@@ -27,6 +27,8 @@ Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
   - **Main session**: enqueue a system event, then run on the next heartbeat.
   - **Isolated**: run a dedicated agent turn in `cron:<jobId>`, with delivery (announce by default or none).
 - Wakeups are first-class: a job can request “wake now” vs “next heartbeat”.
+- Webhook posting is per job via `delivery.mode = "webhook"` + `delivery.to = "<url>"`.
+- Legacy fallback remains for stored jobs with `notify: true` when `cron.webhook` is set, migrate those jobs to webhook delivery mode.
 
 ## Quick start (actionable)
 
@@ -99,7 +101,7 @@ A cron job is a stored record with:
 
 - a **schedule** (when it should run),
 - a **payload** (what it should do),
-- optional **delivery mode** (announce or none).
+- optional **delivery mode** (`announce`, `webhook`, or `none`).
 - optional **agent binding** (`agentId`): run the job under a specific agent; if
   missing or unknown, the gateway falls back to the default agent.
 
@@ -140,8 +142,9 @@ Key behaviors:
 - Prompt is prefixed with `[cron:<jobId> <job name>]` for traceability.
 - Each run starts a **fresh session id** (no prior conversation carry-over).
 - Default behavior: if `delivery` is omitted, isolated jobs announce a summary (`delivery.mode = "announce"`).
-- `delivery.mode` (isolated-only) chooses what happens:
+- `delivery.mode` chooses what happens:
   - `announce`: deliver a summary to the target channel and post a brief summary to the main session.
+  - `webhook`: POST the finished event payload to `delivery.to` when the finished event includes a summary.
   - `none`: internal only (no delivery, no main-session summary).
 - `wakeMode` controls when the main-session summary posts:
   - `now`: immediate heartbeat.
@@ -163,11 +166,11 @@ Common `agentTurn` fields:
 - `model` / `thinking`: optional overrides (see below).
 - `timeoutSeconds`: optional timeout override.
 
-Delivery config (isolated jobs only):
+Delivery config:
 
-- `delivery.mode`: `none` | `announce`.
+- `delivery.mode`: `none` | `announce` | `webhook`.
 - `delivery.channel`: `last` or a specific channel.
-- `delivery.to`: channel-specific target (phone/chat/channel id).
+- `delivery.to`: channel-specific target (announce) or webhook URL (webhook mode).
 - `delivery.bestEffort`: avoid failing the job if announce delivery fails.
 
 Announce delivery suppresses messaging tool sends for the run; use `delivery.channel`/`delivery.to`
@@ -192,6 +195,18 @@ Behavior details:
 - The main-session summary respects `wakeMode`: `now` triggers an immediate heartbeat and
   `next-heartbeat` waits for the next scheduled heartbeat.
 
+#### Webhook delivery flow
+
+When `delivery.mode = "webhook"`, cron posts the finished event payload to `delivery.to` when the finished event includes a summary.
+
+Behavior details:
+
+- The endpoint must be a valid HTTP(S) URL.
+- No channel delivery is attempted in webhook mode.
+- No main-session summary is posted in webhook mode.
+- If `cron.webhookToken` is set, auth header is `Authorization: Bearer <cron.webhookToken>`.
+- Deprecated fallback: stored legacy jobs with `notify: true` still post to `cron.webhook` (if configured), with a warning so you can migrate to `delivery.mode = "webhook"`.
+
 ### Model and thinking overrides
 
 Isolated jobs (`agentTurn`) can override the model and thinking level:
@@ -213,11 +228,12 @@ Resolution priority:
 
 Isolated jobs can deliver output to a channel via the top-level `delivery` config:
 
-- `delivery.mode`: `announce` (deliver a summary) or `none`.
+- `delivery.mode`: `announce` (channel delivery), `webhook` (HTTP POST), or `none`.
 - `delivery.channel`: `whatsapp` / `telegram` / `discord` / `slack` / `mattermost` (plugin) / `signal` / `imessage` / `last`.
 - `delivery.to`: channel-specific recipient target.
 
-Delivery config is only valid for isolated jobs (`sessionTarget: "isolated"`).
+`announce` delivery is only valid for isolated jobs (`sessionTarget: "isolated"`).
+`webhook` delivery is valid for both main and isolated jobs.
 
 If `delivery.channel` or `delivery.to` is omitted, cron can fall back to the main session’s
 “last route” (the last place the agent replied).
@@ -333,10 +349,21 @@ Notes:
     enabled: true, // default true
     store: "~/.openclaw/cron/jobs.json",
     maxConcurrentRuns: 1, // default 1
+    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
+    webhookToken: "replace-with-dedicated-webhook-token", // optional bearer token for webhook mode
   },
 }
 ```
 
+Webhook behavior:
+
+- Preferred: set `delivery.mode: "webhook"` with `delivery.to: "https://..."` per job.
+- Webhook URLs must be valid `http://` or `https://` URLs.
+- When posted, payload is the cron finished event JSON.
+- If `cron.webhookToken` is set, auth header is `Authorization: Bearer <cron.webhookToken>`.
+- If `cron.webhookToken` is not set, no `Authorization` header is sent.
+- Deprecated fallback: stored legacy jobs with `notify: true` still use `cron.webhook` when present.
+
 Disable cron entirely:
 
 - `cron.enabled: false` (config)
@@ -476,3 +503,10 @@ openclaw system event --mode now --text "Next heartbeat: check battery."
 - For forum topics, use `-100…:topic:<id>` so it’s explicit and unambiguous.
 - If you see `telegram:...` prefixes in logs or stored “last route” targets, that’s normal;
   cron delivery accepts them and still parses topic IDs correctly.
+
+### Subagent announce delivery retries
+
+- When a subagent run completes, the gateway announces the result to the requester session.
+- If the announce flow returns `false` (e.g. requester session is busy), the gateway retries up to 3 times with tracking via `announceRetryCount`.
+- Announces older than 5 minutes past `endedAt` are force-expired to prevent stale entries from looping indefinitely.
+- If you see repeated announce deliveries in logs, check the subagent registry for entries with high `announceRetryCount` values.

docs/channels/discord.md

@@ -87,6 +87,86 @@ Token resolution is account-aware. Config token values win over env fallback. `D
 - Group DMs are ignored by default (`channels.discord.dm.groupEnabled=false`).
 - Native slash commands run in isolated command sessions (`agent:<agentId>:discord:slash:<userId>`), while still carrying `CommandTargetSessionKey` to the routed conversation session.
 
+## Interactive components
+
+OpenClaw supports Discord components v2 containers for agent messages. Use the message tool with a `components` payload. Interaction results are routed back to the agent as normal inbound messages and follow the existing Discord `replyToMode` settings.
+
+Supported blocks:
+
+- `text`, `section`, `separator`, `actions`, `media-gallery`, `file`
+- Action rows allow up to 5 buttons or a single select menu
+- Select types: `string`, `user`, `role`, `mentionable`, `channel`
+
+By default, components are single use. Set `components.reusable=true` to allow buttons, selects, and forms to be used multiple times until they expire.
+
+To restrict who can click a button, set `allowedUsers` on that button (Discord user IDs, tags, or `*`). When configured, unmatched users receive an ephemeral denial.
+
+File attachments:
+
+- `file` blocks must point to an attachment reference (`attachment://<filename>`)
+- Provide the attachment via `media`/`path`/`filePath` (single file); use `media-gallery` for multiple files
+- Use `filename` to override the upload name when it should match the attachment reference
+
+Modal forms:
+
+- Add `components.modal` with up to 5 fields
+- Field types: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select`
+- OpenClaw adds a trigger button automatically
+
+Example:
+
+```json5
+{
+  channel: "discord",
+  action: "send",
+  to: "channel:123456789012345678",
+  message: "Optional fallback text",
+  components: {
+    reusable: true,
+    text: "Choose a path",
+    blocks: [
+      {
+        type: "actions",
+        buttons: [
+          {
+            label: "Approve",
+            style: "success",
+            allowedUsers: ["123456789012345678"],
+          },
+          { label: "Decline", style: "danger" },
+        ],
+      },
+      {
+        type: "actions",
+        select: {
+          type: "string",
+          placeholder: "Pick an option",
+          options: [
+            { label: "Option A", value: "a" },
+            { label: "Option B", value: "b" },
+          ],
+        },
+      },
+    ],
+    modal: {
+      title: "Details",
+      triggerLabel: "Open form",
+      fields: [
+        { type: "text", label: "Requester" },
+        {
+          type: "select",
+          label: "Priority",
+          options: [
+            { label: "Low", value: "low" },
+            { label: "High", value: "high" },
+          ],
+        },
+      ],
+    },
+  },
+}
+```
+
 ## Access control and routing
 
 <Tabs>
@@ -313,6 +393,23 @@ See [Slash commands](/tools/slash-commands) for command catalog and behavior.
 
   </Accordion>
 
+  <Accordion title="Ack reactions">
+    `ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message.
+
+    Resolution order:
+
+    - `channels.discord.accounts.<accountId>.ackReaction`
+    - `channels.discord.ackReaction`
+    - `messages.ackReaction`
+    - agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
+
+    Notes:
+
+    - Discord accepts unicode emoji or custom emoji names.
+    - Use `""` to disable the reaction for a channel or account.
+
+  </Accordion>
+
   <Accordion title="Config writes">
     Channel-initiated config writes are enabled by default.
 
@@ -333,7 +430,7 @@ See [Slash commands](/tools/slash-commands) for command catalog and behavior.
   </Accordion>
 
   <Accordion title="Gateway proxy">
-    Route Discord gateway WebSocket traffic through an HTTP(S) proxy with `channels.discord.proxy`.
+    Route Discord gateway WebSocket traffic and startup REST lookups (application ID + allowlist resolution) through an HTTP(S) proxy with `channels.discord.proxy`.
 
 ```json5
 {
@@ -482,6 +579,30 @@ Default gate behavior:
 | moderation                                                                                                                                                               | disabled |
 | presence                                                                                                                                                                 | disabled |
 
+## Components v2 UI
+
+OpenClaw uses Discord components v2 for exec approvals and cross-context markers. Discord message actions can also accept `components` for custom UI (advanced; requires Carbon component instances), while legacy `embeds` remain available but are not recommended.
+
+- `channels.discord.ui.components.accentColor` sets the accent color used by Discord component containers (hex).
+- Set per account with `channels.discord.accounts.<id>.ui.components.accentColor`.
+- `embeds` are ignored when components v2 are present.
+
+Example:
+
+```json5
+{
+  channels: {
+    discord: {
+      ui: {
+        components: {
+          accentColor: "#5865F2",
+        },
+      },
+    },
+  },
+}
+```
+
 ## Voice messages
 
 Discord voice messages show a waveform preview and require OGG/Opus audio plus metadata. OpenClaw generates the waveform automatically, but it needs `ffmpeg` and `ffprobe` available on the gateway host to inspect and convert audio files.
@@ -574,6 +695,7 @@ High-signal Discord fields:
 - media/retry: `mediaMaxMb`, `retry`
 - actions: `actions.*`
 - presence: `activity`, `status`, `activityType`, `activityUrl`
+- UI: `ui.components.accentColor`
 - features: `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix`
 
 ## Safety and operations

docs/channels/grammy.md

@@ -21,7 +21,7 @@ title: grammY
 - **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `channels.telegram.webhookUrl` + `channels.telegram.webhookSecret` are set (otherwise it long-polls).
 - **Sessions:** direct chats collapse into the agent main session (`agent:<agentId>:<mainKey>`); groups use `agent:<agentId>:telegram:group:<chatId>`; replies route back to the same channel.
 - **Config knobs:** `channels.telegram.botToken`, `channels.telegram.dmPolicy`, `channels.telegram.groups` (allowlist + mention defaults), `channels.telegram.allowFrom`, `channels.telegram.groupAllowFrom`, `channels.telegram.groupPolicy`, `channels.telegram.mediaMaxMb`, `channels.telegram.linkPreview`, `channels.telegram.proxy`, `channels.telegram.webhookSecret`, `channels.telegram.webhookUrl`, `channels.telegram.webhookHost`.
-- **Draft streaming:** optional `channels.telegram.streamMode` uses `sendMessageDraft` in private topic chats (Bot API 9.3+). This is separate from channel block streaming.
+- **Live stream preview:** optional `channels.telegram.streamMode` sends a temporary message and updates it with `editMessageText`. This is separate from channel block streaming.
 - **Tests:** grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome.
 
 Open questions

docs/channels/groups.md

@@ -105,7 +105,7 @@ Want “groups can only see folder X” instead of “no host access”? Keep `w
         docker: {
           binds: [
             // hostPath:containerPath:mode
-            "~/FriendsShared:/data:ro",
+            "/home/user/FriendsShared:/data:ro",
           ],
         },
       },

docs/channels/slack.md

@@ -201,6 +201,12 @@ For actions/directory reads, user token can be preferred when configured. For wr
 - Enable native Slack command handlers with `channels.slack.commands.native: true` (or global `commands.native: true`).
 - When native commands are enabled, register matching slash commands in Slack (`/<command>` names).
 - If native commands are not enabled, you can run a single configured slash command via `channels.slack.slashCommand`.
+- Native arg menus now adapt their rendering strategy:
+  - up to 5 options: button blocks
+  - 6-100 options: static select menu
+  - more than 100 options: external select with async option filtering when interactivity options handlers are available
+  - if encoded option values exceed Slack limits, the flow falls back to buttons
+- For long option payloads, Slash command argument menus use a confirm dialog before dispatching a selected value.
 
 Default slash command settings:
 
@@ -286,6 +292,25 @@ Available action groups in current Slack tooling:
 - Member join/leave, channel created/renamed, and pin add/remove events are mapped into system events.
 - `channel_id_changed` can migrate channel config keys when `configWrites` is enabled.
 - Channel topic/purpose metadata is treated as untrusted context and can be injected into routing context.
+- Block actions and modal interactions emit structured `Slack interaction: ...` system events with rich payload fields:
+  - block actions: selected values, labels, picker values, and `workflow_*` metadata
+  - modal `view_submission` and `view_closed` events with routed channel metadata and form inputs
+
+## Ack reactions
+
+`ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message.
+
+Resolution order:
+
+- `channels.slack.accounts.<accountId>.ackReaction`
+- `channels.slack.ackReaction`
+- `messages.ackReaction`
+- agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
+
+Notes:
+
+- Slack expects shortcodes (for example `"eyes"`).
+- Use `""` to disable the reaction for a channel or account.
 
 ## Manifest and scope checklist
 

docs/channels/telegram.md

@@ -221,23 +221,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 ## Feature reference
 
 <AccordionGroup>
-  <Accordion title="Draft streaming in Telegram DMs">
-    OpenClaw can stream partial replies with Telegram draft bubbles (`sendMessageDraft`).
+  <Accordion title="Live stream preview (message edits)">
+    OpenClaw can stream partial replies by sending a temporary Telegram message and editing it as text arrives.
 
-    Requirements:
+    Requirement:
 
     - `channels.telegram.streamMode` is not `"off"` (default: `"partial"`)
-    - private chat
-    - inbound update includes `message_thread_id`
-    - bot topics are enabled (`getMe().has_topics_enabled`)
 
     Modes:
 
-    - `off`: no draft streaming
-    - `partial`: frequent draft updates from partial text
-    - `block`: chunked draft updates using `channels.telegram.draftChunk`
+    - `off`: no live preview
+    - `partial`: frequent preview updates from partial text
+    - `block`: chunked preview updates using `channels.telegram.draftChunk`
 
-    `draftChunk` defaults for block mode:
+    `draftChunk` defaults for `streamMode: "block"`:
 
     - `minChars: 200`
     - `maxChars: 800`
@@ -245,13 +242,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     `maxChars` is clamped by `channels.telegram.textChunkLimit`.
 
-    Draft streaming is DM-only; groups/channels do not use draft bubbles.
+    This works in direct chats and groups/topics.
 
-    If you want early real Telegram messages instead of draft updates, use block streaming (`channels.telegram.blockStreaming: true`).
+    For text-only replies, OpenClaw keeps the same preview message and performs a final edit in place (no second message).
+
+    For complex replies (for example media payloads), OpenClaw falls back to normal final delivery and then cleans up the preview message.
+
+    `streamMode` is separate from block streaming. When block streaming is explicitly enabled for Telegram, OpenClaw skips the preview stream to avoid double-streaming.
 
     Telegram-only reasoning stream:
 
-    - `/reasoning stream` sends reasoning to the draft bubble while generating
+    - `/reasoning stream` sends reasoning to the live preview while generating
     - final answer is sent without reasoning text
 
   </Accordion>
@@ -570,6 +571,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
   </Accordion>
 
+  <Accordion title="Ack reactions">
+    `ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message.
+
+    Resolution order:
+
+    - `channels.telegram.accounts.<accountId>.ackReaction`
+    - `channels.telegram.ackReaction`
+    - `messages.ackReaction`
+    - agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
+
+    Notes:
+
+    - Telegram expects unicode emoji (for example "👀").
+    - Use `""` to disable the reaction for a channel or account.
+
+  </Accordion>
+
   <Accordion title="Config writes from Telegram events and commands">
     Channel config writes are enabled by default (`configWrites !== false`).
 
@@ -703,7 +721,7 @@ Primary reference:
 - `channels.telegram.textChunkLimit`: outbound chunk size (chars).
 - `channels.telegram.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.
 - `channels.telegram.linkPreview`: toggle link previews for outbound messages (default: true).
-- `channels.telegram.streamMode`: `off | partial | block` (draft streaming).
+- `channels.telegram.streamMode`: `off | partial | block` (live stream preview).
 - `channels.telegram.mediaMaxMb`: inbound/outbound media cap (MB).
 - `channels.telegram.retry`: retry policy for outbound Telegram API calls (attempts, minDelayMs, maxDelayMs, jitter).
 - `channels.telegram.network.autoSelectFamily`: override Node autoSelectFamily (true=enable, false=disable). Defaults to disabled on Node 22 to avoid Happy Eyeballs timeouts.
@@ -727,7 +745,7 @@ Telegram-specific high-signal fields:
 - access control: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`
 - command/menu: `commands.native`, `customCommands`
 - threading/replies: `replyToMode`
-- streaming: `streamMode`, `draftChunk`, `blockStreaming`
+- streaming: `streamMode` (preview), `draftChunk`, `blockStreaming`
 - formatting/delivery: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
 - media/network: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `proxy`
 - webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`

docs/concepts/agent-loop.md

@@ -81,7 +81,9 @@ See [Hooks](/automation/hooks) for setup and examples.
 
 These run inside the agent loop or gateway pipeline:
 
-- **`before_agent_start`**: inject context or override system prompt before the run starts.
+- **`before_model_resolve`**: runs pre-session (no `messages`) to deterministically override provider/model before model resolution.
+- **`before_prompt_build`**: runs after session load (with `messages`) to inject `prependContext`/`systemPrompt` before prompt submission.
+- **`before_agent_start`**: legacy compatibility hook that may run in either phase; prefer the explicit hooks above.
 - **`agent_end`**: inspect the final message list and run metadata after completion.
 - **`before_compaction` / `after_compaction`**: observe or annotate compaction cycles.
 - **`before_tool_call` / `after_tool_call`**: intercept tool params/results.

docs/concepts/agent-workspace.md

@@ -116,7 +116,8 @@ See [Memory](/concepts/memory) for the workflow and automatic memory flush.
 
 If any bootstrap file is missing, OpenClaw injects a "missing file" marker into
 the session and continues. Large bootstrap files are truncated when injected;
-adjust the limit with `agents.defaults.bootstrapMaxChars` (default: 20000).
+adjust limits with `agents.defaults.bootstrapMaxChars` (default: 20000) and
+`agents.defaults.bootstrapTotalMaxChars` (default: 150000).
 `openclaw setup` can recreate missing defaults without overwriting existing
 files.
 

docs/concepts/context.md

@@ -112,7 +112,7 @@ By default, OpenClaw injects a fixed set of workspace files (if present):
 - `HEARTBEAT.md`
 - `BOOTSTRAP.md` (first-run only)
 
-Large files are truncated per-file using `agents.defaults.bootstrapMaxChars` (default `20000` chars). OpenClaw also enforces a total bootstrap injection cap across files with `agents.defaults.bootstrapTotalMaxChars` (default `24000` chars). `/context` shows **raw vs injected** sizes and whether truncation happened.
+Large files are truncated per-file using `agents.defaults.bootstrapMaxChars` (default `20000` chars). OpenClaw also enforces a total bootstrap injection cap across files with `agents.defaults.bootstrapTotalMaxChars` (default `150000` chars). `/context` shows **raw vs injected** sizes and whether truncation happened.
 
 ## Skills: what’s injected vs loaded on-demand
 

docs/concepts/memory.md

@@ -396,11 +396,11 @@ But it can be weak at exact, high-signal tokens:
 
 - IDs (`a828e60`, `b3b9895a…`)
 - code symbols (`memorySearch.query.hybrid`)
-- error strings (“sqlite-vec unavailable”)
+- error strings ("sqlite-vec unavailable")
 
 BM25 (full-text) is the opposite: strong at exact tokens, weaker at paraphrases.
 Hybrid search is the pragmatic middle ground: **use both retrieval signals** so you get
-good results for both “natural language” queries and “needle in a haystack” queries.
+good results for both "natural language" queries and "needle in a haystack" queries.
 
 #### How we merge results (the current design)
 
@@ -423,13 +423,142 @@ Notes:
 
 - `vectorWeight` + `textWeight` is normalized to 1.0 in config resolution, so weights behave as percentages.
 - If embeddings are unavailable (or the provider returns a zero-vector), we still run BM25 and return keyword matches.
-- If FTS5 can’t be created, we keep vector-only search (no hard failure).
+- If FTS5 can't be created, we keep vector-only search (no hard failure).
 
-This isn’t “IR-theory perfect”, but it’s simple, fast, and tends to improve recall/precision on real notes.
+This isn't "IR-theory perfect", but it's simple, fast, and tends to improve recall/precision on real notes.
 If we want to get fancier later, common next steps are Reciprocal Rank Fusion (RRF) or score normalization
 (min/max or z-score) before mixing.
 
-Config:
+#### Post-processing pipeline
+
+After merging vector and keyword scores, two optional post-processing stages
+refine the result list before it reaches the agent:
+
+```
+Vector + Keyword → Weighted Merge → Temporal Decay → Sort → MMR → Top-K Results
+```
+
+Both stages are **off by default** and can be enabled independently.
+
+#### MMR re-ranking (diversity)
+
+When hybrid search returns results, multiple chunks may contain similar or overlapping content.
+For example, searching for "home network setup" might return five nearly identical snippets
+from different daily notes that all mention the same router configuration.
+
+**MMR (Maximal Marginal Relevance)** re-ranks the results to balance relevance with diversity,
+ensuring the top results cover different aspects of the query instead of repeating the same information.
+
+How it works:
+
+1. Results are scored by their original relevance (vector + BM25 weighted score).
+2. MMR iteratively selects results that maximize: `λ × relevance − (1−λ) × max_similarity_to_selected`.
+3. Similarity between results is measured using Jaccard text similarity on tokenized content.
+
+The `lambda` parameter controls the trade-off:
+
+- `lambda = 1.0` → pure relevance (no diversity penalty)
+- `lambda = 0.0` → maximum diversity (ignores relevance)
+- Default: `0.7` (balanced, slight relevance bias)
+
+**Example — query: "home network setup"**
+
+Given these memory files:
+
+```
+memory/2026-02-10.md  → "Configured Omada router, set VLAN 10 for IoT devices"
+memory/2026-02-08.md  → "Configured Omada router, moved IoT to VLAN 10"
+memory/2026-02-05.md  → "Set up AdGuard DNS on 192.168.10.2"
+memory/network.md     → "Router: Omada ER605, AdGuard: 192.168.10.2, VLAN 10: IoT"
+```
+
+Without MMR — top 3 results:
+
+```
+1. memory/2026-02-10.md  (score: 0.92)  ← router + VLAN
+2. memory/2026-02-08.md  (score: 0.89)  ← router + VLAN (near-duplicate!)
+3. memory/network.md     (score: 0.85)  ← reference doc
+```
+
+With MMR (λ=0.7) — top 3 results:
+
+```
+1. memory/2026-02-10.md  (score: 0.92)  ← router + VLAN
+2. memory/network.md     (score: 0.85)  ← reference doc (diverse!)
+3. memory/2026-02-05.md  (score: 0.78)  ← AdGuard DNS (diverse!)
+```
+
+The near-duplicate from Feb 8 drops out, and the agent gets three distinct pieces of information.
+
+**When to enable:** If you notice `memory_search` returning redundant or near-duplicate snippets,
+especially with daily notes that often repeat similar information across days.
+
+#### Temporal decay (recency boost)
+
+Agents with daily notes accumulate hundreds of dated files over time. Without decay,
+a well-worded note from six months ago can outrank yesterday's update on the same topic.
+
+**Temporal decay** applies an exponential multiplier to scores based on the age of each result,
+so recent memories naturally rank higher while old ones fade:
+
+```
+decayedScore = score × e^(-λ × ageInDays)
+```
+
+where `λ = ln(2) / halfLifeDays`.
+
+With the default half-life of 30 days:
+
+- Today's notes: **100%** of original score
+- 7 days ago: **~84%**
+- 30 days ago: **50%**
+- 90 days ago: **12.5%**
+- 180 days ago: **~1.6%**
+
+**Evergreen files are never decayed:**
+
+- `MEMORY.md` (root memory file)
+- Non-dated files in `memory/` (e.g., `memory/projects.md`, `memory/network.md`)
+- These contain durable reference information that should always rank normally.
+
+**Dated daily files** (`memory/YYYY-MM-DD.md`) use the date extracted from the filename.
+Other sources (e.g., session transcripts) fall back to file modification time (`mtime`).
+
+**Example — query: "what's Rod's work schedule?"**
+
+Given these memory files (today is Feb 10):
+
+```
+memory/2025-09-15.md  → "Rod works Mon-Fri, standup at 10am, pairing at 2pm"  (148 days old)
+memory/2026-02-10.md  → "Rod has standup at 14:15, 1:1 with Zeb at 14:45"    (today)
+memory/2026-02-03.md  → "Rod started new team, standup moved to 14:15"        (7 days old)
+```
+
+Without decay:
+
+```
+1. memory/2025-09-15.md  (score: 0.91)  ← best semantic match, but stale!
+2. memory/2026-02-10.md  (score: 0.82)
+3. memory/2026-02-03.md  (score: 0.80)
+```
+
+With decay (halfLife=30):
+
+```
+1. memory/2026-02-10.md  (score: 0.82 × 1.00 = 0.82)  ← today, no decay
+2. memory/2026-02-03.md  (score: 0.80 × 0.85 = 0.68)  ← 7 days, mild decay
+3. memory/2025-09-15.md  (score: 0.91 × 0.03 = 0.03)  ← 148 days, nearly gone
+```
+
+The stale September note drops to the bottom despite having the best raw semantic match.
+
+**When to enable:** If your agent has months of daily notes and you find that old,
+stale information outranks recent context. A half-life of 30 days works well for
+daily-note-heavy workflows; increase it (e.g., 90 days) if you reference older notes frequently.
+
+#### Configuration
+
+Both features are configured under `memorySearch.query.hybrid`:
 
 ```json5
 agents: {
@@ -440,7 +569,17 @@ agents: {
           enabled: true,
           vectorWeight: 0.7,
           textWeight: 0.3,
-          candidateMultiplier: 4
+          candidateMultiplier: 4,
+          // Diversity: reduce redundant results
+          mmr: {
+            enabled: true,    // default: false
+            lambda: 0.7       // 0 = max diversity, 1 = max relevance
+          },
+          // Recency: boost newer memories
+          temporalDecay: {
+            enabled: true,    // default: false
+            halfLifeDays: 30  // score halves every 30 days
+          }
         }
       }
     }
@@ -448,6 +587,12 @@ agents: {
 }
 ```
 
+You can enable either feature independently:
+
+- **MMR only** — useful when you have many similar notes but age doesn't matter.
+- **Temporal decay only** — useful when recency matters but your results are already diverse.
+- **Both** — recommended for agents with large, long-running daily note histories.
+
 ### Embedding cache
 
 OpenClaw can cache **chunk embeddings** in SQLite so reindexing and frequent updates (especially session transcripts) don't re-embed unchanged text.

docs/concepts/session-tool.md

@@ -176,12 +176,24 @@ Behavior:
 
 ## Sandbox Session Visibility
 
-Sandboxed sessions can use session tools, but by default they only see sessions they spawned via `sessions_spawn`.
+Session tools can be scoped to reduce cross-session access.
+
+Default behavior:
+
+- `tools.sessions.visibility` defaults to `tree` (current session + spawned subagent sessions).
+- For sandboxed sessions, `agents.defaults.sandbox.sessionToolsVisibility` can hard-clamp visibility.
 
 Config:
 
 ```json5
 {
+  tools: {
+    sessions: {
+      // "self" | "tree" | "agent" | "all"
+      // default: "tree"
+      visibility: "tree",
+    },
+  },
   agents: {
     defaults: {
       sandbox: {
@@ -192,3 +204,11 @@ Config:
   },
 }
 ```
+
+Notes:
+
+- `self`: only the current session key.
+- `tree`: current session + sessions spawned by the current session.
+- `agent`: any session belonging to the current agent id.
+- `all`: any session (cross-agent access still requires `tools.agentToAgent`).
+- When a session is sandboxed and `sessionToolsVisibility="spawned"`, OpenClaw clamps visibility to `tree` even if you set `tools.sessions.visibility="all"`.