Приложение для iOS

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

Возможности

• Подключается к Gateway по WebSocket (через локальную сеть или tailnet).
• Предоставляет возможности Node: Canvas, снимок экрана, съёмка с камеры, геопозиция, режим разговора, голосовая активация и включаемые пользователем сводки Health.
• Получает команды node.invoke и сообщает события состояния Node.
• Позволяет просматривать в режиме только для чтения рабочее пространство выбранного агента в разделе «Агенты» (Файлы): переход по каталогам, предварительный просмотр текста с подсветкой синтаксиса, предварительный просмотр изображений и экспорт через меню «Поделиться». Операции записи отсутствуют; размер предварительного просмотра ограничивается 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. Настройка незашифрованного подключения по локальной сети ws:// автоматически ограничивается для безопасности bearer-токена. Если доступ ограничен, настройте wss:// или Tailscale Serve, отсканируйте новый код полного доступа из веб-интерфейса управления или openclaw qr, затем переподключитесь, чтобы включить настройки и обновления.

Для кнопки веб-интерфейса управления требуется уже сопряжённый сеанс с operator.admin. В качестве резервного варианта через терминал выберите обнаруженный Gateway в приложении iOS (или включите Manual Host и введите хост и порт), затем подтвердите запрос на хосте Gateway:

openclaw devices listopenclaw devices approve <requestId>

Если приложение повторяет сопряжение с изменёнными данными аутентификации (ролью, областями доступа или открытым ключом), предыдущий ожидающий запрос заменяется и создаётся новый requestId. Перед подтверждением снова выполните openclaw devices list.

Необязательно: если Node iOS всегда подключается из строго контролируемой подсети, можно включить автоматическое подтверждение первого сопряжения Node для явно заданных CIDR или точных IP-адресов:

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

По умолчанию эта функция отключена. Она применяется только к первичному сопряжению role: node без запрошенных областей доступа. Сопряжение оператора или браузера, а также любые изменения роли, области доступа, метаданных или открытого ключа по-прежнему требуют ручного подтверждения.

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

openclaw nodes statusopenclaw gateway call node.list --params "{}"

Сводки Health

Node 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.

Необязательный прямой Node Apple Watch

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

Требования:

• iPhone подключён к Gateway с областью доступа operator.admin.
• Код настройки объявляет конечную точку Gateway wss:// с сертификатом, которому доверяет watchOS; часы опрашивают соответствующий источник https://. Обычный HTTP, самоподписанное доверие или доверие только по отпечатку не поддерживаются. Сведения о настройке конечной точки см. в разделе Сопряжение под управлением Gateway. Маршруты loopback, доступные только с iPhone, и маршруты, доступные только через tailnet, недоступны часам напрямую.
• Для использования сотовой сети требуются Apple Watch с поддержкой сотовой связи и активным обслуживанием.
• OpenClaw активен на часах. Apple не разрешает обычным приложениям watchOS поддерживать универсальные подключения WebSocket/TCP, поэтому прямой Node использует короткие HTTPS- опросы и переподключается, когда приложение возвращается на передний план. См. рекомендации Apple по низкоуровневой работе с сетью в watchOS.

Настройка:

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

Код настройки содержит краткосрочные загрузочные учётные данные только для Node; обращайтесь с ними как с паролем до истечения срока действия. Он никогда не содержит сохранённый на iPhone пароль или токен Gateway. После сопряжения часы сохраняют собственный токен устройства и удаляют загрузочные учётные данные. Прямой режим охватывает только перечисленные ниже команды. Чат, режим разговора, подтверждения и существующий поток уведомлений watch.* остаются функциями ретрансляции через iPhone и по-прежнему требуют сопряжённого iPhone.

Прямые команды Node watchOS:

watchOS не предоставляет WebKit сторонним приложениям, поэтому прямой Node часов не объявляет команды 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 (локальная сеть)

Приложение iOS просматривает _openclaw-gw._tcp в local., а при соответствующей настройке — тот же домен глобального обнаружения DNS-SD. Gateway в той же локальной сети автоматически появляются из local.; для обнаружения между сетями можно использовать настроенный глобальный домен без изменения типа сигнала.

Tailnet (между сетями)

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

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

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

Несколько Gateway

Приложение ведёт реестр всех Gateway, с которыми оно было сопряжено, поэтому между ними можно переключаться без повторного сопряжения:

• В разделе Настройки -> Gateway отображается список Сопряжённые Gateway, в котором отмечен активный Gateway. Нажмите запись, чтобы переключиться; приложение завершит текущие сеансы и переподключится к выбранному Gateway. Если сопряжено несколько Gateway, рядом со строкой подключения отображается меню быстрого переключения.
• Учётные данные, решения о доверии TLS, настройки для каждого Gateway и кешированная история чатов хранятся отдельно для каждого Gateway. При переключении состояния разных Gateway никогда не смешиваются, а регистрация push-уведомлений следует за активным Gateway.
• Смахните сопряжённый Gateway (или воспользуйтесь его контекстным меню), чтобы Забыть его; при этом будут удалены его учётные данные, токены устройств, закрепление TLS и кешированные чаты.
• Для переключения на обнаруженные Gateway они должны быть видимы в сети; Gateway, добавленные вручную, переподключаются по сохранённым хосту и порту.

Canvas + A2UI

Node iOS отображает холст WKWebView. Для управления им используйте node.invoke:

openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__openclaw__/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 см. на этой странице.

Вычисление на холсте / снимок

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

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

• Голосовое пробуждение и режим разговора доступны в настройках.
• Разговор в реальном времени 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 на передний план (это требуется командам холста, камеры и экрана).
• A2UI_HOST_UNAVAILABLE: встроенная страница A2UI была недоступна в WebView приложения; оставьте приложение на переднем плане на вкладке «Экран» и повторите попытку.
• Запрос на сопряжение не появляется: выполните openclaw devices list и подтвердите сопряжение вручную.
• На Watch не отображается состояние iPhone: убедитесь, что iPhone сообщает watchPaired: true и watchAppInstalled: true в watch.status. Если сопряжение отсутствует, выполните сопряжение Watch в приложении Apple Watch. Если приложение не установлено, установите сопутствующее приложение через My Watch -> Available Apps. После любого из этих изменений один раз откройте OpenClaw на Watch; для немедленной доступности по-прежнему требуется, чтобы оба приложения были запущены, тогда как обновления из очереди могут поступить позднее в фоновом режиме.
• После переустановки не удаётся переподключиться: токен сопряжения в связке ключей был удалён; повторно сопрягите Node.

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

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