Узел Android: настройка локальных операций на устройстве

Что вы сможете сделать после изучения

• Подключить устройство Android к Gateway в качестве узла для выполнения локальных операций на устройстве
• Управлять камерой устройства Android через AI-помощника для фото- и видеосъемки
• Использовать визуальный интерфейс Canvas для отображения содержимого в реальном времени на Android
• Управлять записью экрана, получением геолокации и отправкой SMS

Ваша текущая проблема

Вы хотите, чтобы AI-помощник мог получить доступ к вашему устройству Android — делать фото, записывать видео, отображать интерфейс Canvas — но не знаете, как безопасно подключить устройство к Gateway.

Простая установка приложения Android может не позволить обнаружить Gateway, или после настройки сопряжение не удаётся. Вам нужен чёткий процесс подключения.

Когда использовать этот подход

• Требуются локальные операции на устройстве: Вы хотите, чтобы устройство Android выполняло локальные операции через AI-помощника (фото, видео, запись экрана)
• Доступ между сетями: Устройство Android и Gateway находятся в разных сетях, требуется подключение через Tailscale
• Визуализация Canvas: Необходимо отображать интерфейсы HTML/CSS/JS, созданные AI, на Android

🎒 Подготовка перед началом

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

Перед началом убедитесь:

• ✅ Gateway установлен и работает: Gateway работает на macOS, Linux или Windows (WSL2)
• ✅ Устройство Android доступно: Устройство или эмулятор Android 8.0+
• ✅ Сетевое подключение нормально: Устройство Android может получить доступ к порту WebSocket Gateway (по умолчанию 18789)
• ✅ CLI доступна: На хосте Gateway можно использовать команду clawdbot

Основная идея

Узел Android — это сопутствующее приложение (companion app), которое подключается к Gateway через WebSocket и предоставляет возможности локальных операций на устройстве для использования AI-помощником.

Обзор архитектуры

Устройство Android (приложение узла)
        ↓
    WebSocket подключение
        ↓
    Gateway (плоскость управления)
        ↓
    AI-помощник + вызов инструментов

Ключевые моменты:

• Android не размещает Gateway, а подключается к уже работающему Gateway в качестве узла
• Все команды маршрутизируются через метод node.invoke Gateway к узлу Android
• Узел требует сопряжения (pairing) для получения доступа

Поддерживаемые функции

Узел Android поддерживает следующие локальные операции на устройстве:

Функция	Команда	Описание
Canvas	canvas.*	Отображение визуального интерфейса в реальном времени (A2UI)
Camera	camera.*	Фотосъемка (JPG) и видеозапись (MP4)
Screen	screen.*	Запись экрана
Location	location.*	Получение GPS-локации
SMS	sms.*	Отправка SMS

Ограничения переднего плана

Все локальные операции на устройстве (Canvas, Camera, Screen) требуют, чтобы приложение Android находилось в состоянии переднего плана. Фоновые вызовы возвращают ошибку NODE_BACKGROUND_UNAVAILABLE.

Следуйте инструкциям

Шаг 1: Запуск Gateway

Зачем Узел Android должен подключиться к работающему Gateway, чтобы функционировать. Gateway предоставляет плоскость управления WebSocket и сервис сопряжения.

clawdbot gateway --port 18789 --verbose

Вы должны увидеть:

listening on ws://0.0.0.0:18789
bonjour: advertising _clawdbot-gw._tcp on local...

Режим Tailscale (рекомендуется)

Если Gateway и устройство Android находятся в разных сетях, но подключены через Tailscale, привяжите Gateway к tailnet IP:

// ~/.clawdbot/clawdbot.json
{
  gateway: {
    bind: "tailnet"
  }
}

После перезапуска Gateway узел Android может быть обнаружен через Wide-Area Bonjour.

Шаг 2: Проверка обнаружения (опционально)

Зачем Подтвердить, что сервис Bonjour/mDNS Gateway работает корректно для удобства обнаружения приложением Android.

На хосте Gateway выполните:

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

Вы должны увидеть:

Timestamp     A/R    IF  N/T   Target              Port
==========   ===   ===  ========               ====
12:34:56.123 Addr   10  _clawdbot-gw._tcp. 18789

Если вы видите подобный вывод, это означает, что Gateway рекламирует сервис обнаружения.

Отладка проблем Bonjour

Если обнаружение не удаётся, возможные причины:

• mDNS заблокирован: Некоторые сети Wi-Fi отключают mDNS
• Брандмауэр: Блокирует UDP-порт 5353
• Изоляция сети: Устройства находятся в разных VLAN или подсетях

Решение: Используйте Tailscale + Wide-Area Bonjour или вручную настройте адрес Gateway.

Шаг 3: Подключение с Android

Зачем Приложение Android обнаруживает Gateway через mDNS/NSD и устанавливает WebSocket подключение.

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

1. Откройте Настройки (Settings)
2. В Discovered Gateways выберите ваш Gateway
3. Нажмите Connect

Если mDNS заблокирован:

• Перейдите в Advanced → Manual Gateway
• Введите имя хоста и порт Gateway (например, 192.168.1.100:18789)
• Нажмите Connect (Manual)

Автоматическое переподключение

После успешного первого сопряжения приложение Android автоматически переподключается при запуске:

• Если настроен ручный endpoint, используется ручной endpoint
• В противном случае используется последний обнаруженный Gateway (по возможности)

Контрольная точка ✅

• Приложение Android показывает статус "Connected"
• Приложение отображает отображаемое имя Gateway
• Приложение показывает статус сопряжения (Pending или Paired)

Шаг 4: Одобрение сопряжения (CLI)

Зачем Gateway требует, чтобы вы одобрили запрос на сопряжение узла для предоставления доступа.

На хосте Gateway:

# Просмотреть ожидающие запросы на сопряжение
clawdbot nodes pending

# Одобрить сопряжение
clawdbot nodes approve <requestId>

Процесс сопряжения

Рабочий процесс Gateway-owned pairing:

1. Узел Android подключается к Gateway, запрашивает сопряжение
2. Gateway сохраняет pending request и отправляет событие node.pair.requested
3. Вы одобряете или отклоняете запрос через CLI
4. После одобрения Gateway выдаёт новый auth token
5. Узел Android использует токен для повторного подключения, переходя в статус "paired"

Ожидающие запросы автоматически истекают через 5 минут.

Вы должны увидеть:

✓ Node approved: android-node-abc123
Token issued: eyJhbGc...

Приложение Android автоматически переподключится и покажет статус "Paired".

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

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

Проверка через CLI:

clawdbot nodes status

Вы должны увидеть:

Known: 1 · Paired: 1 · Connected: 1

┌──────────────────────────────────────────────┐
│ Name: My Samsung Tab                     │
│ Device: Android                          │
│ Model: Samsung SM-X926B                 │
│ IP: 192.168.0.99                      │
│ Status: paired, connected                 │
│ Caps: camera, canvas, screen, location, sms │
└──────────────────────────────────────────────┘

Или через API Gateway:

clawdbot gateway call node.list --params '{}'

Шаг 6: Тестирование функции Camera

Зачем Проверить, что команды Camera узла Android работают корректно, права доступа предоставлены.

Тестирование фотосъемки через CLI:

# Сделать фото (по умолчанию фронтальная камера)
clawdbot nodes camera snap --node "android-node"

# Указать заднюю камеру
clawdbot nodes camera snap --node "android-node" --facing back

# Записать видео (3 секунды)
clawdbot nodes camera clip --node "android-node" --duration 3000

Вы должны увидеть:

MEDIA: /tmp/clawdbot-camera-snap-123456.jpg

Разрешения Camera

Узел Android требует следующие разрешения времени выполнения:

• CAMERA: Для camera.snap и camera.clip
• RECORD_AUDIO: Для camera.clip (когда includeAudio=true)

При первом вызове команд Camera приложение запросит предоставление разрешений. Если отказано, команды вернут ошибки CAMERA_PERMISSION_REQUIRED или AUDIO_PERMISSION_REQUIRED.

Шаг 7: Тестирование функции Canvas

Зачем Проверить, что визуальный интерфейс Canvas может отображаться на устройстве Android.

Canvas Host

Canvas требует HTTP-сервер для предоставления содержимого HTML/CSS/JS. По умолчанию Gateway запускает Canvas Host на порту 18793.

Создайте файл Canvas на хосте Gateway:

mkdir -p ~/clawd/canvas
echo '<h1>Hello from AI!</h1>' > ~/clawd/canvas/index.html

Перейдите к Canvas в приложении Android:

clawdbot nodes invoke --node "android-node" \
  --command canvas.navigate \
  --params '{"url":"http://<gateway-hostname>.local:18793/__clawdbot__/canvas/"}'

Вы должны увидеть: Страница "Hello from AI!" отображается в приложении Android.

Среда Tailscale

Если устройство Android и Gateway находятся в сети Tailscale, используйте имя MagicDNS или tailnet IP вместо .local:

{"url":"http://<gateway-magicdns>:18793/__clawdbot__/canvas/"}

Шаг 8: Тестирование функций Screen и Location

Зачем Проверить, что запись экрана и получение геолокации работают корректно.

Запись экрана:

# Записать 10 секунд экрана
clawdbot nodes screen record --node "android-node" --duration 10s --fps 15

Вы должны увидеть:

MEDIA: /tmp/clawdbot-screen-record-123456.mp4

Получение геолокации:

clawdbot nodes invoke --node "android-node" --command location.get

Вы должны увидеть:

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "accuracy": 10,
  "timestamp": 1706345678000
}

Требования к разрешениям

Запись экрана требует разрешения Android RECORD_AUDIO (если аудио включено) и доступа к переднему плану. Получение геолокации требует разрешения LOCATION.

При первом вызове приложение запросит предоставление разрешений.

Предупреждения о проблемах

Проблема 1: Не удается обнаружить Gateway

Симптомы: В приложении Android не видно Gateway

Возможные причины:

• Gateway не запущен или привязан к loopback
• mDNS заблокирован в сети
• Брандмауэр блокирует UDP-порт 5353

Решения:

1. Проверьте, работает ли Gateway: clawdbot nodes status
2. Используйте ручной адрес Gateway: введите IP и порт Gateway в приложении Android
3. Настройте Tailscale + Wide-Area Bonjour (рекомендуется)

Проблема 2: Сбой подключения после сопряжения

Симптомы: Показывает "Paired", но не удается подключиться

Возможные причины:

• Токен истёк (токен ротируется после каждого сопряжения)
• Gateway перезапущен, но узел не переподключился
• Изменение сети

Решения:

1. В приложении Android вручную нажмите "Reconnect"
2. Проверьте журналы Gateway: bonjour: client disconnected ...
3. Пересопрягите: удалите узел и одобрите заново

Проблема 3: Команды Camera возвращают ошибку разрешений

Симптомы: camera.snap возвращает CAMERA_PERMISSION_REQUIRED

Возможные причины:

• Пользователь отклонил разрешение
• Разрешение отключено системной политикой

Решения:

1. В настройках Android найдите приложение "Clawdbot"
2. Перейдите в "Permissions"
3. Предоставьте разрешения Camera и Microphone
4. Повторите команду Camera

Проблема 4: Фоновые вызовы не удаются

Симптомы: Фоновые вызовы возвращают NODE_BACKGROUND_UNAVAILABLE

Причина: Узел Android разрешает только вызовы локальных команд устройства с переднего плана

Решения:

1. Убедитесь, что приложение работает на переднем плане (откройте приложение)
2. Проверьте, оптимизировано ли приложение системой (оптимизация батареи)
3. Отключите ограничения "режима энергосбережения" для приложения

Итог урока

В этом уроке мы рассмотрели, как настроить узел Android для выполнения локальных операций на устройстве:

• Процесс подключения: Подключение узла Android к Gateway через mDNS/NSD или ручную конфигурацию
• Механизм сопряжения: Использование Gateway-owned pairing для одобрения доступа узла
• Доступные функции: Camera, Canvas, Screen, Location, SMS
• Инструменты CLI: Использование команд clawdbot nodes для управления узлами и вызова функций
• Требования к разрешениям: Приложение Android требует разрешений Camera, Audio, Location и т. д. во время выполнения

Ключевые моменты:

• Узел Android — это сопутствующее приложение, оно не размещает Gateway
• Все локальные операции на устройстве требуют работы приложения на переднем плане
• Запросы на сопряжение автоматически истекают через 5 минут
• Поддерживает обнаружение Wide-Area Bonjour для сетей Tailscale

Предпросмотр следующего урока

В следующем уроке мы изучим Визуальный интерфейс Canvas и A2UI.

Вы узнаете:

• Механизм отправки Canvas A2UI
• Как отображать содержимое в реальном времени на Canvas
• Полный список команд Canvas

---

Приложение: ссылка на исходный код

Нажмите, чтобы раскрыть расположение исходного кода

Время обновления: 2026-01-27

Функция	Путь к файлу	Строки
Политика команд узла	src/gateway/node-command-policy.ts	1-112
Schema протокола узла	src/gateway/protocol/schema/nodes.ts	1-103
Документация Android	docs/platforms/android.md	1-142
CLI узлов	docs/cli/nodes.md	1-69

Ключевые константы:

• PLATFORM_DEFAULTS: определяет список команд, поддерживаемых каждой платформой (node-command-policy.ts:32-58)
• Команды, поддерживаемые Android: Canvas, Camera, Screen, Location, SMS (node-command-policy.ts:34-40)

Ключевые функции:

• resolveNodeCommandAllowlist(): разрешает список разрешённых команд в зависимости от платформы (node-command-policy.ts:77-91)
• normalizePlatformId(): нормализует ID платформы (node-command-policy.ts:60-75)

Особенности узла Android:

• ID клиента: clawdbot-android (gateway/protocol/client-info.ts:9)
• Обнаружение семейства устройств: идентификация Android через поле deviceFamily (node-command-policy.ts:70)
• По умолчанию включены функции Canvas и Camera (docs/platforms/android.md)