--- read_when: - Сопряжение или повторное подключение узла iOS - Запуск приложения iOS из исходного кода - Отладка обнаружения Gateway или команд холста summary: 'Приложение узла iOS: подключение к Gateway, сопряжение, холст и устранение неполадок' title: Приложение iOS x-i18n: generated_at: "2026-06-28T23:11:21Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 1a93381fd2b95316e05a555bee45b9aed5572679b4b1f10f7f9e40c1a69faf17 source_path: platforms/ios.md workflow: 16 --- Доступность: сборки приложения для iPhone распространяются через каналы Apple, когда они включены для релиза. Локальные сборки для разработки также можно запускать из исходного кода. ## Что оно делает - Подключается к Gateway через WebSocket (LAN или tailnet). - Предоставляет возможности узла: Canvas, снимок экрана, захват с камеры, местоположение, режим Talk, голосовое пробуждение. - Получает команды `node.invoke` и сообщает события статуса узла. ## Требования - Gateway, запущенный на другом устройстве (macOS, Linux или Windows через WSL2). - Сетевой путь: - Та же LAN через Bonjour, **или** - Tailnet через unicast DNS-SD (пример домена: `openclaw.internal.`), **или** - Ручной хост/порт (резервный вариант). ## Быстрый старт (сопряжение + подключение) 1. Запустите Gateway: ```bash openclaw gateway --port 18789 ``` 2. В приложении iOS откройте Settings и выберите обнаруженный Gateway (или включите Manual Host и введите хост/порт). 3. Одобрите запрос сопряжения на хосте Gateway: ```bash openclaw devices list openclaw devices approve ``` Если приложение повторяет сопряжение с измененными данными аутентификации (роль/области/публичный ключ), предыдущий ожидающий запрос заменяется и создается новый `requestId`. Перед одобрением снова выполните `openclaw devices list`. Необязательно: если iOS-узел всегда подключается из строго контролируемой подсети, вы можете включить автоматическое одобрение узла при первом подключении с явными CIDR или точными IP: ```json5 { gateway: { nodes: { pairing: { autoApproveCidrs: ["192.168.1.0/24"], }, }, }, } ``` По умолчанию это отключено. Это применяется только к новому сопряжению `role: node` без запрошенных областей. Сопряжение оператора/браузера и любое изменение роли, области, метаданных или публичного ключа по-прежнему требуют ручного одобрения. 4. Проверьте подключение: ```bash openclaw nodes status openclaw gateway call node.list --params "{}" ``` ## Push через relay для официальных сборок Официально распространяемые сборки iOS используют внешний push relay вместо публикации необработанного токена APNs в Gateway. Официальные/TestFlight-сборки из публичной ветки релиза App Store используют размещенный relay по адресу `https://ios-push-relay.openclaw.ai`. Пользовательские развертывания relay требуют намеренно отдельного пути сборки/развертывания iOS, URL relay которого совпадает с URL relay Gateway. Публичная ветка релиза 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 возвращает непрозрачный дескриптор relay и разрешение на отправку, привязанное к регистрации. - Приложение iOS получает идентичность сопряженного Gateway и включает ее в регистрацию relay, поэтому регистрация через relay делегируется этому конкретному Gateway. - Приложение пересылает эту регистрацию через relay сопряженному Gateway с помощью `push.apns.register`. - Gateway использует сохраненный дескриптор relay для `push.test`, фоновых пробуждений и мягких сигналов пробуждения. - Пользовательские URL relay Gateway должны совпадать с URL relay, встроенным в сборку iOS. - Если приложение позже подключается к другому Gateway или к сборке с другим базовым URL relay, оно обновляет регистрацию relay вместо повторного использования старой привязки. Что Gateway **не** нужно для этого пути: - Нет токена relay на все развертывание. - Нет прямого ключа APNs для официальных/TestFlight отправок через relay. Ожидаемый поток оператора: 1. Установите официальную/TestFlight-сборку iOS. 2. Необязательно: задайте `gateway.push.apns.relay.baseUrl` на Gateway только при использовании намеренно отдельной пользовательской сборки relay. 3. Сопрягите приложение с Gateway и дождитесь завершения подключения. 4. Приложение автоматически публикует `push.apns.register` после того, как у него есть токен APNs, сеанс оператора подключен, а регистрация relay успешна. 5. После этого `push.test`, пробуждения для переподключения и мягкие сигналы пробуждения могут использовать сохраненную регистрацию через relay. ## Фоновые сигналы alive Когда iOS пробуждает приложение для silent 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. - Публичная ветка релиза 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, а также требует официальный/производственный путь распространения. - Именно это блокирует локальные сборки Xcode/dev от использования размещенного relay. Локальная сборка может быть подписана, но она не удовлетворяет доказательству официального распространения Apple, которое ожидает relay. 3. `gateway identity delegation` - Перед регистрацией relay приложение получает идентичность сопряженного Gateway из `gateway.identity.get`. - Приложение включает эту идентичность Gateway в полезную нагрузку регистрации relay. - Relay возвращает дескриптор relay и разрешение на отправку, привязанное к регистрации, которые делегированы этой идентичности Gateway. 4. `gateway -> relay` - Gateway сохраняет дескриптор relay и разрешение на отправку из `push.apns.register`. - При `push.test`, пробуждениях для переподключения и мягких сигналах пробуждения Gateway подписывает запрос отправки своей собственной идентичностью устройства. - Relay проверяет и сохраненное разрешение на отправку, и подпись Gateway относительно делегированной идентичности Gateway из регистрации. - Другой Gateway не может повторно использовать эту сохраненную регистрацию, даже если каким-то образом получит дескриптор. 5. `relay -> APNs` - Relay владеет production-учетными данными APNs и необработанным токеном APNs для официальной сборки. - Gateway никогда не сохраняет необработанный токен APNs для официальных сборок с relay. - Relay отправляет финальный push в APNs от имени сопряженного Gateway. Зачем был создан этот дизайн: - Чтобы не хранить production-учетные данные APNs на пользовательских Gateway. - Чтобы избежать хранения необработанных токенов APNs официальных сборок на Gateway. - Чтобы разрешить использование размещенного relay только для официальных/TestFlight-сборок OpenClaw. - Чтобы не позволить одному 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 vars хоста Gateway, а не настройки Fastlane. `apps/ios/fastlane/.env` хранит только аутентификацию App Store Connect / TestFlight, такую как `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.` и, когда настроено, тот же домен широкозонного обнаружения DNS-SD. Gateway в той же LAN автоматически появляются из `local.`; обнаружение между сетями может использовать настроенный широкозонный домен без изменения типа beacon. ### Tailnet (между сетями) Если mDNS заблокирован, используйте зону unicast DNS-SD (выберите домен; пример: `openclaw.internal.`) и split DNS Tailscale. См. [Bonjour](/ru/gateway/bonjour) для примера CoreDNS. ### Ручной хост/порт В Settings включите **Manual Host** и введите хост Gateway + порт (по умолчанию `18789`). ## Canvas + A2UI iOS-узел отображает canvas WKWebView. Используйте `node.invoke`, чтобы управлять им: ```bash openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://:18789/__openclaw__/canvas/"}' ``` Примечания: - Хост canvas Gateway обслуживает `/__openclaw__/canvas/` и `/__openclaw__/a2ui/`. - Он обслуживается HTTP-сервером Gateway (тот же порт, что и `gateway.port`, по умолчанию `18789`). - iOS-узел сохраняет встроенный scaffold как подключенный вид по умолчанию. `canvas.a2ui.push` и `canvas.a2ui.reset` используют встроенную страницу A2UI, принадлежащую приложению. - Удаленные страницы A2UI Gateway на iOS работают только для отображения; нативные действия кнопок A2UI принимаются только со встроенных страниц, принадлежащих приложению. - Вернитесь к встроенному scaffold с помощью `canvas.navigate` и `{"url":""}`. ## Связь с Computer Use Приложение iOS — это мобильная поверхность узла, а не backend Codex Computer Use. Codex Computer Use и `cua-driver mcp` управляют локальным рабочим столом macOS через инструменты MCP; приложение iOS предоставляет возможности iPhone через команды узла OpenClaw, такие как `canvas.*`, `camera.*`, `screen.*`, `location.*` и `talk.*`. Агенты по-прежнему могут работать с приложением iOS через OpenClaw, вызывая команды узла, но эти вызовы проходят через протокол узла Gateway и следуют ограничениям iOS для foreground/background. Используйте [Codex Computer Use](/ru/plugins/codex-computer-use) для управления локальным рабочим столом и эту страницу для возможностей 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"}' ``` ## Голосовое пробуждение + режим Talk - Голосовое пробуждение и режим Talk доступны в Settings. - iOS-узлы с поддержкой Talk объявляют возможность `talk` и могут объявлять `talk.ptt.start`, `talk.ptt.stop`, `talk.ptt.cancel` и `talk.ptt.once`; Gateway по умолчанию разрешает эти команды push-to-talk для доверенных узлов с поддержкой Talk. - iOS может приостанавливать фоновый звук; считайте голосовые функции best-effort, когда приложение не активно. ## Распространенные ошибки - `NODE_BACKGROUND_UNAVAILABLE`: выведите приложение iOS на передний план (команды canvas/camera/screen требуют этого). - `A2UI_HOST_UNAVAILABLE`: встроенная страница A2UI была недоступна в WebView приложения; держите приложение на переднем плане на вкладке Screen и повторите попытку. - Запрос сопряжения никогда не появляется: выполните `openclaw devices list` и одобрите вручную. - Переподключение не удается после переустановки: токен сопряжения Keychain был очищен; выполните повторное сопряжение узла. ## Связанные документы - [Сопряжение](/ru/channels/pairing) - [Обнаружение](/ru/gateway/discovery) - [Bonjour](/ru/gateway/bonjour)