Застосунок iOS

Доступність: збірки застосунку для iPhone розповсюджуються через канали Apple, коли це увімкнено для релізу. Локальні збірки для розробки також можна запускати з вихідного коду.

Що він робить

• Підключається до Gateway через WebSocket (LAN або tailnet).
• Надає можливості вузла: Canvas, знімок екрана, захоплення з камери, місцезнаходження, режим розмови, голосове пробудження.
• Отримує команди node.invoke і повідомляє події стану вузла.

Вимоги

• Gateway, запущений на іншому пристрої (macOS, Linux або Windows через WSL2).
• Мережевий шлях:
  • Та сама LAN через Bonjour, або
  • Tailnet через unicast DNS-SD (приклад домену: openclaw.internal.), або
  • Ручний хост/порт (резервний варіант).

Швидкий старт (спарювання + підключення)

1. Запустіть автентифікований Gateway з маршрутом, доступним для вашого телефона. Tailscale Serve є рекомендованим віддаленим шляхом:

openclaw gateway --port 18789 --tailscale serve

Для довіреного налаштування в тій самій LAN натомість використовуйте автентифікований gateway.bind: "lan". Прив’язка за замовчуванням до loopback недоступна з телефона. Якщо Gateway ще не налаштовано, спочатку виконайте openclaw onboard, щоб створення коду налаштування мало шлях автентифікації через токен або пароль.

2. Відкрийте інтерфейс керування, виберіть Вузли і натисніть Спарувати мобільний пристрій у картці Пристрої.

3. У застосунку iOS відкрийте Налаштування → Gateway, відскануйте QR-код (або вставте код налаштування) і підключіться.

4. Офіційний застосунок підключається автоматично. Якщо Пристрої показують запит, що очікує, перегляньте його роль і області доступу перед схваленням.

Кнопка в інтерфейсі керування потребує вже спарованого сеансу з operator.admin. Як резервний варіант у терміналі виберіть виявлений gateway у застосунку iOS (або увімкніть ручний хост і введіть хост/порт), потім схваліть запит на хості Gateway:

openclaw devices listopenclaw devices approve <requestId>

Якщо застосунок повторює спарювання зі зміненими даними автентифікації (роль/області доступу/публічний ключ), попередній запит, що очікує, замінюється і створюється новий requestId. Перед схваленням знову виконайте openclaw devices list.

Необов’язково: якщо вузол iOS завжди підключається з жорстко контрольованої підмережі, ви можете явно увімкнути автоматичне схвалення вузла під час першого підключення за допомогою CIDR або точних IP:

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

За замовчуванням це вимкнено. Це застосовується лише до нового спарювання з role: node без запитаних областей доступу. Спарювання оператора/браузера та будь-яка зміна ролі, області доступу, метаданих або публічного ключа все одно потребує ручного схвалення.

5. Перевірте підключення:

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

Push із підтримкою relay для офіційних збірок

Офіційно розповсюджувані збірки iOS використовують зовнішній push relay замість публікації сирого токена APNs на gateway.

Офіційні збірки App Store з публічної release-доріжки використовують розміщений relay на https://ios-push-relay.openclaw.ai.

Користувацькі розгортання relay потребують навмисно окремого шляху збірки/розгортання iOS, URL relay якого збігається з URL relay gateway. Публічна release-доріжка App Store не приймає перевизначення користувацького URL relay. Якщо ви використовуєте користувацьку збірку relay, задайте відповідний URL relay gateway:

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

Як працює потік:

• Застосунок iOS реєструється в relay за допомогою App Attest і JWS транзакції застосунку StoreKit.
• Relay повертає непрозорий handle relay і дозвіл надсилання, обмежений реєстрацією.
• Застосунок iOS отримує ідентичність спарованого gateway і включає її до реєстрації relay, тому реєстрація з підтримкою relay делегується саме цьому gateway.
• Застосунок пересилає цю реєстрацію з підтримкою relay до спарованого gateway через push.apns.register.
• Gateway використовує збережений handle relay для push.test, фонових пробуджень і поштовхів пробудження.
• Користувацькі URL relay gateway мають збігатися з URL relay, вбудованим у збірку iOS.
• Якщо застосунок пізніше підключається до іншого gateway або збірки з іншим базовим URL relay, він оновлює реєстрацію relay замість повторного використання старої прив’язки.

Що gateway не потребує для цього шляху:

• Немає relay-токена на рівні всього розгортання.
• Немає прямого ключа APNs для офіційних надсилань з App Store через relay.

Очікуваний потік оператора:

1. Встановіть офіційний застосунок iOS.
2. Необов’язково: задайте gateway.push.apns.relay.baseUrl на gateway лише під час використання навмисно окремої користувацької збірки relay.
3. Спаруйте застосунок із gateway і дозвольте йому завершити підключення.
4. Застосунок автоматично публікує push.apns.register після того, як має токен APNs, сеанс оператора підключено, а реєстрація relay успішна.
5. Після цього push.test, пробудження для повторного підключення і поштовхи пробудження можуть використовувати збережену реєстрацію з підтримкою relay.

Фонові сигнали активності

Коли iOS пробуджує застосунок через тихий push, фонове оновлення або подію значної зміни місцезнаходження, застосунок намагається коротко повторно підключити вузол, а потім викликає node.event з event: "node.presence.alive". Gateway записує це як lastSeenAtMs/lastSeenReason у метаданих спарованого вузла/пристрою лише після того, як відома ідентичність автентифікованого вузлового пристрою.

Застосунок вважає фонове пробудження успішно записаним лише тоді, коли відповідь gateway містить handled: true. Старіші gateway можуть підтверджувати node.event через { "ok": true }; така відповідь сумісна, але не рахується як довговічне оновлення last-seen.

Примітка щодо сумісності:

• OPENCLAW_APNS_RELAY_BASE_URL все ще працює як тимчасове перевизначення env для gateway.
• Публічна release-доріжка App Store відхиляє OPENCLAW_PUSH_RELAY_BASE_URL для збірок iOS.

Автентифікація і потік довіри

Relay існує, щоб забезпечити два обмеження, яких прямий APNs на gateway не може надати для офіційних збірок iOS:

• Лише справжні збірки OpenClaw iOS, розповсюджувані через Apple, можуть використовувати розміщений relay.
• Gateway може надсилати push через relay лише для пристроїв iOS, спарованих саме з цим gateway.

Крок за кроком:

1. iOS app -> gateway

   • Застосунок спочатку спаровується з gateway через звичайний потік автентифікації Gateway.
   • Це дає застосунку автентифікований сеанс вузла плюс автентифікований сеанс оператора.
   • Сеанс оператора використовується для виклику gateway.identity.get.

2. iOS app -> relay

   • Застосунок викликає кінцеві точки реєстрації relay через HTTPS.
   • Реєстрація містить доказ App Attest плюс JWS транзакції застосунку StoreKit.
   • Relay перевіряє bundle ID, доказ App Attest і доказ розповсюдження Apple, а також вимагає офіційний/production шлях розповсюдження.
   • Саме це блокує локальні збірки Xcode/dev від використання розміщеного relay. Локальна збірка може бути підписана, але вона не задовольняє офіційний доказ розповсюдження Apple, якого очікує relay.

3. gateway identity delegation

   • Перед реєстрацією relay застосунок отримує ідентичність спарованого gateway з gateway.identity.get.
   • Застосунок включає цю ідентичність gateway у payload реєстрації relay.
   • Relay повертає handle relay і дозвіл надсилання, обмежений реєстрацією, які делеговано цій ідентичності gateway.

4. gateway -> relay

   • Gateway зберігає handle relay і дозвіл надсилання з push.apns.register.
   • Під час push.test, пробуджень для повторного підключення і поштовхів пробудження gateway підписує запит надсилання своєю власною ідентичністю пристрою.
   • Relay перевіряє як збережений дозвіл надсилання, так і підпис gateway щодо делегованої ідентичності gateway з реєстрації.
   • Інший gateway не може повторно використати цю збережену реєстрацію, навіть якщо якимось чином отримає handle.

5. relay -> APNs

   • Relay володіє production-обліковими даними APNs і сирим токеном APNs для офіційної збірки.
   • Gateway ніколи не зберігає сирий токен APNs для офіційних збірок із підтримкою relay.
   • Relay надсилає фінальний push до APNs від імені спарованого gateway.

Чому було створено цей дизайн:

• Щоб не зберігати production-облікові дані APNs на gateway користувачів.
• Щоб уникнути зберігання сирих токенів APNs офіційних збірок на gateway.
• Щоб дозволити використання розміщеного relay лише для офіційних збірок OpenClaw iOS.
• Щоб запобігти надсиланню одним gateway push-пробуджень на пристрої iOS, що належать іншому gateway.

Локальні/ручні збірки залишаються на прямому APNs. Якщо ви тестуєте ці збірки без 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)"

Це runtime-змінні env хоста gateway, а не налаштування Fastlane. apps/ios/fastlane/.env зберігає лише автентифікацію App Store Connect, як-от APP_STORE_CONNECT_KEY_ID і APP_STORE_CONNECT_ISSUER_ID; він не налаштовує пряму доставку APNs для локальних збірок iOS.

Рекомендоване сховище на хості gateway:

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 і не розміщуйте його в checkout репозиторію.

Шляхи виявлення

Bonjour (LAN)

Застосунок iOS переглядає _openclaw-gw._tcp на local. і, якщо налаштовано, той самий домен виявлення wide-area DNS-SD. Gateway в тій самій LAN автоматично з’являються з local.; міжмережеве виявлення може використовувати налаштований wide-area домен без зміни типу beacon.

Tailnet (міжмережево)

Якщо mDNS заблоковано, використовуйте зону unicast DNS-SD (виберіть домен; приклад: openclaw.internal.) і Tailscale split DNS. Див. Bonjour для прикладу CoreDNS.

Ручний хост/порт

У налаштуваннях увімкніть Ручний хост і введіть хост gateway + порт (за замовчуванням 18789).

Canvas + A2UI

Вузол iOS рендерить canvas WKWebView. Використовуйте node.invoke, щоб керувати ним:

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

Примітки:

• Хост canvas Gateway обслуговує /__openclaw__/canvas/ і /__openclaw__/a2ui/.
• Він обслуговується з HTTP-сервера Gateway (той самий порт, що й gateway.port, за замовчуванням 18789).
• Вузол iOS зберігає вбудований scaffold як стандартний підключений вигляд. canvas.a2ui.push і canvas.a2ui.reset використовують bundled сторінку A2UI, що належить застосунку.
• Віддалені сторінки Gateway A2UI на iOS доступні лише для рендерингу; нативні дії кнопок A2UI приймаються лише зі bundled сторінок, що належать застосунку.
• Поверніться до вбудованого scaffold за допомогою canvas.navigate і {"url":""}.

Зв’язок із Computer Use

Застосунок iOS є поверхнею мобільного вузла, а не backend Codex Computer Use. Codex Computer Use і cua-driver mcp керують локальним desktop macOS через інструменти MCP; застосунок iOS надає можливості iPhone через команди вузла OpenClaw, такі як canvas.*, camera.*, screen.*, location.* і talk.*.

Агенти все одно можуть працювати із застосунком iOS через OpenClaw, викликаючи команди вузла, але ці виклики проходять через протокол вузла gateway і дотримуються обмежень iOS для foreground/background. Використовуйте Codex Computer Use для керування локальним desktop і цю сторінку для можливостей вузла iOS.

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

Голосове пробудження + режим розмови

• Голосове пробудження та режим розмови доступні в налаштуваннях.
• Розмова OpenAI у реальному часі використовує WebRTC, керований клієнтом, коли talk.realtime.transport має значення webrtc; явна конфігурація gateway-relay і далі належить Gateway. Див. режим розмови.
• Вузли iOS із підтримкою розмови оголошують можливість talk і можуть декларувати talk.ptt.start, talk.ptt.stop, talk.ptt.cancel і talk.ptt.once; Gateway за замовчуванням дозволяє ці команди «натисни й говори» для довірених вузлів із підтримкою розмови.
• iOS може призупиняти фоновий звук; вважайте голосові функції доступними на основі найкращих зусиль, коли застосунок не активний.

Поширені помилки

• NODE_BACKGROUND_UNAVAILABLE: виведіть застосунок iOS на передній план (для команд полотна/камери/екрана це обов’язково).
• A2UI_HOST_UNAVAILABLE: вбудована сторінка A2UI була недоступна у WebView застосунку; тримайте застосунок на передньому плані на вкладці «Екран» і повторіть спробу.
• Запит на сполучення не з’являється: виконайте openclaw devices list і схваліть вручну.
• Повторне підключення не вдається після перевстановлення: токен сполучення Keychain було очищено; повторно сполучіть вузол.

Пов’язані документи

• Сполучення
• Виявлення
• Bonjour