iOS 应用配置与连接

2025-07-10 · 6 分钟安装部署

iOS 节点的角色

OpenClaw iOS 应用是一个内部预览版节点，通过 WebSocket 连接 Gateway，将设备的摄像头、屏幕截图、位置服务、Canvas 渲染和语音功能暴露给 AI 智能体。Gateway 必须运行在单独的设备上（macOS、Linux 或 Windows WSL2），iOS 本身不承载 Gateway 进程。

快速连接流程

第一步：启动 Gateway

openclaw gateway --port 18789

第二步：在 iOS 上配置连接

打开 App 设置，从自动发现列表中选择 Gateway，或开启「Manual Host」手动输入地址和端口（默认 18789）。

第三步：审批配对

openclaw devices list
openclaw devices approve <requestId>

如果更换了认证参数重新配对，旧的待审批请求会被新请求覆盖，需要用最新的 requestId 审批。

第四步：验证节点状态

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

Canvas 与 A2UI

iOS 使用 WKWebView 渲染 Canvas 内容，支持 A2UI 协议的服务端推送消息（beginRendering、surfaceUpdate、dataModelUpdate 等）。连接成功后若 Gateway 配置了 canvas host，App 会自动导航到 A2UI 页面。

手动导航示例：

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

在 Canvas 中执行绘图脚本：

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\"; })()"}'

推送通知配置

官方构建版支持通过 APNs Relay 接收推送通知，无需暴露 Gateway 端口。在 Gateway 配置文件中添加：

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

配对成功并建立 operator session 后，App 会自动完成 relay 注册。Relay 通过多重验证链保障安全：仅官方 App Store/TestFlight 版本可接入托管 relay；Gateway 只能为已配对设备发推送；每个 relay 注册都绑定到特定 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 广播 `_openclaw-gw._tcp` 服务，App 自动列出
Tailnet	通过 Tailscale split DNS 实现跨网络发现
手动输入	设置 → Manual Host，填入 IP 和端口

常见问题

错误	处理方式
`NODE_BACKGROUND_UNAVAILABLE`	将 App 切换到前台，Canvas/摄像头功能必须在前台运行
`A2UI_HOST_NOT_CONFIGURED`	检查 Gateway 是否配置并广播了 `canvasHost`
配对弹窗未出现	手动执行 `openclaw devices list` 查看并审批
重装后无法重连	Keychain 中的配对令牌已清除，需重新配对

语音功能

语音唤醒和按键说话（Push-to-Talk）可在 App 设置中开启。由于 iOS 系统限制，App 退到后台时语音功能属于尽力而为，建议需要持续语音交互时保持 App 在前台。