Приложение iOS

Доступность: сборки приложения для 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:

openclaw gateway --port 18789

2. В приложении iOS откройте Settings и выберите обнаруженный Gateway (или включите Manual Host и введите хост/порт).

3. Одобрите запрос сопряжения на хосте 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 без запрошенных областей. Сопряжение оператора/браузера и любое изменение роли, области, метаданных или публичного ключа по-прежнему требуют ручного одобрения.

4. Проверьте подключение:

openclaw nodes statusopenclaw 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:

{  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:

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:

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 и не помещайте его в 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 для примера CoreDNS.

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

В Settings включите Manual Host и введите хост Gateway + порт (по умолчанию 18789).

Canvas + A2UI

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).
• 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 для управления локальным рабочим столом и эту страницу для возможностей iOS-узла.

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

Голосовое пробуждение + режим 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 был очищен; выполните повторное сопряжение узла.

Связанные документы

• Сопряжение
• Обнаружение
• Bonjour