重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。

同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
2026-10-11 15:13:23 +08:00 · 2026-04-26 08:34:33 +08:00 · 2026-04-26 08:34:33 +08:00 · dbbe3add6a
commit dbbe3add6a
parent 4a23b715a2
14438 changed files with 2693620 additions and 2546 deletions
--- a/openclaw/apps/ios/.swiftlint.yml
+++ b/openclaw/apps/ios/.swiftlint.yml
@ -0,0 +1,9 @@
+parent_config: ../../.swiftlint.yml
+
+included:
+  - Sources
+  - ../shared/ClawdisNodeKit/Sources
+
+type_body_length:
+  warning: 900
+  error: 1300
--- a/openclaw/apps/ios/ActivityWidget/Assets.xcassets/Contents.json
+++ b/openclaw/apps/ios/ActivityWidget/Assets.xcassets/Contents.json
@ -0,0 +1,6 @@
+{
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
--- a/openclaw/apps/ios/ActivityWidget/Info.plist
+++ b/openclaw/apps/ios/ActivityWidget/Info.plist
@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>OpenClaw Activity</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>XPC!</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
+	<key>CFBundleVersion</key>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.widgetkit-extension</string>
+	</dict>
+	<key>NSSupportsLiveActivities</key>
+	<true/>
+</dict>
+</plist>
--- a/openclaw/apps/ios/ActivityWidget/OpenClawActivityWidgetBundle.swift
+++ b/openclaw/apps/ios/ActivityWidget/OpenClawActivityWidgetBundle.swift
@ -0,0 +1,9 @@
+import SwiftUI
+import WidgetKit
+
+@main
+struct OpenClawActivityWidgetBundle: WidgetBundle {
+    var body: some Widget {
+        OpenClawLiveActivity()
+    }
+}
--- a/openclaw/apps/ios/ActivityWidget/OpenClawLiveActivity.swift
+++ b/openclaw/apps/ios/ActivityWidget/OpenClawLiveActivity.swift
@ -0,0 +1,85 @@
+import ActivityKit
+import SwiftUI
+import WidgetKit
+
+struct OpenClawLiveActivity: Widget {
+    var body: some WidgetConfiguration {
+        ActivityConfiguration(for: OpenClawActivityAttributes.self) { context in
+            lockScreenView(context: context)
+        } dynamicIsland: { context in
+            DynamicIsland {
+                DynamicIslandExpandedRegion(.leading) {
+                    statusDot(state: context.state)
+                }
+                DynamicIslandExpandedRegion(.center) {
+                    Text(context.state.statusText)
+                        .font(.subheadline)
+                        .lineLimit(1)
+                }
+                DynamicIslandExpandedRegion(.trailing) {
+                    trailingView(state: context.state)
+                }
+            } compactLeading: {
+                statusDot(state: context.state)
+            } compactTrailing: {
+                Text(context.state.statusText)
+                    .font(.caption2)
+                    .lineLimit(1)
+                    .frame(maxWidth: 64)
+            } minimal: {
+                statusDot(state: context.state)
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func lockScreenView(context: ActivityViewContext<OpenClawActivityAttributes>) -> some View {
+        HStack(spacing: 8) {
+            statusDot(state: context.state)
+                .frame(width: 10, height: 10)
+            VStack(alignment: .leading, spacing: 2) {
+                Text("OpenClaw")
+                    .font(.subheadline.bold())
+                Text(context.state.statusText)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+            Spacer()
+            trailingView(state: context.state)
+        }
+        .padding(.horizontal, 12)
+        .padding(.vertical, 4)
+    }
+
+    @ViewBuilder
+    private func trailingView(state: OpenClawActivityAttributes.ContentState) -> some View {
+        if state.isConnecting {
+            ProgressView().controlSize(.small)
+        } else if state.isDisconnected {
+            Image(systemName: "wifi.slash")
+                .foregroundStyle(.red)
+        } else if state.isIdle {
+            Image(systemName: "antenna.radiowaves.left.and.right")
+                .foregroundStyle(.green)
+        } else {
+            Text(state.startedAt, style: .timer)
+                .font(.caption)
+                .monospacedDigit()
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder
+    private func statusDot(state: OpenClawActivityAttributes.ContentState) -> some View {
+        Circle()
+            .fill(dotColor(state: state))
+            .frame(width: 6, height: 6)
+    }
+
+    private func dotColor(state: OpenClawActivityAttributes.ContentState) -> Color {
+        if state.isDisconnected { return .red }
+        if state.isConnecting { return .gray }
+        if state.isIdle { return .green }
+        return .blue
+    }
+}
--- a/openclaw/apps/ios/CHANGELOG.md
+++ b/openclaw/apps/ios/CHANGELOG.md
@ -0,0 +1,33 @@
+# OpenClaw iOS Changelog
+
+## 2026.4.20 - 2026-04-20
+
+Maintenance update for the current OpenClaw release.
+
+## 2026.4.19 - 2026-04-19
+
+Maintenance update for the current OpenClaw beta release.
+
+## 2026.4.18 - 2026-04-18
+
+Maintenance update for the current OpenClaw release.
+
+## 2026.4.15 - 2026-04-15
+
+Maintenance update for the current OpenClaw beta release.
+
+## 2026.4.14 - 2026-04-14
+
+Maintenance update for the current OpenClaw beta release.
+
+## 2026.4.12 - 2026-04-12
+
+Maintenance update for the current OpenClaw release.
+
+## 2026.4.10 - 2026-04-10
+
+Maintenance update for the current OpenClaw release.
+
+## 2026.4.6 - 2026-04-06
+
+First App Store release of OpenClaw for iPhone. Pair with your OpenClaw Gateway to use chat, voice, sharing, and device actions from iOS.
--- a/openclaw/apps/ios/Config/Signing.xcconfig
+++ b/openclaw/apps/ios/Config/Signing.xcconfig
@ -0,0 +1,25 @@
+// Shared iOS signing defaults for local development + CI.
+#include "Version.xcconfig"
+
+OPENCLAW_IOS_DEFAULT_TEAM = Y5PE65HELJ
+OPENCLAW_IOS_SELECTED_TEAM = $(OPENCLAW_IOS_DEFAULT_TEAM)
+OPENCLAW_DEVELOPMENT_TEAM = $(OPENCLAW_IOS_SELECTED_TEAM)
+OPENCLAW_CODE_SIGN_STYLE = Automatic
+OPENCLAW_APP_BUNDLE_ID = ai.openclaw.client
+OPENCLAW_WATCH_APP_BUNDLE_ID = ai.openclaw.client.watchkitapp
+OPENCLAW_WATCH_EXTENSION_BUNDLE_ID = ai.openclaw.client.watchkitapp.extension
+OPENCLAW_ACTIVITY_WIDGET_BUNDLE_ID = ai.openclaw.client.activitywidget
+OPENCLAW_WATCH_APP_PROFILE =
+OPENCLAW_WATCH_EXTENSION_PROFILE =
+
+// Local contributors can override this by running scripts/ios-configure-signing.sh.
+// Keep include after defaults: xcconfig is evaluated top-to-bottom.
+#include? "../.local-signing.xcconfig"
+#include? "../LocalSigning.xcconfig"
+
+CODE_SIGN_STYLE = $(OPENCLAW_CODE_SIGN_STYLE)
+CODE_SIGN_IDENTITY = Apple Development
+DEVELOPMENT_TEAM = $(OPENCLAW_DEVELOPMENT_TEAM)
+
+// Let Xcode manage provisioning for the selected local team unless a local override pins one.
+PROVISIONING_PROFILE_SPECIFIER =
--- a/openclaw/apps/ios/Config/Version.xcconfig
+++ b/openclaw/apps/ios/Config/Version.xcconfig
@ -0,0 +1,9 @@
+// Shared iOS version defaults.
+// Source of truth: apps/ios/version.json
+// Generated by scripts/ios-sync-versioning.ts.
+
+OPENCLAW_IOS_VERSION = 2026.4.20
+OPENCLAW_MARKETING_VERSION = 2026.4.20
+OPENCLAW_BUILD_VERSION = 1
+
+#include? "../build/Version.xcconfig"
--- a/openclaw/apps/ios/LocalSigning.xcconfig.example
+++ b/openclaw/apps/ios/LocalSigning.xcconfig.example
@ -0,0 +1,17 @@
+// Copy to LocalSigning.xcconfig for personal local signing overrides.
+// This file is only an example and should stay committed.
+
+OPENCLAW_CODE_SIGN_STYLE = Automatic
+OPENCLAW_DEVELOPMENT_TEAM = YOUR_TEAM_ID
+
+OPENCLAW_APP_BUNDLE_ID = ai.openclaw.client
+OPENCLAW_SHARE_BUNDLE_ID = ai.openclaw.client.share
+OPENCLAW_ACTIVITY_WIDGET_BUNDLE_ID = ai.openclaw.client.activitywidget
+OPENCLAW_WATCH_APP_BUNDLE_ID = ai.openclaw.client.watchkitapp
+OPENCLAW_WATCH_EXTENSION_BUNDLE_ID = ai.openclaw.client.watchkitapp.extension
+
+// Leave empty with automatic signing.
+OPENCLAW_APP_PROFILE =
+OPENCLAW_SHARE_PROFILE =
+OPENCLAW_WATCH_APP_PROFILE =
+OPENCLAW_WATCH_EXTENSION_PROFILE =
--- a/openclaw/apps/ios/README.md
+++ b/openclaw/apps/ios/README.md
@ -0,0 +1,321 @@
+# OpenClaw iOS (Super Alpha)
+
+This iPhone app is super-alpha and internal-use only. It connects to an OpenClaw Gateway as a `role: node`.
+
+## Distribution Status
+
+- Public distribution: not available.
+- Internal beta distribution: local archive + TestFlight upload via Fastlane.
+- Local/manual deploy from source via Xcode remains the default development path.
+
+## Super-Alpha Disclaimer
+
+- Breaking changes are expected.
+- UI and onboarding flows can change without migration guarantees.
+- Foreground use is the only reliable mode right now.
+- Treat this build as sensitive while permissions and background behavior are still being hardened.
+
+## Exact Xcode Manual Deploy Flow
+
+1. Prereqs:
+   - Xcode 16+
+   - `pnpm`
+   - `xcodegen`
+   - Apple Development signing set up in Xcode
+2. From repo root:
+
+```bash
+pnpm install
+./scripts/ios-configure-signing.sh
+cd apps/ios
+xcodegen generate
+open OpenClaw.xcodeproj
+```
+
+3. In Xcode:
+   - Scheme: `OpenClaw`
+   - Destination: connected iPhone (recommended for real behavior)
+   - Build configuration: `Debug`
+   - Run (`Product` -> `Run`)
+4. If signing fails on a personal team:
+   - Use unique local bundle IDs via `apps/ios/LocalSigning.xcconfig`.
+   - Start from `apps/ios/LocalSigning.xcconfig.example`.
+
+Shortcut command (same flow + open project):
+
+```bash
+pnpm ios:open
+```
+
+## Local Beta Release Flow
+
+Prereqs:
+
+- Xcode 16+
+- `pnpm`
+- `xcodegen`
+- `fastlane`
+- Apple account signed into Xcode for automatic signing/provisioning
+- App Store Connect API key set up in Keychain via `scripts/ios-asc-keychain-setup.sh` when auto-resolving a beta build number or uploading to TestFlight
+
+Release behavior:
+
+- Local development keeps using unique per-developer bundle IDs from `scripts/ios-configure-signing.sh`.
+- Beta release uses canonical `ai.openclaw.client*` bundle IDs through a temporary generated xcconfig in `apps/ios/build/BetaRelease.xcconfig`.
+- Beta release also switches the app to `OpenClawPushTransport=relay`, `OpenClawPushDistribution=official`, and `OpenClawPushAPNsEnvironment=production`.
+- The beta flow does not modify `apps/ios/.local-signing.xcconfig` or `apps/ios/LocalSigning.xcconfig`.
+- `apps/ios/version.json` is the pinned iOS release version source.
+- `apps/ios/CHANGELOG.md` is the iOS-only changelog and release-note source.
+- The pinned iOS version must use CalVer like `2026.4.10`.
+- That pinned value becomes:
+  - `CFBundleShortVersionString = 2026.4.10`
+  - `CFBundleVersion = next TestFlight build number for 2026.4.10`
+- Changing the root gateway version does not change the iOS app version until you explicitly pin from the gateway.
+- See `apps/ios/VERSIONING.md` for the full workflow.
+
+Required env for beta builds:
+
+- `OPENCLAW_PUSH_RELAY_BASE_URL=https://relay.example.com`
+  This must be a plain `https://host[:port][/path]` base URL without whitespace, query params, fragments, or xcconfig metacharacters.
+
+Archive without upload:
+
+```bash
+pnpm ios:beta:archive
+```
+
+Archive and upload to TestFlight:
+
+```bash
+pnpm ios:beta
+```
+
+If you need to force a specific build number:
+
+```bash
+pnpm ios:beta -- --build-number 7
+```
+
+### Maintainer Quick Release Checklist
+
+Use this when a clone is missing local iOS release setup and you want the shortest path to a TestFlight upload.
+
+1. Confirm Fastlane auth is set up:
+
+```bash
+cd apps/ios
+fastlane ios auth_check
+```
+
+2. If auth is missing, bootstrap it once on this Mac:
+
+```bash
+scripts/ios-asc-keychain-setup.sh \
+  --key-path /absolute/path/to/AuthKey_XXXXXXXXXX.p8 \
+  --issuer-id YOUR_ISSUER_ID \
+  --write-env
+```
+
+This should create `apps/ios/fastlane/.env` with the non-secret ASC variables while the private key stays in Keychain.
+
+3. Set the official/TestFlight relay URL for the build:
+
+```bash
+export OPENCLAW_PUSH_RELAY_BASE_URL=https://relay.example.com
+```
+
+4. If you are starting a brand-new production release train, pin iOS to the current gateway version first:
+
+```bash
+pnpm ios:version:pin -- --from-gateway
+```
+
+5. Upload the beta:
+
+```bash
+pnpm ios:beta
+```
+
+6. Expected behavior:
+   - Fastlane reads `apps/ios/version.json`
+   - verifies synced iOS versioning artifacts
+   - resolves the next TestFlight build number for that short version
+   - generates `apps/ios/build/BetaRelease.xcconfig`
+   - archives `OpenClaw`
+   - uploads the IPA to TestFlight
+
+7. Expected outputs after a successful run:
+   - `apps/ios/build/beta/OpenClaw-<version>.ipa`
+   - `apps/ios/build/beta/OpenClaw-<version>.app.dSYM.zip`
+   - Fastlane log line like `Uploaded iOS beta: version=<version> short=<short> build=<build>`
+
+8. If this is a fresh clone on a maintainer machine that already works elsewhere, it is OK to copy the non-secret `apps/ios/fastlane/.env` from another trusted local clone on the same Mac. The Keychain-backed private key remains machine-local and is not stored in the repo.
+
+## iOS Versioning Workflow
+
+- Pinned iOS release version: `apps/ios/version.json`
+- iOS-only changelog: `apps/ios/CHANGELOG.md`
+- Generated checked-in artifacts:
+  - `apps/ios/Config/Version.xcconfig`
+  - `apps/ios/fastlane/metadata/en-US/release_notes.txt`
+- Useful commands:
+
+```bash
+pnpm ios:version
+pnpm ios:version:check
+pnpm ios:version:sync
+pnpm ios:version:pin -- --from-gateway
+pnpm ios:version:pin -- --version 2026.4.10
+```
+
+Recommended flow:
+
+### TestFlight iteration on an existing train
+
+1. Keep `apps/ios/version.json` pinned to the current train version.
+2. Update `apps/ios/CHANGELOG.md`, usually under `## Unreleased` while iterating.
+3. Run `pnpm ios:version:sync` after changelog changes.
+4. Upload more TestFlight builds with `pnpm ios:beta`.
+5. Let Fastlane bump only the numeric build number.
+
+### Starting the next production release train
+
+1. Pin iOS to the current gateway version:
+
+```bash
+pnpm ios:version:pin -- --from-gateway
+```
+
+2. Update `apps/ios/CHANGELOG.md` for the new release as needed.
+3. Run `pnpm ios:version:sync`.
+4. Submit the first TestFlight build for that newly pinned version.
+5. Keep iterating on that same version until the release candidate is ready.
+
+See `apps/ios/VERSIONING.md` for the detailed spec.
+
+## APNs Expectations For Local/Manual Builds
+
+- The app calls `registerForRemoteNotifications()` at launch.
+- `apps/ios/Sources/OpenClaw.entitlements` sets `aps-environment` to `development`.
+- APNs token registration to gateway happens only after gateway connection (`push.apns.register`).
+- Local/manual builds default to `OpenClawPushTransport=direct` and `OpenClawPushDistribution=local`.
+- Your selected team/profile must support Push Notifications for the app bundle ID you are signing.
+- If push capability or provisioning is wrong, APNs registration fails at runtime (check Xcode logs for `APNs registration failed`).
+- The gateway host also needs direct APNs auth configured separately with `OPENCLAW_APNS_TEAM_ID`, `OPENCLAW_APNS_KEY_ID`, and either `OPENCLAW_APNS_PRIVATE_KEY_P8` or `OPENCLAW_APNS_PRIVATE_KEY_PATH`.
+- Recommended gateway-host storage for the APNs `.p8` file is `~/.openclaw/credentials/apns/AuthKey_<KEYID>.p8` with restrictive permissions, then point `OPENCLAW_APNS_PRIVATE_KEY_PATH` at that file.
+- `apps/ios/fastlane/.env` only covers App Store Connect / Fastlane auth; it does not provide gateway APNs credentials for local direct-push testing.
+- Debug builds default to `OpenClawPushAPNsEnvironment=sandbox`; Release builds default to `production`.
+
+## APNs Expectations For Official Builds
+
+- Official/TestFlight builds register with the external push relay before they publish `push.apns.register` to the gateway.
+- The gateway registration for relay mode contains an opaque relay handle, a registration-scoped send grant, relay origin metadata, and installation metadata instead of the raw APNs token.
+- The relay registration is bound to the gateway identity fetched from `gateway.identity.get`, so another gateway cannot reuse that stored registration.
+- The app persists the relay handle metadata locally so reconnects can republish the gateway registration without re-registering on every connect.
+- If the relay base URL changes in a later build, the app refreshes the relay registration instead of reusing the old relay origin.
+- Relay mode requires a reachable relay base URL and uses App Attest plus the app receipt during registration.
+- Gateway-side relay sending is configured through `gateway.push.apns.relay.baseUrl` in `openclaw.json`. `OPENCLAW_APNS_RELAY_BASE_URL` remains a temporary env override only.
+
+## Official Build Relay Trust Model
+
+- `iOS -> gateway`
+  - The app must pair with the gateway and establish both node and operator sessions.
+  - The operator session is used to fetch `gateway.identity.get`.
+- `iOS -> relay`
+  - The app registers with the relay over HTTPS using App Attest plus the app receipt.
+  - The relay requires the official production/TestFlight distribution path, which is why local
+    Xcode/dev installs cannot use the hosted relay.
+- `gateway delegation`
+  - The app includes the gateway identity in relay registration.
+  - The relay returns a relay handle and registration-scoped send grant delegated to that gateway.
+- `gateway -> relay`
+  - The gateway signs relay send requests with its own device identity.
+  - The relay verifies both the delegated send grant and the gateway signature before it sends to
+    APNs.
+- `relay -> APNs`
+  - Production APNs credentials and raw official-build APNs tokens stay in the relay deployment,
+    not on the gateway.
+
+This exists to keep the hosted relay limited to genuine OpenClaw official builds and to ensure a
+gateway can only send pushes for iOS devices that paired with that gateway.
+
+## What Works Now (Concrete)
+
+- Pairing via setup code flow (`/pair` then `/pair approve` in Telegram).
+- Gateway connection via discovery or manual host/port with TLS fingerprint trust prompt.
+- Chat + Talk surfaces through the operator gateway session.
+- iPhone node commands in foreground: camera snap/clip, canvas present/navigate/eval/snapshot, screen record, location, contacts, calendar, reminders, photos, motion, local notifications.
+- Share extension deep-link forwarding into the connected gateway session.
+
+## Location Automation Use Case (Testing)
+
+Use this for automation signals ("I moved", "I arrived", "I left"), not as a keep-awake mechanism.
+
+- Product intent:
+  - movement-aware automations driven by iOS location events
+  - example: arrival/exit geofence, significant movement, visit detection
+- Non-goal:
+  - continuous GPS polling just to keep the app alive
+
+Test path to include in QA runs:
+
+1. Enable location permission in app:
+   - set `Always` permission
+   - verify background location capability is enabled in the build profile
+2. Background the app and trigger movement:
+   - walk/drive enough for a significant location update, or cross a configured geofence
+3. Validate gateway side effects:
+   - node reconnect/wake if needed
+   - expected location/movement event arrives at gateway
+   - automation trigger executes once (no duplicate storm)
+4. Validate resource impact:
+   - no sustained high thermal state
+   - no excessive background battery drain over a short observation window
+
+Pass criteria:
+
+- movement events are delivered reliably enough for automation UX
+- no location-driven reconnect spam loops
+- app remains stable after repeated background/foreground transitions
+
+## Known Issues / Limitations / Problems
+
+- Foreground-first: iOS can suspend sockets in background; reconnect recovery is still being tuned.
+- Background command limits are strict: `canvas.*`, `camera.*`, `screen.*`, and `talk.*` are blocked when backgrounded.
+- Background location requires `Always` location permission.
+- Pairing/auth errors intentionally pause reconnect loops until a human fixes auth/pairing state.
+- Voice Wake and Talk contend for the same microphone; Talk suppresses wake capture while active.
+- APNs reliability depends on local signing/provisioning/topic alignment.
+- Expect rough UX edges and occasional reconnect churn during active development.
+
+## Current In-Progress Workstream
+
+Automatic wake/reconnect hardening:
+
+- improve wake/resume behavior across scene transitions
+- reduce dead-socket states after background -> foreground
+- tighten node/operator session reconnect coordination
+- reduce manual recovery steps after transient network failures
+
+## Debugging Checklist
+
+1. Confirm build/signing baseline:
+   - regenerate project (`xcodegen generate`)
+   - verify selected team + bundle IDs
+2. In app `Settings -> Gateway`:
+   - confirm status text, server, and remote address
+   - verify whether status shows pairing/auth gating
+3. If pairing is required:
+   - run `/pair approve` from Telegram, then reconnect
+4. If discovery is flaky:
+   - enable `Discovery Debug Logs`
+   - inspect `Settings -> Gateway -> Discovery Logs`
+5. If network path is unclear:
+   - switch to manual host/port + TLS in Gateway Advanced settings
+6. In Xcode console, filter for subsystem/category signals:
+   - `ai.openclaw.ios`
+   - `GatewayDiag`
+   - `APNs registration failed`
+7. Validate background expectations:
+   - repro in foreground first
+   - then test background transitions and confirm reconnect on return
--- a/openclaw/apps/ios/ShareExtension/Info.plist
+++ b/openclaw/apps/ios/ShareExtension/Info.plist
@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>OpenClaw Share</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>XPC!</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
+	<key>CFBundleVersion</key>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionAttributes</key>
+		<dict>
+			<key>NSExtensionActivationRule</key>
+			<dict>
+				<key>NSExtensionActivationSupportsImageWithMaxCount</key>
+				<integer>10</integer>
+				<key>NSExtensionActivationSupportsMovieWithMaxCount</key>
+				<integer>1</integer>
+				<key>NSExtensionActivationSupportsText</key>
+				<true/>
+				<key>NSExtensionActivationSupportsWebURLWithMaxCount</key>
+				<integer>1</integer>
+			</dict>
+		</dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.share-services</string>
+		<key>NSExtensionPrincipalClass</key>
+		<string>$(PRODUCT_MODULE_NAME).ShareViewController</string>
+	</dict>
+</dict>
+</plist>
--- a/openclaw/apps/ios/ShareExtension/ShareViewController.swift
+++ b/openclaw/apps/ios/ShareExtension/ShareViewController.swift
@ -0,0 +1,550 @@
+import Foundation
+import OpenClawKit
+import os
+import UIKit
+import UniformTypeIdentifiers
+
+final class ShareViewController: UIViewController {
+    private struct ShareAttachment: Codable {
+        var type: String
+        var mimeType: String
+        var fileName: String
+        var content: String
+    }
+
+    private struct ExtractedShareContent {
+        var payload: SharedContentPayload
+        var attachments: [ShareAttachment]
+    }
+
+    private let logger = Logger(subsystem: "ai.openclaw.ios", category: "ShareExtension")
+    private var statusLabel: UILabel?
+    private let draftTextView = UITextView()
+    private let sendButton = UIButton(type: .system)
+    private let cancelButton = UIButton(type: .system)
+    private var didPrepareDraft = false
+    private var isSending = false
+    private var pendingAttachments: [ShareAttachment] = []
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        self.preferredContentSize = CGSize(width: UIScreen.main.bounds.width, height: 420)
+        self.setupUI()
+    }
+
+    override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        guard !self.didPrepareDraft else { return }
+        self.didPrepareDraft = true
+        Task { await self.prepareDraft() }
+    }
+
+    private func setupUI() {
+        self.view.backgroundColor = .systemBackground
+
+        self.draftTextView.translatesAutoresizingMaskIntoConstraints = false
+        self.draftTextView.font = .preferredFont(forTextStyle: .body)
+        self.draftTextView.backgroundColor = UIColor.secondarySystemBackground
+        self.draftTextView.layer.cornerRadius = 10
+        self.draftTextView.textContainerInset = UIEdgeInsets(top: 12, left: 10, bottom: 12, right: 10)
+
+        self.sendButton.translatesAutoresizingMaskIntoConstraints = false
+        self.sendButton.setTitle("Send to OpenClaw", for: .normal)
+        self.sendButton.titleLabel?.font = .preferredFont(forTextStyle: .headline)
+        self.sendButton.addTarget(self, action: #selector(self.handleSendTap), for: .touchUpInside)
+        self.sendButton.isEnabled = false
+
+        self.cancelButton.translatesAutoresizingMaskIntoConstraints = false
+        self.cancelButton.setTitle("Cancel", for: .normal)
+        self.cancelButton.addTarget(self, action: #selector(self.handleCancelTap), for: .touchUpInside)
+
+        let buttons = UIStackView(arrangedSubviews: [self.cancelButton, self.sendButton])
+        buttons.translatesAutoresizingMaskIntoConstraints = false
+        buttons.axis = .horizontal
+        buttons.alignment = .fill
+        buttons.distribution = .fillEqually
+        buttons.spacing = 12
+
+        self.view.addSubview(self.draftTextView)
+        self.view.addSubview(buttons)
+
+        NSLayoutConstraint.activate([
+            self.draftTextView.topAnchor.constraint(equalTo: self.view.safeAreaLayoutGuide.topAnchor, constant: 14),
+            self.draftTextView.leadingAnchor.constraint(equalTo: self.view.leadingAnchor, constant: 14),
+            self.draftTextView.trailingAnchor.constraint(equalTo: self.view.trailingAnchor, constant: -14),
+            self.draftTextView.bottomAnchor.constraint(equalTo: buttons.topAnchor, constant: -12),
+
+            buttons.leadingAnchor.constraint(equalTo: self.view.leadingAnchor, constant: 14),
+            buttons.trailingAnchor.constraint(equalTo: self.view.trailingAnchor, constant: -14),
+            buttons.bottomAnchor.constraint(equalTo: self.view.keyboardLayoutGuide.topAnchor, constant: -8),
+            buttons.heightAnchor.constraint(equalToConstant: 44),
+        ])
+    }
+
+    private func prepareDraft() async {
+        let traceId = UUID().uuidString
+        ShareGatewayRelaySettings.saveLastEvent("Share opened.")
+        self.showStatus("Preparing share…")
+        self.logger.info("share begin trace=\(traceId, privacy: .public)")
+        let extracted = await self.extractSharedContent()
+        let payload = extracted.payload
+        self.pendingAttachments = extracted.attachments
+        self.logger.info(
+            "share payload trace=\(traceId, privacy: .public) titleChars=\(payload.title?.count ?? 0) textChars=\(payload.text?.count ?? 0) hasURL=\(payload.url != nil) imageAttachments=\(self.pendingAttachments.count)"
+        )
+        let message = self.composeDraft(from: payload)
+        await MainActor.run {
+            self.draftTextView.text = message
+            self.sendButton.isEnabled = true
+            self.draftTextView.becomeFirstResponder()
+        }
+        if message.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            ShareGatewayRelaySettings.saveLastEvent("Share ready: waiting for message input.")
+            self.showStatus("Add a message, then tap Send.")
+        } else {
+            ShareGatewayRelaySettings.saveLastEvent("Share ready: draft prepared.")
+            self.showStatus("Edit text, then tap Send.")
+        }
+    }
+
+    @objc
+    private func handleSendTap() {
+        guard !self.isSending else { return }
+        Task { await self.sendCurrentDraft() }
+    }
+
+    @objc
+    private func handleCancelTap() {
+        self.extensionContext?.completeRequest(returningItems: nil)
+    }
+
+    private func sendCurrentDraft() async {
+        let message = await MainActor.run { self.draftTextView.text ?? "" }
+        let trimmed = message.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else {
+            ShareGatewayRelaySettings.saveLastEvent("Share blocked: message is empty.")
+            self.showStatus("Message is empty.")
+            return
+        }
+
+        await MainActor.run {
+            self.isSending = true
+            self.sendButton.isEnabled = false
+            self.cancelButton.isEnabled = false
+        }
+        self.showStatus("Sending to OpenClaw gateway…")
+        ShareGatewayRelaySettings.saveLastEvent("Sending to gateway…")
+        do {
+            try await self.sendMessageToGateway(trimmed, attachments: self.pendingAttachments)
+            ShareGatewayRelaySettings.saveLastEvent(
+                "Sent to gateway (\(trimmed.count) chars, \(self.pendingAttachments.count) attachment(s)).")
+            self.showStatus("Sent to OpenClaw.")
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.45) {
+                self.extensionContext?.completeRequest(returningItems: nil)
+            }
+        } catch {
+            self.logger.error("share send failed reason=\(error.localizedDescription, privacy: .public)")
+            ShareGatewayRelaySettings.saveLastEvent("Send failed: \(error.localizedDescription)")
+            self.showStatus("Send failed: \(error.localizedDescription)")
+            await MainActor.run {
+                self.isSending = false
+                self.sendButton.isEnabled = true
+                self.cancelButton.isEnabled = true
+            }
+        }
+    }
+
+    private func sendMessageToGateway(_ message: String, attachments: [ShareAttachment]) async throws {
+        guard let config = ShareGatewayRelaySettings.loadConfig() else {
+            throw NSError(
+                domain: "OpenClawShare",
+                code: 10,
+                userInfo: [NSLocalizedDescriptionKey: "OpenClaw is not connected to a gateway yet."])
+        }
+        guard let url = URL(string: config.gatewayURLString) else {
+            throw NSError(
+                domain: "OpenClawShare",
+                code: 11,
+                userInfo: [NSLocalizedDescriptionKey: "Invalid saved gateway URL."])
+        }
+
+        let gateway = GatewayNodeSession()
+        defer {
+            Task { await gateway.disconnect() }
+        }
+        let makeOptions: (String) -> GatewayConnectOptions = { clientId in
+            GatewayConnectOptions(
+                role: "node",
+                scopes: [],
+                caps: [],
+                commands: [],
+                permissions: [:],
+                clientId: clientId,
+                clientMode: "node",
+                clientDisplayName: "OpenClaw Share",
+                includeDeviceIdentity: false)
+        }
+
+        do {
+            try await gateway.connect(
+                url: url,
+                token: config.token,
+                bootstrapToken: nil,
+                password: config.password,
+                connectOptions: makeOptions("openclaw-ios"),
+                sessionBox: nil,
+                onConnected: {},
+                onDisconnected: { _ in },
+                onInvoke: { req in
+                    BridgeInvokeResponse(
+                        id: req.id,
+                        ok: false,
+                        error: OpenClawNodeError(
+                            code: .invalidRequest,
+                            message: "share extension does not support node invoke"))
+                })
+        } catch {
+            let expectsLegacyClientId = self.shouldRetryWithLegacyClientId(error)
+            guard expectsLegacyClientId else { throw error }
+            try await gateway.connect(
+                url: url,
+                token: config.token,
+                bootstrapToken: nil,
+                password: config.password,
+                connectOptions: makeOptions("moltbot-ios"),
+                sessionBox: nil,
+                onConnected: {},
+                onDisconnected: { _ in },
+                onInvoke: { req in
+                    BridgeInvokeResponse(
+                        id: req.id,
+                        ok: false,
+                        error: OpenClawNodeError(
+                            code: .invalidRequest,
+                            message: "share extension does not support node invoke"))
+                })
+        }
+
+        struct AgentRequestPayload: Codable {
+            var message: String
+            var sessionKey: String?
+            var thinking: String
+            var deliver: Bool
+            var attachments: [ShareAttachment]?
+            var receipt: Bool
+            var receiptText: String?
+            var to: String?
+            var channel: String?
+            var timeoutSeconds: Int?
+            var key: String?
+        }
+
+        let deliveryChannel = config.deliveryChannel?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let deliveryTo = config.deliveryTo?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let canDeliverToRoute = (deliveryChannel?.isEmpty == false) && (deliveryTo?.isEmpty == false)
+
+        let params = AgentRequestPayload(
+            message: message,
+            sessionKey: config.sessionKey,
+            thinking: "low",
+            deliver: canDeliverToRoute,
+            attachments: attachments.isEmpty ? nil : attachments,
+            receipt: canDeliverToRoute,
+            receiptText: canDeliverToRoute ? "Just received your iOS share + request, working on it." : nil,
+            to: canDeliverToRoute ? deliveryTo : nil,
+            channel: canDeliverToRoute ? deliveryChannel : nil,
+            timeoutSeconds: nil,
+            key: UUID().uuidString)
+        let data = try JSONEncoder().encode(params)
+        guard let json = String(data: data, encoding: .utf8) else {
+            throw NSError(
+                domain: "OpenClawShare",
+                code: 12,
+                userInfo: [NSLocalizedDescriptionKey: "Failed to encode chat payload."])
+        }
+        struct NodeEventParams: Codable {
+            var event: String
+            var payloadJSON: String
+        }
+        let eventData = try JSONEncoder().encode(NodeEventParams(event: "agent.request", payloadJSON: json))
+        guard let nodeEventParams = String(data: eventData, encoding: .utf8) else {
+            throw NSError(
+                domain: "OpenClawShare",
+                code: 13,
+                userInfo: [NSLocalizedDescriptionKey: "Failed to encode node event payload."])
+        }
+        _ = try await gateway.request(method: "node.event", paramsJSON: nodeEventParams, timeoutSeconds: 25)
+    }
+
+    private func shouldRetryWithLegacyClientId(_ error: Error) -> Bool {
+        if let gatewayError = error as? GatewayResponseError {
+            let code = gatewayError.code.lowercased()
+            let message = gatewayError.message.lowercased()
+            let pathValue = (gatewayError.details["path"]?.value as? String)?.lowercased() ?? ""
+            let mentionsClientIdPath =
+                message.contains("/client/id") || message.contains("client id")
+                || pathValue.contains("/client/id")
+            let isInvalidConnectParams =
+                (code.contains("invalid") && code.contains("connect"))
+                || message.contains("invalid connect params")
+            if isInvalidConnectParams && mentionsClientIdPath {
+                return true
+            }
+        }
+
+        let text = error.localizedDescription.lowercased()
+        return text.contains("invalid connect params")
+            && (text.contains("/client/id") || text.contains("client id"))
+    }
+
+    private func showStatus(_ text: String) {
+        DispatchQueue.main.async {
+            let label: UILabel
+            if let existing = self.statusLabel {
+                label = existing
+            } else {
+                let newLabel = UILabel()
+                newLabel.translatesAutoresizingMaskIntoConstraints = false
+                newLabel.numberOfLines = 0
+                newLabel.textAlignment = .center
+                newLabel.font = .preferredFont(forTextStyle: .body)
+                newLabel.textColor = .label
+                newLabel.backgroundColor = UIColor.systemBackground.withAlphaComponent(0.92)
+                newLabel.layer.cornerRadius = 12
+                newLabel.clipsToBounds = true
+                newLabel.layoutMargins = UIEdgeInsets(top: 12, left: 14, bottom: 12, right: 14)
+                self.view.addSubview(newLabel)
+                NSLayoutConstraint.activate([
+                    newLabel.leadingAnchor.constraint(equalTo: self.view.leadingAnchor, constant: 18),
+                    newLabel.trailingAnchor.constraint(equalTo: self.view.trailingAnchor, constant: -18),
+                    newLabel.bottomAnchor.constraint(equalTo: self.sendButton.topAnchor, constant: -10),
+                ])
+                self.statusLabel = newLabel
+                label = newLabel
+            }
+            label.text = "  \(text)  "
+        }
+    }
+
+    private func composeDraft(from payload: SharedContentPayload) -> String {
+        var lines: [String] = []
+        let title = self.sanitizeDraftFragment(payload.title)
+        let text = self.sanitizeDraftFragment(payload.text)
+        let url = payload.url?.absoluteString.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+
+        if let title, !title.isEmpty { lines.append(title) }
+        if let text, !text.isEmpty { lines.append(text) }
+        if !url.isEmpty { lines.append(url) }
+
+        return lines.joined(separator: "\n\n")
+    }
+
+    private func sanitizeDraftFragment(_ raw: String?) -> String? {
+        guard let raw else { return nil }
+        let banned = [
+            "shared from ios.",
+            "text:",
+            "shared attachment(s):",
+            "please help me with this.",
+            "please help me with this.w",
+        ]
+        let cleanedLines = raw
+            .components(separatedBy: .newlines)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { line in
+                guard !line.isEmpty else { return false }
+                let lowered = line.lowercased()
+                return !banned.contains { lowered == $0 || lowered.hasPrefix($0) }
+            }
+        let cleaned = cleanedLines.joined(separator: "\n").trimmingCharacters(in: .whitespacesAndNewlines)
+        return cleaned.isEmpty ? nil : cleaned
+    }
+
+    private func extractSharedContent() async -> ExtractedShareContent {
+        guard let items = self.extensionContext?.inputItems as? [NSExtensionItem] else {
+            return ExtractedShareContent(
+                payload: SharedContentPayload(title: nil, url: nil, text: nil),
+                attachments: [])
+        }
+
+        var title: String?
+        var sharedURL: URL?
+        var sharedText: String?
+        var imageCount = 0
+        var videoCount = 0
+        var fileCount = 0
+        var unknownCount = 0
+        var attachments: [ShareAttachment] = []
+        let maxImageAttachments = 3
+
+        for item in items {
+            if title == nil {
+                title = item.attributedTitle?.string ?? item.attributedContentText?.string
+            }
+
+            for provider in item.attachments ?? [] {
+                if sharedURL == nil {
+                    sharedURL = await self.loadURL(from: provider)
+                }
+
+                if sharedText == nil {
+                    sharedText = await self.loadText(from: provider)
+                }
+
+                if provider.hasItemConformingToTypeIdentifier(UTType.image.identifier) {
+                    imageCount += 1
+                    if attachments.count < maxImageAttachments,
+                       let attachment = await self.loadImageAttachment(from: provider, index: attachments.count)
+                    {
+                        attachments.append(attachment)
+                    }
+                } else if provider.hasItemConformingToTypeIdentifier(UTType.movie.identifier) {
+                    videoCount += 1
+                } else if provider.hasItemConformingToTypeIdentifier(UTType.fileURL.identifier) {
+                    fileCount += 1
+                } else {
+                    unknownCount += 1
+                }
+
+            }
+        }
+
+        _ = imageCount
+        _ = videoCount
+        _ = fileCount
+        _ = unknownCount
+
+        return ExtractedShareContent(
+            payload: SharedContentPayload(title: title, url: sharedURL, text: sharedText),
+            attachments: attachments)
+    }
+
+    private func loadImageAttachment(from provider: NSItemProvider, index: Int) async -> ShareAttachment? {
+        let imageUTI = self.preferredImageTypeIdentifier(from: provider) ?? UTType.image.identifier
+        guard let rawData = await self.loadDataValue(from: provider, typeIdentifier: imageUTI) else {
+            return nil
+        }
+
+        let maxBytes = 5_000_000
+        guard let image = UIImage(data: rawData),
+              let data = self.normalizedJPEGData(from: image, maxBytes: maxBytes)
+        else {
+            return nil
+        }
+
+        return ShareAttachment(
+            type: "image",
+            mimeType: "image/jpeg",
+            fileName: "shared-image-\(index + 1).jpg",
+            content: data.base64EncodedString())
+    }
+
+    private func preferredImageTypeIdentifier(from provider: NSItemProvider) -> String? {
+        for identifier in provider.registeredTypeIdentifiers {
+            guard let utType = UTType(identifier) else { continue }
+            if utType.conforms(to: .image) {
+                return identifier
+            }
+        }
+        return nil
+    }
+
+    private func normalizedJPEGData(from image: UIImage, maxBytes: Int) -> Data? {
+        var quality: CGFloat = 0.9
+        while quality >= 0.4 {
+            if let data = image.jpegData(compressionQuality: quality), data.count <= maxBytes {
+                return data
+            }
+            quality -= 0.1
+        }
+        guard let fallback = image.jpegData(compressionQuality: 0.35) else { return nil }
+        if fallback.count <= maxBytes { return fallback }
+        return nil
+    }
+
+    private func loadURL(from provider: NSItemProvider) async -> URL? {
+        if provider.hasItemConformingToTypeIdentifier(UTType.url.identifier) {
+            if let url = await self.loadURLValue(
+                from: provider,
+                typeIdentifier: UTType.url.identifier)
+            {
+                return url
+            }
+        }
+
+        if provider.hasItemConformingToTypeIdentifier(UTType.text.identifier) {
+            if let text = await self.loadTextValue(from: provider, typeIdentifier: UTType.text.identifier),
+               let url = URL(string: text.trimmingCharacters(in: .whitespacesAndNewlines)),
+                   url.scheme != nil
+            {
+                return url
+            }
+        }
+
+        return nil
+    }
+
+    private func loadText(from provider: NSItemProvider) async -> String? {
+        if provider.hasItemConformingToTypeIdentifier(UTType.plainText.identifier) {
+            if let text = await self.loadTextValue(from: provider, typeIdentifier: UTType.plainText.identifier) {
+                return text
+            }
+        }
+
+        if provider.hasItemConformingToTypeIdentifier(UTType.url.identifier) {
+            if let url = await self.loadURLValue(from: provider, typeIdentifier: UTType.url.identifier) {
+                return url.absoluteString
+            }
+        }
+
+        return nil
+    }
+
+    private func loadURLValue(from provider: NSItemProvider, typeIdentifier: String) async -> URL? {
+        await withCheckedContinuation { continuation in
+            provider.loadItem(forTypeIdentifier: typeIdentifier, options: nil) { item, _ in
+                if let url = item as? URL {
+                    continuation.resume(returning: url)
+                    return
+                }
+                if let str = item as? String, let url = URL(string: str) {
+                    continuation.resume(returning: url)
+                    return
+                }
+                if let ns = item as? NSString, let url = URL(string: ns as String) {
+                    continuation.resume(returning: url)
+                    return
+                }
+                continuation.resume(returning: nil)
+            }
+        }
+    }
+
+    private func loadTextValue(from provider: NSItemProvider, typeIdentifier: String) async -> String? {
+        await withCheckedContinuation { continuation in
+            provider.loadItem(forTypeIdentifier: typeIdentifier, options: nil) { item, _ in
+                if let text = item as? String {
+                    continuation.resume(returning: text)
+                    return
+                }
+                if let text = item as? NSString {
+                    continuation.resume(returning: text as String)
+                    return
+                }
+                if let text = item as? NSAttributedString {
+                    continuation.resume(returning: text.string)
+                    return
+                }
+                continuation.resume(returning: nil)
+            }
+        }
+    }
+
+    private func loadDataValue(from provider: NSItemProvider, typeIdentifier: String) async -> Data? {
+        await withCheckedContinuation { continuation in
+            provider.loadDataRepresentation(forTypeIdentifier: typeIdentifier) { data, _ in
+                continuation.resume(returning: data)
+            }
+        }
+    }
+}
--- a/openclaw/apps/ios/Signing.xcconfig
+++ b/openclaw/apps/ios/Signing.xcconfig
@ -0,0 +1,22 @@
+// Default signing values for shared/repo builds.
+// Auto-selected local team overrides live in .local-signing.xcconfig (git-ignored).
+// Manual local overrides can go in LocalSigning.xcconfig (git-ignored).
+
+#include "Config/Version.xcconfig"
+
+OPENCLAW_CODE_SIGN_STYLE = Manual
+OPENCLAW_DEVELOPMENT_TEAM = Y5PE65HELJ
+
+OPENCLAW_APP_BUNDLE_ID = ai.openclaw.client
+OPENCLAW_SHARE_BUNDLE_ID = ai.openclaw.client.share
+OPENCLAW_WATCH_APP_BUNDLE_ID = ai.openclaw.client.watchkitapp
+OPENCLAW_WATCH_EXTENSION_BUNDLE_ID = ai.openclaw.client.watchkitapp.extension
+OPENCLAW_ACTIVITY_WIDGET_BUNDLE_ID = ai.openclaw.client.activitywidget
+
+OPENCLAW_APP_PROFILE = ai.openclaw.client Development
+OPENCLAW_SHARE_PROFILE = ai.openclaw.client.share Development
+
+// Keep local includes after defaults: xcconfig is evaluated top-to-bottom,
+// so later assignments in local files override the defaults above.
+#include? ".local-signing.xcconfig"
+#include? "LocalSigning.xcconfig"
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/100.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/100.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/102.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/102.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/1024.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/1024.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/108.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/108.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/114.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/114.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/120.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/120.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/172.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/172.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/180.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/180.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/196.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/196.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/216.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/216.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/234.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/234.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/258.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/258.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/29.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/29.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/40.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/40.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/48.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/48.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/55.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/55.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/57.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/57.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/58.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/58.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/60.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/60.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/66.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/66.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/80.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/80.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/87.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/87.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/88.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/88.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/92.png
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/92.png
--- a/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/Contents.json
+++ b/openclaw/apps/ios/Sources/Assets.xcassets/AppIcon.appiconset/Contents.json
@ -0,0 +1 @@
+{"images":[{"size":"60x60","expected-size":"180","filename":"180.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"3x"},{"size":"40x40","expected-size":"80","filename":"80.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"40x40","expected-size":"120","filename":"120.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"3x"},{"size":"60x60","expected-size":"120","filename":"120.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"57x57","expected-size":"57","filename":"57.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"1x"},{"size":"29x29","expected-size":"58","filename":"58.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"29x29","expected-size":"29","filename":"29.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"1x"},{"size":"29x29","expected-size":"87","filename":"87.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"3x"},{"size":"57x57","expected-size":"114","filename":"114.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"20x20","expected-size":"40","filename":"40.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"20x20","expected-size":"60","filename":"60.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"3x"},{"size":"1024x1024","filename":"1024.png","expected-size":"1024","idiom":"ios-marketing","folder":"Assets.xcassets/AppIcon.appiconset/","scale":"1x"},{"idiom":"watch","filename":"172.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"38mm","scale":"2x","size":"86x86","expected-size":"172","role":"quickLook"},{"idiom":"watch","filename":"80.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"38mm","scale":"2x","size":"40x40","expected-size":"80","role":"appLauncher"},{"idiom":"watch","filename":"88.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"40mm","scale":"2x","size":"44x44","expected-size":"88","role":"appLauncher"},{"idiom":"watch","filename":"102.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"45mm","scale":"2x","size":"51x51","expected-size":"102","role":"appLauncher"},{"idiom":"watch","filename":"108.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"49mm","scale":"2x","size":"54x54","expected-size":"108","role":"appLauncher"},{"idiom":"watch","filename":"92.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"41mm","scale":"2x","size":"46x46","expected-size":"92","role":"appLauncher"},{"idiom":"watch","filename":"100.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"44mm","scale":"2x","size":"50x50","expected-size":"100","role":"appLauncher"},{"idiom":"watch","filename":"196.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"42mm","scale":"2x","size":"98x98","expected-size":"196","role":"quickLook"},{"idiom":"watch","filename":"216.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"44mm","scale":"2x","size":"108x108","expected-size":"216","role":"quickLook"},{"idiom":"watch","filename":"234.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"45mm","scale":"2x","size":"117x117","expected-size":"234","role":"quickLook"},{"idiom":"watch","filename":"258.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"49mm","scale":"2x","size":"129x129","expected-size":"258","role":"quickLook"},{"idiom":"watch","filename":"48.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"38mm","scale":"2x","size":"24x24","expected-size":"48","role":"notificationCenter"},{"idiom":"watch","filename":"55.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"42mm","scale":"2x","size":"27.5x27.5","expected-size":"55","role":"notificationCenter"},{"idiom":"watch","filename":"66.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"45mm","scale":"2x","size":"33x33","expected-size":"66","role":"notificationCenter"},{"size":"29x29","expected-size":"87","filename":"87.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"watch","role":"companionSettings","scale":"3x"},{"size":"29x29","expected-size":"58","filename":"58.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"watch","role":"companionSettings","scale":"2x"},{"size":"1024x1024","expected-size":"1024","filename":"1024.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"watch-marketing","scale":"1x"}]}
--- a/openclaw/apps/ios/Sources/Calendar/CalendarService.swift
+++ b/openclaw/apps/ios/Sources/Calendar/CalendarService.swift
@ -0,0 +1,135 @@
+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 = EventKitAuthorization.allowsRead(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 = EventKitAuthorization.allowsWrite(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 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)
+    }
+}
--- a/openclaw/apps/ios/Sources/Camera/CameraController.swift
+++ b/openclaw/apps/ios/Sources/Camera/CameraController.swift
@ -0,0 +1,353 @@
+import AVFoundation
+import OpenClawKit
+import Foundation
+import os
+
+actor CameraController {
+    struct CameraDeviceInfo: Codable, Sendable {
+        var id: String
+        var name: String
+        var position: String
+        var deviceType: String
+    }
+
+    enum CameraError: LocalizedError, Sendable {
+        case cameraUnavailable
+        case microphoneUnavailable
+        case permissionDenied(kind: String)
+        case invalidParams(String)
+        case captureFailed(String)
+        case exportFailed(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .cameraUnavailable:
+                "Camera unavailable"
+            case .microphoneUnavailable:
+                "Microphone unavailable"
+            case let .permissionDenied(kind):
+                "\(kind) permission denied"
+            case let .invalidParams(msg):
+                msg
+            case let .captureFailed(msg):
+                msg
+            case let .exportFailed(msg):
+                msg
+            }
+        }
+    }
+
+    func snap(params: OpenClawCameraSnapParams) async throws -> (
+        format: String,
+        base64: String,
+        width: Int,
+        height: Int)
+    {
+        let facing = params.facing ?? .front
+        let format = params.format ?? .jpg
+        // Default to a reasonable max width to keep gateway payload sizes manageable.
+        // If you need the full-res photo, explicitly request a larger maxWidth.
+        let maxWidth = params.maxWidth.flatMap { $0 > 0 ? $0 : nil } ?? 1600
+        let quality = Self.clampQuality(params.quality)
+        let delayMs = max(0, params.delayMs ?? 0)
+
+        try await self.ensureAccess(for: .video)
+
+        let prepared = try CameraCapturePipelineSupport.preparePhotoSession(
+            preferFrontCamera: facing == .front,
+            deviceId: params.deviceId,
+            pickCamera: { preferFrontCamera, deviceId in
+                Self.pickCamera(facing: preferFrontCamera ? .front : .back, deviceId: deviceId)
+            },
+            cameraUnavailableError: CameraError.cameraUnavailable,
+            mapSetupError: { setupError in
+                CameraError.captureFailed(setupError.localizedDescription)
+            })
+        let session = prepared.session
+        let output = prepared.output
+
+        session.startRunning()
+        defer { session.stopRunning() }
+        await CameraCapturePipelineSupport.warmUpCaptureSession()
+        await Self.sleepDelayMs(delayMs)
+
+        let rawData = try await CameraCapturePipelineSupport.capturePhotoData(output: output) { continuation in
+            PhotoCaptureDelegate(continuation)
+        }
+
+        let res = try PhotoCapture.transcodeJPEGForGateway(
+            rawData: rawData,
+            maxWidthPx: maxWidth,
+            quality: quality)
+
+        return (
+            format: format.rawValue,
+            base64: res.data.base64EncodedString(),
+            width: res.widthPx,
+            height: res.heightPx)
+    }
+
+    func clip(params: OpenClawCameraClipParams) async throws -> (
+        format: String,
+        base64: String,
+        durationMs: Int,
+        hasAudio: Bool)
+    {
+        let facing = params.facing ?? .front
+        let durationMs = Self.clampDurationMs(params.durationMs)
+        let includeAudio = params.includeAudio ?? true
+        let format = params.format ?? .mp4
+
+        try await self.ensureAccess(for: .video)
+        if includeAudio {
+            try await self.ensureAccess(for: .audio)
+        }
+
+        let movURL = FileManager().temporaryDirectory
+            .appendingPathComponent("openclaw-camera-\(UUID().uuidString).mov")
+        let mp4URL = FileManager().temporaryDirectory
+            .appendingPathComponent("openclaw-camera-\(UUID().uuidString).mp4")
+        defer {
+            try? FileManager().removeItem(at: movURL)
+            try? FileManager().removeItem(at: mp4URL)
+        }
+
+        let data = try await CameraCapturePipelineSupport.withWarmMovieSession(
+            preferFrontCamera: facing == .front,
+            deviceId: params.deviceId,
+            includeAudio: includeAudio,
+            durationMs: durationMs,
+            pickCamera: { preferFrontCamera, deviceId in
+                Self.pickCamera(facing: preferFrontCamera ? .front : .back, deviceId: deviceId)
+            },
+            cameraUnavailableError: CameraError.cameraUnavailable,
+            mapSetupError: Self.mapMovieSetupError,
+            operation: { output in
+                var delegate: MovieFileDelegate?
+                let recordedURL: URL = try await withCheckedThrowingContinuation { cont in
+                    let d = MovieFileDelegate(cont)
+                    delegate = d
+                    output.startRecording(to: movURL, recordingDelegate: d)
+                }
+                withExtendedLifetime(delegate) {}
+                // Transcode .mov -> .mp4 for easier downstream handling.
+                try await Self.exportToMP4(inputURL: recordedURL, outputURL: mp4URL)
+                return try Data(contentsOf: mp4URL)
+            })
+        return (
+            format: format.rawValue,
+            base64: data.base64EncodedString(),
+            durationMs: durationMs,
+            hasAudio: includeAudio)
+    }
+
+    func listDevices() -> [CameraDeviceInfo] {
+        return Self.discoverVideoDevices().map { device in
+            CameraDeviceInfo(
+                id: device.uniqueID,
+                name: device.localizedName,
+                position: Self.positionLabel(device.position),
+                deviceType: device.deviceType.rawValue)
+        }
+    }
+
+    private func ensureAccess(for mediaType: AVMediaType) async throws {
+        if !(await CameraAuthorization.isAuthorized(for: mediaType)) {
+            throw CameraError.permissionDenied(kind: mediaType == .video ? "Camera" : "Microphone")
+        }
+    }
+
+    private nonisolated static func pickCamera(
+        facing: OpenClawCameraFacing,
+        deviceId: String?) -> AVCaptureDevice?
+    {
+        if let deviceId, !deviceId.isEmpty {
+            if let match = Self.discoverVideoDevices().first(where: { $0.uniqueID == deviceId }) {
+                return match
+            }
+        }
+        let position: AVCaptureDevice.Position = (facing == .front) ? .front : .back
+        if let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: position) {
+            return device
+        }
+        // Fall back to any default camera (e.g. simulator / unusual device configurations).
+        return AVCaptureDevice.default(for: .video)
+    }
+
+    private nonisolated static func mapMovieSetupError(_ setupError: CameraSessionConfigurationError) -> CameraError {
+        CameraCapturePipelineSupport.mapMovieSetupError(
+            setupError,
+            microphoneUnavailableError: .microphoneUnavailable,
+            captureFailed: { .captureFailed($0) })
+    }
+
+    private nonisolated static func positionLabel(_ position: AVCaptureDevice.Position) -> String {
+        CameraCapturePipelineSupport.positionLabel(position)
+    }
+
+    private nonisolated static func discoverVideoDevices() -> [AVCaptureDevice] {
+        let types: [AVCaptureDevice.DeviceType] = [
+            .builtInWideAngleCamera,
+            .builtInUltraWideCamera,
+            .builtInTelephotoCamera,
+            .builtInDualCamera,
+            .builtInDualWideCamera,
+            .builtInTripleCamera,
+            .builtInTrueDepthCamera,
+            .builtInLiDARDepthCamera,
+        ]
+        let session = AVCaptureDevice.DiscoverySession(
+            deviceTypes: types,
+            mediaType: .video,
+            position: .unspecified)
+        return session.devices
+    }
+
+    nonisolated static func clampQuality(_ quality: Double?) -> Double {
+        let q = quality ?? 0.9
+        return min(1.0, max(0.05, q))
+    }
+
+    nonisolated static func clampDurationMs(_ ms: Int?) -> Int {
+        let v = ms ?? 3000
+        // Keep clips short by default; avoid huge base64 payloads on the gateway.
+        return min(60000, max(250, v))
+    }
+
+    private nonisolated static func exportToMP4(inputURL: URL, outputURL: URL) async throws {
+        let asset = AVURLAsset(url: inputURL)
+        guard let exporter = AVAssetExportSession(asset: asset, presetName: AVAssetExportPresetMediumQuality) else {
+            throw CameraError.exportFailed("Failed to create export session")
+        }
+        exporter.shouldOptimizeForNetworkUse = true
+
+        if #available(iOS 18.0, tvOS 18.0, visionOS 2.0, *) {
+            do {
+                try await exporter.export(to: outputURL, as: .mp4)
+                return
+            } catch {
+                throw CameraError.exportFailed(error.localizedDescription)
+            }
+        } else {
+            exporter.outputURL = outputURL
+            exporter.outputFileType = .mp4
+
+            try await withCheckedThrowingContinuation(isolation: nil) { (cont: CheckedContinuation<Void, Error>) in
+                exporter.exportAsynchronously {
+                    cont.resume(returning: ())
+                }
+            }
+
+            switch exporter.status {
+            case .completed:
+                return
+            case .failed:
+                throw CameraError.exportFailed(exporter.error?.localizedDescription ?? "export failed")
+            case .cancelled:
+                throw CameraError.exportFailed("export cancelled")
+            default:
+                throw CameraError.exportFailed("export did not complete")
+            }
+        }
+    }
+
+    private nonisolated static func sleepDelayMs(_ delayMs: Int) async {
+        guard delayMs > 0 else { return }
+        let maxDelayMs = 10 * 1000
+        let ns = UInt64(min(delayMs, maxDelayMs)) * UInt64(NSEC_PER_MSEC)
+        try? await Task.sleep(nanoseconds: ns)
+    }
+}
+
+private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegate {
+    private let continuation: CheckedContinuation<Data, Error>
+    private let resumed = OSAllocatedUnfairLock(initialState: false)
+
+    init(_ continuation: CheckedContinuation<Data, Error>) {
+        self.continuation = continuation
+    }
+
+    func photoOutput(
+        _ output: AVCapturePhotoOutput,
+        didFinishProcessingPhoto photo: AVCapturePhoto,
+        error: Error?
+    ) {
+        let alreadyResumed = self.resumed.withLock { old in
+            let was = old
+            old = true
+            return was
+        }
+        guard !alreadyResumed else { return }
+
+        if let error {
+            self.continuation.resume(throwing: error)
+            return
+        }
+        guard let data = photo.fileDataRepresentation() else {
+            self.continuation.resume(
+                throwing: NSError(domain: "Camera", code: 1, userInfo: [
+                    NSLocalizedDescriptionKey: "photo data missing",
+                ]))
+            return
+        }
+        if data.isEmpty {
+            self.continuation.resume(
+                throwing: NSError(domain: "Camera", code: 2, userInfo: [
+                    NSLocalizedDescriptionKey: "photo data empty",
+                ]))
+            return
+        }
+        self.continuation.resume(returning: data)
+    }
+
+    func photoOutput(
+        _ output: AVCapturePhotoOutput,
+        didFinishCaptureFor resolvedSettings: AVCaptureResolvedPhotoSettings,
+        error: Error?
+    ) {
+        guard let error else { return }
+        let alreadyResumed = self.resumed.withLock { old in
+            let was = old
+            old = true
+            return was
+        }
+        guard !alreadyResumed else { return }
+        self.continuation.resume(throwing: error)
+    }
+}
+
+private final class MovieFileDelegate: NSObject, AVCaptureFileOutputRecordingDelegate {
+    private let continuation: CheckedContinuation<URL, Error>
+    private let resumed = OSAllocatedUnfairLock(initialState: false)
+
+    init(_ continuation: CheckedContinuation<URL, Error>) {
+        self.continuation = continuation
+    }
+
+    func fileOutput(
+        _ output: AVCaptureFileOutput,
+        didFinishRecordingTo outputFileURL: URL,
+        from connections: [AVCaptureConnection],
+        error: Error?)
+    {
+        let alreadyResumed = self.resumed.withLock { old in
+            let was = old
+            old = true
+            return was
+        }
+        guard !alreadyResumed else { return }
+
+        if let error {
+            let ns = error as NSError
+            if ns.domain == AVFoundationErrorDomain,
+               ns.code == AVError.maximumDurationReached.rawValue
+            {
+                self.continuation.resume(returning: outputFileURL)
+                return
+            }
+            self.continuation.resume(throwing: error)
+            return
+        }
+        self.continuation.resume(returning: outputFileURL)
+    }
+}
--- a/openclaw/apps/ios/Sources/Capabilities/NodeCapabilityRouter.swift
+++ b/openclaw/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)
+    }
+}
--- a/openclaw/apps/ios/Sources/Chat/ChatSheet.swift
+++ b/openclaw/apps/ios/Sources/Chat/ChatSheet.swift
@ -0,0 +1,47 @@
+import OpenClawChatUI
+import OpenClawKit
+import SwiftUI
+
+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, 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 {
+        NavigationStack {
+            OpenClawChatView(
+                viewModel: self.viewModel,
+                showsSessionSwitcher: true,
+                userAccent: self.userAccent)
+                .navigationTitle(self.chatTitle)
+                .navigationBarTitleDisplayMode(.inline)
+                .toolbar {
+                    ToolbarItem(placement: .topBarTrailing) {
+                        Button {
+                            self.dismiss()
+                        } label: {
+                            Image(systemName: "xmark")
+                        }
+                        .accessibilityLabel("Close")
+                    }
+                }
+        }
+    }
+
+    private var chatTitle: String {
+        let trimmed = (self.agentName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return "Chat" }
+        return "Chat (\(trimmed))"
+    }
+}
--- a/openclaw/apps/ios/Sources/Chat/IOSGatewayChatTransport.swift
+++ b/openclaw/apps/ios/Sources/Chat/IOSGatewayChatTransport.swift
@ -0,0 +1,156 @@
+import OpenClawChatUI
+import OpenClawKit
+import OpenClawProtocol
+import Foundation
+import OSLog
+
+struct IOSGatewayChatTransport: OpenClawChatTransport, Sendable {
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "ios.chat.transport")
+    private let gateway: GatewayNodeSession
+
+    init(gateway: GatewayNodeSession) {
+        self.gateway = gateway
+    }
+
+    func abortRun(sessionKey: String, runId: String) async throws {
+        struct Params: Codable {
+            var sessionKey: String
+            var runId: String
+        }
+        let data = try JSONEncoder().encode(Params(sessionKey: sessionKey, runId: runId))
+        let json = String(data: data, encoding: .utf8)
+        _ = try await self.gateway.request(method: "chat.abort", paramsJSON: json, timeoutSeconds: 10)
+    }
+
+    func listSessions(limit: Int?) async throws -> OpenClawChatSessionsListResponse {
+        struct Params: Codable {
+            var includeGlobal: Bool
+            var includeUnknown: Bool
+            var limit: Int?
+        }
+        let data = try JSONEncoder().encode(Params(includeGlobal: true, includeUnknown: false, limit: limit))
+        let json = String(data: data, encoding: .utf8)
+        let res = try await self.gateway.request(method: "sessions.list", paramsJSON: json, timeoutSeconds: 15)
+        return try JSONDecoder().decode(OpenClawChatSessionsListResponse.self, from: res)
+    }
+
+    func setActiveSessionKey(_ sessionKey: String) async throws {
+        // Operator clients receive chat events without node-style subscriptions.
+        // (chat.subscribe is a node event, not an operator RPC method.)
+    }
+
+    func resetSession(sessionKey: String) async throws {
+        struct Params: Codable { var key: String }
+        let data = try JSONEncoder().encode(Params(key: sessionKey))
+        let json = String(data: data, encoding: .utf8)
+        _ = try await self.gateway.request(method: "sessions.reset", paramsJSON: json, timeoutSeconds: 10)
+    }
+
+    func compactSession(sessionKey: String) async throws {
+        struct Params: Codable { var key: String }
+        let data = try JSONEncoder().encode(Params(key: sessionKey))
+        let json = String(data: data, encoding: .utf8)
+        _ = try await self.gateway.request(method: "sessions.compact", paramsJSON: json, timeoutSeconds: 10)
+    }
+
+    func requestHistory(sessionKey: String) async throws -> OpenClawChatHistoryPayload {
+        struct Params: Codable { var sessionKey: String }
+        let data = try JSONEncoder().encode(Params(sessionKey: sessionKey))
+        let json = String(data: data, encoding: .utf8)
+        let res = try await self.gateway.request(method: "chat.history", paramsJSON: json, timeoutSeconds: 15)
+        return try JSONDecoder().decode(OpenClawChatHistoryPayload.self, from: res)
+    }
+
+    func sendMessage(
+        sessionKey: String,
+        message: String,
+        thinking: String,
+        idempotencyKey: String,
+        attachments: [OpenClawChatAttachmentPayload]) async throws -> OpenClawChatSendResponse
+    {
+        let startLogMessage =
+            "chat.send start sessionKey=\(sessionKey) "
+            + "len=\(message.count) attachments=\(attachments.count)"
+        Self.logger.info(
+            "\(startLogMessage, privacy: .public)"
+        )
+        struct Params: Codable {
+            var sessionKey: String
+            var message: String
+            var thinking: String
+            var attachments: [OpenClawChatAttachmentPayload]?
+            var timeoutMs: Int
+            var idempotencyKey: String
+        }
+
+        let params = Params(
+            sessionKey: sessionKey,
+            message: message,
+            thinking: thinking,
+            attachments: attachments.isEmpty ? nil : attachments,
+            timeoutMs: 30000,
+            idempotencyKey: idempotencyKey)
+        let data = try JSONEncoder().encode(params)
+        let json = String(data: data, encoding: .utf8)
+        do {
+            let res = try await self.gateway.request(method: "chat.send", paramsJSON: json, timeoutSeconds: 35)
+            let decoded = try JSONDecoder().decode(OpenClawChatSendResponse.self, from: res)
+            Self.logger.info("chat.send ok runId=\(decoded.runId, privacy: .public)")
+            return decoded
+        } catch {
+            Self.logger.error("chat.send failed \(error.localizedDescription, privacy: .public)")
+            throw error
+        }
+    }
+
+    func requestHealth(timeoutMs: Int) async throws -> Bool {
+        let seconds = max(1, Int(ceil(Double(timeoutMs) / 1000.0)))
+        let res = try await self.gateway.request(method: "health", paramsJSON: nil, timeoutSeconds: seconds)
+        return (try? JSONDecoder().decode(OpenClawGatewayHealthOK.self, from: res))?.ok ?? true
+    }
+
+    func events() -> AsyncStream<OpenClawChatTransportEvent> {
+        AsyncStream { continuation in
+            let task = Task {
+                let stream = await self.gateway.subscribeServerEvents()
+                for await evt in stream {
+                    if Task.isCancelled { return }
+                    switch evt.event {
+                    case "tick":
+                        continuation.yield(.tick)
+                    case "seqGap":
+                        continuation.yield(.seqGap)
+                    case "health":
+                        guard let payload = evt.payload else { break }
+                        let ok = (try? GatewayPayloadDecoding.decode(
+                            payload,
+                            as: OpenClawGatewayHealthOK.self))?.ok ?? true
+                        continuation.yield(.health(ok: ok))
+                    case "chat":
+                        guard let payload = evt.payload else { break }
+                        if let chatPayload = try? GatewayPayloadDecoding.decode(
+                            payload,
+                            as: OpenClawChatEventPayload.self)
+                        {
+                            continuation.yield(.chat(chatPayload))
+                        }
+                    case "agent":
+                        guard let payload = evt.payload else { break }
+                        if let agentPayload = try? GatewayPayloadDecoding.decode(
+                            payload,
+                            as: OpenClawAgentEventPayload.self)
+                        {
+                            continuation.yield(.agent(agentPayload))
+                        }
+                    default:
+                        break
+                    }
+                }
+            }
+
+            continuation.onTermination = { @Sendable _ in
+                task.cancel()
+            }
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Contacts/ContactsService.swift
+++ b/openclaw/apps/ios/Sources/Contacts/ContactsService.swift
@ -0,0 +1,210 @@
+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 = try await Self.authorizedStore()
+
+        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 = try await Self.authorizedStore()
+
+        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 authorizedStore() async throws -> CNContactStore {
+        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",
+            ])
+        }
+        return store
+    }
+
+    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
+}
--- a/openclaw/apps/ios/Sources/Device/DeviceInfoHelper.swift
+++ b/openclaw/apps/ios/Sources/Device/DeviceInfoHelper.swift
@ -0,0 +1,75 @@
+import Foundation
+import UIKit
+
+import Darwin
+
+/// Shared device and platform info for Settings, gateway node payloads, and device status.
+enum DeviceInfoHelper {
+    /// e.g. "iOS 18.0.0" or "iPadOS 18.0.0" by interface idiom. Use for gateway/device payloads.
+    @MainActor
+    static func platformString() -> String {
+        let v = ProcessInfo.processInfo.operatingSystemVersion
+        let name = switch UIDevice.current.userInterfaceIdiom {
+        case .pad:
+            "iPadOS"
+        case .phone:
+            "iOS"
+        default:
+            "iOS"
+        }
+        return "\(name) \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
+    }
+
+    /// Always "iOS X.Y.Z" for UI display (e.g. Settings), matching legacy behavior on iPad.
+    static func platformStringForDisplay() -> String {
+        let v = ProcessInfo.processInfo.operatingSystemVersion
+        return "iOS \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
+    }
+
+    /// Device family for display: "iPad", "iPhone", or "iOS".
+    @MainActor
+    static func deviceFamily() -> String {
+        switch UIDevice.current.userInterfaceIdiom {
+        case .pad:
+            "iPad"
+        case .phone:
+            "iPhone"
+        default:
+            "iOS"
+        }
+    }
+
+    /// Machine model identifier from uname (e.g. "iPhone17,1").
+    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
+    }
+
+    /// Canonical app version when present, otherwise the Apple marketing version.
+    static func appVersion() -> String {
+        (Bundle.main.infoDictionary?["OpenClawCanonicalVersion"] as? String)
+            ?? (Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String)
+            ?? "dev"
+    }
+
+    /// App build string, e.g. "123" or "".
+    static func appBuild() -> String {
+        let raw = Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? ""
+        return raw.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    /// Display string for Settings: "1.2.3" or "1.2.3 (456)" when build differs.
+    static func openClawVersionString() -> String {
+        let version = appVersion()
+        let build = appBuild()
+        if build.isEmpty || build == version {
+            return version
+        }
+        return "\(version) (\(build))"
+    }
+}
--- a/openclaw/apps/ios/Sources/Device/DeviceStatusService.swift
+++ b/openclaw/apps/ios/Sources/Device/DeviceStatusService.swift
@ -0,0 +1,83 @@
+import Foundation
+import OpenClawKit
+import UIKit
+
+@MainActor
+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 = DeviceInfoHelper.appVersion()
+        let appBuild = DeviceStatusService.fallbackAppBuild(DeviceInfoHelper.appBuild())
+        let locale = Locale.preferredLanguages.first ?? Locale.current.identifier
+        return OpenClawDeviceInfoPayload(
+            deviceName: device.name,
+            modelIdentifier: DeviceInfoHelper.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)
+    }
+
+    /// Fallback for payloads that require a non-empty build (e.g. "0").
+    private static func fallbackAppBuild(_ build: String) -> String {
+        build.isEmpty ? "0" : build
+    }
+}
--- a/openclaw/apps/ios/Sources/Device/NetworkStatusService.swift
+++ b/openclaw/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: "ai.openclaw.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
+    }
+}
--- a/openclaw/apps/ios/Sources/Device/NodeDisplayName.swift
+++ b/openclaw/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
+    }
+}
--- a/openclaw/apps/ios/Sources/EventKit/EventKitAuthorization.swift
+++ b/openclaw/apps/ios/Sources/EventKit/EventKitAuthorization.swift
@ -0,0 +1,34 @@
+import EventKit
+
+enum EventKitAuthorization {
+    static func allowsRead(status: EKAuthorizationStatus) -> Bool {
+        switch status {
+        case .authorized, .fullAccess:
+            return true
+        case .writeOnly:
+            return false
+        case .notDetermined:
+            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
+            return false
+        case .restricted, .denied:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+
+    static func allowsWrite(status: EKAuthorizationStatus) -> Bool {
+        switch status {
+        case .authorized, .fullAccess, .writeOnly:
+            return true
+        case .notDetermined:
+            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
+            return false
+        case .restricted, .denied:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+}
+
--- a/openclaw/apps/ios/Sources/Gateway/DeepLinkAgentPromptAlert.swift
+++ b/openclaw/apps/ios/Sources/Gateway/DeepLinkAgentPromptAlert.swift
@ -0,0 +1,40 @@
+import SwiftUI
+
+struct DeepLinkAgentPromptAlert: ViewModifier {
+    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+
+    private var promptBinding: Binding<NodeAppModel.AgentDeepLinkPrompt?> {
+        Binding(
+            get: { self.appModel.pendingAgentDeepLinkPrompt },
+            set: { _ in
+                // Keep prompt state until explicit user action.
+            })
+    }
+
+    func body(content: Content) -> some View {
+        content.alert(item: self.promptBinding) { prompt in
+            Alert(
+                title: Text("Run OpenClaw agent?"),
+                message: Text(
+                    """
+                    Message:
+                    \(prompt.messagePreview)
+
+                    URL:
+                    \(prompt.urlPreview)
+                    """),
+                primaryButton: .cancel(Text("Cancel")) {
+                    self.appModel.declinePendingAgentDeepLinkPrompt()
+                },
+                secondaryButton: .default(Text("Run")) {
+                    Task { await self.appModel.approvePendingAgentDeepLinkPrompt() }
+                })
+        }
+    }
+}
+
+extension View {
+    func deepLinkAgentPromptAlert() -> some View {
+        self.modifier(DeepLinkAgentPromptAlert())
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/ExecApprovalPromptDialog.swift
+++ b/openclaw/apps/ios/Sources/Gateway/ExecApprovalPromptDialog.swift
@ -0,0 +1,196 @@
+import SwiftUI
+
+private struct ExecApprovalPromptDialogModifier: ViewModifier {
+    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+    @Environment(\.colorScheme) private var colorScheme
+
+    func body(content: Content) -> some View {
+        content
+            .overlay {
+                if let prompt = self.appModel.pendingExecApprovalPrompt {
+                    ZStack {
+                        Color.black.opacity(0.38)
+                            .ignoresSafeArea()
+
+                        ExecApprovalPromptCard(
+                            prompt: prompt,
+                            isResolving: self.appModel.pendingExecApprovalPromptResolving,
+                            errorText: self.appModel.pendingExecApprovalPromptErrorText,
+                            brighten: self.colorScheme == .light,
+                            onAllowOnce: {
+                                Task {
+                                    await self.appModel.resolvePendingExecApprovalPrompt(decision: "allow-once")
+                                }
+                            },
+                            onAllowAlways: {
+                                Task {
+                                    await self.appModel.resolvePendingExecApprovalPrompt(decision: "allow-always")
+                                }
+                            },
+                            onDeny: {
+                                Task {
+                                    await self.appModel.resolvePendingExecApprovalPrompt(decision: "deny")
+                                }
+                            },
+                            onCancel: {
+                                self.appModel.dismissPendingExecApprovalPrompt()
+                            })
+                            .padding(.horizontal, 20)
+                            .frame(maxWidth: 460)
+                            .transition(.scale(scale: 0.98).combined(with: .opacity))
+                    }
+                    .zIndex(1)
+                }
+            }
+            .animation(.easeInOut(duration: 0.18), value: self.appModel.pendingExecApprovalPrompt?.id)
+    }
+}
+
+private struct ExecApprovalPromptCard: View {
+    let prompt: NodeAppModel.ExecApprovalPrompt
+    let isResolving: Bool
+    let errorText: String?
+    let brighten: Bool
+    let onAllowOnce: () -> Void
+    let onAllowAlways: () -> Void
+    let onDeny: () -> Void
+    let onCancel: () -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 14) {
+            VStack(alignment: .leading, spacing: 6) {
+                Text("Exec approval required")
+                    .font(.headline)
+                Text("OpenClaw opened from a notification. Review this exec request before continuing.")
+                    .font(.subheadline)
+                    .foregroundStyle(.secondary)
+            }
+
+            Text(self.prompt.commandText)
+                .font(.system(size: 15, weight: .regular, design: .monospaced))
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(10)
+                .background(.black.opacity(0.14), in: RoundedRectangle(cornerRadius: 12, style: .continuous))
+
+            VStack(alignment: .leading, spacing: 8) {
+                if let host = self.normalized(self.prompt.host) {
+                    ExecApprovalPromptMetadataRow(label: "Host", value: host)
+                }
+                if let nodeId = self.normalized(self.prompt.nodeId) {
+                    ExecApprovalPromptMetadataRow(label: "Node", value: nodeId)
+                }
+                if let agentId = self.normalized(self.prompt.agentId) {
+                    ExecApprovalPromptMetadataRow(label: "Agent", value: agentId)
+                }
+                if let expiresText = self.expiresText(self.prompt.expiresAtMs) {
+                    ExecApprovalPromptMetadataRow(label: "Expires", value: expiresText)
+                }
+            }
+
+            if let errorText = self.normalized(self.errorText) {
+                Text(errorText)
+                    .font(.footnote)
+                    .foregroundStyle(.red)
+            }
+
+            if self.isResolving {
+                HStack(spacing: 8) {
+                    ProgressView()
+                        .progressViewStyle(.circular)
+                    Text("Resolving…")
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+            }
+
+            VStack(spacing: 10) {
+                Button {
+                    self.onAllowOnce()
+                } label: {
+                    Text("Allow Once")
+                        .frame(maxWidth: .infinity)
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(self.isResolving)
+
+                if self.prompt.allowsAllowAlways {
+                    Button {
+                        self.onAllowAlways()
+                    } label: {
+                        Text("Allow Always")
+                            .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.isResolving)
+                }
+
+                HStack(spacing: 10) {
+                    Button(role: .destructive) {
+                        self.onDeny()
+                    } label: {
+                        Text("Deny")
+                            .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.isResolving)
+
+                    Button(role: .cancel) {
+                        self.onCancel()
+                    } label: {
+                        Text("Cancel")
+                            .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.isResolving)
+                }
+            }
+            .controlSize(.large)
+            .frame(maxWidth: .infinity)
+        }
+        .statusGlassCard(brighten: self.brighten, verticalPadding: 18, horizontalPadding: 18)
+    }
+
+    private func normalized(_ value: String?) -> String? {
+        let trimmed = (value ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private func expiresText(_ expiresAtMs: Int?) -> String? {
+        guard let expiresAtMs else { return nil }
+        let remainingSeconds = Int((Double(expiresAtMs) / 1000.0) - Date().timeIntervalSince1970)
+        if remainingSeconds <= 0 {
+            return "expired"
+        }
+        if remainingSeconds < 60 {
+            return "under a minute"
+        }
+        if remainingSeconds < 3600 {
+            let minutes = Int(ceil(Double(remainingSeconds) / 60.0))
+            return minutes == 1 ? "about 1 minute" : "about \(minutes) minutes"
+        }
+        let hours = Int(ceil(Double(remainingSeconds) / 3600.0))
+        return hours == 1 ? "about 1 hour" : "about \(hours) hours"
+    }
+}
+
+private struct ExecApprovalPromptMetadataRow: View {
+    let label: String
+    let value: String
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 2) {
+            Text(self.label)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            Text(self.value)
+                .font(.footnote)
+                .textSelection(.enabled)
+        }
+    }
+}
+
+extension View {
+    func execApprovalPromptDialog() -> some View {
+        self.modifier(ExecApprovalPromptDialogModifier())
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayConnectConfig.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayConnectConfig.swift
@ -0,0 +1,28 @@
+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 bootstrapToken: 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
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayConnectionController.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayConnectionController.swift
--- a/openclaw/apps/ios/Sources/Gateway/GatewayConnectionIssue.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayConnectionIssue.swift
@ -0,0 +1,103 @@
+import Foundation
+import OpenClawKit
+
+enum GatewayConnectionIssue: Equatable {
+    case none
+    case tokenMissing
+    case unauthorized
+    case pairingRequired(requestId: String?)
+    case network
+    case unknown(String)
+
+    var requestId: String? {
+        if case let .pairingRequired(requestId) = self {
+            return requestId
+        }
+        return nil
+    }
+
+    var needsAuthToken: Bool {
+        switch self {
+        case .tokenMissing, .unauthorized:
+            return true
+        default:
+            return false
+        }
+    }
+
+    var needsPairing: Bool {
+        if case .pairingRequired = self { return true }
+        return false
+    }
+
+    static func detect(problem: GatewayConnectionProblem?) -> Self {
+        guard let problem else { return .none }
+        if problem.needsPairingApproval {
+            return .pairingRequired(requestId: problem.requestId)
+        }
+        if problem.needsCredentialUpdate {
+            return problem.kind == .gatewayAuthTokenMissing ? .tokenMissing : .unauthorized
+        }
+        switch problem.kind {
+        case .deviceIdentityRequired,
+            .deviceSignatureExpired,
+            .deviceNonceRequired,
+            .deviceNonceMismatch,
+            .deviceSignatureInvalid,
+            .devicePublicKeyInvalid,
+            .deviceIdMismatch,
+            .tailscaleIdentityMissing,
+            .tailscaleProxyMissing,
+            .tailscaleWhoisFailed,
+            .tailscaleIdentityMismatch,
+            .authRateLimited:
+            return .unauthorized
+        case .timeout, .connectionRefused, .reachabilityFailed, .websocketCancelled:
+            return .network
+        case .unknown:
+            return .unknown(problem.message)
+        default:
+            return .none
+        }
+    }
+
+    static func detect(from statusText: String) -> Self {
+        let trimmed = statusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return .none }
+        let lower = trimmed.lowercased()
+
+        if lower.contains("pairing required") || lower.contains("not_paired") || lower.contains("not paired") {
+            return .pairingRequired(requestId: self.extractRequestId(from: trimmed))
+        }
+        if lower.contains("gateway token missing") {
+            return .tokenMissing
+        }
+        if lower.contains("unauthorized") {
+            return .unauthorized
+        }
+        if lower.contains("connection refused") ||
+            lower.contains("timed out") ||
+            lower.contains("network is unreachable") ||
+            lower.contains("cannot find host") ||
+            lower.contains("could not connect")
+        {
+            return .network
+        }
+        if lower.hasPrefix("gateway error:") {
+            return .unknown(trimmed)
+        }
+        return .none
+    }
+
+    private static func extractRequestId(from statusText: String) -> String? {
+        let marker = "requestId:"
+        guard let range = statusText.range(of: marker) else { return nil }
+        let suffix = statusText[range.upperBound...]
+        let trimmed = suffix.trimmingCharacters(in: .whitespacesAndNewlines)
+        let end = trimmed.firstIndex(where: { ch in
+            ch == ")" || ch.isWhitespace || ch == "," || ch == ";"
+        }) ?? trimmed.endIndex
+        let id = String(trimmed[..<end]).trimmingCharacters(in: .whitespacesAndNewlines)
+        return id.isEmpty ? nil : id
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayDiscoveryDebugLogView.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayDiscoveryDebugLogView.swift
@ -0,0 +1,68 @@
+import SwiftUI
+import UIKit
+
+struct GatewayDiscoveryDebugLogView: View {
+    @Environment(GatewayConnectionController.self) private var gatewayController
+    @AppStorage("gateway.discovery.debugLogs") private var debugLogsEnabled: Bool = false
+
+    var body: some View {
+        List {
+            if !self.debugLogsEnabled {
+                Text("Enable “Discovery Debug Logs” to start collecting events.")
+                    .foregroundStyle(.secondary)
+            }
+
+            if self.gatewayController.discoveryDebugLog.isEmpty {
+                Text("No log entries yet.")
+                    .foregroundStyle(.secondary)
+            } else {
+                ForEach(self.gatewayController.discoveryDebugLog) { entry in
+                    VStack(alignment: .leading, spacing: 2) {
+                        Text(Self.formatTime(entry.ts))
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                        Text(entry.message)
+                            .font(.callout)
+                            .textSelection(.enabled)
+                    }
+                    .padding(.vertical, 4)
+                }
+            }
+        }
+        .navigationTitle("Discovery Logs")
+        .toolbar {
+            ToolbarItem(placement: .topBarTrailing) {
+                Button("Copy") {
+                    UIPasteboard.general.string = self.formattedLog()
+                }
+                .disabled(self.gatewayController.discoveryDebugLog.isEmpty)
+            }
+        }
+    }
+
+    private func formattedLog() -> String {
+        self.gatewayController.discoveryDebugLog
+            .map { "\(Self.formatISO($0.ts)) \($0.message)" }
+            .joined(separator: "\n")
+    }
+
+    private static let timeFormatter: DateFormatter = {
+        let formatter = DateFormatter()
+        formatter.dateFormat = "HH:mm:ss"
+        return formatter
+    }()
+
+    private static let isoFormatter: ISO8601DateFormatter = {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return formatter
+    }()
+
+    private static func formatTime(_ date: Date) -> String {
+        self.timeFormatter.string(from: date)
+    }
+
+    private static func formatISO(_ date: Date) -> String {
+        self.isoFormatter.string(from: date)
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayDiscoveryModel.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayDiscoveryModel.swift
@ -0,0 +1,181 @@
+import OpenClawKit
+import Foundation
+import Network
+import Observation
+
+@MainActor
+@Observable
+final class GatewayDiscoveryModel {
+    struct DebugLogEntry: Identifiable, Equatable {
+        var id = UUID()
+        var ts: Date
+        var message: String
+    }
+
+    struct DiscoveredGateway: Identifiable, Equatable {
+        var id: String { self.stableID }
+        var name: String
+        var endpoint: NWEndpoint
+        var stableID: String
+        var debugID: String
+        var lanHost: String?
+        var tailnetDns: String?
+        var gatewayPort: Int?
+        var canvasPort: Int?
+        var tlsEnabled: Bool
+        var tlsFingerprintSha256: String?
+        var cliPath: String?
+    }
+
+    var gateways: [DiscoveredGateway] = []
+    var statusText: String = "Idle"
+    private(set) var debugLog: [DebugLogEntry] = []
+
+    private var browsers: [String: NWBrowser] = [:]
+    private var gatewaysByDomain: [String: [DiscoveredGateway]] = [:]
+    private var statesByDomain: [String: NWBrowser.State] = [:]
+    private var debugLoggingEnabled = false
+    private var lastStableIDs = Set<String>()
+
+    func setDebugLoggingEnabled(_ enabled: Bool) {
+        let wasEnabled = self.debugLoggingEnabled
+        self.debugLoggingEnabled = enabled
+        if !enabled {
+            self.debugLog = []
+        } else if !wasEnabled {
+            self.appendDebugLog("debug logging enabled")
+            self.appendDebugLog("snapshot: status=\(self.statusText) gateways=\(self.gateways.count)")
+        }
+    }
+
+    func start() {
+        if !self.browsers.isEmpty { return }
+        self.appendDebugLog("start()")
+
+        for domain in OpenClawBonjour.gatewayServiceDomains {
+            let browser = GatewayDiscoveryBrowserSupport.makeBrowser(
+                serviceType: OpenClawBonjour.gatewayServiceType,
+                domain: domain,
+                queueLabelPrefix: "ai.openclaw.ios.gateway-discovery",
+                onState: { [weak self] state in
+                    guard let self else { return }
+                    self.statesByDomain[domain] = state
+                    self.updateStatusText()
+                    self.appendDebugLog("state[\(domain)]: \(Self.prettyState(state))")
+                },
+                onResults: { [weak self] results in
+                    guard let self else { return }
+                    self.gatewaysByDomain[domain] = results.compactMap { result -> DiscoveredGateway? in
+                        switch result.endpoint {
+                        case let .service(name, _, _, _):
+                            let decodedName = BonjourEscapes.decode(name)
+                            let txt = result.endpoint.txtRecord?.dictionary ?? [:]
+                            let advertisedName = txt["displayName"]
+                            let prettyAdvertised = advertisedName
+                                .map(Self.prettifyInstanceName)
+                                .flatMap { $0.isEmpty ? nil : $0 }
+                            let prettyName = prettyAdvertised ?? Self.prettifyInstanceName(decodedName)
+                            return DiscoveredGateway(
+                                name: prettyName,
+                                endpoint: result.endpoint,
+                                stableID: GatewayEndpointID.stableID(result.endpoint),
+                                debugID: GatewayEndpointID.prettyDescription(result.endpoint),
+                                lanHost: Self.txtValue(txt, key: "lanHost"),
+                                tailnetDns: Self.txtValue(txt, key: "tailnetDns"),
+                                gatewayPort: Self.txtIntValue(txt, key: "gatewayPort"),
+                                canvasPort: Self.txtIntValue(txt, key: "canvasPort"),
+                                tlsEnabled: Self.txtBoolValue(txt, key: "gatewayTls"),
+                                tlsFingerprintSha256: Self.txtValue(txt, key: "gatewayTlsSha256"),
+                                cliPath: Self.txtValue(txt, key: "cliPath"))
+                        default:
+                            return nil
+                        }
+                    }
+                    .sorted { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
+                    self.recomputeGateways()
+                })
+
+            self.browsers[domain] = browser
+        }
+    }
+
+    func stop() {
+        self.appendDebugLog("stop()")
+        for browser in self.browsers.values {
+            browser.cancel()
+        }
+        self.browsers = [:]
+        self.gatewaysByDomain = [:]
+        self.statesByDomain = [:]
+        self.gateways = []
+        self.statusText = "Stopped"
+    }
+
+    private func recomputeGateways() {
+        let next = self.gatewaysByDomain.values
+            .flatMap(\.self)
+            .sorted { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
+
+        let nextIDs = Set(next.map(\.stableID))
+        let added = nextIDs.subtracting(self.lastStableIDs)
+        let removed = self.lastStableIDs.subtracting(nextIDs)
+        if !added.isEmpty || !removed.isEmpty {
+            self.appendDebugLog("results: total=\(next.count) added=\(added.count) removed=\(removed.count)")
+        }
+        self.lastStableIDs = nextIDs
+        self.gateways = next
+    }
+
+    private func updateStatusText() {
+        self.statusText = GatewayDiscoveryStatusText.make(
+            states: Array(self.statesByDomain.values),
+            hasBrowsers: !self.browsers.isEmpty)
+    }
+
+    private static func prettyState(_ state: NWBrowser.State) -> String {
+        switch state {
+        case .setup:
+            "setup"
+        case .ready:
+            "ready"
+        case let .failed(err):
+            "failed (\(err))"
+        case .cancelled:
+            "cancelled"
+        case let .waiting(err):
+            "waiting (\(err))"
+        @unknown default:
+            "unknown"
+        }
+    }
+
+    private func appendDebugLog(_ message: String) {
+        guard self.debugLoggingEnabled else { return }
+        self.debugLog.append(DebugLogEntry(ts: Date(), message: message))
+        if self.debugLog.count > 200 {
+            self.debugLog.removeFirst(self.debugLog.count - 200)
+        }
+    }
+
+    private static func prettifyInstanceName(_ decodedName: String) -> String {
+        let normalized = decodedName.split(whereSeparator: \.isWhitespace).joined(separator: " ")
+        let stripped = normalized.replacingOccurrences(of: " (OpenClaw)", with: "")
+            .replacingOccurrences(of: #"\s+\(\d+\)$"#, with: "", options: .regularExpression)
+        return stripped.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private static func txtValue(_ dict: [String: String], key: String) -> String? {
+        let raw = dict[key]?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return raw.isEmpty ? nil : raw
+    }
+
+    private static func txtIntValue(_ dict: [String: String], key: String) -> Int? {
+        guard let raw = self.txtValue(dict, key: key) else { return nil }
+        return Int(raw)
+    }
+
+    private static func txtBoolValue(_ dict: [String: String], key: String) -> Bool {
+        guard let raw = self.txtValue(dict, key: key)?.lowercased() else { return false }
+        return raw == "1" || raw == "true" || raw == "yes"
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayHealthMonitor.swift
+++ b/openclaw/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
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayProblemView.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayProblemView.swift
@ -0,0 +1,232 @@
+import OpenClawKit
+import SwiftUI
+import UIKit
+
+struct GatewayProblemBanner: View {
+    let problem: GatewayConnectionProblem
+    var primaryActionTitle: String?
+    var onPrimaryAction: (() -> Void)?
+    var onShowDetails: (() -> Void)?
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            HStack(alignment: .top, spacing: 10) {
+                Image(systemName: self.iconName)
+                    .font(.headline.weight(.semibold))
+                    .foregroundStyle(self.tint)
+                    .frame(width: 20)
+                    .padding(.top, 2)
+
+                VStack(alignment: .leading, spacing: 6) {
+                    HStack(alignment: .firstTextBaseline, spacing: 8) {
+                        Text(self.problem.title)
+                            .font(.subheadline.weight(.semibold))
+                            .multilineTextAlignment(.leading)
+                        Spacer(minLength: 0)
+                        Text(self.ownerLabel)
+                            .font(.caption.weight(.semibold))
+                            .foregroundStyle(.secondary)
+                    }
+
+                    Text(self.problem.message)
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+
+                    if let requestId = self.problem.requestId {
+                        Text("Request ID: \(requestId)")
+                            .font(.system(.caption, design: .monospaced).weight(.medium))
+                            .foregroundStyle(.secondary)
+                            .textSelection(.enabled)
+                    }
+                }
+            }
+
+            HStack(spacing: 10) {
+                if let primaryActionTitle, let onPrimaryAction {
+                    Button(primaryActionTitle, action: onPrimaryAction)
+                        .buttonStyle(.borderedProminent)
+                        .controlSize(.small)
+                }
+                if let onShowDetails {
+                    Button("Details", action: onShowDetails)
+                        .buttonStyle(.bordered)
+                        .controlSize(.small)
+                }
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(14)
+        .background(
+            .thinMaterial,
+            in: RoundedRectangle(cornerRadius: 16, style: .continuous)
+        )
+    }
+
+    private var iconName: String {
+        switch self.problem.kind {
+        case .pairingRequired,
+            .pairingRoleUpgradeRequired,
+            .pairingScopeUpgradeRequired,
+            .pairingMetadataUpgradeRequired:
+            return "person.crop.circle.badge.clock"
+        case .timeout, .connectionRefused, .reachabilityFailed, .websocketCancelled:
+            return "wifi.exclamationmark"
+        case .deviceIdentityRequired,
+            .deviceSignatureExpired,
+            .deviceNonceRequired,
+            .deviceNonceMismatch,
+            .deviceSignatureInvalid,
+            .devicePublicKeyInvalid,
+            .deviceIdMismatch:
+            return "lock.shield"
+        default:
+            return "exclamationmark.triangle.fill"
+        }
+    }
+
+    private var tint: Color {
+        switch self.problem.kind {
+        case .pairingRequired,
+            .pairingRoleUpgradeRequired,
+            .pairingScopeUpgradeRequired,
+            .pairingMetadataUpgradeRequired:
+            return .orange
+        case .timeout, .connectionRefused, .reachabilityFailed, .websocketCancelled:
+            return .yellow
+        default:
+            return .red
+        }
+    }
+
+    private var ownerLabel: String {
+        switch self.problem.owner {
+        case .gateway:
+            return "Fix on gateway"
+        case .iphone:
+            return "Fix on iPhone"
+        case .both:
+            return "Check both"
+        case .network:
+            return "Check network"
+        case .unknown:
+            return "Needs attention"
+        }
+    }
+}
+
+struct GatewayProblemDetailsSheet: View {
+    @Environment(\.dismiss) private var dismiss
+
+    let problem: GatewayConnectionProblem
+    var primaryActionTitle: String?
+    var onPrimaryAction: (() -> Void)?
+
+    @State private var copyFeedback: String?
+
+    var body: some View {
+        NavigationStack {
+            List {
+                Section {
+                    VStack(alignment: .leading, spacing: 10) {
+                        Text(self.problem.title)
+                            .font(.title3.weight(.semibold))
+                        Text(self.problem.message)
+                            .font(.body)
+                            .foregroundStyle(.secondary)
+                        Text(self.ownerSummary)
+                            .font(.footnote.weight(.semibold))
+                            .foregroundStyle(.secondary)
+                    }
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .padding(.vertical, 4)
+                }
+
+                if let requestId = self.problem.requestId {
+                    Section("Request") {
+                        Text(verbatim: requestId)
+                            .font(.system(.body, design: .monospaced))
+                            .textSelection(.enabled)
+                        Button("Copy request ID") {
+                            UIPasteboard.general.string = requestId
+                            self.copyFeedback = "Copied request ID"
+                        }
+                    }
+                }
+
+                if let actionCommand = self.problem.actionCommand {
+                    Section("Gateway command") {
+                        Text(verbatim: actionCommand)
+                            .font(.system(.body, design: .monospaced))
+                            .textSelection(.enabled)
+                        Button("Copy command") {
+                            UIPasteboard.general.string = actionCommand
+                            self.copyFeedback = "Copied command"
+                        }
+                    }
+                }
+
+                if let docsURL = self.problem.docsURL {
+                    Section("Help") {
+                        Link(destination: docsURL) {
+                            Label("Open docs", systemImage: "book")
+                        }
+                        Text(verbatim: docsURL.absoluteString)
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+                            .textSelection(.enabled)
+                    }
+                }
+
+                if let technicalDetails = self.problem.technicalDetails {
+                    Section("Technical details") {
+                        Text(verbatim: technicalDetails)
+                            .font(.system(.footnote, design: .monospaced))
+                            .foregroundStyle(.secondary)
+                            .textSelection(.enabled)
+                    }
+                }
+
+                if let copyFeedback {
+                    Section {
+                        Text(copyFeedback)
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+                    }
+                }
+            }
+            .navigationTitle("Connection problem")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .topBarLeading) {
+                    if let primaryActionTitle, let onPrimaryAction {
+                        Button(primaryActionTitle) {
+                            self.dismiss()
+                            onPrimaryAction()
+                        }
+                    }
+                }
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button("Done") {
+                        self.dismiss()
+                    }
+                }
+            }
+        }
+    }
+
+    private var ownerSummary: String {
+        switch self.problem.owner {
+        case .gateway:
+            return "Primary fix: gateway"
+        case .iphone:
+            return "Primary fix: this iPhone"
+        case .both:
+            return "Primary fix: check both this iPhone and the gateway"
+        case .network:
+            return "Primary fix: network or remote access"
+        case .unknown:
+            return "Primary fix: review details and retry"
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayQuickSetupSheet.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayQuickSetupSheet.swift
@ -0,0 +1,127 @@
+import SwiftUI
+
+struct GatewayQuickSetupSheet: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @Environment(GatewayConnectionController.self) private var gatewayController
+    @Environment(\.dismiss) private var dismiss
+
+    @AppStorage("onboarding.quickSetupDismissed") private var quickSetupDismissed: Bool = false
+    @State private var connecting: Bool = false
+    @State private var connectError: String?
+    @State private var showGatewayProblemDetails: Bool = false
+
+    var body: some View {
+        NavigationStack {
+            VStack(alignment: .leading, spacing: 16) {
+                Text("Connect to a Gateway?")
+                    .font(.title2.bold())
+
+                if let gatewayProblem = self.appModel.lastGatewayProblem {
+                    GatewayProblemBanner(
+                        problem: gatewayProblem,
+                        onShowDetails: {
+                            self.showGatewayProblemDetails = true
+                        })
+                }
+
+                if let candidate = self.bestCandidate {
+                    VStack(alignment: .leading, spacing: 6) {
+                        Text(verbatim: candidate.name)
+                            .font(.headline)
+                        Text(verbatim: candidate.debugID)
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+
+                        VStack(alignment: .leading, spacing: 2) {
+                            // Use verbatim strings so Bonjour-provided values can't be interpreted as
+                            // localized format strings (which can crash with Objective-C exceptions).
+                            Text(verbatim: "Discovery: \(self.gatewayController.discoveryStatusText)")
+                            Text(verbatim: "Status: \(self.appModel.gatewayDisplayStatusText)")
+                            Text(verbatim: "Node: \(self.appModel.nodeStatusText)")
+                            Text(verbatim: "Operator: \(self.appModel.operatorStatusText)")
+                        }
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                    }
+                    .padding(12)
+                    .background(.thinMaterial)
+                    .clipShape(RoundedRectangle(cornerRadius: 14))
+
+                    Button {
+                        self.connectError = nil
+                        self.connecting = true
+                        Task {
+                            let err = await self.gatewayController.connectWithDiagnostics(candidate)
+                            await MainActor.run {
+                                self.connecting = false
+                                self.connectError = err
+                                // If we kicked off a connect, leave the sheet up so the user can see status evolve.
+                            }
+                        }
+                    } label: {
+                        Group {
+                            if self.connecting {
+                                HStack(spacing: 8) {
+                                    ProgressView().progressViewStyle(.circular)
+                                    Text("Connecting…")
+                                }
+                            } else {
+                                Text("Connect")
+                            }
+                        }
+                        .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(self.connecting)
+
+                    if let connectError {
+                        Text(connectError)
+                            .font(.footnote)
+                            .foregroundStyle(.secondary)
+                            .textSelection(.enabled)
+                    }
+
+                    Button {
+                        self.dismiss()
+                    } label: {
+                        Text("Not now")
+                            .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.connecting)
+
+                    Toggle("Don’t show this again", isOn: self.$quickSetupDismissed)
+                        .padding(.top, 4)
+                } else {
+                    Text("No gateways found yet. Make sure your gateway is running and Bonjour discovery is enabled.")
+                        .foregroundStyle(.secondary)
+                }
+
+                Spacer()
+            }
+            .padding()
+            .navigationTitle("Quick Setup")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button {
+                        self.quickSetupDismissed = true
+                        self.dismiss()
+                    } label: {
+                        Text("Close")
+                    }
+                }
+            }
+        }
+        .sheet(isPresented: self.$showGatewayProblemDetails) {
+            if let gatewayProblem = self.appModel.lastGatewayProblem {
+                GatewayProblemDetailsSheet(problem: gatewayProblem)
+            }
+        }
+    }
+
+    private var bestCandidate: GatewayDiscoveryModel.DiscoveredGateway? {
+        // Prefer whatever discovery says is first; the list is already name-sorted.
+        self.gatewayController.gateways.first
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayServiceResolver.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayServiceResolver.swift
@ -0,0 +1,52 @@
+import Foundation
+import OpenClawKit
+
+// NetService-based resolver for Bonjour services.
+// Used to resolve the service endpoint (SRV + A/AAAA) without trusting TXT for routing.
+final class GatewayServiceResolver: NSObject, NetServiceDelegate {
+    private let service: NetService
+    private let completion: ((host: String, port: Int)?) -> Void
+    private var didFinish = false
+
+    init(
+        name: String,
+        type: String,
+        domain: String,
+        completion: @escaping ((host: String, port: Int)?) -> Void)
+    {
+        self.service = NetService(domain: domain, type: type, name: name)
+        self.completion = completion
+        super.init()
+        self.service.delegate = self
+    }
+
+    func start(timeout: TimeInterval = 2.0) {
+        BonjourServiceResolverSupport.start(self.service, timeout: timeout)
+    }
+
+    func netServiceDidResolveAddress(_ sender: NetService) {
+        let host = Self.normalizeHost(sender.hostName)
+        let port = sender.port
+        guard let host, !host.isEmpty, port > 0 else {
+            self.finish(result: nil)
+            return
+        }
+        self.finish(result: (host: host, port: port))
+    }
+
+    func netService(_ sender: NetService, didNotResolve errorDict: [String: NSNumber]) {
+        self.finish(result: nil)
+    }
+
+    private func finish(result: ((host: String, port: Int))?) {
+        guard !self.didFinish else { return }
+        self.didFinish = true
+        self.service.stop()
+        self.service.remove(from: .main, forMode: .common)
+        self.completion(result)
+    }
+
+    private static func normalizeHost(_ raw: String?) -> String? {
+        BonjourServiceResolverSupport.normalizeHost(raw)
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewaySettingsStore.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewaySettingsStore.swift
@ -0,0 +1,563 @@
+import Foundation
+import os
+
+enum GatewaySettingsStore {
+    private static let gatewayService = "ai.openclaw.gateway"
+    private static let nodeService = "ai.openclaw.node"
+    private static let talkService = "ai.openclaw.talk"
+
+    private static let instanceIdDefaultsKey = "node.instanceId"
+    private static let preferredGatewayStableIDDefaultsKey = "gateway.preferredStableID"
+    private static let lastDiscoveredGatewayStableIDDefaultsKey = "gateway.lastDiscoveredStableID"
+    private static let manualEnabledDefaultsKey = "gateway.manual.enabled"
+    private static let manualHostDefaultsKey = "gateway.manual.host"
+    private static let manualPortDefaultsKey = "gateway.manual.port"
+    private static let manualTlsDefaultsKey = "gateway.manual.tls"
+    private static let discoveryDebugLogsDefaultsKey = "gateway.discovery.debugLogs"
+    private static let lastGatewayKindDefaultsKey = "gateway.last.kind"
+    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"
+    private static let lastDiscoveredGatewayStableIDAccount = "lastDiscoveredStableID"
+    private static let lastGatewayConnectionAccount = "lastConnection"
+    private static let talkProviderApiKeyAccountPrefix = "provider.apiKey." // pragma: allowlist secret
+
+    static func bootstrapPersistence() {
+        self.ensureStableInstanceID()
+        self.ensurePreferredGatewayStableID()
+        self.ensureLastDiscoveredGatewayStableID()
+    }
+
+    static func loadStableInstanceID() -> String? {
+        if let value = KeychainStore.loadString(service: self.nodeService, account: self.instanceIdAccount)?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+            !value.isEmpty
+        {
+            return value
+        }
+
+        return nil
+    }
+
+    static func saveStableInstanceID(_ instanceId: String) {
+        _ = KeychainStore.saveString(instanceId, service: self.nodeService, account: self.instanceIdAccount)
+    }
+
+    static func loadPreferredGatewayStableID() -> String? {
+        if let value = KeychainStore.loadString(
+            service: self.gatewayService,
+            account: self.preferredGatewayStableIDAccount
+        )?.trimmingCharacters(in: .whitespacesAndNewlines),
+            !value.isEmpty
+        {
+            return value
+        }
+
+        return nil
+    }
+
+    static func savePreferredGatewayStableID(_ stableID: String) {
+        _ = KeychainStore.saveString(
+            stableID,
+            service: self.gatewayService,
+            account: self.preferredGatewayStableIDAccount)
+    }
+
+    static func clearPreferredGatewayStableID(defaults: UserDefaults = .standard) {
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.preferredGatewayStableIDAccount)
+        defaults.removeObject(forKey: self.preferredGatewayStableIDDefaultsKey)
+    }
+
+    static func loadLastDiscoveredGatewayStableID() -> String? {
+        if let value = KeychainStore.loadString(
+            service: self.gatewayService,
+            account: self.lastDiscoveredGatewayStableIDAccount
+        )?.trimmingCharacters(in: .whitespacesAndNewlines),
+            !value.isEmpty
+        {
+            return value
+        }
+
+        return nil
+    }
+
+    static func saveLastDiscoveredGatewayStableID(_ stableID: String) {
+        _ = KeychainStore.saveString(
+            stableID,
+            service: self.gatewayService,
+            account: self.lastDiscoveredGatewayStableIDAccount)
+    }
+
+    static func clearLastDiscoveredGatewayStableID(defaults: UserDefaults = .standard) {
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.lastDiscoveredGatewayStableIDAccount)
+        defaults.removeObject(forKey: self.lastDiscoveredGatewayStableIDDefaultsKey)
+    }
+
+    static func loadGatewayToken(instanceId: String) -> String? {
+        let account = self.gatewayTokenAccount(instanceId: instanceId)
+        let token = KeychainStore.loadString(service: self.gatewayService, account: account)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if token?.isEmpty == false { return token }
+        return nil
+    }
+
+    static func saveGatewayToken(_ token: String, instanceId: String) {
+        _ = KeychainStore.saveString(
+            token,
+            service: self.gatewayService,
+            account: self.gatewayTokenAccount(instanceId: instanceId))
+    }
+
+    static func loadGatewayBootstrapToken(instanceId: String) -> String? {
+        let account = self.gatewayBootstrapTokenAccount(instanceId: instanceId)
+        let token = KeychainStore.loadString(service: self.gatewayService, account: account)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if token?.isEmpty == false { return token }
+        return nil
+    }
+
+    static func saveGatewayBootstrapToken(_ token: String, instanceId: String) {
+        _ = KeychainStore.saveString(
+            token,
+            service: self.gatewayService,
+            account: self.gatewayBootstrapTokenAccount(instanceId: instanceId))
+    }
+
+    static func clearGatewayBootstrapToken(instanceId: String) {
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.gatewayBootstrapTokenAccount(instanceId: instanceId))
+    }
+
+    static func loadGatewayPassword(instanceId: String) -> String? {
+        KeychainStore.loadString(
+            service: self.gatewayService,
+            account: self.gatewayPasswordAccount(instanceId: instanceId))?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    static func saveGatewayPassword(_ password: String, instanceId: String) {
+        _ = KeychainStore.saveString(
+            password,
+            service: self.gatewayService,
+            account: self.gatewayPasswordAccount(instanceId: instanceId))
+    }
+
+    enum LastGatewayConnection: Equatable {
+        case manual(host: String, port: Int, useTLS: Bool, stableID: String)
+        case discovered(stableID: String, useTLS: Bool)
+
+        var stableID: String {
+            switch self {
+            case let .manual(_, _, _, stableID):
+                return stableID
+            case let .discovered(stableID, _):
+                return stableID
+            }
+        }
+
+        var useTLS: Bool {
+            switch self {
+            case let .manual(_, _, useTLS, _):
+                return useTLS
+            case let .discovered(_, useTLS):
+                return useTLS
+            }
+        }
+    }
+
+    private enum LastGatewayKind: String, Codable {
+        case manual
+        case discovered
+    }
+
+    /// JSON-serializable envelope stored as a single Keychain entry.
+    private struct LastGatewayConnectionData: Codable {
+        var kind: LastGatewayKind
+        var stableID: String
+        var useTLS: Bool
+        var host: String?
+        var port: Int?
+    }
+
+    static func loadTalkProviderApiKey(provider: String) -> String? {
+        guard let providerId = self.normalizedTalkProviderID(provider) else { return nil }
+        let account = self.talkProviderApiKeyAccount(providerId: providerId)
+        let value = KeychainStore.loadString(
+            service: self.talkService,
+            account: account)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if value?.isEmpty == false { return value }
+        return nil
+    }
+
+    static func saveTalkProviderApiKey(_ apiKey: String?, provider: String) {
+        guard let providerId = self.normalizedTalkProviderID(provider) else { return }
+        let account = self.talkProviderApiKeyAccount(providerId: providerId)
+        let trimmed = apiKey?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmed.isEmpty {
+            _ = KeychainStore.delete(service: self.talkService, account: account)
+            return
+        }
+        _ = KeychainStore.saveString(trimmed, service: self.talkService, account: account)
+    }
+
+    static func saveLastGatewayConnectionManual(host: String, port: Int, useTLS: Bool, stableID: String) {
+        let payload = LastGatewayConnectionData(
+            kind: .manual, stableID: stableID, useTLS: useTLS, host: host, port: port)
+        self.saveLastGatewayConnectionData(payload)
+    }
+
+    static func saveLastGatewayConnectionDiscovered(stableID: String, useTLS: Bool) {
+        let payload = LastGatewayConnectionData(
+            kind: .discovered, stableID: stableID, useTLS: useTLS)
+        self.saveLastGatewayConnectionData(payload)
+    }
+
+    static func loadLastGatewayConnection() -> LastGatewayConnection? {
+        // Migrate legacy UserDefaults entries on first access.
+        self.migrateLastGatewayFromUserDefaultsIfNeeded()
+
+        guard let json = KeychainStore.loadString(
+            service: self.gatewayService, account: self.lastGatewayConnectionAccount),
+            let data = json.data(using: .utf8),
+            let stored = try? JSONDecoder().decode(LastGatewayConnectionData.self, from: data)
+        else { return nil }
+
+        let stableID = stored.stableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !stableID.isEmpty else { return nil }
+
+        if stored.kind == .discovered {
+            return .discovered(stableID: stableID, useTLS: stored.useTLS)
+        }
+
+        let host = (stored.host ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        let port = stored.port ?? 0
+        guard !host.isEmpty, port > 0, port <= 65535 else { return nil }
+        return .manual(host: host, port: port, useTLS: stored.useTLS, stableID: stableID)
+    }
+
+    static func clearLastGatewayConnection(defaults: UserDefaults = .standard) {
+        _ = KeychainStore.delete(
+            service: self.gatewayService, account: self.lastGatewayConnectionAccount)
+        // Clean up any legacy UserDefaults entries.
+        defaults.removeObject(forKey: self.lastGatewayKindDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayHostDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayPortDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayTlsDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayStableIDDefaultsKey)
+    }
+
+    @discardableResult
+    private static func saveLastGatewayConnectionData(_ payload: LastGatewayConnectionData) -> Bool {
+        guard let data = try? JSONEncoder().encode(payload),
+              let json = String(data: data, encoding: .utf8)
+        else { return false }
+        return KeychainStore.saveString(
+            json, service: self.gatewayService, account: self.lastGatewayConnectionAccount)
+    }
+
+    /// Migrate legacy UserDefaults gateway.last.* keys into a single Keychain entry.
+    private static func migrateLastGatewayFromUserDefaultsIfNeeded() {
+        let defaults = UserDefaults.standard
+        let stableID = defaults.string(forKey: self.lastGatewayStableIDDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !stableID.isEmpty else { return }
+
+        // Already migrated if Keychain entry exists.
+        if KeychainStore.loadString(
+            service: self.gatewayService, account: self.lastGatewayConnectionAccount) != nil
+        {
+            // Clean up legacy keys.
+            self.removeLastGatewayDefaults(defaults)
+            return
+        }
+
+        let useTLS = defaults.bool(forKey: self.lastGatewayTlsDefaultsKey)
+        let kindRaw = defaults.string(forKey: self.lastGatewayKindDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let kind = LastGatewayKind(rawValue: kindRaw) ?? .manual
+        let host = defaults.string(forKey: self.lastGatewayHostDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let port = defaults.object(forKey: self.lastGatewayPortDefaultsKey) as? Int
+
+        let payload = LastGatewayConnectionData(
+            kind: kind,
+            stableID: stableID,
+            useTLS: useTLS,
+            host: kind == .manual ? host : nil,
+            port: kind == .manual ? port : nil)
+        guard self.saveLastGatewayConnectionData(payload) else { return }
+        self.removeLastGatewayDefaults(defaults)
+    }
+
+    private static func removeLastGatewayDefaults(_ defaults: UserDefaults) {
+        defaults.removeObject(forKey: self.lastGatewayKindDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayHostDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayPortDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayTlsDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayStableIDDefaultsKey)
+    }
+
+    static func deleteGatewayCredentials(instanceId: String) {
+        let trimmed = instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.gatewayTokenAccount(instanceId: trimmed))
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.gatewayBootstrapTokenAccount(instanceId: trimmed))
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.gatewayPasswordAccount(instanceId: trimmed))
+    }
+
+    static func loadGatewayClientIdOverride(stableID: String) -> String? {
+        let trimmedID = stableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedID.isEmpty else { return nil }
+        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)"
+    }
+
+    private static func gatewayBootstrapTokenAccount(instanceId: String) -> String {
+        "gateway-bootstrap-token.\(instanceId)"
+    }
+
+    private static func gatewayPasswordAccount(instanceId: String) -> String {
+        "gateway-password.\(instanceId)"
+    }
+
+    private static func talkProviderApiKeyAccount(providerId: String) -> String {
+        self.talkProviderApiKeyAccountPrefix + providerId
+    }
+
+    private static func normalizedTalkProviderID(_ provider: String) -> String? {
+        let trimmed = provider.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func ensureStableInstanceID() {
+        let defaults = UserDefaults.standard
+
+        if let existing = defaults.string(forKey: self.instanceIdDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+            !existing.isEmpty
+        {
+            if self.loadStableInstanceID() == nil {
+                self.saveStableInstanceID(existing)
+            }
+            return
+        }
+
+        if let stored = self.loadStableInstanceID(), !stored.isEmpty {
+            defaults.set(stored, forKey: self.instanceIdDefaultsKey)
+            return
+        }
+
+        let fresh = UUID().uuidString
+        self.saveStableInstanceID(fresh)
+        defaults.set(fresh, forKey: self.instanceIdDefaultsKey)
+    }
+
+    private static func ensurePreferredGatewayStableID() {
+        let defaults = UserDefaults.standard
+
+        if let existing = defaults.string(forKey: self.preferredGatewayStableIDDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+            !existing.isEmpty
+        {
+            if self.loadPreferredGatewayStableID() == nil {
+                self.savePreferredGatewayStableID(existing)
+            }
+            return
+        }
+
+        if let stored = self.loadPreferredGatewayStableID(), !stored.isEmpty {
+            defaults.set(stored, forKey: self.preferredGatewayStableIDDefaultsKey)
+        }
+    }
+
+    private static func ensureLastDiscoveredGatewayStableID() {
+        let defaults = UserDefaults.standard
+
+        if let existing = defaults.string(forKey: self.lastDiscoveredGatewayStableIDDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+            !existing.isEmpty
+        {
+            if self.loadLastDiscoveredGatewayStableID() == nil {
+                self.saveLastDiscoveredGatewayStableID(existing)
+            }
+            return
+        }
+
+        if let stored = self.loadLastDiscoveredGatewayStableID(), !stored.isEmpty {
+            defaults.set(stored, forKey: self.lastDiscoveredGatewayStableIDDefaultsKey)
+        }
+    }
+
+}
+
+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
+    private static let logWritesSinceCheck = OSAllocatedUnfairLock(initialState: 0)
+    private static func isoTimestamp() -> String {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return formatter.string(from: Date())
+    }
+
+    private static var fileURL: URL? {
+        FileManager.default.urls(for: .cachesDirectory, 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)
+        }
+    }
+
+    private static func applyFileProtection(url: URL) {
+        try? FileManager.default.setAttributes(
+            [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
+            ofItemAtPath: url.path)
+    }
+
+    static func bootstrap() {
+        guard let url = fileURL else { return }
+        queue.async {
+            self.truncateLogIfNeeded(url: url)
+            let timestamp = self.isoTimestamp()
+            let line = "[\(timestamp)] gateway diagnostics started\n"
+            if let data = line.data(using: .utf8) {
+                self.appendToLog(url: url, data: data)
+                self.applyFileProtection(url: url)
+            }
+        }
+    }
+
+    static func log(_ message: String) {
+        let timestamp = self.isoTimestamp()
+        let line = "[\(timestamp)] \(message)"
+        logger.info("\(line, privacy: .public)")
+
+        guard let url = fileURL else { return }
+        queue.async {
+            let shouldTruncate = self.logWritesSinceCheck.withLock { count in
+                count += 1
+                if count >= self.logSizeCheckEveryWrites {
+                    count = 0
+                    return true
+                }
+                return false
+            }
+            if shouldTruncate {
+                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)
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewaySetupCode.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewaySetupCode.swift
@ -0,0 +1,42 @@
+import Foundation
+
+struct GatewaySetupPayload: Codable {
+    var url: String?
+    var host: String?
+    var port: Int?
+    var tls: Bool?
+    var bootstrapToken: String?
+    var token: String?
+    var password: String?
+}
+
+enum GatewaySetupCode {
+    static func decode(raw: String) -> GatewaySetupPayload? {
+        if let payload = decodeFromJSON(raw) {
+            return payload
+        }
+        if let decoded = decodeBase64Payload(raw),
+           let payload = decodeFromJSON(decoded)
+        {
+            return payload
+        }
+        return nil
+    }
+
+    private static func decodeFromJSON(_ json: String) -> GatewaySetupPayload? {
+        guard let data = json.data(using: .utf8) else { return nil }
+        return try? JSONDecoder().decode(GatewaySetupPayload.self, from: data)
+    }
+
+    private static func decodeBase64Payload(_ raw: String) -> String? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        let normalized = trimmed
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+        let padding = normalized.count % 4
+        let padded = padding == 0 ? normalized : normalized + String(repeating: "=", count: 4 - padding)
+        guard let data = Data(base64Encoded: padded) else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/GatewayTrustPromptAlert.swift
+++ b/openclaw/apps/ios/Sources/Gateway/GatewayTrustPromptAlert.swift
@ -0,0 +1,41 @@
+import SwiftUI
+
+struct GatewayTrustPromptAlert: ViewModifier {
+    @Environment(GatewayConnectionController.self) private var gatewayController: GatewayConnectionController
+
+    private var promptBinding: Binding<GatewayConnectionController.TrustPrompt?> {
+        Binding(
+            get: { self.gatewayController.pendingTrustPrompt },
+            set: { _ in
+                // Keep pending trust state until explicit user action.
+                // `alert(item:)` may set the binding to nil during dismissal, which can race with
+                // the button handler and cause accept to no-op.
+            })
+    }
+
+    func body(content: Content) -> some View {
+        content.alert(item: self.promptBinding) { prompt in
+            Alert(
+                title: Text("Trust this gateway?"),
+                message: Text(
+                    """
+                    First-time TLS connection.
+
+                    Verify this SHA-256 fingerprint out-of-band before trusting:
+                    \(prompt.fingerprintSha256)
+                    """),
+                primaryButton: .cancel(Text("Cancel")) {
+                    self.gatewayController.declinePendingTrustPrompt()
+                },
+                secondaryButton: .default(Text("Trust and connect")) {
+                    Task { await self.gatewayController.acceptPendingTrustPrompt() }
+                })
+        }
+    }
+}
+
+extension View {
+    func gatewayTrustPromptAlert() -> some View {
+        self.modifier(GatewayTrustPromptAlert())
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/KeychainStore.swift
+++ b/openclaw/apps/ios/Sources/Gateway/KeychainStore.swift
@ -0,0 +1,16 @@
+import Foundation
+import OpenClawKit
+
+enum KeychainStore {
+    static func loadString(service: String, account: String) -> String? {
+        GenericPasswordKeychainStore.loadString(service: service, account: account)
+    }
+
+    static func saveString(_ value: String, service: String, account: String) -> Bool {
+        GenericPasswordKeychainStore.saveString(value, service: service, account: account)
+    }
+
+    static func delete(service: String, account: String) -> Bool {
+        GenericPasswordKeychainStore.delete(service: service, account: account)
+    }
+}
--- a/openclaw/apps/ios/Sources/Gateway/TCPProbe.swift
+++ b/openclaw/apps/ios/Sources/Gateway/TCPProbe.swift
@ -0,0 +1,43 @@
+import Foundation
+import Network
+import os
+
+enum TCPProbe {
+    static func probe(host: String, port: Int, timeoutSeconds: Double, queueLabel: String) async -> Bool {
+        guard port >= 1, port <= 65535 else { return false }
+        guard let nwPort = NWEndpoint.Port(rawValue: UInt16(port)) else { return false }
+
+        let endpointHost = NWEndpoint.Host(host)
+        let connection = NWConnection(host: endpointHost, port: nwPort, using: .tcp)
+
+        return await withCheckedContinuation { cont in
+            let queue = DispatchQueue(label: queueLabel)
+            let finished = OSAllocatedUnfairLock(initialState: false)
+            let finish: @Sendable (Bool) -> Void = { ok in
+                let shouldResume = finished.withLock { flag -> Bool in
+                    if flag { return false }
+                    flag = true
+                    return true
+                }
+                guard shouldResume else { return }
+                connection.cancel()
+                cont.resume(returning: ok)
+            }
+
+            connection.stateUpdateHandler = { state in
+                switch state {
+                case .ready:
+                    finish(true)
+                case .failed, .cancelled:
+                    finish(false)
+                default:
+                    break
+                }
+            }
+
+            connection.start(queue: queue)
+            queue.asyncAfter(deadline: .now() + timeoutSeconds) { finish(false) }
+        }
+    }
+}
+
--- a/openclaw/apps/ios/Sources/HomeToolbar.swift
+++ b/openclaw/apps/ios/Sources/HomeToolbar.swift
@ -0,0 +1,226 @@
+import SwiftUI
+
+struct HomeToolbar: View {
+    var gateway: StatusPill.GatewayState
+    var voiceWakeEnabled: Bool
+    var activity: StatusPill.Activity?
+    var brighten: Bool
+    var talkButtonEnabled: Bool
+    var talkActive: Bool
+    var talkTint: Color
+    var onStatusTap: () -> Void
+    var onChatTap: () -> Void
+    var onTalkTap: () -> Void
+    var onSettingsTap: () -> Void
+
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    var body: some View {
+        VStack(spacing: 0) {
+            Rectangle()
+                .fill(.white.opacity(self.contrast == .increased ? 0.46 : (self.brighten ? 0.18 : 0.12)))
+                .frame(height: self.contrast == .increased ? 1.0 : 0.6)
+                .allowsHitTesting(false)
+
+            HStack(spacing: 12) {
+                HomeToolbarStatusButton(
+                    gateway: self.gateway,
+                    voiceWakeEnabled: self.voiceWakeEnabled,
+                    activity: self.activity,
+                    brighten: self.brighten,
+                    onTap: self.onStatusTap)
+
+                Spacer(minLength: 0)
+
+                HStack(spacing: 8) {
+                    HomeToolbarActionButton(
+                        systemImage: "text.bubble.fill",
+                        accessibilityLabel: "Chat",
+                        brighten: self.brighten,
+                        action: self.onChatTap)
+
+                    if self.talkButtonEnabled {
+                        HomeToolbarActionButton(
+                            systemImage: self.talkActive ? "waveform.circle.fill" : "waveform.circle",
+                            accessibilityLabel: self.talkActive ? "Talk Mode On" : "Talk Mode Off",
+                            brighten: self.brighten,
+                            tint: self.talkTint,
+                            isActive: self.talkActive,
+                            action: self.onTalkTap)
+                    }
+
+                    HomeToolbarActionButton(
+                        systemImage: "gearshape.fill",
+                        accessibilityLabel: "Settings",
+                        brighten: self.brighten,
+                        action: self.onSettingsTap)
+                }
+            }
+            .padding(.horizontal, 12)
+            .padding(.top, 10)
+            .padding(.bottom, 8)
+        }
+        .frame(maxWidth: .infinity)
+        .background(.ultraThinMaterial)
+        .overlay(alignment: .top) {
+            LinearGradient(
+                colors: [
+                    .white.opacity(self.brighten ? 0.10 : 0.06),
+                    .clear,
+                ],
+                startPoint: .top,
+                endPoint: .bottom)
+                .allowsHitTesting(false)
+        }
+    }
+}
+
+private struct HomeToolbarStatusButton: View {
+    @Environment(\.scenePhase) private var scenePhase
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    var gateway: StatusPill.GatewayState
+    var voiceWakeEnabled: Bool
+    var activity: StatusPill.Activity?
+    var brighten: Bool
+    var onTap: () -> Void
+
+    @State private var pulse: Bool = false
+
+    var body: some View {
+        Button(action: self.onTap) {
+            HStack(spacing: 8) {
+                HStack(spacing: 6) {
+                    Circle()
+                        .fill(self.gateway.color)
+                        .frame(width: 8, height: 8)
+                        .scaleEffect(
+                            self.gateway == .connecting && !self.reduceMotion
+                                ? (self.pulse ? 1.15 : 0.85)
+                                : 1.0
+                        )
+                        .opacity(self.gateway == .connecting && !self.reduceMotion ? (self.pulse ? 1.0 : 0.6) : 1.0)
+
+                    Text(self.gateway.title)
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(.primary)
+                        .lineLimit(1)
+                }
+
+                if let activity {
+                    Image(systemName: activity.systemImage)
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(activity.tint ?? .primary)
+                        .transition(.opacity.combined(with: .move(edge: .top)))
+                } else {
+                    Image(systemName: self.voiceWakeEnabled ? "mic.fill" : "mic.slash")
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(self.voiceWakeEnabled ? .primary : .secondary)
+                        .transition(.opacity.combined(with: .move(edge: .top)))
+                }
+            }
+            .padding(.horizontal, 12)
+            .padding(.vertical, 8)
+            .background {
+                RoundedRectangle(cornerRadius: 14, style: .continuous)
+                    .fill(Color.black.opacity(self.brighten ? 0.12 : 0.18))
+                    .overlay {
+                        RoundedRectangle(cornerRadius: 14, style: .continuous)
+                            .strokeBorder(
+                                .white.opacity(self.contrast == .increased ? 0.46 : (self.brighten ? 0.22 : 0.16)),
+                                lineWidth: self.contrast == .increased ? 1.0 : 0.6)
+                    }
+            }
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel("Connection Status")
+        .accessibilityValue(self.accessibilityValue)
+        .accessibilityHint(
+            self.gateway == .connected
+                ? "Double tap for gateway actions"
+                : "Double tap to open settings")
+        .onAppear { self.updatePulse(for: self.gateway, scenePhase: self.scenePhase, reduceMotion: self.reduceMotion) }
+        .onDisappear { self.pulse = false }
+        .onChange(of: self.gateway) { _, newValue in
+            self.updatePulse(for: newValue, scenePhase: self.scenePhase, reduceMotion: self.reduceMotion)
+        }
+        .onChange(of: self.scenePhase) { _, newValue in
+            self.updatePulse(for: self.gateway, scenePhase: newValue, reduceMotion: self.reduceMotion)
+        }
+        .onChange(of: self.reduceMotion) { _, newValue in
+            self.updatePulse(for: self.gateway, scenePhase: self.scenePhase, reduceMotion: newValue)
+        }
+        .animation(.easeInOut(duration: 0.18), value: self.activity?.title)
+    }
+
+    private var accessibilityValue: String {
+        if let activity {
+            return "\(self.gateway.title), \(activity.title)"
+        }
+        return "\(self.gateway.title), Voice Wake \(self.voiceWakeEnabled ? "enabled" : "disabled")"
+    }
+
+    private func updatePulse(for gateway: StatusPill.GatewayState, scenePhase: ScenePhase, reduceMotion: Bool) {
+        guard gateway == .connecting, scenePhase == .active, !reduceMotion else {
+            withAnimation(reduceMotion ? .none : .easeOut(duration: 0.2)) { self.pulse = false }
+            return
+        }
+
+        guard !self.pulse else { return }
+        withAnimation(.easeInOut(duration: 0.9).repeatForever(autoreverses: true)) {
+            self.pulse = true
+        }
+    }
+}
+
+private struct HomeToolbarActionButton: View {
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    let systemImage: String
+    let accessibilityLabel: String
+    let brighten: Bool
+    var tint: Color?
+    var isActive: Bool = false
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: self.action) {
+            Image(systemName: self.systemImage)
+                .font(.system(size: 16, weight: .semibold))
+                .foregroundStyle(self.isActive ? (self.tint ?? .primary) : .primary)
+                .frame(width: 40, height: 40)
+                .background {
+                    RoundedRectangle(cornerRadius: 12, style: .continuous)
+                        .fill(Color.black.opacity(self.brighten ? 0.12 : 0.18))
+                        .overlay {
+                            if let tint {
+                                RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                    .fill(
+                                        LinearGradient(
+                                            colors: [
+                                                tint.opacity(self.isActive ? 0.22 : 0.14),
+                                                tint.opacity(self.isActive ? 0.08 : 0.04),
+                                                .clear,
+                                            ],
+                                            startPoint: .topLeading,
+                                            endPoint: .bottomTrailing))
+                                    .blendMode(.overlay)
+                            }
+                        }
+                        .overlay {
+                            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                .strokeBorder(
+                                    (self.tint ?? .white).opacity(
+                                        self.isActive
+                                            ? 0.34
+                                            : (self.contrast == .increased ? 0.4 : (self.brighten ? 0.22 : 0.16))
+                                    ),
+                                    lineWidth: self.contrast == .increased ? 1.0 : (self.isActive ? 0.8 : 0.6))
+                        }
+                }
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel(self.accessibilityLabel)
+    }
+}
--- a/openclaw/apps/ios/Sources/Info.plist
+++ b/openclaw/apps/ios/Sources/Info.plist
@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>BGTaskSchedulerPermittedIdentifiers</key>
+	<array>
+		<string>ai.openclaw.ios.bgrefresh</string>
+	</array>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>OpenClaw</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIconName</key>
+	<string>AppIcon</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(OPENCLAW_MARKETING_VERSION)</string>
+	<key>OpenClawCanonicalVersion</key>
+	<string>$(OPENCLAW_IOS_VERSION)</string>
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleURLName</key>
+			<string>ai.openclaw.ios</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>openclaw</string>
+			</array>
+		</dict>
+	</array>
+	<key>CFBundleVersion</key>
+	<string>$(OPENCLAW_BUILD_VERSION)</string>
+	<key>ITSAppUsesNonExemptEncryption</key>
+	<false/>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoadsInWebContent</key>
+		<true/>
+	</dict>
+	<key>NSBonjourServices</key>
+	<array>
+		<string>_openclaw-gw._tcp</string>
+	</array>
+	<key>NSCameraUsageDescription</key>
+	<string>OpenClaw can capture photos or short video clips when requested via the gateway.</string>
+	<key>NSLocalNetworkUsageDescription</key>
+	<string>OpenClaw discovers and connects to your OpenClaw gateway on the local network.</string>
+	<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+	<string>OpenClaw can share your location in the background when you enable Always.</string>
+	<key>NSLocationWhenInUseUsageDescription</key>
+	<string>OpenClaw uses your location when you allow location sharing.</string>
+	<key>NSMicrophoneUsageDescription</key>
+	<string>OpenClaw needs microphone access for voice wake.</string>
+	<key>NSMotionUsageDescription</key>
+	<string>OpenClaw may use motion data to support device-aware interactions and automations.</string>
+	<key>NSPhotoLibraryUsageDescription</key>
+	<string>OpenClaw needs photo library access when you choose existing photos to share with your assistant.</string>
+	<key>NSSpeechRecognitionUsageDescription</key>
+	<string>OpenClaw uses on-device speech recognition for voice wake.</string>
+	<key>NSSupportsLiveActivities</key>
+	<true/>
+	<key>OpenClawPushAPNsEnvironment</key>
+	<string>$(OPENCLAW_PUSH_APNS_ENVIRONMENT)</string>
+	<key>OpenClawPushDistribution</key>
+	<string>$(OPENCLAW_PUSH_DISTRIBUTION)</string>
+	<key>OpenClawPushRelayBaseURL</key>
+	<string>$(OPENCLAW_PUSH_RELAY_BASE_URL)</string>
+	<key>OpenClawPushTransport</key>
+	<string>$(OPENCLAW_PUSH_TRANSPORT)</string>
+	<key>UIApplicationSceneManifest</key>
+	<dict>
+		<key>UIApplicationSupportsMultipleScenes</key>
+		<false/>
+	</dict>
+	<key>UIBackgroundModes</key>
+	<array>
+		<string>audio</string>
+		<string>remote-notification</string>
+	</array>
+	<key>UILaunchScreen</key>
+	<dict/>
+	<key>UISupportedInterfaceOrientations</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationPortraitUpsideDown</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+	</array>
+	<key>UISupportedInterfaceOrientations~ipad</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationPortraitUpsideDown</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+	</array>
+</dict>
+</plist>
--- a/openclaw/apps/ios/Sources/LiveActivity/LiveActivityManager.swift
+++ b/openclaw/apps/ios/Sources/LiveActivity/LiveActivityManager.swift
@ -0,0 +1,125 @@
+@preconcurrency import ActivityKit
+import Foundation
+import os
+
+/// Minimal Live Activity lifecycle focused on connection health + stale cleanup.
+@MainActor
+final class LiveActivityManager {
+    static let shared = LiveActivityManager()
+
+    private let logger = Logger(subsystem: "ai.openclaw.ios", category: "LiveActivity")
+    private var currentActivity: Activity<OpenClawActivityAttributes>?
+    private var activityStartDate: Date = .now
+
+    private init() {
+        self.hydrateCurrentAndPruneDuplicates()
+    }
+
+    var isActive: Bool {
+        guard let activity = self.currentActivity else { return false }
+        guard activity.activityState == .active else {
+            self.currentActivity = nil
+            return false
+        }
+        return true
+    }
+
+    func startActivity(agentName: String, sessionKey: String) {
+        self.hydrateCurrentAndPruneDuplicates()
+
+        if self.currentActivity != nil {
+            self.handleConnecting()
+            return
+        }
+
+        let authInfo = ActivityAuthorizationInfo()
+        guard authInfo.areActivitiesEnabled else {
+            self.logger.info("Live Activities disabled; skipping start")
+            return
+        }
+
+        self.activityStartDate = .now
+        let attributes = OpenClawActivityAttributes(agentName: agentName, sessionKey: sessionKey)
+
+        do {
+            let activity = try Activity.request(
+                attributes: attributes,
+                content: ActivityContent(state: self.connectingState(), staleDate: nil),
+                pushType: nil)
+            self.currentActivity = activity
+            self.logger.info("started live activity id=\(activity.id, privacy: .public)")
+        } catch {
+            self.logger.error("failed to start live activity: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    func handleConnecting() {
+        self.updateCurrent(state: self.connectingState())
+    }
+
+    func handleReconnect() {
+        self.updateCurrent(state: self.idleState())
+    }
+
+    func handleDisconnect() {
+        self.updateCurrent(state: self.disconnectedState())
+    }
+
+    private func hydrateCurrentAndPruneDuplicates() {
+        let active = Activity<OpenClawActivityAttributes>.activities
+        guard !active.isEmpty else {
+            self.currentActivity = nil
+            return
+        }
+
+        let keeper = active.max { lhs, rhs in
+            lhs.content.state.startedAt < rhs.content.state.startedAt
+        } ?? active[0]
+
+        self.currentActivity = keeper
+        self.activityStartDate = keeper.content.state.startedAt
+
+        let stale = active.filter { $0.id != keeper.id }
+        for activity in stale {
+            Task {
+                await activity.end(
+                    ActivityContent(state: self.disconnectedState(), staleDate: nil),
+                    dismissalPolicy: .immediate)
+            }
+        }
+    }
+
+    private func updateCurrent(state: OpenClawActivityAttributes.ContentState) {
+        guard let activity = self.currentActivity else { return }
+        Task {
+            await activity.update(ActivityContent(state: state, staleDate: nil))
+        }
+    }
+
+    private func connectingState() -> OpenClawActivityAttributes.ContentState {
+        OpenClawActivityAttributes.ContentState(
+            statusText: "Connecting...",
+            isIdle: false,
+            isDisconnected: false,
+            isConnecting: true,
+            startedAt: self.activityStartDate)
+    }
+
+    private func idleState() -> OpenClawActivityAttributes.ContentState {
+        OpenClawActivityAttributes.ContentState(
+            statusText: "Idle",
+            isIdle: true,
+            isDisconnected: false,
+            isConnecting: false,
+            startedAt: self.activityStartDate)
+    }
+
+    private func disconnectedState() -> OpenClawActivityAttributes.ContentState {
+        OpenClawActivityAttributes.ContentState(
+            statusText: "Disconnected",
+            isIdle: false,
+            isDisconnected: true,
+            isConnecting: false,
+            startedAt: self.activityStartDate)
+    }
+}
--- a/openclaw/apps/ios/Sources/LiveActivity/OpenClawActivityAttributes.swift
+++ b/openclaw/apps/ios/Sources/LiveActivity/OpenClawActivityAttributes.swift
@ -0,0 +1,45 @@
+import ActivityKit
+import Foundation
+
+/// Shared schema used by iOS app + Live Activity widget extension.
+struct OpenClawActivityAttributes: ActivityAttributes {
+    var agentName: String
+    var sessionKey: String
+
+    struct ContentState: Codable, Hashable {
+        var statusText: String
+        var isIdle: Bool
+        var isDisconnected: Bool
+        var isConnecting: Bool
+        var startedAt: Date
+    }
+}
+
+#if DEBUG
+extension OpenClawActivityAttributes {
+    static let preview = OpenClawActivityAttributes(agentName: "main", sessionKey: "main")
+}
+
+extension OpenClawActivityAttributes.ContentState {
+    static let connecting = OpenClawActivityAttributes.ContentState(
+        statusText: "Connecting...",
+        isIdle: false,
+        isDisconnected: false,
+        isConnecting: true,
+        startedAt: .now)
+
+    static let idle = OpenClawActivityAttributes.ContentState(
+        statusText: "Idle",
+        isIdle: true,
+        isDisconnected: false,
+        isConnecting: false,
+        startedAt: .now)
+
+    static let disconnected = OpenClawActivityAttributes.ContentState(
+        statusText: "Disconnected",
+        isIdle: false,
+        isDisconnected: true,
+        isConnecting: false,
+        startedAt: .now)
+}
+#endif
--- a/openclaw/apps/ios/Sources/Location/LocationService.swift
+++ b/openclaw/apps/ios/Sources/Location/LocationService.swift
@ -0,0 +1,178 @@
+import OpenClawKit
+import CoreLocation
+import Foundation
+
+@MainActor
+final class LocationService: NSObject, CLLocationManagerDelegate, LocationServiceCommon {
+    enum Error: Swift.Error {
+        case timeout
+        case unavailable
+    }
+
+    private let manager = CLLocationManager()
+    private var authContinuation: CheckedContinuation<CLAuthorizationStatus, Never>?
+    private var locationContinuation: CheckedContinuation<CLLocation, Swift.Error>?
+    private var updatesContinuation: AsyncStream<CLLocation>.Continuation?
+    private var isStreaming = false
+    private var significantLocationCallback: (@Sendable (CLLocation) -> Void)?
+    private var isMonitoringSignificantChanges = false
+
+    var locationManager: CLLocationManager {
+        self.manager
+    }
+
+    var locationRequestContinuation: CheckedContinuation<CLLocation, Swift.Error>? {
+        get { self.locationContinuation }
+        set { self.locationContinuation = newValue }
+    }
+
+    override init() {
+        super.init()
+        self.configureLocationManager()
+    }
+
+    func ensureAuthorization(mode: OpenClawLocationMode) async -> CLAuthorizationStatus {
+        guard CLLocationManager.locationServicesEnabled() else { return .denied }
+
+        let status = self.manager.authorizationStatus
+        if status == .notDetermined {
+            self.manager.requestWhenInUseAuthorization()
+            let updated = await self.awaitAuthorizationChange()
+            if mode != .always { return updated }
+        }
+
+        if mode == .always {
+            let current = self.manager.authorizationStatus
+            if current == .authorizedWhenInUse {
+                self.manager.requestAlwaysAuthorization()
+                return await self.awaitAuthorizationChange()
+            }
+            return current
+        }
+
+        return self.manager.authorizationStatus
+    }
+
+    func currentLocation(
+        params: OpenClawLocationGetParams,
+        desiredAccuracy: OpenClawLocationAccuracy,
+        maxAgeMs: Int?,
+        timeoutMs: Int?) async throws -> CLLocation
+    {
+        _ = params
+        return try await LocationCurrentRequest.resolve(
+            manager: self.manager,
+            desiredAccuracy: desiredAccuracy,
+            maxAgeMs: maxAgeMs,
+            timeoutMs: timeoutMs,
+            request: { try await self.requestLocationOnce() },
+            withTimeout: { timeoutMs, operation in
+                try await self.withTimeout(timeoutMs: timeoutMs, operation: operation)
+            })
+    }
+
+    private func awaitAuthorizationChange() async -> CLAuthorizationStatus {
+        await withCheckedContinuation { cont in
+            self.authContinuation = cont
+        }
+    }
+
+    private func withTimeout<T: Sendable>(
+        timeoutMs: Int,
+        operation: @escaping @Sendable () async throws -> T) async throws -> T
+    {
+        try await AsyncTimeout.withTimeoutMs(timeoutMs: timeoutMs, onTimeout: { Error.timeout }, operation: operation)
+    }
+
+    func startLocationUpdates(
+        desiredAccuracy: OpenClawLocationAccuracy,
+        significantChangesOnly: Bool) -> AsyncStream<CLLocation>
+    {
+        self.stopLocationUpdates()
+
+        self.manager.desiredAccuracy = LocationCurrentRequest.accuracyValue(desiredAccuracy)
+        self.manager.pausesLocationUpdatesAutomatically = true
+        self.manager.allowsBackgroundLocationUpdates = true
+
+        self.isStreaming = true
+        if significantChangesOnly {
+            self.manager.startMonitoringSignificantLocationChanges()
+        } else {
+            self.manager.startUpdatingLocation()
+        }
+
+        return AsyncStream(bufferingPolicy: .bufferingNewest(1)) { continuation in
+            self.updatesContinuation = continuation
+            continuation.onTermination = { @Sendable _ in
+                Task { @MainActor in
+                    self.stopLocationUpdates()
+                }
+            }
+        }
+    }
+
+    func stopLocationUpdates() {
+        guard self.isStreaming else { return }
+        self.isStreaming = false
+        self.manager.stopUpdatingLocation()
+        self.manager.stopMonitoringSignificantLocationChanges()
+        self.updatesContinuation?.finish()
+        self.updatesContinuation = nil
+    }
+
+    func startMonitoringSignificantLocationChanges(onUpdate: @escaping @Sendable (CLLocation) -> Void) {
+        self.significantLocationCallback = onUpdate
+        guard !self.isMonitoringSignificantChanges else { return }
+        self.isMonitoringSignificantChanges = true
+        self.manager.startMonitoringSignificantLocationChanges()
+    }
+
+    func stopMonitoringSignificantLocationChanges() {
+        guard self.isMonitoringSignificantChanges else { return }
+        self.isMonitoringSignificantChanges = false
+        self.significantLocationCallback = nil
+        self.manager.stopMonitoringSignificantLocationChanges()
+    }
+
+    nonisolated func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
+        let status = manager.authorizationStatus
+        Task { @MainActor in
+            if let cont = self.authContinuation {
+                self.authContinuation = nil
+                cont.resume(returning: status)
+            }
+        }
+    }
+
+    nonisolated func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
+        let locs = locations
+        Task { @MainActor in
+            // Resolve the one-shot continuation first (if any).
+            if let cont = self.locationContinuation {
+                self.locationContinuation = nil
+                if let latest = locs.last {
+                    cont.resume(returning: latest)
+                } else {
+                    cont.resume(throwing: Error.unavailable)
+                }
+                // Don't return — also forward to significant-change callback below
+                // so both consumers receive updates when both are active.
+            }
+            if let callback = self.significantLocationCallback, let latest = locs.last {
+                callback(latest)
+            }
+            if let latest = locs.last, let updates = self.updatesContinuation {
+                updates.yield(latest)
+            }
+        }
+    }
+
+    nonisolated func locationManager(_ manager: CLLocationManager, didFailWithError error: Swift.Error) {
+        let err = error
+        Task { @MainActor in
+            guard let cont = self.locationContinuation else { return }
+            self.locationContinuation = nil
+            cont.resume(throwing: err)
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Location/SignificantLocationMonitor.swift
+++ b/openclaw/apps/ios/Sources/Location/SignificantLocationMonitor.swift
@ -0,0 +1,42 @@
+import CoreLocation
+import Foundation
+import OpenClawKit
+
+/// Monitors significant location changes and pushes `location.update`
+/// events to the gateway so the severance hook can determine whether
+/// the user is at their configured work location.
+@MainActor
+enum SignificantLocationMonitor {
+    static func startIfNeeded(
+        locationService: any LocationServicing,
+        locationMode: OpenClawLocationMode,
+        gateway: GatewayNodeSession,
+        beforeSend: (@MainActor @Sendable () async -> Void)? = nil
+    ) {
+        guard locationMode == .always else { return }
+        let status = locationService.authorizationStatus()
+        guard status == .authorizedAlways else { return }
+        locationService.startMonitoringSignificantLocationChanges { location in
+            struct Payload: Codable {
+                var lat: Double
+                var lon: Double
+                var accuracyMeters: Double
+                var source: String?
+            }
+            let payload = Payload(
+                lat: location.coordinate.latitude,
+                lon: location.coordinate.longitude,
+                accuracyMeters: location.horizontalAccuracy,
+                source: "ios-significant-location")
+            guard let data = try? JSONEncoder().encode(payload),
+                  let json = String(data: data, encoding: .utf8)
+            else { return }
+            Task { @MainActor in
+                if let beforeSend {
+                    await beforeSend()
+                }
+                await gateway.sendEvent(event: "location.update", payloadJSON: json)
+            }
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Media/PhotoLibraryService.swift
+++ b/openclaw/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))
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Model/NodeAppModel+Canvas.swift
+++ b/openclaw/apps/ios/Sources/Model/NodeAppModel+Canvas.swift
@ -0,0 +1,107 @@
+import Foundation
+import Network
+import OpenClawKit
+
+enum A2UIReadyState {
+    case ready(String)
+    case hostNotConfigured
+    case hostUnavailable
+}
+
+extension NodeAppModel {
+    func resolveCanvasHostURL() async -> String? {
+        guard let raw = await self.gatewaySession.currentCanvasHostUrl() else { return nil }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, let base = URL(string: trimmed) else { return nil }
+        if let host = base.host, LoopbackHost.isLoopback(host) {
+            return nil
+        }
+        return base.appendingPathComponent("__openclaw__/canvas/").absoluteString
+    }
+
+    func _test_resolveA2UIHostURL() async -> String? {
+        await self.resolveA2UIHostURL()
+    }
+
+    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, LoopbackHost.isLoopback(host) {
+            return nil
+        }
+        return base.appendingPathComponent("__openclaw__/a2ui/").absoluteString + "?platform=ios"
+    }
+
+    /// Normalize a URL string for trust comparison: lowercase scheme/host and strip fragment.
+    /// This matches the normalization applied by ScreenController.isTrustedCanvasUIURL so that
+    /// SPA hash-routing fragments and scheme/host casing do not silently prevent trust being set.
+    static func normalizeURLForTrustComparison(_ raw: String) -> String {
+        guard let url = URL(string: raw),
+              var components = URLComponents(url: url, resolvingAgainstBaseURL: false)
+        else { return raw }
+        components.fragment = nil
+        components.scheme = components.scheme?.lowercased()
+        components.host = components.host?.lowercased()
+        return components.url?.absoluteString ?? raw
+    }
+
+    func showA2UIOnConnectIfNeeded() async {
+        await MainActor.run {
+            // Keep the bundled home canvas as the default connected view.
+            // Agents can still explicitly present a remote or local canvas later.
+            self.lastAutoA2uiURL = nil
+            self.screen.showDefaultCanvas()
+        }
+    }
+
+    func ensureA2UIReadyWithCapabilityRefresh(timeoutMs: Int = 5000) async -> A2UIReadyState {
+        guard let initialUrl = await self.resolveA2UIHostURLWithCapabilityRefresh() else {
+            return .hostNotConfigured
+        }
+        self.screen.navigate(to: initialUrl, trustA2UIActions: true)
+        if await self.screen.waitForA2UIReady(timeoutMs: timeoutMs) {
+            return .ready(initialUrl)
+        }
+
+        // First render can fail when scoped capability rotates between reconnects.
+        guard await self.gatewaySession.refreshNodeCanvasCapability() else { return .hostUnavailable }
+        guard let refreshedUrl = await self.resolveA2UIHostURL() else { return .hostUnavailable }
+        self.screen.navigate(to: refreshedUrl, trustA2UIActions: true)
+        if await self.screen.waitForA2UIReady(timeoutMs: timeoutMs) {
+            return .ready(refreshedUrl)
+        }
+        return .hostUnavailable
+    }
+
+    func showLocalCanvasOnDisconnect() {
+        self.lastAutoA2uiURL = nil
+        self.screen.showDefaultCanvas()
+    }
+
+    private func resolveA2UIHostURLWithCapabilityRefresh() async -> String? {
+        if let url = await self.resolveA2UIHostURL() {
+            return url
+        }
+        guard await self.gatewaySession.refreshNodeCanvasCapability() else { return nil }
+        return await self.resolveA2UIHostURL()
+    }
+
+    private func resolveCanvasHostURLWithCapabilityRefresh() async -> String? {
+        if let url = await self.resolveCanvasHostURL() {
+            return url
+        }
+        guard await self.gatewaySession.refreshNodeCanvasCapability() else { return nil }
+        return await self.resolveCanvasHostURL()
+    }
+
+    private static func probeTCP(url: URL, timeoutSeconds: Double) async -> Bool {
+        guard let host = url.host, !host.isEmpty else { return false }
+        let portInt = url.port ?? ((url.scheme ?? "").lowercased() == "wss" ? 443 : 80)
+        return await TCPProbe.probe(
+            host: host,
+            port: portInt,
+            timeoutSeconds: timeoutSeconds,
+            queueLabel: "a2ui.preflight")
+    }
+}
--- a/openclaw/apps/ios/Sources/Model/NodeAppModel+WatchNotifyNormalization.swift
+++ b/openclaw/apps/ios/Sources/Model/NodeAppModel+WatchNotifyNormalization.swift
@ -0,0 +1,103 @@
+import Foundation
+import OpenClawKit
+
+extension NodeAppModel {
+    static func normalizeWatchNotifyParams(_ params: OpenClawWatchNotifyParams) -> OpenClawWatchNotifyParams {
+        var normalized = params
+        normalized.title = params.title.trimmingCharacters(in: .whitespacesAndNewlines)
+        normalized.body = params.body.trimmingCharacters(in: .whitespacesAndNewlines)
+        normalized.promptId = self.trimmedOrNil(params.promptId)
+        normalized.sessionKey = self.trimmedOrNil(params.sessionKey)
+        normalized.kind = self.trimmedOrNil(params.kind)
+        normalized.details = self.trimmedOrNil(params.details)
+        normalized.priority = self.normalizedWatchPriority(params.priority, risk: params.risk)
+        normalized.risk = self.normalizedWatchRisk(params.risk, priority: normalized.priority)
+
+        let normalizedActions = self.normalizeWatchActions(
+            params.actions,
+            kind: normalized.kind,
+            promptId: normalized.promptId)
+        normalized.actions = normalizedActions.isEmpty ? nil : normalizedActions
+        return normalized
+    }
+
+    static func normalizeWatchActions(
+        _ actions: [OpenClawWatchAction]?,
+        kind: String?,
+        promptId: String?) -> [OpenClawWatchAction]
+    {
+        let provided = (actions ?? []).compactMap { action -> OpenClawWatchAction? in
+            let id = action.id.trimmingCharacters(in: .whitespacesAndNewlines)
+            let label = action.label.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !id.isEmpty, !label.isEmpty else { return nil }
+            return OpenClawWatchAction(
+                id: id,
+                label: label,
+                style: self.trimmedOrNil(action.style))
+        }
+        if !provided.isEmpty {
+            return Array(provided.prefix(4))
+        }
+
+        // Only auto-insert quick actions when this is a prompt/decision flow.
+        guard promptId?.isEmpty == false else {
+            return []
+        }
+
+        let normalizedKind = kind?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() ?? ""
+        if normalizedKind.contains("approval") || normalizedKind.contains("approve") {
+            return [
+                OpenClawWatchAction(id: "approve", label: "Approve"),
+                OpenClawWatchAction(id: "decline", label: "Decline", style: "destructive"),
+                OpenClawWatchAction(id: "open_phone", label: "Open iPhone"),
+                OpenClawWatchAction(id: "escalate", label: "Escalate"),
+            ]
+        }
+
+        return [
+            OpenClawWatchAction(id: "done", label: "Done"),
+            OpenClawWatchAction(id: "snooze_10m", label: "Snooze 10m"),
+            OpenClawWatchAction(id: "open_phone", label: "Open iPhone"),
+            OpenClawWatchAction(id: "escalate", label: "Escalate"),
+        ]
+    }
+
+    static func normalizedWatchRisk(
+        _ risk: OpenClawWatchRisk?,
+        priority: OpenClawNotificationPriority?) -> OpenClawWatchRisk?
+    {
+        if let risk { return risk }
+        switch priority {
+        case .passive:
+            return .low
+        case .active:
+            return .medium
+        case .timeSensitive:
+            return .high
+        case nil:
+            return nil
+        }
+    }
+
+    static func normalizedWatchPriority(
+        _ priority: OpenClawNotificationPriority?,
+        risk: OpenClawWatchRisk?) -> OpenClawNotificationPriority?
+    {
+        if let priority { return priority }
+        switch risk {
+        case .low:
+            return .passive
+        case .medium:
+            return .active
+        case .high:
+            return .timeSensitive
+        case nil:
+            return nil
+        }
+    }
+
+    static func trimmedOrNil(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}
--- a/openclaw/apps/ios/Sources/Model/NodeAppModel.swift
+++ b/openclaw/apps/ios/Sources/Model/NodeAppModel.swift
--- a/openclaw/apps/ios/Sources/Model/WatchReplyCoordinator.swift
+++ b/openclaw/apps/ios/Sources/Model/WatchReplyCoordinator.swift
@ -0,0 +1,46 @@
+import Foundation
+
+@MainActor
+final class WatchReplyCoordinator {
+    enum Decision {
+        case dropMissingFields
+        case deduped(replyId: String)
+        case queue(replyId: String, actionId: String)
+        case forward
+    }
+
+    private var queuedReplies: [WatchQuickReplyEvent] = []
+    private var seenReplyIds = Set<String>()
+
+    func ingest(_ event: WatchQuickReplyEvent, isGatewayConnected: Bool) -> Decision {
+        let replyId = event.replyId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let actionId = event.actionId.trimmingCharacters(in: .whitespacesAndNewlines)
+        if replyId.isEmpty || actionId.isEmpty {
+            return .dropMissingFields
+        }
+        if self.seenReplyIds.contains(replyId) {
+            return .deduped(replyId: replyId)
+        }
+        self.seenReplyIds.insert(replyId)
+        if !isGatewayConnected {
+            self.queuedReplies.append(event)
+            return .queue(replyId: replyId, actionId: actionId)
+        }
+        return .forward
+    }
+
+    func drainIfConnected(_ isGatewayConnected: Bool) -> [WatchQuickReplyEvent] {
+        guard isGatewayConnected, !self.queuedReplies.isEmpty else { return [] }
+        let pending = self.queuedReplies
+        self.queuedReplies.removeAll()
+        return pending
+    }
+
+    func requeueFront(_ event: WatchQuickReplyEvent) {
+        self.queuedReplies.insert(event, at: 0)
+    }
+
+    var queuedCount: Int {
+        self.queuedReplies.count
+    }
+}
--- a/openclaw/apps/ios/Sources/Motion/MotionService.swift
+++ b/openclaw/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: [OpenClawMotionActivityEntry] = try await withCheckedThrowingContinuation { cont 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: OpenClawPedometerPayload = try await withCheckedThrowingContinuation { cont 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"
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift
+++ b/openclaw/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift
@ -0,0 +1,386 @@
+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")
+        }
+        .gatewayTrustPromptAlert()
+    }
+}
+
+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)
+            }
+
+            gatewayConnectionStatusSection(
+                appModel: self.appModel,
+                gatewayController: self.gatewayController,
+                secondaryLine: self.connectStatusText)
+
+            Section {
+                Button("Retry") {
+                    resetGatewayConnectionState(
+                        appModel: self.appModel,
+                        connectStatusText: &self.connectStatusText,
+                        connectingGatewayID: &self.connectingGatewayID)
+                    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 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()
+            }
+
+            gatewayConnectionStatusSection(
+                appModel: self.appModel,
+                gatewayController: self.gatewayController,
+                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") {
+                    resetGatewayConnectionState(
+                        appModel: self.appModel,
+                        connectStatusText: &self.connectStatusText,
+                        connectingGatewayID: &self.connectingGatewayID)
+                    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 resetManualForm() {
+        self.setupCode = ""
+        self.setupStatusText = nil
+        self.manualHost = ""
+        self.manualPortText = ""
+        self.manualUseTLS = true
+        self.manualToken = ""
+        self.manualPassword = ""
+    }
+
+    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 = GatewaySetupCode.decode(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)
+        } else if payload.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false {
+            self.manualToken = ""
+        }
+        if let password = payload.password, !password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            self.manualPassword = password.trimmingCharacters(in: .whitespacesAndNewlines)
+        } else if payload.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false {
+            self.manualPassword = ""
+        }
+
+        let trimmedInstanceId = UserDefaults.standard.string(forKey: "node.instanceId")?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedInstanceId.isEmpty {
+            let trimmedBootstrapToken =
+                payload.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            GatewaySettingsStore.saveGatewayBootstrapToken(trimmedBootstrapToken, instanceId: trimmedInstanceId)
+        }
+
+        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
+        }
+    }
+
+    // (GatewaySetupCode) decode raw setup codes.
+}
+
+@MainActor
+private func gatewayConnectionStatusLines(
+    appModel: NodeAppModel,
+    gatewayController: GatewayConnectionController) -> [String]
+{
+    ConnectionStatusBox.defaultLines(appModel: appModel, gatewayController: gatewayController)
+}
+
+@MainActor
+private func resetGatewayConnectionState(
+    appModel: NodeAppModel,
+    connectStatusText: inout String?,
+    connectingGatewayID: inout String?)
+{
+    appModel.disconnectGateway()
+    connectStatusText = nil
+    connectingGatewayID = nil
+}
+
+@MainActor
+@ViewBuilder
+private func gatewayConnectionStatusSection(
+    appModel: NodeAppModel,
+    gatewayController: GatewayConnectionController,
+    secondaryLine: String?) -> some View
+{
+    Section("Connection status") {
+        ConnectionStatusBox(
+            statusLines: gatewayConnectionStatusLines(
+                appModel: appModel,
+                gatewayController: gatewayController),
+            secondaryLine: secondaryLine)
+    }
+}
+
+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.gatewayDisplayStatusText)",
+            "discovery: \(gatewayController.discoveryStatusText)",
+        ]
+        lines.append("server: \(appModel.gatewayServerName ?? "—")")
+        lines.append("address: \(appModel.gatewayRemoteAddress ?? "—")")
+        return lines
+    }
+}
--- a/openclaw/apps/ios/Sources/Onboarding/OnboardingStateStore.swift
+++ b/openclaw/apps/ios/Sources/Onboarding/OnboardingStateStore.swift
@ -0,0 +1,66 @@
+import Foundation
+
+enum OnboardingConnectionMode: String, CaseIterable {
+    case homeNetwork = "home_network"
+    case remoteDomain = "remote_domain"
+    case developerLocal = "developer_local"
+
+    var title: String {
+        switch self {
+        case .homeNetwork:
+            "Home Network"
+        case .remoteDomain:
+            "Remote Domain"
+        case .developerLocal:
+            "Same Machine (Dev)"
+        }
+    }
+}
+
+enum OnboardingStateStore {
+    private static let completedDefaultsKey = "onboarding.completed"
+    private static let firstRunIntroSeenDefaultsKey = "onboarding.first_run_intro_seen"
+    private static let lastModeDefaultsKey = "onboarding.last_mode"
+    private static let lastSuccessTimeDefaultsKey = "onboarding.last_success_time"
+
+    @MainActor
+    static func shouldPresentOnLaunch(appModel: NodeAppModel, defaults: UserDefaults = .standard) -> Bool {
+        if defaults.bool(forKey: Self.completedDefaultsKey) { return false }
+        // If we have a last-known connection config, don't force onboarding on launch. Auto-connect
+        // should handle reconnecting, and users can always open onboarding manually if needed.
+        if GatewaySettingsStore.loadLastGatewayConnection() != nil { return false }
+        return appModel.gatewayServerName == nil
+    }
+
+    static func markCompleted(mode: OnboardingConnectionMode? = nil, defaults: UserDefaults = .standard) {
+        defaults.set(true, forKey: Self.completedDefaultsKey)
+        if let mode {
+            defaults.set(mode.rawValue, forKey: Self.lastModeDefaultsKey)
+        }
+        defaults.set(Int(Date().timeIntervalSince1970), forKey: Self.lastSuccessTimeDefaultsKey)
+    }
+
+    static func shouldPresentFirstRunIntro(defaults: UserDefaults = .standard) -> Bool {
+        !defaults.bool(forKey: Self.firstRunIntroSeenDefaultsKey)
+    }
+
+    static func markFirstRunIntroSeen(defaults: UserDefaults = .standard) {
+        defaults.set(true, forKey: Self.firstRunIntroSeenDefaultsKey)
+    }
+
+    static func markIncomplete(defaults: UserDefaults = .standard) {
+        defaults.set(false, forKey: Self.completedDefaultsKey)
+    }
+
+    static func reset(defaults: UserDefaults = .standard) {
+        defaults.set(false, forKey: Self.completedDefaultsKey)
+        defaults.set(false, forKey: Self.firstRunIntroSeenDefaultsKey)
+    }
+
+    static func lastMode(defaults: UserDefaults = .standard) -> OnboardingConnectionMode? {
+        let raw = defaults.string(forKey: Self.lastModeDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !raw.isEmpty else { return nil }
+        return OnboardingConnectionMode(rawValue: raw)
+    }
+}
--- a/openclaw/apps/ios/Sources/Onboarding/OnboardingWizardView.swift
+++ b/openclaw/apps/ios/Sources/Onboarding/OnboardingWizardView.swift
--- a/openclaw/apps/ios/Sources/Onboarding/QRScannerView.swift
+++ b/openclaw/apps/ios/Sources/Onboarding/QRScannerView.swift
@ -0,0 +1,96 @@
+import OpenClawKit
+import SwiftUI
+import VisionKit
+
+struct QRScannerView: UIViewControllerRepresentable {
+    let onGatewayLink: (GatewayConnectDeepLink) -> Void
+    let onError: (String) -> Void
+    let onDismiss: () -> Void
+
+    func makeUIViewController(context: Context) -> UIViewController {
+        guard DataScannerViewController.isSupported else {
+            context.coordinator.reportError("QR scanning is not supported on this device.")
+            return UIViewController()
+        }
+        guard DataScannerViewController.isAvailable else {
+            context.coordinator.reportError("Camera scanning is currently unavailable.")
+            return UIViewController()
+        }
+        let scanner = DataScannerViewController(
+            recognizedDataTypes: [.barcode(symbologies: [.qr])],
+            isHighlightingEnabled: true)
+        scanner.delegate = context.coordinator
+        do {
+            try scanner.startScanning()
+        } catch {
+            context.coordinator.reportError("Could not start QR scanner.")
+        }
+        return scanner
+    }
+
+    func updateUIViewController(_: UIViewController, context _: Context) {}
+
+    static func dismantleUIViewController(_ uiViewController: UIViewController, coordinator: Coordinator) {
+        if let scanner = uiViewController as? DataScannerViewController {
+            scanner.stopScanning()
+        }
+        coordinator.parent.onDismiss()
+    }
+
+    func makeCoordinator() -> Coordinator {
+        Coordinator(parent: self)
+    }
+
+    final class Coordinator: NSObject, DataScannerViewControllerDelegate {
+        let parent: QRScannerView
+        private var handled = false
+        private var reportedError = false
+
+        init(parent: QRScannerView) {
+            self.parent = parent
+        }
+
+        func reportError(_ message: String) {
+            guard !self.reportedError else { return }
+            self.reportedError = true
+            Task { @MainActor in
+                self.parent.onError(message)
+            }
+        }
+
+        func dataScanner(_: DataScannerViewController, didAdd items: [RecognizedItem], allItems _: [RecognizedItem]) {
+            guard !self.handled else { return }
+            for item in items {
+                guard case let .barcode(barcode) = item,
+                      let payload = barcode.payloadStringValue
+                else { continue }
+
+                // Try setup code format first (base64url JSON from /pair qr).
+                if let link = GatewayConnectDeepLink.fromSetupCode(payload) {
+                    self.handled = true
+                    self.parent.onGatewayLink(link)
+                    return
+                }
+
+                // Fall back to deep link URL format (openclaw://gateway?...).
+                if let url = URL(string: payload),
+                   let route = DeepLinkParser.parse(url),
+                   case let .gateway(link) = route
+                {
+                    self.handled = true
+                    self.parent.onGatewayLink(link)
+                    return
+                }
+            }
+        }
+
+        func dataScanner(_: DataScannerViewController, didRemove _: [RecognizedItem], allItems _: [RecognizedItem]) {}
+
+        func dataScanner(
+            _: DataScannerViewController,
+            becameUnavailableWithError _: DataScannerViewController.ScanningUnavailable)
+        {
+            self.reportError("Camera is not available on this device.")
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/OpenClaw.entitlements
+++ b/openclaw/apps/ios/Sources/OpenClaw.entitlements
@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>aps-environment</key>
+	<string>development</string>
+</dict>
+</plist>
+
--- a/openclaw/apps/ios/Sources/OpenClawApp.swift
+++ b/openclaw/apps/ios/Sources/OpenClawApp.swift
@ -0,0 +1,655 @@
+import SwiftUI
+import Foundation
+import OpenClawKit
+import os
+import UIKit
+import BackgroundTasks
+@preconcurrency import UserNotifications
+
+private struct PendingWatchPromptAction {
+    var promptId: String?
+    var actionId: String
+    var actionLabel: String?
+    var sessionKey: String?
+}
+
+private typealias PendingExecApprovalPrompt = ExecApprovalNotificationPrompt
+
+@MainActor
+enum OpenClawAppModelRegistry {
+    static var appModel: NodeAppModel?
+}
+
+@MainActor
+final class OpenClawAppDelegate: NSObject, UIApplicationDelegate, @preconcurrency UNUserNotificationCenterDelegate {
+    private let logger = Logger(subsystem: "ai.openclaw.ios", category: "Push")
+    private let backgroundWakeLogger = Logger(subsystem: "ai.openclaw.ios", category: "BackgroundWake")
+    private static let wakeRefreshTaskIdentifier = "ai.openclaw.ios.bgrefresh"
+    private var backgroundWakeTask: Task<Bool, Never>?
+    private var pendingAPNsDeviceToken: Data?
+    private var pendingWatchPromptActions: [PendingWatchPromptAction] = []
+    private var pendingExecApprovalPrompts: [PendingExecApprovalPrompt] = []
+    private var pendingExecApprovalRequestedPushIDs: [String] = []
+    private var pendingExecApprovalResolvedPushIDs: [String] = []
+
+    weak var appModel: NodeAppModel? {
+        didSet {
+            guard let model = self.resolvedAppModel() else { return }
+            if let token = self.pendingAPNsDeviceToken {
+                self.pendingAPNsDeviceToken = nil
+                Task { @MainActor in
+                    model.updateAPNsDeviceToken(token)
+                }
+            }
+            if !self.pendingWatchPromptActions.isEmpty {
+                let pending = self.pendingWatchPromptActions
+                self.pendingWatchPromptActions.removeAll()
+                Task { @MainActor in
+                    for action in pending {
+                        await model.handleMirroredWatchPromptAction(
+                            promptId: action.promptId,
+                            actionId: action.actionId,
+                            actionLabel: action.actionLabel,
+                            sessionKey: action.sessionKey)
+                    }
+                }
+            }
+            if !self.pendingExecApprovalPrompts.isEmpty {
+                let pending = self.pendingExecApprovalPrompts
+                self.pendingExecApprovalPrompts.removeAll()
+                Task { @MainActor in
+                    for prompt in pending {
+                        await model.presentExecApprovalNotificationPrompt(prompt)
+                    }
+                }
+            }
+            if !self.pendingExecApprovalRequestedPushIDs.isEmpty {
+                let pending = self.pendingExecApprovalRequestedPushIDs
+                self.pendingExecApprovalRequestedPushIDs.removeAll()
+                Task { @MainActor in
+                    for approvalId in pending {
+                        _ = await model.handleExecApprovalRequestedRemotePush(approvalId: approvalId)
+                    }
+                }
+            }
+            if !self.pendingExecApprovalResolvedPushIDs.isEmpty {
+                let pending = self.pendingExecApprovalResolvedPushIDs
+                self.pendingExecApprovalResolvedPushIDs.removeAll()
+                Task { @MainActor in
+                    for approvalId in pending {
+                        await model.handleExecApprovalResolvedRemotePush(approvalId: approvalId)
+                    }
+                }
+            }
+        }
+    }
+
+    private func resolvedAppModel() -> NodeAppModel? {
+        self.appModel ?? OpenClawAppModelRegistry.appModel
+    }
+
+#if DEBUG
+    func _test_resolvedAppModel() -> NodeAppModel? {
+        self.resolvedAppModel()
+    }
+#endif
+
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+    ) -> Bool
+    {
+        GatewayDiagnostics.log("app delegate: didFinishLaunching")
+        if self.appModel == nil {
+            self.appModel = OpenClawAppModelRegistry.appModel
+        }
+        self.registerBackgroundWakeRefreshTask()
+        let notificationCenter = UNUserNotificationCenter.current()
+        notificationCenter.delegate = self
+        ExecApprovalNotificationBridge.registerCategory(center: notificationCenter)
+        application.registerForRemoteNotifications()
+        return true
+    }
+
+    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+        if let appModel = self.resolvedAppModel() {
+            Task { @MainActor in
+                appModel.updateAPNsDeviceToken(deviceToken)
+            }
+            return
+        }
+
+        self.pendingAPNsDeviceToken = deviceToken
+    }
+
+    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: any Error) {
+        self.logger.error("APNs registration failed: \(error.localizedDescription, privacy: .public)")
+    }
+
+    func application(
+        _ application: UIApplication,
+        didReceiveRemoteNotification userInfo: [AnyHashable: Any],
+        fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
+    {
+        self.logger.info("APNs remote notification received keys=\(userInfo.keys.count, privacy: .public)")
+        Task { @MainActor in
+            let notificationCenter = LiveNotificationCenter()
+            if await ExecApprovalNotificationBridge.handleResolvedPushIfNeeded(
+                userInfo: userInfo,
+                notificationCenter: notificationCenter)
+            {
+                if let approvalId = ExecApprovalNotificationBridge.approvalID(from: userInfo) {
+                    if let appModel = self.resolvedAppModel() {
+                        await appModel.handleExecApprovalResolvedRemotePush(approvalId: approvalId)
+                    } else {
+                        self.pendingExecApprovalResolvedPushIDs.append(approvalId)
+                    }
+                }
+                completionHandler(.newData)
+                return
+            }
+            guard let appModel = self.resolvedAppModel() else {
+                if ExecApprovalNotificationBridge.payloadKind(userInfo: userInfo)
+                    == ExecApprovalNotificationBridge.requestedKind,
+                   let approvalId = ExecApprovalNotificationBridge.approvalID(from: userInfo)
+                {
+                    self.pendingExecApprovalRequestedPushIDs.append(approvalId)
+                }
+                self.logger.info("APNs wake skipped: appModel unavailable")
+                self.scheduleBackgroundWakeRefresh(afterSeconds: 90, reason: "silent_push_no_model")
+                completionHandler(.noData)
+                return
+            }
+            let handled = await appModel.handleSilentPushWake(userInfo)
+            self.logger.info("APNs wake handled=\(handled, privacy: .public)")
+            if !handled {
+                self.scheduleBackgroundWakeRefresh(afterSeconds: 90, reason: "silent_push_not_applied")
+            }
+            completionHandler(handled ? .newData : .noData)
+        }
+    }
+
+    func scenePhaseChanged(_ phase: ScenePhase) {
+        GatewayDiagnostics.log("app delegate: scene phase changed=\(String(describing: phase))")
+        if phase == .background {
+            self.scheduleBackgroundWakeRefresh(afterSeconds: 120, reason: "scene_background")
+        }
+    }
+
+    private func registerBackgroundWakeRefreshTask() {
+        BGTaskScheduler.shared.register(
+            forTaskWithIdentifier: Self.wakeRefreshTaskIdentifier,
+            using: nil
+        ) { [weak self] task in
+            guard let refreshTask = task as? BGAppRefreshTask else {
+                task.setTaskCompleted(success: false)
+                return
+            }
+            self?.handleBackgroundWakeRefresh(task: refreshTask)
+        }
+    }
+
+    private func scheduleBackgroundWakeRefresh(afterSeconds delay: TimeInterval, reason: String) {
+        let request = BGAppRefreshTaskRequest(identifier: Self.wakeRefreshTaskIdentifier)
+        request.earliestBeginDate = Date().addingTimeInterval(max(60, delay))
+        do {
+            try BGTaskScheduler.shared.submit(request)
+            let scheduledLogMessage =
+                "Scheduled background wake refresh reason=\(reason) "
+                + "delaySeconds=\(max(60, delay))"
+            self.backgroundWakeLogger.info(
+                "\(scheduledLogMessage, privacy: .public)"
+            )
+        } catch {
+            let failedLogMessage =
+                "Failed scheduling background wake refresh reason=\(reason) "
+                + "error=\(error.localizedDescription)"
+            self.backgroundWakeLogger.error(
+                "\(failedLogMessage, privacy: .public)"
+            )
+        }
+    }
+
+    private func handleBackgroundWakeRefresh(task: BGAppRefreshTask) {
+        self.scheduleBackgroundWakeRefresh(afterSeconds: 15 * 60, reason: "reschedule")
+        self.backgroundWakeTask?.cancel()
+
+        let wakeTask = Task { @MainActor [weak self] in
+            guard let self, let appModel = self.resolvedAppModel() else { return false }
+            return await appModel.handleBackgroundRefreshWake(trigger: "bg_app_refresh")
+        }
+        self.backgroundWakeTask = wakeTask
+        task.expirationHandler = {
+            wakeTask.cancel()
+        }
+        Task {
+            let applied = await wakeTask.value
+            task.setTaskCompleted(success: applied)
+            self.backgroundWakeLogger.info(
+                "Background wake refresh finished applied=\(applied, privacy: .public)")
+        }
+    }
+
+    private static func isWatchPromptNotification(_ userInfo: [AnyHashable: Any]) -> Bool {
+        (userInfo[WatchPromptNotificationBridge.typeKey] as? String) == WatchPromptNotificationBridge.typeValue
+    }
+
+    private static func parseWatchPromptAction(
+        from response: UNNotificationResponse) -> PendingWatchPromptAction?
+    {
+        let userInfo = response.notification.request.content.userInfo
+        guard Self.isWatchPromptNotification(userInfo) else { return nil }
+
+        let promptId = userInfo[WatchPromptNotificationBridge.promptIDKey] as? String
+        let sessionKey = userInfo[WatchPromptNotificationBridge.sessionKeyKey] as? String
+
+        switch response.actionIdentifier {
+        case WatchPromptNotificationBridge.actionPrimaryIdentifier:
+            let actionId = (userInfo[WatchPromptNotificationBridge.actionPrimaryIDKey] as? String)?
+                .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            guard !actionId.isEmpty else { return nil }
+            let actionLabel = userInfo[WatchPromptNotificationBridge.actionPrimaryLabelKey] as? String
+            return PendingWatchPromptAction(
+                promptId: promptId,
+                actionId: actionId,
+                actionLabel: actionLabel,
+                sessionKey: sessionKey)
+        case WatchPromptNotificationBridge.actionSecondaryIdentifier:
+            let actionId = (userInfo[WatchPromptNotificationBridge.actionSecondaryIDKey] as? String)?
+                .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            guard !actionId.isEmpty else { return nil }
+            let actionLabel = userInfo[WatchPromptNotificationBridge.actionSecondaryLabelKey] as? String
+            return PendingWatchPromptAction(
+                promptId: promptId,
+                actionId: actionId,
+                actionLabel: actionLabel,
+                sessionKey: sessionKey)
+        default:
+            break
+        }
+
+        guard response.actionIdentifier.hasPrefix(WatchPromptNotificationBridge.actionIdentifierPrefix) else {
+            return nil
+        }
+        let indexString = String(
+            response.actionIdentifier.dropFirst(WatchPromptNotificationBridge.actionIdentifierPrefix.count))
+        guard let actionIndex = Int(indexString), actionIndex >= 0 else {
+            return nil
+        }
+        let actionIdKey = WatchPromptNotificationBridge.actionIDKey(index: actionIndex)
+        let actionLabelKey = WatchPromptNotificationBridge.actionLabelKey(index: actionIndex)
+        let actionId = (userInfo[actionIdKey] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !actionId.isEmpty else {
+            return nil
+        }
+        let actionLabel = userInfo[actionLabelKey] as? String
+        return PendingWatchPromptAction(
+            promptId: promptId,
+            actionId: actionId,
+            actionLabel: actionLabel,
+            sessionKey: sessionKey)
+    }
+
+    private static func parseExecApprovalPrompt(
+        from response: UNNotificationResponse) -> PendingExecApprovalPrompt?
+    {
+        ExecApprovalNotificationBridge.parsePrompt(
+            actionIdentifier: response.actionIdentifier,
+            userInfo: response.notification.request.content.userInfo)
+    }
+
+    private func routeWatchPromptAction(_ action: PendingWatchPromptAction) async {
+        guard let appModel = self.resolvedAppModel() else {
+            self.pendingWatchPromptActions.append(action)
+            return
+        }
+        await appModel.handleMirroredWatchPromptAction(
+            promptId: action.promptId,
+            actionId: action.actionId,
+            actionLabel: action.actionLabel,
+            sessionKey: action.sessionKey)
+        _ = await appModel.handleBackgroundRefreshWake(trigger: "watch_prompt_action")
+    }
+
+    private func routeExecApprovalPrompt(_ prompt: PendingExecApprovalPrompt) {
+        guard let appModel = self.resolvedAppModel() else {
+            self.pendingExecApprovalPrompts.append(prompt)
+            return
+        }
+        Task { @MainActor in
+            await appModel.presentExecApprovalNotificationPrompt(prompt)
+        }
+    }
+
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        willPresent notification: UNNotification,
+        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void)
+    {
+        let userInfo = notification.request.content.userInfo
+        if Self.isWatchPromptNotification(userInfo)
+            || ExecApprovalNotificationBridge.shouldPresentNotification(userInfo: userInfo)
+        {
+            completionHandler([.banner, .list, .sound])
+            return
+        }
+        completionHandler([])
+    }
+
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        didReceive response: UNNotificationResponse,
+        withCompletionHandler completionHandler: @escaping () -> Void)
+    {
+        if let action = Self.parseWatchPromptAction(from: response) {
+            Task { @MainActor [weak self] in
+                guard let self else {
+                    completionHandler()
+                    return
+                }
+                await self.routeWatchPromptAction(action)
+                completionHandler()
+            }
+            return
+        }
+        if let prompt = Self.parseExecApprovalPrompt(from: response) {
+            Task { @MainActor [weak self] in
+                guard let self else {
+                    completionHandler()
+                    return
+                }
+                self.routeExecApprovalPrompt(prompt)
+                completionHandler()
+            }
+            return
+        }
+        completionHandler()
+    }
+}
+
+enum WatchPromptNotificationBridge {
+    static let typeKey = "openclaw.type"
+    static let typeValue = "watch.prompt"
+    static let promptIDKey = "openclaw.watch.promptId"
+    static let sessionKeyKey = "openclaw.watch.sessionKey"
+    static let actionPrimaryIDKey = "openclaw.watch.action.primary.id"
+    static let actionPrimaryLabelKey = "openclaw.watch.action.primary.label"
+    static let actionSecondaryIDKey = "openclaw.watch.action.secondary.id"
+    static let actionSecondaryLabelKey = "openclaw.watch.action.secondary.label"
+    static let actionPrimaryIdentifier = "openclaw.watch.action.primary"
+    static let actionSecondaryIdentifier = "openclaw.watch.action.secondary"
+    static let actionIdentifierPrefix = "openclaw.watch.action."
+    static let actionIDKeyPrefix = "openclaw.watch.action.id."
+    static let actionLabelKeyPrefix = "openclaw.watch.action.label."
+    static let categoryPrefix = "openclaw.watch.prompt.category."
+
+    @MainActor
+    static func scheduleMirroredWatchPromptNotificationIfNeeded(
+        invokeID: String,
+        params: OpenClawWatchNotifyParams,
+        sendResult: WatchNotificationSendResult) async
+    {
+        guard sendResult.queuedForDelivery || !sendResult.deliveredImmediately else { return }
+
+        let title = params.title.trimmingCharacters(in: .whitespacesAndNewlines)
+        let body = params.body.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !title.isEmpty || !body.isEmpty else { return }
+        guard await self.requestNotificationAuthorizationIfNeeded() else { return }
+
+        let normalizedActions = (params.actions ?? []).compactMap { action -> OpenClawWatchAction? in
+            let id = action.id.trimmingCharacters(in: .whitespacesAndNewlines)
+            let label = action.label.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !id.isEmpty, !label.isEmpty else { return nil }
+            return OpenClawWatchAction(id: id, label: label, style: action.style)
+        }
+        let displayedActions = Array(normalizedActions.prefix(4))
+
+        let center = UNUserNotificationCenter.current()
+        var categoryIdentifier = ""
+        if !displayedActions.isEmpty {
+            let categoryID = "\(self.categoryPrefix)\(invokeID)"
+            let category = UNNotificationCategory(
+                identifier: categoryID,
+                actions: self.categoryActions(displayedActions),
+                intentIdentifiers: [],
+                options: [])
+            await self.upsertNotificationCategory(category, center: center)
+            categoryIdentifier = categoryID
+        }
+
+        var userInfo: [AnyHashable: Any] = [
+            self.typeKey: self.typeValue,
+        ]
+        if let promptId = params.promptId?.trimmingCharacters(in: .whitespacesAndNewlines), !promptId.isEmpty {
+            userInfo[self.promptIDKey] = promptId
+        }
+        if let sessionKey = params.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines), !sessionKey.isEmpty {
+            userInfo[self.sessionKeyKey] = sessionKey
+        }
+        for (index, action) in displayedActions.enumerated() {
+            userInfo[self.actionIDKey(index: index)] = action.id
+            userInfo[self.actionLabelKey(index: index)] = action.label
+            if index == 0 {
+                userInfo[self.actionPrimaryIDKey] = action.id
+                userInfo[self.actionPrimaryLabelKey] = action.label
+            } else if index == 1 {
+                userInfo[self.actionSecondaryIDKey] = action.id
+                userInfo[self.actionSecondaryLabelKey] = action.label
+            }
+        }
+
+        let content = UNMutableNotificationContent()
+        content.title = title.isEmpty ? "OpenClaw" : title
+        content.body = body
+        content.sound = .default
+        content.userInfo = userInfo
+        if !categoryIdentifier.isEmpty {
+            content.categoryIdentifier = categoryIdentifier
+        }
+        if #available(iOS 15.0, *) {
+            switch params.priority ?? .active {
+            case .passive:
+                content.interruptionLevel = .passive
+            case .timeSensitive:
+                content.interruptionLevel = .timeSensitive
+            case .active:
+                content.interruptionLevel = .active
+            }
+        }
+
+        let request = UNNotificationRequest(
+            identifier: "watch.prompt.\(invokeID)",
+            content: content,
+            trigger: nil)
+        try? await self.addNotificationRequest(request, center: center)
+    }
+
+    static func actionIDKey(index: Int) -> String {
+        "\(self.actionIDKeyPrefix)\(index)"
+    }
+
+    static func actionLabelKey(index: Int) -> String {
+        "\(self.actionLabelKeyPrefix)\(index)"
+    }
+
+    private static func categoryActions(_ actions: [OpenClawWatchAction]) -> [UNNotificationAction] {
+        actions.enumerated().map { index, action in
+            let identifier: String
+            switch index {
+            case 0:
+                identifier = self.actionPrimaryIdentifier
+            case 1:
+                identifier = self.actionSecondaryIdentifier
+            default:
+                identifier = "\(self.actionIdentifierPrefix)\(index)"
+            }
+            return UNNotificationAction(
+                identifier: identifier,
+                title: action.label,
+                options: self.notificationActionOptions(style: action.style))
+        }
+    }
+
+    private static func notificationActionOptions(style: String?) -> UNNotificationActionOptions {
+        switch style?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() {
+        case "destructive":
+            return [.destructive]
+        case "foreground":
+            // For mirrored watch actions, keep handling in background when possible.
+            return []
+        default:
+            return []
+        }
+    }
+
+    private static func requestNotificationAuthorizationIfNeeded() async -> Bool {
+        let center = UNUserNotificationCenter.current()
+        let status = await self.notificationAuthorizationStatus(center: center)
+        switch status {
+        case .authorized, .provisional, .ephemeral:
+            return true
+        case .notDetermined:
+            let granted = (try? await center.requestAuthorization(options: [.alert, .sound, .badge])) ?? false
+            if !granted { return false }
+            let updatedStatus = await self.notificationAuthorizationStatus(center: center)
+            if self.isAuthorizationStatusAllowed(updatedStatus) {
+                // Refresh APNs registration immediately after the first permission grant so the
+                // gateway can receive a push registration without requiring an app relaunch.
+                await MainActor.run {
+                    UIApplication.shared.registerForRemoteNotifications()
+                }
+            }
+            return self.isAuthorizationStatusAllowed(updatedStatus)
+        case .denied:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+
+    private static func isAuthorizationStatusAllowed(_ status: UNAuthorizationStatus) -> Bool {
+        switch status {
+        case .authorized, .provisional, .ephemeral:
+            return true
+        case .denied, .notDetermined:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+
+    private static func notificationAuthorizationStatus(
+        center: UNUserNotificationCenter
+    ) async -> UNAuthorizationStatus {
+        await withCheckedContinuation { continuation in
+            center.getNotificationSettings { settings in
+                continuation.resume(returning: settings.authorizationStatus)
+            }
+        }
+    }
+
+    private static func upsertNotificationCategory(
+        _ category: UNNotificationCategory,
+        center: UNUserNotificationCenter) async
+    {
+        await withCheckedContinuation { continuation in
+            center.getNotificationCategories { categories in
+                var updated = categories
+                updated.update(with: category)
+                center.setNotificationCategories(updated)
+                continuation.resume()
+            }
+        }
+    }
+
+    private static func addNotificationRequest(
+        _ request: UNNotificationRequest,
+        center: UNUserNotificationCenter
+    ) async throws {
+        try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+            center.add(request) { error in
+                ThrowingContinuationSupport.resumeVoid(continuation, error: error)
+            }
+        }
+    }
+}
+
+extension NodeAppModel {
+    func handleMirroredWatchPromptAction(
+        promptId: String?,
+        actionId: String,
+        actionLabel: String?,
+        sessionKey: String?) async
+    {
+        let normalizedActionID = actionId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedActionID.isEmpty else { return }
+
+        let normalizedPromptID = promptId?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let normalizedSessionKey = sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let normalizedActionLabel = actionLabel?.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        let event = WatchQuickReplyEvent(
+            replyId: UUID().uuidString,
+            promptId: (normalizedPromptID?.isEmpty == false) ? normalizedPromptID! : "unknown",
+            actionId: normalizedActionID,
+            actionLabel: (normalizedActionLabel?.isEmpty == false) ? normalizedActionLabel : nil,
+            sessionKey: (normalizedSessionKey?.isEmpty == false) ? normalizedSessionKey : nil,
+            note: "source=ios.notification",
+            sentAtMs: Int(Date().timeIntervalSince1970 * 1000),
+            transport: "ios.notification")
+        await self._bridgeConsumeMirroredWatchReply(event)
+    }
+}
+
+@main
+struct OpenClawApp: App {
+    @State private var appModel: NodeAppModel
+    @State private var gatewayController: GatewayConnectionController
+    @UIApplicationDelegateAdaptor(OpenClawAppDelegate.self) private var appDelegate
+    @Environment(\.scenePhase) private var scenePhase
+
+    init() {
+        Self.installUncaughtExceptionLogger()
+        GatewaySettingsStore.bootstrapPersistence()
+        let appModel = NodeAppModel()
+        OpenClawAppModelRegistry.appModel = appModel
+        _appModel = State(initialValue: appModel)
+        _gatewayController = State(initialValue: GatewayConnectionController(appModel: appModel))
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            RootCanvas()
+                .environment(self.appModel)
+                .environment(self.appModel.voiceWake)
+                .environment(self.gatewayController)
+                .task {
+                    self.appDelegate.appModel = self.appModel
+                }
+                .onOpenURL { url in
+                    Task { await self.appModel.handleDeepLink(url: url) }
+                }
+                .onChange(of: self.scenePhase) { _, newValue in
+                    self.appModel.setScenePhase(newValue)
+                    self.gatewayController.setScenePhase(newValue)
+                    self.appDelegate.scenePhaseChanged(newValue)
+                }
+        }
+    }
+}
+
+extension OpenClawApp {
+    private static func installUncaughtExceptionLogger() {
+        NSLog("OpenClaw: installing uncaught exception handler")
+        NSSetUncaughtExceptionHandler { exception in
+            // Useful when the app hits NSExceptions from SwiftUI/WebKit internals; these do not
+            // produce a normal Swift error backtrace.
+            let reason = exception.reason ?? "(no reason)"
+            NSLog("UNCAUGHT EXCEPTION: %@ %@", exception.name.rawValue, reason)
+            for line in exception.callStackSymbols {
+                NSLog("  %@", line)
+            }
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Push/ExecApprovalNotificationBridge.swift
+++ b/openclaw/apps/ios/Sources/Push/ExecApprovalNotificationBridge.swift
@ -0,0 +1,117 @@
+import Foundation
+import UserNotifications
+
+struct ExecApprovalNotificationPrompt: Sendable, Equatable {
+    let approvalId: String
+}
+
+enum ExecApprovalNotificationBridge {
+    static let requestedKind = "exec.approval.requested"
+    static let resolvedKind = "exec.approval.resolved"
+    static let categoryIdentifier = "openclaw.exec-approval"
+    static let reviewActionIdentifier = "openclaw.exec-approval.review"
+
+    private static let localRequestPrefix = "exec.approval."
+
+    static func registerCategory(center: UNUserNotificationCenter = .current()) {
+        let category = UNNotificationCategory(
+            identifier: self.categoryIdentifier,
+            actions: [
+                UNNotificationAction(
+                    identifier: self.reviewActionIdentifier,
+                    title: "Review",
+                    options: [.foreground]),
+            ],
+            intentIdentifiers: [],
+            options: [])
+
+        center.getNotificationCategories { categories in
+            var updated = categories
+            updated.update(with: category)
+            center.setNotificationCategories(updated)
+        }
+    }
+
+    static func shouldPresentNotification(userInfo: [AnyHashable: Any]) -> Bool {
+        self.payloadKind(userInfo: userInfo) == self.requestedKind
+    }
+
+    static func parsePrompt(
+        actionIdentifier: String,
+        userInfo: [AnyHashable: Any]
+    ) -> ExecApprovalNotificationPrompt?
+    {
+        guard actionIdentifier == UNNotificationDefaultActionIdentifier
+            || actionIdentifier == self.reviewActionIdentifier
+        else {
+            return nil
+        }
+        guard self.payloadKind(userInfo: userInfo) == self.requestedKind else { return nil }
+        guard let approvalId = self.approvalID(from: userInfo) else { return nil }
+        return ExecApprovalNotificationPrompt(approvalId: approvalId)
+    }
+
+    @MainActor
+    static func handleResolvedPushIfNeeded(
+        userInfo: [AnyHashable: Any],
+        notificationCenter: NotificationCentering
+    ) async -> Bool
+    {
+        guard self.payloadKind(userInfo: userInfo) == self.resolvedKind,
+              let approvalId = self.approvalID(from: userInfo)
+        else {
+            return false
+        }
+
+        await self.removeNotifications(forApprovalID: approvalId, notificationCenter: notificationCenter)
+        return true
+    }
+
+    @MainActor
+    static func removeNotifications(
+        forApprovalID approvalId: String,
+        notificationCenter: NotificationCentering
+    ) async {
+        let normalizedID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedID.isEmpty else { return }
+
+        await notificationCenter.removePendingNotificationRequests(
+            withIdentifiers: [self.localRequestIdentifier(for: normalizedID)])
+
+        let delivered = await notificationCenter.deliveredNotifications()
+        let identifiers = delivered.compactMap { snapshot -> String? in
+            guard self.approvalID(from: snapshot.userInfo) == normalizedID else { return nil }
+            return snapshot.identifier
+        }
+        await notificationCenter.removeDeliveredNotifications(withIdentifiers: identifiers)
+    }
+
+    static func approvalID(from userInfo: [AnyHashable: Any]) -> String? {
+        let raw = self.openClawPayload(userInfo: userInfo)?["approvalId"] as? String
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func localRequestIdentifier(for approvalId: String) -> String {
+        "\(self.localRequestPrefix)\(approvalId)"
+    }
+
+    static func payloadKind(userInfo: [AnyHashable: Any]) -> String {
+        let raw = self.openClawPayload(userInfo: userInfo)?["kind"] as? String
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? "unknown" : trimmed
+    }
+
+    private static func openClawPayload(userInfo: [AnyHashable: Any]) -> [String: Any]? {
+        if let payload = userInfo["openclaw"] as? [String: Any] {
+            return payload
+        }
+        if let payload = userInfo["openclaw"] as? [AnyHashable: Any] {
+            return payload.reduce(into: [String: Any]()) { partialResult, pair in
+                guard let key = pair.key as? String else { return }
+                partialResult[key] = pair.value
+            }
+        }
+        return nil
+    }
+}
--- a/openclaw/apps/ios/Sources/Push/PushBuildConfig.swift
+++ b/openclaw/apps/ios/Sources/Push/PushBuildConfig.swift
@ -0,0 +1,75 @@
+import Foundation
+
+enum PushTransportMode: String {
+    case direct
+    case relay
+}
+
+enum PushDistributionMode: String {
+    case local
+    case official
+}
+
+enum PushAPNsEnvironment: String {
+    case sandbox
+    case production
+}
+
+struct PushBuildConfig {
+    let transport: PushTransportMode
+    let distribution: PushDistributionMode
+    let relayBaseURL: URL?
+    let apnsEnvironment: PushAPNsEnvironment
+
+    static let current = PushBuildConfig()
+
+    init(bundle: Bundle = .main) {
+        self.transport = Self.readEnum(
+            bundle: bundle,
+            key: "OpenClawPushTransport",
+            fallback: .direct)
+        self.distribution = Self.readEnum(
+            bundle: bundle,
+            key: "OpenClawPushDistribution",
+            fallback: .local)
+        self.apnsEnvironment = Self.readEnum(
+            bundle: bundle,
+            key: "OpenClawPushAPNsEnvironment",
+            fallback: Self.defaultAPNsEnvironment)
+        self.relayBaseURL = Self.readURL(bundle: bundle, key: "OpenClawPushRelayBaseURL")
+    }
+
+    var usesRelay: Bool {
+        self.transport == .relay
+    }
+
+    private static func readURL(bundle: Bundle, key: String) -> URL? {
+        guard let raw = bundle.object(forInfoDictionaryKey: key) as? String else { return nil }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        guard let components = URLComponents(string: trimmed),
+              components.scheme?.lowercased() == "https",
+              let host = components.host,
+              !host.isEmpty,
+              components.user == nil,
+              components.password == nil,
+              components.query == nil,
+              components.fragment == nil
+        else {
+            return nil
+        }
+        return components.url
+    }
+
+    private static func readEnum<T: RawRepresentable>(
+        bundle: Bundle,
+        key: String,
+        fallback: T)
+    -> T where T.RawValue == String {
+        guard let raw = bundle.object(forInfoDictionaryKey: key) as? String else { return fallback }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return T(rawValue: trimmed) ?? fallback
+    }
+
+    private static let defaultAPNsEnvironment: PushAPNsEnvironment = .sandbox
+}
--- a/openclaw/apps/ios/Sources/Push/PushRegistrationManager.swift
+++ b/openclaw/apps/ios/Sources/Push/PushRegistrationManager.swift
@ -0,0 +1,169 @@
+import CryptoKit
+import Foundation
+
+private struct DirectGatewayPushRegistrationPayload: Encodable {
+    var transport: String = PushTransportMode.direct.rawValue
+    var token: String
+    var topic: String
+    var environment: String
+}
+
+private struct RelayGatewayPushRegistrationPayload: Encodable {
+    var transport: String = PushTransportMode.relay.rawValue
+    var relayHandle: String
+    var sendGrant: String
+    var gatewayDeviceId: String
+    var installationId: String
+    var topic: String
+    var environment: String
+    var distribution: String
+    var tokenDebugSuffix: String?
+}
+
+struct PushRelayGatewayIdentity: Codable {
+    var deviceId: String
+    var publicKey: String
+}
+
+actor PushRegistrationManager {
+    private let buildConfig: PushBuildConfig
+    private let relayClient: PushRelayClient?
+
+    var usesRelayTransport: Bool {
+        self.buildConfig.transport == .relay
+    }
+
+    init(buildConfig: PushBuildConfig = .current) {
+        self.buildConfig = buildConfig
+        self.relayClient = buildConfig.relayBaseURL.map { PushRelayClient(baseURL: $0) }
+    }
+
+    func makeGatewayRegistrationPayload(
+        apnsTokenHex: String,
+        topic: String,
+        gatewayIdentity: PushRelayGatewayIdentity?)
+    async throws -> String {
+        switch self.buildConfig.transport {
+        case .direct:
+            return try Self.encodePayload(
+                DirectGatewayPushRegistrationPayload(
+                    token: apnsTokenHex,
+                    topic: topic,
+                    environment: self.buildConfig.apnsEnvironment.rawValue))
+        case .relay:
+            guard let gatewayIdentity else {
+                throw PushRelayError.relayMisconfigured("Missing gateway identity for relay registration")
+            }
+            return try await self.makeRelayPayload(
+                apnsTokenHex: apnsTokenHex,
+                topic: topic,
+                gatewayIdentity: gatewayIdentity)
+        }
+    }
+
+    private func makeRelayPayload(
+        apnsTokenHex: String,
+        topic: String,
+        gatewayIdentity: PushRelayGatewayIdentity)
+    async throws -> String {
+        guard self.buildConfig.distribution == .official else {
+            throw PushRelayError.relayMisconfigured(
+                "Relay transport requires OpenClawPushDistribution=official")
+        }
+        guard self.buildConfig.apnsEnvironment == .production else {
+            throw PushRelayError.relayMisconfigured(
+                "Relay transport requires OpenClawPushAPNsEnvironment=production")
+        }
+        guard let relayClient = self.relayClient else {
+            throw PushRelayError.relayBaseURLMissing
+        }
+        guard let bundleId = Bundle.main.bundleIdentifier?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !bundleId.isEmpty
+        else {
+            throw PushRelayError.relayMisconfigured("Missing bundle identifier for relay registration")
+        }
+        guard let installationId = GatewaySettingsStore.loadStableInstanceID()?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+              !installationId.isEmpty
+        else {
+            throw PushRelayError.relayMisconfigured("Missing stable installation ID for relay registration")
+        }
+
+        let tokenHashHex = Self.sha256Hex(apnsTokenHex)
+        let relayOrigin = relayClient.normalizedBaseURLString
+        if let stored = PushRelayRegistrationStore.loadRegistrationState(),
+           stored.installationId == installationId,
+           stored.gatewayDeviceId == gatewayIdentity.deviceId,
+           stored.relayOrigin == relayOrigin,
+           stored.lastAPNsTokenHashHex == tokenHashHex,
+           !Self.isExpired(stored.relayHandleExpiresAtMs)
+        {
+            return try Self.encodePayload(
+                RelayGatewayPushRegistrationPayload(
+                    relayHandle: stored.relayHandle,
+                    sendGrant: stored.sendGrant,
+                    gatewayDeviceId: gatewayIdentity.deviceId,
+                    installationId: installationId,
+                    topic: topic,
+                    environment: self.buildConfig.apnsEnvironment.rawValue,
+                    distribution: self.buildConfig.distribution.rawValue,
+                    tokenDebugSuffix: stored.tokenDebugSuffix))
+        }
+
+        let response = try await relayClient.register(
+            installationId: installationId,
+            bundleId: bundleId,
+            appVersion: DeviceInfoHelper.appVersion(),
+            environment: self.buildConfig.apnsEnvironment,
+            distribution: self.buildConfig.distribution,
+            apnsTokenHex: apnsTokenHex,
+            gatewayIdentity: gatewayIdentity)
+        let registrationState = PushRelayRegistrationStore.RegistrationState(
+            relayHandle: response.relayHandle,
+            sendGrant: response.sendGrant,
+            relayOrigin: relayOrigin,
+            gatewayDeviceId: gatewayIdentity.deviceId,
+            relayHandleExpiresAtMs: response.expiresAtMs,
+            tokenDebugSuffix: Self.normalizeTokenSuffix(response.tokenSuffix),
+            lastAPNsTokenHashHex: tokenHashHex,
+            installationId: installationId,
+            lastTransport: self.buildConfig.transport.rawValue)
+        _ = PushRelayRegistrationStore.saveRegistrationState(registrationState)
+        return try Self.encodePayload(
+            RelayGatewayPushRegistrationPayload(
+                relayHandle: response.relayHandle,
+                sendGrant: response.sendGrant,
+                gatewayDeviceId: gatewayIdentity.deviceId,
+                installationId: installationId,
+                topic: topic,
+                environment: self.buildConfig.apnsEnvironment.rawValue,
+                distribution: self.buildConfig.distribution.rawValue,
+                tokenDebugSuffix: registrationState.tokenDebugSuffix))
+    }
+
+    private static func isExpired(_ expiresAtMs: Int64?) -> Bool {
+        guard let expiresAtMs else { return true }
+        let nowMs = Int64(Date().timeIntervalSince1970 * 1000)
+        // Refresh shortly before expiry so reconnect-path republishes a live handle.
+        return expiresAtMs <= nowMs + 60_000
+    }
+
+    private static func sha256Hex(_ value: String) -> String {
+        let digest = SHA256.hash(data: Data(value.utf8))
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    private static func normalizeTokenSuffix(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func encodePayload(_ payload: some Encodable) throws -> String {
+        let data = try JSONEncoder().encode(payload)
+        guard let json = String(data: data, encoding: .utf8) else {
+            throw PushRelayError.relayMisconfigured("Failed to encode push registration payload as UTF-8")
+        }
+        return json
+    }
+}
--- a/openclaw/apps/ios/Sources/Push/PushRelayClient.swift
+++ b/openclaw/apps/ios/Sources/Push/PushRelayClient.swift
@ -0,0 +1,349 @@
+import CryptoKit
+import DeviceCheck
+import Foundation
+import StoreKit
+
+enum PushRelayError: LocalizedError {
+    case relayBaseURLMissing
+    case relayMisconfigured(String)
+    case invalidResponse(String)
+    case requestFailed(status: Int, message: String)
+    case unsupportedAppAttest
+    case missingReceipt
+
+    var errorDescription: String? {
+        switch self {
+        case .relayBaseURLMissing:
+            "Push relay base URL missing"
+        case let .relayMisconfigured(message):
+            message
+        case let .invalidResponse(message):
+            message
+        case let .requestFailed(status, message):
+            "Push relay request failed (\(status)): \(message)"
+        case .unsupportedAppAttest:
+            "App Attest unavailable on this device"
+        case .missingReceipt:
+            "App Store receipt missing after refresh"
+        }
+    }
+}
+
+private struct PushRelayChallengeResponse: Decodable {
+    var challengeId: String
+    var challenge: String
+    var expiresAtMs: Int64
+}
+
+private struct PushRelayRegisterSignedPayload: Encodable {
+    var challengeId: String
+    var installationId: String
+    var bundleId: String
+    var environment: String
+    var distribution: String
+    var gateway: PushRelayGatewayIdentity
+    var appVersion: String
+    var apnsToken: String
+}
+
+private struct PushRelayAppAttestPayload: Encodable {
+    var keyId: String
+    var attestationObject: String?
+    var assertion: String
+    var clientDataHash: String
+    var signedPayloadBase64: String
+}
+
+private struct PushRelayReceiptPayload: Encodable {
+    var base64: String
+}
+
+private struct PushRelayRegisterRequest: Encodable {
+    var challengeId: String
+    var installationId: String
+    var bundleId: String
+    var environment: String
+    var distribution: String
+    var gateway: PushRelayGatewayIdentity
+    var appVersion: String
+    var apnsToken: String
+    var appAttest: PushRelayAppAttestPayload
+    var receipt: PushRelayReceiptPayload
+}
+
+struct PushRelayRegisterResponse: Decodable {
+    var relayHandle: String
+    var sendGrant: String
+    var expiresAtMs: Int64?
+    var tokenSuffix: String?
+    var status: String
+}
+
+private struct RelayErrorResponse: Decodable {
+    var error: String?
+    var message: String?
+    var reason: String?
+}
+
+private final class PushRelayReceiptRefreshCoordinator: NSObject, SKRequestDelegate {
+    private var continuation: CheckedContinuation<Void, Error>?
+    private var activeRequest: SKReceiptRefreshRequest?
+
+    func refresh() async throws {
+        try await withCheckedThrowingContinuation { continuation in
+            self.continuation = continuation
+            let request = SKReceiptRefreshRequest()
+            self.activeRequest = request
+            request.delegate = self
+            request.start()
+        }
+    }
+
+    func requestDidFinish(_ request: SKRequest) {
+        self.continuation?.resume(returning: ())
+        self.continuation = nil
+        self.activeRequest = nil
+    }
+
+    func request(_ request: SKRequest, didFailWithError error: Error) {
+        self.continuation?.resume(throwing: error)
+        self.continuation = nil
+        self.activeRequest = nil
+    }
+}
+
+private struct PushRelayAppAttestProof {
+    var keyId: String
+    var attestationObject: String?
+    var assertion: String
+    var clientDataHash: String
+    var signedPayloadBase64: String
+}
+
+private final class PushRelayAppAttestService {
+    func createProof(challenge: String, signedPayload: Data) async throws -> PushRelayAppAttestProof {
+        let service = DCAppAttestService.shared
+        guard service.isSupported else {
+            throw PushRelayError.unsupportedAppAttest
+        }
+
+        let keyID = try await self.loadOrCreateKeyID(using: service)
+        let attestationObject = try await self.attestKeyIfNeeded(
+            service: service,
+            keyID: keyID,
+            challenge: challenge)
+        let signedPayloadHash = Data(SHA256.hash(data: signedPayload))
+        let assertion = try await self.generateAssertion(
+            service: service,
+            keyID: keyID,
+            signedPayloadHash: signedPayloadHash)
+
+        return PushRelayAppAttestProof(
+            keyId: keyID,
+            attestationObject: attestationObject,
+            assertion: assertion.base64EncodedString(),
+            clientDataHash: Self.base64URL(signedPayloadHash),
+            signedPayloadBase64: signedPayload.base64EncodedString())
+    }
+
+    private func loadOrCreateKeyID(using service: DCAppAttestService) async throws -> String {
+        if let existing = PushRelayRegistrationStore.loadAppAttestKeyID(), !existing.isEmpty {
+            return existing
+        }
+        let keyID = try await service.generateKey()
+        _ = PushRelayRegistrationStore.saveAppAttestKeyID(keyID)
+        return keyID
+    }
+
+    private func attestKeyIfNeeded(
+        service: DCAppAttestService,
+        keyID: String,
+        challenge: String)
+    async throws -> String? {
+        if PushRelayRegistrationStore.loadAttestedKeyID() == keyID {
+            return nil
+        }
+        let challengeData = Data(challenge.utf8)
+        let clientDataHash = Data(SHA256.hash(data: challengeData))
+        let attestation = try await service.attestKey(keyID, clientDataHash: clientDataHash)
+        // Apple treats App Attest key attestation as a one-time operation. Save the
+        // attested marker immediately so later receipt/network failures do not cause a
+        // permanently broken re-attestation loop on the same key.
+        _ = PushRelayRegistrationStore.saveAttestedKeyID(keyID)
+        return attestation.base64EncodedString()
+    }
+
+    private func generateAssertion(
+        service: DCAppAttestService,
+        keyID: String,
+        signedPayloadHash: Data)
+    async throws -> Data {
+        do {
+            return try await service.generateAssertion(keyID, clientDataHash: signedPayloadHash)
+        } catch {
+            _ = PushRelayRegistrationStore.clearAppAttestKeyID()
+            _ = PushRelayRegistrationStore.clearAttestedKeyID()
+            throw error
+        }
+    }
+
+    private static func base64URL(_ data: Data) -> String {
+        data.base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+    }
+}
+
+private final class PushRelayReceiptProvider {
+    func loadReceiptBase64() async throws -> String {
+        if let receipt = self.readReceiptData() {
+            return receipt.base64EncodedString()
+        }
+        let refreshCoordinator = PushRelayReceiptRefreshCoordinator()
+        try await refreshCoordinator.refresh()
+        if let refreshed = self.readReceiptData() {
+            return refreshed.base64EncodedString()
+        }
+        throw PushRelayError.missingReceipt
+    }
+
+    private func readReceiptData() -> Data? {
+        guard let url = Bundle.main.appStoreReceiptURL else { return nil }
+        guard let data = try? Data(contentsOf: url), !data.isEmpty else { return nil }
+        return data
+    }
+}
+
+// The client is constructed once and used behind PushRegistrationManager actor isolation.
+final class PushRelayClient: @unchecked Sendable {
+    private let baseURL: URL
+    private let session: URLSession
+    private let jsonDecoder = JSONDecoder()
+    private let jsonEncoder = JSONEncoder()
+    private let appAttest = PushRelayAppAttestService()
+    private let receiptProvider = PushRelayReceiptProvider()
+
+    init(baseURL: URL, session: URLSession = .shared) {
+        self.baseURL = baseURL
+        self.session = session
+    }
+
+    var normalizedBaseURLString: String {
+        Self.normalizeBaseURLString(self.baseURL)
+    }
+
+    func register(
+        installationId: String,
+        bundleId: String,
+        appVersion: String,
+        environment: PushAPNsEnvironment,
+        distribution: PushDistributionMode,
+        apnsTokenHex: String,
+        gatewayIdentity: PushRelayGatewayIdentity)
+    async throws -> PushRelayRegisterResponse {
+        let challenge = try await self.fetchChallenge()
+        let signedPayload = PushRelayRegisterSignedPayload(
+            challengeId: challenge.challengeId,
+            installationId: installationId,
+            bundleId: bundleId,
+            environment: environment.rawValue,
+            distribution: distribution.rawValue,
+            gateway: gatewayIdentity,
+            appVersion: appVersion,
+            apnsToken: apnsTokenHex)
+        let signedPayloadData = try self.jsonEncoder.encode(signedPayload)
+        let appAttest = try await self.appAttest.createProof(
+            challenge: challenge.challenge,
+            signedPayload: signedPayloadData)
+        let receiptBase64 = try await self.receiptProvider.loadReceiptBase64()
+        let requestBody = PushRelayRegisterRequest(
+            challengeId: signedPayload.challengeId,
+            installationId: signedPayload.installationId,
+            bundleId: signedPayload.bundleId,
+            environment: signedPayload.environment,
+            distribution: signedPayload.distribution,
+            gateway: signedPayload.gateway,
+            appVersion: signedPayload.appVersion,
+            apnsToken: signedPayload.apnsToken,
+            appAttest: PushRelayAppAttestPayload(
+                keyId: appAttest.keyId,
+                attestationObject: appAttest.attestationObject,
+                assertion: appAttest.assertion,
+                clientDataHash: appAttest.clientDataHash,
+                signedPayloadBase64: appAttest.signedPayloadBase64),
+            receipt: PushRelayReceiptPayload(base64: receiptBase64))
+
+        let endpoint = self.baseURL.appending(path: "v1/push/register")
+        var request = URLRequest(url: endpoint)
+        request.httpMethod = "POST"
+        request.timeoutInterval = 20
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.httpBody = try self.jsonEncoder.encode(requestBody)
+
+        let (data, response) = try await self.session.data(for: request)
+        let status = Self.statusCode(from: response)
+        guard (200..<300).contains(status) else {
+            if status == 401 {
+                // If the relay rejects registration, drop local App Attest state so the next
+                // attempt re-attests instead of getting stuck without an attestation object.
+                _ = PushRelayRegistrationStore.clearAppAttestKeyID()
+                _ = PushRelayRegistrationStore.clearAttestedKeyID()
+            }
+            throw PushRelayError.requestFailed(
+                status: status,
+                message: Self.decodeErrorMessage(data: data))
+        }
+        let decoded = try self.decode(PushRelayRegisterResponse.self, from: data)
+        return decoded
+    }
+
+    private func fetchChallenge() async throws -> PushRelayChallengeResponse {
+        let endpoint = self.baseURL.appending(path: "v1/push/challenge")
+        var request = URLRequest(url: endpoint)
+        request.httpMethod = "POST"
+        request.timeoutInterval = 10
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.httpBody = Data("{}".utf8)
+
+        let (data, response) = try await self.session.data(for: request)
+        let status = Self.statusCode(from: response)
+        guard (200..<300).contains(status) else {
+            throw PushRelayError.requestFailed(
+                status: status,
+                message: Self.decodeErrorMessage(data: data))
+        }
+        return try self.decode(PushRelayChallengeResponse.self, from: data)
+    }
+
+    private func decode<T: Decodable>(_ type: T.Type, from data: Data) throws -> T {
+        do {
+            return try self.jsonDecoder.decode(type, from: data)
+        } catch {
+            throw PushRelayError.invalidResponse(error.localizedDescription)
+        }
+    }
+
+    private static func statusCode(from response: URLResponse) -> Int {
+        (response as? HTTPURLResponse)?.statusCode ?? 0
+    }
+
+    private static func normalizeBaseURLString(_ url: URL) -> String {
+        var absolute = url.absoluteString
+        while absolute.hasSuffix("/") {
+            absolute.removeLast()
+        }
+        return absolute
+    }
+
+    private static func decodeErrorMessage(data: Data) -> String {
+        if let decoded = try? JSONDecoder().decode(RelayErrorResponse.self, from: data) {
+            let message = decoded.message ?? decoded.reason ?? decoded.error ?? ""
+            if !message.isEmpty {
+                return message
+            }
+        }
+        let raw = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return raw.isEmpty ? "unknown relay error" : raw
+    }
+}
--- a/openclaw/apps/ios/Sources/Push/PushRelayKeychainStore.swift
+++ b/openclaw/apps/ios/Sources/Push/PushRelayKeychainStore.swift
@ -0,0 +1,112 @@
+import Foundation
+
+private struct StoredPushRelayRegistrationState: Codable {
+    var relayHandle: String
+    var sendGrant: String
+    var relayOrigin: String?
+    var gatewayDeviceId: String
+    var relayHandleExpiresAtMs: Int64?
+    var tokenDebugSuffix: String?
+    var lastAPNsTokenHashHex: String
+    var installationId: String
+    var lastTransport: String
+}
+
+enum PushRelayRegistrationStore {
+    private static let service = "ai.openclaw.pushrelay"
+    private static let registrationStateAccount = "registration-state"
+    private static let appAttestKeyIDAccount = "app-attest-key-id"
+    private static let appAttestedKeyIDAccount = "app-attested-key-id"
+
+    struct RegistrationState: Codable {
+        var relayHandle: String
+        var sendGrant: String
+        var relayOrigin: String?
+        var gatewayDeviceId: String
+        var relayHandleExpiresAtMs: Int64?
+        var tokenDebugSuffix: String?
+        var lastAPNsTokenHashHex: String
+        var installationId: String
+        var lastTransport: String
+    }
+
+    static func loadRegistrationState() -> RegistrationState? {
+        guard let raw = KeychainStore.loadString(
+            service: self.service,
+            account: self.registrationStateAccount),
+            let data = raw.data(using: .utf8),
+            let decoded = try? JSONDecoder().decode(StoredPushRelayRegistrationState.self, from: data)
+        else {
+            return nil
+        }
+        return RegistrationState(
+            relayHandle: decoded.relayHandle,
+            sendGrant: decoded.sendGrant,
+            relayOrigin: decoded.relayOrigin,
+            gatewayDeviceId: decoded.gatewayDeviceId,
+            relayHandleExpiresAtMs: decoded.relayHandleExpiresAtMs,
+            tokenDebugSuffix: decoded.tokenDebugSuffix,
+            lastAPNsTokenHashHex: decoded.lastAPNsTokenHashHex,
+            installationId: decoded.installationId,
+            lastTransport: decoded.lastTransport)
+    }
+
+    @discardableResult
+    static func saveRegistrationState(_ state: RegistrationState) -> Bool {
+        let stored = StoredPushRelayRegistrationState(
+            relayHandle: state.relayHandle,
+            sendGrant: state.sendGrant,
+            relayOrigin: state.relayOrigin,
+            gatewayDeviceId: state.gatewayDeviceId,
+            relayHandleExpiresAtMs: state.relayHandleExpiresAtMs,
+            tokenDebugSuffix: state.tokenDebugSuffix,
+            lastAPNsTokenHashHex: state.lastAPNsTokenHashHex,
+            installationId: state.installationId,
+            lastTransport: state.lastTransport)
+        guard let data = try? JSONEncoder().encode(stored),
+              let raw = String(data: data, encoding: .utf8)
+        else {
+            return false
+        }
+        return KeychainStore.saveString(raw, service: self.service, account: self.registrationStateAccount)
+    }
+
+    @discardableResult
+    static func clearRegistrationState() -> Bool {
+        KeychainStore.delete(service: self.service, account: self.registrationStateAccount)
+    }
+
+    static func loadAppAttestKeyID() -> String? {
+        let value = KeychainStore.loadString(service: self.service, account: self.appAttestKeyIDAccount)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if value?.isEmpty == false { return value }
+        return nil
+    }
+
+    @discardableResult
+    static func saveAppAttestKeyID(_ keyID: String) -> Bool {
+        KeychainStore.saveString(keyID, service: self.service, account: self.appAttestKeyIDAccount)
+    }
+
+    @discardableResult
+    static func clearAppAttestKeyID() -> Bool {
+        KeychainStore.delete(service: self.service, account: self.appAttestKeyIDAccount)
+    }
+
+    static func loadAttestedKeyID() -> String? {
+        let value = KeychainStore.loadString(service: self.service, account: self.appAttestedKeyIDAccount)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if value?.isEmpty == false { return value }
+        return nil
+    }
+
+    @discardableResult
+    static func saveAttestedKeyID(_ keyID: String) -> Bool {
+        KeychainStore.saveString(keyID, service: self.service, account: self.appAttestedKeyIDAccount)
+    }
+
+    @discardableResult
+    static func clearAttestedKeyID() -> Bool {
+        KeychainStore.delete(service: self.service, account: self.appAttestedKeyIDAccount)
+    }
+}
--- a/openclaw/apps/ios/Sources/Reminders/RemindersService.swift
+++ b/openclaw/apps/ios/Sources/Reminders/RemindersService.swift
@ -0,0 +1,133 @@
+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 = EventKitAuthorization.allowsRead(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: [OpenClawReminderPayload] = try await withCheckedThrowingContinuation { cont 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 = EventKitAuthorization.allowsWrite(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 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",
+        ])
+    }
+}
--- a/openclaw/apps/ios/Sources/RootCanvas.swift
+++ b/openclaw/apps/ios/Sources/RootCanvas.swift
@ -0,0 +1,601 @@
+import SwiftUI
+import UIKit
+import OpenClawProtocol
+
+struct RootCanvas: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @Environment(GatewayConnectionController.self) private var gatewayController
+    @Environment(VoiceWakeManager.self) private var voiceWake
+    @Environment(\.colorScheme) private var systemColorScheme
+    @Environment(\.scenePhase) private var scenePhase
+    @AppStorage(VoiceWakePreferences.enabledKey) private var voiceWakeEnabled: Bool = false
+    @AppStorage("screen.preventSleep") private var preventSleep: Bool = true
+    @AppStorage("canvas.debugStatusEnabled") private var canvasDebugStatusEnabled: Bool = false
+    @AppStorage("onboarding.requestID") private var onboardingRequestID: Int = 0
+    @AppStorage("gateway.onboardingComplete") private var onboardingComplete: Bool = false
+    @AppStorage("gateway.hasConnectedOnce") private var hasConnectedOnce: Bool = false
+    @AppStorage("gateway.preferredStableID") private var preferredGatewayStableID: String = ""
+    @AppStorage("gateway.manual.enabled") private var manualGatewayEnabled: Bool = false
+    @AppStorage("gateway.manual.host") private var manualGatewayHost: String = ""
+    @AppStorage("onboarding.quickSetupDismissed") private var quickSetupDismissed: Bool = false
+    @State private var presentedSheet: PresentedSheet?
+    @State private var voiceWakeToastText: String?
+    @State private var toastDismissTask: Task<Void, Never>?
+    @State private var showOnboarding: Bool = false
+    @State private var onboardingAllowSkip: Bool = true
+    @State private var didEvaluateOnboarding: Bool = false
+    @State private var didAutoOpenSettings: Bool = false
+
+    private enum PresentedSheet: Identifiable {
+        case settings
+        case chat
+        case quickSetup
+
+        var id: Int {
+            switch self {
+            case .settings: 0
+            case .chat: 1
+            case .quickSetup: 2
+            }
+        }
+    }
+
+    enum StartupPresentationRoute: Equatable {
+        case none
+        case onboarding
+        case settings
+    }
+
+    static func startupPresentationRoute(
+        gatewayConnected: Bool,
+        hasConnectedOnce: Bool,
+        onboardingComplete: Bool,
+        hasExistingGatewayConfig: Bool,
+        shouldPresentOnLaunch: Bool) -> StartupPresentationRoute
+    {
+        if gatewayConnected {
+            return .none
+        }
+        // On first run or explicit launch onboarding state, onboarding always wins.
+        if shouldPresentOnLaunch || !hasConnectedOnce || !onboardingComplete {
+            return .onboarding
+        }
+        // Settings auto-open is a recovery path for previously-connected installs only.
+        if !hasExistingGatewayConfig {
+            return .settings
+        }
+        return .none
+    }
+
+    static func shouldPresentQuickSetup(
+        quickSetupDismissed: Bool,
+        showOnboarding: Bool,
+        hasPresentedSheet: Bool,
+        gatewayConnected: Bool,
+        hasExistingGatewayConfig: Bool,
+        discoveredGatewayCount: Int) -> Bool
+    {
+        guard !quickSetupDismissed else { return false }
+        guard !showOnboarding else { return false }
+        guard !hasPresentedSheet else { return false }
+        guard !gatewayConnected else { return false }
+        // If a gateway target is already configured (manual or last-known), skip quick setup.
+        guard !hasExistingGatewayConfig else { return false }
+        return discoveredGatewayCount > 0
+    }
+
+    var body: some View {
+        ZStack {
+            CanvasContent(
+                systemColorScheme: self.systemColorScheme,
+                gatewayStatus: self.gatewayStatus,
+                voiceWakeEnabled: self.voiceWakeEnabled,
+                voiceWakeToastText: self.voiceWakeToastText,
+                cameraHUDText: self.appModel.cameraHUDText,
+                cameraHUDKind: self.appModel.cameraHUDKind,
+                openChat: {
+                    self.presentedSheet = .chat
+                },
+                openSettings: {
+                    self.presentedSheet = .settings
+                },
+                retryGatewayConnection: {
+                    Task { await self.gatewayController.connectLastKnown() }
+                })
+                .preferredColorScheme(.dark)
+
+            if self.appModel.cameraFlashNonce != 0 {
+                CameraFlashOverlay(nonce: self.appModel.cameraFlashNonce)
+            }
+        }
+        .gatewayTrustPromptAlert()
+        .deepLinkAgentPromptAlert()
+        .execApprovalPromptDialog()
+        .sheet(item: self.$presentedSheet) { sheet in
+            switch sheet {
+            case .settings:
+                SettingsTab()
+                    .environment(self.appModel)
+                    .environment(self.appModel.voiceWake)
+                    .environment(self.gatewayController)
+            case .chat:
+                ChatSheet(
+                    // Chat RPCs run on the operator session (read/write scopes).
+                    gateway: self.appModel.operatorSession,
+                    sessionKey: self.appModel.chatSessionKey,
+                    agentName: self.appModel.activeAgentName,
+                    userAccent: self.appModel.seamColor)
+            case .quickSetup:
+                GatewayQuickSetupSheet()
+                    .environment(self.appModel)
+                    .environment(self.gatewayController)
+            }
+        }
+        .fullScreenCover(isPresented: self.$showOnboarding) {
+            OnboardingWizardView(
+                allowSkip: self.onboardingAllowSkip,
+                onClose: {
+                    self.showOnboarding = false
+                })
+                .environment(self.appModel)
+                .environment(self.appModel.voiceWake)
+                .environment(self.gatewayController)
+        }
+        .onAppear { self.updateIdleTimer() }
+        .onAppear { self.updateHomeCanvasState() }
+        .onAppear { self.evaluateOnboardingPresentation(force: false) }
+        .onAppear { self.maybeAutoOpenSettings() }
+        .onChange(of: self.preventSleep) { _, _ in self.updateIdleTimer() }
+        .onChange(of: self.scenePhase) { _, newValue in
+            self.updateIdleTimer()
+            self.updateHomeCanvasState()
+            guard newValue == .active else { return }
+            Task {
+                await self.appModel.refreshGatewayOverviewIfConnected()
+                await MainActor.run {
+                    self.updateHomeCanvasState()
+                }
+            }
+        }
+        .onAppear { self.maybeShowQuickSetup() }
+        .onChange(of: self.gatewayController.gateways.count) { _, _ in self.maybeShowQuickSetup() }
+        .onAppear { self.updateCanvasDebugStatus() }
+        .onChange(of: self.canvasDebugStatusEnabled) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayStatusText) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
+        .onChange(of: self.appModel.gatewayServerName) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
+        .onChange(of: self.appModel.gatewayServerName) { _, newValue in
+            if newValue != nil {
+                self.showOnboarding = false
+            }
+        }
+        .onChange(of: self.onboardingRequestID) { _, _ in
+            self.evaluateOnboardingPresentation(force: true)
+        }
+        .onChange(of: self.appModel.gatewayRemoteAddress) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
+        .onChange(of: self.appModel.homeCanvasRevision) { _, _ in
+            self.updateHomeCanvasState()
+        }
+        .onChange(of: self.appModel.gatewayServerName) { _, newValue in
+            if newValue != nil {
+                self.onboardingComplete = true
+                self.hasConnectedOnce = true
+                OnboardingStateStore.markCompleted(mode: nil)
+            }
+            self.maybeAutoOpenSettings()
+        }
+        .onChange(of: self.appModel.openChatRequestID) { _, _ in
+            self.presentedSheet = .chat
+        }
+        .onChange(of: self.voiceWake.lastTriggeredCommand) { _, newValue in
+            guard let newValue else { return }
+            let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return }
+
+            self.toastDismissTask?.cancel()
+            withAnimation(.spring(response: 0.25, dampingFraction: 0.85)) {
+                self.voiceWakeToastText = trimmed
+            }
+
+            self.toastDismissTask = Task {
+                try? await Task.sleep(nanoseconds: 2_300_000_000)
+                await MainActor.run {
+                    withAnimation(.easeOut(duration: 0.25)) {
+                        self.voiceWakeToastText = nil
+                    }
+                }
+            }
+        }
+        .onDisappear {
+            UIApplication.shared.isIdleTimerDisabled = false
+            self.toastDismissTask?.cancel()
+            self.toastDismissTask = nil
+        }
+    }
+
+    private var gatewayStatus: StatusPill.GatewayState {
+        GatewayStatusBuilder.build(appModel: self.appModel)
+    }
+
+    private func updateIdleTimer() {
+        UIApplication.shared.isIdleTimerDisabled = (self.scenePhase == .active && self.preventSleep)
+    }
+
+    private func updateCanvasDebugStatus() {
+        self.appModel.screen.setDebugStatusEnabled(self.canvasDebugStatusEnabled)
+        guard self.canvasDebugStatusEnabled else { return }
+        let title = self.appModel.gatewayDisplayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        let subtitle = self.appModel.gatewayServerName ?? self.appModel.gatewayRemoteAddress
+        self.appModel.screen.updateDebugStatus(title: title, subtitle: subtitle)
+    }
+
+    private func updateHomeCanvasState() {
+        let payload = self.makeHomeCanvasPayload()
+        guard let data = try? JSONEncoder().encode(payload),
+              let json = String(data: data, encoding: .utf8)
+        else {
+            self.appModel.screen.updateHomeCanvasState(json: nil)
+            return
+        }
+        self.appModel.screen.updateHomeCanvasState(json: json)
+    }
+
+    private func makeHomeCanvasPayload() -> HomeCanvasPayload {
+        let gatewayName = self.normalized(self.appModel.gatewayServerName)
+        let gatewayAddress = self.normalized(self.appModel.gatewayRemoteAddress)
+        let gatewayLabel = gatewayName ?? gatewayAddress ?? "Gateway"
+        let activeAgentID = self.resolveActiveAgentID()
+        let agents = self.homeCanvasAgents(activeAgentID: activeAgentID)
+
+        switch self.gatewayStatus {
+        case .connected:
+            return HomeCanvasPayload(
+                gatewayState: "connected",
+                eyebrow: "Connected to \(gatewayLabel)",
+                title: "Your agents are ready",
+                subtitle:
+                    "This phone stays dormant until the gateway needs it, then wakes, syncs, and goes back to sleep.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: self.appModel.activeAgentName,
+                activeAgentBadge: agents.first(where: { $0.isActive })?.badge ?? "OC",
+                activeAgentCaption: "Selected on this phone",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(6)),
+                footer: "The overview refreshes on reconnect and when the app returns to foreground.")
+        case .connecting:
+            return HomeCanvasPayload(
+                gatewayState: "connecting",
+                eyebrow: "Reconnecting",
+                title: "OpenClaw is syncing back up",
+                subtitle:
+                    "The gateway session is coming back online. "
+                    + "Agent shortcuts should settle automatically in a moment.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: self.appModel.activeAgentName,
+                activeAgentBadge: "OC",
+                activeAgentCaption: "Gateway session in progress",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(4)),
+                footer: "If the gateway is reachable, reconnect should complete without intervention.")
+        case .error, .disconnected:
+            return HomeCanvasPayload(
+                gatewayState: self.gatewayStatus == .error ? "error" : "offline",
+                eyebrow: "Welcome to OpenClaw",
+                title: "Your phone stays quiet until it is needed",
+                subtitle:
+                    "Pair this device to your gateway to wake it only for real work, "
+                    + "keep a live agent overview handy, and avoid battery-draining background loops.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: "Main",
+                activeAgentBadge: "OC",
+                activeAgentCaption: "Connect to load your agents",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(4)),
+                footer:
+                    "When connected, the gateway can wake the phone with a silent push "
+                    + "instead of holding an always-on session.")
+        }
+    }
+
+    private func resolveActiveAgentID() -> String {
+        let selected = self.normalized(self.appModel.selectedAgentId) ?? ""
+        if !selected.isEmpty {
+            return selected
+        }
+        return self.resolveDefaultAgentID()
+    }
+
+    private func resolveDefaultAgentID() -> String {
+        self.normalized(self.appModel.gatewayDefaultAgentId) ?? ""
+    }
+
+    private func homeCanvasAgents(activeAgentID: String) -> [HomeCanvasAgentCard] {
+        let defaultAgentID = self.resolveDefaultAgentID()
+        let cards = self.appModel.gatewayAgents.map { agent -> HomeCanvasAgentCard in
+            let isActive = !activeAgentID.isEmpty && agent.id == activeAgentID
+            let isDefault = !defaultAgentID.isEmpty && agent.id == defaultAgentID
+            return HomeCanvasAgentCard(
+                id: agent.id,
+                name: self.homeCanvasName(for: agent),
+                badge: self.homeCanvasBadge(for: agent),
+                caption: isActive ? "Active on this phone" : (isDefault ? "Default agent" : "Ready"),
+                isActive: isActive)
+        }
+
+        return cards.sorted { lhs, rhs in
+            if lhs.isActive != rhs.isActive {
+                return lhs.isActive
+            }
+            return lhs.name.localizedCaseInsensitiveCompare(rhs.name) == .orderedAscending
+        }
+    }
+
+    private func homeCanvasName(for agent: AgentSummary) -> String {
+        self.normalized(agent.name) ?? agent.id
+    }
+
+    private func homeCanvasBadge(for agent: AgentSummary) -> String {
+        if let identity = agent.identity,
+           let emoji = identity["emoji"]?.value as? String,
+           let normalizedEmoji = self.normalized(emoji)
+        {
+            return normalizedEmoji
+        }
+        let words = self.homeCanvasName(for: agent)
+            .split(whereSeparator: { $0.isWhitespace || $0 == "-" || $0 == "_" })
+            .prefix(2)
+        let initials = words.compactMap { $0.first }.map(String.init).joined()
+        if !initials.isEmpty {
+            return initials.uppercased()
+        }
+        return "OC"
+    }
+
+    private func normalized(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private func evaluateOnboardingPresentation(force: Bool) {
+        if force {
+            self.onboardingAllowSkip = true
+            self.showOnboarding = true
+            return
+        }
+
+        guard !self.didEvaluateOnboarding else { return }
+        self.didEvaluateOnboarding = true
+        let route = Self.startupPresentationRoute(
+            gatewayConnected: self.appModel.gatewayServerName != nil,
+            hasConnectedOnce: self.hasConnectedOnce,
+            onboardingComplete: self.onboardingComplete,
+            hasExistingGatewayConfig: self.hasExistingGatewayConfig(),
+            shouldPresentOnLaunch: OnboardingStateStore.shouldPresentOnLaunch(appModel: self.appModel))
+        switch route {
+        case .none:
+            break
+        case .onboarding:
+            self.onboardingAllowSkip = true
+            self.showOnboarding = true
+        case .settings:
+            self.didAutoOpenSettings = true
+            self.presentedSheet = .settings
+        }
+    }
+
+    private func hasExistingGatewayConfig() -> Bool {
+        if self.appModel.activeGatewayConnectConfig != nil { return true }
+        if GatewaySettingsStore.loadLastGatewayConnection() != nil { return true }
+
+        let preferredStableID = self.preferredGatewayStableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !preferredStableID.isEmpty { return true }
+
+        let manualHost = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        return self.manualGatewayEnabled && !manualHost.isEmpty
+    }
+
+    private func maybeAutoOpenSettings() {
+        guard !self.didAutoOpenSettings else { return }
+        guard !self.showOnboarding else { return }
+        let route = Self.startupPresentationRoute(
+            gatewayConnected: self.appModel.gatewayServerName != nil,
+            hasConnectedOnce: self.hasConnectedOnce,
+            onboardingComplete: self.onboardingComplete,
+            hasExistingGatewayConfig: self.hasExistingGatewayConfig(),
+            shouldPresentOnLaunch: false)
+        guard route == .settings else { return }
+        self.didAutoOpenSettings = true
+        self.presentedSheet = .settings
+    }
+
+    private func maybeShowQuickSetup() {
+        let shouldPresent = Self.shouldPresentQuickSetup(
+            quickSetupDismissed: self.quickSetupDismissed,
+            showOnboarding: self.showOnboarding,
+            hasPresentedSheet: self.presentedSheet != nil,
+            gatewayConnected: self.appModel.gatewayServerName != nil,
+            hasExistingGatewayConfig: self.hasExistingGatewayConfig(),
+            discoveredGatewayCount: self.gatewayController.gateways.count)
+        guard shouldPresent else { return }
+        self.presentedSheet = .quickSetup
+    }
+}
+
+private struct HomeCanvasPayload: Codable {
+    var gatewayState: String
+    var eyebrow: String
+    var title: String
+    var subtitle: String
+    var gatewayLabel: String
+    var activeAgentName: String
+    var activeAgentBadge: String
+    var activeAgentCaption: String
+    var agentCount: Int
+    var agents: [HomeCanvasAgentCard]
+    var footer: String
+}
+
+private struct HomeCanvasAgentCard: Codable {
+    var id: String
+    var name: String
+    var badge: String
+    var caption: String
+    var isActive: Bool
+}
+
+private struct CanvasContent: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @AppStorage("talk.enabled") private var talkEnabled: Bool = false
+    @AppStorage("talk.button.enabled") private var talkButtonEnabled: Bool = true
+    @State private var showGatewayActions: Bool = false
+    @State private var showGatewayProblemDetails: Bool = false
+    var systemColorScheme: ColorScheme
+    var gatewayStatus: StatusPill.GatewayState
+    var voiceWakeEnabled: Bool
+    var voiceWakeToastText: String?
+    var cameraHUDText: String?
+    var cameraHUDKind: NodeAppModel.CameraHUDKind?
+    var openChat: () -> Void
+    var openSettings: () -> Void
+    var retryGatewayConnection: () -> Void
+
+    private var brightenButtons: Bool { self.systemColorScheme == .light }
+    private var talkActive: Bool { self.appModel.talkMode.isEnabled || self.talkEnabled }
+
+    var body: some View {
+        ZStack {
+            ScreenTab()
+        }
+        .overlay(alignment: .center) {
+            if self.talkActive {
+                TalkOrbOverlay()
+                    .transition(.opacity)
+            }
+        }
+        .safeAreaInset(edge: .bottom, spacing: 0) {
+            HomeToolbar(
+                gateway: self.gatewayStatus,
+                voiceWakeEnabled: self.voiceWakeEnabled,
+                activity: self.statusActivity,
+                brighten: self.brightenButtons,
+                talkButtonEnabled: self.talkButtonEnabled,
+                talkActive: self.talkActive,
+                talkTint: self.appModel.seamColor,
+                onStatusTap: {
+                    if self.gatewayStatus == .connected {
+                        self.showGatewayActions = true
+                    } else if self.appModel.lastGatewayProblem != nil {
+                        self.showGatewayProblemDetails = true
+                    } else {
+                        self.openSettings()
+                    }
+                },
+                onChatTap: {
+                    self.openChat()
+                },
+                onTalkTap: {
+                    let next = !self.talkActive
+                    self.talkEnabled = next
+                    self.appModel.setTalkEnabled(next)
+                },
+                onSettingsTap: {
+                    self.openSettings()
+                })
+        }
+        .overlay(alignment: .top) {
+            if let gatewayProblem = self.appModel.lastGatewayProblem,
+               self.gatewayStatus != .connected
+            {
+                GatewayProblemBanner(
+                    problem: gatewayProblem,
+                    primaryActionTitle: gatewayProblem.retryable ? "Retry" : "Open Settings",
+                    onPrimaryAction: {
+                        if gatewayProblem.retryable {
+                            self.retryGatewayConnection()
+                        } else {
+                            self.openSettings()
+                        }
+                    },
+                    onShowDetails: {
+                        self.showGatewayProblemDetails = true
+                    })
+                    .padding(.horizontal, 12)
+                    .safeAreaPadding(.top, 10)
+                    .transition(.move(edge: .top).combined(with: .opacity))
+            }
+        }
+        .overlay(alignment: .topLeading) {
+            if let voiceWakeToastText, !voiceWakeToastText.isEmpty {
+                VoiceWakeToast(
+                    command: voiceWakeToastText,
+                    brighten: self.brightenButtons)
+                    .padding(.leading, 10)
+                    .safeAreaPadding(.top, self.appModel.lastGatewayProblem == nil ? 58 : 132)
+                    .transition(.move(edge: .top).combined(with: .opacity))
+            }
+        }
+        .gatewayActionsDialog(
+            isPresented: self.$showGatewayActions,
+            onDisconnect: { self.appModel.disconnectGateway() },
+            onOpenSettings: { self.openSettings() })
+        .sheet(isPresented: self.$showGatewayProblemDetails) {
+            if let gatewayProblem = self.appModel.lastGatewayProblem {
+                GatewayProblemDetailsSheet(
+                    problem: gatewayProblem,
+                    primaryActionTitle: "Open Settings",
+                    onPrimaryAction: {
+                        self.openSettings()
+                    })
+            }
+        }
+        .onAppear {
+            // Keep the runtime talk state aligned with persisted toggle state on cold launch.
+            if self.talkEnabled != self.appModel.talkMode.isEnabled {
+                self.appModel.setTalkEnabled(self.talkEnabled)
+            }
+        }
+    }
+
+    private var statusActivity: StatusPill.Activity? {
+        StatusActivityBuilder.build(
+            appModel: self.appModel,
+            voiceWakeEnabled: self.voiceWakeEnabled,
+            cameraHUDText: self.cameraHUDText,
+            cameraHUDKind: self.cameraHUDKind)
+    }
+}
+
+private struct CameraFlashOverlay: View {
+    var nonce: Int
+
+    @State private var opacity: CGFloat = 0
+    @State private var task: Task<Void, Never>?
+
+    var body: some View {
+        Color.white
+            .opacity(self.opacity)
+            .ignoresSafeArea()
+            .allowsHitTesting(false)
+            .onChange(of: self.nonce) { _, _ in
+                self.task?.cancel()
+                self.task = Task { @MainActor in
+                    withAnimation(.easeOut(duration: 0.08)) {
+                        self.opacity = 0.85
+                    }
+                    try? await Task.sleep(nanoseconds: 110_000_000)
+                    withAnimation(.easeOut(duration: 0.32)) {
+                        self.opacity = 0
+                    }
+                }
+            }
+    }
+}
--- a/openclaw/apps/ios/Sources/RootTabs.swift
+++ b/openclaw/apps/ios/Sources/RootTabs.swift
@ -0,0 +1,121 @@
+import SwiftUI
+
+struct RootTabs: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @Environment(VoiceWakeManager.self) private var voiceWake
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @AppStorage(VoiceWakePreferences.enabledKey) private var voiceWakeEnabled: Bool = false
+    @State private var selectedTab: Int = 0
+    @State private var voiceWakeToastText: String?
+    @State private var toastDismissTask: Task<Void, Never>?
+    @State private var showGatewayActions: Bool = false
+    @State private var showGatewayProblemDetails: Bool = false
+
+    var body: some View {
+        TabView(selection: self.$selectedTab) {
+            ScreenTab()
+                .tabItem { Label("Screen", systemImage: "rectangle.and.hand.point.up.left") }
+                .tag(0)
+
+            VoiceTab()
+                .tabItem { Label("Voice", systemImage: "mic") }
+                .tag(1)
+
+            SettingsTab()
+                .tabItem { Label("Settings", systemImage: "gearshape") }
+                .tag(2)
+        }
+        .overlay(alignment: .topLeading) {
+            StatusPill(
+                gateway: self.gatewayStatus,
+                voiceWakeEnabled: self.voiceWakeEnabled,
+                activity: self.statusActivity,
+                onTap: {
+                    if self.gatewayStatus == .connected {
+                        self.showGatewayActions = true
+                    } else if self.appModel.lastGatewayProblem != nil {
+                        self.showGatewayProblemDetails = true
+                    } else {
+                        self.selectedTab = 2
+                    }
+                })
+                .padding(.leading, 10)
+                .safeAreaPadding(.top, 10)
+        }
+        .overlay(alignment: .top) {
+            if let gatewayProblem = self.appModel.lastGatewayProblem,
+               self.gatewayStatus != .connected
+            {
+                GatewayProblemBanner(
+                    problem: gatewayProblem,
+                    primaryActionTitle: "Open Settings",
+                    onPrimaryAction: {
+                        self.selectedTab = 2
+                    },
+                    onShowDetails: {
+                        self.showGatewayProblemDetails = true
+                    })
+                    .padding(.horizontal, 12)
+                    .safeAreaPadding(.top, 10)
+                    .transition(.move(edge: .top).combined(with: .opacity))
+            }
+        }
+        .overlay(alignment: .topLeading) {
+            if let voiceWakeToastText, !voiceWakeToastText.isEmpty {
+                VoiceWakeToast(command: voiceWakeToastText)
+                    .padding(.leading, 10)
+                    .safeAreaPadding(.top, self.appModel.lastGatewayProblem == nil ? 58 : 132)
+                    .transition(.move(edge: .top).combined(with: .opacity))
+            }
+        }
+        .onChange(of: self.voiceWake.lastTriggeredCommand) { _, newValue in
+            guard let newValue else { return }
+            let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return }
+
+            self.toastDismissTask?.cancel()
+            withAnimation(self.reduceMotion ? .none : .spring(response: 0.25, dampingFraction: 0.85)) {
+                self.voiceWakeToastText = trimmed
+            }
+
+            self.toastDismissTask = Task {
+                try? await Task.sleep(nanoseconds: 2_300_000_000)
+                await MainActor.run {
+                    withAnimation(self.reduceMotion ? .none : .easeOut(duration: 0.25)) {
+                        self.voiceWakeToastText = nil
+                    }
+                }
+            }
+        }
+        .onDisappear {
+            self.toastDismissTask?.cancel()
+            self.toastDismissTask = nil
+        }
+        .gatewayActionsDialog(
+            isPresented: self.$showGatewayActions,
+            onDisconnect: { self.appModel.disconnectGateway() },
+            onOpenSettings: { self.selectedTab = 2 })
+        .sheet(isPresented: self.$showGatewayProblemDetails) {
+            if let gatewayProblem = self.appModel.lastGatewayProblem {
+                GatewayProblemDetailsSheet(
+                    problem: gatewayProblem,
+                    primaryActionTitle: "Open Settings",
+                    onPrimaryAction: {
+                        self.selectedTab = 2
+                    })
+            }
+        }
+    }
+
+    private var gatewayStatus: StatusPill.GatewayState {
+        GatewayStatusBuilder.build(appModel: self.appModel)
+    }
+
+    private var statusActivity: StatusPill.Activity? {
+        StatusActivityBuilder.build(
+            appModel: self.appModel,
+            voiceWakeEnabled: self.voiceWakeEnabled,
+            cameraHUDText: self.appModel.cameraHUDText,
+            cameraHUDKind: self.appModel.cameraHUDKind)
+    }
+}
--- a/openclaw/apps/ios/Sources/RootView.swift
+++ b/openclaw/apps/ios/Sources/RootView.swift
@ -0,0 +1,7 @@
+import SwiftUI
+
+struct RootView: View {
+    var body: some View {
+        RootCanvas()
+    }
+}
--- a/openclaw/apps/ios/Sources/Screen/ScreenController.swift
+++ b/openclaw/apps/ios/Sources/Screen/ScreenController.swift
@ -0,0 +1,312 @@
+import OpenClawKit
+import Observation
+import UIKit
+import WebKit
+
+@MainActor
+@Observable
+final class ScreenController {
+    private weak var activeWebView: WKWebView?
+    private var trustedRemoteA2UIURL: URL?
+
+    var urlString: String = ""
+    var errorText: String?
+
+    /// Callback invoked when an openclaw:// deep link is tapped in the canvas
+    var onDeepLink: ((URL) -> Void)?
+
+    /// Callback invoked when the user clicks an A2UI action (e.g. button) inside the canvas web UI.
+    var onA2UIAction: (([String: Any]) -> Void)?
+
+    private var debugStatusEnabled: Bool = false
+    private var debugStatusTitle: String?
+    private var debugStatusSubtitle: String?
+    private var homeCanvasStateJSON: String?
+
+    init() {
+        self.reload()
+    }
+
+    func navigate(to urlString: String, trustA2UIActions: Bool = false) {
+        let trimmed = urlString.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            self.urlString = ""
+            self.trustedRemoteA2UIURL = nil
+            self.reload()
+            return
+        }
+        if let url = URL(string: trimmed),
+           !url.isFileURL,
+           let host = url.host,
+           LoopbackHost.isLoopback(host)
+        {
+            // Never try to load loopback URLs from a remote gateway.
+            self.showDefaultCanvas()
+            return
+        }
+        self.urlString = (trimmed == "/" ? "" : trimmed)
+        self.trustedRemoteA2UIURL = trustA2UIActions ? Self.normalizeTrustedRemoteA2UIURL(from: trimmed) : nil
+        self.reload()
+    }
+
+    func reload() {
+        self.applyScrollBehavior()
+        guard let webView = self.activeWebView else { return }
+
+        let trimmed = self.urlString.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            guard let url = Self.canvasScaffoldURL else { return }
+            self.errorText = nil
+            webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())
+            return
+        }
+
+        guard let url = URL(string: trimmed) else {
+            self.errorText = "Invalid URL: \(trimmed)"
+            return
+        }
+        self.errorText = nil
+        if url.isFileURL {
+            webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())
+        } else {
+            webView.load(URLRequest(url: url))
+        }
+    }
+
+    func showDefaultCanvas() {
+        self.urlString = ""
+        self.trustedRemoteA2UIURL = nil
+        self.reload()
+    }
+
+    func setDebugStatusEnabled(_ enabled: Bool) {
+        self.debugStatusEnabled = enabled
+        self.applyDebugStatusIfNeeded()
+    }
+
+    func updateDebugStatus(title: String?, subtitle: String?) {
+        self.debugStatusTitle = title
+        self.debugStatusSubtitle = subtitle
+        self.applyDebugStatusIfNeeded()
+    }
+
+    func applyDebugStatusIfNeeded() {
+        guard let webView = self.activeWebView else { return }
+        WebViewJavaScriptSupport.applyDebugStatus(
+            webView: webView,
+            enabled: self.debugStatusEnabled,
+            title: self.debugStatusTitle,
+            subtitle: self.debugStatusSubtitle)
+    }
+
+    func updateHomeCanvasState(json: String?) {
+        self.homeCanvasStateJSON = json
+        self.applyHomeCanvasStateIfNeeded()
+    }
+
+    func applyHomeCanvasStateIfNeeded() {
+        guard let webView = self.activeWebView else { return }
+        let payload = self.homeCanvasStateJSON ?? "null"
+        let js = """
+        (() => {
+          try {
+            const api = globalThis.__openclaw;
+            if (!api || typeof api.renderHome !== 'function') return;
+            api.renderHome(\(payload));
+          } catch (_) {}
+        })()
+        """
+        webView.evaluateJavaScript(js) { _, _ in }
+    }
+
+    func waitForA2UIReady(timeoutMs: Int) async -> Bool {
+        let clock = ContinuousClock()
+        let deadline = clock.now.advanced(by: .milliseconds(timeoutMs))
+        while clock.now < deadline {
+            do {
+                let res = try await self.eval(javaScript: """
+                (() => {
+                  try {
+                    const host = globalThis.openclawA2UI;
+                    return !!host && typeof host.applyMessages === 'function';
+                  } catch (_) { return false; }
+                })()
+                """)
+                let trimmed = res.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+                if trimmed == "true" || trimmed == "1" { return true }
+            } catch {
+                // ignore; page likely still loading
+            }
+            try? await Task.sleep(nanoseconds: 120_000_000)
+        }
+        return false
+    }
+
+    func eval(javaScript: String) async throws -> String {
+        guard let webView = self.activeWebView else {
+            throw NSError(domain: "Screen", code: 3, userInfo: [
+                NSLocalizedDescriptionKey: "web view unavailable",
+            ])
+        }
+        return try await WebViewJavaScriptSupport.evaluateToString(webView: webView, javaScript: javaScript)
+    }
+
+    func snapshotPNGBase64(maxWidth: CGFloat? = nil) async throws -> String {
+        let image = try await self.snapshotImage(maxWidth: maxWidth)
+        guard let data = image.pngData() else {
+            throw NSError(domain: "Screen", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "snapshot encode failed",
+            ])
+        }
+        return data.base64EncodedString()
+    }
+
+    func snapshotBase64(
+        maxWidth: CGFloat? = nil,
+        format: OpenClawCanvasSnapshotFormat,
+        quality: Double? = nil) async throws -> String
+    {
+        let image = try await self.snapshotImage(maxWidth: maxWidth)
+
+        let data: Data?
+        switch format {
+        case .png:
+            data = image.pngData()
+        case .jpeg:
+            let q = (quality ?? 0.82).clamped(to: 0.1...1.0)
+            data = image.jpegData(compressionQuality: q)
+        }
+        guard let data else {
+            throw NSError(domain: "Screen", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "snapshot encode failed",
+            ])
+        }
+        return data.base64EncodedString()
+    }
+
+    private func snapshotImage(maxWidth: CGFloat?) async throws -> UIImage {
+        let config = WKSnapshotConfiguration()
+        if let maxWidth {
+            config.snapshotWidth = NSNumber(value: Double(maxWidth))
+        }
+        guard let webView = self.activeWebView else {
+            throw NSError(domain: "Screen", code: 3, userInfo: [
+                NSLocalizedDescriptionKey: "web view unavailable",
+            ])
+        }
+        let image: UIImage = try await withCheckedThrowingContinuation { cont in
+            webView.takeSnapshot(with: config) { image, error in
+                if let error {
+                    cont.resume(throwing: error)
+                    return
+                }
+                guard let image else {
+                    cont.resume(throwing: NSError(domain: "Screen", code: 2, userInfo: [
+                        NSLocalizedDescriptionKey: "snapshot failed",
+                    ]))
+                    return
+                }
+                cont.resume(returning: image)
+            }
+        }
+        return image
+    }
+
+    func attachWebView(_ webView: WKWebView) {
+        self.activeWebView = webView
+        self.reload()
+        self.applyDebugStatusIfNeeded()
+        self.applyHomeCanvasStateIfNeeded()
+    }
+
+    func detachWebView(_ webView: WKWebView) {
+        guard self.activeWebView === webView else { return }
+        self.activeWebView = nil
+    }
+
+    private static func bundledResourceURL(
+        name: String,
+        ext: String,
+        subdirectory: String)
+        -> URL?
+    {
+        let bundle = OpenClawKitResources.bundle
+        return bundle.url(forResource: name, withExtension: ext, subdirectory: subdirectory)
+            ?? bundle.url(forResource: name, withExtension: ext)
+    }
+
+    private static let canvasScaffoldURL: URL? = ScreenController.bundledResourceURL(
+        name: "scaffold",
+        ext: "html",
+        subdirectory: "CanvasScaffold")
+
+    func isTrustedCanvasUIURL(_ url: URL) -> Bool {
+        if url.isFileURL {
+            let std = url.standardizedFileURL
+            if let expected = Self.canvasScaffoldURL,
+               std == expected.standardizedFileURL
+            {
+                return true
+            }
+            return false
+        }
+        guard let trusted = self.trustedRemoteA2UIURL else { return false }
+        return Self.normalizeTrustedRemoteA2UIURL(from: url) == trusted
+    }
+
+    nonisolated static func parseA2UIActionBody(_ body: Any) -> [String: Any]? {
+        if let dict = body as? [String: Any] { return dict.isEmpty ? nil : dict }
+        if let str = body as? String,
+           let data = str.data(using: .utf8),
+           let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        {
+            return json.isEmpty ? nil : json
+        }
+        if let dict = body as? [AnyHashable: Any] {
+            let mapped = dict.reduce(into: [String: Any]()) { acc, pair in
+                guard let key = pair.key as? String else { return }
+                acc[key] = pair.value
+            }
+            return mapped.isEmpty ? nil : mapped
+        }
+        return nil
+    }
+
+    private func applyScrollBehavior() {
+        guard let webView = self.activeWebView else { return }
+        let trimmed = self.urlString.trimmingCharacters(in: .whitespacesAndNewlines)
+        let allowScroll = !trimmed.isEmpty
+        let scrollView = webView.scrollView
+        // Default canvas needs raw touch events; external pages should scroll.
+        scrollView.isScrollEnabled = allowScroll
+        scrollView.bounces = allowScroll
+    }
+
+    private static func normalizeTrustedRemoteA2UIURL(from raw: String) -> URL? {
+        guard let url = URL(string: raw) else { return nil }
+        return self.normalizeTrustedRemoteA2UIURL(from: url)
+    }
+
+    private static func normalizeTrustedRemoteA2UIURL(from url: URL) -> URL? {
+        guard !url.isFileURL else { return nil }
+        guard let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" else {
+            return nil
+        }
+        guard let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines), !host.isEmpty else {
+            return nil
+        }
+        var components = URLComponents(url: url, resolvingAgainstBaseURL: false)
+        components?.scheme = scheme
+        components?.host = host.lowercased()
+        components?.fragment = nil
+        return components?.url
+    }
+}
+
+extension Double {
+    fileprivate func clamped(to range: ClosedRange<Double>) -> Double {
+        if self < range.lowerBound { return range.lowerBound }
+        if self > range.upperBound { return range.upperBound }
+        return self
+    }
+}
--- a/openclaw/apps/ios/Sources/Screen/ScreenRecordService.swift
+++ b/openclaw/apps/ios/Sources/Screen/ScreenRecordService.swift
@ -0,0 +1,351 @@
+import AVFoundation
+import OpenClawKit
+import ReplayKit
+
+final class ScreenRecordService: @unchecked Sendable {
+    private struct UncheckedSendableBox<T>: @unchecked Sendable {
+        let value: T
+    }
+
+    private final class CaptureState: @unchecked Sendable {
+        private let lock = NSLock()
+        var writer: AVAssetWriter?
+        var videoInput: AVAssetWriterInput?
+        var audioInput: AVAssetWriterInput?
+        var started = false
+        var sawVideo = false
+        var lastVideoTime: CMTime?
+        var handlerError: Error?
+
+        func withLock<T>(_ body: (CaptureState) -> T) -> T {
+            self.lock.lock()
+            defer { lock.unlock() }
+            return body(self)
+        }
+    }
+
+    enum ScreenRecordError: LocalizedError {
+        case invalidScreenIndex(Int)
+        case captureFailed(String)
+        case writeFailed(String)
+
+        var errorDescription: String? {
+            switch self {
+            case let .invalidScreenIndex(idx):
+                "Invalid screen index \(idx)"
+            case let .captureFailed(msg):
+                msg
+            case let .writeFailed(msg):
+                msg
+            }
+        }
+    }
+
+    func record(
+        screenIndex: Int?,
+        durationMs: Int?,
+        fps: Double?,
+        includeAudio: Bool?,
+        outPath: String?) async throws -> String
+    {
+        let config = try self.makeRecordConfig(
+            screenIndex: screenIndex,
+            durationMs: durationMs,
+            fps: fps,
+            includeAudio: includeAudio,
+            outPath: outPath)
+
+        let state = CaptureState()
+        let recordQueue = DispatchQueue(label: "ai.openclaw.screenrecord")
+
+        try await self.startCapture(state: state, config: config, recordQueue: recordQueue)
+        try await Task.sleep(nanoseconds: UInt64(config.durationMs) * 1_000_000)
+        try await self.stopCapture()
+        try self.finalizeCapture(state: state)
+        try await self.finishWriting(state: state)
+
+        return config.outURL.path
+    }
+
+    private struct RecordConfig {
+        let durationMs: Int
+        let fpsValue: Double
+        let includeAudio: Bool
+        let outURL: URL
+    }
+
+    private func makeRecordConfig(
+        screenIndex: Int?,
+        durationMs: Int?,
+        fps: Double?,
+        includeAudio: Bool?,
+        outPath: String?) throws -> RecordConfig
+    {
+        if let idx = screenIndex, idx != 0 {
+            throw ScreenRecordError.invalidScreenIndex(idx)
+        }
+
+        let durationMs = CaptureRateLimits.clampDurationMs(durationMs)
+        let fps = CaptureRateLimits.clampFps(fps, maxFps: 30)
+        let fpsInt = Int32(fps.rounded())
+        let fpsValue = Double(fpsInt)
+        let includeAudio = includeAudio ?? true
+
+        let outURL = self.makeOutputURL(outPath: outPath)
+        try? FileManager().removeItem(at: outURL)
+
+        return RecordConfig(
+            durationMs: durationMs,
+            fpsValue: fpsValue,
+            includeAudio: includeAudio,
+            outURL: outURL)
+    }
+
+    private func makeOutputURL(outPath: String?) -> URL {
+        if let outPath, !outPath.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            return URL(fileURLWithPath: outPath)
+        }
+        return FileManager().temporaryDirectory
+            .appendingPathComponent("openclaw-screen-record-\(UUID().uuidString).mp4")
+    }
+
+    private func startCapture(
+        state: CaptureState,
+        config: RecordConfig,
+        recordQueue: DispatchQueue) async throws
+    {
+        try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
+            let handler = self.makeCaptureHandler(
+                state: state,
+                config: config,
+                recordQueue: recordQueue)
+            let completion: @Sendable (Error?) -> Void = { error in
+                if let error { cont.resume(throwing: error) } else { cont.resume() }
+            }
+
+            Task { @MainActor in
+                startReplayKitCapture(
+                    includeAudio: config.includeAudio,
+                    handler: handler,
+                    completion: completion)
+            }
+        }
+    }
+
+    private func makeCaptureHandler(
+        state: CaptureState,
+        config: RecordConfig,
+        recordQueue: DispatchQueue) -> @Sendable (CMSampleBuffer, RPSampleBufferType, Error?) -> Void
+    {
+        { sample, type, error in
+            let sampleBox = UncheckedSendableBox(value: sample)
+            // ReplayKit can call the capture handler on a background queue.
+            // Serialize writes to avoid queue asserts.
+            recordQueue.async {
+                let sample = sampleBox.value
+                if let error {
+                    state.withLock { state in
+                        if state.handlerError == nil { state.handlerError = error }
+                    }
+                    return
+                }
+                guard CMSampleBufferDataIsReady(sample) else { return }
+
+                switch type {
+                case .video:
+                    self.handleVideoSample(sample, state: state, config: config)
+                case .audioApp, .audioMic:
+                    self.handleAudioSample(sample, state: state, includeAudio: config.includeAudio)
+                @unknown default:
+                    break
+                }
+            }
+        }
+    }
+
+    private func handleVideoSample(
+        _ sample: CMSampleBuffer,
+        state: CaptureState,
+        config: RecordConfig)
+    {
+        let pts = CMSampleBufferGetPresentationTimeStamp(sample)
+        let shouldSkip = state.withLock { state in
+            if let lastVideoTime = state.lastVideoTime {
+                let delta = CMTimeSubtract(pts, lastVideoTime)
+                return delta.seconds < (1.0 / config.fpsValue)
+            }
+            return false
+        }
+        if shouldSkip { return }
+
+        if state.withLock({ $0.writer == nil }) {
+            self.prepareWriter(sample: sample, state: state, config: config, pts: pts)
+        }
+
+        let vInput = state.withLock { $0.videoInput }
+        let isStarted = state.withLock { $0.started }
+        guard let vInput, isStarted else { return }
+        if vInput.isReadyForMoreMediaData {
+            if vInput.append(sample) {
+                state.withLock { state in
+                    state.sawVideo = true
+                    state.lastVideoTime = pts
+                }
+            } else {
+                let err = state.withLock { $0.writer?.error }
+                if let err {
+                    state.withLock { state in
+                        if state.handlerError == nil {
+                            state.handlerError = ScreenRecordError.writeFailed(err.localizedDescription)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    private func prepareWriter(
+        sample: CMSampleBuffer,
+        state: CaptureState,
+        config: RecordConfig,
+        pts: CMTime)
+    {
+        guard let imageBuffer = CMSampleBufferGetImageBuffer(sample) else {
+            state.withLock { state in
+                if state.handlerError == nil {
+                    state.handlerError = ScreenRecordError.captureFailed("Missing image buffer")
+                }
+            }
+            return
+        }
+        let width = CVPixelBufferGetWidth(imageBuffer)
+        let height = CVPixelBufferGetHeight(imageBuffer)
+        do {
+            let writer = try AVAssetWriter(outputURL: config.outURL, fileType: .mp4)
+            let settings: [String: Any] = [
+                AVVideoCodecKey: AVVideoCodecType.h264,
+                AVVideoWidthKey: width,
+                AVVideoHeightKey: height,
+            ]
+            let vInput = AVAssetWriterInput(mediaType: .video, outputSettings: settings)
+            vInput.expectsMediaDataInRealTime = true
+            guard writer.canAdd(vInput) else {
+                throw ScreenRecordError.writeFailed("Cannot add video input")
+            }
+            writer.add(vInput)
+
+            if config.includeAudio {
+                let aInput = AVAssetWriterInput(mediaType: .audio, outputSettings: nil)
+                aInput.expectsMediaDataInRealTime = true
+                if writer.canAdd(aInput) {
+                    writer.add(aInput)
+                    state.withLock { state in
+                        state.audioInput = aInput
+                    }
+                }
+            }
+
+            guard writer.startWriting() else {
+                throw ScreenRecordError.writeFailed(
+                    writer.error?.localizedDescription ?? "Failed to start writer")
+            }
+            writer.startSession(atSourceTime: pts)
+            state.withLock { state in
+                state.writer = writer
+                state.videoInput = vInput
+                state.started = true
+            }
+        } catch {
+            state.withLock { state in
+                if state.handlerError == nil { state.handlerError = error }
+            }
+        }
+    }
+
+    private func handleAudioSample(
+        _ sample: CMSampleBuffer,
+        state: CaptureState,
+        includeAudio: Bool)
+    {
+        let aInput = state.withLock { $0.audioInput }
+        let isStarted = state.withLock { $0.started }
+        guard includeAudio, let aInput, isStarted else { return }
+        if aInput.isReadyForMoreMediaData {
+            _ = aInput.append(sample)
+        }
+    }
+
+    private func stopCapture() async throws {
+        let stopError = await withCheckedContinuation { cont in
+            Task { @MainActor in
+                stopReplayKitCapture { error in cont.resume(returning: error) }
+            }
+        }
+        if let stopError { throw stopError }
+    }
+
+    private func finalizeCapture(state: CaptureState) throws {
+        if let handlerErrorSnapshot = state.withLock({ $0.handlerError }) {
+            throw handlerErrorSnapshot
+        }
+        let writerSnapshot = state.withLock { $0.writer }
+        let videoInputSnapshot = state.withLock { $0.videoInput }
+        let audioInputSnapshot = state.withLock { $0.audioInput }
+        let sawVideoSnapshot = state.withLock { $0.sawVideo }
+        guard let writerSnapshot, let videoInputSnapshot, sawVideoSnapshot else {
+            throw ScreenRecordError.captureFailed("No frames captured")
+        }
+
+        videoInputSnapshot.markAsFinished()
+        audioInputSnapshot?.markAsFinished()
+        _ = writerSnapshot
+    }
+
+    private func finishWriting(state: CaptureState) async throws {
+        guard let writerSnapshot = state.withLock({ $0.writer }) else {
+            throw ScreenRecordError.captureFailed("Missing writer")
+        }
+        let writerBox = UncheckedSendableBox(value: writerSnapshot)
+        try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
+            writerBox.value.finishWriting {
+                let writer = writerBox.value
+                if let err = writer.error {
+                    cont.resume(throwing: ScreenRecordError.writeFailed(err.localizedDescription))
+                } else if writer.status != .completed {
+                    cont.resume(throwing: ScreenRecordError.writeFailed("Failed to finalize video"))
+                } else {
+                    cont.resume()
+                }
+            }
+        }
+    }
+
+}
+
+@MainActor
+private func startReplayKitCapture(
+    includeAudio: Bool,
+    handler: @escaping @Sendable (CMSampleBuffer, RPSampleBufferType, Error?) -> Void,
+    completion: @escaping @Sendable (Error?) -> Void)
+{
+    let recorder = RPScreenRecorder.shared()
+    recorder.isMicrophoneEnabled = includeAudio
+    recorder.startCapture(handler: handler, completionHandler: completion)
+}
+
+@MainActor
+private func stopReplayKitCapture(_ completion: @escaping @Sendable (Error?) -> Void) {
+    RPScreenRecorder.shared().stopCapture { error in completion(error) }
+}
+
+#if DEBUG
+extension ScreenRecordService {
+    nonisolated static func _test_clampDurationMs(_ ms: Int?) -> Int {
+        CaptureRateLimits.clampDurationMs(ms)
+    }
+
+    nonisolated static func _test_clampFps(_ fps: Double?) -> Double {
+        CaptureRateLimits.clampFps(fps, maxFps: 30)
+    }
+}
+#endif
--- a/openclaw/apps/ios/Sources/Screen/ScreenTab.swift
+++ b/openclaw/apps/ios/Sources/Screen/ScreenTab.swift
@ -0,0 +1,27 @@
+import OpenClawKit
+import SwiftUI
+
+struct ScreenTab: View {
+    @Environment(NodeAppModel.self) private var appModel
+
+    var body: some View {
+        ZStack(alignment: .top) {
+            ScreenWebView(controller: self.appModel.screen)
+                .ignoresSafeArea(.container, edges: [.top, .leading, .trailing])
+                .overlay(alignment: .top) {
+                    if let errorText = self.appModel.screen.errorText,
+                       self.appModel.gatewayServerName == nil
+                    {
+                        Text(errorText)
+                            .font(.footnote)
+                            .padding(10)
+                            .background(.thinMaterial)
+                            .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
+                            .padding()
+                    }
+                }
+        }
+    }
+
+    // Navigation is agent-driven; no local URL bar here.
+}
--- a/openclaw/apps/ios/Sources/Screen/ScreenWebView.swift
+++ b/openclaw/apps/ios/Sources/Screen/ScreenWebView.swift
@ -0,0 +1,189 @@
+import OpenClawKit
+import SwiftUI
+import WebKit
+
+struct ScreenWebView: UIViewRepresentable {
+    var controller: ScreenController
+
+    func makeCoordinator() -> ScreenWebViewCoordinator {
+        ScreenWebViewCoordinator(controller: self.controller)
+    }
+
+    func makeUIView(context: Context) -> UIView {
+        context.coordinator.makeContainerView()
+    }
+
+    func updateUIView(_: UIView, context: Context) {
+        context.coordinator.updateController(self.controller)
+    }
+
+    static func dismantleUIView(_: UIView, coordinator: ScreenWebViewCoordinator) {
+        coordinator.teardown()
+    }
+}
+
+@MainActor
+final class ScreenWebViewCoordinator: NSObject {
+    private weak var controller: ScreenController?
+    private let navigationDelegate = ScreenNavigationDelegate()
+    private let a2uiActionHandler = CanvasA2UIActionMessageHandler()
+    private let userContentController = WKUserContentController()
+
+    private(set) var managedWebView: WKWebView?
+    private weak var containerView: UIView?
+
+    init(controller: ScreenController) {
+        self.controller = controller
+        super.init()
+        self.navigationDelegate.controller = controller
+        self.a2uiActionHandler.controller = controller
+    }
+
+    func makeContainerView() -> UIView {
+        if let containerView {
+            return containerView
+        }
+
+        let container = UIView(frame: .zero)
+        container.backgroundColor = .black
+
+        let webView = Self.makeWebView(userContentController: self.userContentController)
+        webView.navigationDelegate = self.navigationDelegate
+        self.installA2UIHandlers()
+
+        webView.translatesAutoresizingMaskIntoConstraints = false
+        container.addSubview(webView)
+        NSLayoutConstraint.activate([
+            webView.leadingAnchor.constraint(equalTo: container.leadingAnchor),
+            webView.trailingAnchor.constraint(equalTo: container.trailingAnchor),
+            webView.topAnchor.constraint(equalTo: container.topAnchor),
+            webView.bottomAnchor.constraint(equalTo: container.bottomAnchor),
+        ])
+
+        self.managedWebView = webView
+        self.containerView = container
+        self.controller?.attachWebView(webView)
+        return container
+    }
+
+    func updateController(_ controller: ScreenController) {
+        let previousController = self.controller
+        let controllerChanged = self.controller !== controller
+        self.controller = controller
+        self.navigationDelegate.controller = controller
+        self.a2uiActionHandler.controller = controller
+        if controllerChanged, let managedWebView {
+            previousController?.detachWebView(managedWebView)
+            controller.attachWebView(managedWebView)
+        }
+    }
+
+    func teardown() {
+        if let managedWebView {
+            self.controller?.detachWebView(managedWebView)
+            managedWebView.navigationDelegate = nil
+        }
+        self.removeA2UIHandlers()
+        self.navigationDelegate.controller = nil
+        self.a2uiActionHandler.controller = nil
+        self.managedWebView = nil
+        self.containerView = nil
+    }
+
+    private static func makeWebView(userContentController: WKUserContentController) -> WKWebView {
+        let config = WKWebViewConfiguration()
+        config.websiteDataStore = .nonPersistent()
+        config.userContentController = userContentController
+
+        let webView = WKWebView(frame: .zero, configuration: config)
+        // Canvas scaffold is a fully self-contained HTML page; avoid relying on transparency underlays.
+        webView.isOpaque = true
+        webView.backgroundColor = .black
+
+        let scrollView = webView.scrollView
+        scrollView.backgroundColor = .black
+        scrollView.contentInsetAdjustmentBehavior = .never
+        scrollView.contentInset = .zero
+        scrollView.scrollIndicatorInsets = .zero
+        scrollView.automaticallyAdjustsScrollIndicatorInsets = false
+
+        return webView
+    }
+
+    private func installA2UIHandlers() {
+        for name in CanvasA2UIActionMessageHandler.handlerNames {
+            self.userContentController.add(self.a2uiActionHandler, name: name)
+        }
+    }
+
+    private func removeA2UIHandlers() {
+        for name in CanvasA2UIActionMessageHandler.handlerNames {
+            self.userContentController.removeScriptMessageHandler(forName: name)
+        }
+    }
+}
+
+// MARK: - Navigation Delegate
+
+/// Handles navigation policy to intercept openclaw:// deep links from canvas
+@MainActor
+private final class ScreenNavigationDelegate: NSObject, WKNavigationDelegate {
+    weak var controller: ScreenController?
+
+    func webView(
+        _: WKWebView,
+        decidePolicyFor navigationAction: WKNavigationAction,
+        decisionHandler: @escaping @MainActor @Sendable (WKNavigationActionPolicy) -> Void)
+    {
+        guard let url = navigationAction.request.url else {
+            decisionHandler(.allow)
+            return
+        }
+
+        // Intercept openclaw:// deep links.
+        if url.scheme?.lowercased() == "openclaw" {
+            decisionHandler(.cancel)
+            self.controller?.onDeepLink?(url)
+            return
+        }
+
+        decisionHandler(.allow)
+    }
+
+    func webView(
+        _: WKWebView,
+        didFailProvisionalNavigation _: WKNavigation?,
+        withError error: any Error)
+    {
+        self.controller?.errorText = error.localizedDescription
+    }
+
+    func webView(_: WKWebView, didFinish _: WKNavigation?) {
+        self.controller?.errorText = nil
+        self.controller?.applyDebugStatusIfNeeded()
+        self.controller?.applyHomeCanvasStateIfNeeded()
+    }
+
+    func webView(_: WKWebView, didFail _: WKNavigation?, withError error: any Error) {
+        self.controller?.errorText = error.localizedDescription
+    }
+}
+
+private final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
+    static let messageName = "openclawCanvasA2UIAction"
+    static let handlerNames = [messageName]
+
+    weak var controller: ScreenController?
+
+    func userContentController(_: WKUserContentController, didReceive message: WKScriptMessage) {
+        guard Self.handlerNames.contains(message.name) else { return }
+        guard let controller else { return }
+
+        guard let url = message.webView?.url else { return }
+        guard controller.isTrustedCanvasUIURL(url) else { return }
+
+        guard let body = ScreenController.parseA2UIActionBody(message.body) else { return }
+
+        controller.onA2UIAction?(body)
+    }
+}
--- a/openclaw/apps/ios/Sources/Services/NodeServiceProtocols.swift
+++ b/openclaw/apps/ios/Sources/Services/NodeServiceProtocols.swift
@ -0,0 +1,133 @@
+import CoreLocation
+import Foundation
+import OpenClawKit
+import UIKit
+
+typealias OpenClawCameraSnapResult = (format: String, base64: String, width: Int, height: Int)
+typealias OpenClawCameraClipResult = (format: String, base64: String, durationMs: Int, hasAudio: Bool)
+
+protocol CameraServicing: Sendable {
+    func listDevices() async -> [CameraController.CameraDeviceInfo]
+    func snap(params: OpenClawCameraSnapParams) async throws -> OpenClawCameraSnapResult
+    func clip(params: OpenClawCameraClipParams) async throws -> OpenClawCameraClipResult
+}
+
+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
+    func startLocationUpdates(
+        desiredAccuracy: OpenClawLocationAccuracy,
+        significantChangesOnly: Bool) -> AsyncStream<CLLocation>
+    func stopLocationUpdates()
+    func startMonitoringSignificantLocationChanges(onUpdate: @escaping @Sendable (CLLocation) -> Void)
+    func stopMonitoringSignificantLocationChanges()
+}
+
+@MainActor
+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
+}
+
+struct WatchMessagingStatus: Sendable, Equatable {
+    var supported: Bool
+    var paired: Bool
+    var appInstalled: Bool
+    var reachable: Bool
+    var activationState: String
+}
+
+struct WatchQuickReplyEvent: Sendable, Equatable {
+    var replyId: String
+    var promptId: String
+    var actionId: String
+    var actionLabel: String?
+    var sessionKey: String?
+    var note: String?
+    var sentAtMs: Int?
+    var transport: String
+}
+
+struct WatchExecApprovalResolveEvent: Sendable, Equatable {
+    var replyId: String
+    var approvalId: String
+    var decision: OpenClawWatchExecApprovalDecision
+    var sentAtMs: Int?
+    var transport: String
+}
+
+struct WatchExecApprovalSnapshotRequestEvent: Sendable, Equatable {
+    var requestId: String
+    var sentAtMs: Int?
+    var transport: String
+}
+
+struct WatchNotificationSendResult: Sendable, Equatable {
+    var deliveredImmediately: Bool
+    var queuedForDelivery: Bool
+    var transport: String
+}
+
+protocol WatchMessagingServicing: AnyObject, Sendable {
+    func status() async -> WatchMessagingStatus
+    func setStatusHandler(_ handler: (@Sendable (WatchMessagingStatus) -> Void)?)
+    func setReplyHandler(_ handler: (@Sendable (WatchQuickReplyEvent) -> Void)?)
+    func setExecApprovalResolveHandler(_ handler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?)
+    func setExecApprovalSnapshotRequestHandler(
+        _ handler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?)
+    func sendNotification(
+        id: String,
+        params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult
+    func sendExecApprovalPrompt(
+        _ message: OpenClawWatchExecApprovalPromptMessage) async throws -> WatchNotificationSendResult
+    func sendExecApprovalResolved(
+        _ message: OpenClawWatchExecApprovalResolvedMessage) async throws -> WatchNotificationSendResult
+    func sendExecApprovalExpired(
+        _ message: OpenClawWatchExecApprovalExpiredMessage) async throws -> WatchNotificationSendResult
+    func syncExecApprovalSnapshot(
+        _ message: OpenClawWatchExecApprovalSnapshotMessage) async throws -> WatchNotificationSendResult
+}
+
+extension CameraController: CameraServicing {}
+extension ScreenRecordService: ScreenRecordingServicing {}
+extension LocationService: LocationServicing {}
--- a/openclaw/apps/ios/Sources/Services/NotificationService.swift
+++ b/openclaw/apps/ios/Sources/Services/NotificationService.swift
@ -0,0 +1,89 @@
+import Foundation
+import UserNotifications
+
+struct NotificationSnapshot: @unchecked Sendable {
+    let identifier: String
+    let userInfo: [AnyHashable: Any]
+}
+
+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
+    func removePendingNotificationRequests(withIdentifiers identifiers: [String]) async
+    func removeDeliveredNotifications(withIdentifiers identifiers: [String]) async
+    func deliveredNotifications() async -> [NotificationSnapshot]
+}
+
+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: ())
+                }
+            }
+        }
+    }
+
+    func removePendingNotificationRequests(withIdentifiers identifiers: [String]) async {
+        guard !identifiers.isEmpty else { return }
+        self.center.removePendingNotificationRequests(withIdentifiers: identifiers)
+    }
+
+    func removeDeliveredNotifications(withIdentifiers identifiers: [String]) async {
+        guard !identifiers.isEmpty else { return }
+        self.center.removeDeliveredNotifications(withIdentifiers: identifiers)
+    }
+
+    func deliveredNotifications() async -> [NotificationSnapshot] {
+        await withCheckedContinuation { continuation in
+            self.center.getDeliveredNotifications { notifications in
+                continuation.resume(
+                    returning: notifications.map { notification in
+                        NotificationSnapshot(
+                            identifier: notification.request.identifier,
+                            userInfo: notification.request.content.userInfo)
+                    })
+            }
+        }
+    }
+}
--- a/openclaw/apps/ios/Sources/Services/WatchConnectivityTransport.swift
+++ b/openclaw/apps/ios/Sources/Services/WatchConnectivityTransport.swift
@ -0,0 +1,366 @@
+import Foundation
+import OSLog
+@preconcurrency import WatchConnectivity
+
+private struct WatchConnectivityTransportCallbacks {
+    var statusUpdateHandler: (@Sendable (WatchMessagingStatus) -> Void)?
+    var replyHandler: (@Sendable (WatchQuickReplyEvent) -> Void)?
+    var execApprovalResolveHandler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?
+    var execApprovalSnapshotRequestHandler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?
+}
+
+private func sendReachableWatchMessage(_ payload: [String: Any], with session: WCSession) async throws {
+    // WatchConnectivity replies arrive on its own queue. Keep this continuation explicitly
+    // nonisolated so Swift 6 does not inherit a caller actor (for example MainActor) into the
+    // Objective-C callback boundary and trap on the reply callback executor check.
+    try await withCheckedThrowingContinuation(isolation: nil) { (continuation: CheckedContinuation<Void, Error>) in
+        session.sendMessage(
+            payload,
+            replyHandler: { _ in
+                continuation.resume(returning: ())
+            },
+            errorHandler: { error in
+                continuation.resume(throwing: error)
+            }
+        )
+    }
+}
+
+final class WatchConnectivityTransport: NSObject, @unchecked Sendable {
+    nonisolated private static let logger = Logger(subsystem: "ai.openclaw", category: "watch.messaging")
+
+    private let session: WCSession?
+    private let callbacksLock = NSLock()
+    private var callbacks = WatchConnectivityTransportCallbacks()
+
+    override init() {
+        if WCSession.isSupported() {
+            self.session = WCSession.default
+        } else {
+            self.session = nil
+        }
+        super.init()
+        if let session = self.session {
+            session.delegate = self
+            session.activate()
+        }
+    }
+
+    nonisolated static func isSupportedOnDevice() -> Bool {
+        WCSession.isSupported()
+    }
+
+    nonisolated static func currentStatusSnapshot() -> WatchMessagingStatus {
+        guard WCSession.isSupported() else {
+            return WatchMessagingStatus(
+                supported: false,
+                paired: false,
+                appInstalled: false,
+                reachable: false,
+                activationState: "unsupported")
+        }
+        return self.status(for: WCSession.default)
+    }
+
+    func status() async -> WatchMessagingStatus {
+        await self.ensureActivated()
+        return self.currentStatusSnapshot()
+    }
+
+    func currentStatusSnapshot() -> WatchMessagingStatus {
+        guard let session = self.session else {
+            return WatchMessagingStatus(
+                supported: false,
+                paired: false,
+                appInstalled: false,
+                reachable: false,
+                activationState: "unsupported")
+        }
+        return Self.status(for: session)
+    }
+
+    func setStatusUpdateHandler(_ handler: (@Sendable (WatchMessagingStatus) -> Void)?) {
+        self.updateCallbacks { $0.statusUpdateHandler = handler }
+    }
+
+    func setReplyHandler(_ handler: (@Sendable (WatchQuickReplyEvent) -> Void)?) {
+        self.updateCallbacks { $0.replyHandler = handler }
+    }
+
+    func setExecApprovalResolveHandler(_ handler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?) {
+        self.updateCallbacks { $0.execApprovalResolveHandler = handler }
+    }
+
+    func setExecApprovalSnapshotRequestHandler(
+        _ handler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?)
+    {
+        self.updateCallbacks { $0.execApprovalSnapshotRequestHandler = handler }
+    }
+
+    func sendPayload(_ payload: [String: Any]) async throws -> WatchNotificationSendResult {
+        await self.ensureActivated()
+        let session = try self.requireReadySession()
+        if session.isReachable {
+            do {
+                try await sendReachableWatchMessage(payload, with: session)
+                return WatchNotificationSendResult(
+                    deliveredImmediately: true,
+                    queuedForDelivery: false,
+                    transport: "sendMessage")
+            } catch {
+                Self.logger.error("watch sendMessage failed: \(error.localizedDescription, privacy: .public)")
+            }
+        }
+
+        _ = session.transferUserInfo(payload)
+        return WatchNotificationSendResult(
+            deliveredImmediately: false,
+            queuedForDelivery: true,
+            transport: "transferUserInfo")
+    }
+
+    func sendSnapshotPayload(_ payload: [String: Any]) async throws -> WatchNotificationSendResult {
+        await self.ensureActivated()
+        let session = try self.requireReadySession()
+        if session.isReachable {
+            do {
+                try await sendReachableWatchMessage(payload, with: session)
+                return WatchNotificationSendResult(
+                    deliveredImmediately: true,
+                    queuedForDelivery: false,
+                    transport: "sendMessage")
+            } catch {
+                Self.logger.error(
+                    "watch snapshot sendMessage failed: \(error.localizedDescription, privacy: .public)")
+            }
+        }
+
+        do {
+            try session.updateApplicationContext(payload)
+            return WatchNotificationSendResult(
+                deliveredImmediately: false,
+                queuedForDelivery: true,
+                transport: "applicationContext")
+        } catch {
+            Self.logger.error(
+                "watch updateApplicationContext failed: \(error.localizedDescription, privacy: .public)")
+            _ = session.transferUserInfo(payload)
+            return WatchNotificationSendResult(
+                deliveredImmediately: false,
+                queuedForDelivery: true,
+                transport: "transferUserInfo")
+        }
+    }
+
+    private func updateCallbacks(_ update: (inout WatchConnectivityTransportCallbacks) -> Void) {
+        self.callbacksLock.lock()
+        defer { self.callbacksLock.unlock() }
+        update(&self.callbacks)
+    }
+
+    private func callbacksSnapshot() -> WatchConnectivityTransportCallbacks {
+        self.callbacksLock.lock()
+        defer { self.callbacksLock.unlock() }
+        return self.callbacks
+    }
+
+    private func requireReadySession() throws -> WCSession {
+        guard let session = self.session else {
+            throw WatchMessagingError.unsupported
+        }
+        let snapshot = Self.status(for: session)
+        guard snapshot.paired else {
+            throw WatchMessagingError.notPaired
+        }
+        guard snapshot.appInstalled else {
+            throw WatchMessagingError.watchAppNotInstalled
+        }
+        return session
+    }
+
+    private func ensureActivated() async {
+        guard let session = self.session else { return }
+        if session.activationState == .activated {
+            return
+        }
+        session.activate()
+        for _ in 0..<8 {
+            if session.activationState == .activated {
+                return
+            }
+            try? await Task.sleep(nanoseconds: 100_000_000)
+        }
+    }
+
+    private func emitStatusUpdate(_ snapshot: WatchMessagingStatus) {
+        guard let handler = self.callbacksSnapshot().statusUpdateHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(snapshot)
+        }
+    }
+
+    private func emitReply(_ event: WatchQuickReplyEvent) {
+        guard let handler = self.callbacksSnapshot().replyHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(event)
+        }
+    }
+
+    private func emitExecApprovalResolve(_ event: WatchExecApprovalResolveEvent) {
+        guard let handler = self.callbacksSnapshot().execApprovalResolveHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(event)
+        }
+    }
+
+    private func emitExecApprovalSnapshotRequest(_ event: WatchExecApprovalSnapshotRequestEvent) {
+        guard let handler = self.callbacksSnapshot().execApprovalSnapshotRequestHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(event)
+        }
+    }
+
+    nonisolated private static func status(for session: WCSession) -> WatchMessagingStatus {
+        WatchMessagingStatus(
+            supported: true,
+            paired: session.isPaired,
+            appInstalled: session.isWatchAppInstalled,
+            reachable: session.isReachable,
+            activationState: self.activationStateLabel(session.activationState))
+    }
+
+    nonisolated private static func activationStateLabel(_ state: WCSessionActivationState) -> String {
+        switch state {
+        case .notActivated:
+            "notActivated"
+        case .inactive:
+            "inactive"
+        case .activated:
+            "activated"
+        @unknown default:
+            "unknown"
+        }
+    }
+}
+
+extension WatchConnectivityTransport: WCSessionDelegate {
+    func session(
+        _ session: WCSession,
+        activationDidCompleteWith activationState: WCSessionActivationState,
+        error: (any Error)?)
+    {
+        GatewayDiagnostics.log(
+            "watch messaging: activation complete "
+                + "state=\(Self.activationStateLabel(activationState)) "
+                + "error=\(error?.localizedDescription ?? "none")")
+        if let error {
+            Self.logger.error("watch activation failed: \(error.localizedDescription, privacy: .public)")
+        } else {
+            Self.logger.debug(
+                "watch activation state=\(Self.activationStateLabel(activationState), privacy: .public)")
+        }
+        self.emitStatusUpdate(Self.status(for: session))
+    }
+
+    func sessionDidBecomeInactive(_: WCSession) {}
+
+    func sessionDidDeactivate(_ session: WCSession) {
+        GatewayDiagnostics.log("watch messaging: session did deactivate; reactivating")
+        session.activate()
+        self.emitStatusUpdate(Self.status(for: session))
+    }
+
+    func session(_: WCSession, didReceiveMessage message: [String: Any]) {
+        let type = (message["type"] as? String) ?? "unknown"
+        GatewayDiagnostics.log("watch messaging: didReceiveMessage type=\(type)")
+        if let event = WatchMessagingPayloadCodec.parseQuickReplyPayload(message, transport: "sendMessage") {
+            self.emitReply(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalResolvePayload(
+            message,
+            transport: "sendMessage")
+        {
+            self.emitExecApprovalResolve(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalSnapshotRequestPayload(
+            message,
+            transport: "sendMessage")
+        {
+            self.emitExecApprovalSnapshotRequest(event)
+        }
+    }
+
+    func session(
+        _: WCSession,
+        didReceiveMessage message: [String: Any],
+        replyHandler: @escaping ([String: Any]) -> Void)
+    {
+        let type = (message["type"] as? String) ?? "unknown"
+        GatewayDiagnostics.log("watch messaging: didReceiveMessageWithReply type=\(type)")
+        if let event = WatchMessagingPayloadCodec.parseQuickReplyPayload(message, transport: "sendMessage") {
+            replyHandler(["ok": true])
+            self.emitReply(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalResolvePayload(
+            message,
+            transport: "sendMessage")
+        {
+            replyHandler(["ok": true])
+            self.emitExecApprovalResolve(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalSnapshotRequestPayload(
+            message,
+            transport: "sendMessage")
+        {
+            replyHandler(["ok": true])
+            self.emitExecApprovalSnapshotRequest(event)
+            return
+        }
+        replyHandler(["ok": false, "error": "unsupported_payload"])
+    }
+
+    func session(_: WCSession, didReceiveUserInfo userInfo: [String: Any]) {
+        let type = (userInfo["type"] as? String) ?? "unknown"
+        GatewayDiagnostics.log("watch messaging: didReceiveUserInfo type=\(type)")
+        if let event = WatchMessagingPayloadCodec.parseQuickReplyPayload(
+            userInfo,
+            transport: "transferUserInfo")
+        {
+            self.emitReply(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalResolvePayload(
+            userInfo,
+            transport: "transferUserInfo")
+        {
+            self.emitExecApprovalResolve(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseExecApprovalSnapshotRequestPayload(
+            userInfo,
+            transport: "transferUserInfo")
+        {
+            self.emitExecApprovalSnapshotRequest(event)
+        }
+    }
+
+    func sessionReachabilityDidChange(_ session: WCSession) {
+        GatewayDiagnostics.log(
+            "watch messaging: reachability changed "
+                + "reachable=\(session.isReachable) paired=\(session.isPaired) "
+                + "installed=\(session.isWatchAppInstalled)")
+        self.emitStatusUpdate(Self.status(for: session))
+    }
+}
--- a/openclaw/apps/ios/Sources/Services/WatchMessagingPayloadCodec.swift
+++ b/openclaw/apps/ios/Sources/Services/WatchMessagingPayloadCodec.swift
@ -0,0 +1,219 @@
+import Foundation
+import OpenClawKit
+
+enum WatchMessagingPayloadCodec {
+    static func nowMs() -> Int {
+        Int(Date().timeIntervalSince1970 * 1000)
+    }
+
+    static func nonEmpty(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    static func encodeNotificationPayload(
+        id: String,
+        params: OpenClawWatchNotifyParams) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.notify.rawValue,
+            "id": id,
+            "title": params.title,
+            "body": params.body,
+            "priority": params.priority?.rawValue ?? OpenClawNotificationPriority.active.rawValue,
+            "sentAtMs": nowMs(),
+        ]
+        if let promptId = nonEmpty(params.promptId) {
+            payload["promptId"] = promptId
+        }
+        if let sessionKey = nonEmpty(params.sessionKey) {
+            payload["sessionKey"] = sessionKey
+        }
+        if let kind = nonEmpty(params.kind) {
+            payload["kind"] = kind
+        }
+        if let details = nonEmpty(params.details) {
+            payload["details"] = details
+        }
+        if let expiresAtMs = params.expiresAtMs {
+            payload["expiresAtMs"] = expiresAtMs
+        }
+        if let risk = params.risk {
+            payload["risk"] = risk.rawValue
+        }
+        if let actions = params.actions, !actions.isEmpty {
+            payload["actions"] = actions.map { action in
+                var encoded: [String: Any] = [
+                    "id": action.id,
+                    "label": action.label,
+                ]
+                if let style = nonEmpty(action.style) {
+                    encoded["style"] = style
+                }
+                return encoded
+            }
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalItem(_ item: OpenClawWatchExecApprovalItem) -> [String: Any] {
+        var payload: [String: Any] = [
+            "id": item.id,
+            "commandText": item.commandText,
+            "allowedDecisions": item.allowedDecisions.map(\.rawValue),
+        ]
+        if let commandPreview = nonEmpty(item.commandPreview) {
+            payload["commandPreview"] = commandPreview
+        }
+        if let host = nonEmpty(item.host) {
+            payload["host"] = host
+        }
+        if let nodeId = nonEmpty(item.nodeId) {
+            payload["nodeId"] = nodeId
+        }
+        if let agentId = nonEmpty(item.agentId) {
+            payload["agentId"] = agentId
+        }
+        if let expiresAtMs = item.expiresAtMs {
+            payload["expiresAtMs"] = expiresAtMs
+        }
+        if let risk = item.risk {
+            payload["risk"] = risk.rawValue
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalPromptPayload(
+        _ message: OpenClawWatchExecApprovalPromptMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.execApprovalPrompt.rawValue,
+            "approval": encodeExecApprovalItem(message.approval),
+        ]
+        if let sentAtMs = message.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        if let deliveryId = nonEmpty(message.deliveryId) {
+            payload["deliveryId"] = deliveryId
+        }
+        if message.resetResolvingState == true {
+            payload["resetResolvingState"] = true
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalResolvedPayload(
+        _ message: OpenClawWatchExecApprovalResolvedMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.execApprovalResolved.rawValue,
+            "approvalId": message.approvalId,
+        ]
+        if let decision = message.decision {
+            payload["decision"] = decision.rawValue
+        }
+        if let resolvedAtMs = message.resolvedAtMs {
+            payload["resolvedAtMs"] = resolvedAtMs
+        }
+        if let source = nonEmpty(message.source) {
+            payload["source"] = source
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalExpiredPayload(
+        _ message: OpenClawWatchExecApprovalExpiredMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.execApprovalExpired.rawValue,
+            "approvalId": message.approvalId,
+            "reason": message.reason.rawValue,
+        ]
+        if let expiredAtMs = message.expiredAtMs {
+            payload["expiredAtMs"] = expiredAtMs
+        }
+        return payload
+    }
+
+    static func encodeExecApprovalSnapshotPayload(
+        _ message: OpenClawWatchExecApprovalSnapshotMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.execApprovalSnapshot.rawValue,
+            "approvals": message.approvals.map(encodeExecApprovalItem),
+        ]
+        if let sentAtMs = message.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        if let snapshotId = nonEmpty(message.snapshotId) {
+            payload["snapshotId"] = snapshotId
+        }
+        return payload
+    }
+
+    static func parseQuickReplyPayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchQuickReplyEvent?
+    {
+        guard (payload["type"] as? String) == OpenClawWatchPayloadType.reply.rawValue else {
+            return nil
+        }
+        guard let actionId = nonEmpty(payload["actionId"] as? String) else {
+            return nil
+        }
+        let promptId = nonEmpty(payload["promptId"] as? String) ?? "unknown"
+        let replyId = nonEmpty(payload["replyId"] as? String) ?? UUID().uuidString
+        let actionLabel = nonEmpty(payload["actionLabel"] as? String)
+        let sessionKey = nonEmpty(payload["sessionKey"] as? String)
+        let note = nonEmpty(payload["note"] as? String)
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+
+        return WatchQuickReplyEvent(
+            replyId: replyId,
+            promptId: promptId,
+            actionId: actionId,
+            actionLabel: actionLabel,
+            sessionKey: sessionKey,
+            note: note,
+            sentAtMs: sentAtMs,
+            transport: transport)
+    }
+
+    static func parseExecApprovalResolvePayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchExecApprovalResolveEvent?
+    {
+        guard (payload["type"] as? String) == OpenClawWatchPayloadType.execApprovalResolve.rawValue else {
+            return nil
+        }
+        guard let approvalId = nonEmpty(payload["approvalId"] as? String),
+              let rawDecision = nonEmpty(payload["decision"] as? String),
+              let decision = OpenClawWatchExecApprovalDecision(rawValue: rawDecision)
+        else {
+            return nil
+        }
+        let replyId = nonEmpty(payload["replyId"] as? String) ?? UUID().uuidString
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        return WatchExecApprovalResolveEvent(
+            replyId: replyId,
+            approvalId: approvalId,
+            decision: decision,
+            sentAtMs: sentAtMs,
+            transport: transport)
+    }
+
+    static func parseExecApprovalSnapshotRequestPayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchExecApprovalSnapshotRequestEvent?
+    {
+        guard (payload["type"] as? String) == OpenClawWatchPayloadType.execApprovalSnapshotRequest.rawValue else {
+            return nil
+        }
+        let requestId = nonEmpty(payload["requestId"] as? String) ?? UUID().uuidString
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        return WatchExecApprovalSnapshotRequestEvent(
+            requestId: requestId,
+            sentAtMs: sentAtMs,
+            transport: transport)
+    }
+}
--- a/Show more
+++ b/Show more
				`@ -0,0 +1 @@`
				{"images":[{"size":"60x60","expected-size":"180","filename":"180.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"3x"},{"size":"40x40","expected-size":"80","filename":"80.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"40x40","expected-size":"120","filename":"120.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"3x"},{"size":"60x60","expected-size":"120","filename":"120.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"57x57","expected-size":"57","filename":"57.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"1x"},{"size":"29x29","expected-size":"58","filename":"58.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"29x29","expected-size":"29","filename":"29.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"1x"},{"size":"29x29","expected-size":"87","filename":"87.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"3x"},{"size":"57x57","expected-size":"114","filename":"114.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"20x20","expected-size":"40","filename":"40.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"2x"},{"size":"20x20","expected-size":"60","filename":"60.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"iphone","scale":"3x"},{"size":"1024x1024","filename":"1024.png","expected-size":"1024","idiom":"ios-marketing","folder":"Assets.xcassets/AppIcon.appiconset/","scale":"1x"},{"idiom":"watch","filename":"172.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"38mm","scale":"2x","size":"86x86","expected-size":"172","role":"quickLook"},{"idiom":"watch","filename":"80.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"38mm","scale":"2x","size":"40x40","expected-size":"80","role":"appLauncher"},{"idiom":"watch","filename":"88.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"40mm","scale":"2x","size":"44x44","expected-size":"88","role":"appLauncher"},{"idiom":"watch","filename":"102.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"45mm","scale":"2x","size":"51x51","expected-size":"102","role":"appLauncher"},{"idiom":"watch","filename":"108.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"49mm","scale":"2x","size":"54x54","expected-size":"108","role":"appLauncher"},{"idiom":"watch","filename":"92.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"41mm","scale":"2x","size":"46x46","expected-size":"92","role":"appLauncher"},{"idiom":"watch","filename":"100.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"44mm","scale":"2x","size":"50x50","expected-size":"100","role":"appLauncher"},{"idiom":"watch","filename":"196.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"42mm","scale":"2x","size":"98x98","expected-size":"196","role":"quickLook"},{"idiom":"watch","filename":"216.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"44mm","scale":"2x","size":"108x108","expected-size":"216","role":"quickLook"},{"idiom":"watch","filename":"234.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"45mm","scale":"2x","size":"117x117","expected-size":"234","role":"quickLook"},{"idiom":"watch","filename":"258.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"49mm","scale":"2x","size":"129x129","expected-size":"258","role":"quickLook"},{"idiom":"watch","filename":"48.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"38mm","scale":"2x","size":"24x24","expected-size":"48","role":"notificationCenter"},{"idiom":"watch","filename":"55.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"42mm","scale":"2x","size":"27.5x27.5","expected-size":"55","role":"notificationCenter"},{"idiom":"watch","filename":"66.png","folder":"Assets.xcassets/AppIcon.appiconset/","subtype":"45mm","scale":"2x","size":"33x33","expected-size":"66","role":"notificationCenter"},{"size":"29x29","expected-size":"87","filename":"87.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"watch","role":"companionSettings","scale":"3x"},{"size":"29x29","expected-size":"58","filename":"58.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"watch","role":"companionSettings","scale":"2x"},{"size":"1024x1024","expected-size":"1024","filename":"1024.png","folder":"Assets.xcassets/AppIcon.appiconset/","idiom":"watch-marketing","scale":"1x"}]}