iOS 应用（节点）

可用性：内部预览版。iOS 应用尚未公开分发。

功能说明

• 通过 WebSocket 连接 Gateway（局域网或 tailnet）。
• 提供节点能力：Canvas、截屏、拍照、位置、通话模式、语音唤醒。
• 接收 node.invoke 命令并上报节点状态事件。

环境要求

• Gateway 运行在另一台设备上（macOS、Linux 或 Windows WSL2）。
• 网络路径：
  • 同一局域网通过 Bonjour，或
  • Tailnet 通过单播 DNS-SD（示例域名：openclaw.internal.），或
  • 手动指定 host/port（备选）。

快速开始（配对 + 连接）

1. 启动 Gateway：

openclaw gateway --port 18789

2. 在 iOS 应用中，打开 Settings，选择已发现的 Gateway（或启用 Manual Host 并输入 host/port）。

3. 在 Gateway 宿主机上批准配对请求：

openclaw devices list
openclaw devices approve <requestId>

如果应用使用变更的认证信息（role/scopes/公钥）重新发起配对请求， 旧的待处理请求会被替换，并生成新的 requestId。 批准前请再次运行 openclaw devices list。

4. 验证连接：

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

官方构建的中继推送

官方分发的 iOS 构建使用外部推送中继，而不是将原始 APNs token 暴露给 Gateway。

Gateway 端配置要求：

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

流程说明：

• iOS 应用通过 App Attest 和应用收据向中继注册。
• 中继返回不透明的中继句柄和注册范围的发送授权。
• iOS 应用获取已配对 Gateway 的身份并在中继注册中包含它，使中继支持的注册委托给该特定 Gateway。
• 应用通过 push.apns.register 将该中继支持的注册转发给已配对的 Gateway。
• Gateway 使用存储的中继句柄进行 push.test、后台唤醒和唤醒推送。
• Gateway 中继 base URL 必须与烧录到官方/TestFlight iOS 构建中的中继 URL 匹配。
• 如果应用后来连接到不同的 Gateway 或使用不同中继 base URL 的构建，它会刷新中继注册而不是复用旧绑定。

此路径下 Gateway 不需要：

• 不需要部署级别的中继 token。
• 不需要官方/TestFlight 中继支持发送的直接 APNs 密钥。

预期操作流程：

1. 安装官方/TestFlight iOS 构建。
2. 在 Gateway 上设置 gateway.push.apns.relay.baseUrl。
3. 将应用配对到 Gateway 并等待连接完成。
4. 应用在获取 APNs token、运营商会话连接且中继注册成功后，自动发布 push.apns.register。
5. 此后，push.test、重连唤醒和唤醒推送可使用存储的中继支持注册。

兼容性说明：

• OPENCLAW_APNS_RELAY_BASE_URL 仍可作为 Gateway 的临时环境变量覆盖。

认证与信任流程

中继的存在是为了强制两个直接 APNs on Gateway 无法为官方 iOS 构建提供的约束：

• 只有通过 Apple 官方渠道分发的真实 OpenClaw iOS 构建才能使用托管中继。
• Gateway 只能为与该特定 Gateway 配对的 iOS 设备发送中继支持的推送。

逐跳说明：

1. iOS 应用 -> Gateway

   • 应用首先通过正常的 Gateway 认证流程与 Gateway 配对。
   • 这使应用获得已认证的节点会话和已认证的运营商会话。
   • 运营商会话用于调用 gateway.identity.get。

2. iOS 应用 -> 中继

   • 应用通过 HTTPS 调用中继注册端点。
   • 注册包含 App Attest 证明和应用收据。
   • 中继验证 Bundle ID、App Attest 证明和 Apple 收据，并要求官方/生产分发路径。
   • 这阻止了本地 Xcode/开发构建使用托管中继。本地构建可能已签名，但不满足中继期望的官方 Apple 分发证明。

3. Gateway 身份委托

   • 在中继注册之前，应用从 gateway.identity.get 获取已配对 Gateway 的身份。
   • 应用在中继注册载荷中包含该 Gateway 身份。
   • 中继返回委托给该 Gateway 身份的中继句柄和注册范围发送授权。

4. Gateway -> 中继

   • Gateway 存储来自 push.apns.register 的中继句柄和发送授权。
   • 在 push.test、重连唤醒和唤醒推送时，Gateway 用自己的设备身份签名发送请求。
   • 中继根据注册中的委托 Gateway 身份验证存储的发送授权和 Gateway 签名。
   • 其他 Gateway 无法复用该存储的注册，即使以某种方式获取了句柄。

5. 中继 -> APNs

   • 中继拥有生产 APNs 凭据和官方构建的原始 APNs token。
   • Gateway 不存储中继支持的官方构建的原始 APNs token。
   • 中继代表已配对的 Gateway 向 APNs 发送最终推送。

这样设计的原因：

• 将生产 APNs 凭据保持在用户 Gateway 之外。
• 避免在 Gateway 上存储官方构建的原始 APNs token。
• 仅允许官方/TestFlight OpenClaw 构建使用托管中继。
• 防止一个 Gateway 向属于不同 Gateway 的 iOS 设备发送唤醒推送。

本地/手动构建保持使用直接 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)"

发现路径

Bonjour（局域网）

Gateway 在 local. 上广播 _openclaw-gw._tcp。iOS 应用会自动列出这些 Gateway。

Tailnet（跨网络）

如果 mDNS 被阻止，使用单播 DNS-SD 区域（选择一个域名；示例：openclaw.internal.）和 Tailscale split DNS。 CoreDNS 示例见 Bonjour。

手动 host/port

在 Settings 中启用 Manual Host 并输入 Gateway host + port（默认 18789）。

Canvas + A2UI

iOS 节点渲染 WKWebView Canvas。使用 node.invoke 控制它：

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

说明：

• Gateway Canvas 宿主提供 /__openclaw__/canvas/ 和 /__openclaw__/a2ui/。
• 从 Gateway HTTP 服务器提供（与 gateway.port 同端口，默认 18789）。
• 当 Canvas 宿主 URL 被广播时，iOS 节点连接后自动导航到 A2UI。
• 使用 canvas.navigate 和 {"url":""} 返回内置脚手架。

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

语音唤醒 + 通话模式

• 语音唤醒和通话模式可在 Settings 中使用。
• iOS 可能挂起后台音频；应用不在前台时，请将语音功能视为尽力而为。

常见错误

• NODE_BACKGROUND_UNAVAILABLE：将 iOS 应用切换到前台（canvas/camera/screen 命令需要前台）。
• A2UI_HOST_NOT_CONFIGURED：Gateway 未广播 Canvas 宿主 URL；检查 Gateway 配置 中的 canvasHost。
• 配对提示从未出现：运行 openclaw devices list 并手动批准。
• 重装后重连失败：Keychain 配对 token 已清除；重新配对节点。

相关文档

• 设备配对
• Gateway 发现
• Bonjour