---
read_when:
    - Сполучення або повторне підключення вузла iOS
    - Запуск iOS-застосунку з вихідного коду
    - Налагодження виявлення Gateway або команд полотна
summary: 'Застосунок вузла iOS: підключення до Gateway, створення пари, полотно та усунення несправностей'
title: Застосунок iOS
x-i18n:
    generated_at: "2026-07-04T18:18:52Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: ad6d272518b36564562256f55ffc320c0c4d2b954914ac73c23e450fa7acee0b
    source_path: platforms/ios.md
    workflow: 16
---

Доступність: збірки застосунку для 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
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
openclaw devices list
openclaw devices approve <requestId>
```

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

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

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

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

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

```bash
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
{
  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
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
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
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
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
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)