OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Platforms overview

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

Стан підтримки

Системне керування (launchd/systemd) виконується на хості Gateway — див. Gateway.

Встановлення поза Google Play

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

Виберіть випуск, у якому перелічено обидва ресурси, потім завантажте й перевірте саме цей тег перед установленням зі стороннього джерела:

bash
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). Це робочий процес на боці оператора, окремий від підключення Node 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:

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

  • Забезпечте доступність пристрою Android під час першого підключення. Android має схвалити ключ ADB кожного Mac, перш ніж цей Mac зможе керувати пристроєм.

Увімкнення ADB через TCP

Для початкового налаштування підключіть пристрій Android через USB до надійного комп’ютера та схваліть запит на налагодження. Потім виконайте:

bash
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 цих двох пристроїв:

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

Відомості про псевдоніми хостів та інші селектори див. у документації дозволів Tailscale. Не надавайте доступ до цього порту з публічного інтернету та не відкривайте його через Funnel: авторизований клієнт ADB має широкі можливості керування пристроєм.

Підключення та запуск віддзеркалення

На віддаленому Mac:

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

bash
adb disconnect <android-tailnet-ip>:5555

Інструкція з підключення

Застосунок Node для Android ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway

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

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

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

Передумови

  • Gateway запущено на іншому комп’ютері (або він доступний через SSH).
  • Пристрій або емулятор Android може підключитися до WebSocket Gateway:
    • Та сама LAN із mDNS/NSD, або
    • Та сама tailnet Tailscale із Wide-Area Bonjour / одноадресним DNS-SD (див. нижче), або
    • Хост/порт Gateway указано вручну (резервний варіант)
  • Сполучення мобільного пристрою через tailnet або публічну мережу не використовує необроблені кінцеві точки IP-адрес tailnet ws://. Натомість використовуйте Tailscale Serve або іншу URL-адресу wss://.
  • CLI openclaw доступний на комп’ютері Gateway (або через SSH) для схвалення запитів на сполучення.

1. Запуск Gateway

bash
openclaw gateway --port 18789 --verbose

Переконайтеся, що в журналах є щось подібне:

  • listening on ws://0.0.0.0:18789

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

bash
openclaw gateway --tailscale serve

Це надає Android захищену кінцеву точку wss:// / https://. Простого налаштування gateway.bind: "tailnet" недостатньо для першого віддаленого сполучення Android, якщо TLS не завершується окремо.

2. Перевірка виявлення (необов’язково)

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

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

Докладніші примітки щодо налагодження: Bonjour.

Якщо також налаштовано домен широкомасштабного виявлення, порівняйте з результатом:

bash
openclaw gateway discover --json

Ця команда за один прохід показує local. разом із налаштованим широкомасштабним доменом, використовуючи визначену кінцеву точку служби замість підказок лише з TXT.

Виявлення між мережами через одноадресний DNS-SD

Виявлення Android NSD/mDNS не працює між мережами. Якщо Node 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 через службу переднього плану (постійне сповіщення).
  • Відкрийте вкладку Connect.
  • Скористайтеся режимом Setup Code або Manual.
  • Якщо виявлення заблоковано, у розділі Advanced controls укажіть хост/порт вручну. Для хостів приватної LAN ws:// і надалі працює. Для хостів Tailscale або публічних хостів увімкніть TLS і використовуйте кінцеву точку wss:// / Tailscale Serve.

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

Офіційні коди налаштування підключають Android як Node і за замовчуванням надають повний операторський доступ до Gateway через wss://. Налаштування незашифрованого ws:// не через loopback автоматично використовує обмежений доступ для захисту токена на пред’явника. Settings → Gateway показує рівень доступу Full або Limited. Для обмеженого з’єднання налаштуйте wss:// або Tailscale Serve, створіть новий код повного доступу в Control UI чи за допомогою openclaw qr, потім відскануйте або вставте його на цій сторінці та повторно підключіться. Оператори, яким потрібен обмежений профіль, можуть вибрати Limited access у Control UI або виконати openclaw qr --limited.

Кілька Gateway

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

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

Сигнали активної присутності

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

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

4. Схвалення сполучення (CLI)

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

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

Докладніше про сполучення: Сполучення.

Необов’язково: якщо Android-вузол завжди підключається з підмережі зі строгим контролем, можна ввімкнути автоматичне схвалення першого сполучення вузла з явно зазначеними CIDR або точними IP-адресами:

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

Типово це вимкнено. Це застосовується лише до нового сполучення role: node без запитаних областей доступу. Сполучення оператора/браузера та будь-яка зміна ролі, області доступу, метаданих або відкритого ключа, як і раніше, потребує ручного схвалення.

5. Перевірте, чи підключено вузол

bash
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. Перейдіть до нього на вузлі (LAN):
bash
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 лише коли ввімкнено Settings > Phone Capabilities > Installed 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, може переглядати очікувані запити на виконання в розділі Settings -> Approvals. Застосунок завантажує очищений запис схвалення 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. Це налаштовується на пристрої, на сторінці Settings застосунку, а не в конфігурації gateway/openclaw.json.

Налаштування Опис
Forward Notification Events Головний перемикач. Типово вимкнено; спочатку потрібно надати Notification Listener Access.
Package Filter Allowlist (пересилаються лише зазначені ідентифікатори пакетів) або Blocklist (типово: усі пакети, крім зазначених ідентифікаторів). Власний пакет OpenClaw завжди виключається в режимі Blocklist, щоб запобігти циклам пересилання.
Quiet Hours Локальний часовий проміжок початку/завершення у форматі HH:mm, протягом якого пересилання пригнічується. Типово вимкнено; після ввімкнення типові значення — 22:00-07:00.
Max Events / Minute Обмеження частоти пересилання сповіщень для кожного пристрою. Типове значення — 20.
Route Session Key Необов’язково. Закріплює переслані події сповіщень за певним сеансом замість типового маршруту сповіщень пристрою.

Сповіщення WhatsApp, WhatsApp Business, Telegram, Telegram X, Discord і Signal завжди виключаються. Їхні повідомлення вже належать сеансам нативних каналів OpenClaw; пересилання сповіщення Android як окремої події вузла може спрямувати відповідь не до тієї розмови.

Пов’язані матеріали

Was this useful?
On this page

On this page