iOS 應用程式

​

功能

• 透過 WebSocket 連線至閘道（LAN 或 tailnet）。
• 暴露節點能力：畫布、螢幕快照、相機擷取、位置、對話模式、語音喚醒。
• 接收 node.invoke 命令並回報節點狀態事件。
• 從代理介面（檔案）以唯讀方式瀏覽所選代理的工作區：目錄逐層深入、具語法突顯的文字預覽、圖片預覽，以及分享表單匯出。沒有寫入操作；預覽大小由閘道限制。
• 依每個已配對閘道保留近期聊天工作階段和逐字稿的小型唯讀離線快取：冷啟動會立即繪製最後已知逐字稿，並在閘道回應後重新整理；中斷連線時仍可瀏覽近期聊天；重設/忘記會清除受保護的本機快取。
• 將中斷連線時傳送的文字訊息排入每個閘道的持久寄件匣（最多 50 則）：已排入佇列的氣泡會顯示在逐字稿中，重新連線時依序送出並以冪等方式重試，直到標準歷史確認傳送前都會保持持久，在顯示重試/刪除動作前會以退避方式重試，離線超過 48 小時後會過期而不是傳送；重設/忘記會連同快取清除佇列。
• 可依需求朗讀助理訊息：在聊天中長按訊息並選擇 聆聽。app 會使用已設定的 TTS 提供者播放支援的閘道 tts.speak 音訊片段，並在閘道音訊不可用或無法播放時退回到裝置端語音。切換工作階段或進入背景時會停止播放。

​

需求

• 在另一台裝置上執行的閘道（macOS、Linux，或透過 WSL2 的 Windows）。
• 網路路徑：
  • 透過 Bonjour 的相同 LAN，或
  • 透過單播 DNS-SD 的 tailnet（範例網域：openclaw.internal.），或
  • 手動主機/連接埠（備援）。

​

快速開始（配對 + 連線）

1. 啟動一個已驗證的閘道，並設定你的手機可連到的路由。Tailscale Serve 是建議的遠端路徑：

openclaw gateway --port 18789 --tailscale serve

2. 開啟控制介面，選取 節點，然後在 裝置 卡片中點擊 配對行動裝置。
3. 在 iOS app 中，開啟 設定 -> 閘道，掃描 QR code（或貼上 設定碼），然後連線。 如果設定碼同時包含 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 transaction JWS 向中繼註冊。
• 中繼會回傳不透明的中繼控制代碼，以及註冊範圍的傳送授權。
• iOS app 擷取已配對的閘道身分（gateway.identity.get），並在中繼註冊中包含它，因此中繼支援的註冊會委派給該特定閘道。
• app 會使用 push.apns.register 將該中繼支援的註冊轉送給已配對的閘道。
• 閘道會將儲存的中繼控制代碼用於 push.test、背景喚醒和喚醒提示。
• 如果 app 之後連線至不同閘道，或連線至使用不同中繼基底 URL 的組建，它會重新整理中繼註冊，而不是重複使用舊繫結。

1. 安裝官方 iOS app。
2. 選用：只有在使用刻意分離的自訂中繼組建時，才在閘道上設定 gateway.push.apns.relay.baseUrl。
3. 將 app 與閘道配對，並讓它完成連線。
4. app 會在取得 APNs 權杖、操作者工作階段已連線，且中繼註冊成功後，發布 push.apns.register。
5. 之後，push.test、重新連線喚醒和喚醒提示就可以使用已儲存的中繼支援註冊。

​

背景存活信標

• OPENCLAW_APNS_RELAY_BASE_URL 仍可作為閘道的暫時環境覆寫使用（gateway.push.apns.relay.baseUrl 是以設定優先的路徑）。
• App Store 發行組建的推播模式會硬編碼託管中繼主機，且永遠不讀取中繼 URL 覆寫 — OPENCLAW_PUSH_RELAY_BASE_URL 建置時環境變數只影響本機/沙盒 iOS 組建模式。

​

驗證與信任流程

• 只有透過 Apple 發布的真正 OpenClaw iOS 組建可以使用託管中繼。
• 閘道只能為與該特定閘道配對的 iOS 裝置傳送中繼支援推播。

1. iOS app -> gateway：app 透過一般閘道驗證流程與閘道配對，取得已驗證的節點工作階段以及已驗證的操作者工作階段。操作者工作階段會呼叫 gateway.identity.get。
2. iOS app -> relay：app 透過 HTTPS 呼叫中繼註冊端點，並附上 App Attest 證明及 StoreKit app transaction JWS。中繼會驗證 bundle ID、App Attest 證明和 Apple 發布證明，並要求官方/正式發布路徑 — 這就是阻止本機 Xcode/開發組建使用託管中繼的機制，因為本機組建無法滿足官方 Apple 發布證明。
3. gateway identity delegation：在中繼註冊前，app 會從 gateway.identity.get 擷取已配對的閘道身分，並將它包含在中繼註冊酬載中。中繼會回傳中繼控制代碼，以及委派給該閘道身分的註冊範圍傳送授權。
4. gateway -> relay：閘道會儲存來自 push.apns.register 的中繼控制代碼和傳送授權。在 push.test、重新連線喚醒和喚醒提示時，閘道會使用自己的裝置身分簽署傳送請求；中繼會依據註冊時委派的閘道身分，驗證已儲存的傳送授權和閘道簽章。即使另一個閘道以某種方式取得控制代碼，也無法重複使用該已儲存的註冊。
5. relay -> APNs：中繼擁有官方組建的正式 APNs 認證和原始 APNs 權杖。對於中繼支援的官方組建，閘道永遠不會儲存原始 APNs 權杖；中繼會代表已配對的閘道將最終推播傳送至 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（跨網路）

​

手動主機/連接埠

​

多個閘道

• 設定 -> 閘道 會顯示 已配對的閘道 清單，並標示作用中的閘道。點一下項目即可切換；App 會拆除目前的工作階段，並重新連線到選取的閘道。配對超過一個閘道時，連線列旁會出現快速切換選單。
• 憑證、TLS 信任決策、個別閘道偏好設定，以及快取的聊天記錄都會按閘道分開儲存。切換永遠不會混用不同閘道之間的狀態，推播註冊也會跟隨作用中的閘道。
• 滑動已配對的閘道（或使用其內容選單）即可 忘記 它，這會移除其憑證、裝置權杖、TLS 釘選，以及快取的聊天。
• 必須能在網路上看見已探索到的閘道，才能切換到它們；手動閘道會依已儲存的主機和連接埠重新連線。

​

Canvas + A2UI

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

• 閘道畫布主機會從閘道 HTTP 伺服器提供 /__openclaw__/canvas/ 和 /__openclaw__/a2ui/（與 gateway.port 相同連接埠，預設為 18789）。
• iOS 節點會保留內建支架作為已連線的預設檢視。canvas.a2ui.push 和 canvas.a2ui.reset 使用隨附、由 App 擁有的 A2UI 頁面。
• 遠端閘道 A2UI 頁面在 iOS 上僅供呈現；原生 A2UI 按鈕動作只接受來自隨附、由 App 擁有的頁面。
• 使用 canvas.navigate 和 {"url":""} 返回內建支架。

​

與 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.realtime.transport 為 webrtc 時，OpenAI 即時 Talk 會使用用戶端擁有的 WebRTC；明確的 gateway-relay 設定仍由閘道擁有。請參閱對話模式。
• 支援 Talk 的 iOS 節點會宣告 talk 功能，並可宣告 talk.ptt.start、talk.ptt.stop、talk.ptt.cancel 和 talk.ptt.once；閘道預設允許受信任、支援 Talk 的節點使用這些按住說話命令。
• iOS 可能會暫停背景音訊；當 App 未處於作用中狀態時，請將語音功能視為盡力而為。

​

常見錯誤

• NODE_BACKGROUND_UNAVAILABLE：將 iOS App 帶到前景（畫布/相機/螢幕命令需要如此）。
• A2UI_HOST_UNAVAILABLE：隨附的 A2UI 頁面無法在 App WebView 中連線；請讓 App 保持在前景並停留於螢幕分頁，然後重試。
• 配對提示從未出現：執行 openclaw devices list 並手動核准。
• Watch 未顯示 iPhone 狀態：確認 iPhone 在 watch.status 中回報 watchPaired: true 和 watchAppInstalled: true。如果配對為 false，請在 Apple 的 Watch App 中配對 Watch。如果安裝為 false，請從 我的手錶 -> 可用 App 安裝配套 App。完成任一變更後，在 Watch 上開啟一次 OpenClaw；即時可達性仍需要兩個 App 都在執行， 而排入佇列的更新可以稍後在背景抵達。
• 重新安裝後重新連線失敗：鑰匙圈配對權杖已清除；請重新配對節點。

​

相關文件

• 配對
• 探索
• Bonjour