​

iOS App (вузол)

​

Що він робить

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

​

Вимоги

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

​

Швидкий старт (pair + connect)

1. Запустіть Gateway:

openclaw gateway --port 18789

2. У застосунку iOS відкрийте Settings і виберіть знайдений gateway (або ввімкніть Manual Host і введіть host/port).
3. Схваліть запит pairing на хості шлюзу:

openclaw devices list
openclaw devices approve <requestId>

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

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

​

Push через relay для офіційних збірок

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

• iOS-застосунок реєструється в relay за допомогою App Attest і receipt застосунку.
• Relay повертає непрозорий relay handle разом із send grant, обмеженим областю реєстрації.
• iOS-застосунок отримує ідентичність pair-ованого gateway і включає її в реєстрацію relay, тож relay-backed реєстрація делегується саме цьому gateway.
• Застосунок передає цю relay-backed реєстрацію pair-ованому gateway через push.apns.register.
• Gateway використовує збережений relay handle для push.test, фонових пробуджень і wake nudges.
• Base URL relay шлюзу має збігатися з URL relay, вбудованим в офіційну/TestFlight збірку iOS.
• Якщо застосунок пізніше підключиться до іншого gateway або до збірки з іншим base URL relay, він оновить relay-реєстрацію замість повторного використання старої прив’язки.

• Жодного relay-токена для всього розгортання.
• Жодного прямого ключа APNs для relay-backed надсилання в офіційних/TestFlight збірках.

1. Встановіть офіційну/TestFlight збірку iOS.
2. Задайте gateway.push.apns.relay.baseUrl на шлюзі.
3. Pair-уйте застосунок зі шлюзом і дочекайтеся завершення підключення.
4. Застосунок автоматично публікує push.apns.register, щойно матиме токен APNs, сесію оператора буде підключено, а реєстрація relay завершиться успішно.
5. Після цього push.test, пробудження для перепідключення та wake nudges зможуть використовувати збережену relay-backed реєстрацію.

• OPENCLAW_APNS_RELAY_BASE_URL як і раніше працює як тимчасове перевизначення env для gateway.

​

Потік автентифікації та довіри

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

1. iOS app -> gateway
   • Спочатку застосунок виконує pairing зі шлюзом через звичайний потік автентифікації Gateway.
   • Це дає застосунку автентифіковану сесію вузла та автентифіковану сесію оператора.
   • Сесія оператора використовується для виклику gateway.identity.get.
2. iOS app -> relay
   • Застосунок викликає кінцеві точки реєстрації relay через HTTPS.
   • Реєстрація включає App Attest proof і receipt застосунку.
   • Relay перевіряє bundle ID, App Attest proof і Apple receipt та вимагає офіційний/production шлях розповсюдження.
   • Саме це блокує локальні Xcode/dev збірки від використання hosted relay. Локальна збірка може бути підписана, але вона не задовольняє вимогу офіційного підтвердження розповсюдження через Apple, яку очікує relay.
3. делегування ідентичності gateway
   • Перед реєстрацією relay застосунок отримує ідентичність pair-ованого gateway через gateway.identity.get.
   • Застосунок включає цю ідентичність gateway у payload реєстрації relay.
   • Relay повертає relay handle і send grant, обмежений областю реєстрації, делеговані цій ідентичності gateway.
4. gateway -> relay
   • Gateway зберігає relay handle і send grant з push.apns.register.
   • Для push.test, пробуджень перепідключення і wake nudges gateway підписує запит на надсилання власною ідентичністю пристрою.
   • Relay перевіряє і збережений send grant, і підпис gateway щодо делегованої ідентичності gateway з реєстрації.
   • Інший gateway не може повторно використати цю збережену реєстрацію, навіть якщо якимось чином отримає handle.
5. relay -> APNs
   • Relay володіє production-обліковими даними APNs і сирим токеном APNs для офіційної збірки.
   • Gateway ніколи не зберігає сирий токен APNs для relay-backed офіційних збірок.
   • Relay надсилає фінальний push до APNs від імені pair-ованого gateway.

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

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 (міжмережевий)

​

Ручний host/port

​

Canvas + A2UI

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

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

​

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

​

Voice wake + talk mode

• Voice wake і режим розмови доступні в Settings.
• iOS може призупиняти фонове аудіо; розглядайте голосові функції як best-effort, коли застосунок не активний.

​

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

• NODE_BACKGROUND_UNAVAILABLE: переведіть iOS-застосунок на передній план (команди canvas/camera/screen цього потребують).
• A2UI_HOST_NOT_CONFIGURED: Gateway не оголосив URL canvas host; перевірте canvasHost у конфігурації Gateway.
• Запит pairing ніколи не з’являється: виконайте openclaw devices list і схваліть його вручну.
• Повторне підключення не працює після перевстановлення: токен pairing у Keychain було очищено; виконайте pairing вузла знову.

​

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

• Pairing
• Discovery
• Bonjour