test: skip unix-path OPENCLAW_HOME tests on Windows

- session-key.test.ts: verify both :dm: and :direct: keys are valid
- getDmHistoryLimitFromSessionKey: verify both formats work

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

@@ -0,0 +1,41 @@
+name: Setup pnpm + store cache
+description: Prepare pnpm via corepack and restore pnpm store cache.
+inputs:
+  pnpm-version:
+    description: pnpm version to activate via corepack.
+    required: false
+    default: "10.23.0"
+  cache-key-suffix:
+    description: Suffix appended to the cache key.
+    required: false
+    default: "node22"
+runs:
+  using: composite
+  steps:
+    - name: Setup pnpm (corepack retry)
+      shell: bash
+      run: |
+        set -euo pipefail
+        corepack enable
+        for attempt in 1 2 3; do
+          if corepack prepare "pnpm@${{ inputs.pnpm-version }}" --activate; then
+            pnpm -v
+            exit 0
+          fi
+          echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+          sleep $((attempt * 10))
+        done
+        exit 1
+
+    - name: Resolve pnpm store path
+      id: pnpm-store
+      shell: bash
+      run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
+
+    - name: Restore pnpm store cache
+      uses: actions/cache@v4
+      with:
+        path: ${{ steps.pnpm-store.outputs.path }}
+        key: ${{ runner.os }}-pnpm-store-${{ inputs.cache-key-suffix }}-${{ hashFiles('pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-store-${{ inputs.cache-key-suffix }}-

.github/instructions/copilot.instructions.md

@@ -0,0 +1,64 @@
+# OpenClaw Codebase Patterns
+
+**Always reuse existing code - no redundancy!**
+
+## Tech Stack
+
+- **Runtime**: Node 22+ (Bun also supported for dev/scripts)
+- **Language**: TypeScript (ESM, strict mode)
+- **Package Manager**: pnpm (keep `pnpm-lock.yaml` in sync)
+- **Lint/Format**: Oxlint, Oxfmt (`pnpm check`)
+- **Tests**: Vitest with V8 coverage
+- **CLI Framework**: Commander + clack/prompts
+- **Build**: tsdown (outputs to `dist/`)
+
+## Anti-Redundancy Rules
+
+- Avoid files that just re-export from another file. Import directly from the original source.
+- If a function already exists, import it - do NOT create a duplicate in another file.
+- Before creating any formatter, utility, or helper, search for existing implementations first.
+
+## Source of Truth Locations
+
+### Formatting Utilities (`src/infra/`)
+
+- **Time formatting**: `src\infra\format-time`
+
+**NEVER create local `formatAge`, `formatDuration`, `formatElapsedTime` functions - import from centralized modules.**
+
+### Terminal Output (`src/terminal/`)
+
+- Tables: `src/terminal/table.ts` (`renderTable`)
+- Themes/colors: `src/terminal/theme.ts` (`theme.success`, `theme.muted`, etc.)
+- Progress: `src/cli/progress.ts` (spinners, progress bars)
+
+### CLI Patterns
+
+- CLI option wiring: `src/cli/`
+- Commands: `src/commands/`
+- Dependency injection via `createDefaultDeps`
+
+## Import Conventions
+
+- Use `.js` extension for cross-package imports (ESM)
+- Direct imports only - no re-export wrapper files
+- Types: `import type { X }` for type-only imports
+
+## Code Quality
+
+- TypeScript (ESM), strict typing, avoid `any`
+- Keep files under ~700 LOC - extract helpers when larger
+- Colocated tests: `*.test.ts` next to source files
+- Run `pnpm check` before commits (lint + format)
+- Run `pnpm tsgo` for type checking
+
+## Stack & Commands
+
+- **Package manager**: pnpm (`pnpm install`)
+- **Dev**: `pnpm openclaw ...` or `pnpm dev`
+- **Type-check**: `pnpm tsgo`
+- **Lint/format**: `pnpm check`
+- **Tests**: `pnpm test`
+- **Build**: `pnpm build`
+
+If you are coding together with a human, do NOT use scripts/committer, but git directly and run the above commands manually to ensure quality.

.github/workflows/ci.yml

@@ -27,9 +27,101 @@ jobs:
         id: check
         uses: ./.github/actions/detect-docs-only
 
-  install-check:
+  # Detect which heavy areas are touched so PRs can skip unrelated expensive jobs.
+  # Push to main keeps broad coverage.
+  changed-scope:
     needs: [docs-scope]
     if: needs.docs-scope.outputs.docs_only != 'true'
+    runs-on: ubuntu-latest
+    outputs:
+      run_node: ${{ steps.scope.outputs.run_node }}
+      run_macos: ${{ steps.scope.outputs.run_macos }}
+      run_android: ${{ steps.scope.outputs.run_android }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: false
+
+      - name: Detect changed scopes
+        id: scope
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [ "${{ github.event_name }}" = "push" ]; then
+            BASE="${{ github.event.before }}"
+          else
+            BASE="${{ github.event.pull_request.base.sha }}"
+          fi
+
+          CHANGED="$(git diff --name-only "$BASE" HEAD 2>/dev/null || echo "UNKNOWN")"
+          if [ "$CHANGED" = "UNKNOWN" ] || [ -z "$CHANGED" ]; then
+            # Fail-safe: run broad checks if detection fails.
+            echo "run_node=true" >> "$GITHUB_OUTPUT"
+            echo "run_macos=true" >> "$GITHUB_OUTPUT"
+            echo "run_android=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          run_node=false
+          run_macos=false
+          run_android=false
+          has_non_docs=false
+          has_non_native_non_docs=false
+
+          while IFS= read -r path; do
+            [ -z "$path" ] && continue
+            case "$path" in
+              docs/*|*.md|*.mdx)
+                continue
+                ;;
+              *)
+                has_non_docs=true
+                ;;
+            esac
+
+            case "$path" in
+              apps/macos/*|apps/ios/*|apps/shared/*|Swabble/*)
+                run_macos=true
+                ;;
+            esac
+
+            case "$path" in
+              apps/android/*|apps/shared/*)
+                run_android=true
+                ;;
+            esac
+
+            case "$path" in
+              src/*|test/*|extensions/*|packages/*|scripts/*|ui/*|.github/*|openclaw.mjs|package.json|pnpm-lock.yaml|pnpm-workspace.yaml|tsconfig*.json|vitest*.ts|tsdown.config.ts|.oxlintrc.json|.oxfmtrc.jsonc)
+                run_node=true
+                ;;
+            esac
+
+            case "$path" in
+              apps/android/*|apps/ios/*|apps/macos/*|apps/shared/*|Swabble/*|appcast.xml)
+                ;;
+              *)
+                has_non_native_non_docs=true
+                ;;
+            esac
+          done <<< "$CHANGED"
+
+          # If there are non-doc files outside native app trees, keep Node checks enabled.
+          if [ "$run_node" = false ] && [ "$has_non_docs" = true ] && [ "$has_non_native_non_docs" = true ]; then
+            run_node=true
+          fi
+
+          echo "run_node=${run_node}" >> "$GITHUB_OUTPUT"
+          echo "run_macos=${run_macos}" >> "$GITHUB_OUTPUT"
+          echo "run_android=${run_android}" >> "$GITHUB_OUTPUT"
+
+  # Build dist once for Node-relevant changes and share it with downstream jobs.
+  build-artifacts:
+    needs: [docs-scope, changed-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout
@@ -56,20 +148,76 @@ jobs:
           node-version: 22.x
           check-latest: true
 
-      - name: Setup pnpm (corepack retry)
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          pnpm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Install dependencies (frozen)
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Build dist
+        run: pnpm build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-build
+          path: dist/
+          retention-days: 1
+
+  install-check:
+    needs: [docs-scope, changed-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (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
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
               exit 0
             fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+            echo "Submodule update failed (attempt $attempt/5). 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: Runtime versions
         run: |
           node -v
@@ -90,8 +238,8 @@ jobs:
           pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
 
   checks:
-    needs: [docs-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true'
+    needs: [docs-scope, changed-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
       fail-fast: false
@@ -108,7 +256,7 @@ jobs:
             command: pnpm protocol:check
           - runtime: bun
             task: test
-            command: pnpm canvas:a2ui:bundle && bunx vitest run
+            command: pnpm canvas:a2ui:bundle && bunx vitest run --config vitest.unit.config.ts
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -134,19 +282,11 @@ jobs:
           node-version: 22.x
           check-latest: true
 
-      - 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 pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -184,7 +324,7 @@ jobs:
       matrix:
         include:
           - task: lint
-            command: pnpm build && pnpm lint
+            command: pnpm lint
           - task: format
             command: pnpm format
     steps:
@@ -212,19 +352,11 @@ jobs:
           node-version: 22.x
           check-latest: true
 
-      - 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 pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -280,8 +412,8 @@ jobs:
           fi
 
   checks-windows:
-    needs: [docs-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true'
+    needs: [docs-scope, changed-scope, build-artifacts]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-windows-2025
     env:
       NODE_OPTIONS: --max-old-space-size=4096
@@ -296,8 +428,8 @@ jobs:
       matrix:
         include:
           - runtime: node
-            task: build & lint
-            command: pnpm build && pnpm lint
+            task: lint
+            command: pnpm lint
           - runtime: node
             task: test
             command: pnpm canvas:a2ui:bundle && pnpm test
@@ -342,25 +474,31 @@ jobs:
           done
           exit 1
 
+      - name: Download dist artifact (lint lane)
+        if: matrix.task == 'lint'
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-build
+          path: dist/
+
+      - name: Verify dist artifact (lint lane)
+        if: matrix.task == 'lint'
+        run: |
+          set -euo pipefail
+          test -s dist/index.js
+          test -s dist/plugin-sdk/index.js
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 22.x
           check-latest: true
 
-      - 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 pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -395,8 +533,8 @@ jobs:
   # running 4 separate jobs per PR (as before) starved the queue. One job
   # per PR allows 5 PRs to run macOS checks simultaneously.
   macos:
-    needs: [docs-scope]
-    if: github.event_name == 'pull_request' && needs.docs-scope.outputs.docs_only != 'true'
+    needs: [docs-scope, changed-scope]
+    if: github.event_name == 'pull_request' && needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_macos == 'true'
     runs-on: macos-latest
     steps:
       - name: Checkout
@@ -424,19 +562,11 @@ jobs:
           node-version: 22.x
           check-latest: true
 
-      - 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 pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Runtime versions
         run: |
@@ -681,8 +811,8 @@ jobs:
           PY
 
   android:
-    needs: [docs-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true'
+    needs: [docs-scope, changed-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_android == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
       fail-fast: false

.gitignore

@@ -72,6 +72,7 @@ USER.md
 .serena/
 
 # Agent credentials and memory (NEVER COMMIT)
-memory/
+/memory/
 .agent/*.json
 !.agent/workflows/
+local/

CHANGELOG.md

@@ -7,21 +7,44 @@ Docs: https://docs.openclaw.ai
 ### Added
 
 - Gateway: add `agents.create`, `agents.update`, `agents.delete` RPC methods for web UI agent management. (#11045) Thanks @advaitpaliwal.
+- Gateway: add node command allowlists (default-deny unknown node commands; configurable via `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`). (#11755) Thanks @mbelinky.
+- Plugins: add `device-pair` (Telegram `/pair` flow) and `phone-control` (iOS/Android node controls). (#11755) Thanks @mbelinky.
+- iOS: add alpha iOS node app (Telegram setup-code pairing + Talk/Chat surfaces). (#11756) Thanks @mbelinky.
+- Docs: seed initial ja-JP translations (POC) and make docs-i18n prompts language-pluggable for Japanese. (#11988) Thanks @joshp123.
+- Paths: add `OPENCLAW_HOME` environment variable for overriding the home directory used by all internal path resolution. (#12091) Thanks @sebslight.
 
 ### Fixes
 
+- Exec approvals: format forwarded command text as inline/fenced monospace for safer approval scanning across channels. (#11937)
+- Config: clamp `maxTokens` to `contextWindow` to prevent invalid model configs. (#5516) Thanks @lailoo.
+- Docs: fix language switcher ordering and Japanese locale flag in Mintlify nav. (#12023) Thanks @joshp123.
+- Paths: make internal path resolution respect `HOME`/`USERPROFILE` before `os.homedir()` across config, agents, sessions, pairing, cron, and CLI profiles. (#12091) Thanks @sebslight.
+- Thinking: allow xhigh for `github-copilot/gpt-5.2-codex` and `github-copilot/gpt-5.2`. (#11646) Thanks @seans-openclawbot.
+- Discord: support forum/media `thread create` starter messages, wire `message thread create --message`, and harden thread-create routing. (#10062) Thanks @jarvis89757.
+- Gateway: stabilize chat routing by canonicalizing node session keys for node-originated chat methods. (#11755) Thanks @mbelinky.
+- Web UI: make chat refresh smoothly scroll to the latest messages and suppress new-messages badge flash during manual refresh.
+- Cron: route text-only isolated agent announces through the shared subagent announce flow; add exponential backoff for repeated errors; preserve future `nextRunAtMs` on restart; include current-boundary schedule matches; prevent stale threadId reuse across targets; and add per-job execution timeout. (#11641) Thanks @tyler6204.
+- Subagents: stabilize announce timing, preserve compaction metrics across retries, clamp overflow-prone long timeouts, and cap impossible context usage token totals. (#11551) Thanks @tyler6204.
 - Agents: recover from context overflow caused by oversized tool results (pre-emptive capping + fallback truncation). (#11579) Thanks @tyler6204.
+- Telegram: render markdown spoilers with `<tg-spoiler>` HTML tags. (#11543) Thanks @ezhikkk.
 - Gateway/CLI: when `gateway.bind=lan`, use a LAN IP for probe URLs and Control UI links. (#11448) Thanks @AnonO6.
 - Memory: set Voyage embeddings `input_type` for improved retrieval. (#10818) Thanks @mcinteerj.
 - Memory/QMD: run boot refresh in background by default, add configurable QMD maintenance timeouts, and retry QMD after fallback failures. (#9690, #9705)
+- Memory/QMD: log explicit warnings when `memory.qmd.scope` blocks a search request. (#10191)
 - Media understanding: recognize `.caf` audio attachments for transcription. (#10982) Thanks @succ985.
 - State dir: honor `OPENCLAW_STATE_DIR` for default device identity and canvas storage paths. (#4824) Thanks @kossoy.
+- Doctor/State dir: suppress repeated legacy migration warnings only for valid symlink mirrors, while keeping warnings for empty or invalid legacy trees. (#11709) Thanks @gumadeiras.
 - Tests: harden flaky hotspots by removing timer sleeps, consolidating onboarding provider-auth coverage, and improving memory test realism. (#11598) Thanks @gumadeiras.
 
 ## 2026.2.6
 
 ### Changes
 
+- Hygiene: remove `workspace:*` from `dependencies` in msteams, nostr, zalo extensions (breaks external `npm install`; keep in `devDependencies` only).
+- Hygiene: add non-root `sandbox` user to `Dockerfile.sandbox` and `Dockerfile.sandbox-browser`.
+- Hygiene: remove dead `vitest` key from `package.json` (superseded by `vitest.config.ts`).
+- Hygiene: remove redundant top-level `overrides` from `package.json` (pnpm uses `pnpm.overrides`).
+- Hygiene: sync `onlyBuiltDependencies` between `pnpm-workspace.yaml` and `package.json` (add missing `node-llama-cpp`, sort alphabetically).
 - Cron: default `wakeMode` is now `"now"` for new jobs (was `"next-heartbeat"`). (#10776) Thanks @tyler6204.
 - Cron: `cron run` defaults to force execution; use `--due` to restrict to due-only. (#10776) Thanks @tyler6204.
 - Models: support Anthropic Opus 4.6 and OpenAI Codex gpt-5.3-codex (forward-compat fallbacks). (#9853, #10720, #9995) Thanks @TinyTb, @calvin-hpnet, @tyler6204.

Dockerfile.sandbox

@@ -13,4 +13,8 @@ RUN apt-get update \
     ripgrep \
   && rm -rf /var/lib/apt/lists/*
 
+RUN useradd --create-home --shell /bin/bash sandbox
+USER sandbox
+WORKDIR /home/sandbox
+
 CMD ["sleep", "infinity"]

Dockerfile.sandbox-browser

@@ -23,6 +23,10 @@ RUN apt-get update \
 COPY scripts/sandbox-browser-entrypoint.sh /usr/local/bin/openclaw-sandbox-browser
 RUN chmod +x /usr/local/bin/openclaw-sandbox-browser
 
+RUN useradd --create-home --shell /bin/bash sandbox
+USER sandbox
+WORKDIR /home/sandbox
+
 EXPOSE 9222 5900 6080
 
 CMD ["openclaw-sandbox-browser"]

SECURITY.md

@@ -4,8 +4,13 @@ If you believe you've found a security issue in OpenClaw, please report it priva
 
 ## Reporting
 
-- Email: `steipete@gmail.com`
-- What to include: reproduction steps, impact assessment, and (if possible) a minimal PoC.
+For full reporting instructions - including which repo to report to and how - see our [Trust page](https://trust.openclaw.ai).
+
+Include: reproduction steps, impact assessment, and (if possible) a minimal PoC.
+
+## Security & Trust
+
+**Jamieson O'Reilly** ([@theonejvo](https://twitter.com/theonejvo)) is Security & Trust at OpenClaw. Jamieson is the founder of [Dvuln](https://dvuln.com) and brings extensive experience in offensive security, penetration testing, and security program development.
 
 ## Bug Bounties
 

apps/ios/README.md

@@ -1,28 +1,66 @@
 # OpenClaw (iOS)
 
-Internal-only SwiftUI app scaffold.
+This is an **alpha** iOS app that connects to an OpenClaw Gateway as a `role: node`.
+
+Expect rough edges:
+
+- UI and onboarding are changing quickly.
+- Background behavior is not stable yet (foreground app is the supported mode right now).
+- Permissions are opt-in and the app should be treated as sensitive while we harden it.
+
+## What It Does
+
+- Connects to a Gateway over `ws://` / `wss://`
+- Pairs a new device (approved from your bot)
+- Exposes phone services as node commands (camera, location, photos, calendar, reminders, etc; gated by iOS permissions)
+- Provides Talk + Chat surfaces (alpha)
+
+## Pairing (Recommended Flow)
+
+If your Gateway has the `device-pair` plugin installed:
+
+1. In Telegram, message your bot: `/pair`
+2. Copy the **setup code** message
+3. On iOS: OpenClaw → Settings → Gateway → paste setup code → Connect
+4. Back in Telegram: `/pair approve`
+
+## Build And Run
+
+Prereqs:
+
+- Xcode (current stable)
+- `pnpm`
+- `xcodegen`
+
+From the repo root:
 
-## Lint/format (required)
 ```bash
-brew install swiftformat swiftlint
+pnpm install
+pnpm ios:open
 ```
 
-## Generate the Xcode project
+Then in Xcode:
+
+1. Select the `OpenClaw` scheme
+2. Select a simulator or a connected device
+3. Run
+
+If you're using a personal Apple Development team, you may need to change the bundle identifier in Xcode to a unique value so signing succeeds.
+
+## Build From CLI
+
+```bash
+pnpm ios:build
+```
+
+## Tests
+
 ```bash
 cd apps/ios
 xcodegen generate
-open OpenClaw.xcodeproj
+xcodebuild test -project OpenClaw.xcodeproj -scheme OpenClaw -destination "platform=iOS Simulator,name=iPhone 17"
 ```
 
-## Shared packages
-- `../shared/OpenClawKit` — shared types/constants used by iOS (and later macOS bridge + gateway routing).
+## Shared Code
 
-## fastlane
-```bash
-brew install fastlane
-
-cd apps/ios
-fastlane lanes
-```
-
-See `apps/ios/fastlane/SETUP.md` for App Store Connect auth + upload lanes.
+- `apps/shared/OpenClawKit` contains the shared transport/types used by the iOS app.

apps/ios/Sources/Calendar/CalendarService.swift

@@ -0,0 +1,167 @@
+import EventKit
+import Foundation
+import OpenClawKit
+
+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)
+        guard authorized else {
+            throw NSError(domain: "Calendar", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "CALENDAR_PERMISSION_REQUIRED: grant Calendar permission",
+            ])
+        }
+
+        let (start, end) = Self.resolveRange(
+            startISO: params.startISO,
+            endISO: params.endISO)
+        let predicate = store.predicateForEvents(withStart: start, end: end, calendars: nil)
+        let events = store.events(matching: predicate)
+        let limit = max(1, min(params.limit ?? 50, 500))
+        let selected = Array(events.prefix(limit))
+
+        let formatter = ISO8601DateFormatter()
+        let payload = selected.map { event in
+            OpenClawCalendarEventPayload(
+                identifier: event.eventIdentifier ?? UUID().uuidString,
+                title: event.title ?? "(untitled)",
+                startISO: formatter.string(from: event.startDate),
+                endISO: formatter.string(from: event.endDate),
+                isAllDay: event.isAllDay,
+                location: event.location,
+                calendarTitle: event.calendar.title)
+        }
+
+        return OpenClawCalendarEventsPayload(events: payload)
+    }
+
+    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)
+        guard authorized else {
+            throw NSError(domain: "Calendar", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "CALENDAR_PERMISSION_REQUIRED: grant Calendar permission",
+            ])
+        }
+
+        let title = params.title.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !title.isEmpty else {
+            throw NSError(domain: "Calendar", code: 3, userInfo: [
+                NSLocalizedDescriptionKey: "CALENDAR_INVALID: title required",
+            ])
+        }
+
+        let formatter = ISO8601DateFormatter()
+        guard let start = formatter.date(from: params.startISO) else {
+            throw NSError(domain: "Calendar", code: 4, userInfo: [
+                NSLocalizedDescriptionKey: "CALENDAR_INVALID: startISO required",
+            ])
+        }
+        guard let end = formatter.date(from: params.endISO) else {
+            throw NSError(domain: "Calendar", code: 5, userInfo: [
+                NSLocalizedDescriptionKey: "CALENDAR_INVALID: endISO required",
+            ])
+        }
+
+        let event = EKEvent(eventStore: store)
+        event.title = title
+        event.startDate = start
+        event.endDate = end
+        event.isAllDay = params.isAllDay ?? false
+        if let location = params.location?.trimmingCharacters(in: .whitespacesAndNewlines), !location.isEmpty {
+            event.location = location
+        }
+        if let notes = params.notes?.trimmingCharacters(in: .whitespacesAndNewlines), !notes.isEmpty {
+            event.notes = notes
+        }
+        event.calendar = try Self.resolveCalendar(
+            store: store,
+            calendarId: params.calendarId,
+            calendarTitle: params.calendarTitle)
+
+        try store.save(event, span: .thisEvent)
+
+        let payload = OpenClawCalendarEventPayload(
+            identifier: event.eventIdentifier ?? UUID().uuidString,
+            title: event.title ?? title,
+            startISO: formatter.string(from: event.startDate),
+            endISO: formatter.string(from: event.endDate),
+            isAllDay: event.isAllDay,
+            location: event.location,
+            calendarTitle: event.calendar.title)
+
+        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?,
+        calendarTitle: String?) throws -> EKCalendar
+    {
+        if let id = calendarId?.trimmingCharacters(in: .whitespacesAndNewlines), !id.isEmpty,
+           let calendar = store.calendar(withIdentifier: id)
+        {
+            return calendar
+        }
+
+        if let title = calendarTitle?.trimmingCharacters(in: .whitespacesAndNewlines), !title.isEmpty {
+            if let calendar = store.calendars(for: .event).first(where: {
+                $0.title.compare(title, options: [.caseInsensitive, .diacriticInsensitive]) == .orderedSame
+            }) {
+                return calendar
+            }
+            throw NSError(domain: "Calendar", code: 6, userInfo: [
+                NSLocalizedDescriptionKey: "CALENDAR_NOT_FOUND: no calendar named \(title)",
+            ])
+        }
+
+        if let fallback = store.defaultCalendarForNewEvents {
+            return fallback
+        }
+
+        throw NSError(domain: "Calendar", code: 7, userInfo: [
+            NSLocalizedDescriptionKey: "CALENDAR_NOT_FOUND: no default calendar",
+        ])
+    }
+
+    private static func resolveRange(startISO: String?, endISO: String?) -> (Date, Date) {
+        let formatter = ISO8601DateFormatter()
+        let start = startISO.flatMap { formatter.date(from: $0) } ?? Date()
+        let end = endISO.flatMap { formatter.date(from: $0) } ?? start.addingTimeInterval(7 * 24 * 3600)
+        return (start, end)
+    }
+}

apps/ios/Sources/Capabilities/NodeCapabilityRouter.swift

@@ -0,0 +1,25 @@
+import Foundation
+import OpenClawKit
+
+@MainActor
+final class NodeCapabilityRouter {
+    enum RouterError: Error {
+        case unknownCommand
+        case handlerUnavailable
+    }
+
+    typealias Handler = (BridgeInvokeRequest) async throws -> BridgeInvokeResponse
+
+    private let handlers: [String: Handler]
+
+    init(handlers: [String: Handler]) {
+        self.handlers = handlers
+    }
+
+    func handle(_ request: BridgeInvokeRequest) async throws -> BridgeInvokeResponse {
+        guard let handler = handlers[request.command] else {
+            throw RouterError.unknownCommand
+        }
+        return try await handler(request)
+    }
+}

apps/ios/Sources/Chat/ChatSheet.swift

@@ -6,14 +6,16 @@ struct ChatSheet: View {
     @Environment(\.dismiss) private var dismiss
     @State private var viewModel: OpenClawChatViewModel
     private let userAccent: Color?
+    private let agentName: String?
 
-    init(gateway: GatewayNodeSession, sessionKey: String, userAccent: Color? = nil) {
+    init(gateway: GatewayNodeSession, sessionKey: String, agentName: String? = nil, userAccent: Color? = nil) {
         let transport = IOSGatewayChatTransport(gateway: gateway)
         self._viewModel = State(
             initialValue: OpenClawChatViewModel(
                 sessionKey: sessionKey,
                 transport: transport))
         self.userAccent = userAccent
+        self.agentName = agentName
     }
 
     var body: some View {
@@ -22,7 +24,7 @@ struct ChatSheet: View {
                 viewModel: self.viewModel,
                 showsSessionSwitcher: true,
                 userAccent: self.userAccent)
-                .navigationTitle("Chat")
+                .navigationTitle(self.chatTitle)
                 .navigationBarTitleDisplayMode(.inline)
                 .toolbar {
                     ToolbarItem(placement: .topBarTrailing) {
@@ -36,4 +38,10 @@ struct ChatSheet: View {
                 }
         }
     }
+
+    private var chatTitle: String {
+        let trimmed = (self.agentName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return "Chat" }
+        return "Chat (\(trimmed))"
+    }
 }

apps/ios/Sources/Contacts/ContactsService.swift

@@ -0,0 +1,212 @@
+import Contacts
+import Foundation
+import OpenClawKit
+
+final class ContactsService: ContactsServicing {
+    private static var payloadKeys: [CNKeyDescriptor] {
+        [
+            CNContactIdentifierKey as CNKeyDescriptor,
+            CNContactGivenNameKey as CNKeyDescriptor,
+            CNContactFamilyNameKey as CNKeyDescriptor,
+            CNContactOrganizationNameKey as CNKeyDescriptor,
+            CNContactPhoneNumbersKey as CNKeyDescriptor,
+            CNContactEmailAddressesKey as CNKeyDescriptor,
+        ]
+    }
+
+    func search(params: OpenClawContactsSearchParams) async throws -> OpenClawContactsSearchPayload {
+        let store = CNContactStore()
+        let status = CNContactStore.authorizationStatus(for: .contacts)
+        let authorized = await Self.ensureAuthorization(store: store, status: status)
+        guard authorized else {
+            throw NSError(domain: "Contacts", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "CONTACTS_PERMISSION_REQUIRED: grant Contacts permission",
+            ])
+        }
+
+        let limit = max(1, min(params.limit ?? 25, 200))
+
+        var contacts: [CNContact] = []
+        if let query = params.query?.trimmingCharacters(in: .whitespacesAndNewlines), !query.isEmpty {
+            let predicate = CNContact.predicateForContacts(matchingName: query)
+            contacts = try store.unifiedContacts(matching: predicate, keysToFetch: Self.payloadKeys)
+        } else {
+            let request = CNContactFetchRequest(keysToFetch: Self.payloadKeys)
+            try store.enumerateContacts(with: request) { contact, stop in
+                contacts.append(contact)
+                if contacts.count >= limit {
+                    stop.pointee = true
+                }
+            }
+        }
+
+        let sliced = Array(contacts.prefix(limit))
+        let payload = sliced.map { Self.payload(from: $0) }
+
+        return OpenClawContactsSearchPayload(contacts: payload)
+    }
+
+    func add(params: OpenClawContactsAddParams) async throws -> OpenClawContactsAddPayload {
+        let store = CNContactStore()
+        let status = CNContactStore.authorizationStatus(for: .contacts)
+        let authorized = await Self.ensureAuthorization(store: store, status: status)
+        guard authorized else {
+            throw NSError(domain: "Contacts", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "CONTACTS_PERMISSION_REQUIRED: grant Contacts permission",
+            ])
+        }
+
+        let givenName = params.givenName?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let familyName = params.familyName?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let organizationName = params.organizationName?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let displayName = params.displayName?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let phoneNumbers = Self.normalizeStrings(params.phoneNumbers)
+        let emails = Self.normalizeStrings(params.emails, lowercased: true)
+
+        let hasName = !(givenName ?? "").isEmpty || !(familyName ?? "").isEmpty || !(displayName ?? "").isEmpty
+        let hasOrg = !(organizationName ?? "").isEmpty
+        let hasDetails = !phoneNumbers.isEmpty || !emails.isEmpty
+        guard hasName || hasOrg || hasDetails else {
+            throw NSError(domain: "Contacts", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "CONTACTS_INVALID: include a name, organization, phone, or email",
+            ])
+        }
+
+        if !phoneNumbers.isEmpty || !emails.isEmpty {
+            if let existing = try Self.findExistingContact(
+                store: store,
+                phoneNumbers: phoneNumbers,
+                emails: emails)
+            {
+                return OpenClawContactsAddPayload(contact: Self.payload(from: existing))
+            }
+        }
+
+        let contact = CNMutableContact()
+        contact.givenName = givenName ?? ""
+        contact.familyName = familyName ?? ""
+        contact.organizationName = organizationName ?? ""
+        if contact.givenName.isEmpty && contact.familyName.isEmpty, let displayName {
+            contact.givenName = displayName
+        }
+        contact.phoneNumbers = phoneNumbers.map {
+            CNLabeledValue(label: CNLabelPhoneNumberMobile, value: CNPhoneNumber(stringValue: $0))
+        }
+        contact.emailAddresses = emails.map {
+            CNLabeledValue(label: CNLabelHome, value: $0 as NSString)
+        }
+
+        let save = CNSaveRequest()
+        save.add(contact, toContainerWithIdentifier: nil)
+        try store.execute(save)
+
+        let persisted: CNContact
+        if !contact.identifier.isEmpty {
+            persisted = try store.unifiedContact(
+                withIdentifier: contact.identifier,
+                keysToFetch: Self.payloadKeys)
+        } else {
+            persisted = contact
+        }
+
+        return OpenClawContactsAddPayload(contact: Self.payload(from: persisted))
+    }
+
+    private static func ensureAuthorization(store: CNContactStore, status: CNAuthorizationStatus) async -> Bool {
+        switch status {
+        case .authorized, .limited:
+            return true
+        case .notDetermined:
+            // Don’t prompt during node.invoke; the caller should instruct the user to grant permission.
+            // Prompts block the invoke and lead to timeouts in headless flows.
+            return false
+        case .restricted, .denied:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+
+    private static func normalizeStrings(_ values: [String]?, lowercased: Bool = false) -> [String] {
+        (values ?? [])
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .map { lowercased ? $0.lowercased() : $0 }
+    }
+
+    private static func findExistingContact(
+        store: CNContactStore,
+        phoneNumbers: [String],
+        emails: [String]) throws -> CNContact?
+    {
+        if phoneNumbers.isEmpty && emails.isEmpty {
+            return nil
+        }
+
+        var matches: [CNContact] = []
+
+        for phone in phoneNumbers {
+            let predicate = CNContact.predicateForContacts(matching: CNPhoneNumber(stringValue: phone))
+            let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: Self.payloadKeys)
+            matches.append(contentsOf: contacts)
+        }
+
+        for email in emails {
+            let predicate = CNContact.predicateForContacts(matchingEmailAddress: email)
+            let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: Self.payloadKeys)
+            matches.append(contentsOf: contacts)
+        }
+
+        return Self.matchContacts(contacts: matches, phoneNumbers: phoneNumbers, emails: emails)
+    }
+
+    private static func matchContacts(
+        contacts: [CNContact],
+        phoneNumbers: [String],
+        emails: [String]) -> CNContact?
+    {
+        let normalizedPhones = Set(phoneNumbers.map { normalizePhone($0) }.filter { !$0.isEmpty })
+        let normalizedEmails = Set(emails.map { $0.lowercased() }.filter { !$0.isEmpty })
+        var seen = Set<String>()
+
+        for contact in contacts {
+            guard seen.insert(contact.identifier).inserted else { continue }
+            let contactPhones = Set(contact.phoneNumbers.map { normalizePhone($0.value.stringValue) })
+            let contactEmails = Set(contact.emailAddresses.map { String($0.value).lowercased() })
+
+            if !normalizedPhones.isEmpty, !contactPhones.isDisjoint(with: normalizedPhones) {
+                return contact
+            }
+            if !normalizedEmails.isEmpty, !contactEmails.isDisjoint(with: normalizedEmails) {
+                return contact
+            }
+        }
+
+        return nil
+    }
+
+    private static func normalizePhone(_ phone: String) -> String {
+        let trimmed = phone.trimmingCharacters(in: .whitespacesAndNewlines)
+        let digits = trimmed.unicodeScalars.filter { CharacterSet.decimalDigits.contains($0) }
+        let normalized = String(String.UnicodeScalarView(digits))
+        return normalized.isEmpty ? trimmed : normalized
+    }
+
+    private static func payload(from contact: CNContact) -> OpenClawContactPayload {
+        OpenClawContactPayload(
+            identifier: contact.identifier,
+            displayName: CNContactFormatter.string(from: contact, style: .fullName)
+                ?? "\(contact.givenName) \(contact.familyName)".trimmingCharacters(in: .whitespacesAndNewlines),
+            givenName: contact.givenName,
+            familyName: contact.familyName,
+            organizationName: contact.organizationName,
+            phoneNumbers: contact.phoneNumbers.map { $0.value.stringValue },
+            emails: contact.emailAddresses.map { String($0.value) })
+    }
+
+#if DEBUG
+    static func _test_matches(contact: CNContact, phoneNumbers: [String], emails: [String]) -> Bool {
+        matchContacts(contacts: [contact], phoneNumbers: phoneNumbers, emails: emails) != nil
+    }
+#endif
+}

apps/ios/Sources/Device/DeviceStatusService.swift

@@ -0,0 +1,87 @@
+import Foundation
+import OpenClawKit
+import UIKit
+
+final class DeviceStatusService: DeviceStatusServicing {
+    private let networkStatus: NetworkStatusService
+
+    init(networkStatus: NetworkStatusService = NetworkStatusService()) {
+        self.networkStatus = networkStatus
+    }
+
+    func status() async throws -> OpenClawDeviceStatusPayload {
+        let battery = self.batteryStatus()
+        let thermal = self.thermalStatus()
+        let storage = self.storageStatus()
+        let network = await self.networkStatus.currentStatus()
+        let uptime = ProcessInfo.processInfo.systemUptime
+
+        return OpenClawDeviceStatusPayload(
+            battery: battery,
+            thermal: thermal,
+            storage: storage,
+            network: network,
+            uptimeSeconds: uptime)
+    }
+
+    func info() -> OpenClawDeviceInfoPayload {
+        let device = UIDevice.current
+        let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"
+        let appBuild = Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "0"
+        let locale = Locale.preferredLanguages.first ?? Locale.current.identifier
+        return OpenClawDeviceInfoPayload(
+            deviceName: device.name,
+            modelIdentifier: Self.modelIdentifier(),
+            systemName: device.systemName,
+            systemVersion: device.systemVersion,
+            appVersion: appVersion,
+            appBuild: appBuild,
+            locale: locale)
+    }
+
+    private func batteryStatus() -> OpenClawBatteryStatusPayload {
+        let device = UIDevice.current
+        device.isBatteryMonitoringEnabled = true
+        let level = device.batteryLevel >= 0 ? Double(device.batteryLevel) : nil
+        let state: OpenClawBatteryState = switch device.batteryState {
+        case .charging: .charging
+        case .full: .full
+        case .unplugged: .unplugged
+        case .unknown: .unknown
+        @unknown default: .unknown
+        }
+        return OpenClawBatteryStatusPayload(
+            level: level,
+            state: state,
+            lowPowerModeEnabled: ProcessInfo.processInfo.isLowPowerModeEnabled)
+    }
+
+    private func thermalStatus() -> OpenClawThermalStatusPayload {
+        let state: OpenClawThermalState = switch ProcessInfo.processInfo.thermalState {
+        case .nominal: .nominal
+        case .fair: .fair
+        case .serious: .serious
+        case .critical: .critical
+        @unknown default: .nominal
+        }
+        return OpenClawThermalStatusPayload(state: state)
+    }
+
+    private func storageStatus() -> OpenClawStorageStatusPayload {
+        let attrs = (try? FileManager.default.attributesOfFileSystem(forPath: NSHomeDirectory())) ?? [:]
+        let total = (attrs[.systemSize] as? NSNumber)?.int64Value ?? 0
+        let free = (attrs[.systemFreeSize] as? NSNumber)?.int64Value ?? 0
+        let used = max(0, total - free)
+        return OpenClawStorageStatusPayload(totalBytes: total, freeBytes: free, usedBytes: used)
+    }
+
+    private static func modelIdentifier() -> String {
+        var systemInfo = utsname()
+        uname(&systemInfo)
+        let machine = withUnsafeBytes(of: &systemInfo.machine) { ptr in
+            String(bytes: ptr.prefix { $0 != 0 }, encoding: .utf8)
+        }
+        let trimmed = machine?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? "unknown" : trimmed
+    }
+}

apps/ios/Sources/Device/NetworkStatusService.swift

@@ -0,0 +1,69 @@
+import Foundation
+import Network
+import OpenClawKit
+
+final class NetworkStatusService: @unchecked Sendable {
+    func currentStatus(timeoutMs: Int = 1500) async -> OpenClawNetworkStatusPayload {
+        await withCheckedContinuation { cont in
+            let monitor = NWPathMonitor()
+            let queue = DispatchQueue(label: "bot.molt.ios.network-status")
+            let state = NetworkStatusState()
+
+            monitor.pathUpdateHandler = { path in
+                guard state.markCompleted() else { return }
+                monitor.cancel()
+                cont.resume(returning: Self.payload(from: path))
+            }
+
+            monitor.start(queue: queue)
+
+            queue.asyncAfter(deadline: .now() + .milliseconds(timeoutMs)) {
+                guard state.markCompleted() else { return }
+                monitor.cancel()
+                cont.resume(returning: Self.fallbackPayload())
+            }
+        }
+    }
+
+    private static func payload(from path: NWPath) -> OpenClawNetworkStatusPayload {
+        let status: OpenClawNetworkPathStatus = switch path.status {
+        case .satisfied: .satisfied
+        case .requiresConnection: .requiresConnection
+        case .unsatisfied: .unsatisfied
+        @unknown default: .unsatisfied
+        }
+
+        var interfaces: [OpenClawNetworkInterfaceType] = []
+        if path.usesInterfaceType(.wifi) { interfaces.append(.wifi) }
+        if path.usesInterfaceType(.cellular) { interfaces.append(.cellular) }
+        if path.usesInterfaceType(.wiredEthernet) { interfaces.append(.wired) }
+        if interfaces.isEmpty { interfaces.append(.other) }
+
+        return OpenClawNetworkStatusPayload(
+            status: status,
+            isExpensive: path.isExpensive,
+            isConstrained: path.isConstrained,
+            interfaces: interfaces)
+    }
+
+    private static func fallbackPayload() -> OpenClawNetworkStatusPayload {
+        OpenClawNetworkStatusPayload(
+            status: .unsatisfied,
+            isExpensive: false,
+            isConstrained: false,
+            interfaces: [.other])
+    }
+}
+
+private final class NetworkStatusState: @unchecked Sendable {
+    private let lock = NSLock()
+    private var completed = false
+
+    func markCompleted() -> Bool {
+        self.lock.lock()
+        defer { self.lock.unlock() }
+        if self.completed { return false }
+        self.completed = true
+        return true
+    }
+}

apps/ios/Sources/Device/NodeDisplayName.swift

@@ -0,0 +1,48 @@
+import Foundation
+import UIKit
+
+enum NodeDisplayName {
+    private static let genericNames: Set<String> = ["iOS Node", "iPhone Node", "iPad Node"]
+
+    static func isGeneric(_ name: String) -> Bool {
+        Self.genericNames.contains(name)
+    }
+
+    static func defaultValue(for interfaceIdiom: UIUserInterfaceIdiom) -> String {
+        switch interfaceIdiom {
+        case .phone:
+            return "iPhone Node"
+        case .pad:
+            return "iPad Node"
+        default:
+            return "iOS Node"
+        }
+    }
+
+    static func resolve(
+        existing: String?,
+        deviceName: String,
+        interfaceIdiom: UIUserInterfaceIdiom
+    ) -> String {
+        let trimmedExisting = existing?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedExisting.isEmpty, !Self.isGeneric(trimmedExisting) {
+            return trimmedExisting
+        }
+
+        let trimmedDevice = deviceName.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let normalized = Self.normalizedDeviceName(trimmedDevice) {
+            return normalized
+        }
+
+        return Self.defaultValue(for: interfaceIdiom)
+    }
+
+    private static func normalizedDeviceName(_ deviceName: String) -> String? {
+        guard !deviceName.isEmpty else { return nil }
+        let lower = deviceName.lowercased()
+        if lower.contains("iphone") || lower.contains("ipad") || lower.contains("ios") {
+            return deviceName
+        }
+        return nil
+    }
+}

apps/ios/Sources/Gateway/GatewayConnectConfig.swift

@@ -0,0 +1,27 @@
+import Foundation
+import OpenClawKit
+
+/// Single source of truth for "how we connect" to the current gateway.
+///
+/// The iOS app maintains two WebSocket sessions to the same gateway:
+/// - a `role=node` session for device capabilities (`node.invoke.*`)
+/// - a `role=operator` session for chat/talk/config (`chat.*`, `talk.*`, etc.)
+///
+/// Both sessions should derive all connection inputs from this config so we
+/// don't accidentally persist gateway-scoped state under different keys.
+struct GatewayConnectConfig: Sendable {
+    let url: URL
+    let stableID: String
+    let tls: GatewayTLSParams?
+    let token: String?
+    let password: String?
+    let nodeOptions: GatewayConnectOptions
+
+    /// Stable, non-empty identifier used for gateway-scoped persistence keys.
+    /// If the caller doesn't provide a stableID, fall back to URL identity.
+    var effectiveStableID: String {
+        let trimmed = self.stableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return self.url.absoluteString }
+        return trimmed
+    }
+}

apps/ios/Sources/Gateway/GatewayConnectionController.swift

@@ -1,8 +1,15 @@
-import OpenClawKit
-import Darwin
+import AVFoundation
+import Contacts
+import CoreLocation
+import CoreMotion
+import EventKit
 import Foundation
+import OpenClawKit
 import Network
 import Observation
+import Photos
+import ReplayKit
+import Speech
 import SwiftUI
 import UIKit
 
@@ -42,8 +49,10 @@ final class GatewayConnectionController {
             self.discovery.stop()
         case .active, .inactive:
             self.discovery.start()
+            self.attemptAutoReconnectIfNeeded()
         @unknown default:
             self.discovery.start()
+            self.attemptAutoReconnectIfNeeded()
         }
     }
 
@@ -60,6 +69,11 @@ final class GatewayConnectionController {
             port: port,
             useTLS: tlsParams?.required == true)
         else { return }
+        GatewaySettingsStore.saveLastGatewayConnection(
+            host: host,
+            port: port,
+            useTLS: tlsParams?.required == true,
+            stableID: gateway.stableID)
         self.didAutoConnect = true
         self.startAutoConnect(
             url: url,
@@ -74,13 +88,24 @@ final class GatewayConnectionController {
             .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
         let token = GatewaySettingsStore.loadGatewayToken(instanceId: instanceId)
         let password = GatewaySettingsStore.loadGatewayPassword(instanceId: instanceId)
-        let stableID = self.manualStableID(host: host, port: port)
-        let tlsParams = self.resolveManualTLSParams(stableID: stableID, tlsEnabled: useTLS)
+        let resolvedUseTLS = useTLS
+        guard let resolvedPort = self.resolveManualPort(host: host, port: port, useTLS: resolvedUseTLS)
+        else { return }
+        let stableID = self.manualStableID(host: host, port: resolvedPort)
+        let tlsParams = self.resolveManualTLSParams(
+            stableID: stableID,
+            tlsEnabled: resolvedUseTLS,
+            allowTOFUReset: self.shouldForceTLS(host: host))
         guard let url = self.buildGatewayURL(
             host: host,
-            port: port,
+            port: resolvedPort,
             useTLS: tlsParams?.required == true)
         else { return }
+        GatewaySettingsStore.saveLastGatewayConnection(
+            host: host,
+            port: resolvedPort,
+            useTLS: tlsParams?.required == true,
+            stableID: stableID)
         self.didAutoConnect = true
         self.startAutoConnect(
             url: url,
@@ -90,6 +115,38 @@ final class GatewayConnectionController {
             password: password)
     }
 
+    func connectLastKnown() async {
+        guard let last = GatewaySettingsStore.loadLastGatewayConnection() else { return }
+        let instanceId = UserDefaults.standard.string(forKey: "node.instanceId")?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let token = GatewaySettingsStore.loadGatewayToken(instanceId: instanceId)
+        let password = GatewaySettingsStore.loadGatewayPassword(instanceId: instanceId)
+        let resolvedUseTLS = last.useTLS
+        let tlsParams = self.resolveManualTLSParams(
+            stableID: last.stableID,
+            tlsEnabled: resolvedUseTLS,
+            allowTOFUReset: self.shouldForceTLS(host: last.host))
+        guard let url = self.buildGatewayURL(
+            host: last.host,
+            port: last.port,
+            useTLS: tlsParams?.required == true)
+        else { return }
+        if resolvedUseTLS != last.useTLS {
+            GatewaySettingsStore.saveLastGatewayConnection(
+                host: last.host,
+                port: last.port,
+                useTLS: resolvedUseTLS,
+                stableID: last.stableID)
+        }
+        self.didAutoConnect = true
+        self.startAutoConnect(
+            url: url,
+            gatewayStableID: last.stableID,
+            tls: tlsParams,
+            token: token,
+            password: password)
+    }
+
     private func updateFromDiscovery() {
         let newGateways = self.discovery.gateways
         self.gateways = newGateways
@@ -119,6 +176,7 @@ final class GatewayConnectionController {
         guard appModel.gatewayServerName == nil else { return }
 
         let defaults = UserDefaults.standard
+        guard defaults.bool(forKey: "gateway.autoconnect") else { return }
         let manualEnabled = defaults.bool(forKey: "gateway.manual.enabled")
 
         let instanceId = defaults.string(forKey: "node.instanceId")?
@@ -134,11 +192,19 @@ final class GatewayConnectionController {
             guard !manualHost.isEmpty else { return }
 
             let manualPort = defaults.integer(forKey: "gateway.manual.port")
-            let resolvedPort = manualPort > 0 ? manualPort : 18789
             let manualTLS = defaults.bool(forKey: "gateway.manual.tls")
+            let resolvedUseTLS = manualTLS || self.shouldForceTLS(host: manualHost)
+            guard let resolvedPort = self.resolveManualPort(
+                host: manualHost,
+                port: manualPort,
+                useTLS: resolvedUseTLS)
+            else { return }
 
             let stableID = self.manualStableID(host: manualHost, port: resolvedPort)
-            let tlsParams = self.resolveManualTLSParams(stableID: stableID, tlsEnabled: manualTLS)
+            let tlsParams = self.resolveManualTLSParams(
+                stableID: stableID,
+                tlsEnabled: resolvedUseTLS,
+                allowTOFUReset: self.shouldForceTLS(host: manualHost))
 
             guard let url = self.buildGatewayURL(
                 host: manualHost,
@@ -156,30 +222,80 @@ final class GatewayConnectionController {
             return
         }
 
+        if let lastKnown = GatewaySettingsStore.loadLastGatewayConnection() {
+            let resolvedUseTLS = lastKnown.useTLS || self.shouldForceTLS(host: lastKnown.host)
+            let tlsParams = self.resolveManualTLSParams(
+                stableID: lastKnown.stableID,
+                tlsEnabled: resolvedUseTLS,
+                allowTOFUReset: self.shouldForceTLS(host: lastKnown.host))
+            guard let url = self.buildGatewayURL(
+                host: lastKnown.host,
+                port: lastKnown.port,
+                useTLS: tlsParams?.required == true)
+            else { return }
+
+            self.didAutoConnect = true
+            self.startAutoConnect(
+                url: url,
+                gatewayStableID: lastKnown.stableID,
+                tls: tlsParams,
+                token: token,
+                password: password)
+            return
+        }
+
         let preferredStableID = defaults.string(forKey: "gateway.preferredStableID")?
             .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
         let lastDiscoveredStableID = defaults.string(forKey: "gateway.lastDiscoveredStableID")?
             .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
 
         let candidates = [preferredStableID, lastDiscoveredStableID].filter { !$0.isEmpty }
-        guard let targetStableID = candidates.first(where: { id in
+        if let targetStableID = candidates.first(where: { id in
             self.gateways.contains(where: { $0.stableID == id })
-        }) else { return }
+        }) {
+            guard let target = self.gateways.first(where: { $0.stableID == targetStableID }) else { return }
+            guard let host = self.resolveGatewayHost(target) else { return }
+            let port = target.gatewayPort ?? 18789
+            let tlsParams = self.resolveDiscoveredTLSParams(gateway: target)
+            guard let url = self.buildGatewayURL(host: host, port: port, useTLS: tlsParams?.required == true)
+            else { return }
 
-        guard let target = self.gateways.first(where: { $0.stableID == targetStableID }) else { return }
-        guard let host = self.resolveGatewayHost(target) else { return }
-        let port = target.gatewayPort ?? 18789
-        let tlsParams = self.resolveDiscoveredTLSParams(gateway: target)
-        guard let url = self.buildGatewayURL(host: host, port: port, useTLS: tlsParams?.required == true)
-        else { return }
+            self.didAutoConnect = true
+            self.startAutoConnect(
+                url: url,
+                gatewayStableID: target.stableID,
+                tls: tlsParams,
+                token: token,
+                password: password)
+            return
+        }
 
-        self.didAutoConnect = true
-        self.startAutoConnect(
-            url: url,
-            gatewayStableID: target.stableID,
-            tls: tlsParams,
-            token: token,
-            password: password)
+        if self.gateways.count == 1, let gateway = self.gateways.first {
+            guard let host = self.resolveGatewayHost(gateway) else { return }
+            let port = gateway.gatewayPort ?? 18789
+            let tlsParams = self.resolveDiscoveredTLSParams(gateway: gateway)
+            guard let url = self.buildGatewayURL(host: host, port: port, useTLS: tlsParams?.required == true)
+            else { return }
+
+            self.didAutoConnect = true
+            self.startAutoConnect(
+                url: url,
+                gatewayStableID: gateway.stableID,
+                tls: tlsParams,
+                token: token,
+                password: password)
+            return
+        }
+    }
+
+    private func attemptAutoReconnectIfNeeded() {
+        guard let appModel = self.appModel else { return }
+        guard appModel.gatewayAutoReconnectEnabled else { return }
+        // Avoid starting duplicate connect loops while a prior config is active.
+        guard appModel.activeGatewayConnectConfig == nil else { return }
+        guard UserDefaults.standard.bool(forKey: "gateway.autoconnect") else { return }
+        self.didAutoConnect = false
+        self.maybeAutoConnect()
     }
 
     private func updateLastDiscoveredGateway(from gateways: [GatewayDiscoveryModel.DiscoveredGateway]) {
@@ -205,20 +321,21 @@ final class GatewayConnectionController {
         password: String?)
     {
         guard let appModel else { return }
-        let connectOptions = self.makeConnectOptions()
+        let connectOptions = self.makeConnectOptions(stableID: gatewayStableID)
 
-        Task { [weak self] in
-            guard let self else { return }
+        Task { [weak appModel] in
+            guard let appModel else { return }
             await MainActor.run {
                 appModel.gatewayStatusText = "Connecting…"
             }
-            appModel.connectToGateway(
+            let cfg = GatewayConnectConfig(
                 url: url,
-                gatewayStableID: gatewayStableID,
+                stableID: gatewayStableID,
                 tls: tls,
                 token: token,
                 password: password,
-                connectOptions: connectOptions)
+                nodeOptions: connectOptions)
+            appModel.applyGatewayConnectConfig(cfg)
         }
     }
 
@@ -237,13 +354,17 @@ final class GatewayConnectionController {
         return nil
     }
 
-    private func resolveManualTLSParams(stableID: String, tlsEnabled: Bool) -> GatewayTLSParams? {
+    private func resolveManualTLSParams(
+        stableID: String,
+        tlsEnabled: Bool,
+        allowTOFUReset: Bool = false) -> GatewayTLSParams?
+    {
         let stored = GatewayTLSStore.loadFingerprint(stableID: stableID)
         if tlsEnabled || stored != nil {
             return GatewayTLSParams(
                 required: true,
                 expectedFingerprint: stored,
-                allowTOFU: stored == nil,
+                allowTOFU: stored == nil || allowTOFUReset,
                 storeKey: stableID)
         }
 
@@ -251,12 +372,12 @@ final class GatewayConnectionController {
     }
 
     private func resolveGatewayHost(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String? {
-        if let lanHost = gateway.lanHost?.trimmingCharacters(in: .whitespacesAndNewlines), !lanHost.isEmpty {
-            return lanHost
-        }
         if let tailnet = gateway.tailnetDns?.trimmingCharacters(in: .whitespacesAndNewlines), !tailnet.isEmpty {
             return tailnet
         }
+        if let lanHost = gateway.lanHost?.trimmingCharacters(in: .whitespacesAndNewlines), !lanHost.isEmpty {
+            return lanHost
+        }
         return nil
     }
 
@@ -269,38 +390,69 @@ final class GatewayConnectionController {
         return components.url
     }
 
+    private func shouldForceTLS(host: String) -> Bool {
+        let trimmed = host.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if trimmed.isEmpty { return false }
+        return trimmed.hasSuffix(".ts.net") || trimmed.hasSuffix(".ts.net.")
+    }
+
     private func manualStableID(host: String, port: Int) -> String {
         "manual|\(host.lowercased())|\(port)"
     }
 
-    private func makeConnectOptions() -> GatewayConnectOptions {
+    private func makeConnectOptions(stableID: String?) -> GatewayConnectOptions {
         let defaults = UserDefaults.standard
         let displayName = self.resolvedDisplayName(defaults: defaults)
+        let resolvedClientId = self.resolvedClientId(defaults: defaults, stableID: stableID)
 
         return GatewayConnectOptions(
             role: "node",
             scopes: [],
             caps: self.currentCaps(),
             commands: self.currentCommands(),
-            permissions: [:],
-            clientId: "openclaw-ios",
+            permissions: self.currentPermissions(),
+            clientId: resolvedClientId,
             clientMode: "node",
             clientDisplayName: displayName)
     }
 
+    private func resolvedClientId(defaults: UserDefaults, stableID: String?) -> String {
+        if let stableID,
+           let override = GatewaySettingsStore.loadGatewayClientIdOverride(stableID: stableID) {
+            return override
+        }
+        let manualClientId = defaults.string(forKey: "gateway.manual.clientId")?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if manualClientId?.isEmpty == false {
+            return manualClientId!
+        }
+        return "openclaw-ios"
+    }
+
+    private func resolveManualPort(host: String, port: Int, useTLS: Bool) -> Int? {
+        if port > 0 {
+            return port <= 65535 ? port : nil
+        }
+        let trimmedHost = host.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedHost.isEmpty else { return nil }
+        if useTLS && self.shouldForceTLS(host: trimmedHost) {
+            return 443
+        }
+        return 18789
+    }
+
     private func resolvedDisplayName(defaults: UserDefaults) -> String {
         let key = "node.displayName"
-        let existing = defaults.string(forKey: key)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        if !existing.isEmpty, existing != "iOS Node" { return existing }
-
-        let deviceName = UIDevice.current.name.trimmingCharacters(in: .whitespacesAndNewlines)
-        let candidate = deviceName.isEmpty ? "iOS Node" : deviceName
-
-        if existing.isEmpty || existing == "iOS Node" {
-            defaults.set(candidate, forKey: key)
+        let existingRaw = defaults.string(forKey: key)
+        let resolved = NodeDisplayName.resolve(
+            existing: existingRaw,
+            deviceName: UIDevice.current.name,
+            interfaceIdiom: UIDevice.current.userInterfaceIdiom)
+        let existing = existingRaw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if existing.isEmpty || NodeDisplayName.isGeneric(existing) {
+            defaults.set(resolved, forKey: key)
         }
-
-        return candidate
+        return resolved
     }
 
     private func currentCaps() -> [String] {
@@ -320,6 +472,15 @@ final class GatewayConnectionController {
         let locationMode = OpenClawLocationMode(rawValue: locationModeRaw) ?? .off
         if locationMode != .off { caps.append(OpenClawCapability.location.rawValue) }
 
+        caps.append(OpenClawCapability.device.rawValue)
+        caps.append(OpenClawCapability.photos.rawValue)
+        caps.append(OpenClawCapability.contacts.rawValue)
+        caps.append(OpenClawCapability.calendar.rawValue)
+        caps.append(OpenClawCapability.reminders.rawValue)
+        if Self.motionAvailable() {
+            caps.append(OpenClawCapability.motion.rawValue)
+        }
+
         return caps
     }
 
@@ -335,10 +496,11 @@ final class GatewayConnectionController {
             OpenClawCanvasA2UICommand.reset.rawValue,
             OpenClawScreenCommand.record.rawValue,
             OpenClawSystemCommand.notify.rawValue,
-            OpenClawSystemCommand.which.rawValue,
-            OpenClawSystemCommand.run.rawValue,
-            OpenClawSystemCommand.execApprovalsGet.rawValue,
-            OpenClawSystemCommand.execApprovalsSet.rawValue,
+            OpenClawChatCommand.push.rawValue,
+            OpenClawTalkCommand.pttStart.rawValue,
+            OpenClawTalkCommand.pttStop.rawValue,
+            OpenClawTalkCommand.pttCancel.rawValue,
+            OpenClawTalkCommand.pttOnce.rawValue,
         ]
 
         let caps = Set(self.currentCaps())
@@ -350,10 +512,76 @@ final class GatewayConnectionController {
         if caps.contains(OpenClawCapability.location.rawValue) {
             commands.append(OpenClawLocationCommand.get.rawValue)
         }
+        if caps.contains(OpenClawCapability.device.rawValue) {
+            commands.append(OpenClawDeviceCommand.status.rawValue)
+            commands.append(OpenClawDeviceCommand.info.rawValue)
+        }
+        if caps.contains(OpenClawCapability.photos.rawValue) {
+            commands.append(OpenClawPhotosCommand.latest.rawValue)
+        }
+        if caps.contains(OpenClawCapability.contacts.rawValue) {
+            commands.append(OpenClawContactsCommand.search.rawValue)
+            commands.append(OpenClawContactsCommand.add.rawValue)
+        }
+        if caps.contains(OpenClawCapability.calendar.rawValue) {
+            commands.append(OpenClawCalendarCommand.events.rawValue)
+            commands.append(OpenClawCalendarCommand.add.rawValue)
+        }
+        if caps.contains(OpenClawCapability.reminders.rawValue) {
+            commands.append(OpenClawRemindersCommand.list.rawValue)
+            commands.append(OpenClawRemindersCommand.add.rawValue)
+        }
+        if caps.contains(OpenClawCapability.motion.rawValue) {
+            commands.append(OpenClawMotionCommand.activity.rawValue)
+            commands.append(OpenClawMotionCommand.pedometer.rawValue)
+        }
 
         return commands
     }
 
+    private func currentPermissions() -> [String: Bool] {
+        var permissions: [String: Bool] = [:]
+        permissions["camera"] = AVCaptureDevice.authorizationStatus(for: .video) == .authorized
+        permissions["microphone"] = AVCaptureDevice.authorizationStatus(for: .audio) == .authorized
+        permissions["speechRecognition"] = SFSpeechRecognizer.authorizationStatus() == .authorized
+        permissions["location"] = Self.isLocationAuthorized(
+            status: CLLocationManager().authorizationStatus)
+            && CLLocationManager.locationServicesEnabled()
+        permissions["screenRecording"] = RPScreenRecorder.shared().isAvailable
+
+        let photoStatus = PHPhotoLibrary.authorizationStatus(for: .readWrite)
+        permissions["photos"] = photoStatus == .authorized || photoStatus == .limited
+        let contactsStatus = CNContactStore.authorizationStatus(for: .contacts)
+        permissions["contacts"] = contactsStatus == .authorized || contactsStatus == .limited
+
+        let calendarStatus = EKEventStore.authorizationStatus(for: .event)
+        permissions["calendar"] =
+            calendarStatus == .authorized || calendarStatus == .fullAccess || calendarStatus == .writeOnly
+        let remindersStatus = EKEventStore.authorizationStatus(for: .reminder)
+        permissions["reminders"] =
+            remindersStatus == .authorized || remindersStatus == .fullAccess || remindersStatus == .writeOnly
+
+        let motionStatus = CMMotionActivityManager.authorizationStatus()
+        let pedometerStatus = CMPedometer.authorizationStatus()
+        permissions["motion"] =
+            motionStatus == .authorized || pedometerStatus == .authorized
+
+        return permissions
+    }
+
+    private static func isLocationAuthorized(status: CLAuthorizationStatus) -> Bool {
+        switch status {
+        case .authorizedAlways, .authorizedWhenInUse, .authorized:
+            return true
+        default:
+            return false
+        }
+    }
+
+    private static func motionAvailable() -> Bool {
+        CMMotionActivityManager.isActivityAvailable() || CMPedometer.isStepCountingAvailable()
+    }
+
     private func platformString() -> String {
         let v = ProcessInfo.processInfo.operatingSystemVersion
         let name = switch UIDevice.current.userInterfaceIdiom {
@@ -407,6 +635,10 @@ extension GatewayConnectionController {
         self.currentCommands()
     }
 
+    func _test_currentPermissions() -> [String: Bool] {
+        self.currentPermissions()
+    }
+
     func _test_platformString() -> String {
         self.platformString()
     }

apps/ios/Sources/Gateway/GatewayHealthMonitor.swift

@@ -0,0 +1,85 @@
+import Foundation
+import OpenClawKit
+
+@MainActor
+final class GatewayHealthMonitor {
+    struct Config: Sendable {
+        var intervalSeconds: Double
+        var timeoutSeconds: Double
+        var maxFailures: Int
+    }
+
+    private let config: Config
+    private let sleep: @Sendable (UInt64) async -> Void
+    private var task: Task<Void, Never>?
+
+    init(
+        config: Config = Config(intervalSeconds: 15, timeoutSeconds: 5, maxFailures: 3),
+        sleep: @escaping @Sendable (UInt64) async -> Void = { nanoseconds in
+            try? await Task.sleep(nanoseconds: nanoseconds)
+        }
+    ) {
+        self.config = config
+        self.sleep = sleep
+    }
+
+    func start(
+        check: @escaping @Sendable () async throws -> Bool,
+        onFailure: @escaping @Sendable (_ failureCount: Int) async -> Void)
+    {
+        self.stop()
+        let config = self.config
+        let sleep = self.sleep
+        self.task = Task { @MainActor in
+            var failures = 0
+            while !Task.isCancelled {
+                let ok = await Self.runCheck(check: check, timeoutSeconds: config.timeoutSeconds)
+                if ok {
+                    failures = 0
+                } else {
+                    failures += 1
+                    if failures >= max(1, config.maxFailures) {
+                        await onFailure(failures)
+                        failures = 0
+                    }
+                }
+
+                if Task.isCancelled { break }
+                let interval = max(0.0, config.intervalSeconds)
+                let nanos = UInt64(interval * 1_000_000_000)
+                if nanos > 0 {
+                    await sleep(nanos)
+                } else {
+                    await Task.yield()
+                }
+            }
+        }
+    }
+
+    func stop() {
+        self.task?.cancel()
+        self.task = nil
+    }
+
+    private static func runCheck(
+        check: @escaping @Sendable () async throws -> Bool,
+        timeoutSeconds: Double) async -> Bool
+    {
+        let timeout = max(0.0, timeoutSeconds)
+        if timeout == 0 {
+            return (try? await check()) ?? false
+        }
+        do {
+            let timeoutError = NSError(
+                domain: "GatewayHealthMonitor",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "health check timed out"])
+            return try await AsyncTimeout.withTimeout(
+                seconds: timeout,
+                onTimeout: { timeoutError },
+                operation: check)
+        } catch {
+            return false
+        }
+    }
+}

apps/ios/Sources/Gateway/GatewaySettingsStore.swift

@@ -1,4 +1,5 @@
 import Foundation
+import os
 
 enum GatewaySettingsStore {
     private static let gatewayService = "ai.openclaw.gateway"
@@ -12,6 +13,12 @@ enum GatewaySettingsStore {
     private static let manualPortDefaultsKey = "gateway.manual.port"
     private static let manualTlsDefaultsKey = "gateway.manual.tls"
     private static let discoveryDebugLogsDefaultsKey = "gateway.discovery.debugLogs"
+    private static let lastGatewayHostDefaultsKey = "gateway.last.host"
+    private static let lastGatewayPortDefaultsKey = "gateway.last.port"
+    private static let lastGatewayTlsDefaultsKey = "gateway.last.tls"
+    private static let lastGatewayStableIDDefaultsKey = "gateway.last.stableID"
+    private static let clientIdOverrideDefaultsPrefix = "gateway.clientIdOverride."
+    private static let selectedAgentDefaultsPrefix = "gateway.selectedAgentId."
 
     private static let instanceIdAccount = "instanceId"
     private static let preferredGatewayStableIDAccount = "preferredStableID"
@@ -107,6 +114,71 @@ enum GatewaySettingsStore {
             account: self.gatewayPasswordAccount(instanceId: instanceId))
     }
 
+    static func saveLastGatewayConnection(host: String, port: Int, useTLS: Bool, stableID: String) {
+        let defaults = UserDefaults.standard
+        defaults.set(host, forKey: self.lastGatewayHostDefaultsKey)
+        defaults.set(port, forKey: self.lastGatewayPortDefaultsKey)
+        defaults.set(useTLS, forKey: self.lastGatewayTlsDefaultsKey)
+        defaults.set(stableID, forKey: self.lastGatewayStableIDDefaultsKey)
+    }
+
+    static func loadLastGatewayConnection() -> (host: String, port: Int, useTLS: Bool, stableID: String)? {
+        let defaults = UserDefaults.standard
+        let host = defaults.string(forKey: self.lastGatewayHostDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let port = defaults.integer(forKey: self.lastGatewayPortDefaultsKey)
+        let useTLS = defaults.bool(forKey: self.lastGatewayTlsDefaultsKey)
+        let stableID = defaults.string(forKey: self.lastGatewayStableIDDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+
+        guard !host.isEmpty, port > 0, port <= 65535, !stableID.isEmpty else { return nil }
+        return (host: host, port: port, useTLS: useTLS, stableID: stableID)
+    }
+
+    static func loadGatewayClientIdOverride(stableID: String) -> String? {
+        let trimmedID = stableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedID.isEmpty else { return nil }
+        let key = self.clientIdOverrideDefaultsPrefix + trimmedID
+        let value = UserDefaults.standard.string(forKey: key)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if value?.isEmpty == false { return value }
+        return nil
+    }
+
+    static func saveGatewayClientIdOverride(stableID: String, clientId: String?) {
+        let trimmedID = stableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedID.isEmpty else { return }
+        let key = self.clientIdOverrideDefaultsPrefix + trimmedID
+        let trimmedClientId = clientId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmedClientId.isEmpty {
+            UserDefaults.standard.removeObject(forKey: key)
+        } else {
+            UserDefaults.standard.set(trimmedClientId, forKey: key)
+        }
+    }
+
+    static func loadGatewaySelectedAgentId(stableID: String) -> String? {
+        let trimmedID = stableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedID.isEmpty else { return nil }
+        let key = self.selectedAgentDefaultsPrefix + trimmedID
+        let value = UserDefaults.standard.string(forKey: key)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if value?.isEmpty == false { return value }
+        return nil
+    }
+
+    static func saveGatewaySelectedAgentId(stableID: String, agentId: String?) {
+        let trimmedID = stableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedID.isEmpty else { return }
+        let key = self.selectedAgentDefaultsPrefix + trimmedID
+        let trimmedAgentId = agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmedAgentId.isEmpty {
+            UserDefaults.standard.removeObject(forKey: key)
+        } else {
+            UserDefaults.standard.set(trimmedAgentId, forKey: key)
+        }
+    }
+
     private static func gatewayTokenAccount(instanceId: String) -> String {
         "gateway-token.\(instanceId)"
     }
@@ -175,3 +247,101 @@ enum GatewaySettingsStore {
     }
 
 }
+
+enum GatewayDiagnostics {
+    private static let logger = Logger(subsystem: "ai.openclaw.ios", category: "GatewayDiag")
+    private static let queue = DispatchQueue(label: "ai.openclaw.gateway.diagnostics")
+    private static let maxLogBytes: Int64 = 512 * 1024
+    private static let keepLogBytes: Int64 = 256 * 1024
+    private static let logSizeCheckEveryWrites = 50
+    nonisolated(unsafe) private static var logWritesSinceCheck = 0
+    private static var fileURL: URL? {
+        FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first?
+            .appendingPathComponent("openclaw-gateway.log")
+    }
+
+    private static func truncateLogIfNeeded(url: URL) {
+        guard let attrs = try? FileManager.default.attributesOfItem(atPath: url.path),
+              let sizeNumber = attrs[.size] as? NSNumber
+        else { return }
+        let size = sizeNumber.int64Value
+        guard size > self.maxLogBytes else { return }
+
+        do {
+            let handle = try FileHandle(forReadingFrom: url)
+            defer { try? handle.close() }
+
+            let start = max(Int64(0), size - self.keepLogBytes)
+            try handle.seek(toOffset: UInt64(start))
+            var tail = try handle.readToEnd() ?? Data()
+
+            // If we truncated mid-line, drop the first partial line so logs remain readable.
+            if start > 0, let nl = tail.firstIndex(of: 10) {
+                let next = tail.index(after: nl)
+                if next < tail.endIndex {
+                    tail = tail.suffix(from: next)
+                } else {
+                    tail = Data()
+                }
+            }
+
+            try tail.write(to: url, options: .atomic)
+        } catch {
+            // Best-effort only.
+        }
+    }
+
+    private static func appendToLog(url: URL, data: Data) {
+        if FileManager.default.fileExists(atPath: url.path) {
+            if let handle = try? FileHandle(forWritingTo: url) {
+                defer { try? handle.close() }
+                _ = try? handle.seekToEnd()
+                try? handle.write(contentsOf: data)
+            }
+        } else {
+            try? data.write(to: url, options: .atomic)
+        }
+    }
+
+    static func bootstrap() {
+        guard let url = fileURL else { return }
+        queue.async {
+            self.truncateLogIfNeeded(url: url)
+            let formatter = ISO8601DateFormatter()
+            formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+            let timestamp = formatter.string(from: Date())
+            let line = "[\(timestamp)] gateway diagnostics started\n"
+            if let data = line.data(using: .utf8) {
+                self.appendToLog(url: url, data: data)
+            }
+        }
+    }
+
+    static func log(_ message: String) {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        let timestamp = formatter.string(from: Date())
+        let line = "[\(timestamp)] \(message)"
+        logger.info("\(line, privacy: .public)")
+
+        guard let url = fileURL else { return }
+        queue.async {
+            self.logWritesSinceCheck += 1
+            if self.logWritesSinceCheck >= self.logSizeCheckEveryWrites {
+                self.logWritesSinceCheck = 0
+                self.truncateLogIfNeeded(url: url)
+            }
+            let entry = line + "\n"
+            if let data = entry.data(using: .utf8) {
+                self.appendToLog(url: url, data: data)
+            }
+        }
+    }
+
+    static func reset() {
+        guard let url = fileURL else { return }
+        queue.async {
+            try? FileManager.default.removeItem(at: url)
+        }
+    }
+}

apps/ios/Sources/Media/PhotoLibraryService.swift

@@ -0,0 +1,164 @@
+import Foundation
+import Photos
+import OpenClawKit
+import UIKit
+
+final class PhotoLibraryService: PhotosServicing {
+    // The gateway WebSocket has a max payload size; returning large base64 blobs
+    // can cause the gateway to close the connection. Keep photo payloads small
+    // enough to safely fit in a single RPC frame.
+    //
+    // This is a transport constraint (not a security policy). If callers need
+    // full-resolution media, we should switch to an HTTP media handle flow.
+    private static let maxTotalBase64Chars = 340 * 1024
+    private static let maxPerPhotoBase64Chars = 300 * 1024
+
+    func latest(params: OpenClawPhotosLatestParams) async throws -> OpenClawPhotosLatestPayload {
+        let status = await Self.ensureAuthorization()
+        guard status == .authorized || status == .limited else {
+            throw NSError(domain: "Photos", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "PHOTOS_PERMISSION_REQUIRED: grant Photos permission",
+            ])
+        }
+
+        let limit = max(1, min(params.limit ?? 1, 20))
+        let fetchOptions = PHFetchOptions()
+        fetchOptions.fetchLimit = limit
+        fetchOptions.sortDescriptors = [NSSortDescriptor(key: "creationDate", ascending: false)]
+        let assets = PHAsset.fetchAssets(with: .image, options: fetchOptions)
+
+        var results: [OpenClawPhotoPayload] = []
+        var remainingBudget = Self.maxTotalBase64Chars
+        let maxWidth = params.maxWidth.flatMap { $0 > 0 ? $0 : nil } ?? 1600
+        let quality = params.quality.map { max(0.1, min(1.0, $0)) } ?? 0.85
+        let formatter = ISO8601DateFormatter()
+
+        assets.enumerateObjects { asset, _, stop in
+            if results.count >= limit { stop.pointee = true; return }
+            if let payload = try? Self.renderAsset(
+                asset,
+                maxWidth: maxWidth,
+                quality: quality,
+                formatter: formatter)
+            {
+                // Keep the entire response under the gateway WS max payload.
+                if payload.base64.count > remainingBudget {
+                    stop.pointee = true
+                    return
+                }
+                remainingBudget -= payload.base64.count
+                results.append(payload)
+            }
+        }
+
+        return OpenClawPhotosLatestPayload(photos: results)
+    }
+
+    private static func ensureAuthorization() async -> PHAuthorizationStatus {
+        // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
+        PHPhotoLibrary.authorizationStatus(for: .readWrite)
+    }
+
+    private static func renderAsset(
+        _ asset: PHAsset,
+        maxWidth: Int,
+        quality: Double,
+        formatter: ISO8601DateFormatter) throws -> OpenClawPhotoPayload
+    {
+        let manager = PHImageManager.default()
+        let options = PHImageRequestOptions()
+        options.isSynchronous = true
+        options.isNetworkAccessAllowed = true
+        options.deliveryMode = .highQualityFormat
+
+        let targetSize: CGSize = {
+            guard maxWidth > 0 else { return PHImageManagerMaximumSize }
+            let aspect = CGFloat(asset.pixelHeight) / CGFloat(max(1, asset.pixelWidth))
+            let width = CGFloat(maxWidth)
+            return CGSize(width: width, height: width * aspect)
+        }()
+
+        var image: UIImage?
+        manager.requestImage(
+            for: asset,
+            targetSize: targetSize,
+            contentMode: .aspectFit,
+            options: options)
+        { result, _ in
+            image = result
+        }
+
+        guard let image else {
+            throw NSError(domain: "Photos", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "photo load failed",
+            ])
+        }
+
+        let (data, finalImage) = try encodeJpegUnderBudget(
+            image: image,
+            quality: quality,
+            maxBase64Chars: maxPerPhotoBase64Chars)
+
+        let created = asset.creationDate.map { formatter.string(from: $0) }
+        return OpenClawPhotoPayload(
+            format: "jpeg",
+            base64: data.base64EncodedString(),
+            width: Int(finalImage.size.width),
+            height: Int(finalImage.size.height),
+            createdAt: created)
+    }
+
+    private static func encodeJpegUnderBudget(
+        image: UIImage,
+        quality: Double,
+        maxBase64Chars: Int) throws -> (Data, UIImage)
+    {
+        var currentImage = image
+        var currentQuality = max(0.1, min(1.0, quality))
+
+        // Try lowering JPEG quality first, then downscale if needed.
+        for _ in 0..<10 {
+            guard let data = currentImage.jpegData(compressionQuality: currentQuality) else {
+                throw NSError(domain: "Photos", code: 3, userInfo: [
+                    NSLocalizedDescriptionKey: "photo encode failed",
+                ])
+            }
+
+            let base64Len = ((data.count + 2) / 3) * 4
+            if base64Len <= maxBase64Chars {
+                return (data, currentImage)
+            }
+
+            if currentQuality > 0.35 {
+                currentQuality = max(0.25, currentQuality - 0.15)
+                continue
+            }
+
+            // Downscale by ~25% each step once quality is low.
+            let newWidth = max(240, currentImage.size.width * 0.75)
+            if newWidth >= currentImage.size.width {
+                break
+            }
+            currentImage = resize(image: currentImage, targetWidth: newWidth)
+        }
+
+        throw NSError(domain: "Photos", code: 4, userInfo: [
+            NSLocalizedDescriptionKey: "photo too large for gateway transport; try smaller maxWidth/quality",
+        ])
+    }
+
+    private static func resize(image: UIImage, targetWidth: CGFloat) -> UIImage {
+        let size = image.size
+        if size.width <= 0 || size.height <= 0 || targetWidth <= 0 {
+            return image
+        }
+        let scale = targetWidth / size.width
+        let targetSize = CGSize(width: targetWidth, height: max(1, size.height * scale))
+        let format = UIGraphicsImageRendererFormat.default()
+        format.scale = 1
+        let renderer = UIGraphicsImageRenderer(size: targetSize, format: format)
+        return renderer.image { _ in
+            image.draw(in: CGRect(origin: .zero, size: targetSize))
+        }
+    }
+}

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

@@ -0,0 +1,97 @@
+import Foundation
+import Network
+import os
+
+extension NodeAppModel {
+    func _test_resolveA2UIHostURL() async -> String? {
+        await self.resolveA2UIHostURL()
+    }
+
+    func resolveA2UIHostURL() async -> String? {
+        guard let raw = await self.gatewaySession.currentCanvasHostUrl() else { return nil }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, let base = URL(string: trimmed) else { return nil }
+        if let host = base.host, Self.isLoopbackHost(host) {
+            return nil
+        }
+        return base.appendingPathComponent("__openclaw__/a2ui/").absoluteString + "?platform=ios"
+    }
+
+    private static func isLoopbackHost(_ host: String) -> Bool {
+        let normalized = host.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if normalized.isEmpty { return true }
+        if normalized == "localhost" || normalized == "::1" || normalized == "0.0.0.0" {
+            return true
+        }
+        if normalized == "127.0.0.1" || normalized.hasPrefix("127.") {
+            return true
+        }
+        return false
+    }
+
+    func showA2UIOnConnectIfNeeded() async {
+        guard let a2uiUrl = await self.resolveA2UIHostURL() else {
+            await MainActor.run {
+                self.lastAutoA2uiURL = nil
+                self.screen.showDefaultCanvas()
+            }
+            return
+        }
+        let current = self.screen.urlString.trimmingCharacters(in: .whitespacesAndNewlines)
+        if current.isEmpty || current == self.lastAutoA2uiURL {
+            // Avoid navigating the WKWebView to an unreachable host: it leaves a persistent
+            // "could not connect to the server" overlay even when the gateway is connected.
+            if let url = URL(string: a2uiUrl),
+               await Self.probeTCP(url: url, timeoutSeconds: 2.5)
+            {
+                self.screen.navigate(to: a2uiUrl)
+                self.lastAutoA2uiURL = a2uiUrl
+            } else {
+                self.lastAutoA2uiURL = nil
+                self.screen.showDefaultCanvas()
+            }
+        }
+    }
+
+    func showLocalCanvasOnDisconnect() {
+        self.lastAutoA2uiURL = nil
+        self.screen.showDefaultCanvas()
+    }
+
+    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) }
+        }
+    }
+}

apps/ios/Sources/Motion/MotionService.swift

@@ -0,0 +1,100 @@
+import CoreMotion
+import Foundation
+import OpenClawKit
+
+final class MotionService: MotionServicing {
+    func activities(params: OpenClawMotionActivityParams) async throws -> OpenClawMotionActivityPayload {
+        guard CMMotionActivityManager.isActivityAvailable() else {
+            throw NSError(domain: "Motion", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "MOTION_UNAVAILABLE: activity not supported on this device",
+            ])
+        }
+        let auth = CMMotionActivityManager.authorizationStatus()
+        guard auth == .authorized else {
+            throw NSError(domain: "Motion", code: 3, userInfo: [
+                NSLocalizedDescriptionKey: "MOTION_PERMISSION_REQUIRED: grant Motion & Fitness permission",
+            ])
+        }
+
+        let (start, end) = Self.resolveRange(startISO: params.startISO, endISO: params.endISO)
+        let limit = max(1, min(params.limit ?? 200, 1000))
+
+        let manager = CMMotionActivityManager()
+        let mapped = try await withCheckedThrowingContinuation { (cont: CheckedContinuation<[OpenClawMotionActivityEntry], Error>) in
+            manager.queryActivityStarting(from: start, to: end, to: OperationQueue()) { activity, error in
+                if let error {
+                    cont.resume(throwing: error)
+                } else {
+                    let formatter = ISO8601DateFormatter()
+                    let sliced = Array((activity ?? []).suffix(limit))
+                    let entries = sliced.map { entry in
+                        OpenClawMotionActivityEntry(
+                            startISO: formatter.string(from: entry.startDate),
+                            endISO: formatter.string(from: end),
+                            confidence: Self.confidenceString(entry.confidence),
+                            isWalking: entry.walking,
+                            isRunning: entry.running,
+                            isCycling: entry.cycling,
+                            isAutomotive: entry.automotive,
+                            isStationary: entry.stationary,
+                            isUnknown: entry.unknown)
+                    }
+                    cont.resume(returning: entries)
+                }
+            }
+        }
+
+        return OpenClawMotionActivityPayload(activities: mapped)
+    }
+
+    func pedometer(params: OpenClawPedometerParams) async throws -> OpenClawPedometerPayload {
+        guard CMPedometer.isStepCountingAvailable() else {
+            throw NSError(domain: "Motion", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "PEDOMETER_UNAVAILABLE: step counting not supported",
+            ])
+        }
+        let auth = CMPedometer.authorizationStatus()
+        guard auth == .authorized else {
+            throw NSError(domain: "Motion", code: 4, userInfo: [
+                NSLocalizedDescriptionKey: "MOTION_PERMISSION_REQUIRED: grant Motion & Fitness permission",
+            ])
+        }
+
+        let (start, end) = Self.resolveRange(startISO: params.startISO, endISO: params.endISO)
+        let pedometer = CMPedometer()
+        let payload = try await withCheckedThrowingContinuation { (cont: CheckedContinuation<OpenClawPedometerPayload, Error>) in
+            pedometer.queryPedometerData(from: start, to: end) { data, error in
+                if let error {
+                    cont.resume(throwing: error)
+                } else {
+                    let formatter = ISO8601DateFormatter()
+                    let payload = OpenClawPedometerPayload(
+                        startISO: formatter.string(from: start),
+                        endISO: formatter.string(from: end),
+                        steps: data?.numberOfSteps.intValue,
+                        distanceMeters: data?.distance?.doubleValue,
+                        floorsAscended: data?.floorsAscended?.intValue,
+                        floorsDescended: data?.floorsDescended?.intValue)
+                    cont.resume(returning: payload)
+                }
+            }
+        }
+        return payload
+    }
+
+    private static func resolveRange(startISO: String?, endISO: String?) -> (Date, Date) {
+        let formatter = ISO8601DateFormatter()
+        let start = startISO.flatMap { formatter.date(from: $0) } ?? Calendar.current.startOfDay(for: Date())
+        let end = endISO.flatMap { formatter.date(from: $0) } ?? Date()
+        return (start, end)
+    }
+
+    private static func confidenceString(_ confidence: CMMotionActivityConfidence) -> String {
+        switch confidence {
+        case .low: "low"
+        case .medium: "medium"
+        case .high: "high"
+        @unknown default: "unknown"
+        }
+    }
+}

apps/ios/Sources/Onboarding/GatewayOnboardingView.swift

@@ -0,0 +1,389 @@
+import Foundation
+import SwiftUI
+
+struct GatewayOnboardingView: View {
+    var body: some View {
+        NavigationStack {
+            List {
+                Section {
+                    Text("Connect to your gateway to get started.")
+                        .foregroundStyle(.secondary)
+                }
+
+                Section {
+                    NavigationLink("Auto detect") {
+                        AutoDetectStep()
+                    }
+                    NavigationLink("Manual entry") {
+                        ManualEntryStep()
+                    }
+                }
+            }
+            .navigationTitle("Connect Gateway")
+        }
+    }
+}
+
+private struct AutoDetectStep: View {
+    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+    @Environment(GatewayConnectionController.self) private var gatewayController: GatewayConnectionController
+    @AppStorage("gateway.preferredStableID") private var preferredGatewayStableID: String = ""
+    @AppStorage("gateway.lastDiscoveredStableID") private var lastDiscoveredGatewayStableID: String = ""
+
+    @State private var connectingGatewayID: String?
+    @State private var connectStatusText: String?
+
+    var body: some View {
+        Form {
+            Section {
+                Text("We’ll scan for gateways on your network and connect automatically when we find one.")
+                    .foregroundStyle(.secondary)
+            }
+
+            Section("Connection status") {
+                ConnectionStatusBox(
+                    statusLines: self.connectionStatusLines(),
+                    secondaryLine: self.connectStatusText)
+            }
+
+            Section {
+                Button("Retry") {
+                    self.resetConnectionState()
+                    self.triggerAutoConnect()
+                }
+                .disabled(self.connectingGatewayID != nil)
+            }
+        }
+        .navigationTitle("Auto detect")
+        .onAppear { self.triggerAutoConnect() }
+        .onChange(of: self.gatewayController.gateways) { _, _ in
+            self.triggerAutoConnect()
+        }
+    }
+
+    private func triggerAutoConnect() {
+        guard self.appModel.gatewayServerName == nil else { return }
+        guard self.connectingGatewayID == nil else { return }
+        guard let candidate = self.autoCandidate() else { return }
+
+        self.connectingGatewayID = candidate.id
+        Task {
+            defer { self.connectingGatewayID = nil }
+            await self.gatewayController.connect(candidate)
+        }
+    }
+
+    private func autoCandidate() -> GatewayDiscoveryModel.DiscoveredGateway? {
+        let preferred = self.preferredGatewayStableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        let lastDiscovered = self.lastDiscoveredGatewayStableID.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        if !preferred.isEmpty,
+           let match = self.gatewayController.gateways.first(where: { $0.stableID == preferred })
+        {
+            return match
+        }
+        if !lastDiscovered.isEmpty,
+           let match = self.gatewayController.gateways.first(where: { $0.stableID == lastDiscovered })
+        {
+            return match
+        }
+        if self.gatewayController.gateways.count == 1 {
+            return self.gatewayController.gateways.first
+        }
+        return nil
+    }
+
+    private func connectionStatusLines() -> [String] {
+        ConnectionStatusBox.defaultLines(appModel: self.appModel, gatewayController: self.gatewayController)
+    }
+
+    private func resetConnectionState() {
+        self.appModel.disconnectGateway()
+        self.connectStatusText = nil
+        self.connectingGatewayID = nil
+    }
+}
+
+private struct ManualEntryStep: View {
+    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+    @Environment(GatewayConnectionController.self) private var gatewayController: GatewayConnectionController
+
+    @State private var setupCode: String = ""
+    @State private var setupStatusText: String?
+    @State private var manualHost: String = ""
+    @State private var manualPortText: String = ""
+    @State private var manualUseTLS: Bool = true
+    @State private var manualToken: String = ""
+    @State private var manualPassword: String = ""
+
+    @State private var connectingGatewayID: String?
+    @State private var connectStatusText: String?
+
+    var body: some View {
+        Form {
+            Section("Setup code") {
+                Text("Use /pair in your bot to get a setup code.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+
+                TextField("Paste setup code", text: self.$setupCode)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+
+                Button("Apply setup code") {
+                    self.applySetupCode()
+                }
+                .disabled(self.setupCode.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+
+                if let setupStatusText, !setupStatusText.isEmpty {
+                    Text(setupStatusText)
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+            }
+
+            Section {
+                TextField("Host", text: self.$manualHost)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+
+                TextField("Port", text: self.$manualPortText)
+                    .keyboardType(.numberPad)
+
+                Toggle("Use TLS", isOn: self.$manualUseTLS)
+
+                TextField("Gateway token", text: self.$manualToken)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+
+                SecureField("Gateway password", text: self.$manualPassword)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+            }
+
+            Section("Connection status") {
+                ConnectionStatusBox(
+                    statusLines: self.connectionStatusLines(),
+                    secondaryLine: self.connectStatusText)
+            }
+
+            Section {
+                Button {
+                    Task { await self.connectManual() }
+                } label: {
+                    if self.connectingGatewayID == "manual" {
+                        HStack(spacing: 8) {
+                            ProgressView()
+                                .progressViewStyle(.circular)
+                            Text("Connecting…")
+                        }
+                    } else {
+                        Text("Connect")
+                    }
+                }
+                .disabled(self.connectingGatewayID != nil)
+
+                Button("Retry") {
+                    self.resetConnectionState()
+                    self.resetManualForm()
+                }
+                .disabled(self.connectingGatewayID != nil)
+            }
+        }
+        .navigationTitle("Manual entry")
+    }
+
+    private func connectManual() async {
+        let host = self.manualHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !host.isEmpty else {
+            self.connectStatusText = "Failed: host required"
+            return
+        }
+
+        if let port = self.manualPortValue(), !(1...65535).contains(port) {
+            self.connectStatusText = "Failed: invalid port"
+            return
+        }
+
+        let defaults = UserDefaults.standard
+        defaults.set(true, forKey: "gateway.manual.enabled")
+        defaults.set(host, forKey: "gateway.manual.host")
+        defaults.set(self.manualPortValue() ?? 0, forKey: "gateway.manual.port")
+        defaults.set(self.manualUseTLS, forKey: "gateway.manual.tls")
+
+        if let instanceId = defaults.string(forKey: "node.instanceId")?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !instanceId.isEmpty
+        {
+            let trimmedToken = self.manualToken.trimmingCharacters(in: .whitespacesAndNewlines)
+            let trimmedPassword = self.manualPassword.trimmingCharacters(in: .whitespacesAndNewlines)
+            if !trimmedToken.isEmpty {
+                GatewaySettingsStore.saveGatewayToken(trimmedToken, instanceId: instanceId)
+            }
+            GatewaySettingsStore.saveGatewayPassword(trimmedPassword, instanceId: instanceId)
+        }
+
+        self.connectingGatewayID = "manual"
+        defer { self.connectingGatewayID = nil }
+        await self.gatewayController.connectManual(
+            host: host,
+            port: self.manualPortValue() ?? 0,
+            useTLS: self.manualUseTLS)
+    }
+
+    private func manualPortValue() -> Int? {
+        let trimmed = self.manualPortText.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        return Int(trimmed.filter { $0.isNumber })
+    }
+
+    private func connectionStatusLines() -> [String] {
+        ConnectionStatusBox.defaultLines(appModel: self.appModel, gatewayController: self.gatewayController)
+    }
+
+    private func resetConnectionState() {
+        self.appModel.disconnectGateway()
+        self.connectStatusText = nil
+        self.connectingGatewayID = nil
+    }
+
+    private func resetManualForm() {
+        self.setupCode = ""
+        self.setupStatusText = nil
+        self.manualHost = ""
+        self.manualPortText = ""
+        self.manualUseTLS = true
+        self.manualToken = ""
+        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 {
+            self.setupStatusText = "Paste a setup code to continue."
+            return
+        }
+
+        guard let payload = self.decodeSetupPayload(raw: raw) else {
+            self.setupStatusText = "Setup code not recognized."
+            return
+        }
+
+        if let urlString = payload.url, let url = URL(string: urlString) {
+            self.applyURL(url)
+        } else if let host = payload.host, !host.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            self.manualHost = host.trimmingCharacters(in: .whitespacesAndNewlines)
+            if let port = payload.port {
+                self.manualPortText = String(port)
+            } else {
+                self.manualPortText = ""
+            }
+            if let tls = payload.tls {
+                self.manualUseTLS = tls
+            }
+        } else if let url = URL(string: raw), url.scheme != nil {
+            self.applyURL(url)
+        } else {
+            self.setupStatusText = "Setup code missing URL or host."
+            return
+        }
+
+        if let token = payload.token, !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            self.manualToken = token.trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+        if let password = payload.password, !password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            self.manualPassword = password.trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+
+        self.setupStatusText = "Setup code applied."
+    }
+
+    private func applyURL(_ url: URL) {
+        guard let host = url.host, !host.isEmpty else { return }
+        self.manualHost = host
+        if let port = url.port {
+            self.manualPortText = String(port)
+        } else {
+            self.manualPortText = ""
+        }
+        let scheme = (url.scheme ?? "").lowercased()
+        if scheme == "wss" || scheme == "https" {
+            self.manualUseTLS = true
+        } else if scheme == "ws" || scheme == "http" {
+            self.manualUseTLS = false
+        }
+    }
+
+    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)
+    }
+}
+
+private struct ConnectionStatusBox: View {
+    let statusLines: [String]
+    let secondaryLine: String?
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            ForEach(self.statusLines, id: \.self) { line in
+                Text(line)
+                    .font(.system(size: 12, weight: .regular, design: .monospaced))
+                    .foregroundStyle(.secondary)
+            }
+            if let secondaryLine, !secondaryLine.isEmpty {
+                Text(secondaryLine)
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(10)
+        .background(.thinMaterial, in: RoundedRectangle(cornerRadius: 10, style: .continuous))
+    }
+
+    static func defaultLines(
+        appModel: NodeAppModel,
+        gatewayController: GatewayConnectionController
+    ) -> [String] {
+        var lines: [String] = [
+            "gateway: \(appModel.gatewayStatusText)",
+            "discovery: \(gatewayController.discoveryStatusText)",
+        ]
+        lines.append("server: \(appModel.gatewayServerName ?? "—")")
+        lines.append("address: \(appModel.gatewayRemoteAddress ?? "—")")
+        return lines
+    }
+}

apps/ios/Sources/Reminders/RemindersService.swift

@@ -0,0 +1,165 @@
+import EventKit
+import Foundation
+import OpenClawKit
+
+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)
+        guard authorized else {
+            throw NSError(domain: "Reminders", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "REMINDERS_PERMISSION_REQUIRED: grant Reminders permission",
+            ])
+        }
+
+        let limit = max(1, min(params.limit ?? 50, 500))
+        let statusFilter = params.status ?? .incomplete
+
+        let predicate = store.predicateForReminders(in: nil)
+        let payload = try await withCheckedThrowingContinuation { (cont: CheckedContinuation<[OpenClawReminderPayload], Error>) in
+            store.fetchReminders(matching: predicate) { items in
+                let formatter = ISO8601DateFormatter()
+                let filtered = (items ?? []).filter { reminder in
+                    switch statusFilter {
+                    case .all:
+                        return true
+                    case .completed:
+                        return reminder.isCompleted
+                    case .incomplete:
+                        return !reminder.isCompleted
+                    }
+                }
+                let selected = Array(filtered.prefix(limit))
+                let payload = selected.map { reminder in
+                    let due = reminder.dueDateComponents.flatMap { Calendar.current.date(from: $0) }
+                    return OpenClawReminderPayload(
+                        identifier: reminder.calendarItemIdentifier,
+                        title: reminder.title,
+                        dueISO: due.map { formatter.string(from: $0) },
+                        completed: reminder.isCompleted,
+                        listName: reminder.calendar.title)
+                }
+                cont.resume(returning: payload)
+            }
+        }
+
+        return OpenClawRemindersListPayload(reminders: payload)
+    }
+
+    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)
+        guard authorized else {
+            throw NSError(domain: "Reminders", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "REMINDERS_PERMISSION_REQUIRED: grant Reminders permission",
+            ])
+        }
+
+        let title = params.title.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !title.isEmpty else {
+            throw NSError(domain: "Reminders", code: 3, userInfo: [
+                NSLocalizedDescriptionKey: "REMINDERS_INVALID: title required",
+            ])
+        }
+
+        let reminder = EKReminder(eventStore: store)
+        reminder.title = title
+        if let notes = params.notes?.trimmingCharacters(in: .whitespacesAndNewlines), !notes.isEmpty {
+            reminder.notes = notes
+        }
+        reminder.calendar = try Self.resolveList(
+            store: store,
+            listId: params.listId,
+            listName: params.listName)
+
+        if let dueISO = params.dueISO?.trimmingCharacters(in: .whitespacesAndNewlines), !dueISO.isEmpty {
+            let formatter = ISO8601DateFormatter()
+            guard let dueDate = formatter.date(from: dueISO) else {
+                throw NSError(domain: "Reminders", code: 4, userInfo: [
+                    NSLocalizedDescriptionKey: "REMINDERS_INVALID: dueISO must be ISO-8601",
+                ])
+            }
+            reminder.dueDateComponents = Calendar.current.dateComponents(
+                [.year, .month, .day, .hour, .minute, .second],
+                from: dueDate)
+        }
+
+        try store.save(reminder, commit: true)
+
+        let formatter = ISO8601DateFormatter()
+        let due = reminder.dueDateComponents.flatMap { Calendar.current.date(from: $0) }
+        let payload = OpenClawReminderPayload(
+            identifier: reminder.calendarItemIdentifier,
+            title: reminder.title,
+            dueISO: due.map { formatter.string(from: $0) },
+            completed: reminder.isCompleted,
+            listName: reminder.calendar.title)
+
+        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?,
+        listName: String?) throws -> EKCalendar
+    {
+        if let id = listId?.trimmingCharacters(in: .whitespacesAndNewlines), !id.isEmpty,
+           let calendar = store.calendar(withIdentifier: id)
+        {
+            return calendar
+        }
+
+        if let title = listName?.trimmingCharacters(in: .whitespacesAndNewlines), !title.isEmpty {
+            if let calendar = store.calendars(for: .reminder).first(where: {
+                $0.title.compare(title, options: [.caseInsensitive, .diacriticInsensitive]) == .orderedSame
+            }) {
+                return calendar
+            }
+            throw NSError(domain: "Reminders", code: 5, userInfo: [
+                NSLocalizedDescriptionKey: "REMINDERS_LIST_NOT_FOUND: no list named \(title)",
+            ])
+        }
+
+        if let fallback = store.defaultCalendarForNewReminders() {
+            return fallback
+        }
+
+        throw NSError(domain: "Reminders", code: 6, userInfo: [
+            NSLocalizedDescriptionKey: "REMINDERS_LIST_NOT_FOUND: no default list",
+        ])
+    }
+}

apps/ios/Sources/RootCanvas.swift

@@ -9,9 +9,15 @@ struct RootCanvas: View {
     @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("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 = ""
     @State private var presentedSheet: PresentedSheet?
     @State private var voiceWakeToastText: String?
     @State private var toastDismissTask: Task<Void, Never>?
+    @State private var didAutoOpenSettings: Bool = false
 
     private enum PresentedSheet: Identifiable {
         case settings
@@ -52,12 +58,14 @@ struct RootCanvas: View {
                 SettingsTab()
             case .chat:
                 ChatSheet(
-                    gateway: self.appModel.gatewaySession,
+                    gateway: self.appModel.operatorSession,
                     sessionKey: self.appModel.mainSessionKey,
+                    agentName: self.appModel.activeAgentName,
                     userAccent: self.appModel.seamColor)
             }
         }
         .onAppear { self.updateIdleTimer() }
+        .onAppear { self.maybeAutoOpenSettings() }
         .onChange(of: self.preventSleep) { _, _ in self.updateIdleTimer() }
         .onChange(of: self.scenePhase) { _, _ in self.updateIdleTimer() }
         .onAppear { self.updateCanvasDebugStatus() }
@@ -65,6 +73,13 @@ struct RootCanvas: View {
         .onChange(of: self.appModel.gatewayStatusText) { _, _ in self.updateCanvasDebugStatus() }
         .onChange(of: self.appModel.gatewayServerName) { _, _ in self.updateCanvasDebugStatus() }
         .onChange(of: self.appModel.gatewayRemoteAddress) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayServerName) { _, newValue in
+            if newValue != nil {
+                self.onboardingComplete = true
+                self.hasConnectedOnce = true
+            }
+            self.maybeAutoOpenSettings()
+        }
         .onChange(of: self.voiceWake.lastTriggeredCommand) { _, newValue in
             guard let newValue else { return }
             let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -119,12 +134,33 @@ struct RootCanvas: View {
         let subtitle = self.appModel.gatewayServerName ?? self.appModel.gatewayRemoteAddress
         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 hasExistingGatewayConfig() -> Bool {
+        if GatewaySettingsStore.loadLastGatewayConnection() != nil { return true }
+        let manualHost = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        return self.manualGatewayEnabled && !manualHost.isEmpty
+    }
+
+    private func maybeAutoOpenSettings() {
+        guard !self.didAutoOpenSettings else { return }
+        guard self.shouldAutoOpenSettings() else { return }
+        self.didAutoOpenSettings = true
+        self.presentedSheet = .settings
+    }
 }
 
 private struct CanvasContent: View {
     @Environment(NodeAppModel.self) private var appModel
     @AppStorage("talk.enabled") private var talkEnabled: Bool = false
     @AppStorage("talk.button.enabled") private var talkButtonEnabled: Bool = true
+    @State private var showGatewayActions: Bool = false
     var systemColorScheme: ColorScheme
     var gatewayStatus: StatusPill.GatewayState
     var voiceWakeEnabled: Bool
@@ -182,7 +218,11 @@ private struct CanvasContent: View {
                 activity: self.statusActivity,
                 brighten: self.brightenButtons,
                 onTap: {
-                    self.openSettings()
+                    if self.gatewayStatus == .connected {
+                        self.showGatewayActions = true
+                    } else {
+                        self.openSettings()
+                    }
                 })
                 .padding(.leading, 10)
                 .safeAreaPadding(.top, 10)
@@ -197,6 +237,21 @@ private struct CanvasContent: View {
                     .transition(.move(edge: .top).combined(with: .opacity))
             }
         }
+        .confirmationDialog(
+            "Gateway",
+            isPresented: self.$showGatewayActions,
+            titleVisibility: .visible)
+        {
+            Button("Disconnect", role: .destructive) {
+                self.appModel.disconnectGateway()
+            }
+            Button("Open Settings") {
+                self.openSettings()
+            }
+            Button("Cancel", role: .cancel) {}
+        } message: {
+            Text("Disconnect from the gateway?")
+        }
     }
 
     private var statusActivity: StatusPill.Activity? {
@@ -248,6 +303,10 @@ private struct CanvasContent: View {
                 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")
             }

apps/ios/Sources/RootTabs.swift

@@ -7,6 +7,7 @@ struct RootTabs: View {
     @State private var selectedTab: Int = 0
     @State private var voiceWakeToastText: String?
     @State private var toastDismissTask: Task<Void, Never>?
+    @State private var showGatewayActions: Bool = false
 
     var body: some View {
         TabView(selection: self.$selectedTab) {
@@ -27,7 +28,13 @@ struct RootTabs: View {
                 gateway: self.gatewayStatus,
                 voiceWakeEnabled: self.voiceWakeEnabled,
                 activity: self.statusActivity,
-                onTap: { self.selectedTab = 2 })
+                onTap: {
+                    if self.gatewayStatus == .connected {
+                        self.showGatewayActions = true
+                    } else {
+                        self.selectedTab = 2
+                    }
+                })
                 .padding(.leading, 10)
                 .safeAreaPadding(.top, 10)
         }
@@ -62,6 +69,21 @@ struct RootTabs: View {
             self.toastDismissTask?.cancel()
             self.toastDismissTask = nil
         }
+        .confirmationDialog(
+            "Gateway",
+            isPresented: self.$showGatewayActions,
+            titleVisibility: .visible)
+        {
+            Button("Disconnect", role: .destructive) {
+                self.appModel.disconnectGateway()
+            }
+            Button("Open Settings") {
+                self.selectedTab = 2
+            }
+            Button("Cancel", role: .cancel) {}
+        } message: {
+            Text("Disconnect from the gateway?")
+        }
     }
 
     private var gatewayStatus: StatusPill.GatewayState {
@@ -133,6 +155,10 @@ struct RootTabs: View {
                 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")
             }

apps/ios/Sources/RootView.swift

@@ -0,0 +1,7 @@
+import SwiftUI
+
+struct RootView: View {
+    var body: some View {
+        RootCanvas()
+    }
+}

apps/ios/Sources/Screen/ScreenController.swift

@@ -52,6 +52,20 @@ final class ScreenController {
 
     func navigate(to urlString: String) {
         let trimmed = urlString.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            self.urlString = ""
+            self.reload()
+            return
+        }
+        if let url = URL(string: trimmed),
+           !url.isFileURL,
+           let host = url.host,
+           Self.isLoopbackHost(host)
+        {
+            // Never try to load loopback URLs from a remote gateway.
+            self.showDefaultCanvas()
+            return
+        }
         self.urlString = (trimmed == "/" ? "" : trimmed)
         self.reload()
     }
@@ -239,6 +253,18 @@ final class ScreenController {
         name: "scaffold",
         ext: "html",
         subdirectory: "CanvasScaffold")
+
+    private static func isLoopbackHost(_ host: String) -> Bool {
+        let normalized = host.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if normalized.isEmpty { return true }
+        if normalized == "localhost" || normalized == "::1" || normalized == "0.0.0.0" {
+            return true
+        }
+        if normalized == "127.0.0.1" || normalized.hasPrefix("127.") {
+            return true
+        }
+        return false
+    }
     func isTrustedCanvasUIURL(_ url: URL) -> Bool {
         guard url.isFileURL else { return false }
         let std = url.standardizedFileURL

apps/ios/Sources/Screen/ScreenTab.swift

@@ -9,7 +9,9 @@ struct ScreenTab: View {
             ScreenWebView(controller: self.appModel.screen)
                 .ignoresSafeArea()
                 .overlay(alignment: .top) {
-                    if let errorText = self.appModel.screen.errorText {
+                    if let errorText = self.appModel.screen.errorText,
+                       self.appModel.gatewayServerName == nil
+                    {
                         Text(errorText)
                             .font(.footnote)
                             .padding(10)

apps/ios/Sources/Services/NodeServiceProtocols.swift

@@ -0,0 +1,64 @@
+import CoreLocation
+import Foundation
+import OpenClawKit
+import UIKit
+
+protocol CameraServicing: Sendable {
+    func listDevices() async -> [CameraController.CameraDeviceInfo]
+    func snap(params: OpenClawCameraSnapParams) async throws -> (format: String, base64: String, width: Int, height: Int)
+    func clip(params: OpenClawCameraClipParams) async throws -> (format: String, base64: String, durationMs: Int, hasAudio: Bool)
+}
+
+protocol ScreenRecordingServicing: Sendable {
+    func record(
+        screenIndex: Int?,
+        durationMs: Int?,
+        fps: Double?,
+        includeAudio: Bool?,
+        outPath: String?) async throws -> String
+}
+
+@MainActor
+protocol LocationServicing: Sendable {
+    func authorizationStatus() -> CLAuthorizationStatus
+    func accuracyAuthorization() -> CLAccuracyAuthorization
+    func ensureAuthorization(mode: OpenClawLocationMode) async -> CLAuthorizationStatus
+    func currentLocation(
+        params: OpenClawLocationGetParams,
+        desiredAccuracy: OpenClawLocationAccuracy,
+        maxAgeMs: Int?,
+        timeoutMs: Int?) async throws -> CLLocation
+}
+
+protocol DeviceStatusServicing: Sendable {
+    func status() async throws -> OpenClawDeviceStatusPayload
+    func info() -> OpenClawDeviceInfoPayload
+}
+
+protocol PhotosServicing: Sendable {
+    func latest(params: OpenClawPhotosLatestParams) async throws -> OpenClawPhotosLatestPayload
+}
+
+protocol ContactsServicing: Sendable {
+    func search(params: OpenClawContactsSearchParams) async throws -> OpenClawContactsSearchPayload
+    func add(params: OpenClawContactsAddParams) async throws -> OpenClawContactsAddPayload
+}
+
+protocol CalendarServicing: Sendable {
+    func events(params: OpenClawCalendarEventsParams) async throws -> OpenClawCalendarEventsPayload
+    func add(params: OpenClawCalendarAddParams) async throws -> OpenClawCalendarAddPayload
+}
+
+protocol RemindersServicing: Sendable {
+    func list(params: OpenClawRemindersListParams) async throws -> OpenClawRemindersListPayload
+    func add(params: OpenClawRemindersAddParams) async throws -> OpenClawRemindersAddPayload
+}
+
+protocol MotionServicing: Sendable {
+    func activities(params: OpenClawMotionActivityParams) async throws -> OpenClawMotionActivityPayload
+    func pedometer(params: OpenClawPedometerParams) async throws -> OpenClawPedometerPayload
+}
+
+extension CameraController: CameraServicing {}
+extension ScreenRecordService: ScreenRecordingServicing {}
+extension LocationService: LocationServicing {}

apps/ios/Sources/Services/NotificationService.swift

@@ -0,0 +1,58 @@
+import Foundation
+import UserNotifications
+
+enum NotificationAuthorizationStatus: Sendable {
+    case notDetermined
+    case denied
+    case authorized
+    case provisional
+    case ephemeral
+}
+
+protocol NotificationCentering: Sendable {
+    func authorizationStatus() async -> NotificationAuthorizationStatus
+    func requestAuthorization(options: UNAuthorizationOptions) async throws -> Bool
+    func add(_ request: UNNotificationRequest) async throws
+}
+
+struct LiveNotificationCenter: NotificationCentering, @unchecked Sendable {
+    private let center: UNUserNotificationCenter
+
+    init(center: UNUserNotificationCenter = .current()) {
+        self.center = center
+    }
+
+    func authorizationStatus() async -> NotificationAuthorizationStatus {
+        let settings = await self.center.notificationSettings()
+        return switch settings.authorizationStatus {
+        case .authorized:
+            .authorized
+        case .provisional:
+            .provisional
+        case .ephemeral:
+            .ephemeral
+        case .denied:
+            .denied
+        case .notDetermined:
+            .notDetermined
+        @unknown default:
+            .denied
+        }
+    }
+
+    func requestAuthorization(options: UNAuthorizationOptions) async throws -> Bool {
+        try await self.center.requestAuthorization(options: options)
+    }
+
+    func add(_ request: UNNotificationRequest) async throws {
+        try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
+            self.center.add(request) { error in
+                if let error {
+                    cont.resume(throwing: error)
+                } else {
+                    cont.resume(returning: ())
+                }
+            }
+        }
+    }
+}

apps/ios/Sources/SessionKey.swift

@@ -6,6 +6,14 @@ enum SessionKey {
         return trimmed.isEmpty ? "main" : trimmed
     }
 
+    static func makeAgentSessionKey(agentId: String, baseKey: String) -> String {
+        let trimmedAgent = agentId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedBase = baseKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmedAgent.isEmpty { return trimmedBase.isEmpty ? "main" : trimmedBase }
+        let normalizedBase = trimmedBase.isEmpty ? "main" : trimmedBase
+        return "agent:\(trimmedAgent):\(normalizedBase)"
+    }
+
     static func isCanonicalMainSessionKey(_ value: String?) -> Bool {
         let trimmed = (value ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
         if trimmed.isEmpty { return false }

apps/ios/Sources/Settings/SettingsTab.swift

@@ -1,17 +1,10 @@
 import OpenClawKit
 import Network
 import Observation
+import os
 import SwiftUI
 import UIKit
 
-@MainActor
-@Observable
-private final class ConnectStatusStore {
-    var text: String?
-}
-
-extension ConnectStatusStore: @unchecked Sendable {}
-
 struct SettingsTab: View {
     @Environment(NodeAppModel.self) private var appModel: NodeAppModel
     @Environment(VoiceWakeManager.self) private var voiceWake: VoiceWakeManager
@@ -28,99 +21,140 @@ struct SettingsTab: View {
     @AppStorage("screen.preventSleep") private var preventSleep: Bool = true
     @AppStorage("gateway.preferredStableID") private var preferredGatewayStableID: String = ""
     @AppStorage("gateway.lastDiscoveredStableID") private var lastDiscoveredGatewayStableID: String = ""
+    @AppStorage("gateway.autoconnect") private var gatewayAutoConnect: Bool = false
     @AppStorage("gateway.manual.enabled") private var manualGatewayEnabled: Bool = false
     @AppStorage("gateway.manual.host") private var manualGatewayHost: String = ""
     @AppStorage("gateway.manual.port") private var manualGatewayPort: Int = 18789
     @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
-    @State private var connectStatus = ConnectStatusStore()
     @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 = ""
+    @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 = ""
+
+    private let gatewayLogger = Logger(subsystem: "ai.openclaw.ios", category: "GatewaySettings")
 
     var body: some View {
         NavigationStack {
             Form {
-                Section("Node") {
-                    TextField("Name", text: self.$displayName)
-                    Text(self.instanceId)
-                        .font(.footnote)
-                        .foregroundStyle(.secondary)
-                    LabeledContent("IP", value: self.localIPAddress ?? "—")
-                        .contextMenu {
-                            if let ip = self.localIPAddress {
-                                Button {
-                                    UIPasteboard.general.string = ip
-                                } label: {
-                                    Label("Copy", systemImage: "doc.on.doc")
+                Section {
+                    DisclosureGroup(isExpanded: self.$gatewayExpanded) {
+                        if !self.isGatewayConnected {
+                            Text(
+                                "1. Open Telegram and message your bot: /pair\n"
+                                    + "2. Copy the setup code it returns\n"
+                                    + "3. Paste here and tap Connect\n"
+                                    + "4. Back in Telegram, run /pair approve")
+                                .font(.footnote)
+                                .foregroundStyle(.secondary)
+
+                            if let warning = self.tailnetWarningText {
+                                Text(warning)
+                                    .font(.footnote.weight(.semibold))
+                                    .foregroundStyle(.orange)
+                            }
+
+                            TextField("Paste setup code", text: self.$setupCode)
+                                .textInputAutocapitalization(.never)
+                                .autocorrectionDisabled()
+
+                            Button {
+                                Task { await self.applySetupCodeAndConnect() }
+                            } label: {
+                                if self.connectingGatewayID == "manual" {
+                                    HStack(spacing: 8) {
+                                        ProgressView()
+                                            .progressViewStyle(.circular)
+                                        Text("Connecting…")
+                                    }
+                                } else {
+                                    Text("Connect with setup code")
                                 }
                             }
+                            .disabled(self.connectingGatewayID != nil
+                                || self.setupCode.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+
+                            if let status = self.setupStatusLine {
+                                Text(status)
+                                    .font(.footnote)
+                                    .foregroundStyle(.secondary)
+                            }
                         }
-                    LabeledContent("Platform", value: self.platformString())
-                    LabeledContent("Version", value: self.appVersion())
-                    LabeledContent("Model", value: self.modelIdentifier())
-                }
 
-                Section("Gateway") {
-                    LabeledContent("Discovery", value: self.gatewayController.discoveryStatusText)
-                    LabeledContent("Status", value: self.appModel.gatewayStatusText)
-                    if let serverName = self.appModel.gatewayServerName {
-                        LabeledContent("Server", value: serverName)
-                        if let addr = self.appModel.gatewayRemoteAddress {
-                            let parts = Self.parseHostPort(from: addr)
-                            let urlString = Self.httpURLString(host: parts?.host, port: parts?.port, fallback: addr)
-                            LabeledContent("Address") {
-                                Text(urlString)
-                            }
-                            .contextMenu {
-                                Button {
-                                    UIPasteboard.general.string = urlString
-                                } label: {
-                                    Label("Copy URL", systemImage: "doc.on.doc")
+                        if self.isGatewayConnected {
+                            Picker("Bot", selection: self.$selectedAgentPickerId) {
+                                Text("Default").tag("")
+                                let defaultId = (self.appModel.gatewayDefaultAgentId ?? "")
+                                    .trimmingCharacters(in: .whitespacesAndNewlines)
+                                ForEach(self.appModel.gatewayAgents.filter { $0.id != defaultId }, id: \.id) { agent in
+                                    let name = (agent.name ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+                                    Text(name.isEmpty ? agent.id : name).tag(agent.id)
                                 }
+                            }
+                            Text("Controls which bot Chat and Talk speak to.")
+                                .font(.footnote)
+                                .foregroundStyle(.secondary)
+                        }
 
-                                if let parts {
+                        DisclosureGroup("Advanced") {
+                        if self.appModel.gatewayServerName == nil {
+                            LabeledContent("Discovery", value: self.gatewayController.discoveryStatusText)
+                        }
+                        LabeledContent("Status", value: self.appModel.gatewayStatusText)
+                        Toggle("Auto-connect on launch", isOn: self.$gatewayAutoConnect)
+
+                        if let serverName = self.appModel.gatewayServerName {
+                            LabeledContent("Server", value: serverName)
+                            if let addr = self.appModel.gatewayRemoteAddress {
+                                let parts = Self.parseHostPort(from: addr)
+                                let urlString = Self.httpURLString(host: parts?.host, port: parts?.port, fallback: addr)
+                                LabeledContent("Address") {
+                                    Text(urlString)
+                                }
+                                .contextMenu {
                                     Button {
-                                        UIPasteboard.general.string = parts.host
+                                        UIPasteboard.general.string = urlString
                                     } label: {
-                                        Label("Copy Host", systemImage: "doc.on.doc")
+                                        Label("Copy URL", systemImage: "doc.on.doc")
                                     }
 
-                                    Button {
-                                        UIPasteboard.general.string = "\(parts.port)"
-                                    } label: {
-                                        Label("Copy Port", systemImage: "doc.on.doc")
+                                    if let parts {
+                                        Button {
+                                            UIPasteboard.general.string = parts.host
+                                        } label: {
+                                            Label("Copy Host", systemImage: "doc.on.doc")
+                                        }
+
+                                        Button {
+                                            UIPasteboard.general.string = "\(parts.port)"
+                                        } label: {
+                                            Label("Copy Port", systemImage: "doc.on.doc")
+                                        }
                                     }
                                 }
                             }
+
+                            Button("Disconnect", role: .destructive) {
+                                self.appModel.disconnectGateway()
+                            }
+                        } else {
+                            self.gatewayList(showing: .all)
                         }
 
-                        Button("Disconnect", role: .destructive) {
-                            self.appModel.disconnectGateway()
-                        }
-
-                        self.gatewayList(showing: .availableOnly)
-                    } else {
-                        self.gatewayList(showing: .all)
-                    }
-
-                    if let text = self.connectStatus.text {
-                        Text(text)
-                            .font(.footnote)
-                            .foregroundStyle(.secondary)
-                    }
-
-                    DisclosureGroup("Advanced") {
                         Toggle("Use Manual Gateway", isOn: self.$manualGatewayEnabled)
 
                         TextField("Host", text: self.$manualGatewayHost)
                             .textInputAutocapitalization(.never)
                             .autocorrectionDisabled()
 
-                        TextField("Port", value: self.$manualGatewayPort, format: .number)
+                        TextField("Port (optional)", text: self.manualPortBinding)
                             .keyboardType(.numberPad)
 
                         Toggle("Use TLS", isOn: self.$manualGatewayTLS)
@@ -140,11 +174,11 @@ struct SettingsTab: View {
                         }
                         .disabled(self.connectingGatewayID != nil || self.manualGatewayHost
                             .trimmingCharacters(in: .whitespacesAndNewlines)
-                            .isEmpty || self.manualGatewayPort <= 0 || self.manualGatewayPort > 65535)
+                            .isEmpty || !self.manualPortIsValid)
 
                         Text(
                             "Use this when mDNS/Bonjour discovery is blocked. "
-                                + "The gateway WebSocket listens on port 18789 by default.")
+                                + "Leave port empty for 443 on tailnet DNS (TLS) or 18789 otherwise.")
                             .font(.footnote)
                             .foregroundStyle(.secondary)
 
@@ -164,58 +198,98 @@ struct SettingsTab: View {
                             .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))
+                        }
                     }
-                }
-
-                Section("Voice") {
-                    Toggle("Voice Wake", isOn: self.$voiceWakeEnabled)
-                        .onChange(of: self.voiceWakeEnabled) { _, newValue in
-                            self.appModel.setVoiceWakeEnabled(newValue)
-                        }
-                    Toggle("Talk Mode", isOn: self.$talkEnabled)
-                        .onChange(of: self.talkEnabled) { _, newValue in
-                            self.appModel.setTalkEnabled(newValue)
-                        }
-                    // Keep this separate so users can hide the side bubble without disabling Talk Mode.
-                    Toggle("Show Talk Button", isOn: self.$talkButtonEnabled)
-
-                    NavigationLink {
-                        VoiceWakeWordsSettingsView()
                     } label: {
-                        LabeledContent(
-                            "Wake Words",
-                            value: VoiceWakePreferences.displayString(for: self.voiceWake.triggerWords))
+                        HStack(spacing: 10) {
+                            Circle()
+                                .fill(self.isGatewayConnected ? Color.green : Color.secondary.opacity(0.35))
+                                .frame(width: 10, height: 10)
+                            Text("Gateway")
+                            Spacer()
+                            Text(self.gatewaySummaryText)
+                                .font(.footnote)
+                                .foregroundStyle(.secondary)
+                        }
                     }
                 }
 
-                Section("Camera") {
-                    Toggle("Allow Camera", isOn: self.$cameraEnabled)
-                    Text("Allows the gateway to request photos or short video clips (foreground only).")
-                        .font(.footnote)
-                        .foregroundStyle(.secondary)
-                }
+                Section("Device") {
+                    DisclosureGroup("Features") {
+                        Toggle("Voice Wake", isOn: self.$voiceWakeEnabled)
+                            .onChange(of: self.voiceWakeEnabled) { _, newValue in
+                                self.appModel.setVoiceWakeEnabled(newValue)
+                            }
+                        Toggle("Talk Mode", isOn: self.$talkEnabled)
+                            .onChange(of: self.talkEnabled) { _, newValue in
+                                self.appModel.setTalkEnabled(newValue)
+                            }
+                        // Keep this separate so users can hide the side bubble without disabling Talk Mode.
+                        Toggle("Show Talk Button", isOn: self.$talkButtonEnabled)
 
-                Section("Location") {
-                    Picker("Location Access", selection: self.$locationEnabledModeRaw) {
-                        Text("Off").tag(OpenClawLocationMode.off.rawValue)
-                        Text("While Using").tag(OpenClawLocationMode.whileUsing.rawValue)
-                        Text("Always").tag(OpenClawLocationMode.always.rawValue)
+                        NavigationLink {
+                            VoiceWakeWordsSettingsView()
+                        } label: {
+                            LabeledContent(
+                                "Wake Words",
+                                value: VoiceWakePreferences.displayString(for: self.voiceWake.triggerWords))
+                        }
+
+                        Toggle("Allow Camera", isOn: self.$cameraEnabled)
+                        Text("Allows the gateway to request photos or short video clips (foreground only).")
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+
+                        Picker("Location Access", selection: self.$locationEnabledModeRaw) {
+                            Text("Off").tag(OpenClawLocationMode.off.rawValue)
+                            Text("While Using").tag(OpenClawLocationMode.whileUsing.rawValue)
+                            Text("Always").tag(OpenClawLocationMode.always.rawValue)
+                        }
+                        .pickerStyle(.segmented)
+
+                        Toggle("Precise Location", isOn: self.$locationPreciseEnabled)
+                            .disabled(self.locationMode == .off)
+
+                        Text("Always requires system permission and may prompt to open Settings.")
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+
+                        Toggle("Prevent Sleep", isOn: self.$preventSleep)
+                        Text("Keeps the screen awake while OpenClaw is open.")
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
                     }
-                    .pickerStyle(.segmented)
 
-                    Toggle("Precise Location", isOn: self.$locationPreciseEnabled)
-                        .disabled(self.locationMode == .off)
-
-                    Text("Always requires system permission and may prompt to open Settings.")
-                        .font(.footnote)
-                        .foregroundStyle(.secondary)
-                }
-
-                Section("Screen") {
-                    Toggle("Prevent Sleep", isOn: self.$preventSleep)
-                    Text("Keeps the screen awake while OpenClaw is open.")
-                        .font(.footnote)
-                        .foregroundStyle(.secondary)
+                    DisclosureGroup("Device Info") {
+                        TextField("Name", text: self.$displayName)
+                        Text(self.instanceId)
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+                        LabeledContent("IP", value: self.localIPAddress ?? "—")
+                            .contextMenu {
+                                if let ip = self.localIPAddress {
+                                    Button {
+                                        UIPasteboard.general.string = ip
+                                    } label: {
+                                        Label("Copy", systemImage: "doc.on.doc")
+                                    }
+                                }
+                            }
+                        LabeledContent("Platform", value: self.platformString())
+                        LabeledContent("Version", value: self.appVersion())
+                        LabeledContent("Model", value: self.modelIdentifier())
+                    }
                 }
             }
             .navigationTitle("Settings")
@@ -232,11 +306,24 @@ struct SettingsTab: View {
             .onAppear {
                 self.localIPAddress = Self.primaryIPv4Address()
                 self.lastLocationModeRaw = self.locationEnabledModeRaw
+                self.syncManualPortText()
                 let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
                 if !trimmedInstanceId.isEmpty {
                     self.gatewayToken = GatewaySettingsStore.loadGatewayToken(instanceId: trimmedInstanceId) ?? ""
                     self.gatewayPassword = GatewaySettingsStore.loadGatewayPassword(instanceId: trimmedInstanceId) ?? ""
                 }
+                // Keep setup front-and-center when disconnected; keep things compact once connected.
+                self.gatewayExpanded = !self.isGatewayConnected
+                self.selectedAgentPickerId = self.appModel.selectedAgentId ?? ""
+            }
+            .onChange(of: self.selectedAgentPickerId) { _, newValue in
+                let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
+                self.appModel.setSelectedAgentId(trimmed.isEmpty ? nil : trimmed)
+            }
+            .onChange(of: self.appModel.selectedAgentId ?? "") { _, newValue in
+                if newValue != self.selectedAgentPickerId {
+                    self.selectedAgentPickerId = newValue
+                }
             }
             .onChange(of: self.preferredGatewayStableID) { _, newValue in
                 let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -255,8 +342,24 @@ struct SettingsTab: View {
                 guard !instanceId.isEmpty else { return }
                 GatewaySettingsStore.saveGatewayPassword(trimmed, instanceId: instanceId)
             }
-            .onChange(of: self.appModel.gatewayServerName) { _, _ in
-                self.connectStatus.text = nil
+            .onChange(of: self.manualGatewayPort) { _, _ in
+                self.syncManualPortText()
+            }
+            .onChange(of: self.appModel.gatewayServerName) { _, newValue in
+                if newValue != nil {
+                    self.setupCode = ""
+                    self.setupStatusText = nil
+                    return
+                }
+                if self.manualGatewayEnabled {
+                    self.setupStatusText = self.appModel.gatewayStatusText
+                }
+            }
+            .onChange(of: self.appModel.gatewayStatusText) { _, newValue in
+                guard self.manualGatewayEnabled || self.connectingGatewayID == "manual" else { return }
+                let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
+                guard !trimmed.isEmpty else { return }
+                self.setupStatusText = trimmed
             }
             .onChange(of: self.locationEnabledModeRaw) { _, newValue in
                 let previous = self.lastLocationModeRaw
@@ -278,8 +381,24 @@ struct SettingsTab: View {
     @ViewBuilder
     private func gatewayList(showing: GatewayListMode) -> some View {
         if self.gatewayController.gateways.isEmpty {
-            Text("No gateways found yet.")
-                .foregroundStyle(.secondary)
+            VStack(alignment: .leading, spacing: 12) {
+                Text("No gateways found yet.")
+                    .foregroundStyle(.secondary)
+                Text("If your gateway is on another network, connect it and ensure DNS is working.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+
+                if let lastKnown = GatewaySettingsStore.loadLastGatewayConnection() {
+                    Button {
+                        Task { await self.connectLastKnown() }
+                    } label: {
+                        self.lastKnownButtonLabel(host: lastKnown.host, port: lastKnown.port)
+                    }
+                    .disabled(self.connectingGatewayID != nil)
+                    .buttonStyle(.borderedProminent)
+                    .tint(self.appModel.seamColor)
+                }
+            }
         } else {
             let connectedID = self.appModel.connectedGatewayID
             let rows = self.gatewayController.gateways.filter { gateway in
@@ -331,6 +450,20 @@ struct SettingsTab: View {
         case availableOnly
     }
 
+    private var isGatewayConnected: Bool {
+        let status = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if status.contains("connected") { return true }
+        return self.appModel.gatewayServerName != nil && !status.contains("offline")
+    }
+
+    private var gatewaySummaryText: String {
+        if let server = self.appModel.gatewayServerName, self.isGatewayConnected {
+            return server
+        }
+        let trimmed = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? "Not connected" : trimmed
+    }
+
     private func platformString() -> String {
         let v = ProcessInfo.processInfo.operatingSystemVersion
         return "iOS \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
@@ -377,14 +510,290 @@ struct SettingsTab: View {
         await self.gatewayController.connect(gateway)
     }
 
+    private func connectLastKnown() async {
+        self.connectingGatewayID = "last-known"
+        defer { self.connectingGatewayID = nil }
+        await self.gatewayController.connectLastKnown()
+    }
+
+    private func gatewayDebugText() -> String {
+        var lines: [String] = [
+            "gateway: \(self.appModel.gatewayStatusText)",
+            "discovery: \(self.gatewayController.discoveryStatusText)",
+        ]
+        lines.append("server: \(self.appModel.gatewayServerName ?? "—")")
+        lines.append("address: \(self.appModel.gatewayRemoteAddress ?? "—")")
+        if let last = self.gatewayController.discoveryDebugLog.last?.message {
+            lines.append("discovery log: \(last)")
+        }
+        return lines.joined(separator: "\n")
+    }
+
+    @ViewBuilder
+    private func lastKnownButtonLabel(host: String, port: Int) -> some View {
+        if self.connectingGatewayID == "last-known" {
+            HStack(spacing: 8) {
+                ProgressView()
+                    .progressViewStyle(.circular)
+                Text("Connecting…")
+            }
+            .frame(maxWidth: .infinity)
+        } else {
+            HStack(spacing: 8) {
+                Image(systemName: "bolt.horizontal.circle.fill")
+                VStack(alignment: .leading, spacing: 2) {
+                    Text("Connect last known")
+                    Text("\(host):\(port)")
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer()
+            }
+            .frame(maxWidth: .infinity)
+        }
+    }
+
+    private var manualPortBinding: Binding<String> {
+        Binding(
+            get: { self.manualGatewayPortText },
+            set: { newValue in
+                let filtered = newValue.filter(\.isNumber)
+                if self.manualGatewayPortText != filtered {
+                    self.manualGatewayPortText = filtered
+                }
+                if filtered.isEmpty {
+                    if self.manualGatewayPort != 0 {
+                        self.manualGatewayPort = 0
+                    }
+                } else if let port = Int(filtered), self.manualGatewayPort != port {
+                    self.manualGatewayPort = port
+                }
+            })
+    }
+
+    private var manualPortIsValid: Bool {
+        if self.manualGatewayPortText.isEmpty { return true }
+        return self.manualGatewayPort >= 1 && self.manualGatewayPort <= 65535
+    }
+
+    private func syncManualPortText() {
+        if self.manualGatewayPort > 0 {
+            let next = String(self.manualGatewayPort)
+            if self.manualGatewayPortText != next {
+                self.manualGatewayPortText = next
+            }
+        } else if !self.manualGatewayPortText.isEmpty {
+            self.manualGatewayPortText = ""
+        }
+    }
+
+    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 }
+        let host = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        let resolvedPort = self.resolvedManualPort(host: host)
+        let hasToken = !self.gatewayToken.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        let hasPassword = !self.gatewayPassword.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        GatewayDiagnostics.log(
+            "setup code applied host=\(host) port=\(resolvedPort ?? -1) tls=\(self.manualGatewayTLS) token=\(hasToken) password=\(hasPassword)")
+        guard let port = resolvedPort else {
+            self.setupStatusText = "Failed: invalid port"
+            return
+        }
+        let ok = await self.preflightGateway(host: host, port: port, useTLS: self.manualGatewayTLS)
+        guard ok else { return }
+        self.setupStatusText = "Setup code applied. Connecting…"
+        await self.connectManual()
+    }
+
+    @discardableResult
+    private func applySetupCode() -> Bool {
+        let raw = self.setupCode.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !raw.isEmpty else {
+            self.setupStatusText = "Paste a setup code to continue."
+            return false
+        }
+
+        guard let payload = self.decodeSetupPayload(raw: raw) else {
+            self.setupStatusText = "Setup code not recognized."
+            return false
+        }
+
+        if let urlString = payload.url, let url = URL(string: urlString) {
+            self.applySetupURL(url)
+        } else if let host = payload.host, !host.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            self.manualGatewayHost = host.trimmingCharacters(in: .whitespacesAndNewlines)
+            if let port = payload.port {
+                self.manualGatewayPort = port
+                self.manualGatewayPortText = String(port)
+            } else {
+                self.manualGatewayPort = 0
+                self.manualGatewayPortText = ""
+            }
+            if let tls = payload.tls {
+                self.manualGatewayTLS = tls
+            }
+        } else if let url = URL(string: raw), url.scheme != nil {
+            self.applySetupURL(url)
+        } else {
+            self.setupStatusText = "Setup code missing URL or host."
+            return false
+        }
+
+        let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let token = payload.token, !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            let trimmedToken = token.trimmingCharacters(in: .whitespacesAndNewlines)
+            self.gatewayToken = trimmedToken
+            if !trimmedInstanceId.isEmpty {
+                GatewaySettingsStore.saveGatewayToken(trimmedToken, instanceId: trimmedInstanceId)
+            }
+        }
+        if let password = payload.password, !password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            let trimmedPassword = password.trimmingCharacters(in: .whitespacesAndNewlines)
+            self.gatewayPassword = trimmedPassword
+            if !trimmedInstanceId.isEmpty {
+                GatewaySettingsStore.saveGatewayPassword(trimmedPassword, instanceId: trimmedInstanceId)
+            }
+        }
+
+        return true
+    }
+
+    private func applySetupURL(_ url: URL) {
+        guard let host = url.host, !host.isEmpty else { return }
+        self.manualGatewayHost = host
+        if let port = url.port {
+            self.manualGatewayPort = port
+            self.manualGatewayPortText = String(port)
+        } else {
+            self.manualGatewayPort = 0
+            self.manualGatewayPortText = ""
+        }
+        let scheme = (url.scheme ?? "").lowercased()
+        if scheme == "wss" || scheme == "https" {
+            self.manualGatewayTLS = true
+        } else if scheme == "ws" || scheme == "http" {
+            self.manualGatewayTLS = false
+        }
+    }
+
+    private func resolvedManualPort(host: String) -> Int? {
+        if self.manualGatewayPort > 0 {
+            return self.manualGatewayPort <= 65535 ? self.manualGatewayPort : nil
+        }
+        let trimmed = host.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if self.manualGatewayTLS && trimmed.lowercased().hasSuffix(".ts.net") {
+            return 443
+        }
+        return 18789
+    }
+
+    private func preflightGateway(host: String, port: Int, useTLS: Bool) async -> Bool {
+        let trimmed = host.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return false }
+
+        if Self.isTailnetHostOrIP(trimmed) && !Self.hasTailnetIPv4() {
+            let msg = "Tailscale is off on this iPhone. Turn it on, then try again."
+            self.setupStatusText = msg
+            GatewayDiagnostics.log("preflight fail: tailnet missing host=\(trimmed)")
+            self.gatewayLogger.warning("\(msg, privacy: .public)")
+            return false
+        }
+
+        self.setupStatusText = "Checking gateway reachability…"
+        let ok = await Self.probeTCP(host: trimmed, port: port, timeoutSeconds: 3)
+        if !ok {
+            let msg = "Can't reach gateway at \(trimmed):\(port). Check Tailscale or LAN."
+            self.setupStatusText = msg
+            GatewayDiagnostics.log("preflight fail: unreachable host=\(trimmed) port=\(port)")
+            self.gatewayLogger.warning("\(msg, privacy: .public)")
+            return false
+        }
+        GatewayDiagnostics.log("preflight ok host=\(trimmed) port=\(port) tls=\(useTLS)")
+        return true
+    }
+
+    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)
+            }
+        }
+    }
+
+    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)
+    }
+
     private func connectManual() async {
         let host = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !host.isEmpty else {
-            self.connectStatus.text = "Failed: host required"
+            self.setupStatusText = "Failed: host required"
             return
         }
-        guard self.manualGatewayPort > 0, self.manualGatewayPort <= 65535 else {
-            self.connectStatus.text = "Failed: invalid port"
+        guard self.manualPortIsValid else {
+            self.setupStatusText = "Failed: invalid port"
             return
         }
 
@@ -392,12 +801,54 @@ struct SettingsTab: View {
         self.manualGatewayEnabled = true
         defer { self.connectingGatewayID = nil }
 
+        GatewayDiagnostics.log(
+            "connect manual host=\(host) port=\(self.manualGatewayPort) tls=\(self.manualGatewayTLS)")
         await self.gatewayController.connectManual(
             host: host,
             port: self.manualGatewayPort,
             useTLS: self.manualGatewayTLS)
     }
 
+    private var setupStatusLine: String? {
+        let trimmedSetup = self.setupStatusText?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let gatewayStatus = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let friendly = self.friendlyGatewayMessage(from: gatewayStatus) { return friendly }
+        if let friendly = self.friendlyGatewayMessage(from: trimmedSetup) { return friendly }
+        if !trimmedSetup.isEmpty { return trimmedSetup }
+        if gatewayStatus.isEmpty || gatewayStatus == "Offline" { return nil }
+        return gatewayStatus
+    }
+
+    private var tailnetWarningText: String? {
+        let host = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !host.isEmpty else { return nil }
+        guard Self.isTailnetHostOrIP(host) else { return nil }
+        guard !Self.hasTailnetIPv4() else { return nil }
+        return "This gateway is on your tailnet. Turn on Tailscale on this iPhone, then tap Connect."
+    }
+
+    private func friendlyGatewayMessage(from raw: String) -> String? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        let lower = trimmed.lowercased()
+        if lower.contains("pairing required") {
+            return "Pairing required. Go back to Telegram and run /pair approve, then tap Connect again."
+        }
+        if lower.contains("device nonce required") || lower.contains("device nonce mismatch") {
+            return "Secure handshake failed. Make sure Tailscale is connected, then tap Connect again."
+        }
+        if lower.contains("device signature expired") || lower.contains("device signature invalid") {
+            return "Secure handshake failed. Check that your iPhone time is correct, then tap Connect again."
+        }
+        if lower.contains("connect timed out") || lower.contains("timed out") {
+            return "Connection timed out. Make sure Tailscale is connected, then try again."
+        }
+        if lower.contains("unauthorized role") {
+            return "Connected, but some controls are restricted for nodes. This is expected."
+        }
+        return nil
+    }
+
     private static func primaryIPv4Address() -> String? {
         var addrList: UnsafeMutablePointer<ifaddrs>?
         guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
@@ -436,6 +887,57 @@ struct SettingsTab: View {
         return en0 ?? fallback
     }
 
+    private static func hasTailnetIPv4() -> Bool {
+        var addrList: UnsafeMutablePointer<ifaddrs>?
+        guard getifaddrs(&addrList) == 0, let first = addrList else { return false }
+        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 true }
+        }
+
+        return false
+    }
+
+    private static func isTailnetHostOrIP(_ host: String) -> Bool {
+        let trimmed = host.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if trimmed.hasSuffix(".ts.net") || trimmed.hasSuffix(".ts.net.") {
+            return true
+        }
+        return self.isTailnetIPv4(trimmed)
+    }
+
+    private static func isTailnetIPv4(_ ip: String) -> Bool {
+        let parts = ip.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]
+        guard (0...255).contains(a), (0...255).contains(b) else { return false }
+        return a == 100 && b >= 64 && b <= 127
+    }
+
     private static func parseHostPort(from address: String) -> SettingsHostPort? {
         SettingsNetworkingHelpers.parseHostPort(from: address)
     }

apps/ios/Sources/Voice/TalkOrbOverlay.swift

@@ -7,6 +7,7 @@ struct TalkOrbOverlay: View {
     var body: some View {
         let seam = self.appModel.seamColor
         let status = self.appModel.talkMode.statusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        let mic = min(max(self.appModel.talkMode.micLevel, 0), 1)
 
         VStack(spacing: 14) {
             ZStack {
@@ -28,7 +29,7 @@ struct TalkOrbOverlay: View {
                     .fill(
                         RadialGradient(
                             colors: [
-                                seam.opacity(0.95),
+                                seam.opacity(0.75 + (0.20 * mic)),
                                 seam.opacity(0.40),
                                 Color.black.opacity(0.55),
                             ],
@@ -36,6 +37,7 @@ struct TalkOrbOverlay: View {
                             startRadius: 1,
                             endRadius: 112))
                     .frame(width: 190, height: 190)
+                    .scaleEffect(1.0 + (0.12 * mic))
                     .overlay(
                         Circle()
                             .stroke(seam.opacity(0.35), lineWidth: 1))
@@ -47,6 +49,13 @@ struct TalkOrbOverlay: View {
                 self.appModel.talkMode.userTappedOrb()
             }
 
+            let agentName = self.appModel.activeAgentName.trimmingCharacters(in: .whitespacesAndNewlines)
+            if !agentName.isEmpty {
+                Text("Bot: \(agentName)")
+                    .font(.system(.caption, design: .rounded).weight(.semibold))
+                    .foregroundStyle(Color.white.opacity(0.70))
+            }
+
             if !status.isEmpty, status != "Off" {
                 Text(status)
                     .font(.system(.footnote, design: .rounded).weight(.semibold))
@@ -59,6 +68,14 @@ struct TalkOrbOverlay: View {
                             .overlay(
                                 Capsule().stroke(seam.opacity(0.22), lineWidth: 1)))
             }
+
+            if self.appModel.talkMode.isListening {
+                Capsule()
+                    .fill(seam.opacity(0.90))
+                    .frame(width: max(18, 180 * mic), height: 6)
+                    .animation(.easeOut(duration: 0.12), value: mic)
+                    .accessibilityLabel("Microphone level")
+            }
         }
         .padding(28)
         .onAppear {

apps/ios/Sources/Voice/VoiceWakeManager.swift

@@ -1,6 +1,7 @@
 import AVFAudio
 import Foundation
 import Observation
+import OpenClawKit
 import Speech
 import SwabbleKit
 
@@ -96,6 +97,7 @@ final class VoiceWakeManager: NSObject {
     private var lastDispatched: String?
     private var onCommand: (@Sendable (String) async -> Void)?
     private var userDefaultsObserver: NSObjectProtocol?
+    private var suppressedByTalk: Bool = false
 
     override init() {
         super.init()
@@ -141,9 +143,28 @@ final class VoiceWakeManager: NSObject {
         }
     }
 
+    func setSuppressedByTalk(_ suppressed: Bool) {
+        self.suppressedByTalk = suppressed
+        if suppressed {
+            _ = self.suspendForExternalAudioCapture()
+            if self.isEnabled {
+                self.statusText = "Paused"
+            }
+        } else {
+            if self.isEnabled {
+                Task { await self.start() }
+            }
+        }
+    }
+
     func start() async {
         guard self.isEnabled else { return }
         if self.isListening { return }
+        guard !self.suppressedByTalk else {
+            self.isListening = false
+            self.statusText = "Paused"
+            return
+        }
 
         if ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"] != nil ||
             ProcessInfo.processInfo.environment["SIMULATOR_UDID"] != nil
@@ -159,14 +180,18 @@ final class VoiceWakeManager: NSObject {
 
         let micOk = await Self.requestMicrophonePermission()
         guard micOk else {
-            self.statusText = "Microphone permission denied"
+            self.statusText = Self.permissionMessage(
+                kind: "Microphone",
+                status: AVAudioSession.sharedInstance().recordPermission)
             self.isListening = false
             return
         }
 
         let speechOk = await Self.requestSpeechPermission()
         guard speechOk else {
-            self.statusText = "Speech recognition permission denied"
+            self.statusText = Self.permissionMessage(
+                kind: "Speech recognition",
+                status: SFSpeechRecognizer.authorizationStatus())
             self.isListening = false
             return
         }
@@ -364,20 +389,101 @@ final class VoiceWakeManager: NSObject {
     }
 
     private nonisolated static func requestMicrophonePermission() async -> Bool {
-        await withCheckedContinuation(isolation: nil) { cont in
-            AVAudioApplication.requestRecordPermission { ok in
-                cont.resume(returning: ok)
+        let session = AVAudioSession.sharedInstance()
+        switch session.recordPermission {
+        case .granted:
+            return true
+        case .denied:
+            return false
+        case .undetermined:
+            break
+        @unknown default:
+            return false
+        }
+
+        return await self.requestPermissionWithTimeout { completion in
+            AVAudioSession.sharedInstance().requestRecordPermission { ok in
+                completion(ok)
             }
         }
     }
 
     private nonisolated static func requestSpeechPermission() async -> Bool {
-        await withCheckedContinuation(isolation: nil) { cont in
-            SFSpeechRecognizer.requestAuthorization { status in
-                cont.resume(returning: status == .authorized)
+        let status = SFSpeechRecognizer.authorizationStatus()
+        switch status {
+        case .authorized:
+            return true
+        case .denied, .restricted:
+            return false
+        case .notDetermined:
+            break
+        @unknown default:
+            return false
+        }
+
+        return await self.requestPermissionWithTimeout { completion in
+            SFSpeechRecognizer.requestAuthorization { authStatus in
+                completion(authStatus == .authorized)
             }
         }
     }
+
+    private nonisolated static func requestPermissionWithTimeout(
+        _ operation: @escaping @Sendable (@escaping (Bool) -> Void) -> Void) async -> Bool
+    {
+        do {
+            return try await AsyncTimeout.withTimeout(
+                seconds: 8,
+                onTimeout: { NSError(domain: "VoiceWake", code: 6, userInfo: [
+                    NSLocalizedDescriptionKey: "permission request timed out",
+                ]) },
+                operation: {
+                    await withCheckedContinuation(isolation: nil) { cont in
+                        Task { @MainActor in
+                            operation { ok in
+                                cont.resume(returning: ok)
+                            }
+                        }
+                    }
+                })
+        } catch {
+            return false
+        }
+    }
+
+    private static func permissionMessage(
+        kind: String,
+        status: AVAudioSession.RecordPermission) -> String
+    {
+        switch status {
+        case .denied:
+            return "\(kind) permission denied"
+        case .undetermined:
+            return "\(kind) permission not granted"
+        case .granted:
+            return "\(kind) permission denied"
+        @unknown default:
+            return "\(kind) permission denied"
+        }
+    }
+
+    private static func permissionMessage(
+        kind: String,
+        status: SFSpeechRecognizerAuthorizationStatus) -> String
+    {
+        switch status {
+        case .denied:
+            return "\(kind) permission denied"
+        case .restricted:
+            return "\(kind) permission restricted"
+        case .notDetermined:
+            return "\(kind) permission not granted"
+        case .authorized:
+            return "\(kind) permission denied"
+        @unknown default:
+            return "\(kind) permission denied"
+        }
+    }
 }
 
 #if DEBUG

apps/ios/SwiftSources.input.xcfilelist

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

apps/ios/Tests/GatewaySettingsStoreTests.swift

@@ -7,8 +7,8 @@ private struct KeychainEntry: Hashable {
     let account: String
 }
 
-private let gatewayService = "bot.molt.gateway"
-private let nodeService = "bot.molt.node"
+private let gatewayService = "ai.openclaw.gateway"
+private let nodeService = "ai.openclaw.node"
 private let instanceIdEntry = KeychainEntry(service: nodeService, account: "instanceId")
 private let preferredGatewayEntry = KeychainEntry(service: gatewayService, account: "preferredStableID")
 private let lastGatewayEntry = KeychainEntry(service: gatewayService, account: "lastDiscoveredStableID")

apps/ios/Tests/NodeAppModelInvokeTests.swift

@@ -101,7 +101,8 @@ private func withUserDefaults<T>(_ updates: [String: Any?], _ body: () throws ->
         #expect(presentRes.ok == true)
         #expect(appModel.screen.urlString.isEmpty)
 
-        let navigateParams = OpenClawCanvasNavigateParams(url: "http://localhost:18789/")
+        // Loopback URLs are rejected (they are not meaningful for a remote gateway).
+        let navigateParams = OpenClawCanvasNavigateParams(url: "http://example.com/")
         let navData = try JSONEncoder().encode(navigateParams)
         let navJSON = String(decoding: navData, as: UTF8.self)
         let navigate = BridgeInvokeRequest(
@@ -110,7 +111,7 @@ private func withUserDefaults<T>(_ updates: [String: Any?], _ body: () throws ->
             paramsJSON: navJSON)
         let navRes = await appModel._test_handleInvoke(navigate)
         #expect(navRes.ok == true)
-        #expect(appModel.screen.urlString == "http://localhost:18789/")
+        #expect(appModel.screen.urlString == "http://example.com/")
 
         let evalParams = OpenClawCanvasEvalParams(javaScript: "1+1")
         let evalData = try JSONEncoder().encode(evalParams)

apps/shared/OpenClawKit/Sources/OpenClawKit/CalendarCommands.swift

@@ -0,0 +1,93 @@
+import Foundation
+
+public enum OpenClawCalendarCommand: String, Codable, Sendable {
+    case events = "calendar.events"
+    case add = "calendar.add"
+}
+
+public struct OpenClawCalendarEventsParams: Codable, Sendable, Equatable {
+    public var startISO: String?
+    public var endISO: String?
+    public var limit: Int?
+
+    public init(startISO: String? = nil, endISO: String? = nil, limit: Int? = nil) {
+        self.startISO = startISO
+        self.endISO = endISO
+        self.limit = limit
+    }
+}
+
+public struct OpenClawCalendarAddParams: Codable, Sendable, Equatable {
+    public var title: String
+    public var startISO: String
+    public var endISO: String
+    public var isAllDay: Bool?
+    public var location: String?
+    public var notes: String?
+    public var calendarId: String?
+    public var calendarTitle: String?
+
+    public init(
+        title: String,
+        startISO: String,
+        endISO: String,
+        isAllDay: Bool? = nil,
+        location: String? = nil,
+        notes: String? = nil,
+        calendarId: String? = nil,
+        calendarTitle: String? = nil)
+    {
+        self.title = title
+        self.startISO = startISO
+        self.endISO = endISO
+        self.isAllDay = isAllDay
+        self.location = location
+        self.notes = notes
+        self.calendarId = calendarId
+        self.calendarTitle = calendarTitle
+    }
+}
+
+public struct OpenClawCalendarEventPayload: Codable, Sendable, Equatable {
+    public var identifier: String
+    public var title: String
+    public var startISO: String
+    public var endISO: String
+    public var isAllDay: Bool
+    public var location: String?
+    public var calendarTitle: String?
+
+    public init(
+        identifier: String,
+        title: String,
+        startISO: String,
+        endISO: String,
+        isAllDay: Bool,
+        location: String? = nil,
+        calendarTitle: String? = nil)
+    {
+        self.identifier = identifier
+        self.title = title
+        self.startISO = startISO
+        self.endISO = endISO
+        self.isAllDay = isAllDay
+        self.location = location
+        self.calendarTitle = calendarTitle
+    }
+}
+
+public struct OpenClawCalendarEventsPayload: Codable, Sendable, Equatable {
+    public var events: [OpenClawCalendarEventPayload]
+
+    public init(events: [OpenClawCalendarEventPayload]) {
+        self.events = events
+    }
+}
+
+public struct OpenClawCalendarAddPayload: Codable, Sendable, Equatable {
+    public var event: OpenClawCalendarEventPayload
+
+    public init(event: OpenClawCalendarEventPayload) {
+        self.event = event
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/Capabilities.swift

@@ -6,4 +6,10 @@ public enum OpenClawCapability: String, Codable, Sendable {
     case screen
     case voiceWake
     case location
+    case device
+    case photos
+    case contacts
+    case calendar
+    case reminders
+    case motion
 }

apps/shared/OpenClawKit/Sources/OpenClawKit/ChatCommands.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+public enum OpenClawChatCommand: String, Codable, Sendable {
+    case push = "chat.push"
+}
+
+public struct OpenClawChatPushParams: Codable, Sendable, Equatable {
+    public var text: String
+    public var speak: Bool?
+
+    public init(text: String, speak: Bool? = nil) {
+        self.text = text
+        self.speak = speak
+    }
+}
+
+public struct OpenClawChatPushPayload: Codable, Sendable, Equatable {
+    public var messageId: String?
+
+    public init(messageId: String? = nil) {
+        self.messageId = messageId
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ContactsCommands.swift

@@ -0,0 +1,85 @@
+import Foundation
+
+public enum OpenClawContactsCommand: String, Codable, Sendable {
+    case search = "contacts.search"
+    case add = "contacts.add"
+}
+
+public struct OpenClawContactsSearchParams: Codable, Sendable, Equatable {
+    public var query: String?
+    public var limit: Int?
+
+    public init(query: String? = nil, limit: Int? = nil) {
+        self.query = query
+        self.limit = limit
+    }
+}
+
+public struct OpenClawContactsAddParams: Codable, Sendable, Equatable {
+    public var givenName: String?
+    public var familyName: String?
+    public var organizationName: String?
+    public var displayName: String?
+    public var phoneNumbers: [String]?
+    public var emails: [String]?
+
+    public init(
+        givenName: String? = nil,
+        familyName: String? = nil,
+        organizationName: String? = nil,
+        displayName: String? = nil,
+        phoneNumbers: [String]? = nil,
+        emails: [String]? = nil)
+    {
+        self.givenName = givenName
+        self.familyName = familyName
+        self.organizationName = organizationName
+        self.displayName = displayName
+        self.phoneNumbers = phoneNumbers
+        self.emails = emails
+    }
+}
+
+public struct OpenClawContactPayload: Codable, Sendable, Equatable {
+    public var identifier: String
+    public var displayName: String
+    public var givenName: String
+    public var familyName: String
+    public var organizationName: String
+    public var phoneNumbers: [String]
+    public var emails: [String]
+
+    public init(
+        identifier: String,
+        displayName: String,
+        givenName: String,
+        familyName: String,
+        organizationName: String,
+        phoneNumbers: [String],
+        emails: [String])
+    {
+        self.identifier = identifier
+        self.displayName = displayName
+        self.givenName = givenName
+        self.familyName = familyName
+        self.organizationName = organizationName
+        self.phoneNumbers = phoneNumbers
+        self.emails = emails
+    }
+}
+
+public struct OpenClawContactsSearchPayload: Codable, Sendable, Equatable {
+    public var contacts: [OpenClawContactPayload]
+
+    public init(contacts: [OpenClawContactPayload]) {
+        self.contacts = contacts
+    }
+}
+
+public struct OpenClawContactsAddPayload: Codable, Sendable, Equatable {
+    public var contact: OpenClawContactPayload
+
+    public init(contact: OpenClawContactPayload) {
+        self.contact = contact
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/DeviceCommands.swift

@@ -0,0 +1,134 @@
+import Foundation
+
+public enum OpenClawDeviceCommand: String, Codable, Sendable {
+    case status = "device.status"
+    case info = "device.info"
+}
+
+public enum OpenClawBatteryState: String, Codable, Sendable {
+    case unknown
+    case unplugged
+    case charging
+    case full
+}
+
+public enum OpenClawThermalState: String, Codable, Sendable {
+    case nominal
+    case fair
+    case serious
+    case critical
+}
+
+public enum OpenClawNetworkPathStatus: String, Codable, Sendable {
+    case satisfied
+    case unsatisfied
+    case requiresConnection
+}
+
+public enum OpenClawNetworkInterfaceType: String, Codable, Sendable {
+    case wifi
+    case cellular
+    case wired
+    case other
+}
+
+public struct OpenClawBatteryStatusPayload: Codable, Sendable, Equatable {
+    public var level: Double?
+    public var state: OpenClawBatteryState
+    public var lowPowerModeEnabled: Bool
+
+    public init(level: Double?, state: OpenClawBatteryState, lowPowerModeEnabled: Bool) {
+        self.level = level
+        self.state = state
+        self.lowPowerModeEnabled = lowPowerModeEnabled
+    }
+}
+
+public struct OpenClawThermalStatusPayload: Codable, Sendable, Equatable {
+    public var state: OpenClawThermalState
+
+    public init(state: OpenClawThermalState) {
+        self.state = state
+    }
+}
+
+public struct OpenClawStorageStatusPayload: Codable, Sendable, Equatable {
+    public var totalBytes: Int64
+    public var freeBytes: Int64
+    public var usedBytes: Int64
+
+    public init(totalBytes: Int64, freeBytes: Int64, usedBytes: Int64) {
+        self.totalBytes = totalBytes
+        self.freeBytes = freeBytes
+        self.usedBytes = usedBytes
+    }
+}
+
+public struct OpenClawNetworkStatusPayload: Codable, Sendable, Equatable {
+    public var status: OpenClawNetworkPathStatus
+    public var isExpensive: Bool
+    public var isConstrained: Bool
+    public var interfaces: [OpenClawNetworkInterfaceType]
+
+    public init(
+        status: OpenClawNetworkPathStatus,
+        isExpensive: Bool,
+        isConstrained: Bool,
+        interfaces: [OpenClawNetworkInterfaceType])
+    {
+        self.status = status
+        self.isExpensive = isExpensive
+        self.isConstrained = isConstrained
+        self.interfaces = interfaces
+    }
+}
+
+public struct OpenClawDeviceStatusPayload: Codable, Sendable, Equatable {
+    public var battery: OpenClawBatteryStatusPayload
+    public var thermal: OpenClawThermalStatusPayload
+    public var storage: OpenClawStorageStatusPayload
+    public var network: OpenClawNetworkStatusPayload
+    public var uptimeSeconds: Double
+
+    public init(
+        battery: OpenClawBatteryStatusPayload,
+        thermal: OpenClawThermalStatusPayload,
+        storage: OpenClawStorageStatusPayload,
+        network: OpenClawNetworkStatusPayload,
+        uptimeSeconds: Double)
+    {
+        self.battery = battery
+        self.thermal = thermal
+        self.storage = storage
+        self.network = network
+        self.uptimeSeconds = uptimeSeconds
+    }
+}
+
+public struct OpenClawDeviceInfoPayload: Codable, Sendable, Equatable {
+    public var deviceName: String
+    public var modelIdentifier: String
+    public var systemName: String
+    public var systemVersion: String
+    public var appVersion: String
+    public var appBuild: String
+    public var locale: String
+
+    public init(
+        deviceName: String,
+        modelIdentifier: String,
+        systemName: String,
+        systemVersion: String,
+        appVersion: String,
+        appBuild: String,
+        locale: String)
+    {
+        self.deviceName = deviceName
+        self.modelIdentifier = modelIdentifier
+        self.systemName = systemName
+        self.systemVersion = systemVersion
+        self.appVersion = appVersion
+        self.appBuild = appBuild
+        self.locale = locale
+    }
+}

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

@@ -72,6 +72,10 @@ public struct GatewayConnectOptions: Sendable {
     public var clientId: String
     public var clientMode: String
     public var clientDisplayName: String?
+    // When false, the connection omits the signed device identity payload.
+    // This is useful for secondary "operator" connections where the shared gateway token
+    // should authorize without triggering device pairing flows.
+    public var includeDeviceIdentity: Bool
 
     public init(
         role: String,
@@ -81,7 +85,8 @@ public struct GatewayConnectOptions: Sendable {
         permissions: [String: Bool],
         clientId: String,
         clientMode: String,
-        clientDisplayName: String?)
+        clientDisplayName: String?,
+        includeDeviceIdentity: Bool = true)
     {
         self.role = role
         self.scopes = scopes
@@ -91,6 +96,7 @@ public struct GatewayConnectOptions: Sendable {
         self.clientId = clientId
         self.clientMode = clientMode
         self.clientDisplayName = clientDisplayName
+        self.includeDeviceIdentity = includeDeviceIdentity
     }
 }
 
@@ -128,7 +134,7 @@ public actor GatewayChannelActor {
     private let decoder = JSONDecoder()
     private let encoder = JSONEncoder()
     private let connectTimeoutSeconds: Double = 6
-    private let connectChallengeTimeoutSeconds: Double = 0.75
+    private let connectChallengeTimeoutSeconds: Double = 3.0
     private var watchdogTask: Task<Void, Never>?
     private var tickTask: Task<Void, Never>?
     private let defaultRequestTimeoutMs: Double = 15000
@@ -307,9 +313,15 @@ public actor GatewayChannelActor {
         if !options.permissions.isEmpty {
             params["permissions"] = ProtoAnyCodable(options.permissions)
         }
-        let identity = DeviceIdentityStore.loadOrCreate()
-        let storedToken = DeviceAuthStore.loadToken(deviceId: identity.deviceId, role: role)?.token
-        let authToken = storedToken ?? self.token
+        let includeDeviceIdentity = options.includeDeviceIdentity
+        let identity = includeDeviceIdentity ? DeviceIdentityStore.loadOrCreate() : nil
+        let storedToken =
+            (includeDeviceIdentity && identity != nil)
+                ? DeviceAuthStore.loadToken(deviceId: identity!.deviceId, role: role)?.token
+                : nil
+        // If we're not sending a device identity, a device token can't be validated server-side.
+        // In that mode we always use the shared gateway token/password.
+        let authToken = includeDeviceIdentity ? (storedToken ?? self.token) : self.token
         let authSource: GatewayAuthSource
         if storedToken != nil {
             authSource = .deviceToken
@@ -322,7 +334,7 @@ public actor GatewayChannelActor {
         }
         self.lastAuthSource = authSource
         self.logger.info("gateway connect auth=\(authSource.rawValue, privacy: .public)")
-        let canFallbackToShared = storedToken != nil && self.token != nil
+        let canFallbackToShared = includeDeviceIdentity && storedToken != nil && self.token != nil
         if let authToken {
             params["auth"] = ProtoAnyCodable(["token": ProtoAnyCodable(authToken)])
         } else if let password = self.password {
@@ -333,7 +345,7 @@ public actor GatewayChannelActor {
         let scopesValue = scopes.joined(separator: ",")
         var payloadParts = [
             connectNonce == nil ? "v1" : "v2",
-            identity.deviceId,
+            identity?.deviceId ?? "",
             clientId,
             clientMode,
             role,
@@ -345,18 +357,20 @@ public actor GatewayChannelActor {
             payloadParts.append(connectNonce)
         }
         let payload = payloadParts.joined(separator: "|")
-        if let signature = DeviceIdentityStore.signPayload(payload, identity: identity),
-           let publicKey = DeviceIdentityStore.publicKeyBase64Url(identity) {
-            var device: [String: ProtoAnyCodable] = [
-                "id": ProtoAnyCodable(identity.deviceId),
-                "publicKey": ProtoAnyCodable(publicKey),
-                "signature": ProtoAnyCodable(signature),
-                "signedAt": ProtoAnyCodable(signedAtMs),
-            ]
-            if let connectNonce {
-                device["nonce"] = ProtoAnyCodable(connectNonce)
+        if includeDeviceIdentity, let identity {
+            if let signature = DeviceIdentityStore.signPayload(payload, identity: identity),
+               let publicKey = DeviceIdentityStore.publicKeyBase64Url(identity) {
+                var device: [String: ProtoAnyCodable] = [
+                    "id": ProtoAnyCodable(identity.deviceId),
+                    "publicKey": ProtoAnyCodable(publicKey),
+                    "signature": ProtoAnyCodable(signature),
+                    "signedAt": ProtoAnyCodable(signedAtMs),
+                ]
+                if let connectNonce {
+                    device["nonce"] = ProtoAnyCodable(connectNonce)
+                }
+                params["device"] = ProtoAnyCodable(device)
             }
-            params["device"] = ProtoAnyCodable(device)
         }
 
         let frame = RequestFrame(
@@ -371,7 +385,9 @@ public actor GatewayChannelActor {
             try await self.handleConnectResponse(response, identity: identity, role: role)
         } catch {
             if canFallbackToShared {
-                DeviceAuthStore.clearToken(deviceId: identity.deviceId, role: role)
+                if let identity {
+                    DeviceAuthStore.clearToken(deviceId: identity.deviceId, role: role)
+                }
             }
             throw error
         }
@@ -379,7 +395,7 @@ public actor GatewayChannelActor {
 
     private func handleConnectResponse(
         _ res: ResponseFrame,
-        identity: DeviceIdentity,
+        identity: DeviceIdentity?,
         role: String
     ) async throws {
         if res.ok == false {
@@ -404,11 +420,13 @@ public actor GatewayChannelActor {
             let authRole = auth["role"]?.value as? String ?? role
             let scopes = (auth["scopes"]?.value as? [ProtoAnyCodable])?
                 .compactMap { $0.value as? String } ?? []
-            _ = DeviceAuthStore.storeToken(
-                deviceId: identity.deviceId,
-                role: authRole,
-                token: deviceToken,
-                scopes: scopes)
+            if let identity {
+                _ = DeviceAuthStore.storeToken(
+                    deviceId: identity.deviceId,
+                    role: authRole,
+                    token: deviceToken,
+                    scopes: scopes)
+            }
         }
         self.lastTick = Date()
         self.tickTask?.cancel()
@@ -498,7 +516,10 @@ public actor GatewayChannelActor {
                     }
                 })
         } catch {
-            if error is ConnectChallengeError { return nil }
+            if error is ConnectChallengeError {
+                self.logger.warning("gateway connect challenge timed out")
+                return nil
+            }
             throw error
         }
     }

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

@@ -21,6 +21,7 @@ public actor GatewayNodeSession {
     private var activeURL: URL?
     private var activeToken: String?
     private var activePassword: String?
+    private var activeConnectOptionsKey: String?
     private var connectOptions: GatewayConnectOptions?
     private var onConnected: (@Sendable () async -> Void)?
     private var onDisconnected: (@Sendable (String) async -> Void)?
@@ -103,6 +104,42 @@ public actor GatewayNodeSession {
 
     public init() {}
 
+    private func connectOptionsKey(_ options: GatewayConnectOptions) -> String {
+        func sorted(_ values: [String]) -> String {
+            values.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                .filter { !$0.isEmpty }
+                .sorted()
+                .joined(separator: ",")
+        }
+        let role = options.role.trimmingCharacters(in: .whitespacesAndNewlines)
+        let scopes = sorted(options.scopes)
+        let caps = sorted(options.caps)
+        let commands = sorted(options.commands)
+        let clientId = options.clientId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let clientMode = options.clientMode.trimmingCharacters(in: .whitespacesAndNewlines)
+        let clientDisplayName = (options.clientDisplayName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        let includeDeviceIdentity = options.includeDeviceIdentity ? "1" : "0"
+        let permissions = options.permissions
+            .map { key, value in
+                let trimmed = key.trimmingCharacters(in: .whitespacesAndNewlines)
+                return "\(trimmed)=\(value ? "1" : "0")"
+            }
+            .sorted()
+            .joined(separator: ",")
+
+        return [
+            role,
+            scopes,
+            caps,
+            commands,
+            clientId,
+            clientMode,
+            clientDisplayName,
+            includeDeviceIdentity,
+            permissions,
+        ].joined(separator: "|")
+    }
+
     public func connect(
         url: URL,
         token: String?,
@@ -113,9 +150,11 @@ public actor GatewayNodeSession {
         onDisconnected: @escaping @Sendable (String) async -> Void,
         onInvoke: @escaping @Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse
     ) async throws {
+        let nextOptionsKey = self.connectOptionsKey(connectOptions)
         let shouldReconnect = self.activeURL != url ||
             self.activeToken != token ||
             self.activePassword != password ||
+            self.activeConnectOptionsKey != nextOptionsKey ||
             self.channel == nil
 
         self.connectOptions = connectOptions
@@ -138,12 +177,13 @@ public actor GatewayNodeSession {
                 },
                 connectOptions: connectOptions,
                 disconnectHandler: { [weak self] reason in
-                    await self?.onDisconnected?(reason)
+                    await self?.handleChannelDisconnected(reason)
                 })
             self.channel = channel
             self.activeURL = url
             self.activeToken = token
             self.activePassword = password
+            self.activeConnectOptionsKey = nextOptionsKey
         }
 
         guard let channel = self.channel else {
@@ -157,7 +197,6 @@ public actor GatewayNodeSession {
             _ = await self.waitForSnapshot(timeoutMs: 500)
             await self.notifyConnectedIfNeeded()
         } catch {
-            await onDisconnected(error.localizedDescription)
             throw error
         }
     }
@@ -168,6 +207,7 @@ public actor GatewayNodeSession {
         self.activeURL = nil
         self.activeToken = nil
         self.activePassword = nil
+        self.activeConnectOptionsKey = nil
         self.resetConnectionState()
     }
 
@@ -249,6 +289,13 @@ public actor GatewayNodeSession {
         }
     }
 
+    private func handleChannelDisconnected(_ reason: String) async {
+        // The underlying channel can auto-reconnect; resetting state here ensures we surface a fresh
+        // onConnected callback once a new snapshot arrives after reconnect.
+        self.resetConnectionState()
+        await self.onDisconnected?(reason)
+    }
+
     private func markSnapshotReceived() {
         self.snapshotReceived = true
         if !self.snapshotWaiters.isEmpty {

apps/shared/OpenClawKit/Sources/OpenClawKit/MotionCommands.swift

@@ -0,0 +1,95 @@
+import Foundation
+
+public enum OpenClawMotionCommand: String, Codable, Sendable {
+    case activity = "motion.activity"
+    case pedometer = "motion.pedometer"
+}
+
+public struct OpenClawMotionActivityParams: Codable, Sendable, Equatable {
+    public var startISO: String?
+    public var endISO: String?
+    public var limit: Int?
+
+    public init(startISO: String? = nil, endISO: String? = nil, limit: Int? = nil) {
+        self.startISO = startISO
+        self.endISO = endISO
+        self.limit = limit
+    }
+}
+
+public struct OpenClawMotionActivityEntry: Codable, Sendable, Equatable {
+    public var startISO: String
+    public var endISO: String
+    public var confidence: String
+    public var isWalking: Bool
+    public var isRunning: Bool
+    public var isCycling: Bool
+    public var isAutomotive: Bool
+    public var isStationary: Bool
+    public var isUnknown: Bool
+
+    public init(
+        startISO: String,
+        endISO: String,
+        confidence: String,
+        isWalking: Bool,
+        isRunning: Bool,
+        isCycling: Bool,
+        isAutomotive: Bool,
+        isStationary: Bool,
+        isUnknown: Bool)
+    {
+        self.startISO = startISO
+        self.endISO = endISO
+        self.confidence = confidence
+        self.isWalking = isWalking
+        self.isRunning = isRunning
+        self.isCycling = isCycling
+        self.isAutomotive = isAutomotive
+        self.isStationary = isStationary
+        self.isUnknown = isUnknown
+    }
+}
+
+public struct OpenClawMotionActivityPayload: Codable, Sendable, Equatable {
+    public var activities: [OpenClawMotionActivityEntry]
+
+    public init(activities: [OpenClawMotionActivityEntry]) {
+        self.activities = activities
+    }
+}
+
+public struct OpenClawPedometerParams: Codable, Sendable, Equatable {
+    public var startISO: String?
+    public var endISO: String?
+
+    public init(startISO: String? = nil, endISO: String? = nil) {
+        self.startISO = startISO
+        self.endISO = endISO
+    }
+}
+
+public struct OpenClawPedometerPayload: Codable, Sendable, Equatable {
+    public var startISO: String
+    public var endISO: String
+    public var steps: Int?
+    public var distanceMeters: Double?
+    public var floorsAscended: Int?
+    public var floorsDescended: Int?
+
+    public init(
+        startISO: String,
+        endISO: String,
+        steps: Int?,
+        distanceMeters: Double?,
+        floorsAscended: Int?,
+        floorsDescended: Int?)
+    {
+        self.startISO = startISO
+        self.endISO = endISO
+        self.steps = steps
+        self.distanceMeters = distanceMeters
+        self.floorsAscended = floorsAscended
+        self.floorsDescended = floorsDescended
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/PhotosCommands.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+public enum OpenClawPhotosCommand: String, Codable, Sendable {
+    case latest = "photos.latest"
+}
+
+public struct OpenClawPhotosLatestParams: Codable, Sendable, Equatable {
+    public var limit: Int?
+    public var maxWidth: Int?
+    public var quality: Double?
+
+    public init(limit: Int? = nil, maxWidth: Int? = nil, quality: Double? = nil) {
+        self.limit = limit
+        self.maxWidth = maxWidth
+        self.quality = quality
+    }
+}
+
+public struct OpenClawPhotoPayload: Codable, Sendable, Equatable {
+    public var format: String
+    public var base64: String
+    public var width: Int
+    public var height: Int
+    public var createdAt: String?
+
+    public init(format: String, base64: String, width: Int, height: Int, createdAt: String? = nil) {
+        self.format = format
+        self.base64 = base64
+        self.width = width
+        self.height = height
+        self.createdAt = createdAt
+    }
+}
+
+public struct OpenClawPhotosLatestPayload: Codable, Sendable, Equatable {
+    public var photos: [OpenClawPhotoPayload]
+
+    public init(photos: [OpenClawPhotoPayload]) {
+        self.photos = photos
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/RemindersCommands.swift

@@ -0,0 +1,82 @@
+import Foundation
+
+public enum OpenClawRemindersCommand: String, Codable, Sendable {
+    case list = "reminders.list"
+    case add = "reminders.add"
+}
+
+public enum OpenClawReminderStatusFilter: String, Codable, Sendable {
+    case incomplete
+    case completed
+    case all
+}
+
+public struct OpenClawRemindersListParams: Codable, Sendable, Equatable {
+    public var status: OpenClawReminderStatusFilter?
+    public var limit: Int?
+
+    public init(status: OpenClawReminderStatusFilter? = nil, limit: Int? = nil) {
+        self.status = status
+        self.limit = limit
+    }
+}
+
+public struct OpenClawRemindersAddParams: Codable, Sendable, Equatable {
+    public var title: String
+    public var dueISO: String?
+    public var notes: String?
+    public var listId: String?
+    public var listName: String?
+
+    public init(
+        title: String,
+        dueISO: String? = nil,
+        notes: String? = nil,
+        listId: String? = nil,
+        listName: String? = nil)
+    {
+        self.title = title
+        self.dueISO = dueISO
+        self.notes = notes
+        self.listId = listId
+        self.listName = listName
+    }
+}
+
+public struct OpenClawReminderPayload: Codable, Sendable, Equatable {
+    public var identifier: String
+    public var title: String
+    public var dueISO: String?
+    public var completed: Bool
+    public var listName: String?
+
+    public init(
+        identifier: String,
+        title: String,
+        dueISO: String? = nil,
+        completed: Bool,
+        listName: String? = nil)
+    {
+        self.identifier = identifier
+        self.title = title
+        self.dueISO = dueISO
+        self.completed = completed
+        self.listName = listName
+    }
+}
+
+public struct OpenClawRemindersListPayload: Codable, Sendable, Equatable {
+    public var reminders: [OpenClawReminderPayload]
+
+    public init(reminders: [OpenClawReminderPayload]) {
+        self.reminders = reminders
+    }
+}
+
+public struct OpenClawRemindersAddPayload: Codable, Sendable, Equatable {
+    public var reminder: OpenClawReminderPayload
+
+    public init(reminder: OpenClawReminderPayload) {
+        self.reminder = reminder
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/TalkCommands.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+public enum OpenClawTalkCommand: String, Codable, Sendable {
+    case pttStart = "talk.ptt.start"
+    case pttStop = "talk.ptt.stop"
+    case pttCancel = "talk.ptt.cancel"
+    case pttOnce = "talk.ptt.once"
+}
+
+public struct OpenClawTalkPTTStartPayload: Codable, Sendable, Equatable {
+    public var captureId: String
+
+    public init(captureId: String) {
+        self.captureId = captureId
+    }
+}
+
+public struct OpenClawTalkPTTStopPayload: Codable, Sendable, Equatable {
+    public var captureId: String
+    public var transcript: String?
+    public var status: String
+
+    public init(captureId: String, transcript: String?, status: String) {
+        self.captureId = captureId
+        self.transcript = transcript
+        self.status = status
+    }
+}

docs/.i18n/glossary.ja-JP.json

@@ -0,0 +1,14 @@
+[
+  { "source": "OpenClaw", "target": "OpenClaw" },
+  { "source": "Gateway", "target": "Gateway" },
+  { "source": "Pi", "target": "Pi" },
+  { "source": "Skills", "target": "Skills" },
+  { "source": "local loopback", "target": "local loopback" },
+  { "source": "Tailscale", "target": "Tailscale" },
+  { "source": "Getting Started", "target": "はじめに" },
+  { "source": "Getting started", "target": "はじめに" },
+  { "source": "Quick start", "target": "クイックスタート" },
+  { "source": "Quick Start", "target": "クイックスタート" },
+  { "source": "Onboarding", "target": "オンボーディング" },
+  { "source": "wizard", "target": "ウィザード" }
+]

docs/automation/cron-jobs.md

@@ -464,6 +464,13 @@ openclaw system event --mode now --text "Next heartbeat: check battery."
 - Check the Gateway is running continuously (cron runs inside the Gateway process).
 - For `cron` schedules: confirm timezone (`--tz`) vs the host timezone.
 
+### A recurring job keeps delaying after failures
+
+- OpenClaw applies exponential retry backoff for recurring jobs after consecutive errors:
+  30s, 1m, 5m, 15m, then 60m between retries.
+- Backoff resets automatically after the next successful run.
+- One-shot (`at`) jobs disable after a terminal run (`ok`, `error`, or `skipped`) and do not retry.
+
 ### Telegram delivers to the wrong place
 
 - For forum topics, use `-100…:topic:<id>` so it’s explicit and unambiguous.

docs/channels/feishu.md

@@ -490,14 +490,14 @@ Use `bindings` to route Feishu DMs or groups to different agents.
       agentId: "main",
       match: {
         channel: "feishu",
-        peer: { kind: "dm", id: "ou_xxx" },
+        peer: { kind: "direct", id: "ou_xxx" },
       },
     },
     {
       agentId: "clawd-fan",
       match: {
         channel: "feishu",
-        peer: { kind: "dm", id: "ou_yyy" },
+        peer: { kind: "direct", id: "ou_yyy" },
       },
     },
     {
@@ -514,7 +514,7 @@ Use `bindings` to route Feishu DMs or groups to different agents.
 Routing fields:
 
 - `match.channel`: `"feishu"`
-- `match.peer.kind`: `"dm"` or `"group"`
+- `match.peer.kind`: `"direct"` or `"group"`
 - `match.peer.id`: user Open ID (`ou_xxx`) or group ID (`oc_xxx`)
 
 See [Get group/user IDs](#get-groupuser-ids) for lookup tips.

docs/channels/pairing.md

@@ -52,6 +52,23 @@ Treat these as sensitive (they gate access to your assistant).
 Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
 creates a device pairing request that must be approved.
 
+### Pair via Telegram (recommended for iOS)
+
+If you use the `device-pair` plugin, you can do first-time device pairing entirely from Telegram:
+
+1. In Telegram, message your bot: `/pair`
+2. The bot replies with two messages: an instruction message and a separate **setup code** message (easy to copy/paste in Telegram).
+3. On your phone, open the OpenClaw iOS app → Settings → Gateway.
+4. Paste the setup code and connect.
+5. Back in Telegram: `/pair approve`
+
+The setup code is a base64-encoded JSON payload that contains:
+
+- `url`: the Gateway WebSocket URL (`ws://...` or `wss://...`)
+- `token`: a short-lived pairing token
+
+Treat the setup code like a password while it is valid.
+
 ### Approve a node device
 
 ```bash

docs/channels/telegram.md

@@ -157,10 +157,21 @@ More help: [Channel troubleshooting](/channels/troubleshooting).
 Notes:
 
 - Custom commands are **menu entries only**; OpenClaw does not implement them unless you handle them elsewhere.
+- Some commands can be handled by plugins/skills without being registered in Telegram’s command menu. These still work when typed (they just won't show up in `/commands` / the menu).
 - Command names are normalized (leading `/` stripped, lowercased) and must match `a-z`, `0-9`, `_` (1–32 chars).
 - Custom commands **cannot override native commands**. Conflicts are ignored and logged.
 - If `commands.native` is disabled, only custom commands are registered (or cleared if none).
 
+### Device pairing commands (`device-pair` plugin)
+
+If the `device-pair` plugin is installed, it adds a Telegram-first flow for pairing a new phone:
+
+1. `/pair` generates a setup code (sent as a separate message for easy copy/paste).
+2. Paste the setup code in the iOS app to connect.
+3. `/pair approve` approves the latest pending device request.
+
+More details: [Pairing](/channels/pairing#pair-via-telegram-recommended-for-ios).
+
 ## Limits
 
 - Outbound text is chunked to `channels.telegram.textChunkLimit` (default 4000).

docs/channels/whatsapp.md

@@ -196,7 +196,7 @@ Pairing is a DM gate for unknown senders:
 - Codes expire after 1 hour; pending requests are capped at 3 per channel.
 
 **Can multiple people use different OpenClaw instances on one WhatsApp number?**  
-Yes, by routing each sender to a different agent via `bindings` (peer `kind: "dm"`, sender E.164 like `+15551234567`). Replies still come from the **same WhatsApp account**, and direct chats collapse to each agent’s main session, so use **one agent per person**. DM access control (`dmPolicy`/`allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent).
+Yes, by routing each sender to a different agent via `bindings` (peer `kind: "direct"`, sender E.164 like `+15551234567`). Replies still come from the **same WhatsApp account**, and direct chats collapse to each agent's main session, so use **one agent per person**. DM access control (`dmPolicy`/`allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent).
 
 **Why do you ask for my phone number in the wizard?**  
 The wizard uses it to set your **allowlist/owner** so your own DMs are permitted. It’s not used for auto-sending. If you run on your personal WhatsApp number, use that same number and enable `channels.whatsapp.selfChatMode`.

docs/cli/cron.md

@@ -21,6 +21,8 @@ output internal. `--deliver` remains as a deprecated alias for `--announce`.
 
 Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
 
+Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.
+
 ## Common edits
 
 Update delivery settings without changing the message:

docs/cli/message.md

@@ -118,7 +118,7 @@ Name lookup:
 - `thread create`
   - Channels: Discord
   - Required: `--thread-name`, `--target` (channel id)
-  - Optional: `--message-id`, `--auto-archive-min`
+  - Optional: `--message-id`, `--message`, `--auto-archive-min`
 
 - `thread list`
   - Channels: Discord

docs/concepts/memory.md

@@ -184,6 +184,8 @@ out to QMD for retrieval. Key points:
 - `scope`: same schema as [`session.sendPolicy`](/gateway/configuration#session).
   Default is DM-only (`deny` all, `allow` direct chats); loosen it to surface QMD
   hits in groups/channels.
+- When `scope` denies a search, OpenClaw logs a warning with the derived
+  `channel`/`chatType` so empty results are easier to debug.
 - Snippets sourced outside the workspace show up as
   `qmd/<collection>/<relative-path>` in `memory_search` results; `memory_get`
   understands that prefix and reads from the configured QMD collection root.

docs/concepts/multi-agent.md

@@ -82,7 +82,7 @@ This lets **multiple people** share one Gateway server while keeping their AI
 
 ## One WhatsApp number, multiple people (DM split)
 
-You can route **different WhatsApp DMs** to different agents while staying on **one WhatsApp account**. Match on sender E.164 (like `+15551234567`) with `peer.kind: "dm"`. Replies still come from the same WhatsApp number (no per‑agent sender identity).
+You can route **different WhatsApp DMs** to different agents while staying on **one WhatsApp account**. Match on sender E.164 (like `+15551234567`) with `peer.kind: "direct"`. Replies still come from the same WhatsApp number (no per‑agent sender identity).
 
 Important detail: direct chats collapse to the agent’s **main session key**, so true isolation requires **one agent per person**.
 
@@ -97,8 +97,14 @@ Example:
     ],
   },
   bindings: [
-    { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
-    { agentId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
+    {
+      agentId: "alex",
+      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
+    },
+    {
+      agentId: "mia",
+      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
+    },
   ],
   channels: {
     whatsapp: {
@@ -260,7 +266,10 @@ Keep WhatsApp on the fast agent, but route one DM to Opus:
     ],
   },
   bindings: [
-    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
+    {
+      agentId: "opus",
+      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } },
+    },
     { agentId: "chat", match: { channel: "whatsapp" } },
   ],
 }

docs/concepts/session.md

@@ -106,7 +106,7 @@ the workspace is writable. See [Memory](/concepts/memory) and
 - Daily reset: defaults to **4:00 AM local time on the gateway host**. A session is stale once its last update is earlier than the most recent daily reset time.
 - Idle reset (optional): `idleMinutes` adds a sliding idle window. When both daily and idle resets are configured, **whichever expires first** forces a new session.
 - Legacy idle-only: if you set `session.idleMinutes` without any `session.reset`/`resetByType` config, OpenClaw stays in idle-only mode for backward compatibility.
-- Per-type overrides (optional): `resetByType` lets you override the policy for `dm`, `group`, and `thread` sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).
+- Per-type overrides (optional): `resetByType` lets you override the policy for `direct`, `group`, and `thread` sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).
 - Per-channel overrides (optional): `resetByChannel` overrides the reset policy for a channel (applies to all session types for that channel and takes precedence over `reset`/`resetByType`).
 - Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. `/new <model>` accepts a model alias, `provider/model`, or provider name (fuzzy match) to set the new session model. If `/new` or `/reset` is sent alone, OpenClaw runs a short “hello” greeting turn to confirm the reset.
 - Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
@@ -157,7 +157,7 @@ Runtime override (owner only):
     },
     resetByType: {
       thread: { mode: "daily", atHour: 4 },
-      dm: { mode: "idle", idleMinutes: 240 },
+      direct: { mode: "idle", idleMinutes: 240 },
       group: { mode: "idle", idleMinutes: 120 },
     },
     resetByChannel: {

docs/docs.json

@@ -1796,6 +1796,24 @@
             ]
           }
         ]
+      },
+      {
+        "language": "ja",
+        "tabs": [
+          {
+            "tab": "はじめに",
+            "groups": [
+              {
+                "group": "概要",
+                "pages": ["ja-JP/index"]
+              },
+              {
+                "group": "初回セットアップ",
+                "pages": ["ja-JP/start/getting-started", "ja-JP/start/wizard"]
+              }
+            ]
+          }
+        ]
       }
     ]
   }

docs/gateway/configuration.md

@@ -765,7 +765,7 @@ Inbound messages are routed to an agent via bindings.
 - `bindings[]`: routes inbound messages to an `agentId`.
   - `match.channel` (required)
   - `match.accountId` (optional; `*` = any account; omitted = default account)
-  - `match.peer` (optional; `{ kind: dm|group|channel, id }`)
+  - `match.peer` (optional; `{ kind: direct|group|channel, id }`)
   - `match.guildId` / `match.teamId` (optional; channel-specific)
 
 Deterministic match order:
@@ -2760,7 +2760,7 @@ Controls session scoping, reset policy, reset triggers, and where the session st
     },
     resetByType: {
       thread: { mode: "daily", atHour: 4 },
-      dm: { mode: "idle", idleMinutes: 240 },
+      direct: { mode: "idle", idleMinutes: 240 },
       group: { mode: "idle", idleMinutes: 120 },
     },
     resetTriggers: ["/new", "/reset"],
@@ -2797,7 +2797,7 @@ Fields:
   - `mode`: `daily` or `idle` (default: `daily` when `reset` is present).
   - `atHour`: local hour (0-23) for the daily reset boundary.
   - `idleMinutes`: sliding idle window in minutes. When daily + idle are both configured, whichever expires first wins.
-- `resetByType`: per-session overrides for `dm`, `group`, and `thread`.
+- `resetByType`: per-session overrides for `direct`, `group`, and `thread`. Legacy `dm` key is accepted as an alias for `direct`.
   - If you only set legacy `session.idleMinutes` without any `reset`/`resetByType`, OpenClaw stays in idle-only mode for backward compatibility.
 - `heartbeatIdleMinutes`: optional idle override for heartbeat checks (daily reset still applies when enabled).
 - `agentToAgent.maxPingPongTurns`: max reply-back turns between requester/target (0–5, default 5).

docs/help/environment.md

@@ -74,6 +74,32 @@ You can reference env vars directly in config string values using `${VAR_NAME}`
 
 See [Configuration: Env var substitution](/gateway/configuration#env-var-substitution-in-config) for full details.
 
+## Path-related env vars
+
+| Variable               | Purpose                                                                                                                                                                          |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENCLAW_HOME`        | Override the home directory used for all internal path resolution (`~/.openclaw/`, agent dirs, sessions, credentials). Useful when running OpenClaw as a dedicated service user. |
+| `OPENCLAW_STATE_DIR`   | Override the state directory (default `~/.openclaw`).                                                                                                                            |
+| `OPENCLAW_CONFIG_PATH` | Override the config file path (default `~/.openclaw/openclaw.json`).                                                                                                             |
+
+### `OPENCLAW_HOME`
+
+When set, `OPENCLAW_HOME` replaces the system home directory (`$HOME` / `os.homedir()`) for all internal path resolution. This enables full filesystem isolation for headless service accounts.
+
+**Precedence:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > `os.homedir()`
+
+**Example** (macOS LaunchDaemon):
+
+```xml
+<key>EnvironmentVariables</key>
+<dict>
+  <key>OPENCLAW_HOME</key>
+  <string>/Users/kira</string>
+</dict>
+```
+
+`OPENCLAW_HOME` can also be set to a tilde path (e.g. `~/svc`), which gets expanded using `$HOME` before use.
+
 ## Related
 
 - [Gateway configuration](/gateway/configuration)

docs/help/faq.md

@@ -803,7 +803,7 @@ See [/channels/telegram](/channels/telegram#access-control-dms--groups).
 
 ### Can multiple people use one WhatsApp number with different OpenClaw instances
 
-Yes, via **multi-agent routing**. Bind each sender's WhatsApp **DM** (peer `kind: "dm"`, sender E.164 like `+15551234567`) to a different `agentId`, so each person gets their own workspace and session store. Replies still come from the **same WhatsApp account**, and DM access control (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/channels/whatsapp).
+Yes, via **multi-agent routing**. Bind each sender's WhatsApp **DM** (peer `kind: "direct"`, sender E.164 like `+15551234567`) to a different `agentId`, so each person gets their own workspace and session store. Replies still come from the **same WhatsApp account**, and DM access control (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/channels/whatsapp).
 
 ### Can I run a fast chat agent and an Opus for coding agent
 

docs/install/index.md

@@ -163,6 +163,14 @@ openclaw status         # gateway status
 openclaw dashboard      # open the browser UI
 ```
 
+If you need custom runtime paths, use:
+
+- `OPENCLAW_HOME` for home-directory based internal paths
+- `OPENCLAW_STATE_DIR` for mutable state location
+- `OPENCLAW_CONFIG_PATH` for config file location
+
+See [Environment vars](/help/environment) for precedence and full details.
+
 ## Troubleshooting: `openclaw` not found
 
 <Accordion title="PATH diagnosis and fix">

docs/install/nix.md

@@ -64,7 +64,9 @@ defaults write bot.molt.mac openclaw.nixMode -bool true
 ### Config + state paths
 
 OpenClaw reads JSON5 config from `OPENCLAW_CONFIG_PATH` and stores mutable data in `OPENCLAW_STATE_DIR`.
+When needed, you can also set `OPENCLAW_HOME` to control the base home directory used for internal path resolution.
 
+- `OPENCLAW_HOME` (default precedence: `HOME` / `USERPROFILE` / `os.homedir()`)
 - `OPENCLAW_STATE_DIR` (default: `~/.openclaw`)
 - `OPENCLAW_CONFIG_PATH` (default: `$OPENCLAW_STATE_DIR/openclaw.json`)
 

docs/ja-JP/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md - ja-JP docs translation workspace
+
+## Read When
+
+- Maintaining `docs/ja-JP/**`
+- Updating the Japanese translation pipeline (glossary/TM/prompt)
+- Handling Japanese translation feedback or regressions
+
+## Pipeline (docs-i18n)
+
+- Source docs: `docs/**/*.md`
+- Target docs: `docs/ja-JP/**/*.md`
+- Glossary: `docs/.i18n/glossary.ja-JP.json`
+- Translation memory: `docs/.i18n/ja-JP.tm.jsonl`
+- Prompt rules: `scripts/docs-i18n/prompt.go`
+
+Common runs:
+
+```bash
+# Bulk (doc mode; parallel OK)
+cd scripts/docs-i18n
+go run . -docs ../../docs -lang ja-JP -mode doc -parallel 6 ../../docs/**/*.md
+
+# Single file
+cd scripts/docs-i18n
+go run . -docs ../../docs -lang ja-JP -mode doc ../../docs/start/getting-started.md
+
+# Small patches (segment mode; uses TM; no parallel)
+cd scripts/docs-i18n
+go run . -docs ../../docs -lang ja-JP -mode segment ../../docs/start/getting-started.md
+```
+
+Notes:
+
+- Prefer `doc` mode for whole-page translation; `segment` mode for small fixes.
+- If a very large file times out, do targeted edits or split the page before rerunning.
+- After translation, spot-check: code spans/blocks unchanged, links/anchors unchanged, placeholders preserved.

docs/ja-JP/index.md

@@ -0,0 +1,186 @@
+---
+read_when:
+  - 新規ユーザーにOpenClawを紹介するとき
+summary: OpenClawは、あらゆるOSで動作するAIエージェント向けのマルチチャネルgatewayです。
+title: OpenClaw
+x-i18n:
+  generated_at: "2026-02-08T17:15:47Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: fc8babf7885ef91d526795051376d928599c4cf8aff75400138a0d7d9fa3b75f
+  source_path: index.md
+  workflow: 15
+---
+
+# OpenClaw 🦞
+
+<p align="center">
+    <img
+        src="/assets/openclaw-logo-text-dark.png"
+        alt="OpenClaw"
+        width="500"
+        class="dark:hidden"
+    />
+    <img
+        src="/assets/openclaw-logo-text.png"
+        alt="OpenClaw"
+        width="500"
+        class="hidden dark:block"
+    />
+</p>
+
+> _「EXFOLIATE! EXFOLIATE!」_ — たぶん宇宙ロブスター
+
+<p align="center">
+  <strong>WhatsApp、Telegram、Discord、iMessageなどに対応した、あらゆるOS向けのAIエージェントgateway。</strong><br />
+  メッセージを送信すれば、ポケットからエージェントの応答を受け取れます。プラグインでMattermostなどを追加できます。
+</p>
+
+<Columns>
+  <Card title="はじめに" href="/start/getting-started" icon="rocket">
+    OpenClawをインストールし、数分でGatewayを起動できます。
+  </Card>
+  <Card title="ウィザードを実行" href="/start/wizard" icon="sparkles">
+    `openclaw onboard`とペアリングフローによるガイド付きセットアップ。
+  </Card>
+  <Card title="Control UIを開く" href="/web/control-ui" icon="layout-dashboard">
+    チャット、設定、セッション用のブラウザダッシュボードを起動します。
+  </Card>
+</Columns>
+
+OpenClawは、単一のGatewayプロセスを通じてチャットアプリをPiのようなコーディングエージェントに接続します。OpenClawアシスタントを駆動し、ローカルまたはリモートのセットアップをサポートします。
+
+## 仕組み
+
+```mermaid
+flowchart LR
+  A["チャットアプリ + プラグイン"] --> B["Gateway"]
+  B --> C["Piエージェント"]
+  B --> D["CLI"]
+  B --> E["Web Control UI"]
+  B --> F["macOSアプリ"]
+  B --> G["iOSおよびAndroidノード"]
+```
+
+Gatewayは、セッション、ルーティング、チャネル接続の信頼できる唯一の情報源です。
+
+## 主な機能
+
+<Columns>
+  <Card title="マルチチャネルgateway" icon="network">
+    単一のGatewayプロセスでWhatsApp、Telegram、Discord、iMessageに対応。
+  </Card>
+  <Card title="プラグインチャネル" icon="plug">
+    拡張パッケージでMattermostなどを追加。
+  </Card>
+  <Card title="マルチエージェントルーティング" icon="route">
+    エージェント、ワークスペース、送信者ごとに分離されたセッション。
+  </Card>
+  <Card title="メディアサポート" icon="image">
+    画像、音声、ドキュメントの送受信。
+  </Card>
+  <Card title="Web Control UI" icon="monitor">
+    チャット、設定、セッション、ノード用のブラウザダッシュボード。
+  </Card>
+  <Card title="モバイルノード" icon="smartphone">
+    Canvas対応のiOSおよびAndroidノードをペアリング。
+  </Card>
+</Columns>
+
+## クイックスタート
+
+<Steps>
+  <Step title="OpenClawをインストール">
+    ```bash
+    npm install -g openclaw@latest
+    ```
+  </Step>
+  <Step title="オンボーディングとサービスのインストール">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
+  </Step>
+  <Step title="WhatsAppをペアリングしてGatewayを起動">
+    ```bash
+    openclaw channels login
+    openclaw gateway --port 18789
+    ```
+  </Step>
+</Steps>
+
+完全なインストールと開発セットアップが必要ですか？[クイックスタート](/start/quickstart)をご覧ください。
+
+## ダッシュボード
+
+Gatewayの起動後、ブラウザでControl UIを開きます。
+
+- ローカルデフォルト: http://127.0.0.1:18789/
+- リモートアクセス: [Webサーフェス](/web)および[Tailscale](/gateway/tailscale)
+
+<p align="center">
+  <img src="whatsapp-openclaw.jpg" alt="OpenClaw" width="420" />
+</p>
+
+## 設定（オプション）
+
+設定は`~/.openclaw/openclaw.json`にあります。
+
+- **何もしなければ**、OpenClawはバンドルされたPiバイナリをRPCモードで使用し、送信者ごとのセッションを作成します。
+- 制限を設けたい場合は、`channels.whatsapp.allowFrom`と（グループの場合）メンションルールから始めてください。
+
+例：
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: { "*": { requireMention: true } },
+    },
+  },
+  messages: { groupChat: { mentionPatterns: ["@openclaw"] } },
+}
+```
+
+## ここから始める
+
+<Columns>
+  <Card title="ドキュメントハブ" href="/start/hubs" icon="book-open">
+    ユースケース別に整理されたすべてのドキュメントとガイド。
+  </Card>
+  <Card title="設定" href="/gateway/configuration" icon="settings">
+    Gatewayのコア設定、トークン、プロバイダー設定。
+  </Card>
+  <Card title="リモートアクセス" href="/gateway/remote" icon="globe">
+    SSHおよびtailnetアクセスパターン。
+  </Card>
+  <Card title="チャネル" href="/channels/telegram" icon="message-square">
+    WhatsApp、Telegram、Discordなどのチャネル固有のセットアップ。
+  </Card>
+  <Card title="ノード" href="/nodes" icon="smartphone">
+    ペアリングとCanvas対応のiOSおよびAndroidノード。
+  </Card>
+  <Card title="ヘルプ" href="/help" icon="life-buoy">
+    一般的な修正とトラブルシューティングのエントリーポイント。
+  </Card>
+</Columns>
+
+## 詳細
+
+<Columns>
+  <Card title="全機能リスト" href="/concepts/features" icon="list">
+    チャネル、ルーティング、メディア機能の完全な一覧。
+  </Card>
+  <Card title="マルチエージェントルーティング" href="/concepts/multi-agent" icon="route">
+    ワークスペースの分離とエージェントごとのセッション。
+  </Card>
+  <Card title="セキュリティ" href="/gateway/security" icon="shield">
+    トークン、許可リスト、安全制御。
+  </Card>
+  <Card title="トラブルシューティング" href="/gateway/troubleshooting" icon="wrench">
+    Gatewayの診断と一般的なエラー。
+  </Card>
+  <Card title="概要とクレジット" href="/reference/credits" icon="info">
+    プロジェクトの起源、貢献者、ライセンス。
+  </Card>
+</Columns>

docs/ja-JP/start/getting-started.md

@@ -0,0 +1,125 @@
+---
+read_when:
+  - ゼロからの初回セットアップ
+  - 動作するチャットへの最短ルートを知りたい
+summary: OpenClawをインストールし、数分で最初のチャットを実行しましょう。
+title: はじめに
+x-i18n:
+  generated_at: "2026-02-08T17:15:16Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 27aeeb3d18c495380e94e6b011b0df3def518535c9f1eee504f04871d8a32269
+  source_path: start/getting-started.md
+  workflow: 15
+---
+
+# はじめに
+
+目標：ゼロから最小限のセットアップで最初の動作するチャットを実現する。
+
+<Info>
+最速のチャット方法：Control UIを開く（チャンネル設定は不要）。`openclaw dashboard`を実行してブラウザでチャットするか、<Tooltip headline="Gatewayホスト" tip="OpenClaw Gatewayサービスを実行しているマシン。">Gatewayホスト</Tooltip>で`http://127.0.0.1:18789/`を開きます。
+ドキュメント：[Dashboard](/web/dashboard)と[Control UI](/web/control-ui)。
+</Info>
+
+## 前提条件
+
+- Node 22以降
+
+<Tip>
+不明な場合は`node --version`でNodeのバージョンを確認してください。
+</Tip>
+
+## クイックセットアップ（CLI）
+
+<Steps>
+  <Step title="OpenClawをインストール（推奨）">
+    <Tabs>
+      <Tab title="macOS/Linux">
+        ```bash
+        curl -fsSL https://openclaw.ai/install.sh | bash
+        ```
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        iwr -useb https://openclaw.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
+
+    <Note>
+    その他のインストール方法と要件：[インストール](/install)。
+    </Note>
+
+  </Step>
+  <Step title="オンボーディングウィザードを実行">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
+
+    ウィザードは認証、Gateway設定、およびオプションのチャンネルを構成します。
+    詳細は[オンボーディングウィザード](/start/wizard)を参照してください。
+
+  </Step>
+  <Step title="Gatewayを確認">
+    サービスをインストールした場合、すでに実行されているはずです：
+
+    ```bash
+    openclaw gateway status
+    ```
+
+  </Step>
+  <Step title="Control UIを開く">
+    ```bash
+    openclaw dashboard
+    ```
+  </Step>
+</Steps>
+
+<Check>
+Control UIが読み込まれれば、Gatewayは使用可能な状態です。
+</Check>
+
+## オプションの確認と追加機能
+
+<AccordionGroup>
+  <Accordion title="Gatewayをフォアグラウンドで実行">
+    クイックテストやトラブルシューティングに便利です。
+
+    ```bash
+    openclaw gateway --port 18789
+    ```
+
+  </Accordion>
+  <Accordion title="テストメッセージを送信">
+    構成済みのチャンネルが必要です。
+
+    ```bash
+    openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+    ```
+
+  </Accordion>
+</AccordionGroup>
+
+## さらに詳しく
+
+<Columns>
+  <Card title="オンボーディングウィザード（詳細）" href="/start/wizard">
+    完全なCLIウィザードリファレンスと高度なオプション。
+  </Card>
+  <Card title="macOSアプリのオンボーディング" href="/start/onboarding">
+    macOSアプリの初回実行フロー。
+  </Card>
+</Columns>
+
+## 完了後の状態
+
+- 実行中のGateway
+- 構成済みの認証
+- Control UIアクセスまたは接続済みのチャンネル
+
+## 次のステップ
+
+- DMの安全性と承認：[ペアリング](/channels/pairing)
+- さらにチャンネルを接続：[チャンネル](/channels)
+- 高度なワークフローとソースからのビルド：[セットアップ](/start/setup)

docs/ja-JP/start/wizard.md

@@ -0,0 +1,77 @@
+---
+read_when:
+  - オンボーディングウィザードの実行または設定時
+  - 新しいマシンのセットアップ時
+sidebarTitle: Wizard (CLI)
+summary: CLIオンボーディングウィザード：Gateway、ワークスペース、チャンネル、Skillsの対話式セットアップ
+title: オンボーディングウィザード（CLI）
+x-i18n:
+  generated_at: "2026-02-08T17:15:18Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9a650d46044a930aa4aaec30b35f1273ca3969bf676ab67bf4e1575b5c46db4c
+  source_path: start/wizard.md
+  workflow: 15
+---
+
+# オンボーディングウィザード（CLI）
+
+CLIオンボーディングウィザードは、macOS、Linux、Windows（WSL2経由）でOpenClawをセットアップする際の推奨パスです。ローカルGatewayまたはリモートGateway接続に加えて、ワークスペースのデフォルト設定、チャンネル、Skillsを構成します。
+
+```bash
+openclaw onboard
+```
+
+<Info>
+最速で初回チャットを開始する方法：Control UI を開きます（チャンネル設定は不要）。`openclaw dashboard` を実行してブラウザでチャットできます。ドキュメント：[Dashboard](/web/dashboard)。
+</Info>
+
+## クイックスタート vs 詳細設定
+
+ウィザードは**クイックスタート**（デフォルト設定）と**詳細設定**（完全な制御）のどちらかを選択して開始します。
+
+<Tabs>
+  <Tab title="クイックスタート（デフォルト設定）">
+    - loopback上のローカルGateway
+    - 既存のワークスペースまたはデフォルトワークスペース
+    - Gatewayポート `18789`
+    - Gateway認証トークンは自動生成（loopback上でも生成されます）
+    - Tailscale公開はオフ
+    - TelegramとWhatsAppのDMはデフォルトで許可リスト（電話番号の入力を求められる場合があります）
+  </Tab>
+  <Tab title="詳細設定（完全な制御）">
+    - モード、ワークスペース、Gateway、チャンネル、デーモン、Skillsの完全なプロンプトフローを表示
+  </Tab>
+</Tabs>
+
+## CLIオンボーディングの詳細
+
+<Columns>
+  <Card title="CLIリファレンス" href="/start/wizard-cli-reference">
+    ローカルおよびリモートフローの完全な説明、認証とモデルマトリックス、設定出力、ウィザードRPC、signal-cliの動作。
+  </Card>
+  <Card title="自動化とスクリプト" href="/start/wizard-cli-automation">
+    非対話式オンボーディングのレシピと自動化された `agents add` の例。
+  </Card>
+</Columns>
+
+## よく使うフォローアップコマンド
+
+```bash
+openclaw configure
+openclaw agents add <name>
+```
+
+<Note>
+`--json` は非対話モードを意味しません。スクリプトでは `--non-interactive` を使用してください。
+</Note>
+
+<Tip>
+推奨：エージェントが `web_search` を使用できるように、Brave Search APIキーを設定してください（`web_fetch` はキーなしで動作します）。最も簡単な方法：`openclaw configure --section web` を実行すると `tools.web.search.apiKey` が保存されます。ドキュメント：[Webツール](/tools/web)。
+</Tip>
+
+## 関連ドキュメント
+
+- CLIコマンドリファレンス：[`openclaw onboard`](/cli/onboard)
+- macOSアプリのオンボーディング：[オンボーディング](/start/onboarding)
+- エージェント初回起動の手順：[エージェントブートストラップ](/start/bootstrapping)

docs/refactor/plugin-sdk.md

@@ -72,7 +72,7 @@ export type PluginRuntime = {
         cfg: unknown;
         channel: string;
         accountId: string;
-        peer: { kind: "dm" | "group" | "channel"; id: string };
+        peer: { kind: RoutePeerKind; id: string };
       }): { sessionKey: string; accountId: string };
     };
     pairing: {

docs/security/CONTRIBUTING-THREAT-MODEL.md

@@ -0,0 +1,90 @@
+# Contributing to the OpenClaw Threat Model
+
+Thanks for helping make OpenClaw more secure. This threat model is a living document and we welcome contributions from anyone - you don't need to be a security expert.
+
+## Ways to Contribute
+
+### Add a Threat
+
+Spotted an attack vector or risk we haven't covered? Open an issue on [openclaw/trust](https://github.com/openclaw/trust/issues) and describe it in your own words. You don't need to know any frameworks or fill in every field - just describe the scenario.
+
+**Helpful to include (but not required):**
+
+- The attack scenario and how it could be exploited
+- Which parts of OpenClaw are affected (CLI, gateway, channels, ClawHub, MCP servers, etc.)
+- How severe you think it is (low / medium / high / critical)
+- Any links to related research, CVEs, or real-world examples
+
+We'll handle the ATLAS mapping, threat IDs, and risk assessment during review. If you want to include those details, great - but it's not expected.
+
+> **This is for adding to the threat model, not reporting live vulnerabilities.** If you've found an exploitable vulnerability, see our [Trust page](https://trust.openclaw.ai) for responsible disclosure instructions.
+
+### Suggest a Mitigation
+
+Have an idea for how to address an existing threat? Open an issue or PR referencing the threat. Useful mitigations are specific and actionable - for example, "per-sender rate limiting of 10 messages/minute at the gateway" is better than "implement rate limiting."
+
+### Propose an Attack Chain
+
+Attack chains show how multiple threats combine into a realistic attack scenario. If you see a dangerous combination, describe the steps and how an attacker would chain them together. A short narrative of how the attack unfolds in practice is more valuable than a formal template.
+
+### Fix or Improve Existing Content
+
+Typos, clarifications, outdated info, better examples - PRs welcome, no issue needed.
+
+## What We Use
+
+### MITRE ATLAS
+
+This threat model is built on [MITRE ATLAS](https://atlas.mitre.org/) (Adversarial Threat Landscape for AI Systems), a framework designed specifically for AI/ML threats like prompt injection, tool misuse, and agent exploitation. You don't need to know ATLAS to contribute - we map submissions to the framework during review.
+
+### Threat IDs
+
+Each threat gets an ID like `T-EXEC-003`. The categories are:
+
+| Code    | Category                                   |
+| ------- | ------------------------------------------ |
+| RECON   | Reconnaissance - information gathering     |
+| ACCESS  | Initial access - gaining entry             |
+| EXEC    | Execution - running malicious actions      |
+| PERSIST | Persistence - maintaining access           |
+| EVADE   | Defense evasion - avoiding detection       |
+| DISC    | Discovery - learning about the environment |
+| EXFIL   | Exfiltration - stealing data               |
+| IMPACT  | Impact - damage or disruption              |
+
+IDs are assigned by maintainers during review. You don't need to pick one.
+
+### Risk Levels
+
+| Level        | Meaning                                                           |
+| ------------ | ----------------------------------------------------------------- |
+| **Critical** | Full system compromise, or high likelihood + critical impact      |
+| **High**     | Significant damage likely, or medium likelihood + critical impact |
+| **Medium**   | Moderate risk, or low likelihood + high impact                    |
+| **Low**      | Unlikely and limited impact                                       |
+
+If you're unsure about the risk level, just describe the impact and we'll assess it.
+
+## Review Process
+
+1. **Triage** - We review new submissions within 48 hours
+2. **Assessment** - We verify feasibility, assign ATLAS mapping and threat ID, validate risk level
+3. **Documentation** - We ensure everything is formatted and complete
+4. **Merge** - Added to the threat model and visualization
+
+## Resources
+
+- [ATLAS Website](https://atlas.mitre.org/)
+- [ATLAS Techniques](https://atlas.mitre.org/techniques/)
+- [ATLAS Case Studies](https://atlas.mitre.org/studies/)
+- [OpenClaw Threat Model](./THREAT-MODEL-ATLAS.md)
+
+## Contact
+
+- **Security vulnerabilities:** See our [Trust page](https://trust.openclaw.ai) for reporting instructions
+- **Threat model questions:** Open an issue on [openclaw/trust](https://github.com/openclaw/trust/issues)
+- **General chat:** Discord #security channel
+
+## Recognition
+
+Contributors to the threat model are recognized in the threat model acknowledgments, release notes, and the OpenClaw security hall of fame for significant contributions.

docs/security/README.md

@@ -0,0 +1,17 @@
+# OpenClaw Security & Trust
+
+**Live:** [trust.openclaw.ai](https://trust.openclaw.ai)
+
+## Documents
+
+- [Threat Model](./THREAT-MODEL-ATLAS.md) - MITRE ATLAS-based threat model for the OpenClaw ecosystem
+- [Contributing to the Threat Model](./CONTRIBUTING-THREAT-MODEL.md) - How to add threats, mitigations, and attack chains
+
+## Reporting Vulnerabilities
+
+See the [Trust page](https://trust.openclaw.ai) for full reporting instructions covering all repos.
+
+## Contact
+
+- **Jamieson O'Reilly** ([@theonejvo](https://twitter.com/theonejvo)) - Security & Trust
+- Discord: #security channel

docs/security/THREAT-MODEL-ATLAS.md

@@ -0,0 +1,603 @@
+# OpenClaw Threat Model v1.0
+
+## MITRE ATLAS Framework
+
+**Version:** 1.0-draft
+**Last Updated:** 2026-02-04
+**Methodology:** MITRE ATLAS + Data Flow Diagrams
+**Framework:** [MITRE ATLAS](https://atlas.mitre.org/) (Adversarial Threat Landscape for AI Systems)
+
+### Framework Attribution
+
+This threat model is built on [MITRE ATLAS](https://atlas.mitre.org/), the industry-standard framework for documenting adversarial threats to AI/ML systems. ATLAS is maintained by [MITRE](https://www.mitre.org/) in collaboration with the AI security community.
+
+**Key ATLAS Resources:**
+
+- [ATLAS Techniques](https://atlas.mitre.org/techniques/)
+- [ATLAS Tactics](https://atlas.mitre.org/tactics/)
+- [ATLAS Case Studies](https://atlas.mitre.org/studies/)
+- [ATLAS GitHub](https://github.com/mitre-atlas/atlas-data)
+- [Contributing to ATLAS](https://atlas.mitre.org/resources/contribute)
+
+### Contributing to This Threat Model
+
+This is a living document maintained by the OpenClaw community. See [CONTRIBUTING-THREAT-MODEL.md](./CONTRIBUTING-THREAT-MODEL.md) for guidelines on contributing:
+
+- Reporting new threats
+- Updating existing threats
+- Proposing attack chains
+- Suggesting mitigations
+
+---
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+This threat model documents adversarial threats to the OpenClaw AI agent platform and ClawHub skill marketplace, using the MITRE ATLAS framework designed specifically for AI/ML systems.
+
+### 1.2 Scope
+
+| Component              | Included | Notes                                            |
+| ---------------------- | -------- | ------------------------------------------------ |
+| OpenClaw Agent Runtime | Yes      | Core agent execution, tool calls, sessions       |
+| Gateway                | Yes      | Authentication, routing, channel integration     |
+| Channel Integrations   | Yes      | WhatsApp, Telegram, Discord, Signal, Slack, etc. |
+| ClawHub Marketplace    | Yes      | Skill publishing, moderation, distribution       |
+| MCP Servers            | Yes      | External tool providers                          |
+| User Devices           | Partial  | Mobile apps, desktop clients                     |
+
+### 1.3 Out of Scope
+
+Nothing is explicitly out of scope for this threat model.
+
+---
+
+## 2. System Architecture
+
+### 2.1 Trust Boundaries
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    UNTRUSTED ZONE                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
+│  │  WhatsApp   │  │  Telegram   │  │   Discord   │  ...         │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
+│         │                │                │                      │
+└─────────┼────────────────┼────────────────┼──────────────────────┘
+          │                │                │
+          ▼                ▼                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 1: Channel Access                 │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                      GATEWAY                              │   │
+│  │  • Device Pairing (30s grace period)                      │   │
+│  │  • AllowFrom / AllowList validation                       │   │
+│  │  • Token/Password/Tailscale auth                          │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 2: Session Isolation              │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                   AGENT SESSIONS                          │   │
+│  │  • Session key = agent:channel:peer                       │   │
+│  │  • Tool policies per agent                                │   │
+│  │  • Transcript logging                                     │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 3: Tool Execution                 │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                  EXECUTION SANDBOX                        │   │
+│  │  • Docker sandbox OR Host (exec-approvals)                │   │
+│  │  • Node remote execution                                  │   │
+│  │  • SSRF protection (DNS pinning + IP blocking)            │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 4: External Content               │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │              FETCHED URLs / EMAILS / WEBHOOKS             │   │
+│  │  • External content wrapping (XML tags)                   │   │
+│  │  • Security notice injection                              │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 5: Supply Chain                   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                      CLAWHUB                              │   │
+│  │  • Skill publishing (semver, SKILL.md required)           │   │
+│  │  • Pattern-based moderation flags                         │   │
+│  │  • VirusTotal scanning (coming soon)                      │   │
+│  │  • GitHub account age verification                        │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 Data Flows
+
+| Flow | Source  | Destination | Data               | Protection           |
+| ---- | ------- | ----------- | ------------------ | -------------------- |
+| F1   | Channel | Gateway     | User messages      | TLS, AllowFrom       |
+| F2   | Gateway | Agent       | Routed messages    | Session isolation    |
+| F3   | Agent   | Tools       | Tool invocations   | Policy enforcement   |
+| F4   | Agent   | External    | web_fetch requests | SSRF blocking        |
+| F5   | ClawHub | Agent       | Skill code         | Moderation, scanning |
+| F6   | Agent   | Channel     | Responses          | Output filtering     |
+
+---
+
+## 3. Threat Analysis by ATLAS Tactic
+
+### 3.1 Reconnaissance (AML.TA0002)
+
+#### T-RECON-001: Agent Endpoint Discovery
+
+| Attribute               | Value                                                                |
+| ----------------------- | -------------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0006 - Active Scanning                                          |
+| **Description**         | Attacker scans for exposed OpenClaw gateway endpoints                |
+| **Attack Vector**       | Network scanning, shodan queries, DNS enumeration                    |
+| **Affected Components** | Gateway, exposed API endpoints                                       |
+| **Current Mitigations** | Tailscale auth option, bind to loopback by default                   |
+| **Residual Risk**       | Medium - Public gateways discoverable                                |
+| **Recommendations**     | Document secure deployment, add rate limiting on discovery endpoints |
+
+#### T-RECON-002: Channel Integration Probing
+
+| Attribute               | Value                                                              |
+| ----------------------- | ------------------------------------------------------------------ |
+| **ATLAS ID**            | AML.T0006 - Active Scanning                                        |
+| **Description**         | Attacker probes messaging channels to identify AI-managed accounts |
+| **Attack Vector**       | Sending test messages, observing response patterns                 |
+| **Affected Components** | All channel integrations                                           |
+| **Current Mitigations** | None specific                                                      |
+| **Residual Risk**       | Low - Limited value from discovery alone                           |
+| **Recommendations**     | Consider response timing randomization                             |
+
+---
+
+### 3.2 Initial Access (AML.TA0004)
+
+#### T-ACCESS-001: Pairing Code Interception
+
+| Attribute               | Value                                                    |
+| ----------------------- | -------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access                |
+| **Description**         | Attacker intercepts pairing code during 30s grace period |
+| **Attack Vector**       | Shoulder surfing, network sniffing, social engineering   |
+| **Affected Components** | Device pairing system                                    |
+| **Current Mitigations** | 30s expiry, codes sent via existing channel              |
+| **Residual Risk**       | Medium - Grace period exploitable                        |
+| **Recommendations**     | Reduce grace period, add confirmation step               |
+
+#### T-ACCESS-002: AllowFrom Spoofing
+
+| Attribute               | Value                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access                                      |
+| **Description**         | Attacker spoofs allowed sender identity in channel                             |
+| **Attack Vector**       | Depends on channel - phone number spoofing, username impersonation             |
+| **Affected Components** | AllowFrom validation per channel                                               |
+| **Current Mitigations** | Channel-specific identity verification                                         |
+| **Residual Risk**       | Medium - Some channels vulnerable to spoofing                                  |
+| **Recommendations**     | Document channel-specific risks, add cryptographic verification where possible |
+
+#### T-ACCESS-003: Token Theft
+
+| Attribute               | Value                                                       |
+| ----------------------- | ----------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access                   |
+| **Description**         | Attacker steals authentication tokens from config files     |
+| **Attack Vector**       | Malware, unauthorized device access, config backup exposure |
+| **Affected Components** | ~/.openclaw/credentials/, config storage                    |
+| **Current Mitigations** | File permissions                                            |
+| **Residual Risk**       | High - Tokens stored in plaintext                           |
+| **Recommendations**     | Implement token encryption at rest, add token rotation      |
+
+---
+
+### 3.3 Execution (AML.TA0005)
+
+#### T-EXEC-001: Direct Prompt Injection
+
+| Attribute               | Value                                                                                     |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0051.000 - LLM Prompt Injection: Direct                                              |
+| **Description**         | Attacker sends crafted prompts to manipulate agent behavior                               |
+| **Attack Vector**       | Channel messages containing adversarial instructions                                      |
+| **Affected Components** | Agent LLM, all input surfaces                                                             |
+| **Current Mitigations** | Pattern detection, external content wrapping                                              |
+| **Residual Risk**       | Critical - Detection only, no blocking; sophisticated attacks bypass                      |
+| **Recommendations**     | Implement multi-layer defense, output validation, user confirmation for sensitive actions |
+
+#### T-EXEC-002: Indirect Prompt Injection
+
+| Attribute               | Value                                                       |
+| ----------------------- | ----------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0051.001 - LLM Prompt Injection: Indirect              |
+| **Description**         | Attacker embeds malicious instructions in fetched content   |
+| **Attack Vector**       | Malicious URLs, poisoned emails, compromised webhooks       |
+| **Affected Components** | web_fetch, email ingestion, external data sources           |
+| **Current Mitigations** | Content wrapping with XML tags and security notice          |
+| **Residual Risk**       | High - LLM may ignore wrapper instructions                  |
+| **Recommendations**     | Implement content sanitization, separate execution contexts |
+
+#### T-EXEC-003: Tool Argument Injection
+
+| Attribute               | Value                                                        |
+| ----------------------- | ------------------------------------------------------------ |
+| **ATLAS ID**            | AML.T0051.000 - LLM Prompt Injection: Direct                 |
+| **Description**         | Attacker manipulates tool arguments through prompt injection |
+| **Attack Vector**       | Crafted prompts that influence tool parameter values         |
+| **Affected Components** | All tool invocations                                         |
+| **Current Mitigations** | Exec approvals for dangerous commands                        |
+| **Residual Risk**       | High - Relies on user judgment                               |
+| **Recommendations**     | Implement argument validation, parameterized tool calls      |
+
+#### T-EXEC-004: Exec Approval Bypass
+
+| Attribute               | Value                                                      |
+| ----------------------- | ---------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0043 - Craft Adversarial Data                         |
+| **Description**         | Attacker crafts commands that bypass approval allowlist    |
+| **Attack Vector**       | Command obfuscation, alias exploitation, path manipulation |
+| **Affected Components** | exec-approvals.ts, command allowlist                       |
+| **Current Mitigations** | Allowlist + ask mode                                       |
+| **Residual Risk**       | High - No command sanitization                             |
+| **Recommendations**     | Implement command normalization, expand blocklist          |
+
+---
+
+### 3.4 Persistence (AML.TA0006)
+
+#### T-PERSIST-001: Malicious Skill Installation
+
+| Attribute               | Value                                                                    |
+| ----------------------- | ------------------------------------------------------------------------ |
+| **ATLAS ID**            | AML.T0010.001 - Supply Chain Compromise: AI Software                     |
+| **Description**         | Attacker publishes malicious skill to ClawHub                            |
+| **Attack Vector**       | Create account, publish skill with hidden malicious code                 |
+| **Affected Components** | ClawHub, skill loading, agent execution                                  |
+| **Current Mitigations** | GitHub account age verification, pattern-based moderation flags          |
+| **Residual Risk**       | Critical - No sandboxing, limited review                                 |
+| **Recommendations**     | VirusTotal integration (in progress), skill sandboxing, community review |
+
+#### T-PERSIST-002: Skill Update Poisoning
+
+| Attribute               | Value                                                          |
+| ----------------------- | -------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0010.001 - Supply Chain Compromise: AI Software           |
+| **Description**         | Attacker compromises popular skill and pushes malicious update |
+| **Attack Vector**       | Account compromise, social engineering of skill owner          |
+| **Affected Components** | ClawHub versioning, auto-update flows                          |
+| **Current Mitigations** | Version fingerprinting                                         |
+| **Residual Risk**       | High - Auto-updates may pull malicious versions                |
+| **Recommendations**     | Implement update signing, rollback capability, version pinning |
+
+#### T-PERSIST-003: Agent Configuration Tampering
+
+| Attribute               | Value                                                           |
+| ----------------------- | --------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0010.002 - Supply Chain Compromise: Data                   |
+| **Description**         | Attacker modifies agent configuration to persist access         |
+| **Attack Vector**       | Config file modification, settings injection                    |
+| **Affected Components** | Agent config, tool policies                                     |
+| **Current Mitigations** | File permissions                                                |
+| **Residual Risk**       | Medium - Requires local access                                  |
+| **Recommendations**     | Config integrity verification, audit logging for config changes |
+
+---
+
+### 3.5 Defense Evasion (AML.TA0007)
+
+#### T-EVADE-001: Moderation Pattern Bypass
+
+| Attribute               | Value                                                                  |
+| ----------------------- | ---------------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0043 - Craft Adversarial Data                                     |
+| **Description**         | Attacker crafts skill content to evade moderation patterns             |
+| **Attack Vector**       | Unicode homoglyphs, encoding tricks, dynamic loading                   |
+| **Affected Components** | ClawHub moderation.ts                                                  |
+| **Current Mitigations** | Pattern-based FLAG_RULES                                               |
+| **Residual Risk**       | High - Simple regex easily bypassed                                    |
+| **Recommendations**     | Add behavioral analysis (VirusTotal Code Insight), AST-based detection |
+
+#### T-EVADE-002: Content Wrapper Escape
+
+| Attribute               | Value                                                     |
+| ----------------------- | --------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0043 - Craft Adversarial Data                        |
+| **Description**         | Attacker crafts content that escapes XML wrapper context  |
+| **Attack Vector**       | Tag manipulation, context confusion, instruction override |
+| **Affected Components** | External content wrapping                                 |
+| **Current Mitigations** | XML tags + security notice                                |
+| **Residual Risk**       | Medium - Novel escapes discovered regularly               |
+| **Recommendations**     | Multiple wrapper layers, output-side validation           |
+
+---
+
+### 3.6 Discovery (AML.TA0008)
+
+#### T-DISC-001: Tool Enumeration
+
+| Attribute               | Value                                                 |
+| ----------------------- | ----------------------------------------------------- |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access             |
+| **Description**         | Attacker enumerates available tools through prompting |
+| **Attack Vector**       | "What tools do you have?" style queries               |
+| **Affected Components** | Agent tool registry                                   |
+| **Current Mitigations** | None specific                                         |
+| **Residual Risk**       | Low - Tools generally documented                      |
+| **Recommendations**     | Consider tool visibility controls                     |
+
+#### T-DISC-002: Session Data Extraction
+
+| Attribute               | Value                                                 |
+| ----------------------- | ----------------------------------------------------- |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access             |
+| **Description**         | Attacker extracts sensitive data from session context |
+| **Attack Vector**       | "What did we discuss?" queries, context probing       |
+| **Affected Components** | Session transcripts, context window                   |
+| **Current Mitigations** | Session isolation per sender                          |
+| **Residual Risk**       | Medium - Within-session data accessible               |
+| **Recommendations**     | Implement sensitive data redaction in context         |
+
+---
+
+### 3.7 Collection & Exfiltration (AML.TA0009, AML.TA0010)
+
+#### T-EXFIL-001: Data Theft via web_fetch
+
+| Attribute               | Value                                                                  |
+| ----------------------- | ---------------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0009 - Collection                                                 |
+| **Description**         | Attacker exfiltrates data by instructing agent to send to external URL |
+| **Attack Vector**       | Prompt injection causing agent to POST data to attacker server         |
+| **Affected Components** | web_fetch tool                                                         |
+| **Current Mitigations** | SSRF blocking for internal networks                                    |
+| **Residual Risk**       | High - External URLs permitted                                         |
+| **Recommendations**     | Implement URL allowlisting, data classification awareness              |
+
+#### T-EXFIL-002: Unauthorized Message Sending
+
+| Attribute               | Value                                                            |
+| ----------------------- | ---------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0009 - Collection                                           |
+| **Description**         | Attacker causes agent to send messages containing sensitive data |
+| **Attack Vector**       | Prompt injection causing agent to message attacker               |
+| **Affected Components** | Message tool, channel integrations                               |
+| **Current Mitigations** | Outbound messaging gating                                        |
+| **Residual Risk**       | Medium - Gating may be bypassed                                  |
+| **Recommendations**     | Require explicit confirmation for new recipients                 |
+
+#### T-EXFIL-003: Credential Harvesting
+
+| Attribute               | Value                                                   |
+| ----------------------- | ------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0009 - Collection                                  |
+| **Description**         | Malicious skill harvests credentials from agent context |
+| **Attack Vector**       | Skill code reads environment variables, config files    |
+| **Affected Components** | Skill execution environment                             |
+| **Current Mitigations** | None specific to skills                                 |
+| **Residual Risk**       | Critical - Skills run with agent privileges             |
+| **Recommendations**     | Skill sandboxing, credential isolation                  |
+
+---
+
+### 3.8 Impact (AML.TA0011)
+
+#### T-IMPACT-001: Unauthorized Command Execution
+
+| Attribute               | Value                                               |
+| ----------------------- | --------------------------------------------------- |
+| **ATLAS ID**            | AML.T0031 - Erode AI Model Integrity                |
+| **Description**         | Attacker executes arbitrary commands on user system |
+| **Attack Vector**       | Prompt injection combined with exec approval bypass |
+| **Affected Components** | Bash tool, command execution                        |
+| **Current Mitigations** | Exec approvals, Docker sandbox option               |
+| **Residual Risk**       | Critical - Host execution without sandbox           |
+| **Recommendations**     | Default to sandbox, improve approval UX             |
+
+#### T-IMPACT-002: Resource Exhaustion (DoS)
+
+| Attribute               | Value                                              |
+| ----------------------- | -------------------------------------------------- |
+| **ATLAS ID**            | AML.T0031 - Erode AI Model Integrity               |
+| **Description**         | Attacker exhausts API credits or compute resources |
+| **Attack Vector**       | Automated message flooding, expensive tool calls   |
+| **Affected Components** | Gateway, agent sessions, API provider              |
+| **Current Mitigations** | None                                               |
+| **Residual Risk**       | High - No rate limiting                            |
+| **Recommendations**     | Implement per-sender rate limits, cost budgets     |
+
+#### T-IMPACT-003: Reputation Damage
+
+| Attribute               | Value                                                   |
+| ----------------------- | ------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0031 - Erode AI Model Integrity                    |
+| **Description**         | Attacker causes agent to send harmful/offensive content |
+| **Attack Vector**       | Prompt injection causing inappropriate responses        |
+| **Affected Components** | Output generation, channel messaging                    |
+| **Current Mitigations** | LLM provider content policies                           |
+| **Residual Risk**       | Medium - Provider filters imperfect                     |
+| **Recommendations**     | Output filtering layer, user controls                   |
+
+---
+
+## 4. ClawHub Supply Chain Analysis
+
+### 4.1 Current Security Controls
+
+| Control              | Implementation              | Effectiveness                                        |
+| -------------------- | --------------------------- | ---------------------------------------------------- |
+| GitHub Account Age   | `requireGitHubAccountAge()` | Medium - Raises bar for new attackers                |
+| Path Sanitization    | `sanitizePath()`            | High - Prevents path traversal                       |
+| File Type Validation | `isTextFile()`              | Medium - Only text files, but can still be malicious |
+| Size Limits          | 50MB total bundle           | High - Prevents resource exhaustion                  |
+| Required SKILL.md    | Mandatory readme            | Low security value - Informational only              |
+| Pattern Moderation   | FLAG_RULES in moderation.ts | Low - Easily bypassed                                |
+| Moderation Status    | `moderationStatus` field    | Medium - Manual review possible                      |
+
+### 4.2 Moderation Flag Patterns
+
+Current patterns in `moderation.ts`:
+
+```javascript
+// Known-bad identifiers
+/(keepcold131\/ClawdAuthenticatorTool|ClawdAuthenticatorTool)/i
+
+// Suspicious keywords
+/(malware|stealer|phish|phishing|keylogger)/i
+/(api[-_ ]?key|token|password|private key|secret)/i
+/(wallet|seed phrase|mnemonic|crypto)/i
+/(discord\.gg|webhook|hooks\.slack)/i
+/(curl[^\n]+\|\s*(sh|bash))/i
+/(bit\.ly|tinyurl\.com|t\.co|goo\.gl|is\.gd)/i
+```
+
+**Limitations:**
+
+- Only checks slug, displayName, summary, frontmatter, metadata, file paths
+- Does not analyze actual skill code content
+- Simple regex easily bypassed with obfuscation
+- No behavioral analysis
+
+### 4.3 Planned Improvements
+
+| Improvement            | Status                                | Impact                                                                |
+| ---------------------- | ------------------------------------- | --------------------------------------------------------------------- |
+| VirusTotal Integration | In Progress                           | High - Code Insight behavioral analysis                               |
+| Community Reporting    | Partial (`skillReports` table exists) | Medium                                                                |
+| Audit Logging          | Partial (`auditLogs` table exists)    | Medium                                                                |
+| Badge System           | Implemented                           | Medium - `highlighted`, `official`, `deprecated`, `redactionApproved` |
+
+---
+
+## 5. Risk Matrix
+
+### 5.1 Likelihood vs Impact
+
+| Threat ID     | Likelihood | Impact   | Risk Level   | Priority |
+| ------------- | ---------- | -------- | ------------ | -------- |
+| T-EXEC-001    | High       | Critical | **Critical** | P0       |
+| T-PERSIST-001 | High       | Critical | **Critical** | P0       |
+| T-EXFIL-003   | Medium     | Critical | **Critical** | P0       |
+| T-IMPACT-001  | Medium     | Critical | **High**     | P1       |
+| T-EXEC-002    | High       | High     | **High**     | P1       |
+| T-EXEC-004    | Medium     | High     | **High**     | P1       |
+| T-ACCESS-003  | Medium     | High     | **High**     | P1       |
+| T-EXFIL-001   | Medium     | High     | **High**     | P1       |
+| T-IMPACT-002  | High       | Medium   | **High**     | P1       |
+| T-EVADE-001   | High       | Medium   | **Medium**   | P2       |
+| T-ACCESS-001  | Low        | High     | **Medium**   | P2       |
+| T-ACCESS-002  | Low        | High     | **Medium**   | P2       |
+| T-PERSIST-002 | Low        | High     | **Medium**   | P2       |
+
+### 5.2 Critical Path Attack Chains
+
+**Attack Chain 1: Skill-Based Data Theft**
+
+```
+T-PERSIST-001 → T-EVADE-001 → T-EXFIL-003
+(Publish malicious skill) → (Evade moderation) → (Harvest credentials)
+```
+
+**Attack Chain 2: Prompt Injection to RCE**
+
+```
+T-EXEC-001 → T-EXEC-004 → T-IMPACT-001
+(Inject prompt) → (Bypass exec approval) → (Execute commands)
+```
+
+**Attack Chain 3: Indirect Injection via Fetched Content**
+
+```
+T-EXEC-002 → T-EXFIL-001 → External exfiltration
+(Poison URL content) → (Agent fetches & follows instructions) → (Data sent to attacker)
+```
+
+---
+
+## 6. Recommendations Summary
+
+### 6.1 Immediate (P0)
+
+| ID    | Recommendation                              | Addresses                  |
+| ----- | ------------------------------------------- | -------------------------- |
+| R-001 | Complete VirusTotal integration             | T-PERSIST-001, T-EVADE-001 |
+| R-002 | Implement skill sandboxing                  | T-PERSIST-001, T-EXFIL-003 |
+| R-003 | Add output validation for sensitive actions | T-EXEC-001, T-EXEC-002     |
+
+### 6.2 Short-term (P1)
+
+| ID    | Recommendation                           | Addresses    |
+| ----- | ---------------------------------------- | ------------ |
+| R-004 | Implement rate limiting                  | T-IMPACT-002 |
+| R-005 | Add token encryption at rest             | T-ACCESS-003 |
+| R-006 | Improve exec approval UX and validation  | T-EXEC-004   |
+| R-007 | Implement URL allowlisting for web_fetch | T-EXFIL-001  |
+
+### 6.3 Medium-term (P2)
+
+| ID    | Recommendation                                        | Addresses     |
+| ----- | ----------------------------------------------------- | ------------- |
+| R-008 | Add cryptographic channel verification where possible | T-ACCESS-002  |
+| R-009 | Implement config integrity verification               | T-PERSIST-003 |
+| R-010 | Add update signing and version pinning                | T-PERSIST-002 |
+
+---
+
+## 7. Appendices
+
+### 7.1 ATLAS Technique Mapping
+
+| ATLAS ID      | Technique Name                 | OpenClaw Threats                                                 |
+| ------------- | ------------------------------ | ---------------------------------------------------------------- |
+| AML.T0006     | Active Scanning                | T-RECON-001, T-RECON-002                                         |
+| AML.T0009     | Collection                     | T-EXFIL-001, T-EXFIL-002, T-EXFIL-003                            |
+| AML.T0010.001 | Supply Chain: AI Software      | T-PERSIST-001, T-PERSIST-002                                     |
+| AML.T0010.002 | Supply Chain: Data             | T-PERSIST-003                                                    |
+| AML.T0031     | Erode AI Model Integrity       | T-IMPACT-001, T-IMPACT-002, T-IMPACT-003                         |
+| AML.T0040     | AI Model Inference API Access  | T-ACCESS-001, T-ACCESS-002, T-ACCESS-003, T-DISC-001, T-DISC-002 |
+| AML.T0043     | Craft Adversarial Data         | T-EXEC-004, T-EVADE-001, T-EVADE-002                             |
+| AML.T0051.000 | LLM Prompt Injection: Direct   | T-EXEC-001, T-EXEC-003                                           |
+| AML.T0051.001 | LLM Prompt Injection: Indirect | T-EXEC-002                                                       |
+
+### 7.2 Key Security Files
+
+| Path                                | Purpose                     | Risk Level   |
+| ----------------------------------- | --------------------------- | ------------ |
+| `src/infra/exec-approvals.ts`       | Command approval logic      | **Critical** |
+| `src/gateway/auth.ts`               | Gateway authentication      | **Critical** |
+| `src/web/inbound/access-control.ts` | Channel access control      | **Critical** |
+| `src/infra/net/ssrf.ts`             | SSRF protection             | **Critical** |
+| `src/security/external-content.ts`  | Prompt injection mitigation | **Critical** |
+| `src/agents/sandbox/tool-policy.ts` | Tool policy enforcement     | **Critical** |
+| `convex/lib/moderation.ts`          | ClawHub moderation          | **High**     |
+| `convex/lib/skillPublish.ts`        | Skill publishing flow       | **High**     |
+| `src/routing/resolve-route.ts`      | Session isolation           | **Medium**   |
+
+### 7.3 Glossary
+
+| Term                 | Definition                                                |
+| -------------------- | --------------------------------------------------------- |
+| **ATLAS**            | MITRE's Adversarial Threat Landscape for AI Systems       |
+| **ClawHub**          | OpenClaw's skill marketplace                              |
+| **Gateway**          | OpenClaw's message routing and authentication layer       |
+| **MCP**              | Model Context Protocol - tool provider interface          |
+| **Prompt Injection** | Attack where malicious instructions are embedded in input |
+| **Skill**            | Downloadable extension for OpenClaw agents                |
+| **SSRF**             | Server-Side Request Forgery                               |
+
+---
+
+_This threat model is a living document. Report security issues to security@openclaw.ai_

docs/start/getting-started.md

@@ -96,6 +96,16 @@ If the Control UI loads, your Gateway is ready for use.
   </Accordion>
 </AccordionGroup>
 
+## Useful environment variables
+
+If you run OpenClaw as a service account or want custom config/state locations:
+
+- `OPENCLAW_HOME` sets the home directory used for internal path resolution.
+- `OPENCLAW_STATE_DIR` overrides the state directory.
+- `OPENCLAW_CONFIG_PATH` overrides the config file path.
+
+Full environment variable reference: [Environment vars](/help/environment).
+
 ## Go deeper
 
 <Columns>

docs/tools/index.md

@@ -406,7 +406,7 @@ Core actions:
 Notes:
 
 - `add` expects a full cron job object (same schema as `cron.add` RPC).
-- `update` uses `{ id, patch }`.
+- `update` uses `{ jobId, patch }` (`id` accepted for compatibility).
 
 ### `gateway`
 

docs/zh-CN/refactor/plugin-sdk.md

@@ -79,7 +79,7 @@ export type PluginRuntime = {
         cfg: unknown;
         channel: string;
         accountId: string;
-        peer: { kind: "dm" | "group" | "channel"; id: string };
+        peer: { kind: RoutePeerKind; id: string };
       }): { sessionKey: string; accountId: string };
     };
     pairing: {

extensions/bluebubbles/src/monitor.ts

@@ -1804,7 +1804,7 @@ async function processMessage(
     channel: "bluebubbles",
     accountId: account.accountId,
     peer: {
-      kind: isGroup ? "group" : "dm",
+      kind: isGroup ? "group" : "direct",
       id: peerId,
     },
   });
@@ -2442,7 +2442,7 @@ async function processReaction(
     channel: "bluebubbles",
     accountId: account.accountId,
     peer: {
-      kind: reaction.isGroup ? "group" : "dm",
+      kind: reaction.isGroup ? "group" : "direct",
       id: peerId,
     },
   });

extensions/bluebubbles/src/types.ts

@@ -1,5 +1,4 @@
-export type DmPolicy = "pairing" | "allowlist" | "open" | "disabled";
-export type GroupPolicy = "open" | "disabled" | "allowlist";
+export type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk";
 
 export type BlueBubblesGroupConfig = {
   /** If true, only respond in this group when mentioned. */

extensions/device-pair/index.ts

@@ -0,0 +1,497 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import os from "node:os";
+import { approveDevicePairing, listDevicePairing } from "openclaw/plugin-sdk";
+
+const DEFAULT_GATEWAY_PORT = 18789;
+
+type DevicePairPluginConfig = {
+  publicUrl?: string;
+};
+
+type SetupPayload = {
+  url: string;
+  token?: string;
+  password?: string;
+};
+
+type ResolveUrlResult = {
+  url?: string;
+  source?: string;
+  error?: string;
+};
+
+type ResolveAuthResult = {
+  token?: string;
+  password?: string;
+  label?: string;
+  error?: string;
+};
+
+function normalizeUrl(raw: string, schemeFallback: "ws" | "wss"): string | null {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    const scheme = parsed.protocol.replace(":", "");
+    if (!scheme) {
+      return null;
+    }
+    const resolvedScheme = scheme === "http" ? "ws" : scheme === "https" ? "wss" : scheme;
+    if (resolvedScheme !== "ws" && resolvedScheme !== "wss") {
+      return null;
+    }
+    const host = parsed.hostname;
+    if (!host) {
+      return null;
+    }
+    const port = parsed.port ? `:${parsed.port}` : "";
+    return `${resolvedScheme}://${host}${port}`;
+  } catch {
+    // Fall through to host:port parsing.
+  }
+
+  const withoutPath = trimmed.split("/")[0] ?? "";
+  if (!withoutPath) {
+    return null;
+  }
+  return `${schemeFallback}://${withoutPath}`;
+}
+
+function resolveGatewayPort(cfg: OpenClawPluginApi["config"]): number {
+  const envRaw =
+    process.env.OPENCLAW_GATEWAY_PORT?.trim() || process.env.CLAWDBOT_GATEWAY_PORT?.trim();
+  if (envRaw) {
+    const parsed = Number.parseInt(envRaw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  const configPort = cfg.gateway?.port;
+  if (typeof configPort === "number" && Number.isFinite(configPort) && configPort > 0) {
+    return configPort;
+  }
+  return DEFAULT_GATEWAY_PORT;
+}
+
+function resolveScheme(
+  cfg: OpenClawPluginApi["config"],
+  opts?: { forceSecure?: boolean },
+): "ws" | "wss" {
+  if (opts?.forceSecure) {
+    return "wss";
+  }
+  return cfg.gateway?.tls?.enabled === true ? "wss" : "ws";
+}
+
+function isPrivateIPv4(address: string): boolean {
+  const parts = address.split(".");
+  if (parts.length != 4) {
+    return false;
+  }
+  const octets = parts.map((part) => Number.parseInt(part, 10));
+  if (octets.some((value) => !Number.isFinite(value) || value < 0 || value > 255)) {
+    return false;
+  }
+  const [a, b] = octets;
+  if (a === 10) {
+    return true;
+  }
+  if (a === 172 && b >= 16 && b <= 31) {
+    return true;
+  }
+  if (a === 192 && b === 168) {
+    return true;
+  }
+  return false;
+}
+
+function isTailnetIPv4(address: string): boolean {
+  const parts = address.split(".");
+  if (parts.length !== 4) {
+    return false;
+  }
+  const octets = parts.map((part) => Number.parseInt(part, 10));
+  if (octets.some((value) => !Number.isFinite(value) || value < 0 || value > 255)) {
+    return false;
+  }
+  const [a, b] = octets;
+  return a === 100 && b >= 64 && b <= 127;
+}
+
+function pickLanIPv4(): string | null {
+  const nets = os.networkInterfaces();
+  for (const entries of Object.values(nets)) {
+    if (!entries) {
+      continue;
+    }
+    for (const entry of entries) {
+      const family = entry?.family;
+      const isIpv4 = family === "IPv4" || family === 4;
+      if (!entry || entry.internal || !isIpv4) {
+        continue;
+      }
+      const address = entry.address?.trim() ?? "";
+      if (!address) {
+        continue;
+      }
+      if (isPrivateIPv4(address)) {
+        return address;
+      }
+    }
+  }
+  return null;
+}
+
+function pickTailnetIPv4(): string | null {
+  const nets = os.networkInterfaces();
+  for (const entries of Object.values(nets)) {
+    if (!entries) {
+      continue;
+    }
+    for (const entry of entries) {
+      const family = entry?.family;
+      const isIpv4 = family === "IPv4" || family === 4;
+      if (!entry || entry.internal || !isIpv4) {
+        continue;
+      }
+      const address = entry.address?.trim() ?? "";
+      if (!address) {
+        continue;
+      }
+      if (isTailnetIPv4(address)) {
+        return address;
+      }
+    }
+  }
+  return null;
+}
+
+async function resolveTailnetHost(api: OpenClawPluginApi): Promise<string | null> {
+  const candidates = ["tailscale", "/Applications/Tailscale.app/Contents/MacOS/Tailscale"];
+  for (const candidate of candidates) {
+    try {
+      const result = await api.runtime.system.runCommandWithTimeout(
+        [candidate, "status", "--json"],
+        {
+          timeoutMs: 5000,
+        },
+      );
+      if (result.code !== 0) {
+        continue;
+      }
+      const raw = result.stdout.trim();
+      if (!raw) {
+        continue;
+      }
+      const parsed = parsePossiblyNoisyJsonObject(raw);
+      const self =
+        typeof parsed.Self === "object" && parsed.Self !== null
+          ? (parsed.Self as Record<string, unknown>)
+          : undefined;
+      const dns = typeof self?.DNSName === "string" ? self.DNSName : undefined;
+      if (dns && dns.length > 0) {
+        return dns.replace(/\.$/, "");
+      }
+      const ips = Array.isArray(self?.TailscaleIPs) ? (self?.TailscaleIPs as string[]) : [];
+      if (ips.length > 0) {
+        return ips[0] ?? null;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function parsePossiblyNoisyJsonObject(raw: string): Record<string, unknown> {
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start === -1 || end <= start) {
+    return {};
+  }
+  try {
+    return JSON.parse(raw.slice(start, end + 1)) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+function resolveAuth(cfg: OpenClawPluginApi["config"]): ResolveAuthResult {
+  const mode = cfg.gateway?.auth?.mode;
+  const token =
+    process.env.OPENCLAW_GATEWAY_TOKEN?.trim() ||
+    process.env.CLAWDBOT_GATEWAY_TOKEN?.trim() ||
+    cfg.gateway?.auth?.token?.trim();
+  const password =
+    process.env.OPENCLAW_GATEWAY_PASSWORD?.trim() ||
+    process.env.CLAWDBOT_GATEWAY_PASSWORD?.trim() ||
+    cfg.gateway?.auth?.password?.trim();
+
+  if (mode === "password") {
+    if (!password) {
+      return { error: "Gateway auth is set to password, but no password is configured." };
+    }
+    return { password, label: "password" };
+  }
+  if (mode === "token") {
+    if (!token) {
+      return { error: "Gateway auth is set to token, but no token is configured." };
+    }
+    return { token, label: "token" };
+  }
+  if (token) {
+    return { token, label: "token" };
+  }
+  if (password) {
+    return { password, label: "password" };
+  }
+  return { error: "Gateway auth is not configured (no token or password)." };
+}
+
+async function resolveGatewayUrl(api: OpenClawPluginApi): Promise<ResolveUrlResult> {
+  const cfg = api.config;
+  const pluginCfg = (api.pluginConfig ?? {}) as DevicePairPluginConfig;
+  const scheme = resolveScheme(cfg);
+  const port = resolveGatewayPort(cfg);
+
+  if (typeof pluginCfg.publicUrl === "string" && pluginCfg.publicUrl.trim()) {
+    const url = normalizeUrl(pluginCfg.publicUrl, scheme);
+    if (url) {
+      return { url, source: "plugins.entries.device-pair.config.publicUrl" };
+    }
+    return { error: "Configured publicUrl is invalid." };
+  }
+
+  const tailscaleMode = cfg.gateway?.tailscale?.mode ?? "off";
+  if (tailscaleMode === "serve" || tailscaleMode === "funnel") {
+    const host = await resolveTailnetHost(api);
+    if (!host) {
+      return { error: "Tailscale Serve is enabled, but MagicDNS could not be resolved." };
+    }
+    return { url: `wss://${host}`, source: `gateway.tailscale.mode=${tailscaleMode}` };
+  }
+
+  const remoteUrl = cfg.gateway?.remote?.url;
+  if (typeof remoteUrl === "string" && remoteUrl.trim()) {
+    const url = normalizeUrl(remoteUrl, scheme);
+    if (url) {
+      return { url, source: "gateway.remote.url" };
+    }
+  }
+
+  const bind = cfg.gateway?.bind ?? "loopback";
+  if (bind === "custom") {
+    const host = cfg.gateway?.customBindHost?.trim();
+    if (host) {
+      return { url: `${scheme}://${host}:${port}`, source: "gateway.bind=custom" };
+    }
+    return { error: "gateway.bind=custom requires gateway.customBindHost." };
+  }
+
+  if (bind === "tailnet") {
+    const host = pickTailnetIPv4();
+    if (host) {
+      return { url: `${scheme}://${host}:${port}`, source: "gateway.bind=tailnet" };
+    }
+    return { error: "gateway.bind=tailnet set, but no tailnet IP was found." };
+  }
+
+  if (bind === "lan") {
+    const host = pickLanIPv4();
+    if (host) {
+      return { url: `${scheme}://${host}:${port}`, source: "gateway.bind=lan" };
+    }
+    return { error: "gateway.bind=lan set, but no private LAN IP was found." };
+  }
+
+  return {
+    error:
+      "Gateway is only bound to loopback. Set gateway.bind=lan, enable tailscale serve, or configure plugins.entries.device-pair.config.publicUrl.",
+  };
+}
+
+function encodeSetupCode(payload: SetupPayload): string {
+  const json = JSON.stringify(payload);
+  const base64 = Buffer.from(json, "utf8").toString("base64");
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function formatSetupReply(payload: SetupPayload, authLabel: string): string {
+  const setupCode = encodeSetupCode(payload);
+  return [
+    "Pairing setup code generated.",
+    "",
+    "1) Open the iOS app → Settings → Gateway",
+    "2) Paste the setup code below and tap Connect",
+    "3) Back here, run /pair approve",
+    "",
+    "Setup code:",
+    setupCode,
+    "",
+    `Gateway: ${payload.url}`,
+    `Auth: ${authLabel}`,
+  ].join("\n");
+}
+
+function formatSetupInstructions(): string {
+  return [
+    "Pairing setup code generated.",
+    "",
+    "1) Open the iOS app → Settings → Gateway",
+    "2) Paste the setup code from my next message and tap Connect",
+    "3) Back here, run /pair approve",
+  ].join("\n");
+}
+
+type PendingPairingRequest = {
+  requestId: string;
+  deviceId: string;
+  displayName?: string;
+  platform?: string;
+  remoteIp?: string;
+  ts?: number;
+};
+
+function formatPendingRequests(pending: PendingPairingRequest[]): string {
+  if (pending.length === 0) {
+    return "No pending device pairing requests.";
+  }
+  const lines: string[] = ["Pending device pairing requests:"];
+  for (const req of pending) {
+    const label = req.displayName?.trim() || req.deviceId;
+    const platform = req.platform?.trim();
+    const ip = req.remoteIp?.trim();
+    const parts = [
+      `- ${req.requestId}`,
+      label ? `name=${label}` : null,
+      platform ? `platform=${platform}` : null,
+      ip ? `ip=${ip}` : null,
+    ].filter(Boolean);
+    lines.push(parts.join(" · "));
+  }
+  return lines.join("\n");
+}
+
+export default function register(api: OpenClawPluginApi) {
+  api.registerCommand({
+    name: "pair",
+    description: "Generate setup codes and approve device pairing requests.",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const args = ctx.args?.trim() ?? "";
+      const tokens = args.split(/\s+/).filter(Boolean);
+      const action = tokens[0]?.toLowerCase() ?? "";
+      api.logger.info?.(
+        `device-pair: /pair invoked channel=${ctx.channel} sender=${ctx.senderId ?? "unknown"} action=${
+          action || "new"
+        }`,
+      );
+
+      if (action === "status" || action === "pending") {
+        const list = await listDevicePairing();
+        return { text: formatPendingRequests(list.pending) };
+      }
+
+      if (action === "approve") {
+        const requested = tokens[1]?.trim();
+        const list = await listDevicePairing();
+        if (list.pending.length === 0) {
+          return { text: "No pending device pairing requests." };
+        }
+
+        let pending: (typeof list.pending)[number] | undefined;
+        if (requested) {
+          if (requested.toLowerCase() === "latest") {
+            pending = [...list.pending].toSorted((a, b) => (b.ts ?? 0) - (a.ts ?? 0))[0];
+          } else {
+            pending = list.pending.find((entry) => entry.requestId === requested);
+          }
+        } else if (list.pending.length === 1) {
+          pending = list.pending[0];
+        } else {
+          return {
+            text:
+              `${formatPendingRequests(list.pending)}\n\n` +
+              "Multiple pending requests found. Approve one explicitly:\n" +
+              "/pair approve <requestId>\n" +
+              "Or approve the most recent:\n" +
+              "/pair approve latest",
+          };
+        }
+        if (!pending) {
+          return { text: "Pairing request not found." };
+        }
+        const approved = await approveDevicePairing(pending.requestId);
+        if (!approved) {
+          return { text: "Pairing request not found." };
+        }
+        const label = approved.device.displayName?.trim() || approved.device.deviceId;
+        const platform = approved.device.platform?.trim();
+        const platformLabel = platform ? ` (${platform})` : "";
+        return { text: `✅ Paired ${label}${platformLabel}.` };
+      }
+
+      const auth = resolveAuth(api.config);
+      if (auth.error) {
+        return { text: `Error: ${auth.error}` };
+      }
+
+      const urlResult = await resolveGatewayUrl(api);
+      if (!urlResult.url) {
+        return { text: `Error: ${urlResult.error ?? "Gateway URL unavailable."}` };
+      }
+
+      const payload: SetupPayload = {
+        url: urlResult.url,
+        token: auth.token,
+        password: auth.password,
+      };
+
+      const channel = ctx.channel;
+      const target = ctx.senderId?.trim() || ctx.from?.trim() || ctx.to?.trim() || "";
+      const authLabel = auth.label ?? "auth";
+
+      if (channel === "telegram" && target) {
+        try {
+          const runtimeKeys = Object.keys(api.runtime ?? {});
+          const channelKeys = Object.keys(api.runtime?.channel ?? {});
+          api.logger.debug?.(
+            `device-pair: runtime keys=${runtimeKeys.join(",") || "none"} channel keys=${
+              channelKeys.join(",") || "none"
+            }`,
+          );
+          const send = api.runtime?.channel?.telegram?.sendMessageTelegram;
+          if (!send) {
+            throw new Error(
+              `telegram runtime unavailable (runtime keys: ${runtimeKeys.join(",")}; channel keys: ${channelKeys.join(
+                ",",
+              )})`,
+            );
+          }
+          await send(target, formatSetupInstructions(), {
+            ...(ctx.messageThreadId != null ? { messageThreadId: ctx.messageThreadId } : {}),
+            ...(ctx.accountId ? { accountId: ctx.accountId } : {}),
+          });
+          api.logger.info?.(
+            `device-pair: telegram split send ok target=${target} account=${ctx.accountId ?? "none"} thread=${
+              ctx.messageThreadId ?? "none"
+            }`,
+          );
+          return { text: encodeSetupCode(payload) };
+        } catch (err) {
+          api.logger.warn?.(
+            `device-pair: telegram split send failed, falling back to single message (${String(
+              (err as Error)?.message ?? err,
+            )})`,
+          );
+        }
+      }
+
+      return {
+        text: formatSetupReply(payload, authLabel),
+      };
+    },
+  });
+}

extensions/device-pair/openclaw.plugin.json

@@ -0,0 +1,20 @@
+{
+  "id": "device-pair",
+  "name": "Device Pairing",
+  "description": "Generate setup codes and approve device pairing requests.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "publicUrl": {
+        "type": "string"
+      }
+    }
+  },
+  "uiHints": {
+    "publicUrl": {
+      "label": "Gateway URL",
+      "help": "Public WebSocket URL used for /pair setup codes (ws/wss or http/https)."
+    }
+  }
+}

extensions/feishu/src/bot.ts

@@ -652,7 +652,7 @@ export async function handleFeishuMessage(params: {
       channel: "feishu",
       accountId: account.accountId,
       peer: {
-        kind: isGroup ? "group" : "dm",
+        kind: isGroup ? "group" : "direct",
         id: isGroup ? ctx.chatId : ctx.senderOpenId,
       },
     });

extensions/googlechat/src/monitor.ts

@@ -615,7 +615,7 @@ async function processMessageWithPipeline(params: {
     channel: "googlechat",
     accountId: account.accountId,
     peer: {
-      kind: isGroup ? "group" : "dm",
+      kind: isGroup ? "group" : "direct",
       id: spaceId,
     },
   });

extensions/matrix/src/matrix/monitor/handler.ts

@@ -453,7 +453,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         cfg,
         channel: "matrix",
         peer: {
-          kind: isDirectMessage ? "dm" : "channel",
+          kind: isDirectMessage ? "direct" : "channel",
           id: isDirectMessage ? senderId : roomId,
         },
       });

extensions/matrix/src/onboarding.ts

@@ -1,3 +1,4 @@
+import type { DmPolicy } from "openclaw/plugin-sdk";
 import {
   addWildcardAllowFrom,
   formatDocsLink,
@@ -6,7 +7,7 @@ import {
   type ChannelOnboardingDmPolicy,
   type WizardPrompter,
 } from "openclaw/plugin-sdk";
-import type { CoreConfig, DmPolicy } from "./types.js";
+import type { CoreConfig } from "./types.js";
 import { listMatrixDirectoryGroupsLive } from "./directory-live.js";
 import { resolveMatrixAccount } from "./matrix/accounts.js";
 import { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./matrix/deps.js";

extensions/matrix/src/types.ts

@@ -1,6 +1,6 @@
+export type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk";
+
 export type ReplyToMode = "off" | "first" | "all";
-export type GroupPolicy = "open" | "disabled" | "allowlist";
-export type DmPolicy = "pairing" | "allowlist" | "open" | "disabled";
 
 export type MatrixDmConfig = {
   /** If false, ignore all incoming Matrix DMs. Default: true. */

extensions/mattermost/src/mattermost/monitor.ts

@@ -1,5 +1,6 @@
 import type {
   ChannelAccountSnapshot,
+  ChatType,
   OpenClawConfig,
   ReplyPayload,
   RuntimeEnv,
@@ -131,13 +132,13 @@ function isSystemPost(post: MattermostPost): boolean {
   return Boolean(type);
 }
 
-function channelKind(channelType?: string | null): "dm" | "group" | "channel" {
+function channelKind(channelType?: string | null): ChatType {
   if (!channelType) {
     return "channel";
   }
   const normalized = channelType.trim().toUpperCase();
   if (normalized === "D") {
-    return "dm";
+    return "direct";
   }
   if (normalized === "G") {
     return "group";
@@ -145,8 +146,8 @@ function channelKind(channelType?: string | null): "dm" | "group" | "channel" {
   return "channel";
 }
 
-function channelChatType(kind: "dm" | "group" | "channel"): "direct" | "group" | "channel" {
-  if (kind === "dm") {
+function channelChatType(kind: ChatType): "direct" | "group" | "channel" {
+  if (kind === "direct") {
     return "direct";
   }
   if (kind === "group") {
@@ -469,11 +470,11 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       hasControlCommand,
     });
     const commandAuthorized =
-      kind === "dm"
+      kind === "direct"
         ? dmPolicy === "open" || senderAllowedForCommands
         : commandGate.commandAuthorized;
 
-    if (kind === "dm") {
+    if (kind === "direct") {
       if (dmPolicy === "disabled") {
         logVerboseMessage(`mattermost: drop dm (dmPolicy=disabled sender=${senderId})`);
         return;
@@ -524,7 +525,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       }
     }
 
-    if (kind !== "dm" && commandGate.shouldBlock) {
+    if (kind !== "direct" && commandGate.shouldBlock) {
       logInboundDrop({
         log: logVerboseMessage,
         channel: "mattermost",
@@ -547,7 +548,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       teamId,
       peer: {
         kind,
-        id: kind === "dm" ? senderId : channelId,
+        id: kind === "direct" ? senderId : channelId,
       },
     });
 
@@ -559,11 +560,11 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       parentSessionKey: threadRootId ? baseSessionKey : undefined,
     });
     const sessionKey = threadKeys.sessionKey;
-    const historyKey = kind === "dm" ? null : sessionKey;
+    const historyKey = kind === "direct" ? null : sessionKey;
 
     const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg, route.agentId);
     const wasMentioned =
-      kind !== "dm" &&
+      kind !== "direct" &&
       ((botUsername ? rawText.toLowerCase().includes(`@${botUsername.toLowerCase()}`) : false) ||
         core.channel.mentions.matchesMentionPatterns(rawText, mentionRegexes));
     const pendingBody =
@@ -590,7 +591,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       });
     };
 
-    const oncharEnabled = account.chatmode === "onchar" && kind !== "dm";
+    const oncharEnabled = account.chatmode === "onchar" && kind !== "direct";
     const oncharPrefixes = oncharEnabled ? resolveOncharPrefixes(account.oncharPrefixes) : [];
     const oncharResult = oncharEnabled
       ? stripOncharPrefix(rawText, oncharPrefixes)
@@ -598,7 +599,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
     const oncharTriggered = oncharResult.triggered;
 
     const shouldRequireMention =
-      kind !== "dm" &&
+      kind !== "direct" &&
       core.channel.groups.resolveRequireMention({
         cfg,
         channel: "mattermost",
@@ -615,7 +616,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       return;
     }
 
-    if (kind !== "dm" && shouldRequireMention && canDetectMention) {
+    if (kind !== "direct" && shouldRequireMention && canDetectMention) {
       if (!effectiveWasMentioned) {
         recordPendingHistory();
         return;
@@ -637,7 +638,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
     });
 
     const fromLabel = formatInboundFromLabel({
-      isGroup: kind !== "dm",
+      isGroup: kind !== "direct",
       groupLabel: channelDisplay || roomLabel,
       groupId: channelId,
       groupFallback: roomLabel || "Channel",
@@ -647,7 +648,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
 
     const preview = bodyText.replace(/\s+/g, " ").slice(0, 160);
     const inboundLabel =
-      kind === "dm"
+      kind === "direct"
         ? `Mattermost DM from ${senderName}`
         : `Mattermost message in ${roomLabel} from ${senderName}`;
     core.system.enqueueSystemEvent(`${inboundLabel}: ${preview}`, {
@@ -685,14 +686,14 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       });
     }
 
-    const to = kind === "dm" ? `user:${senderId}` : `channel:${channelId}`;
+    const to = kind === "direct" ? `user:${senderId}` : `channel:${channelId}`;
     const mediaPayload = buildMattermostMediaPayload(mediaList);
     const ctxPayload = core.channel.reply.finalizeInboundContext({
       Body: combinedBody,
       RawBody: bodyText,
       CommandBody: bodyText,
       From:
-        kind === "dm"
+        kind === "direct"
           ? `mattermost:${senderId}`
           : kind === "group"
             ? `mattermost:group:${channelId}`
@@ -703,7 +704,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       AccountId: route.accountId,
       ChatType: chatType,
       ConversationLabel: fromLabel,
-      GroupSubject: kind !== "dm" ? channelDisplay || roomLabel : undefined,
+      GroupSubject: kind !== "direct" ? channelDisplay || roomLabel : undefined,
       GroupChannel: channelName ? `#${channelName}` : undefined,
       GroupSpace: teamId,
       SenderName: senderName,
@@ -718,14 +719,14 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
       ReplyToId: threadRootId,
       MessageThreadId: threadRootId,
       Timestamp: typeof post.create_at === "number" ? post.create_at : undefined,
-      WasMentioned: kind !== "dm" ? effectiveWasMentioned : undefined,
+      WasMentioned: kind !== "direct" ? effectiveWasMentioned : undefined,
       CommandAuthorized: commandAuthorized,
       OriginatingChannel: "mattermost" as const,
       OriginatingTo: to,
       ...mediaPayload,
     });
 
-    if (kind === "dm") {
+    if (kind === "direct") {
       const sessionCfg = cfg.session;
       const storePath = core.channel.session.resolveStorePath(sessionCfg?.store, {
         agentId: route.agentId,

extensions/msteams/package.json

@@ -8,7 +8,6 @@
     "@microsoft/agents-hosting-express": "^1.2.3",
     "@microsoft/agents-hosting-extensions-teams": "^1.2.3",
     "express": "^5.2.1",
-    "openclaw": "workspace:*",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {

extensions/msteams/src/monitor-handler/message-handler.ts

@@ -342,7 +342,7 @@ export function createMSTeamsMessageHandler(deps: MSTeamsMessageHandlerDeps) {
       cfg,
       channel: "msteams",
       peer: {
-        kind: isDirectMessage ? "dm" : isChannel ? "channel" : "group",
+        kind: isDirectMessage ? "direct" : isChannel ? "channel" : "group",
         id: isDirectMessage ? senderId : conversationId,
       },
     });

extensions/nextcloud-talk/src/inbound.ts

@@ -228,7 +228,7 @@ export async function handleNextcloudTalkInbound(params: {
     channel: CHANNEL_ID,
     accountId: account.accountId,
     peer: {
-      kind: isGroup ? "group" : "dm",
+      kind: isGroup ? "group" : "direct",
       id: isGroup ? roomToken : senderId,
     },
   });

extensions/nostr/package.json

@@ -5,7 +5,6 @@
   "type": "module",
   "dependencies": {
     "nostr-tools": "^2.23.0",
-    "openclaw": "workspace:*",
     "zod": "^4.3.6"
   },
   "devDependencies": {

extensions/phone-control/index.ts

@@ -0,0 +1,420 @@
+import type { OpenClawPluginApi, OpenClawPluginService } from "openclaw/plugin-sdk";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+type ArmGroup = "camera" | "screen" | "writes" | "all";
+
+type ArmStateFileV1 = {
+  version: 1;
+  armedAtMs: number;
+  expiresAtMs: number | null;
+  removedFromDeny: string[];
+};
+
+type ArmStateFileV2 = {
+  version: 2;
+  armedAtMs: number;
+  expiresAtMs: number | null;
+  group: ArmGroup;
+  armedCommands: string[];
+  addedToAllow: string[];
+  removedFromDeny: string[];
+};
+
+type ArmStateFile = ArmStateFileV1 | ArmStateFileV2;
+
+const STATE_VERSION = 2;
+const STATE_REL_PATH = ["plugins", "phone-control", "armed.json"] as const;
+
+const GROUP_COMMANDS: Record<Exclude<ArmGroup, "all">, string[]> = {
+  camera: ["camera.snap", "camera.clip"],
+  screen: ["screen.record"],
+  writes: ["calendar.add", "contacts.add", "reminders.add"],
+};
+
+function uniqSorted(values: string[]): string[] {
+  return [...new Set(values.map((v) => v.trim()).filter(Boolean))].toSorted();
+}
+
+function resolveCommandsForGroup(group: ArmGroup): string[] {
+  if (group === "all") {
+    return uniqSorted(Object.values(GROUP_COMMANDS).flat());
+  }
+  return uniqSorted(GROUP_COMMANDS[group]);
+}
+
+function formatGroupList(): string {
+  return ["camera", "screen", "writes", "all"].join(", ");
+}
+
+function parseDurationMs(input: string | undefined): number | null {
+  if (!input) {
+    return null;
+  }
+  const raw = input.trim().toLowerCase();
+  if (!raw) {
+    return null;
+  }
+  const m = raw.match(/^(\d+)(s|m|h|d)$/);
+  if (!m) {
+    return null;
+  }
+  const n = Number.parseInt(m[1] ?? "", 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    return null;
+  }
+  const unit = m[2];
+  const mult = unit === "s" ? 1000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : 86_400_000;
+  return n * mult;
+}
+
+function formatDuration(ms: number): string {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 60) {
+    return `${s}s`;
+  }
+  const m = Math.floor(s / 60);
+  if (m < 60) {
+    return `${m}m`;
+  }
+  const h = Math.floor(m / 60);
+  if (h < 48) {
+    return `${h}h`;
+  }
+  const d = Math.floor(h / 24);
+  return `${d}d`;
+}
+
+function resolveStatePath(stateDir: string): string {
+  return path.join(stateDir, ...STATE_REL_PATH);
+}
+
+async function readArmState(statePath: string): Promise<ArmStateFile | null> {
+  try {
+    const raw = await fs.readFile(statePath, "utf8");
+    const parsed = JSON.parse(raw) as Partial<ArmStateFile>;
+    if (parsed.version !== 1 && parsed.version !== 2) {
+      return null;
+    }
+    if (typeof parsed.armedAtMs !== "number") {
+      return null;
+    }
+    if (!(parsed.expiresAtMs === null || typeof parsed.expiresAtMs === "number")) {
+      return null;
+    }
+
+    if (parsed.version === 1) {
+      if (
+        !Array.isArray(parsed.removedFromDeny) ||
+        !parsed.removedFromDeny.every((v) => typeof v === "string")
+      ) {
+        return null;
+      }
+      return parsed as ArmStateFile;
+    }
+
+    const group = typeof parsed.group === "string" ? parsed.group : "";
+    if (group !== "camera" && group !== "screen" && group !== "writes" && group !== "all") {
+      return null;
+    }
+    if (
+      !Array.isArray(parsed.armedCommands) ||
+      !parsed.armedCommands.every((v) => typeof v === "string")
+    ) {
+      return null;
+    }
+    if (
+      !Array.isArray(parsed.addedToAllow) ||
+      !parsed.addedToAllow.every((v) => typeof v === "string")
+    ) {
+      return null;
+    }
+    if (
+      !Array.isArray(parsed.removedFromDeny) ||
+      !parsed.removedFromDeny.every((v) => typeof v === "string")
+    ) {
+      return null;
+    }
+    return parsed as ArmStateFile;
+  } catch {
+    return null;
+  }
+}
+
+async function writeArmState(statePath: string, state: ArmStateFile | null): Promise<void> {
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  if (!state) {
+    try {
+      await fs.unlink(statePath);
+    } catch {
+      // ignore
+    }
+    return;
+  }
+  await fs.writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function normalizeDenyList(cfg: OpenClawPluginApi["config"]): string[] {
+  return uniqSorted([...(cfg.gateway?.nodes?.denyCommands ?? [])]);
+}
+
+function normalizeAllowList(cfg: OpenClawPluginApi["config"]): string[] {
+  return uniqSorted([...(cfg.gateway?.nodes?.allowCommands ?? [])]);
+}
+
+function patchConfigNodeLists(
+  cfg: OpenClawPluginApi["config"],
+  next: { allowCommands: string[]; denyCommands: string[] },
+): OpenClawPluginApi["config"] {
+  return {
+    ...cfg,
+    gateway: {
+      ...cfg.gateway,
+      nodes: {
+        ...cfg.gateway?.nodes,
+        allowCommands: next.allowCommands,
+        denyCommands: next.denyCommands,
+      },
+    },
+  };
+}
+
+async function disarmNow(params: {
+  api: OpenClawPluginApi;
+  stateDir: string;
+  statePath: string;
+  reason: string;
+}): Promise<{ changed: boolean; restored: string[]; removed: string[] }> {
+  const { api, stateDir, statePath, reason } = params;
+  const state = await readArmState(statePath);
+  if (!state) {
+    return { changed: false, restored: [], removed: [] };
+  }
+  const cfg = api.runtime.config.loadConfig();
+  const allow = new Set(normalizeAllowList(cfg));
+  const deny = new Set(normalizeDenyList(cfg));
+  const removed: string[] = [];
+  const restored: string[] = [];
+
+  if (state.version === 1) {
+    for (const cmd of state.removedFromDeny) {
+      if (!deny.has(cmd)) {
+        deny.add(cmd);
+        restored.push(cmd);
+      }
+    }
+  } else {
+    for (const cmd of state.addedToAllow) {
+      if (allow.delete(cmd)) {
+        removed.push(cmd);
+      }
+    }
+    for (const cmd of state.removedFromDeny) {
+      if (!deny.has(cmd)) {
+        deny.add(cmd);
+        restored.push(cmd);
+      }
+    }
+  }
+
+  if (removed.length > 0 || restored.length > 0) {
+    const next = patchConfigNodeLists(cfg, {
+      allowCommands: uniqSorted([...allow]),
+      denyCommands: uniqSorted([...deny]),
+    });
+    await api.runtime.config.writeConfigFile(next);
+  }
+  await writeArmState(statePath, null);
+  api.logger.info(`phone-control: disarmed (${reason}) stateDir=${stateDir}`);
+  return {
+    changed: removed.length > 0 || restored.length > 0,
+    removed: uniqSorted(removed),
+    restored: uniqSorted(restored),
+  };
+}
+
+function formatHelp(): string {
+  return [
+    "Phone control commands:",
+    "",
+    "/phone status",
+    "/phone arm <group> [duration]",
+    "/phone disarm",
+    "",
+    "Groups:",
+    `- ${formatGroupList()}`,
+    "",
+    "Duration format: 30s | 10m | 2h | 1d (default: 10m).",
+    "",
+    "Notes:",
+    "- This only toggles what the gateway is allowed to invoke on phone nodes.",
+    "- iOS will still ask for permissions (camera, photos, contacts, etc.) on first use.",
+  ].join("\n");
+}
+
+function parseGroup(raw: string | undefined): ArmGroup | null {
+  const value = (raw ?? "").trim().toLowerCase();
+  if (!value) {
+    return null;
+  }
+  if (value === "camera" || value === "screen" || value === "writes" || value === "all") {
+    return value;
+  }
+  return null;
+}
+
+function formatStatus(state: ArmStateFile | null): string {
+  if (!state) {
+    return "Phone control: disarmed.";
+  }
+  const until =
+    state.expiresAtMs == null
+      ? "manual disarm required"
+      : `expires in ${formatDuration(Math.max(0, state.expiresAtMs - Date.now()))}`;
+  const cmds = uniqSorted(
+    state.version === 1
+      ? state.removedFromDeny
+      : state.armedCommands.length > 0
+        ? state.armedCommands
+        : [...state.addedToAllow, ...state.removedFromDeny],
+  );
+  const cmdLabel = cmds.length > 0 ? cmds.join(", ") : "none";
+  return `Phone control: armed (${until}).\nTemporarily allowed: ${cmdLabel}`;
+}
+
+export default function register(api: OpenClawPluginApi) {
+  let expiryInterval: ReturnType<typeof setInterval> | null = null;
+
+  const timerService: OpenClawPluginService = {
+    id: "phone-control-expiry",
+    start: async (ctx) => {
+      const statePath = resolveStatePath(ctx.stateDir);
+      const tick = async () => {
+        const state = await readArmState(statePath);
+        if (!state || state.expiresAtMs == null) {
+          return;
+        }
+        if (Date.now() < state.expiresAtMs) {
+          return;
+        }
+        await disarmNow({
+          api,
+          stateDir: ctx.stateDir,
+          statePath,
+          reason: "expired",
+        });
+      };
+
+      // Best effort; don't crash the gateway if state is corrupt.
+      await tick().catch(() => {});
+
+      expiryInterval = setInterval(() => {
+        tick().catch(() => {});
+      }, 15_000);
+      expiryInterval.unref?.();
+
+      return;
+    },
+    stop: async () => {
+      if (expiryInterval) {
+        clearInterval(expiryInterval);
+        expiryInterval = null;
+      }
+      return;
+    },
+  };
+
+  api.registerService(timerService);
+
+  api.registerCommand({
+    name: "phone",
+    description: "Arm/disarm high-risk phone node commands (camera/screen/writes).",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const args = ctx.args?.trim() ?? "";
+      const tokens = args.split(/\s+/).filter(Boolean);
+      const action = tokens[0]?.toLowerCase() ?? "";
+
+      const stateDir = api.runtime.state.resolveStateDir();
+      const statePath = resolveStatePath(stateDir);
+
+      if (!action || action === "help") {
+        const state = await readArmState(statePath);
+        return { text: `${formatStatus(state)}\n\n${formatHelp()}` };
+      }
+
+      if (action === "status") {
+        const state = await readArmState(statePath);
+        return { text: formatStatus(state) };
+      }
+
+      if (action === "disarm") {
+        const res = await disarmNow({
+          api,
+          stateDir,
+          statePath,
+          reason: "manual",
+        });
+        if (!res.changed) {
+          return { text: "Phone control: disarmed." };
+        }
+        const restoredLabel = res.restored.length > 0 ? res.restored.join(", ") : "none";
+        const removedLabel = res.removed.length > 0 ? res.removed.join(", ") : "none";
+        return {
+          text: `Phone control: disarmed.\nRemoved allowlist: ${removedLabel}\nRestored denylist: ${restoredLabel}`,
+        };
+      }
+
+      if (action === "arm") {
+        const group = parseGroup(tokens[1]);
+        if (!group) {
+          return { text: `Usage: /phone arm <group> [duration]\nGroups: ${formatGroupList()}` };
+        }
+        const durationMs = parseDurationMs(tokens[2]) ?? 10 * 60_000;
+        const expiresAtMs = Date.now() + durationMs;
+
+        const commands = resolveCommandsForGroup(group);
+        const cfg = api.runtime.config.loadConfig();
+        const allowSet = new Set(normalizeAllowList(cfg));
+        const denySet = new Set(normalizeDenyList(cfg));
+
+        const addedToAllow: string[] = [];
+        const removedFromDeny: string[] = [];
+        for (const cmd of commands) {
+          if (!allowSet.has(cmd)) {
+            allowSet.add(cmd);
+            addedToAllow.push(cmd);
+          }
+          if (denySet.delete(cmd)) {
+            removedFromDeny.push(cmd);
+          }
+        }
+        const next = patchConfigNodeLists(cfg, {
+          allowCommands: uniqSorted([...allowSet]),
+          denyCommands: uniqSorted([...denySet]),
+        });
+        await api.runtime.config.writeConfigFile(next);
+
+        await writeArmState(statePath, {
+          version: STATE_VERSION,
+          armedAtMs: Date.now(),
+          expiresAtMs,
+          group,
+          armedCommands: uniqSorted(commands),
+          addedToAllow: uniqSorted(addedToAllow),
+          removedFromDeny: uniqSorted(removedFromDeny),
+        });
+
+        const allowedLabel = uniqSorted(commands).join(", ");
+        return {
+          text:
+            `Phone control: armed for ${formatDuration(durationMs)}.\n` +
+            `Temporarily allowed: ${allowedLabel}\n` +
+            `To disarm early: /phone disarm`,
+        };
+      }
+
+      return { text: formatHelp() };
+    },
+  });
+}

extensions/phone-control/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "phone-control",
+  "name": "Phone Control",
+  "description": "Arm/disarm high-risk phone node commands (camera/screen/writes) with an optional auto-expiry.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/talk-voice/index.ts

@@ -0,0 +1,150 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+type ElevenLabsVoice = {
+  voice_id: string;
+  name?: string;
+  category?: string;
+  description?: string;
+};
+
+function mask(s: string, keep: number = 6): string {
+  const trimmed = s.trim();
+  if (trimmed.length <= keep) {
+    return "***";
+  }
+  return `${trimmed.slice(0, keep)}…`;
+}
+
+function isLikelyVoiceId(value: string): boolean {
+  const v = value.trim();
+  if (v.length < 10 || v.length > 64) {
+    return false;
+  }
+  return /^[a-zA-Z0-9_-]+$/.test(v);
+}
+
+async function listVoices(apiKey: string): Promise<ElevenLabsVoice[]> {
+  const res = await fetch("https://api.elevenlabs.io/v1/voices", {
+    headers: {
+      "xi-api-key": apiKey,
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`ElevenLabs voices API error (${res.status})`);
+  }
+  const json = (await res.json()) as { voices?: ElevenLabsVoice[] };
+  return Array.isArray(json.voices) ? json.voices : [];
+}
+
+function formatVoiceList(voices: ElevenLabsVoice[], limit: number): string {
+  const sliced = voices.slice(0, Math.max(1, Math.min(limit, 50)));
+  const lines: string[] = [];
+  lines.push(`Voices: ${voices.length}`);
+  lines.push("");
+  for (const v of sliced) {
+    const name = (v.name ?? "").trim() || "(unnamed)";
+    const category = (v.category ?? "").trim();
+    const meta = category ? ` · ${category}` : "";
+    lines.push(`- ${name}${meta}`);
+    lines.push(`  id: ${v.voice_id}`);
+  }
+  if (voices.length > sliced.length) {
+    lines.push("");
+    lines.push(`(showing first ${sliced.length})`);
+  }
+  return lines.join("\n");
+}
+
+function findVoice(voices: ElevenLabsVoice[], query: string): ElevenLabsVoice | null {
+  const q = query.trim();
+  if (!q) {
+    return null;
+  }
+  const lower = q.toLowerCase();
+  const byId = voices.find((v) => v.voice_id === q);
+  if (byId) {
+    return byId;
+  }
+  const exactName = voices.find((v) => (v.name ?? "").trim().toLowerCase() === lower);
+  if (exactName) {
+    return exactName;
+  }
+  const partial = voices.find((v) => (v.name ?? "").trim().toLowerCase().includes(lower));
+  return partial ?? null;
+}
+
+export default function register(api: OpenClawPluginApi) {
+  api.registerCommand({
+    name: "voice",
+    description: "List/set ElevenLabs Talk voice (affects iOS Talk playback).",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const args = ctx.args?.trim() ?? "";
+      const tokens = args.split(/\s+/).filter(Boolean);
+      const action = (tokens[0] ?? "status").toLowerCase();
+
+      const cfg = api.runtime.config.loadConfig();
+      const apiKey = (cfg.talk?.apiKey ?? "").trim();
+      if (!apiKey) {
+        return {
+          text:
+            "Talk voice is not configured.\n\n" +
+            "Missing: talk.apiKey (ElevenLabs API key).\n" +
+            "Set it on the gateway, then retry.",
+        };
+      }
+
+      const currentVoiceId = (cfg.talk?.voiceId ?? "").trim();
+
+      if (action === "status") {
+        return {
+          text:
+            "Talk voice status:\n" +
+            `- talk.voiceId: ${currentVoiceId ? currentVoiceId : "(unset)"}\n` +
+            `- talk.apiKey: ${mask(apiKey)}`,
+        };
+      }
+
+      if (action === "list") {
+        const limit = Number.parseInt(tokens[1] ?? "12", 10);
+        const voices = await listVoices(apiKey);
+        return { text: formatVoiceList(voices, Number.isFinite(limit) ? limit : 12) };
+      }
+
+      if (action === "set") {
+        const query = tokens.slice(1).join(" ").trim();
+        if (!query) {
+          return { text: "Usage: /voice set <voiceId|name>" };
+        }
+        const voices = await listVoices(apiKey);
+        const chosen = findVoice(voices, query);
+        if (!chosen) {
+          const hint = isLikelyVoiceId(query) ? query : `"${query}"`;
+          return { text: `No voice found for ${hint}. Try: /voice list` };
+        }
+
+        const nextConfig = {
+          ...cfg,
+          talk: {
+            ...cfg.talk,
+            voiceId: chosen.voice_id,
+          },
+        };
+        await api.runtime.config.writeConfigFile(nextConfig);
+
+        const name = (chosen.name ?? "").trim() || "(unnamed)";
+        return { text: `✅ Talk voice set to ${name}\n${chosen.voice_id}` };
+      }
+
+      return {
+        text: [
+          "Voice commands:",
+          "",
+          "/voice status",
+          "/voice list [limit]",
+          "/voice set <voiceId|name>",
+        ].join("\n"),
+      };
+    },
+  });
+}

extensions/talk-voice/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "talk-voice",
+  "name": "Talk Voice",
+  "description": "Manage Talk voice selection (list/set).",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/tlon/src/channel.ts

@@ -101,7 +101,7 @@ const tlonOutbound: ChannelOutboundAdapter = {
         error: new Error(`Invalid Tlon target. Use ${formatTargetHint()}`),
       };
     }
-    if (parsed.kind === "dm") {
+    if (parsed.kind === "direct") {
       return { ok: true, to: parsed.ship };
     }
     return { ok: true, to: parsed.nest };
@@ -127,7 +127,7 @@ const tlonOutbound: ChannelOutboundAdapter = {
 
     try {
       const fromShip = normalizeShip(account.ship);
-      if (parsed.kind === "dm") {
+      if (parsed.kind === "direct") {
         return await sendDm({
           api,
           fromShip,
@@ -298,7 +298,7 @@ export const tlonPlugin: ChannelPlugin = {
       if (!parsed) {
         return target.trim();
       }
-      if (parsed.kind === "dm") {
+      if (parsed.kind === "direct") {
         return parsed.ship;
       }
       return parsed.nest;