iOS 应用

​

它的功能

• 通过 WebSocket 连接到 Gateway 网关（LAN 或 tailnet）。
• 暴露节点能力：Canvas、屏幕快照、相机拍摄、位置、Talk 模式、语音唤醒。
• 接收 node.invoke 命令并上报节点状态事件。
• 从智能体界面（文件）以只读方式浏览所选智能体的工作区：目录下钻、带语法高亮的文本预览、图片预览和共享表单导出。不执行写入操作；预览大小由 Gateway 网关限制。
• 为每个已配对 Gateway 网关保留一个小型只读离线缓存，保存最近的聊天会话和转录：冷启动会立即绘制最后已知的转录，并在 Gateway 网关响应后刷新；断开连接时仍可浏览最近聊天；重置/忘记会清除受保护的本地缓存。
• 将断开连接时发送的文本消息排入每个 Gateway 网关的持久发件箱（最多 50 条）：排队的气泡会显示在转录中，重连后按顺序刷新并进行幂等重试，在规范历史确认发送前保持持久化，在显示重试/删除操作前使用退避重试，离线 48 小时后过期而不是发送；重置/忘记会随缓存一起清除队列。
• 按需朗读助手消息：在聊天中长按消息并选择 收听。app 会使用已配置的 TTS 提供商播放受支持的 Gateway 网关 tts.speak 片段，并在 Gateway 网关音频不可用或无法播放时回退到设备端语音。切换会话或进入后台时会停止播放。

​

要求

• Gateway 网关运行在另一台设备上（macOS、Linux，或通过 WSL2 的 Windows）。
• 网络路径：
  • 通过 Bonjour 在同一 LAN，或
  • 通过单播 DNS-SD 的 tailnet（示例域名：openclaw.internal.），或
  • 手动主机/端口（回退）。

​

快速开始（配对 + 连接）

1. 启动一个已认证的 Gateway 网关，并提供手机可访问的路由。Tailscale Serve 是推荐的远程路径：

openclaw gateway --port 18789 --tailscale serve

2. 打开 Control UI，选择 节点，然后在 设备 卡片中点击 配对移动设备。
3. 在 iOS app 中，打开 设置 -> Gateway 网关，扫描二维码（或粘贴 设置代码），然后连接。 如果设置代码同时包含 LAN 和 Tailscale Serve 路由，app 会按顺序探测它们，并保存第一个可访问的端点。
4. 官方 app 会自动连接。如果 设备 显示待处理 请求，请在批准前检查它的角色和权限范围。

openclaw devices list
openclaw devices approve <requestId>

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

5. 验证连接：

openclaw nodes status
openclaw gateway call node.list --params "{}"

​

官方构建的中继支持推送

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
        },
      },
    },
  },
}

• iOS app 使用 App Attest 和 StoreKit app 交易 JWS 向中继注册。
• 中继返回一个不透明的中继句柄，以及注册范围内的发送授权。
• iOS app 获取已配对 Gateway 网关身份（gateway.identity.get），并将其包含在中继注册中，因此中继支持的注册会委派给该特定 Gateway 网关。
• app 使用 push.apns.register 将该中继支持的注册转发给已配对 Gateway 网关。
• Gateway 网关将该已存储的中继句柄用于 push.test、后台唤醒和唤醒轻推。
• 如果 app 之后连接到不同的 Gateway 网关，或连接到使用不同中继基础 URL 的构建，它会刷新中继注册，而不是复用旧绑定。

1. 安装官方 iOS app。
2. 可选：仅在使用刻意分离的自定义中继构建时，在 Gateway 网关上设置 gateway.push.apns.relay.baseUrl。
3. 将 app 与 Gateway 网关配对，并让它完成连接。
4. 一旦 app 拥有 APNs 令牌、操作员会话已连接且中继注册成功，它会发布一次 push.apns.register。
5. 之后，push.test、重连唤醒和唤醒轻推可以使用已存储的中继支持注册。

​

后台存活信标

• OPENCLAW_APNS_RELAY_BASE_URL 仍可作为 Gateway 网关的临时环境变量覆盖项使用（gateway.push.apns.relay.baseUrl 是配置优先路径）。
• App Store 发布构建的推送模式会硬编码托管中继主机，并且从不读取中继 URL 覆盖项 —— OPENCLAW_PUSH_RELAY_BASE_URL 构建时环境变量只影响本地/沙箱 iOS 构建模式。

​

认证和信任流程

• 只有通过 Apple 分发的正版 OpenClaw iOS 构建可以使用托管中继。
• Gateway 网关只能为与该特定 Gateway 网关配对的 iOS 设备发送中继支持的推送。

1. iOS app -> gateway：app 通过正常的 Gateway 网关认证流程与 Gateway 网关配对，获得一个已认证的节点会话，以及一个已认证的操作员会话。操作员会话调用 gateway.identity.get。
2. iOS app -> relay：app 通过 HTTPS 调用中继注册端点，并提供 App Attest 证明和 StoreKit app 交易 JWS。中继验证 bundle ID、App Attest 证明和 Apple 分发证明，并要求官方/生产分发路径 —— 这会阻止本地 Xcode/dev 构建使用托管中继，因为本地构建无法满足官方 Apple 分发证明。
3. gateway identity delegation：在中继注册前，app 从 gateway.identity.get 获取已配对 Gateway 网关身份，并将其包含在中继注册载荷中。中继返回一个中继句柄，以及委派给该 Gateway 网关身份的注册范围内发送授权。
4. gateway -> relay：Gateway 网关存储来自 push.apns.register 的中继句柄和发送授权。在 push.test、重连唤醒和唤醒轻推时，Gateway 网关用自己的设备身份签署发送请求；中继会同时验证已存储的发送授权，以及 Gateway 网关签名是否匹配注册时委派的 Gateway 网关身份。即使另一个 Gateway 网关以某种方式获得该句柄，也无法复用该已存储注册。
5. relay -> APNs：中继拥有官方构建的生产 APNs 凭证和原始 APNs 令牌。对于中继支持的官方构建，Gateway 网关从不存储原始 APNs 令牌；中继代表已配对 Gateway 网关向 APNs 发送最终推送。

export OPENCLAW_APNS_TEAM_ID="TEAMID"
export OPENCLAW_APNS_KEY_ID="KEYID"
export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"

mkdir -p ~/.openclaw/credentials/apns
chmod 700 ~/.openclaw/credentials/apns
mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8"

​

设备发现路径

​

Bonjour（LAN）

​

Tailnet（跨网络）

​

手动主机/端口

​

多个 Gateway 网关

• 设置 -> Gateway 网关 会显示 已配对 Gateway 网关 列表，并标记当前活动 Gateway 网关。点按条目即可切换；应用会关闭当前会话并重新连接到所选 Gateway 网关。当配对了多个 Gateway 网关时，连接行旁会出现快速切换菜单。
• 凭证、TLS 信任决策、按 Gateway 网关区分的偏好设置，以及缓存的聊天历史都会按 Gateway 网关存储。切换绝不会在 Gateway 网关之间混用状态，推送注册也会跟随当前活动 Gateway 网关。
• 滑动某个已配对 Gateway 网关（或使用其上下文菜单）选择 忘记，这会移除它的凭证、设备令牌、TLS pin 和缓存聊天。
• 发现到的 Gateway 网关必须在网络上可见，才能切换到它们；手动配置的 Gateway 网关会按保存的主机和端口重新连接。

​

Canvas + A2UI

openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__openclaw__/canvas/"}'

• Gateway 网关 canvas 主机会从 Gateway 网关 HTTP 服务器提供 /__openclaw__/canvas/ 和 /__openclaw__/a2ui/（与 gateway.port 使用同一端口，默认 18789）。
• iOS 节点会将内置脚手架保留为已连接的默认视图。canvas.a2ui.push 和 canvas.a2ui.reset 使用内置的应用自有 A2UI 页面。
• 远程 Gateway 网关 A2UI 页面在 iOS 上仅用于渲染；原生 A2UI 按钮操作只接受来自内置应用自有页面的操作。
• 使用 canvas.navigate 和 {"url":""} 返回内置脚手架。

​

Codex Computer Use 关系

​

Canvas eval / snapshot

openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'

openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'

​

语音唤醒 + Talk 模式

• 语音唤醒和 Talk 模式可在设置中使用。
• 当 talk.realtime.transport 为 webrtc 时，OpenAI realtime Talk 使用客户端自有的 WebRTC；显式的 gateway-relay 配置仍由 Gateway 网关拥有。参见 Talk 模式。
• 支持 Talk 的 iOS 节点会通告 talk 能力，并且可以声明 talk.ptt.start、talk.ptt.stop、talk.ptt.cancel 和 talk.ptt.once；Gateway 网关默认允许受信任且支持 Talk 的节点使用这些按键通话命令。
• iOS 可能会挂起后台音频；当应用未处于活动状态时，应将语音功能视为尽力而为。

​

常见错误

• NODE_BACKGROUND_UNAVAILABLE：将 iOS 应用切到前台（canvas/camera/screen 命令需要这样做）。
• A2UI_HOST_UNAVAILABLE：应用 WebView 中无法访问内置 A2UI 页面；让应用保持在 Screen 标签页前台，然后重试。
• 配对提示一直不出现：运行 openclaw devices list 并手动批准。
• Watch 不显示 iPhone 状态：确认 iPhone 在 watch.status 中报告 watchPaired: true 和 watchAppInstalled: true。如果配对为 false，请在 Apple 的 Watch 应用中配对 Watch。如果安装为 false，请从 My Watch -> Available Apps 安装配套应用。 任一变更完成后，在 Watch 上打开一次 OpenClaw；即时可达性仍然要求两个应用都在运行， 而排队的更新可以稍后在后台到达。
• 重新安装后重连失败：Keychain 配对令牌已被清除；请重新配对节点。

​

相关文档

• 配对
• 设备发现
• Bonjour