> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Застосунок 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 є рекомендованим віддаленим шляхом:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway --port 18789 --tailscale serve
```

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

2. Відкрийте [інтерфейс керування](/uk/web/control-ui), виберіть **Вузли** і натисніть
   **Спарувати мобільний пристрій** у картці **Пристрої**.

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw devices list
openclaw devices approve <requestId>
```

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
```

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/uk/gateway/bonjour) для прикладу CoreDNS.

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

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

## Canvas + A2UI

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/uk/plugins/codex-computer-use)
для керування локальним desktop і цю сторінку для можливостей вузла iOS.

### Canvas eval / snapshot

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'
```

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

* Голосове пробудження та режим розмови доступні в налаштуваннях.
* Розмова OpenAI у реальному часі використовує WebRTC, керований клієнтом, коли `talk.realtime.transport` має значення `webrtc`; явна конфігурація `gateway-relay` і далі належить Gateway. Див. [режим розмови](/uk/nodes/talk).
* Вузли 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 було очищено; повторно сполучіть вузол.

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

* [Сполучення](/uk/channels/pairing)
* [Виявлення](/uk/gateway/discovery)
* [Bonjour](/uk/gateway/bonjour)