Застосунок для iOS

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

Що він робить

• Підключається до Gateway через WebSocket (локальну мережу або tailnet).
• Надає можливості вузла: Canvas, знімок екрана, знімання камерою, геолокацію, режим розмови, активацію голосом і добровільно ввімкнені зведення про здоров’я.
• Отримує команди node.invoke та повідомляє про події стану вузла.
• Дає змогу лише для читання переглядати робочий простір вибраного агента в розділі «Агенти» («Файли»): переходити каталогами, переглядати текст із підсвічуванням синтаксису та зображення, а також експортувати через меню поширення. Операції запису недоступні; Gateway обмежує розмір попереднього перегляду.
• Зберігає невеликий локальний кеш лише для читання з нещодавніми сеансами чатів і журналами розмов для кожного спареного Gateway: під час холодного запуску негайно показує останній відомий журнал розмови й оновлює його після відповіді Gateway, нещодавні чати залишаються доступними для перегляду без підключення, а скидання або забуття очищає захищений локальний кеш.
• Ставить текстові повідомлення, надіслані без підключення, у стійку окрему для кожного Gateway вихідну чергу (до 50): бульбашки повідомлень із черги відображаються в журналі розмови, після повторного підключення надсилаються по черзі з ідемпотентними повторними спробами, зберігаються, доки канонічна історія не підтвердить надсилання, повторюються зі збільшенням затримки, перш ніж з’явиться дія повторення або видалення, і після 48 годин без підключення втрачають чинність замість надсилання; скидання або забуття очищає чергу разом із кешем.
• На вимогу озвучує повідомлення асистента: натисніть і утримуйте повідомлення в чаті та виберіть Listen. Застосунок відтворює підтримувані аудіофрагменти Gateway tts.speak за допомогою налаштованого постачальника TTS, а якщо аудіо Gateway недоступне або не відтворюється — використовує синтез мовлення на пристрої. Відтворення припиняється після перемикання сеансу або переходу застосунку у фоновий режим.

Вимоги

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

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

Під час першого запуску застосунок показує коротке пояснення спарювання та сторінку дозволів (сповіщення, камера, мікрофон, фотографії, контакти, календар, нагадування, геолокація). Усі дозволи необов’язкові, і їх можна змінити згодом у Settings -> Permissions або в застосунку «Параметри» iOS.

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

openclaw gateway --port 18789 --tailscale serve

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

2. Відкрийте інтерфейс керування, виберіть Nodes і натисніть Pair mobile device на сторінці Devices. Рекомендовано повний доступ, який вибрано за замовчуванням; вибирайте Limited access лише тоді, коли потрібно виключити адміністративні елементи керування Gateway, а потім натисніть Create setup code.

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

   Якщо код налаштування містить маршрути і локальної мережі, і Tailscale Serve, застосунок перевіряє їх по черзі та зберігає першу доступну кінцеву точку.

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

   У Settings → Gateway зазначено, чи збережене підключення оператора має Full або Limited доступ. Налаштування через незашифрований LAN ws:// автоматично отримує обмежений доступ для безпеки bearer-токена. Якщо доступ обмежено, налаштуйте wss:// або Tailscale Serve, відскануйте новий код повного доступу з інтерфейсу керування або openclaw qr, а потім підключіться повторно, щоб увімкнути налаштування та оновлення.

Для кнопки інтерфейсу керування потрібен уже спарений сеанс із operator.admin. Як резервний варіант у терміналі виберіть виявлений Gateway у застосунку iOS (або ввімкніть Manual Host і введіть хост та порт), а потім схваліть запит на хості 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 "{}"

Зведення про здоров’я

Вузол iOS може повертати добровільно ввімкнені агреговані дані HealthKit лише для читання за поточний календарний день. Згода на iPhone та явна авторизація команди Gateway — незалежні умови. Відомості про налаштування, виклик, поля корисного навантаження, конфіденційність і усунення несправностей див. у розділі Зведення HealthKit.

За замовчуванням супутній застосунок Apple Watch продовжує використовувати наявний ретранслятор iPhone і не потребує окремого спарювання з Gateway. Спарте годинник з iPhone у застосунку Apple Watch, установіть OpenClaw через Watch app -> My Watch -> Available Apps, а потім один раз відкрийте OpenClaw на обох пристроях.

Перевірка схвалень команд

Підключення оператора з operator.admin або спарене підключення operator.approvals, на яке явно націлено Gateway, може перевіряти запити виконання, що очікують на iPhone. Картка схвалення показує очищений Gateway попередній перегляд команди, попередження, контекст хоста, строк дії та лише рішення, передбачені цим запитом. Спарений Apple Watch отримує ту саму безпечну для перевірки підказку через наявний ретранслятор iPhone і пропонує компактний набір рішень «дозволити один раз» або «відхилити». Прямий режим Gateway на годиннику не передає підказок схвалення.

Стан схвалення спільний для інтерфейсу керування та підтримуваних чатів. Першою зараховується зафіксована відповідь. iPhone і годинник отримують канонічний термінальний запис Gateway після того, як запит вирішено в іншому інтерфейсі, після віддаленого сповіщення про вирішення та щоразу, коли підтвердження вирішення могло бути втрачено. Дії залишаються недоступними, доки це повторне читання не підтвердить, чи запит досі очікує.

Право на схвалення прив’язане до вибраного Gateway. Після перемикання Gateway стару підказку неможливо застосувати до нового підключення. Gateway, що передують уніфікованим методам схвалення, використовують як резервний варіант випущені методи, призначені для виконання; для збереженого термінального стану та розширених міжінтерфейсних результатів потрібен оновлений Gateway.

Необов’язковий прямий вузол Apple Watch

Прямий режим надає годиннику власну підписану ідентичність вузла та підключення до Gateway. Підтримувані команди вузла продовжують працювати через Wi-Fi або стільникову мережу годинника, доки OpenClaw активний, навіть якщо спарений iPhone недоступний.

Вимоги:

• iPhone підключено до Gateway з областю доступу operator.admin.
• Код налаштування оголошує кінцеву точку Gateway wss:// із сертифікатом, якому довіряє watchOS; годинник опитує відповідне джерело https://. Звичайний HTTP і довіра лише до самопідписаного сертифіката або відбитка не підтримуються. Налаштування кінцевої точки описано в розділі Спарювання, яким керує Gateway. Маршрути loopback, лише через iPhone та лише через tailnet не доступні годиннику незалежно.
• Для стільникового підключення потрібен Apple Watch із підтримкою стільникового зв’язку та активною послугою.
• OpenClaw активний на годиннику. Apple не дозволяє звичайним застосункам watchOS підтримувати універсальні з’єднання WebSocket/TCP, тому прямий вузол виконує короткі опитування HTTPS і повторно підключається, коли застосунок повертається на передній план. Див. настанови Apple щодо низькорівневої роботи з мережею у watchOS.

Налаштування:

1. На iPhone відкрийте Settings -> Apple Watch.
2. Натисніть Enable Direct Gateway Connection.
3. Відкрийте OpenClaw на годиннику до завершення строку дії короткочасного коду налаштування.
4. Перевірте окремий рядок Apple Watch за допомогою openclaw nodes status.

Код налаштування містить короткочасні початкові облікові дані лише для вузла; поводьтеся з ними як із паролем до завершення строку їх дії. Він ніколи не містить збереженого на iPhone пароля або токена Gateway. Після спарювання годинник зберігає власний токен пристрою та видаляє початкові облікові дані. Прямий режим охоплює лише наведені нижче команди. Чат, режим розмови, схвалення та наявний потік сповіщень watch.* залишаються функціями ретрансляції через iPhone і надалі потребують спареного iPhone.

Команди прямого вузла watchOS:

watchOS не надає WebKit стороннім застосункам, тому прямий вузол годинника не оголошує команди Canvas.

Ретрансльовані push-сповіщення для офіційних збірок

Офіційні розповсюджувані збірки iOS використовують зовнішній ретранслятор push-сповіщень замість публікації необробленого токена APNs у Gateway. Офіційні збірки App Store із загальнодоступного каналу випусків використовують розміщений ретранслятор за адресою https://ios-push-relay.openclaw.ai; ця базова URL-адреса жорстко задана для розповсюдження через App Store і не зчитує жодних перевизначень.

Для власних розгортань ретранслятора потрібен навмисно окремий шлях збирання та розгортання iOS, URL-адреса ретранслятора якого відповідає URL-адресі ретранслятора Gateway. Канал випусків App Store ніколи не приймає власну URL-адресу ретранслятора. Якщо використовується збірка з власним ретранслятором, задайте відповідну URL-адресу ретранслятора Gateway:

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

Як працює цей процес:

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

Що Gateway не потрібно для цього шляху: ані спільний для всього розгортання токен ретранслятора, ані прямий ключ APNs для офіційних надсилань через ретранслятор App Store.

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

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

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

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

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

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

• OPENCLAW_APNS_RELAY_BASE_URL усе ще працює як тимчасове перевизначення через змінну середовища для Gateway (gateway.push.apns.relay.baseUrl — основний шлях через конфігурацію).
• Режим push-сповіщень у релізній збірці App Store жорстко задає хост розміщеного ретранслятора й ніколи не зчитує перевизначення URL ретранслятора — змінна середовища часу збірки OPENCLAW_PUSH_RELAY_BASE_URL впливає лише на локальні/пісочні режими збірки iOS.

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

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

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

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

1. iOS app -> gateway: застосунок спарюється з Gateway через звичайний процес автентифікації Gateway, отримуючи автентифікований сеанс Node і автентифікований сеанс оператора. Сеанс оператора викликає gateway.identity.get.
2. iOS app -> relay: застосунок викликає кінцеві точки реєстрації ретранслятора через HTTPS із підтвердженням App Attest і JWS транзакції застосунку StoreKit. Ретранслятор перевіряє ідентифікатор пакета, підтвердження App Attest і підтвердження розповсюдження Apple та вимагає офіційного/виробничого шляху розповсюдження — саме це не дозволяє локальним збіркам Xcode/для розробки використовувати розміщений ретранслятор, оскільки локальна збірка не може надати офіційне підтвердження розповсюдження Apple.
3. gateway identity delegation: перед реєстрацією в ретрансляторі застосунок отримує ідентичність спареного Gateway з gateway.identity.get і включає її до реєстраційного навантаження ретранслятора. Ретранслятор повертає дескриптор ретранслятора та обмежений реєстрацією дозвіл на надсилання, делегований цій ідентичності Gateway.
4. gateway -> relay: Gateway зберігає дескриптор ретранслятора й дозвіл на надсилання з push.apns.register. Під час push.test, пробуджень для повторного підключення та спонукальних сигналів пробудження Gateway підписує запит на надсилання власною ідентичністю пристрою; ретранслятор перевіряє і збережений дозвіл на надсилання, і підпис Gateway відповідно до делегованої під час реєстрації ідентичності Gateway. Інший Gateway не може повторно використати цю збережену реєстрацію, навіть якщо якимось чином отримає дескриптор.
5. relay -> APNs: ретранслятор зберігає виробничі облікові дані APNs і необроблений токен APNs для офіційної збірки. Gateway ніколи не зберігає необроблений токен APNs для офіційних збірок із ретранслятором; ретранслятор надсилає остаточне push-сповіщення до APNs від імені спареного Gateway.

Мета цієї архітектури: не зберігати виробничі облікові дані APNs на користувацьких Gateway, уникнути зберігання необроблених токенів APNs офіційних збірок на Gateway, дозволити використання розміщеного ретранслятора лише офіційним збіркам OpenClaw для iOS і не допустити надсилання одним Gateway push-сповіщень пробудження на пристрої iOS, що належать іншому Gateway.

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

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

Рекомендоване місце зберігання на хості Gateway, узгоджене з іншими обліковими даними постачальників у ~/.openclaw/credentials/:

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

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

Bonjour (LAN)

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

Tailnet (між мережами)

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

Хост/порт вручну

У Settings увімкніть Manual Host і введіть хост та порт Gateway (типово 18789).

Кілька Gateway

Застосунок веде реєстр усіх Gateway, з якими його було спарено, тому між ними можна перемикатися без повторного спарювання:

• У Settings -> Gateway відображається список Paired Gateways, у якому позначено активний Gateway. Торкніться запису, щоб перемкнутися; застосунок завершує поточні сеанси та повторно підключається до вибраного Gateway. Коли спарено більше одного Gateway, поруч із рядком підключення з’являється меню швидкого перемикання.
• Облікові дані, рішення щодо довіри TLS, налаштування окремих Gateway і кешована історія чату зберігаються окремо для кожного Gateway. Під час перемикання стан різних Gateway ніколи не змішується, а реєстрація push-сповіщень відповідає активному Gateway.
• Проведіть по спареному Gateway (або скористайтеся його контекстним меню), щоб вибрати Forget; це видалить його облікові дані, токени пристрою, прив’язку TLS і кешовані чати.
• Для перемикання на виявлені Gateway вони мають бути доступні в мережі; Gateway, додані вручну, повторно підключаються за збереженими хостом і портом.

Canvas + A2UI

Node 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).
• Node iOS використовує вбудований каркас як типовий підключений вигляд. canvas.a2ui.push і canvas.a2ui.reset використовують вбудовану сторінку A2UI, що належить застосунку.
• Віддалені сторінки A2UI Gateway на iOS призначені лише для відтворення; нативні дії кнопок A2UI приймаються лише з вбудованих сторінок, що належать застосунку.
• Щоб повернутися до вбудованого каркаса, використовуйте canvas.navigate і {"url":""}.

Зв’язок із Computer Use

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

Агенти все одно можуть керувати застосунком iOS через OpenClaw, викликаючи команди Node, але ці виклики проходять через протокол Node Gateway і підпорядковуються обмеженням iOS для роботи на передньому та задньому плані. Для керування локальним робочим столом використовуйте Codex Computer Use, а можливості Node iOS описано на цій сторінці.

Обчислення / знімок Canvas

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

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

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

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

• NODE_BACKGROUND_UNAVAILABLE: переведіть застосунок iOS на передній план (це потрібно для команд Canvas, камери й екрана).
• A2UI_HOST_UNAVAILABLE: вбудована сторінка A2UI була недоступна у WebView застосунку; залиште застосунок на передньому плані на вкладці Screen і повторіть спробу.
• Запит на спарювання не з’являється: виконайте openclaw devices list і підтвердьте вручну.
• Watch не показує стан iPhone: переконайтеся, що iPhone повідомляє watchPaired: true і watchAppInstalled: true у watch.status. Якщо спарювання має значення false, спарте Watch у застосунку Watch від Apple. Якщо встановлення має значення false, установіть супутній застосунок із My Watch -> Available Apps. Після будь-якої з цих змін один раз відкрийте OpenClaw на Watch; для негайної доступності обидва застосунки все одно мають працювати, тоді як оновлення в черзі можуть надійти пізніше у фоновому режимі.
• Повторне підключення після перевстановлення не вдається: токен спарювання в Keychain було очищено; повторно спарте Node.

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

• Спарювання
• Виявлення
• Bonjour