Include full contents of all nested repositories

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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"}]}

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)
+    }
+}

openclaw/apps/ios/Sources/Camera/CameraController.swift

@@ -0,0 +1,402 @@
+import AVFoundation
+import OpenClawKit
+import Foundation
+
+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 session = AVCaptureSession()
+        session.sessionPreset = .photo
+
+        guard let device = Self.pickCamera(facing: facing, deviceId: params.deviceId) else {
+            throw CameraError.cameraUnavailable
+        }
+
+        let input = try AVCaptureDeviceInput(device: device)
+        guard session.canAddInput(input) else {
+            throw CameraError.captureFailed("Failed to add camera input")
+        }
+        session.addInput(input)
+
+        let output = AVCapturePhotoOutput()
+        guard session.canAddOutput(output) else {
+            throw CameraError.captureFailed("Failed to add photo output")
+        }
+        session.addOutput(output)
+        output.maxPhotoQualityPrioritization = .quality
+
+        session.startRunning()
+        defer { session.stopRunning() }
+        await Self.warmUpCaptureSession()
+        await Self.sleepDelayMs(delayMs)
+
+        let settings: AVCapturePhotoSettings = {
+            if output.availablePhotoCodecTypes.contains(.jpeg) {
+                return AVCapturePhotoSettings(format: [AVVideoCodecKey: AVVideoCodecType.jpeg])
+            }
+            return AVCapturePhotoSettings()
+        }()
+        settings.photoQualityPrioritization = .quality
+
+        var delegate: PhotoCaptureDelegate?
+        let rawData: Data = try await withCheckedThrowingContinuation { cont in
+            let d = PhotoCaptureDelegate(cont)
+            delegate = d
+            output.capturePhoto(with: settings, delegate: d)
+        }
+        withExtendedLifetime(delegate) {}
+
+        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 session = AVCaptureSession()
+        session.sessionPreset = .high
+
+        guard let camera = Self.pickCamera(facing: facing, deviceId: params.deviceId) else {
+            throw CameraError.cameraUnavailable
+        }
+        let cameraInput = try AVCaptureDeviceInput(device: camera)
+        guard session.canAddInput(cameraInput) else {
+            throw CameraError.captureFailed("Failed to add camera input")
+        }
+        session.addInput(cameraInput)
+
+        if includeAudio {
+            guard let mic = AVCaptureDevice.default(for: .audio) else {
+                throw CameraError.microphoneUnavailable
+            }
+            let micInput = try AVCaptureDeviceInput(device: mic)
+            if session.canAddInput(micInput) {
+                session.addInput(micInput)
+            } else {
+                throw CameraError.captureFailed("Failed to add microphone input")
+            }
+        }
+
+        let output = AVCaptureMovieFileOutput()
+        guard session.canAddOutput(output) else {
+            throw CameraError.captureFailed("Failed to add movie output")
+        }
+        session.addOutput(output)
+        output.maxRecordedDuration = CMTime(value: Int64(durationMs), timescale: 1000)
+
+        session.startRunning()
+        defer { session.stopRunning() }
+        await Self.warmUpCaptureSession()
+
+        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)
+        }
+
+        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)
+
+        let data = 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 {
+        let status = AVCaptureDevice.authorizationStatus(for: mediaType)
+        switch status {
+        case .authorized:
+            return
+        case .notDetermined:
+            let ok = await withCheckedContinuation(isolation: nil) { cont in
+                AVCaptureDevice.requestAccess(for: mediaType) { granted in
+                    cont.resume(returning: granted)
+                }
+            }
+            if !ok {
+                throw CameraError.permissionDenied(kind: mediaType == .video ? "Camera" : "Microphone")
+            }
+        case .denied, .restricted:
+            throw CameraError.permissionDenied(kind: mediaType == .video ? "Camera" : "Microphone")
+        @unknown default:
+            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 positionLabel(_ position: AVCaptureDevice.Position) -> String {
+        switch position {
+        case .front: "front"
+        case .back: "back"
+        default: "unspecified"
+        }
+    }
+
+    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 warmUpCaptureSession() async {
+        // A short delay after `startRunning()` significantly reduces "blank first frame" captures on some devices.
+        try? await Task.sleep(nanoseconds: 150_000_000) // 150ms
+    }
+
+    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 var didResume = false
+
+    init(_ continuation: CheckedContinuation<Data, Error>) {
+        self.continuation = continuation
+    }
+
+    func photoOutput(
+        _ output: AVCapturePhotoOutput,
+        didFinishProcessingPhoto photo: AVCapturePhoto,
+        error: Error?
+    ) {
+        guard !self.didResume else { return }
+        self.didResume = true
+
+        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 }
+        guard !self.didResume else { return }
+        self.didResume = true
+        self.continuation.resume(throwing: error)
+    }
+}
+
+private final class MovieFileDelegate: NSObject, AVCaptureFileOutputRecordingDelegate {
+    private let continuation: CheckedContinuation<URL, Error>
+    private var didResume = false
+
+    init(_ continuation: CheckedContinuation<URL, Error>) {
+        self.continuation = continuation
+    }
+
+    func fileOutput(
+        _ output: AVCaptureFileOutput,
+        didFinishRecordingTo outputFileURL: URL,
+        from connections: [AVCaptureConnection],
+        error: Error?)
+    {
+        guard !self.didResume else { return }
+        self.didResume = true
+
+        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)
+    }
+}

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)
+    }
+}

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))"
+    }
+}

openclaw/apps/ios/Sources/Chat/IOSGatewayChatTransport.swift

@@ -0,0 +1,142 @@
+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 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()
+            }
+        }
+    }
+}

openclaw/apps/ios/Sources/Contacts/ContactsService.swift

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

openclaw/apps/ios/Sources/Device/DeviceInfoHelper.swift

@@ -0,0 +1,71 @@
+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.
+    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".
+    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
+    }
+
+    /// App marketing version only, e.g. "2026.2.0" or "dev".
+    static func appVersion() -> 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))"
+    }
+}

openclaw/apps/ios/Sources/Device/DeviceStatusService.swift

@@ -0,0 +1,82 @@
+import Foundation
+import OpenClawKit
+import UIKit
+
+final class DeviceStatusService: DeviceStatusServicing {
+    private let networkStatus: NetworkStatusService
+
+    init(networkStatus: NetworkStatusService = NetworkStatusService()) {
+        self.networkStatus = networkStatus
+    }
+
+    func status() async throws -> OpenClawDeviceStatusPayload {
+        let battery = self.batteryStatus()
+        let thermal = self.thermalStatus()
+        let storage = self.storageStatus()
+        let network = await self.networkStatus.currentStatus()
+        let uptime = ProcessInfo.processInfo.systemUptime
+
+        return OpenClawDeviceStatusPayload(
+            battery: battery,
+            thermal: thermal,
+            storage: storage,
+            network: network,
+            uptimeSeconds: uptime)
+    }
+
+    func info() -> OpenClawDeviceInfoPayload {
+        let device = UIDevice.current
+        let appVersion = 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
+    }
+}

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
+    }
+}

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
+    }
+}

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
+        }
+    }
+}
+

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())
+    }
+}

openclaw/apps/ios/Sources/Gateway/GatewayConnectConfig.swift

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

openclaw/apps/ios/Sources/Gateway/GatewayConnectionIssue.swift

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

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)
+    }
+}

openclaw/apps/ios/Sources/Gateway/GatewayDiscoveryModel.swift

@@ -0,0 +1,190 @@
+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 params = NWParameters.tcp
+            params.includePeerToPeer = true
+            let browser = NWBrowser(
+                for: .bonjour(type: OpenClawBonjour.gatewayServiceType, domain: domain),
+                using: params)
+
+            browser.stateUpdateHandler = { [weak self] state in
+                Task { @MainActor in
+                    guard let self else { return }
+                    self.statesByDomain[domain] = state
+                    self.updateStatusText()
+                    self.appendDebugLog("state[\(domain)]: \(Self.prettyState(state))")
+                }
+            }
+
+            browser.browseResultsChangedHandler = { [weak self] results, _ in
+                Task { @MainActor 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
+            browser.start(queue: DispatchQueue(label: "ai.openclaw.ios.gateway-discovery.\(domain)"))
+        }
+    }
+
+    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"
+    }
+}

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
+        }
+    }
+}

openclaw/apps/ios/Sources/Gateway/GatewayQuickSetupSheet.swift

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

openclaw/apps/ios/Sources/Gateway/GatewayServiceResolver.swift

@@ -0,0 +1,55 @@
+import Foundation
+
+// 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) {
+        self.service.schedule(in: .main, forMode: .common)
+        self.service.resolve(withTimeout: 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? {
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmed.isEmpty { return nil }
+        return trimmed.hasSuffix(".") ? String(trimmed.dropLast()) : trimmed
+    }
+}
+

openclaw/apps/ios/Sources/Gateway/GatewaySettingsStore.swift

@@ -0,0 +1,448 @@
+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 talkProviderApiKeyAccountPrefix = "provider.apiKey."
+
+    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 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 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 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 {
+        case manual
+        case discovered
+    }
+
+    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 defaults = UserDefaults.standard
+        defaults.set(LastGatewayKind.manual.rawValue, forKey: self.lastGatewayKindDefaultsKey)
+        defaults.set(host, forKey: self.lastGatewayHostDefaultsKey)
+        defaults.set(port, forKey: self.lastGatewayPortDefaultsKey)
+        defaults.set(useTLS, forKey: self.lastGatewayTlsDefaultsKey)
+        defaults.set(stableID, forKey: self.lastGatewayStableIDDefaultsKey)
+    }
+
+    static func saveLastGatewayConnectionDiscovered(stableID: String, useTLS: Bool) {
+        let defaults = UserDefaults.standard
+        defaults.set(LastGatewayKind.discovered.rawValue, forKey: self.lastGatewayKindDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayHostDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayPortDefaultsKey)
+        defaults.set(useTLS, forKey: self.lastGatewayTlsDefaultsKey)
+        defaults.set(stableID, forKey: self.lastGatewayStableIDDefaultsKey)
+    }
+
+    static func loadLastGatewayConnection() -> LastGatewayConnection? {
+        let defaults = UserDefaults.standard
+        let stableID = defaults.string(forKey: self.lastGatewayStableIDDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !stableID.isEmpty else { return nil }
+        let useTLS = defaults.bool(forKey: self.lastGatewayTlsDefaultsKey)
+        let kindRaw = defaults.string(forKey: self.lastGatewayKindDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let kind = LastGatewayKind(rawValue: kindRaw) ?? .manual
+
+        if kind == .discovered {
+            return .discovered(stableID: stableID, useTLS: useTLS)
+        }
+
+        let host = defaults.string(forKey: self.lastGatewayHostDefaultsKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let port = defaults.integer(forKey: self.lastGatewayPortDefaultsKey)
+
+        // Back-compat: older builds persisted manual-style host/port without a kind marker.
+        guard !host.isEmpty, port > 0, port <= 65535 else { return nil }
+        return .manual(host: host, port: port, useTLS: useTLS, stableID: stableID)
+    }
+
+    static func clearLastGatewayConnection(defaults: UserDefaults = .standard) {
+        defaults.removeObject(forKey: self.lastGatewayKindDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayHostDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayPortDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayTlsDefaultsKey)
+        defaults.removeObject(forKey: self.lastGatewayStableIDDefaultsKey)
+    }
+
+    static func deleteGatewayCredentials(instanceId: String) {
+        let trimmed = instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.gatewayTokenAccount(instanceId: trimmed))
+        _ = KeychainStore.delete(
+            service: self.gatewayService,
+            account: self.gatewayPasswordAccount(instanceId: trimmed))
+    }
+
+    static func loadGatewayClientIdOverride(stableID: String) -> String? {
+        let trimmedID = stableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedID.isEmpty else { return nil }
+        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 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
+    nonisolated(unsafe) private static var logWritesSinceCheck = 0
+    private static var fileURL: URL? {
+        FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first?
+            .appendingPathComponent("openclaw-gateway.log")
+    }
+
+    private static func truncateLogIfNeeded(url: URL) {
+        guard let attrs = try? FileManager.default.attributesOfItem(atPath: url.path),
+              let sizeNumber = attrs[.size] as? NSNumber
+        else { return }
+        let size = sizeNumber.int64Value
+        guard size > self.maxLogBytes else { return }
+
+        do {
+            let handle = try FileHandle(forReadingFrom: url)
+            defer { try? handle.close() }
+
+            let start = max(Int64(0), size - self.keepLogBytes)
+            try handle.seek(toOffset: UInt64(start))
+            var tail = try handle.readToEnd() ?? Data()
+
+            // If we truncated mid-line, drop the first partial line so logs remain readable.
+            if start > 0, let nl = tail.firstIndex(of: 10) {
+                let next = tail.index(after: nl)
+                if next < tail.endIndex {
+                    tail = tail.suffix(from: next)
+                } else {
+                    tail = Data()
+                }
+            }
+
+            try tail.write(to: url, options: .atomic)
+        } catch {
+            // Best-effort only.
+        }
+    }
+
+    private static func appendToLog(url: URL, data: Data) {
+        if FileManager.default.fileExists(atPath: url.path) {
+            if let handle = try? FileHandle(forWritingTo: url) {
+                defer { try? handle.close() }
+                _ = try? handle.seekToEnd()
+                try? handle.write(contentsOf: data)
+            }
+        } else {
+            try? data.write(to: url, options: .atomic)
+        }
+    }
+
+    static func bootstrap() {
+        guard let url = fileURL else { return }
+        queue.async {
+            self.truncateLogIfNeeded(url: url)
+            let formatter = ISO8601DateFormatter()
+            formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+            let timestamp = formatter.string(from: Date())
+            let line = "[\(timestamp)] gateway diagnostics started\n"
+            if let data = line.data(using: .utf8) {
+                self.appendToLog(url: url, data: data)
+            }
+        }
+    }
+
+    static func log(_ message: String) {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        let timestamp = formatter.string(from: Date())
+        let line = "[\(timestamp)] \(message)"
+        logger.info("\(line, privacy: .public)")
+
+        guard let url = fileURL else { return }
+        queue.async {
+            self.logWritesSinceCheck += 1
+            if self.logWritesSinceCheck >= self.logSizeCheckEveryWrites {
+                self.logWritesSinceCheck = 0
+                self.truncateLogIfNeeded(url: url)
+            }
+            let entry = line + "\n"
+            if let data = entry.data(using: .utf8) {
+                self.appendToLog(url: url, data: data)
+            }
+        }
+    }
+
+    static func reset() {
+        guard let url = fileURL else { return }
+        queue.async {
+            try? FileManager.default.removeItem(at: url)
+        }
+    }
+}

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 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)
+    }
+}
+

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())
+    }
+}

openclaw/apps/ios/Sources/Gateway/KeychainStore.swift

@@ -0,0 +1,48 @@
+import Foundation
+import Security
+
+enum KeychainStore {
+    static func loadString(service: String, account: String) -> String? {
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+            kSecReturnData as String: true,
+            kSecMatchLimit as String: kSecMatchLimitOne,
+        ]
+
+        var item: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &item)
+        guard status == errSecSuccess, let data = item as? Data else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+
+    static func saveString(_ value: String, service: String, account: String) -> Bool {
+        let data = Data(value.utf8)
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+        ]
+
+        let update: [String: Any] = [kSecValueData as String: data]
+        let status = SecItemUpdate(query as CFDictionary, update as CFDictionary)
+        if status == errSecSuccess { return true }
+        if status != errSecItemNotFound { return false }
+
+        var insert = query
+        insert[kSecValueData as String] = data
+        insert[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+        return SecItemAdd(insert as CFDictionary, nil) == errSecSuccess
+    }
+
+    static func delete(service: String, account: String) -> Bool {
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+        ]
+        let status = SecItemDelete(query as CFDictionary)
+        return status == errSecSuccess || status == errSecItemNotFound
+    }
+}

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) }
+        }
+    }
+}
+

openclaw/apps/ios/Sources/Info.plist

@@ -0,0 +1,88 @@
+<?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</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>2026.2.26</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>20260226</string>
+	<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>NSSpeechRecognitionUsageDescription</key>
+	<string>OpenClaw uses on-device speech recognition for voice wake.</string>
+	<key>UIApplicationSceneManifest</key>
+	<dict>
+		<key>UIApplicationSupportsMultipleScenes</key>
+		<false/>
+	</dict>
+	<key>UIBackgroundModes</key>
+	<array>
+		<string>audio</string>
+		<string>remote-notification</string>
+	</array>
+	<key>BGTaskSchedulerPermittedIdentifiers</key>
+	<array>
+		<string>ai.openclaw.ios.bgrefresh</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>

openclaw/apps/ios/Sources/Location/LocationService.swift

@@ -0,0 +1,202 @@
+import OpenClawKit
+import CoreLocation
+import Foundation
+
+@MainActor
+final class LocationService: NSObject, CLLocationManagerDelegate {
+    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
+
+    override init() {
+        super.init()
+        self.manager.delegate = self
+        self.manager.desiredAccuracy = kCLLocationAccuracyBest
+    }
+
+    func authorizationStatus() -> CLAuthorizationStatus {
+        self.manager.authorizationStatus
+    }
+
+    func accuracyAuthorization() -> CLAccuracyAuthorization {
+        if #available(iOS 14.0, *) {
+            return self.manager.accuracyAuthorization
+        }
+        return .fullAccuracy
+    }
+
+    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
+    {
+        let now = Date()
+        if let maxAgeMs,
+           let cached = self.manager.location,
+           now.timeIntervalSince(cached.timestamp) * 1000 <= Double(maxAgeMs)
+        {
+            return cached
+        }
+
+        self.manager.desiredAccuracy = Self.accuracyValue(desiredAccuracy)
+        let timeout = max(0, timeoutMs ?? 10000)
+        return try await self.withTimeout(timeoutMs: timeout) {
+            try await self.requestLocation()
+        }
+    }
+
+    private func requestLocation() async throws -> CLLocation {
+        try await withCheckedThrowingContinuation { cont in
+            self.locationContinuation = cont
+            self.manager.requestLocation()
+        }
+    }
+
+    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)
+    }
+
+    private static func accuracyValue(_ accuracy: OpenClawLocationAccuracy) -> CLLocationAccuracy {
+        switch accuracy {
+        case .coarse:
+            kCLLocationAccuracyKilometer
+        case .balanced:
+            kCLLocationAccuracyHundredMeters
+        case .precise:
+            kCLLocationAccuracyBest
+        }
+    }
+
+    func startLocationUpdates(
+        desiredAccuracy: OpenClawLocationAccuracy,
+        significantChangesOnly: Bool) -> AsyncStream<CLLocation>
+    {
+        self.stopLocationUpdates()
+
+        self.manager.desiredAccuracy = Self.accuracyValue(desiredAccuracy)
+        self.manager.pausesLocationUpdatesAutomatically = true
+        self.manager.allowsBackgroundLocationUpdates = true
+
+        self.isStreaming = true
+        if significantChangesOnly {
+            self.manager.startMonitoringSignificantLocationChanges()
+        } else {
+            self.manager.startUpdatingLocation()
+        }
+
+        return AsyncStream(bufferingPolicy: .bufferingNewest(1)) { continuation in
+            self.updatesContinuation = continuation
+            continuation.onTermination = { @Sendable _ in
+                Task { @MainActor in
+                    self.stopLocationUpdates()
+                }
+            }
+        }
+    }
+
+    func stopLocationUpdates() {
+        guard self.isStreaming else { return }
+        self.isStreaming = false
+        self.manager.stopUpdatingLocation()
+        self.manager.stopMonitoringSignificantLocationChanges()
+        self.updatesContinuation?.finish()
+        self.updatesContinuation = nil
+    }
+
+    func startMonitoringSignificantLocationChanges(onUpdate: @escaping @Sendable (CLLocation) -> Void) {
+        self.significantLocationCallback = onUpdate
+        guard !self.isMonitoringSignificantChanges else { return }
+        self.isMonitoringSignificantChanges = true
+        self.manager.startMonitoringSignificantLocationChanges()
+    }
+
+    func stopMonitoringSignificantLocationChanges() {
+        guard self.isMonitoringSignificantChanges else { return }
+        self.isMonitoringSignificantChanges = false
+        self.significantLocationCallback = nil
+        self.manager.stopMonitoringSignificantLocationChanges()
+    }
+
+    nonisolated func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
+        let status = manager.authorizationStatus
+        Task { @MainActor in
+            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)
+        }
+    }
+}

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)
+            }
+        }
+    }
+}

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))
+        }
+    }
+}

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

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

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
+    }
+}

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"
+        }
+    }
+}

openclaw/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift

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

openclaw/apps/ios/Sources/Onboarding/OnboardingStateStore.swift

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

openclaw/apps/ios/Sources/Onboarding/OnboardingWizardView.swift

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

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.")
+        }
+    }
+}

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>
+

openclaw/apps/ios/Sources/OpenClawApp.swift

@@ -0,0 +1,545 @@
+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?
+}
+
+@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] = []
+
+    weak var appModel: NodeAppModel? {
+        didSet {
+            guard let model = self.appModel 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)
+                    }
+                }
+            }
+        }
+    }
+
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+    ) -> Bool
+    {
+        self.registerBackgroundWakeRefreshTask()
+        UNUserNotificationCenter.current().delegate = self
+        application.registerForRemoteNotifications()
+        return true
+    }
+
+    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+        if let appModel = self.appModel {
+            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
+            guard let appModel = self.appModel else {
+                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) {
+        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.appModel 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 func routeWatchPromptAction(_ action: PendingWatchPromptAction) async {
+        guard let appModel = self.appModel 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")
+    }
+
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        willPresent notification: UNNotification,
+        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void)
+    {
+        let userInfo = notification.request.content.userInfo
+        if Self.isWatchPromptNotification(userInfo) {
+            completionHandler([.banner, .list, .sound])
+            return
+        }
+        completionHandler([])
+    }
+
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        didReceive response: UNNotificationResponse,
+        withCompletionHandler completionHandler: @escaping () -> Void)
+    {
+        guard let action = Self.parseWatchPromptAction(from: response) else {
+            completionHandler()
+            return
+        }
+        Task { @MainActor [weak self] in
+            guard let self else {
+                completionHandler()
+                return
+            }
+            await self.routeWatchPromptAction(action)
+            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)
+            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
+                if let error {
+                    continuation.resume(throwing: error)
+                } else {
+                    continuation.resume(returning: ())
+                }
+            }
+        }
+    }
+}
+
+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()
+        _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)
+            }
+        }
+    }
+}

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",
+        ])
+    }
+}

openclaw/apps/ios/Sources/RootCanvas.swift

@@ -0,0 +1,506 @@
+import SwiftUI
+import UIKit
+
+struct RootCanvas: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @Environment(GatewayConnectionController.self) private var gatewayController
+    @Environment(VoiceWakeManager.self) private var voiceWake
+    @Environment(\.colorScheme) private var systemColorScheme
+    @Environment(\.scenePhase) private var scenePhase
+    @AppStorage(VoiceWakePreferences.enabledKey) private var voiceWakeEnabled: Bool = false
+    @AppStorage("screen.preventSleep") private var preventSleep: Bool = true
+    @AppStorage("canvas.debugStatusEnabled") private var canvasDebugStatusEnabled: Bool = false
+    @AppStorage("onboarding.requestID") private var onboardingRequestID: Int = 0
+    @AppStorage("gateway.onboardingComplete") private var onboardingComplete: Bool = false
+    @AppStorage("gateway.hasConnectedOnce") private var hasConnectedOnce: Bool = false
+    @AppStorage("gateway.preferredStableID") private var preferredGatewayStableID: String = ""
+    @AppStorage("gateway.manual.enabled") private var manualGatewayEnabled: Bool = false
+    @AppStorage("gateway.manual.host") private var manualGatewayHost: String = ""
+    @AppStorage("onboarding.quickSetupDismissed") private var quickSetupDismissed: Bool = false
+    @State private var presentedSheet: PresentedSheet?
+    @State private var voiceWakeToastText: String?
+    @State private var toastDismissTask: Task<Void, Never>?
+    @State private var showOnboarding: Bool = false
+    @State private var onboardingAllowSkip: Bool = true
+    @State private var didEvaluateOnboarding: Bool = false
+    @State private var didAutoOpenSettings: Bool = false
+
+    private enum PresentedSheet: Identifiable {
+        case settings
+        case chat
+        case quickSetup
+
+        var id: Int {
+            switch self {
+            case .settings: 0
+            case .chat: 1
+            case .quickSetup: 2
+            }
+        }
+    }
+
+    enum StartupPresentationRoute: Equatable {
+        case none
+        case onboarding
+        case settings
+    }
+
+    static func startupPresentationRoute(
+        gatewayConnected: Bool,
+        hasConnectedOnce: Bool,
+        onboardingComplete: Bool,
+        hasExistingGatewayConfig: Bool,
+        shouldPresentOnLaunch: Bool) -> StartupPresentationRoute
+    {
+        if gatewayConnected {
+            return .none
+        }
+        // On first run or explicit launch onboarding state, onboarding always wins.
+        if shouldPresentOnLaunch || !hasConnectedOnce || !onboardingComplete {
+            return .onboarding
+        }
+        // Settings auto-open is a recovery path for previously-connected installs only.
+        if !hasExistingGatewayConfig {
+            return .settings
+        }
+        return .none
+    }
+
+    var body: some View {
+        ZStack {
+            CanvasContent(
+                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
+                })
+                .preferredColorScheme(.dark)
+
+            if self.appModel.cameraFlashNonce != 0 {
+                CameraFlashOverlay(nonce: self.appModel.cameraFlashNonce)
+            }
+        }
+        .gatewayTrustPromptAlert()
+        .deepLinkAgentPromptAlert()
+        .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.evaluateOnboardingPresentation(force: false) }
+        .onAppear { self.maybeAutoOpenSettings() }
+        .onChange(of: self.preventSleep) { _, _ in self.updateIdleTimer() }
+        .onChange(of: self.scenePhase) { _, _ in self.updateIdleTimer() }
+        .onAppear { self.maybeShowQuickSetup() }
+        .onChange(of: self.gatewayController.gateways.count) { _, _ in self.maybeShowQuickSetup() }
+        .onAppear { self.updateCanvasDebugStatus() }
+        .onChange(of: self.canvasDebugStatusEnabled) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayStatusText) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayServerName) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayServerName) { _, newValue in
+            if newValue != nil {
+                self.showOnboarding = false
+            }
+        }
+        .onChange(of: self.onboardingRequestID) { _, _ in
+            self.evaluateOnboardingPresentation(force: true)
+        }
+        .onChange(of: self.appModel.gatewayRemoteAddress) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayServerName) { _, newValue in
+            if newValue != nil {
+                self.onboardingComplete = true
+                self.hasConnectedOnce = true
+                OnboardingStateStore.markCompleted(mode: nil)
+            }
+            self.maybeAutoOpenSettings()
+        }
+        .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 {
+        if self.appModel.gatewayServerName != nil { return .connected }
+
+        let text = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        if text.localizedCaseInsensitiveContains("connecting") ||
+            text.localizedCaseInsensitiveContains("reconnecting")
+        {
+            return .connecting
+        }
+
+        if text.localizedCaseInsensitiveContains("error") {
+            return .error
+        }
+
+        return .disconnected
+    }
+
+    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.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        let subtitle = self.appModel.gatewayServerName ?? self.appModel.gatewayRemoteAddress
+        self.appModel.screen.updateDebugStatus(title: title, subtitle: subtitle)
+    }
+
+    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 GatewaySettingsStore.loadLastGatewayConnection() != nil { return true }
+        let manualHost = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        return self.manualGatewayEnabled && !manualHost.isEmpty
+    }
+
+    private func maybeAutoOpenSettings() {
+        guard !self.didAutoOpenSettings else { return }
+        guard !self.showOnboarding else { return }
+        let route = Self.startupPresentationRoute(
+            gatewayConnected: self.appModel.gatewayServerName != nil,
+            hasConnectedOnce: self.hasConnectedOnce,
+            onboardingComplete: self.onboardingComplete,
+            hasExistingGatewayConfig: self.hasExistingGatewayConfig(),
+            shouldPresentOnLaunch: false)
+        guard route == .settings else { return }
+        self.didAutoOpenSettings = true
+        self.presentedSheet = .settings
+    }
+
+    private func maybeShowQuickSetup() {
+        guard !self.quickSetupDismissed else { return }
+        guard !self.showOnboarding else { return }
+        guard self.presentedSheet == nil else { return }
+        guard self.appModel.gatewayServerName == nil else { return }
+        guard !self.gatewayController.gateways.isEmpty else { return }
+        self.presentedSheet = .quickSetup
+    }
+}
+
+private struct CanvasContent: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @AppStorage("talk.enabled") private var talkEnabled: Bool = false
+    @AppStorage("talk.button.enabled") private var talkButtonEnabled: Bool = true
+    @State private var showGatewayActions: Bool = false
+    var systemColorScheme: ColorScheme
+    var gatewayStatus: StatusPill.GatewayState
+    var voiceWakeEnabled: Bool
+    var voiceWakeToastText: String?
+    var cameraHUDText: String?
+    var cameraHUDKind: NodeAppModel.CameraHUDKind?
+    var openChat: () -> Void
+    var openSettings: () -> Void
+
+    private var brightenButtons: Bool { self.systemColorScheme == .light }
+
+    var body: some View {
+        ZStack(alignment: .topTrailing) {
+            ScreenTab()
+
+            VStack(spacing: 10) {
+                OverlayButton(systemImage: "text.bubble.fill", brighten: self.brightenButtons) {
+                    self.openChat()
+                }
+                .accessibilityLabel("Chat")
+
+                if self.talkButtonEnabled {
+                    // Talk mode lives on a side bubble so it doesn't get buried in settings.
+                    OverlayButton(
+                        systemImage: self.appModel.talkMode.isEnabled ? "waveform.circle.fill" : "waveform.circle",
+                        brighten: self.brightenButtons,
+                        tint: self.appModel.seamColor,
+                        isActive: self.appModel.talkMode.isEnabled)
+                    {
+                        let next = !self.appModel.talkMode.isEnabled
+                        self.talkEnabled = next
+                        self.appModel.setTalkEnabled(next)
+                    }
+                    .accessibilityLabel("Talk Mode")
+                }
+
+                OverlayButton(systemImage: "gearshape.fill", brighten: self.brightenButtons) {
+                    self.openSettings()
+                }
+                .accessibilityLabel("Settings")
+            }
+            .padding(.top, 10)
+            .padding(.trailing, 10)
+        }
+        .overlay(alignment: .center) {
+            if self.appModel.talkMode.isEnabled {
+                TalkOrbOverlay()
+                    .transition(.opacity)
+            }
+        }
+        .overlay(alignment: .topLeading) {
+            StatusPill(
+                gateway: self.gatewayStatus,
+                voiceWakeEnabled: self.voiceWakeEnabled,
+                activity: self.statusActivity,
+                brighten: self.brightenButtons,
+                onTap: {
+                    if self.gatewayStatus == .connected {
+                        self.showGatewayActions = true
+                    } else {
+                        self.openSettings()
+                    }
+                })
+                .padding(.leading, 10)
+                .safeAreaPadding(.top, 10)
+        }
+        .overlay(alignment: .topLeading) {
+            if let voiceWakeToastText, !voiceWakeToastText.isEmpty {
+                VoiceWakeToast(
+                    command: voiceWakeToastText,
+                    brighten: self.brightenButtons)
+                    .padding(.leading, 10)
+                    .safeAreaPadding(.top, 58)
+                    .transition(.move(edge: .top).combined(with: .opacity))
+            }
+        }
+        .confirmationDialog(
+            "Gateway",
+            isPresented: self.$showGatewayActions,
+            titleVisibility: .visible)
+        {
+            Button("Disconnect", role: .destructive) {
+                self.appModel.disconnectGateway()
+            }
+            Button("Open Settings") {
+                self.openSettings()
+            }
+            Button("Cancel", role: .cancel) {}
+        } message: {
+            Text("Disconnect from the gateway?")
+        }
+    }
+
+    private var statusActivity: StatusPill.Activity? {
+        // Status pill owns transient activity state so it doesn't overlap the connection indicator.
+        if self.appModel.isBackgrounded {
+            return StatusPill.Activity(
+                title: "Foreground required",
+                systemImage: "exclamationmark.triangle.fill",
+                tint: .orange)
+        }
+
+        let gatewayStatus = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        let gatewayLower = gatewayStatus.lowercased()
+        if gatewayLower.contains("repair") {
+            return StatusPill.Activity(title: "Repairing…", systemImage: "wrench.and.screwdriver", tint: .orange)
+        }
+        if gatewayLower.contains("approval") || gatewayLower.contains("pairing") {
+            return StatusPill.Activity(title: "Approval pending", systemImage: "person.crop.circle.badge.clock")
+        }
+        // Avoid duplicating the primary gateway status ("Connecting…") in the activity slot.
+
+        if self.appModel.screenRecordActive {
+            return StatusPill.Activity(title: "Recording screen…", systemImage: "record.circle.fill", tint: .red)
+        }
+
+        if let cameraHUDText, !cameraHUDText.isEmpty, let cameraHUDKind {
+            let systemImage: String
+            let tint: Color?
+            switch cameraHUDKind {
+            case .photo:
+                systemImage = "camera.fill"
+                tint = nil
+            case .recording:
+                systemImage = "video.fill"
+                tint = .red
+            case .success:
+                systemImage = "checkmark.circle.fill"
+                tint = .green
+            case .error:
+                systemImage = "exclamationmark.triangle.fill"
+                tint = .red
+            }
+            return StatusPill.Activity(title: cameraHUDText, systemImage: systemImage, tint: tint)
+        }
+
+        if self.voiceWakeEnabled {
+            let voiceStatus = self.appModel.voiceWake.statusText
+            if voiceStatus.localizedCaseInsensitiveContains("microphone permission") {
+                return StatusPill.Activity(title: "Mic permission", systemImage: "mic.slash", tint: .orange)
+            }
+            if voiceStatus == "Paused" {
+                // Talk mode intentionally pauses voice wake to release the mic. Don't spam the HUD for that case.
+                if self.appModel.talkMode.isEnabled {
+                    return nil
+                }
+                let suffix = self.appModel.isBackgrounded ? " (background)" : ""
+                return StatusPill.Activity(title: "Voice Wake paused\(suffix)", systemImage: "pause.circle.fill")
+            }
+        }
+
+        return nil
+    }
+}
+
+private struct OverlayButton: View {
+    let systemImage: String
+    let brighten: Bool
+    var tint: Color?
+    var isActive: Bool = false
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: self.action) {
+            Image(systemName: self.systemImage)
+                .font(.system(size: 16, weight: .semibold))
+                .foregroundStyle(self.isActive ? (self.tint ?? .primary) : .primary)
+                .padding(10)
+                .background {
+                    RoundedRectangle(cornerRadius: 12, style: .continuous)
+                        .fill(.ultraThinMaterial)
+                        .overlay {
+                            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                .fill(
+                                    LinearGradient(
+                                        colors: [
+                                            .white.opacity(self.brighten ? 0.26 : 0.18),
+                                            .white.opacity(self.brighten ? 0.08 : 0.04),
+                                            .clear,
+                                        ],
+                                        startPoint: .topLeading,
+                                        endPoint: .bottomTrailing))
+                                .blendMode(.overlay)
+                        }
+                        .overlay {
+                            if let tint {
+                                RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                    .fill(
+                                        LinearGradient(
+                                            colors: [
+                                                tint.opacity(self.isActive ? 0.22 : 0.14),
+                                                tint.opacity(self.isActive ? 0.10 : 0.06),
+                                                .clear,
+                                            ],
+                                            startPoint: .topLeading,
+                                            endPoint: .bottomTrailing))
+                                    .blendMode(.overlay)
+                            }
+                        }
+                        .overlay {
+                            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                .strokeBorder(
+                                    (self.tint ?? .white).opacity(self.isActive ? 0.34 : (self.brighten ? 0.24 : 0.18)),
+                                    lineWidth: self.isActive ? 0.7 : 0.5)
+                        }
+                        .shadow(color: .black.opacity(0.35), radius: 12, y: 6)
+                }
+        }
+        .buttonStyle(.plain)
+    }
+}
+
+private struct CameraFlashOverlay: View {
+    var nonce: Int
+
+    @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
+                    }
+                }
+            }
+    }
+}

openclaw/apps/ios/Sources/RootTabs.swift

@@ -0,0 +1,114 @@
+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
+
+    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 {
+                        self.selectedTab = 2
+                    }
+                })
+                .padding(.leading, 10)
+                .safeAreaPadding(.top, 10)
+        }
+        .overlay(alignment: .topLeading) {
+            if let voiceWakeToastText, !voiceWakeToastText.isEmpty {
+                VoiceWakeToast(command: voiceWakeToastText)
+                    .padding(.leading, 10)
+                    .safeAreaPadding(.top, 58)
+                    .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
+        }
+        .confirmationDialog(
+            "Gateway",
+            isPresented: self.$showGatewayActions,
+            titleVisibility: .visible)
+        {
+            Button("Disconnect", role: .destructive) {
+                self.appModel.disconnectGateway()
+            }
+            Button("Open Settings") {
+                self.selectedTab = 2
+            }
+            Button("Cancel", role: .cancel) {}
+        } message: {
+            Text("Disconnect from the gateway?")
+        }
+    }
+
+    private var gatewayStatus: StatusPill.GatewayState {
+        if self.appModel.gatewayServerName != nil { return .connected }
+
+        let text = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        if text.localizedCaseInsensitiveContains("connecting") ||
+            text.localizedCaseInsensitiveContains("reconnecting")
+        {
+            return .connecting
+        }
+
+        if text.localizedCaseInsensitiveContains("error") {
+            return .error
+        }
+
+        return .disconnected
+    }
+
+    private var statusActivity: StatusPill.Activity? {
+        StatusActivityBuilder.build(
+            appModel: self.appModel,
+            voiceWakeEnabled: self.voiceWakeEnabled,
+            cameraHUDText: self.appModel.cameraHUDText,
+            cameraHUDKind: self.appModel.cameraHUDKind)
+    }
+}

openclaw/apps/ios/Sources/RootView.swift

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

openclaw/apps/ios/Sources/Screen/ScreenController.swift

@@ -0,0 +1,373 @@
+import OpenClawKit
+import Observation
+import UIKit
+import WebKit
+
+@MainActor
+@Observable
+final class ScreenController {
+    private weak var activeWebView: WKWebView?
+
+    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?
+
+    init() {
+        self.reload()
+    }
+
+    func navigate(to urlString: String) {
+        let trimmed = urlString.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            self.urlString = ""
+            self.reload()
+            return
+        }
+        if let url = URL(string: trimmed),
+           !url.isFileURL,
+           let host = url.host,
+           Self.isLoopbackHost(host)
+        {
+            // Never try to load loopback URLs from a remote gateway.
+            self.showDefaultCanvas()
+            return
+        }
+        self.urlString = (trimmed == "/" ? "" : trimmed)
+        self.reload()
+    }
+
+    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.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 }
+        let enabled = self.debugStatusEnabled
+        let title = self.debugStatusTitle
+        let subtitle = self.debugStatusSubtitle
+        let js = """
+        (() => {
+          try {
+            const api = globalThis.__openclaw;
+            if (!api) return;
+            if (typeof api.setDebugStatusEnabled === 'function') {
+              api.setDebugStatusEnabled(\(enabled ? "true" : "false"));
+            }
+            if (!\(enabled ? "true" : "false")) return;
+            if (typeof api.setStatus === 'function') {
+              api.setStatus(\(Self.jsValue(title)), \(Self.jsValue(subtitle)));
+            }
+          } 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 withCheckedThrowingContinuation { cont in
+            webView.evaluateJavaScript(javaScript) { result, error in
+                if let error {
+                    cont.resume(throwing: error)
+                    return
+                }
+                if let result {
+                    cont.resume(returning: String(describing: result))
+                } else {
+                    cont.resume(returning: "")
+                }
+            }
+        }
+    }
+
+    func snapshotPNGBase64(maxWidth: CGFloat? = nil) async throws -> String {
+        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)
+            }
+        }
+        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 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)
+            }
+        }
+
+        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()
+    }
+
+    func attachWebView(_ webView: WKWebView) {
+        self.activeWebView = webView
+        self.reload()
+        self.applyDebugStatusIfNeeded()
+    }
+
+    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")
+
+    private static func isLoopbackHost(_ host: String) -> Bool {
+        let normalized = host.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if normalized.isEmpty { return true }
+        if normalized == "localhost" || normalized == "::1" || normalized == "0.0.0.0" {
+            return true
+        }
+        if normalized == "127.0.0.1" || normalized.hasPrefix("127.") {
+            return true
+        }
+        return false
+    }
+    func isTrustedCanvasUIURL(_ url: URL) -> Bool {
+        guard url.isFileURL else { return false }
+        let std = url.standardizedFileURL
+        if let expected = Self.canvasScaffoldURL,
+           std == expected.standardizedFileURL
+        {
+            return true
+        }
+        return false
+    }
+
+    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 jsValue(_ value: String?) -> String {
+        guard let value else { return "null" }
+        if let data = try? JSONSerialization.data(withJSONObject: [value]),
+           let encoded = String(data: data, encoding: .utf8),
+           encoded.count >= 2
+        {
+            return String(encoded.dropFirst().dropLast())
+        }
+        return "null"
+    }
+
+    func isLocalNetworkCanvasURL(_ url: URL) -> Bool {
+        guard let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" else {
+            return false
+        }
+        guard let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines), !host.isEmpty else {
+            return false
+        }
+        if host == "localhost" { return true }
+        if host.hasSuffix(".local") { return true }
+        if host.hasSuffix(".ts.net") { return true }
+        if host.hasSuffix(".tailscale.net") { return true }
+        // Allow MagicDNS / LAN hostnames like "peters-mac-studio-1".
+        if !host.contains("."), !host.contains(":") { return true }
+        if let ipv4 = Self.parseIPv4(host) {
+            return Self.isLocalNetworkIPv4(ipv4)
+        }
+        return false
+    }
+
+    private static func parseIPv4(_ host: String) -> (UInt8, UInt8, UInt8, UInt8)? {
+        let parts = host.split(separator: ".", omittingEmptySubsequences: false)
+        guard parts.count == 4 else { return nil }
+        let bytes: [UInt8] = parts.compactMap { UInt8($0) }
+        guard bytes.count == 4 else { return nil }
+        return (bytes[0], bytes[1], bytes[2], bytes[3])
+    }
+
+    private static func isLocalNetworkIPv4(_ ip: (UInt8, UInt8, UInt8, UInt8)) -> Bool {
+        let (a, b, _, _) = ip
+        // 10.0.0.0/8
+        if a == 10 { return true }
+        // 172.16.0.0/12
+        if a == 172, (16...31).contains(Int(b)) { return true }
+        // 192.168.0.0/16
+        if a == 192, b == 168 { return true }
+        // 127.0.0.0/8
+        if a == 127 { return true }
+        // 169.254.0.0/16 (link-local)
+        if a == 169, b == 254 { return true }
+        // Tailscale: 100.64.0.0/10
+        if a == 100, (64...127).contains(Int(b)) { return true }
+        return false
+    }
+
+    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
+    }
+}
+
+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
+    }
+}

openclaw/apps/ios/Sources/Screen/ScreenRecordService.swift

@@ -0,0 +1,360 @@
+import AVFoundation
+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 = Self.clampDurationMs(durationMs)
+        let fps = Self.clampFps(fps)
+        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()
+                }
+            }
+        }
+    }
+
+    private nonisolated static func clampDurationMs(_ ms: Int?) -> Int {
+        let v = ms ?? 10000
+        return min(60000, max(250, v))
+    }
+
+    private nonisolated static func clampFps(_ fps: Double?) -> Double {
+        let v = fps ?? 10
+        if !v.isFinite { return 10 }
+        return min(30, max(1, v))
+    }
+}
+
+@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 {
+        self.clampDurationMs(ms)
+    }
+
+    nonisolated static func _test_clampFps(_ fps: Double?) -> Double {
+        self.clampFps(fps)
+    }
+}
+#endif

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()
+                .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.
+}

openclaw/apps/ios/Sources/Screen/ScreenWebView.swift

@@ -0,0 +1,193 @@
+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()
+    }
+
+    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 }
+        if url.isFileURL {
+            guard controller.isTrustedCanvasUIURL(url) else { return }
+        } else {
+            // For security, only accept actions from local-network pages (e.g. the canvas host).
+            guard controller.isLocalNetworkCanvasURL(url) else { return }
+        }
+
+        guard let body = ScreenController.parseA2UIActionBody(message.body) else { return }
+
+        controller.onA2UIAction?(body)
+    }
+}

openclaw/apps/ios/Sources/Services/NodeServiceProtocols.swift

@@ -0,0 +1,106 @@
+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()
+}
+
+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 WatchNotificationSendResult: Sendable, Equatable {
+    var deliveredImmediately: Bool
+    var queuedForDelivery: Bool
+    var transport: String
+}
+
+protocol WatchMessagingServicing: AnyObject, Sendable {
+    func status() async -> WatchMessagingStatus
+    func setReplyHandler(_ handler: (@Sendable (WatchQuickReplyEvent) -> Void)?)
+    func sendNotification(
+        id: String,
+        params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult
+}
+
+extension CameraController: CameraServicing {}
+extension ScreenRecordService: ScreenRecordingServicing {}
+extension LocationService: LocationServicing {}

openclaw/apps/ios/Sources/Services/NotificationService.swift

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

openclaw/apps/ios/Sources/Services/WatchMessagingService.swift

@@ -0,0 +1,284 @@
+import Foundation
+import OpenClawKit
+import OSLog
+@preconcurrency import WatchConnectivity
+
+enum WatchMessagingError: LocalizedError {
+    case unsupported
+    case notPaired
+    case watchAppNotInstalled
+
+    var errorDescription: String? {
+        switch self {
+        case .unsupported:
+            "WATCH_UNAVAILABLE: WatchConnectivity is not supported on this device"
+        case .notPaired:
+            "WATCH_UNAVAILABLE: no paired Apple Watch"
+        case .watchAppNotInstalled:
+            "WATCH_UNAVAILABLE: OpenClaw watch companion app is not installed"
+        }
+    }
+}
+
+final class WatchMessagingService: NSObject, WatchMessagingServicing, @unchecked Sendable {
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "watch.messaging")
+    private let session: WCSession?
+    private let replyHandlerLock = NSLock()
+    private var replyHandler: (@Sendable (WatchQuickReplyEvent) -> Void)?
+
+    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()
+        }
+    }
+
+    static func isSupportedOnDevice() -> Bool {
+        WCSession.isSupported()
+    }
+
+    static func currentStatusSnapshot() -> WatchMessagingStatus {
+        guard WCSession.isSupported() else {
+            return WatchMessagingStatus(
+                supported: false,
+                paired: false,
+                appInstalled: false,
+                reachable: false,
+                activationState: "unsupported")
+        }
+        let session = WCSession.default
+        return status(for: session)
+    }
+
+    func status() async -> WatchMessagingStatus {
+        await self.ensureActivated()
+        guard let session = self.session else {
+            return WatchMessagingStatus(
+                supported: false,
+                paired: false,
+                appInstalled: false,
+                reachable: false,
+                activationState: "unsupported")
+        }
+        return Self.status(for: session)
+    }
+
+    func setReplyHandler(_ handler: (@Sendable (WatchQuickReplyEvent) -> Void)?) {
+        self.replyHandlerLock.lock()
+        self.replyHandler = handler
+        self.replyHandlerLock.unlock()
+    }
+
+    func sendNotification(
+        id: String,
+        params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult
+    {
+        await self.ensureActivated()
+        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 }
+
+        var payload: [String: Any] = [
+            "type": "watch.notify",
+            "id": id,
+            "title": params.title,
+            "body": params.body,
+            "priority": params.priority?.rawValue ?? OpenClawNotificationPriority.active.rawValue,
+            "sentAtMs": Int(Date().timeIntervalSince1970 * 1000),
+        ]
+        if let promptId = Self.nonEmpty(params.promptId) {
+            payload["promptId"] = promptId
+        }
+        if let sessionKey = Self.nonEmpty(params.sessionKey) {
+            payload["sessionKey"] = sessionKey
+        }
+        if let kind = Self.nonEmpty(params.kind) {
+            payload["kind"] = kind
+        }
+        if let details = Self.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 = Self.nonEmpty(action.style) {
+                    encoded["style"] = style
+                }
+                return encoded
+            }
+        }
+
+        if snapshot.reachable {
+            do {
+                try await self.sendReachableMessage(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")
+    }
+
+    private func sendReachableMessage(_ payload: [String: Any], with session: WCSession) async throws {
+        try await withCheckedThrowingContinuation { continuation in
+            session.sendMessage(
+                payload,
+                replyHandler: { _ in
+                    continuation.resume()
+                },
+                errorHandler: { error in
+                    continuation.resume(throwing: error)
+                }
+            )
+        }
+    }
+
+    private func emitReply(_ event: WatchQuickReplyEvent) {
+        let handler: ((WatchQuickReplyEvent) -> Void)?
+        self.replyHandlerLock.lock()
+        handler = self.replyHandler
+        self.replyHandlerLock.unlock()
+        handler?(event)
+    }
+
+    private static func nonEmpty(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func parseQuickReplyPayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchQuickReplyEvent?
+    {
+        guard (payload["type"] as? String) == "watch.reply" 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)
+    }
+
+    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 static func status(for session: WCSession) -> WatchMessagingStatus {
+        WatchMessagingStatus(
+            supported: true,
+            paired: session.isPaired,
+            appInstalled: session.isWatchAppInstalled,
+            reachable: session.isReachable,
+            activationState: activationStateLabel(session.activationState))
+    }
+
+    private static func activationStateLabel(_ state: WCSessionActivationState) -> String {
+        switch state {
+        case .notActivated:
+            "notActivated"
+        case .inactive:
+            "inactive"
+        case .activated:
+            "activated"
+        @unknown default:
+            "unknown"
+        }
+    }
+}
+
+extension WatchMessagingService: WCSessionDelegate {
+    func session(
+        _ session: WCSession,
+        activationDidCompleteWith activationState: WCSessionActivationState,
+        error: (any Error)?)
+    {
+        if let error {
+            Self.logger.error("watch activation failed: \(error.localizedDescription, privacy: .public)")
+            return
+        }
+        Self.logger.debug("watch activation state=\(Self.activationStateLabel(activationState), privacy: .public)")
+    }
+
+    func sessionDidBecomeInactive(_ session: WCSession) {}
+
+    func sessionDidDeactivate(_ session: WCSession) {
+        session.activate()
+    }
+
+    func session(_: WCSession, didReceiveMessage message: [String: Any]) {
+        guard let event = Self.parseQuickReplyPayload(message, transport: "sendMessage") else {
+            return
+        }
+        self.emitReply(event)
+    }
+
+    func session(
+        _: WCSession,
+        didReceiveMessage message: [String: Any],
+        replyHandler: @escaping ([String: Any]) -> Void)
+    {
+        guard let event = Self.parseQuickReplyPayload(message, transport: "sendMessage") else {
+            replyHandler(["ok": false, "error": "unsupported_payload"])
+            return
+        }
+        replyHandler(["ok": true])
+        self.emitReply(event)
+    }
+
+    func session(_: WCSession, didReceiveUserInfo userInfo: [String: Any]) {
+        guard let event = Self.parseQuickReplyPayload(userInfo, transport: "transferUserInfo") else {
+            return
+        }
+        self.emitReply(event)
+    }
+
+    func sessionReachabilityDidChange(_ session: WCSession) {}
+}

openclaw/apps/ios/Sources/SessionKey.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+enum SessionKey {
+    static func normalizeMainKey(_ raw: String?) -> String {
+        let trimmed = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? "main" : trimmed
+    }
+
+    static func makeAgentSessionKey(agentId: String, baseKey: String) -> String {
+        let trimmedAgent = agentId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedBase = baseKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmedAgent.isEmpty { return trimmedBase.isEmpty ? "main" : trimmedBase }
+        let normalizedBase = trimmedBase.isEmpty ? "main" : trimmedBase
+        return "agent:\(trimmedAgent):\(normalizedBase)"
+    }
+
+    static func isCanonicalMainSessionKey(_ value: String?) -> Bool {
+        let trimmed = (value ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return false }
+        if trimmed == "global" { return true }
+        return trimmed.hasPrefix("agent:")
+    }
+}

openclaw/apps/ios/Sources/Settings/SettingsNetworkingHelpers.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+struct SettingsHostPort: Equatable {
+    var host: String
+    var port: Int
+}
+
+enum SettingsNetworkingHelpers {
+    static func parseHostPort(from address: String) -> SettingsHostPort? {
+        let trimmed = address.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+
+        if trimmed.hasPrefix("["),
+           let close = trimmed.firstIndex(of: "]"),
+           close < trimmed.endIndex
+        {
+            let host = String(trimmed[trimmed.index(after: trimmed.startIndex)..<close])
+            let portStart = trimmed.index(after: close)
+            guard portStart < trimmed.endIndex, trimmed[portStart] == ":" else { return nil }
+            let portString = String(trimmed[trimmed.index(after: portStart)...])
+            guard let port = Int(portString) else { return nil }
+            return SettingsHostPort(host: host, port: port)
+        }
+
+        guard let colon = trimmed.lastIndex(of: ":") else { return nil }
+        let host = String(trimmed[..<colon])
+        let portString = String(trimmed[trimmed.index(after: colon)...])
+        guard !host.isEmpty, let port = Int(portString) else { return nil }
+        return SettingsHostPort(host: host, port: port)
+    }
+
+    static func httpURLString(host: String?, port: Int?, fallback: String) -> String {
+        if let host, let port {
+            let needsBrackets = host.contains(":") && !host.hasPrefix("[") && !host.hasSuffix("]")
+            let hostPart = needsBrackets ? "[\(host)]" : host
+            return "http://\(hostPart):\(port)"
+        }
+        return "http://\(fallback)"
+    }
+}

openclaw/apps/ios/Sources/Settings/VoiceWakeWordsSettingsView.swift

@@ -0,0 +1,98 @@
+import SwiftUI
+import Combine
+
+struct VoiceWakeWordsSettingsView: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @State private var triggerWords: [String] = VoiceWakePreferences.loadTriggerWords()
+    @FocusState private var focusedTriggerIndex: Int?
+    @State private var syncTask: Task<Void, Never>?
+
+    var body: some View {
+        Form {
+            Section {
+                ForEach(self.triggerWords.indices, id: \.self) { index in
+                    TextField("Wake word", text: self.binding(for: index))
+                        .textInputAutocapitalization(.never)
+                        .autocorrectionDisabled()
+                        .focused(self.$focusedTriggerIndex, equals: index)
+                        .onSubmit {
+                            self.commitTriggerWords()
+                        }
+                }
+                .onDelete(perform: self.removeWords)
+
+                Button {
+                    self.addWord()
+                } label: {
+                    Label("Add word", systemImage: "plus")
+                }
+                .disabled(self.triggerWords
+                    .contains(where: { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }))
+
+                Button("Reset defaults") {
+                    self.triggerWords = VoiceWakePreferences.defaultTriggerWords
+                }
+            } header: {
+                Text("Wake Words")
+            } footer: {
+                Text(
+                    "OpenClaw reacts when any trigger appears in a transcription. "
+                        + "Keep them short to avoid false positives.")
+            }
+        }
+        .navigationTitle("Wake Words")
+        .toolbar { EditButton() }
+        .onAppear {
+            if self.triggerWords.isEmpty {
+                self.triggerWords = VoiceWakePreferences.defaultTriggerWords
+                self.commitTriggerWords()
+            }
+        }
+        .onChange(of: self.focusedTriggerIndex) { oldValue, newValue in
+            guard oldValue != nil, oldValue != newValue else { return }
+            self.commitTriggerWords()
+        }
+        .onReceive(NotificationCenter.default.publisher(for: UserDefaults.didChangeNotification)) { _ in
+            guard self.focusedTriggerIndex == nil else { return }
+            let updated = VoiceWakePreferences.loadTriggerWords()
+            if updated != self.triggerWords {
+                self.triggerWords = updated
+            }
+        }
+    }
+
+    private func addWord() {
+        self.triggerWords.append("")
+    }
+
+    private func removeWords(at offsets: IndexSet) {
+        self.triggerWords.remove(atOffsets: offsets)
+        if self.triggerWords.isEmpty {
+            self.triggerWords = VoiceWakePreferences.defaultTriggerWords
+        }
+        self.commitTriggerWords()
+    }
+
+    private func binding(for index: Int) -> Binding<String> {
+        Binding(
+            get: {
+                guard self.triggerWords.indices.contains(index) else { return "" }
+                return self.triggerWords[index]
+            },
+            set: { newValue in
+                guard self.triggerWords.indices.contains(index) else { return }
+                self.triggerWords[index] = newValue
+            })
+    }
+
+    private func commitTriggerWords() {
+        VoiceWakePreferences.saveTriggerWords(self.triggerWords)
+
+        let snapshot = VoiceWakePreferences.sanitizeTriggerWords(self.triggerWords)
+        self.syncTask?.cancel()
+        self.syncTask = Task { [snapshot, weak appModel = self.appModel] in
+            try? await Task.sleep(nanoseconds: 650_000_000)
+            await appModel?.setGlobalWakeWords(snapshot)
+        }
+    }
+}

openclaw/apps/ios/Sources/Status/StatusActivityBuilder.swift

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

openclaw/apps/ios/Sources/Status/StatusPill.swift

@@ -0,0 +1,140 @@
+import SwiftUI
+
+struct StatusPill: View {
+    @Environment(\.scenePhase) private var scenePhase
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    enum GatewayState: Equatable {
+        case connected
+        case connecting
+        case error
+        case disconnected
+
+        var title: String {
+            switch self {
+            case .connected: "Connected"
+            case .connecting: "Connecting…"
+            case .error: "Error"
+            case .disconnected: "Offline"
+            }
+        }
+
+        var color: Color {
+            switch self {
+            case .connected: .green
+            case .connecting: .yellow
+            case .error: .red
+            case .disconnected: .gray
+            }
+        }
+    }
+
+    struct Activity: Equatable {
+        var title: String
+        var systemImage: String
+        var tint: Color?
+    }
+
+    var gateway: GatewayState
+    var voiceWakeEnabled: Bool
+    var activity: Activity?
+    var brighten: Bool = false
+    var onTap: () -> Void
+
+    @State private var pulse: Bool = false
+
+    var body: some View {
+        Button(action: self.onTap) {
+            HStack(spacing: 10) {
+                HStack(spacing: 8) {
+                    Circle()
+                        .fill(self.gateway.color)
+                        .frame(width: 9, height: 9)
+                        .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(.subheadline.weight(.semibold))
+                        .foregroundStyle(.primary)
+                }
+
+                Divider()
+                    .frame(height: 14)
+                    .opacity(0.35)
+
+                if let activity {
+                    HStack(spacing: 6) {
+                        Image(systemName: activity.systemImage)
+                            .font(.subheadline.weight(.semibold))
+                            .foregroundStyle(activity.tint ?? .primary)
+                        Text(activity.title)
+                            .font(.subheadline.weight(.semibold))
+                            .foregroundStyle(.primary)
+                            .lineLimit(1)
+                    }
+                    .transition(.opacity.combined(with: .move(edge: .top)))
+                } else {
+                    Image(systemName: self.voiceWakeEnabled ? "mic.fill" : "mic.slash")
+                        .font(.subheadline.weight(.semibold))
+                        .foregroundStyle(self.voiceWakeEnabled ? .primary : .secondary)
+                        .accessibilityLabel(self.voiceWakeEnabled ? "Voice Wake enabled" : "Voice Wake disabled")
+                        .transition(.opacity.combined(with: .move(edge: .top)))
+                }
+            }
+            .padding(.vertical, 8)
+            .padding(.horizontal, 12)
+            .background {
+                RoundedRectangle(cornerRadius: 14, style: .continuous)
+                    .fill(.ultraThinMaterial)
+                    .overlay {
+                        RoundedRectangle(cornerRadius: 14, style: .continuous)
+                            .strokeBorder(
+                                .white.opacity(self.contrast == .increased ? 0.5 : (self.brighten ? 0.24 : 0.18)),
+                                lineWidth: self.contrast == .increased ? 1.0 : 0.5
+                            )
+                    }
+                    .shadow(color: .black.opacity(0.25), radius: 12, y: 6)
+            }
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel("Connection Status")
+        .accessibilityValue(self.accessibilityValue)
+        .accessibilityHint("Double tap to open settings")
+        .onAppear { self.updatePulse(for: self.gateway, scenePhase: self.scenePhase, reduceMotion: self.reduceMotion) }
+        .onDisappear { self.pulse = false }
+        .onChange(of: self.gateway) { _, newValue in
+            self.updatePulse(for: newValue, scenePhase: self.scenePhase, 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: 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
+        }
+    }
+}

openclaw/apps/ios/Sources/Status/VoiceWakeToast.swift

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

openclaw/apps/ios/Sources/Voice/TalkOrbOverlay.swift

@@ -0,0 +1,87 @@
+import SwiftUI
+
+struct TalkOrbOverlay: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @State private var pulse: Bool = false
+
+    var body: some View {
+        let seam = self.appModel.seamColor
+        let status = self.appModel.talkMode.statusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        let mic = min(max(self.appModel.talkMode.micLevel, 0), 1)
+
+        VStack(spacing: 14) {
+            ZStack {
+                Circle()
+                    .stroke(seam.opacity(0.26), lineWidth: 2)
+                    .frame(width: 320, height: 320)
+                    .scaleEffect(self.pulse ? 1.15 : 0.96)
+                    .opacity(self.pulse ? 0.0 : 1.0)
+                    .animation(.easeOut(duration: 1.3).repeatForever(autoreverses: false), value: self.pulse)
+
+                Circle()
+                    .stroke(seam.opacity(0.18), lineWidth: 2)
+                    .frame(width: 320, height: 320)
+                    .scaleEffect(self.pulse ? 1.45 : 1.02)
+                    .opacity(self.pulse ? 0.0 : 0.9)
+                    .animation(.easeOut(duration: 1.9).repeatForever(autoreverses: false).delay(0.2), value: self.pulse)
+
+                Circle()
+                    .fill(
+                        RadialGradient(
+                            colors: [
+                                seam.opacity(0.75 + (0.20 * mic)),
+                                seam.opacity(0.40),
+                                Color.black.opacity(0.55),
+                            ],
+                            center: .center,
+                            startRadius: 1,
+                            endRadius: 112))
+                    .frame(width: 190, height: 190)
+                    .scaleEffect(1.0 + (0.12 * mic))
+                    .overlay(
+                        Circle()
+                            .stroke(seam.opacity(0.35), lineWidth: 1))
+                    .shadow(color: seam.opacity(0.32), radius: 26, x: 0, y: 0)
+                    .shadow(color: Color.black.opacity(0.50), radius: 22, x: 0, y: 10)
+            }
+            .contentShape(Circle())
+            .onTapGesture {
+                self.appModel.talkMode.userTappedOrb()
+            }
+
+            let agentName = self.appModel.activeAgentName.trimmingCharacters(in: .whitespacesAndNewlines)
+            if !agentName.isEmpty {
+                Text("Bot: \(agentName)")
+                    .font(.system(.caption, design: .rounded).weight(.semibold))
+                    .foregroundStyle(Color.white.opacity(0.70))
+            }
+
+            if !status.isEmpty, status != "Off" {
+                Text(status)
+                    .font(.system(.footnote, design: .rounded).weight(.semibold))
+                    .foregroundStyle(Color.white.opacity(0.92))
+                    .padding(.horizontal, 12)
+                    .padding(.vertical, 8)
+                    .background(
+                        Capsule()
+                            .fill(Color.black.opacity(0.40))
+                            .overlay(
+                                Capsule().stroke(seam.opacity(0.22), lineWidth: 1)))
+            }
+
+            if self.appModel.talkMode.isListening {
+                Capsule()
+                    .fill(seam.opacity(0.90))
+                    .frame(width: max(18, 180 * mic), height: 6)
+                    .animation(.easeOut(duration: 0.12), value: mic)
+                    .accessibilityLabel("Microphone level")
+            }
+        }
+        .padding(28)
+        .onAppear {
+            self.pulse = true
+        }
+        .accessibilityElement(children: .combine)
+        .accessibilityLabel("Talk Mode \(status)")
+    }
+}

openclaw/apps/ios/Sources/Voice/VoiceTab.swift

@@ -0,0 +1,46 @@
+import SwiftUI
+
+struct VoiceTab: View {
+    @Environment(NodeAppModel.self) private var appModel
+    @Environment(VoiceWakeManager.self) private var voiceWake
+    @AppStorage("voiceWake.enabled") private var voiceWakeEnabled: Bool = false
+    @AppStorage("talk.enabled") private var talkEnabled: Bool = false
+
+    var body: some View {
+        NavigationStack {
+            List {
+                Section("Status") {
+                    LabeledContent("Voice Wake", value: self.voiceWakeEnabled ? "Enabled" : "Disabled")
+                    LabeledContent("Listener", value: self.voiceWake.isListening ? "Listening" : "Idle")
+                    Text(self.voiceWake.statusText)
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                    LabeledContent("Talk Mode", value: self.talkEnabled ? "Enabled" : "Disabled")
+                }
+
+                Section("Notes") {
+                    let triggers = self.voiceWake.activeTriggerWords
+                    Group {
+                        if triggers.isEmpty {
+                            Text("Add wake words in Settings.")
+                        } else if triggers.count == 1 {
+                            Text("Say “\(triggers[0]) …” to trigger.")
+                        } else if triggers.count == 2 {
+                            Text("Say “\(triggers[0]) …” or “\(triggers[1]) …” to trigger.")
+                        } else {
+                            Text("Say “\(triggers.joined(separator: " …”, “")) …” to trigger.")
+                        }
+                    }
+                    .foregroundStyle(.secondary)
+                }
+            }
+            .navigationTitle("Voice")
+            .onChange(of: self.voiceWakeEnabled) { _, newValue in
+                self.appModel.setVoiceWakeEnabled(newValue)
+            }
+            .onChange(of: self.talkEnabled) { _, newValue in
+                self.appModel.setTalkEnabled(newValue)
+            }
+        }
+    }
+}

openclaw/apps/ios/Sources/Voice/VoiceWakeManager.swift

@@ -0,0 +1,495 @@
+import AVFAudio
+import Foundation
+import Observation
+import OpenClawKit
+import Speech
+import SwabbleKit
+
+private func makeAudioTapEnqueueCallback(queue: AudioBufferQueue) -> @Sendable (AVAudioPCMBuffer, AVAudioTime) -> Void {
+    { buffer, _ in
+        // This callback is invoked on a realtime audio thread/queue. Keep it tiny and nonisolated.
+        queue.enqueueCopy(of: buffer)
+    }
+}
+
+private final class AudioBufferQueue: @unchecked Sendable {
+    private let lock = NSLock()
+    private var buffers: [AVAudioPCMBuffer] = []
+
+    func enqueueCopy(of buffer: AVAudioPCMBuffer) {
+        guard let copy = buffer.deepCopy() else { return }
+        self.lock.lock()
+        self.buffers.append(copy)
+        self.lock.unlock()
+    }
+
+    func drain() -> [AVAudioPCMBuffer] {
+        self.lock.lock()
+        let drained = self.buffers
+        self.buffers.removeAll(keepingCapacity: true)
+        self.lock.unlock()
+        return drained
+    }
+
+    func clear() {
+        self.lock.lock()
+        self.buffers.removeAll(keepingCapacity: false)
+        self.lock.unlock()
+    }
+}
+
+extension AVAudioPCMBuffer {
+    fileprivate func deepCopy() -> AVAudioPCMBuffer? {
+        let format = self.format
+        let frameLength = self.frameLength
+        guard let copy = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: frameLength) else {
+            return nil
+        }
+        copy.frameLength = frameLength
+
+        if let src = self.floatChannelData, let dst = copy.floatChannelData {
+            let channels = Int(format.channelCount)
+            let frames = Int(frameLength)
+            for ch in 0..<channels {
+                dst[ch].update(from: src[ch], count: frames)
+            }
+            return copy
+        }
+
+        if let src = self.int16ChannelData, let dst = copy.int16ChannelData {
+            let channels = Int(format.channelCount)
+            let frames = Int(frameLength)
+            for ch in 0..<channels {
+                dst[ch].update(from: src[ch], count: frames)
+            }
+            return copy
+        }
+
+        if let src = self.int32ChannelData, let dst = copy.int32ChannelData {
+            let channels = Int(format.channelCount)
+            let frames = Int(frameLength)
+            for ch in 0..<channels {
+                dst[ch].update(from: src[ch], count: frames)
+            }
+            return copy
+        }
+
+        return nil
+    }
+}
+
+@MainActor
+@Observable
+final class VoiceWakeManager: NSObject {
+    var isEnabled: Bool = false
+    var isListening: Bool = false
+    var statusText: String = "Off"
+    var triggerWords: [String] = VoiceWakePreferences.loadTriggerWords()
+    var lastTriggeredCommand: String?
+
+    private let audioEngine = AVAudioEngine()
+    private var speechRecognizer: SFSpeechRecognizer?
+    private var recognitionRequest: SFSpeechAudioBufferRecognitionRequest?
+    private var recognitionTask: SFSpeechRecognitionTask?
+    private var tapQueue: AudioBufferQueue?
+    private var tapDrainTask: Task<Void, Never>?
+
+    private var lastDispatched: String?
+    private var onCommand: (@Sendable (String) async -> Void)?
+    private var userDefaultsObserver: NSObjectProtocol?
+    private var suppressedByTalk: Bool = false
+
+    override init() {
+        super.init()
+        self.triggerWords = VoiceWakePreferences.loadTriggerWords()
+        self.userDefaultsObserver = NotificationCenter.default.addObserver(
+            forName: UserDefaults.didChangeNotification,
+            object: UserDefaults.standard,
+            queue: .main,
+            using: { [weak self] _ in
+                Task { @MainActor in
+                    self?.handleUserDefaultsDidChange()
+                }
+            })
+    }
+
+    @MainActor deinit {
+        if let userDefaultsObserver = self.userDefaultsObserver {
+            NotificationCenter.default.removeObserver(userDefaultsObserver)
+        }
+    }
+
+    var activeTriggerWords: [String] {
+        VoiceWakePreferences.sanitizeTriggerWords(self.triggerWords)
+    }
+
+    private func handleUserDefaultsDidChange() {
+        let updated = VoiceWakePreferences.loadTriggerWords()
+        if updated != self.triggerWords {
+            self.triggerWords = updated
+        }
+    }
+
+    func configure(onCommand: @escaping @Sendable (String) async -> Void) {
+        self.onCommand = onCommand
+    }
+
+    func setEnabled(_ enabled: Bool) {
+        self.isEnabled = enabled
+        if enabled {
+            Task { await self.start() }
+        } else {
+            self.stop()
+        }
+    }
+
+    func setSuppressedByTalk(_ suppressed: Bool) {
+        self.suppressedByTalk = suppressed
+        if suppressed {
+            _ = self.suspendForExternalAudioCapture()
+            if self.isEnabled {
+                self.statusText = "Paused"
+            }
+        } else {
+            if self.isEnabled {
+                Task { await self.start() }
+            }
+        }
+    }
+
+    func start() async {
+        guard self.isEnabled else { return }
+        if self.isListening { return }
+        guard !self.suppressedByTalk else {
+            self.isListening = false
+            self.statusText = "Paused"
+            return
+        }
+
+        if ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"] != nil ||
+            ProcessInfo.processInfo.environment["SIMULATOR_UDID"] != nil
+        {
+            // The iOS Simulator’s audio stack is unreliable for long-running microphone capture.
+            // (We’ve observed CoreAudio deadlocks after TCC permission prompts.)
+            self.isListening = false
+            self.statusText = "Voice Wake isn’t supported on Simulator"
+            return
+        }
+
+        self.statusText = "Requesting permissions…"
+
+        let micOk = await Self.requestMicrophonePermission()
+        guard micOk else {
+            self.statusText = Self.permissionMessage(
+                kind: "Microphone",
+                status: AVAudioSession.sharedInstance().recordPermission)
+            self.isListening = false
+            return
+        }
+
+        let speechOk = await Self.requestSpeechPermission()
+        guard speechOk else {
+            self.statusText = Self.permissionMessage(
+                kind: "Speech recognition",
+                status: SFSpeechRecognizer.authorizationStatus())
+            self.isListening = false
+            return
+        }
+
+        self.speechRecognizer = SFSpeechRecognizer()
+        guard self.speechRecognizer != nil else {
+            self.statusText = "Speech recognizer unavailable"
+            self.isListening = false
+            return
+        }
+
+        do {
+            try Self.configureAudioSession()
+            try self.startRecognition()
+            self.isListening = true
+            self.statusText = "Listening"
+        } catch {
+            self.isListening = false
+            self.statusText = "Start failed: \(error.localizedDescription)"
+        }
+    }
+
+    func stop() {
+        self.isEnabled = false
+        self.isListening = false
+        self.statusText = "Off"
+
+        self.tapDrainTask?.cancel()
+        self.tapDrainTask = nil
+        self.tapQueue?.clear()
+        self.tapQueue = nil
+
+        self.recognitionTask?.cancel()
+        self.recognitionTask = nil
+        self.recognitionRequest = nil
+
+        if self.audioEngine.isRunning {
+            self.audioEngine.stop()
+            self.audioEngine.inputNode.removeTap(onBus: 0)
+        }
+
+        try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+    }
+
+    /// Temporarily releases the microphone so other subsystems (e.g. camera video capture) can record audio.
+    /// Returns `true` when listening was active and was suspended.
+    func suspendForExternalAudioCapture() -> Bool {
+        guard self.isEnabled, self.isListening else { return false }
+
+        self.isListening = false
+        self.statusText = "Paused"
+
+        self.tapDrainTask?.cancel()
+        self.tapDrainTask = nil
+        self.tapQueue?.clear()
+        self.tapQueue = nil
+
+        self.recognitionTask?.cancel()
+        self.recognitionTask = nil
+        self.recognitionRequest = nil
+
+        if self.audioEngine.isRunning {
+            self.audioEngine.stop()
+            self.audioEngine.inputNode.removeTap(onBus: 0)
+        }
+
+        try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+        return true
+    }
+
+    func resumeAfterExternalAudioCapture(wasSuspended: Bool) {
+        guard wasSuspended else { return }
+        Task { await self.start() }
+    }
+
+    private func startRecognition() throws {
+        self.recognitionTask?.cancel()
+        self.recognitionTask = nil
+        self.tapDrainTask?.cancel()
+        self.tapDrainTask = nil
+        self.tapQueue?.clear()
+        self.tapQueue = nil
+
+        let request = SFSpeechAudioBufferRecognitionRequest()
+        request.shouldReportPartialResults = true
+        self.recognitionRequest = request
+
+        let inputNode = self.audioEngine.inputNode
+        inputNode.removeTap(onBus: 0)
+
+        let recordingFormat = inputNode.outputFormat(forBus: 0)
+
+        let queue = AudioBufferQueue()
+        self.tapQueue = queue
+        let tapBlock: @Sendable (AVAudioPCMBuffer, AVAudioTime) -> Void = makeAudioTapEnqueueCallback(queue: queue)
+        inputNode.installTap(
+            onBus: 0,
+            bufferSize: 1024,
+            format: recordingFormat,
+            block: tapBlock)
+
+        self.audioEngine.prepare()
+        try self.audioEngine.start()
+
+        let handler = self.makeRecognitionResultHandler()
+        self.recognitionTask = self.speechRecognizer?.recognitionTask(with: request, resultHandler: handler)
+
+        self.tapDrainTask = Task { [weak self] in
+            guard let self, let queue = self.tapQueue else { return }
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: 40_000_000)
+                let drained = queue.drain()
+                if drained.isEmpty { continue }
+                for buf in drained {
+                    request.append(buf)
+                }
+            }
+        }
+    }
+
+    private nonisolated func makeRecognitionResultHandler() -> @Sendable (SFSpeechRecognitionResult?, Error?) -> Void {
+        { [weak self] result, error in
+            let transcript = result?.bestTranscription.formattedString
+            let segments = result.flatMap { result in
+                transcript.map { WakeWordSpeechSegments.from(transcription: result.bestTranscription, transcript: $0) }
+            } ?? []
+            let errorText = error?.localizedDescription
+
+            Task { @MainActor in
+                self?.handleRecognitionCallback(transcript: transcript, segments: segments, errorText: errorText)
+            }
+        }
+    }
+
+    private func handleRecognitionCallback(transcript: String?, segments: [WakeWordSegment], errorText: String?) {
+        if let errorText {
+            self.statusText = "Recognizer error: \(errorText)"
+            self.isListening = false
+
+            let shouldRestart = self.isEnabled
+            if shouldRestart {
+                Task {
+                    try? await Task.sleep(nanoseconds: 700_000_000)
+                    await self.start()
+                }
+            }
+            return
+        }
+
+        guard let transcript else { return }
+        guard let cmd = self.extractCommand(from: transcript, segments: segments) else { return }
+
+        if cmd == self.lastDispatched { return }
+        self.lastDispatched = cmd
+        self.lastTriggeredCommand = cmd
+        self.statusText = "Triggered"
+
+        Task { [weak self] in
+            guard let self else { return }
+            await self.onCommand?(cmd)
+            await self.startIfEnabled()
+        }
+    }
+
+    private func startIfEnabled() async {
+        let shouldRestart = self.isEnabled
+        if shouldRestart {
+            await self.start()
+        }
+    }
+
+    private func extractCommand(from transcript: String, segments: [WakeWordSegment]) -> String? {
+        Self.extractCommand(from: transcript, segments: segments, triggers: self.activeTriggerWords)
+    }
+
+    nonisolated static func extractCommand(
+        from transcript: String,
+        segments: [WakeWordSegment],
+        triggers: [String],
+        minPostTriggerGap: TimeInterval = 0.45) -> String?
+    {
+        let config = WakeWordGateConfig(triggers: triggers, minPostTriggerGap: minPostTriggerGap)
+        return WakeWordGate.match(transcript: transcript, segments: segments, config: config)?.command
+    }
+
+    private static func configureAudioSession() throws {
+        let session = AVAudioSession.sharedInstance()
+        try session.setCategory(.playAndRecord, mode: .measurement, options: [
+            .duckOthers,
+            .mixWithOthers,
+            .allowBluetoothHFP,
+            .defaultToSpeaker,
+        ])
+        try session.setActive(true, options: [])
+    }
+
+    private nonisolated static func requestMicrophonePermission() async -> Bool {
+        let session = AVAudioSession.sharedInstance()
+        switch session.recordPermission {
+        case .granted:
+            return true
+        case .denied:
+            return false
+        case .undetermined:
+            break
+        @unknown default:
+            return false
+        }
+
+        return await self.requestPermissionWithTimeout { completion in
+            AVAudioSession.sharedInstance().requestRecordPermission { ok in
+                completion(ok)
+            }
+        }
+    }
+
+    private nonisolated static func requestSpeechPermission() async -> Bool {
+        let status = SFSpeechRecognizer.authorizationStatus()
+        switch status {
+        case .authorized:
+            return true
+        case .denied, .restricted:
+            return false
+        case .notDetermined:
+            break
+        @unknown default:
+            return false
+        }
+
+        return await self.requestPermissionWithTimeout { completion in
+            SFSpeechRecognizer.requestAuthorization { authStatus in
+                completion(authStatus == .authorized)
+            }
+        }
+    }
+
+    private nonisolated static func requestPermissionWithTimeout(
+        _ operation: @escaping @Sendable (@escaping (Bool) -> Void) -> Void) async -> Bool
+    {
+        do {
+            return try await AsyncTimeout.withTimeout(
+                seconds: 8,
+                onTimeout: { NSError(domain: "VoiceWake", code: 6, userInfo: [
+                    NSLocalizedDescriptionKey: "permission request timed out",
+                ]) },
+                operation: {
+                    await withCheckedContinuation(isolation: nil) { cont in
+                        Task { @MainActor in
+                            operation { ok in
+                                cont.resume(returning: ok)
+                            }
+                        }
+                    }
+                })
+        } catch {
+            return false
+        }
+    }
+
+    private static func permissionMessage(
+        kind: String,
+        status: AVAudioSession.RecordPermission) -> String
+    {
+        switch status {
+        case .denied:
+            return "\(kind) permission denied"
+        case .undetermined:
+            return "\(kind) permission not granted"
+        case .granted:
+            return "\(kind) permission denied"
+        @unknown default:
+            return "\(kind) permission denied"
+        }
+    }
+
+    private static func permissionMessage(
+        kind: String,
+        status: SFSpeechRecognizerAuthorizationStatus) -> String
+    {
+        switch status {
+        case .denied:
+            return "\(kind) permission denied"
+        case .restricted:
+            return "\(kind) permission restricted"
+        case .notDetermined:
+            return "\(kind) permission not granted"
+        case .authorized:
+            return "\(kind) permission denied"
+        @unknown default:
+            return "\(kind) permission denied"
+        }
+    }
+}
+
+#if DEBUG
+extension VoiceWakeManager {
+    func _test_handleRecognitionCallback(transcript: String?, segments: [WakeWordSegment], errorText: String?) {
+        self.handleRecognitionCallback(transcript: transcript, segments: segments, errorText: errorText)
+    }
+}
+#endif

openclaw/apps/ios/Sources/Voice/VoiceWakePreferences.swift

@@ -0,0 +1,44 @@
+import Foundation
+
+enum VoiceWakePreferences {
+    static let enabledKey = "voiceWake.enabled"
+    static let triggerWordsKey = "voiceWake.triggerWords"
+
+    // Keep defaults aligned with the mac app.
+    static let defaultTriggerWords: [String] = ["openclaw", "claude"]
+    static let maxWords = 32
+    static let maxWordLength = 64
+
+    static func decodeGatewayTriggers(from payloadJSON: String) -> [String]? {
+        guard let data = payloadJSON.data(using: .utf8) else { return nil }
+        return self.decodeGatewayTriggers(from: data)
+    }
+
+    static func decodeGatewayTriggers(from data: Data) -> [String]? {
+        struct Payload: Decodable { var triggers: [String] }
+        guard let decoded = try? JSONDecoder().decode(Payload.self, from: data) else { return nil }
+        return self.sanitizeTriggerWords(decoded.triggers)
+    }
+
+    static func loadTriggerWords(defaults: UserDefaults = .standard) -> [String] {
+        defaults.stringArray(forKey: self.triggerWordsKey) ?? self.defaultTriggerWords
+    }
+
+    static func saveTriggerWords(_ words: [String], defaults: UserDefaults = .standard) {
+        defaults.set(words, forKey: self.triggerWordsKey)
+    }
+
+    static func sanitizeTriggerWords(_ words: [String]) -> [String] {
+        let cleaned = words
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .prefix(Self.maxWords)
+            .map { String($0.prefix(Self.maxWordLength)) }
+        return cleaned.isEmpty ? Self.defaultTriggerWords : cleaned
+    }
+
+    static func displayString(for words: [String]) -> String {
+        let sanitized = self.sanitizeTriggerWords(words)
+        return sanitized.joined(separator: ", ")
+    }
+}