36.2 iOS 节点应用

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~180k tokens，输出 ~5k tokens（本节）

---

OpenClaw 的 iOS 应用与 macOS 应用有本质区别：macOS 应用是一个控制端（operator），而 iOS 应用是一个节点（node）。节点不运行 Gateway，而是连接到局域网中的 Gateway 实例，将 iPhone/iPad 的硬件能力（摄像头、屏幕、麦克风、位置）暴露给 AI Agent 使用。

36.2.1 Bonjour 配对

服务发现

iOS 应用启动后的第一件事是找到局域网中的 Gateway。这通过 Apple 的 Bonjour（mDNS/DNS-SD）协议实现：

// apps/ios/Sources/Gateway/GatewayConnectionController.swift
@MainActor
@Observable
final class GatewayConnectionController {
    private let discovery = GatewayDiscoveryModel()
    private(set) var gateways: [GatewayDiscoveryModel.DiscoveredGateway] = []
    
    init(appModel: NodeAppModel, startDiscovery: Bool = true) {
        GatewaySettingsStore.bootstrapPersistence()
        self.updateFromDiscovery()
        self.observeDiscovery()
        if startDiscovery { self.discovery.start() }
    }
    
    // 场景生命周期感知
    func setScenePhase(_ phase: ScenePhase) {
        switch phase {
        case .background:  self.discovery.stop()   // 后台时停止发现
        case .active, .inactive: self.discovery.start()
        }
    }
}

衍生解释 — Bonjour (mDNS/DNS-SD)

Bonjour 是 Apple 对两个 IETF 标准的实现：mDNS（多播 DNS，RFC 6762）和 DNS-SD（基于 DNS 的服务发现，RFC 6763）。设备在局域网中通过 UDP 多播（224.0.0.251:5353）广播和发现服务，无需中央 DNS 服务器。例如，Gateway 广播一个 _openclaw._tcp 服务，iOS 应用通过 NWBrowser 发现它并获取 IP 和端口。

发现到 Gateway 后，用户可以选择连接。连接参数包括主机地址、端口、TLS 配置和认证凭据：

func connect(_ gateway: DiscoveredGateway) async {
    let host = resolveGatewayHost(gateway)
    let port = gateway.gatewayPort ?? 18789
    let tlsParams = resolveDiscoveredTLSParams(gateway: gateway)
    let url = buildGatewayURL(host: host, port: port, useTLS: tlsParams?.required == true)
    // 通过 WebSocket 连接 Gateway，角色为 "node"
    startAutoConnect(url: url, tls: tlsParams, token: token, password: password)
}

应用入口

iOS 应用的入口很简洁：

// apps/ios/Sources/OpenClawApp.swift
@main
struct OpenClawApp: App {
    @State private var appModel: NodeAppModel
    @State private var gatewayController: GatewayConnectionController

    var body: some Scene {
        WindowGroup {
            RootCanvas()
                .environment(appModel)
                .environment(appModel.voiceWake)
                .environment(gatewayController)
                .onOpenURL { url in
                    Task { await appModel.handleDeepLink(url: url) }
                }
                .onChange(of: scenePhase) { _, newValue in
                    appModel.setScenePhase(newValue)
                    gatewayController.setScenePhase(newValue)
                }
        }
    }
}

NodeAppModel 是应用的核心状态模型，管理与 Gateway 的会话、设备能力、语音唤醒等。

36.2.2 Canvas 表面

iOS 应用的主界面是一个 Canvas 表面——它不仅是聊天界面，更是 AI Agent 可以直接操控的"画布"。Agent 可以发送 Canvas 命令来控制界面内容，实现展示图表、动画、交互式控件等能力。

源码结构：

apps/ios/Sources/
├── RootCanvas.swift        # 主 Canvas 视图
├── Camera/                 # 摄像头能力
├── Screen/                 # 屏幕录制能力
├── Voice/                  # 语音能力
├── Location/               # 位置能力
├── Chat/                   # 聊天界面
├── Gateway/                # 连接管理
├── Model/                  # 数据模型
├── Settings/               # 设置界面
├── Status/                 # 状态显示
└── SessionKey.swift        # 会话键管理

Canvas 命令由共享库 OpenClawKit 定义（见 28.4 节），包括 DOM 操作、文件显示、A2UI（Agent-to-UI）动作等。

36.2.3 Voice Wake / Talk Mode

iOS 节点同样支持语音唤醒和对话模式，实现方式与 macOS 类似（共享自 OpenClawKit），但有以下适配：

1. 后台限制：iOS 不允许应用在后台无限制运行音频捕获。语音唤醒在应用进入后台时暂停（setScenePhase(.background) → 停止发现和录音）

2. 音频会话管理：需要正确配置 AVAudioSession 的 category 和 mode，确保与系统音频（如电话、音乐）和平共处

3. 权限模型：iOS 的权限弹窗是一次性的——如果用户拒绝了麦克风权限，只能引导到系统设置中手动开启

36.2.4 摄像头与屏幕录制

iOS 节点的独特价值在于将移动设备的传感器暴露给 AI Agent：

摄像头（Camera/）：Agent 可以请求拍照或实时视频帧，用于视觉分析。摄像头能力通过 AVCaptureSession 实现。

屏幕录制（Screen/）：Agent 可以请求屏幕截图或录制。iOS 使用 ReplayKit 框架提供屏幕内容捕获。

这些能力在连接 Gateway 时通过 caps（capabilities）字段声明：

// apps/shared/OpenClawKit/Sources/OpenClawKit/Capabilities.swift
public enum OpenClawCapability: String, Codable, Sendable {
    case canvas         // 画布操控能力
    case camera         // 摄像头
    case screen         // 屏幕录制
    case voiceWake      // 语音唤醒
    case location       // 位置信息
}

Gateway 根据节点声明的能力来决定哪些工具可以使用——只有连接了具备 camera 能力的节点时，Agent 才能调用拍照工具。

v2026.3.9 更新 —— iOS 应用新增了 Home Canvas 刷新机制。当 iOS 应用从后台恢复到前台时，Home Canvas 会自动刷新其内容（通过向 Gateway 发送 canvas.refresh 请求），确保用户看到的 Canvas 状态始终是最新的。此前，后台恢复后 Canvas 可能显示过时内容，需要用户手动触发刷新。

---

本节小结

1. iOS 应用是"节点"角色，不运行 Gateway，而是通过 Bonjour 发现并连接到局域网中的 Gateway 实例。

2. 服务发现基于 mDNS/DNS-SD 协议，应用自动感知场景生命周期（前台/后台）来启停发现。

3. Canvas 表面是主界面，AI Agent 可以通过命令直接操控界面内容。

4. 语音唤醒共享自 OpenClawKit，但受 iOS 后台执行限制。

5. 摄像头和屏幕录制是节点的核心硬件能力，通过 capabilities 声明让 Gateway 知晓可用工具。