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

Сводка поддержки

• Роль: приложение вспомогательного узла (Android не размещает Gateway).
• Требуется Gateway: да (запустите его в macOS, Linux или Windows через WSL2).
• Установка: Google Play или OpenClaw-Android.apk из поддерживаемого выпуска GitHub, начало работы с Gateway, затем сопряжение.
• Gateway: руководство по эксплуатации + конфигурация.
  • Протоколы: протокол Gateway (узлы + плоскость управления).

Управление системой (launchd/systemd) выполняется на хосте Gateway — см. раздел Gateway.

Установка вне Google Play

Обычные финальные и корректирующие выпуски GitHub включают универсальные OpenClaw-Android.apk и OpenClaw-Android-SHA256SUMS.txt. APK собирается из тега выпуска, подписывается ключом выпуска OpenClaw для Android и содержит аттестацию происхождения GitHub Actions.

Выберите выпуск, в котором указаны оба ресурса, затем загрузите и проверьте этот точный тег перед установкой из стороннего источника:

release_tag=vYYYY.M.PATCHgh release download "$release_tag" \  --repo openclaw/openclaw \  --pattern OpenClaw-Android.apk \  --pattern OpenClaw-Android-SHA256SUMS.txtsha256sum --check OpenClaw-Android-SHA256SUMS.txtgh attestation verify OpenClaw-Android.apk \  --repo openclaw/openclaw \  --signer-workflow openclaw/openclaw/.github/workflows/android-release.yml \  --source-ref "refs/tags/${release_tag}" \  --deny-self-hosted-runners

Трансляция экрана Android и управление им с удалённого Mac

scrcpy отображает экран Android в окне macOS и передаёт ввод с клавиатуры и указателя через Android Debug Bridge (ADB). Это рабочий процесс на стороне оператора, не связанный с подключением узла OpenClaw. Он полезен, когда устройство Android и Mac находятся в разных местах, но используют общую частную сеть Tailscale.

Перед началом

• Установите Tailscale на устройство Android и Mac и подключите оба устройства к одной сети tailnet.

• На Android включите Developer options и USB debugging. В Android 16 пункт Wireless debugging находится в разделе Settings > System > Developer options. См. параметры разработчика Android.

• Установите scrcpy и ADB на Mac:

  brew install scrcpybrew install --cask android-platform-tools

• Обеспечьте доступность устройства Android при первом подключении. Android должен подтвердить ключ ADB каждого Mac, прежде чем этот Mac сможет управлять устройством.

Включение ADB через TCP

Для первоначальной настройки подключите устройство Android по USB к доверенному компьютеру и подтвердите запрос на отладку. Затем выполните:

adb devicesadb tcpip 5555

Теперь USB можно отключить. Если после перезагрузки устройства или сброса параметров отладки порт 5555 перестаёт прослушиваться, повторите этот этап локальной настройки. В Android 11 и более поздних версиях первоначальное доверие также можно установить с помощью Wireless debugging > Pair device with pairing code и adb pair.

Разрешение доступа только управляющему Mac

В сетях tailnet с ограничительными правилами необходимо явно разрешить управляющему Mac доступ к TCP-порту 5555 на устройстве Android. Добавьте узкое правило в политику tailnet, заменив адреса из примера стабильными IP-адресами Tailscale двух устройств:

{  grants: [    {      src: ["<remote-mac-tailnet-ip>"],      dst: ["<android-tailnet-ip>"],      ip: ["tcp:5555"],    },  ],}

Сведения о псевдонимах хостов и других селекторах см. в разделе правила предоставления доступа Tailscale. Не открывайте этот порт для общедоступного интернета и не предоставляйте к нему доступ через Funnel: авторизованный клиент ADB получает широкие возможности управления устройством.

Подключение и запуск трансляции экрана

На удалённом Mac:

adb connect <android-tailnet-ip>:5555adb devicesscrcpy --serial <android-tailnet-ip>:5555

Первый adb connect с этого Mac отображает диалог авторизации на Android. Разблокируйте устройство, подтвердите отпечаток ключа и выберите Always allow from this computer, только если Mac является доверенным. Успешная запись adb devices заканчивается на device; unauthorized означает, что запрос на устройстве не был подтверждён.

После открытия окна scrcpy используйте его напрямую или управляйте им с помощью инструмента автоматизации экрана macOS, например Peekaboo. scrcpy передаёт изображение и ввод; Tailscale предоставляет только частный сетевой маршрут.

Устранение неполадок

• Connection timed out: проверьте правило tailnet для TCP 5555. Успешный tailscale ping подтверждает доступность однорангового узла, но не разрешение этого TCP-порта политикой. Выполните проверку с помощью nc -vz <android-tailnet-ip> 5555 на Mac.
• unauthorized: разблокируйте Android и подтвердите ключ ADB удалённого Mac либо удалите устаревшую рабочую станцию в разделе Wireless debugging > Paired devices и выполните сопряжение заново.
• Connection refused: повторно подключитесь локально и снова выполните adb tcpip 5555.
• В списке несколько устройств: сохраняйте явный аргумент --serial <android-tailnet-ip>:5555.

По завершении закройте scrcpy и отключите ADB:

adb disconnect <android-tailnet-ip>:5555

Руководство по подключению

Приложение узла Android ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway

Android подключается непосредственно к WebSocket Gateway и использует сопряжение устройств (role: node).

Для Tailscale или общедоступных хостов Android требуется защищённая конечная точка:

• Предпочтительный вариант: Tailscale Serve / Funnel с https://<magicdns> / wss://<magicdns>
• Также поддерживается: любой другой URL-адрес Gateway wss:// с настоящей конечной точкой TLS
• Незашифрованный ws:// по-прежнему поддерживается для адресов частной локальной сети / хостов .local, а также localhost, 127.0.0.1 и моста эмулятора Android (10.0.2.2); при настройке соединения не через loopback автоматически используется ограниченный операторский доступ

Предварительные требования

• Gateway запущен на другом компьютере (или доступен через SSH).
• Устройство или эмулятор Android может подключиться к WebSocket Gateway:
  • в той же локальной сети с mDNS/NSD, или
  • в той же сети tailnet Tailscale с использованием Wide-Area Bonjour / одноадресного DNS-SD (см. ниже), или
  • с указанием хоста/порта Gateway вручную (резервный вариант)
• Для сопряжения мобильного устройства через tailnet или общедоступную сеть не используются конечные точки ws:// с необработанным IP-адресом tailnet. Вместо этого используйте Tailscale Serve или другой URL-адрес wss://.
• На компьютере Gateway (или через SSH) доступен CLI openclaw для подтверждения запросов на сопряжение.

1. Запустите Gateway

openclaw gateway --port 18789 --verbose

Убедитесь, что в журналах присутствует примерно следующая запись:

• listening on ws://0.0.0.0:18789

Для удалённого доступа Android через Tailscale вместо привязки к необработанному адресу tailnet предпочтительно использовать Serve/Funnel:

openclaw gateway --tailscale serve

Так Android получает защищённую конечную точку wss:// / https://. Обычной настройки gateway.bind: "tailnet" недостаточно для первоначального удалённого сопряжения Android, если TLS не завершается отдельно.

2. Проверьте обнаружение (необязательно)

На компьютере Gateway:

dns-sd -B _openclaw-gw._tcp local.

Дополнительные сведения об отладке: Bonjour.

Если вы также настроили домен обнаружения для глобальной сети, сравните результаты с:

openclaw gateway discover --json

Команда за один проход отображает local. и настроенный домен глобальной сети, используя разрешённую конечную точку службы вместо одних лишь подсказок TXT.

Межсетевое обнаружение через одноадресный DNS-SD

Обнаружение Android через NSD/mDNS не работает между сетями. Если узел Android и Gateway находятся в разных сетях, но соединены через Tailscale, используйте Wide-Area Bonjour / одноадресный DNS-SD. Одного обнаружения недостаточно для сопряжения Android через tailnet или общедоступную сеть — обнаруженному маршруту всё равно требуется защищённая конечная точка (wss:// или Tailscale Serve):

1. Настройте зону DNS-SD (например, openclaw.internal.) на хосте Gateway и опубликуйте записи _openclaw-gw._tcp.
2. Настройте раздельный DNS Tailscale для выбранного домена, указав этот DNS-сервер.

Подробности и пример конфигурации CoreDNS: Bonjour.

3. Подключитесь с Android

В приложении Android:

• Приложение поддерживает подключение к Gateway с помощью службы переднего плана (постоянное уведомление).
• Откройте вкладку Подключение.
• Используйте режим Код настройки или Вручную.
• Если обнаружение заблокировано, укажите хост/порт вручную в разделе Расширенные элементы управления. Для хостов в частной локальной сети по-прежнему работает ws://. Для хостов Tailscale или общедоступных хостов включите TLS и используйте конечную точку wss:// / Tailscale Serve.

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

Официальные коды настройки подключают Android как узел и по умолчанию предоставляют полный операторский доступ к Gateway через wss://. При настройке незашифрованного соединения ws:// не через loopback автоматически используется ограниченный доступ для защиты токена предъявителя. Раздел Настройки → Gateway показывает уровень доступа Полный или Ограниченный. Для ограниченного подключения настройте wss:// или Tailscale Serve, создайте новый код полного доступа в Control UI или с помощью openclaw qr, затем отсканируйте либо вставьте его на этой странице и повторно подключитесь. Операторы, которым нужен сокращённый профиль, могут выбрать Ограниченный доступ в Control UI или выполнить openclaw qr --limited.

Несколько Gateway

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

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

Сигналы активности присутствия

После подключения аутентифицированного сеанса узла, а также когда приложение переходит в фоновый режим при всё ещё подключённой службе переднего плана, Android вызывает node.event с event: "node.presence.alive". Gateway записывает это как lastSeenAtMs/lastSeenReason в метаданных сопряжённого узла/устройства только после определения идентификатора аутентифицированного устройства узла.

Приложение считает сигнал успешно записанным только в том случае, если ответ Gateway содержит handled: true. Более старые Gateway могут подтверждать node.event с помощью { "ok": true }; такой ответ совместим, но не считается постоянным обновлением времени последней активности.

4. Подтвердите сопряжение (CLI)

На компьютере Gateway:

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

Подробнее о сопряжении: Сопряжение.

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

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

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

5. Проверка подключения узла

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

6. Чат и история

Вкладка чата Android поддерживает выбор сеанса (по умолчанию main, а также другие существующие сеансы):

• История: chat.history (нормализована для отображения — удаляются встроенные теги директив, XML-данные вызовов инструментов в виде обычного текста (<tool_call>, <function_call>, <tool_calls>, <function_calls> и усечённые варианты), а также просочившиеся управляющие токены модели в ASCII или полноширинном написании; строки ассистента, содержащие только служебные токены, например точные NO_REPLY / no_reply, не отображаются; слишком большие строки могут заменяться заполнителями)
• Отправка: chat.send
• Надёжная отправка: каждая отправка (текст, выбранные изображения и голосовые сообщения) до любой попытки сетевой передачи записывается в локальную исходящую очередь для соответствующего Gateway, поэтому завершение приложения не приводит к потере отправленных данных. Сообщения, поставленные в очередь без подключения, после его восстановления доставляются по порядку со стабильными ключами идемпотентности, а отправка удаляется из очереди только после появления хода в каноническом chat.history — одно лишь подтверждение не считается доказательством доставки. Неоднозначные результаты (утрата подтверждения, завершение приложения во время отправки, перезапуск Gateway до записи расшифровки) отображаются как видимые строки с явными действиями Повторить/Удалить вместо автоматической повторной отправки. Команды с косой чертой никогда не воспроизводятся автоматически после восстановления подключения; они ожидают явного повторного запуска. Размер очереди ограничен (50 сообщений и 48 МБ данных вложений на каждый Gateway), а неотправленные строки удаляются через 48 часов. Черновики в поле ввода, которые не были отправлены, не сохраняются после завершения процесса.
• Push-обновления (по возможности): chat.subscribe -> event:"chat"
• Прослушивание: нажмите и удерживайте сообщение ассистента, затем выберите Прослушать; аудио формируется через tts.speak Gateway с использованием настроенной цепочки поставщиков TTS, а если Gateway не может сформировать аудио, используется системный TTS устройства. Воспроизведение прекращается при переключении сеанса, создании нового чата, переходе приложения в фоновый режим или закрытии чата.

7. Холст и камера

Хост холста Gateway (рекомендуется для веб-содержимого)

Чтобы узел отображал настоящий HTML/CSS/JS, который агент может редактировать на диске, направьте узел на хост холста Gateway.

1. Создайте ~/.openclaw/workspace/canvas/index.html на хосте Gateway.
2. Перейдите к нему на узле (через локальную сеть):

openclaw nodes invoke --node "&lt;Android Node&gt;" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'

Tailnet (необязательно): если оба устройства подключены к Tailscale, используйте имя MagicDNS или IP-адрес tailnet вместо .local, например http://<gateway-magicdns>:18789/__openclaw__/canvas/.

Этот сервер внедряет в HTML клиент автоматической перезагрузки и перезагружает страницу при изменении файлов. Gateway также обслуживает /__openclaw__/a2ui/, однако приложение Android рассматривает удалённые страницы A2UI только как доступные для отображения. Команды A2UI с поддержкой действий используют встроенную страницу A2UI, принадлежащую приложению.

Команды холста (только на переднем плане):

• canvas.eval, canvas.snapshot, canvas.navigate (для возврата к стандартному каркасу используйте {"url":""} или {"url":"/"}). canvas.snapshot возвращает { format, base64 } (по умолчанию format="jpeg").
• A2UI: canvas.a2ui.push, canvas.a2ui.reset (устаревший псевдоним canvas.a2ui.pushJSONL). Для отображения с поддержкой действий они используют встроенную страницу A2UI, принадлежащую приложению.

Команды камеры (только на переднем плане; требуют разрешения): camera.snap (jpg), camera.clip (mp4). Параметры и вспомогательные команды CLI описаны в разделе Узел камеры.

8. Голос и расширенный набор команд Android

• Вкладка голосового ввода: в Android предусмотрены два явных режима записи. Микрофон — это ручной сеанс на вкладке голосового ввода, который отправляет каждую паузу как ход чата и прекращается, когда приложение уходит с переднего плана или пользователь покидает вкладку голосового ввода. Разговор — это непрерывный режим разговора, который продолжает прослушивание, пока не будет отключён или пока узел не отсоединится.
• Перед началом записи режим разговора повышает уровень существующей фоновой службы с connectedDevice до connectedDevice|microphone, а после остановки режима разговора понижает его обратно. Служба узла объявляет FOREGROUND_SERVICE_CONNECTED_DEVICE с CHANGE_NETWORK_STATE; Android 14+ также требует объявления FOREGROUND_SERVICE_MICROPHONE, предоставления разрешения RECORD_AUDIO во время выполнения и типа службы микрофона во время выполнения.
• По умолчанию режим разговора Android использует встроенное распознавание речи, чат Gateway и talk.speak через настроенного поставщика режима разговора Gateway. Локальный системный TTS используется только тогда, когда talk.speak недоступен.
• Режим разговора Android использует ретрансляцию Gateway в реальном времени, только если talk.realtime.mode имеет значение realtime, а talk.realtime.transport — значение gateway-relay.
• Android не заявляет возможность voiceWake. Для голосового ввода используйте Микрофон или Разговор.
• Дополнительные семейства команд Android (доступность зависит от устройства, разрешений и настроек пользователя):
  • device.status, device.info, device.permissions, device.health
  • device.apps доступна только при включённом параметре Настройки > Возможности телефона > Установленные приложения; по умолчанию она перечисляет приложения, отображаемые в средстве запуска (передайте includeNonLaunchable, чтобы получить полный список).
  • notifications.list, notifications.actions (см. раздел Пересылка уведомлений ниже)
  • photos.latest
  • contacts.search, contacts.add
  • calendar.events, calendar.add
  • callLog.search
  • sms.search
  • motion.activity, motion.pedometer

9. Файлы рабочего пространства (только для чтения)

На главном экране обзора есть карточка Файлы, которая позволяет просматривать рабочее пространство активного агента через RPC Gateway agents.workspace.list / agents.workspace.get, доступные только для чтения: переходить по каталогам, предварительно просматривать текст и изображения, а также экспортировать файлы через системное меню общего доступа Android. Операции записи отсутствуют, а размер предварительного просмотра ограничивается Gateway.

Проверка одобрений команд

Подключение оператора с operator.admin или сопряжённое подключение operator.approvals, явно назначенное Gateway, может проверять ожидающие запросы выполнения в разделе Настройки -> Одобрения. Прежде чем активировать кнопки, приложение загружает очищенную запись одобрения из Gateway, отображает все предупреждения системы безопасности и точный набор решений, предлагаемых запросом, а затем отправляет идентификатор одобрения и тип владельца обратно в Gateway.

Состояние одобрения совместно используется Control UI и поддерживаемыми интерфейсами чата. Принимается первый зафиксированный ответ; Android отображает этот канонический результат, даже если первым ответил другой интерфейс. Если ответ о разрешении потерян или Gateway отключается, приложение оставляет действие заблокированным и повторно считывает одобрение, прежде чем предложить принять другое решение.

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

Точки входа ассистента

Android поддерживает запуск OpenClaw с помощью системного средства вызова ассистента (Google Assistant). Удерживание кнопки главного экрана (или использование другого средства вызова ACTION_ASSIST) открывает приложение; фраза «Hey Google, ask OpenClaw <prompt>» соответствует шаблону запроса App Actions, объявленному приложением, и передаёт запрос в поле ввода чата, не отправляя его автоматически.

Для этого используются Android App Actions (возможность shortcuts.xml), объявленные в манифесте приложения. Настройка на стороне Gateway не требуется — намерение ассистента полностью обрабатывается приложением Android.

Пересылка уведомлений

Android может пересылать уведомления устройства в Gateway как элементы node.event. Эта функция настраивается на устройстве, на странице настроек приложения, а не в конфигурации Gateway/openclaw.json.

Уведомления WhatsApp, WhatsApp Business, Telegram, Telegram X, Discord и Signal всегда исключаются. Их сообщения уже относятся к собственным сеансам каналов OpenClaw; пересылка уведомления Android как отдельного события узла может направить ответ не в тот разговор.

Связанные разделы

• Приложение iOS
• Узлы
• Устранение неполадок узла Android