OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

平台概览

iOS 应用

可用性：当某个版本启用时，iPhone 应用构建会通过 Apple 渠道分发。本地开发构建也可以从源代码运行。

功能

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

要求

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

快速开始（配对 + 连接）

  1. 启动一个已通过身份验证、且手机可访问其路由的 Gateway 网关。建议使用 Tailscale Serve 作为远程访问路径：
bash
openclaw gateway --port 18789 --tailscale serve

对于受信任的同一 LAN 环境，请改用已通过身份验证的 gateway.bind: "lan"。 默认的回环绑定无法从手机访问。如果尚未配置 Gateway 网关，请先运行 openclaw onboard，以便创建设置代码时具有令牌或密码身份验证路径。

  1. 打开 Control UI，选择 Nodes，然后在 Devices 页面点击 Pair mobile device。

  2. 在 iOS 应用中，打开 Settings -> Gateway，扫描二维码（或粘贴 设置代码），然后连接。

    如果设置代码同时包含 LAN 和 Tailscale Serve 路由，应用会按顺序探测这些路由， 并保存第一个可访问的端点。

  3. 官方应用会自动连接。如果显示 Pending approval 请求， 请在批准前检查其角色和权限范围。

Control UI 按钮要求已有一个具备 operator.admin 的配对会话。 作为终端回退方式，请在 iOS 应用中选择发现的 Gateway 网关（或启用 Manual Host 并输入主机/端口），然后在 Gateway 网关主机上批准请求：

bash
openclaw devices listopenclaw devices approve <requestId>

如果应用使用已更改的身份验证详细信息（角色/权限范围/公钥）重试配对，之前的待处理请求将被取代，并创建新的 requestId。批准前请再次运行 openclaw devices list。

可选：如果 iOS 节点始终从受到严格控制的子网连接，你可以通过显式指定 CIDR 或确切 IP，选择启用首次节点自动批准：

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

此功能默认禁用。它仅适用于未请求任何权限范围的新 role: node 配对。操作员/浏览器配对，以及角色、权限范围、元数据或公钥的任何变更，仍需手动批准。

  1. 验证连接：
bash
openclaw nodes statusopenclaw gateway call node.list --params "{}"

健康摘要

iOS 节点可以返回设备端针对 today 的只读汇总数据。固定摘要包括步数、睡眠时长、平均静息心率，以及锻炼次数/时长。它绝不会返回单条 HealthKit 样本、来源、元数据、临床记录或写入权限。

此功能有两个相互独立的选择启用步骤：

  1. 在 iOS 应用中，打开 Settings -> Permissions -> Privacy & Access -> Health Summaries， 然后点击 Enable & Share Summaries。披露说明会解释：请求的汇总数据将通过你的 Gateway 网关离开手机、发送到你配置的 AI 提供商，并且可能保留在聊天历史记录中。
  2. 将 health.summary 添加到 gateway.nodes.allowCommands，然后拒绝并 重新批准已更改的 iPhone 节点命令界面。请确保 Gateway 网关仅限本地 或 tailnet 访问；启用此敏感命令后，安全审计会报告该命令。

模型使用现有的 nodes 工具，并设置 action: "invoke"、 invokeCommand: "health.summary"，以及将 invokeParamsJson 设置为 {"period":"today"}。

HealthKit 有意不透露读取权限是否已被拒绝。因此，缺少指标只表示没有返回可读取的值；这既不能证明权限遭拒，也不能证明不存在健康数据。OpenClaw 将摘要限制在当前日历日内，以免有限的历史访问窗口使多日总量看起来像是完整数据。OpenClaw 不会在后台摄取健康数据，也不会将摘要用于诊断或医疗建议。

默认情况下，Apple Watch 配套应用继续使用现有的 iPhone 中继，无需单独与 Gateway 网关配对。请在 Apple 的 Watch 应用中将 Watch 与 iPhone 配对，通过 Watch app -> My Watch -> Available Apps 安装 OpenClaw，然后分别在两台设备上打开一次 OpenClaw。

审核命令审批

具有 operator.admin 的操作员连接，或者由 Gateway 网关明确指定的已配对 operator.approvals 连接，可以在 iPhone 上审核待处理的 Exec 请求。审批卡片会显示 Gateway 网关提供的已清理命令预览、警告、主机上下文、到期时间，以及该请求提供的决策选项。已配对的 Apple Watch 会通过现有的 iPhone 中继接收相同的审核者安全提示，并提供精简的一次性允许/拒绝决策子集。Apple Watch 直接连接 Gateway 网关的模式不传递审批提示。

审批状态与 Control UI 及受支持的聊天界面共享。首个提交的答案生效。当其他界面处理了请求、收到远程处理完成通知，以及可能丢失处理确认时，iPhone 和 Watch 都会获取 Gateway 网关的规范终态记录。在回读确认请求是否仍处于待处理状态之前，操作始终不可用。

审批归属绑定到所选 Gateway 网关。切换 Gateway 网关时，不能将旧提示应用于替代连接。早于统一审批方法的 Gateway 网关会回退到已发布的 Exec 专用方法；要保留终态以及获得更丰富的跨界面结果，需要更新后的 Gateway 网关。

可选的 Apple Watch 直接节点

直接模式为 Watch 提供独立的签名节点身份和 Gateway 网关连接。当 OpenClaw 处于活动状态时，即使已配对的 iPhone 不可用，受支持的节点命令仍可通过 Watch 的 Wi-Fi 或蜂窝网络运行。

要求：

  • iPhone 已通过 operator.admin 权限范围连接到 Gateway 网关。
  • 设置代码公布一个使用 watchOS 信任证书的 wss:// Gateway 网关端点；Watch 会轮询对应的 https:// 源。不支持纯 HTTP、自签名证书或仅指纹信任。有关端点配置，请参阅 Gateway 网关负责的配对。Watch 无法独立访问回环、仅限 iPhone 和仅限 tailnet 的路由。
  • 使用蜂窝网络需要支持蜂窝网络且已启用服务的 Apple Watch。
  • OpenClaw 在 Watch 上处于活动状态。Apple 不允许普通 watchOS 应用持续保持通用 WebSocket/TCP 连接，因此直接节点会使用短 HTTPS 轮询，并在应用返回前台时重新连接。请参阅 Apple 的 watchOS 底层网络指南。

设置：

  1. 在 iPhone 上打开 Settings -> Apple Watch。
  2. 点击 Enable Direct Gateway Connection。
  3. 在短期有效的设置代码过期前，在 Watch 上打开 OpenClaw。
  4. 使用 openclaw nodes status 验证单独的 Apple Watch 行。

设置代码包含一个短期有效、仅供节点使用的引导凭据；在过期前应像保护密码一样保护它。它绝不会包含 iPhone 保存的 Gateway 网关密码或令牌。配对后，Watch 会存储自己的设备令牌并删除引导凭据。直接模式仅覆盖下列命令。聊天、Talk、审批和现有的 watch.* 通知流程仍属于 iPhone 中继功能，并且仍需要已配对的 iPhone。

watchOS 直接节点命令：

界面 命令 说明
设备 device.info, device.status Watch 身份、电池、温度、存储和网络。
通知 system.notify 应用处于活动状态时可用；需要 Watch 权限。

watchOS 不向第三方应用提供 WebKit，因此 Watch 直接节点不会公布 Canvas 命令。

官方构建的中继支持推送

官方分发的 iOS 构建使用外部推送中继，而不是将原始 APNs 令牌发布给 Gateway 网关。来自公共发布通道的官方 App Store 构建使用托管中继 https://ios-push-relay.openclaw.ai；此基础 URL 被硬编码用于 App Store 分发，不会读取任何覆盖配置。

自定义中继部署需要使用刻意独立的 iOS 构建/部署路径，并确保其中继 URL 与 Gateway 网关中继 URL 匹配。App Store 发布通道绝不会接受自定义中继 URL。如果你使用自定义中继构建，请设置匹配的 Gateway 网关中继 URL：

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

流程工作方式：

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

此路径中 Gateway 网关不需要：部署范围的中继令牌，也不需要用于官方 App Store 中继支持发送的直接 APNs 密钥。

预期的操作员流程：

  1. 安装官方 iOS 应用。
  2. 可选：仅在使用刻意独立的自定义中继构建时，在 Gateway 网关上设置 gateway.push.apns.relay.baseUrl。
  3. 将应用与 Gateway 网关配对，并等待连接完成。
  4. 当应用获得 APNs 令牌、操作员会话已连接且中继注册成功后，应用会发布 push.apns.register。
  5. 此后，push.test、重新连接唤醒和唤醒提示即可使用存储的中继支持注册。

后台存活信标

当 iOS 因静默推送、后台刷新或显著位置变化事件唤醒应用时，应用会尝试短暂重新连接节点，然后调用 node.event，并传入 event: "node.presence.alive"。仅在获知经过身份验证的节点设备身份后，Gateway 网关才会将其作为 lastSeenAtMs/lastSeenReason 记录到已配对节点/设备的元数据中。

仅当 Gateway 网关响应中包含 handled: true 时，应用才会将后台唤醒视为已成功记录。旧版 Gateway 网关可能会使用 { "ok": true } 确认 node.event；该响应兼容，但不算作持久的最后在线时间更新。

兼容性说明：

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

身份验证和信任流程

中继服务用于实施官方 iOS 构建中由 Gateway 网关直接连接 APNs 无法满足的两项约束：

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

逐跳流程：

  1. iOS app -> gateway：应用通过常规 Gateway 网关身份验证流程与 Gateway 网关配对，从而获得经过身份验证的节点会话和经过身份验证的操作员会话。操作员会话调用 gateway.identity.get。
  2. iOS app -> relay：应用通过 HTTPS 调用中继注册端点，并提供 App Attest 证明和 StoreKit 应用交易 JWS。中继会验证 bundle ID、App Attest 证明和 Apple 分发证明，并要求使用官方/生产分发路径——这会阻止本地 Xcode/开发构建使用托管中继，因为本地构建无法满足官方 Apple 分发证明要求。
  3. gateway identity delegation：在中继注册之前，应用会从 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。

创建此设计的原因：避免将生产 APNs 凭据放入用户的 Gateway 网关，避免在 Gateway 网关上存储官方构建的原始 APNs 令牌，仅允许官方 OpenClaw iOS 构建使用托管中继，并防止一个 Gateway 网关向归属另一 Gateway 网关的 iOS 设备发送唤醒推送。

本地/手动构建仍直接使用 APNs。如果你在不使用中继的情况下测试这些构建，Gateway 网关仍需要直接使用的 APNs 凭据：

bash
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 身份验证信息，例如 APP_STORE_CONNECT_KEY_ID 和 APP_STORE_CONNECT_ISSUER_ID；它不会为本地 iOS 构建配置直接 APNs 投递。

建议采用以下 Gateway 网关主机存储方式，与 ~/.openclaw/credentials/ 下其他提供商凭据的存储方式保持一致：

bash
mkdir -p ~/.openclaw/credentials/apnschmod 700 ~/.openclaw/credentials/apnsmv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8"

不要提交 .p8 文件，也不要将其放在仓库检出目录下。

设备发现路径

Bonjour（局域网）

iOS 应用会在 local. 上浏览 _openclaw-gw._tcp，并在配置后浏览同一广域 DNS-SD 设备发现域。同一局域网内的 Gateway 网关会通过 local. 自动显示；跨网络设备发现可以使用配置的广域域，而无需更改信标类型。

Tailnet（跨网络）

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

手动主机/端口

在设置中，启用手动主机并输入 Gateway 网关主机和端口（默认值为 18789）。

多个 Gateway 网关

应用会保存其已配对的每个 Gateway 网关的注册表，因此你无需重新配对即可在它们之间切换：

  • 设置 -> Gateway 网关会显示已配对的 Gateway 网关列表，并标记当前活动的 Gateway 网关。轻触条目即可切换；应用会断开当前会话并重新连接到所选 Gateway 网关。配对了多个 Gateway 网关时，连接行旁会显示快速切换菜单。
  • 凭据、TLS 信任决定、每个 Gateway 网关的偏好设置以及缓存的聊天记录均按 Gateway 网关分别存储。切换绝不会混用不同 Gateway 网关之间的状态，推送注册也会跟随当前活动的 Gateway 网关。
  • 轻扫已配对的 Gateway 网关（或使用其上下文菜单）以忘记它，这会移除其凭据、设备令牌、TLS 固定信息和缓存的聊天记录。
  • 若要切换到通过设备发现找到的 Gateway 网关，该 Gateway 网关必须在网络上可见；手动添加的 Gateway 网关会使用已保存的主机和端口重新连接。

Canvas + A2UI

iOS 节点会渲染 WKWebView 画布。使用 node.invoke 驱动它：

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

说明：

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

与计算机使用的关系

iOS 应用是移动节点界面，而不是 Codex Computer Use 后端。Codex Computer Use 和 cua-driver mcp 通过 MCP 工具控制本地 macOS 桌面；iOS 应用则通过 OpenClaw 节点命令公开 iPhone 能力，例如 canvas.*、camera.*、screen.*、location.* 和 talk.*。

智能体仍可通过调用节点命令，经由 OpenClaw 操作 iOS 应用，但这些调用会经过 Gateway 网关节点协议，并受 iOS 前台/后台限制。使用 Codex Computer Use 控制本地桌面；有关 iOS 节点能力，请参阅本页。

Canvas 求值/快照

bash
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\"; })()"}'
bash
openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'

语音唤醒 + Talk 模式

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

常见错误

  • NODE_BACKGROUND_UNAVAILABLE：将 iOS 应用切换到前台（画布/相机/屏幕命令要求应用位于前台）。
  • A2UI_HOST_UNAVAILABLE：应用 WebView 无法访问内置 A2UI 页面；让应用在屏幕标签页中保持前台运行，然后重试。
  • 配对提示始终不出现：运行 openclaw devices list 并手动批准。
  • Watch 未显示 iPhone 状态：确认 iPhone 在 watch.status 中报告 watchPaired: true 和 watchAppInstalled: true。如果配对状态为 false，请在 Apple 的 Watch 应用中配对 Watch。如果安装状态为 false，请从 My Watch -> Available Apps 安装配套应用。 进行任一更改后，在 Watch 上打开一次 OpenClaw；即时可访问仍要求两个应用都在运行， 而排队的更新可稍后在后台送达。
  • 重新安装后无法重新连接：钥匙串中的配对令牌已被清除；请重新配对节点。

相关文档

Was this useful?
On this page

On this page