iOS 节点应用通过 WebSocket 连接 OpenClaw Gateway，支持 Canvas、截屏、拍照、位置、语音唤醒等能力。配对时需在宿主机上用 openclaw devices approve 手动批准请求；如果配对提示不出现，直接用 openclaw devices list 查看并批准。Gateway 必须配置 Canvas host 才能使用 A2UI，否则报 A2UI_HOST_NOT_CONFIGURED。官方 iOS 构建使用外部推送中继（需设置 gateway.push.apns.relay.baseUrl），本地构建则直接用 APNs 环境变量。

iOS 节点配对与 Gateway 连接指南 - OpenClaw 配置与排错

可用性：内部预览版。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。

可选自动批准：如果 iOS 节点始终从受控子网连接，可在 Gateway 配置中指定 CIDR 或精确 IP，实现首次节点自动批准：

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

默认关闭。仅对 role: node 且未申请 scopes 的首次配对生效。操作员/浏览器配对以及任何 role、scope、metadata 或公钥变更仍需要手动批准。

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 和 StoreKit 应用交易 JWS 向中继注册。
• 中继返回不透明的中继句柄和注册范围的发送授权。
• 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 证明和 StoreKit 应用交易 JWS。
   • 中继验证 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)"

这些是 Gateway 宿主运行时的环境变量，不是 Fastlane 设置。apps/ios/fastlane/.env 仅存储 App Store Connect / TestFlight 认证信息（如 ASC_KEY_ID、ASC_ISSUER_ID），不配置直接 APNs 投递。

推荐的 Gateway 宿主存储方式：

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"

不要提交 .p8 文件到版本控制或放在项目检出目录下。

发现路径

Bonjour（局域网）

iOS 应用浏览 _openclaw-gw._tcp 在 local. 上的广播，以及配置的广域 DNS-SD 发现域。同一局域网的 Gateway 自动出现在 local.；跨网络发现可以使用配置的广域域而无需更改信标类型。

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 节点会声明 talk 能力，并可声明 talk.ptt.start、talk.ptt.stop、talk.ptt.cancel 和 talk.ptt.once；Gateway 默认允许这些 PTT 命令用于受信的可通话节点。
• iOS 可能挂起后台音频；应用不在前台时，请将语音功能视为尽力而为。

后台存活信标

当 iOS 因静默推送、后台刷新或显著性位置事件唤醒应用时，应用会尝试短时节点重连，然后调用 node.event，事件类型为 node.presence.alive。Gateway 仅在认证的节点设备标识已知后，才会在配对节点/设备元数据中记录 lastSeenAtMs/lastSeenReason。

应用仅在 Gateway 响应中包含 handled: true 时，才视为后台唤醒成功记录。旧版 Gateway 可能用 { "ok": true } 确认 node.event；该响应兼容但不计入持久的 last-seen 更新。

常见错误

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

常见问题

iOS 节点一直显示 "Pairing prompt never appears" 怎么办？

在 Gateway 宿主机上运行 openclaw devices list 查看是否有待处理的配对请求，然后用 openclaw devices approve <requestId> 手动批准。如果自动批准未生效，检查 gateway.nodes.pairing.autoApproveCidrs 是否匹配 iOS 设备的 IP。

配置 Canvas 后 iOS 节点报 A2UI_HOST_NOT_CONFIGURED？

检查 Gateway 配置中 plugins.entries.canvas.config.host 是否正确设置。Canvas 主机默认使用 Gateway 的 HTTP 端口（18789），确保该地址可通过 iOS 设备访问。

重新安装 iOS 应用后无法连接 Gateway？

Keychain 中的配对 token 已被清除，需要在 iOS 应用中重新输入配对码或手动发现 Gateway 并再次配对。在 Gateway 上重新运行 openclaw devices list 并批准新的请求。

相关文档

• 设备配对
• Gateway 发现
• Bonjour