Перейти до основного вмісту
Доступність: збірки застосунку для 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, щоб створення коду налаштування мало шлях автентифікації через токен або пароль.
  1. Відкрийте інтерфейс керування, виберіть Вузли і натисніть Спарувати мобільний пристрій у картці Пристрої.
  2. У застосунку iOS відкрийте Налаштування → Gateway, відскануйте QR-код (або вставте код налаштування) і підключіться.
  3. Офіційний застосунок підключається автоматично. Якщо Пристрої показують запит, що очікує, перегляньте його роль і області доступу перед схваленням.
Кнопка в інтерфейсі керування потребує вже спарованого сеансу з operator.admin. Як резервний варіант у терміналі виберіть виявлений gateway у застосунку iOS (або увімкніть ручний хост і введіть хост/порт), потім схваліть запит на хості Gateway: 
openclaw devices list
openclaw devices approve <requestId>
Якщо застосунок повторює спарювання зі зміненими даними автентифікації (роль/області доступу/публічний ключ), попередній запит, що очікує, замінюється і створюється новий requestId. Перед схваленням знову виконайте openclaw devices list. Необов’язково: якщо вузол iOS завжди підключається з жорстко контрольованої підмережі, ви можете явно увімкнути автоматичне схвалення вузла під час першого підключення за допомогою CIDR або точних IP: 
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
За замовчуванням це вимкнено. Це застосовується лише до нового спарювання з role: node без запитаних областей доступу. Спарювання оператора/браузера та будь-яка зміна ролі, області доступу, метаданих або публічного ключа все одно потребує ручного схвалення.
  1. Перевірте підключення:
openclaw nodes status
openclaw 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/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 і не розміщуйте його в 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 було очищено; повторно сполучіть вузол.

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