Основы

Архитектура шлюза

Последнее обновление: 2026-01-22

Обзор

  • Единственный долгоживущий Шлюз управляет всеми поверхностями для обмена сообщениями (WhatsApp через Baileys, Telegram через grammY, Slack, Discord, Signal, iMessage, WebChat).
  • Клиенты плоскости управления (приложение для macOS, CLI, веб-интерфейс, автоматизации) подключаются к Шлюзу по WebSocket на настроенном хосте привязки (по умолчанию 127.0.0.1:18789).
  • Узлы (macOS/iOS/Android/headless) также подключаются по WebSocket, но объявляют role: node с явными возможностями/командами.
  • Один Шлюз на хост; это единственное место, где открывается сессия WhatsApp.
  • Хост canvas обслуживается HTTP-сервером Шлюза по адресам:
    • /__openclaw__/canvas/ (HTML/CSS/JS, редактируемые агентом)
    • /__openclaw__/a2ui/ (хост A2UI) Он использует тот же порт, что и Шлюз (по умолчанию 18789).

Компоненты и потоки

Шлюз (демон)

  • Поддерживает подключения к провайдерам.
  • Предоставляет типизированный WS API (запросы, ответы, события с сервера).
  • Проверяет входящие фреймы на соответствие JSON Schema.
  • Генерирует события, такие как agent, chat, presence, health, heartbeat, cron.

Клиенты (приложение для Mac / CLI / веб-админка)

  • Одно WS-подключение на клиента.
  • Отправляют запросы (health, status, send, agent, system-presence).
  • Подписываются на события (tick, agent, presence, shutdown).

Узлы (macOS / iOS / Android / headless)

  • Подключаются к тому же WS-серверу с role: node.
  • Предоставляют идентификатор устройства в connect; спаривание происходит на основе устройства (роль node), и подтверждение хранится в хранилище спаренных устройств.
  • Предоставляют команды, такие как canvas.*, camera.*, screen.record, location.get.

Детали протокола:

WebChat

  • Статический интерфейс, который использует WS API Шлюза для истории чата и отправки сообщений.
  • В удаленных конфигурациях подключается через тот же SSH/Tailscale туннель, что и другие клиенты.

Жизненный цикл подключения (один клиент)

Проводной протокол (кратко)

  • Транспорт: WebSocket, текстовые фреймы с полезной нагрузкой JSON.
  • Первый фрейм обязательно должен быть connect.
  • После подтверждения соединения:
    • Запросы: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • События: {type:"event", event, payload, seq?, stateVersion?}
  • Если задан OPENCLAW_GATEWAY_TOKEN (или --token), connect.params.auth.token должен совпадать, иначе сокет закрывается.
  • Ключи идемпотентности требуются для методов с побочными эффектами (send, agent) для безопасного повторения; сервер хранит кратковременный кэш дедупликации.
  • Узлы должны включать role: "node", а также возможности/команды/разрешения в connect.

Спаривание + локальное доверие

  • Все WS-клиенты (операторы и узлы) включают идентификатор устройства в connect.
  • Новые идентификаторы устройств требуют подтверждения спаривания; Шлюз выдает токен устройства для последующих подключений.
  • Локальные подключения (loopback или собственный адрес tailnet хоста шлюза) могут быть подтверждены автоматически для удобства работы на том же хосте.
  • Все подключения должны подписывать одноразовый номер connect.challenge.
  • Полезная нагрузка подписи v3 также привязывает platform + deviceFamily; шлюз фиксирует метаданные спаренного устройства при повторном подключении и требует повторного спаривания при изменении метаданных.
  • Нелокальные подключения по-прежнему требуют явного подтверждения.
  • Аутентификация шлюза (gateway.auth.*) по-прежнему применяется ко всем подключениям, локальным или удаленным.

Подробности: Протокол шлюза, Спаривание, Безопасность.

Типизация протокола и кодогенерация

  • Схемы TypeBox определяют протокол.
  • JSON Schema генерируется из этих схем.
  • Swift-модели генерируются из JSON Schema.

Удаленный доступ

  • Предпочтительный способ: Tailscale или VPN.

  • Альтернатива: SSH-туннель

    Копировать

    ssh -N -L 18789:127.0.0.1:18789 user@host

  • Тот же процесс подтверждения соединения и токен аутентификации применяются через туннель.

  • TLS и опциональная привязка сертификата могут быть включены для WS в удаленных конфигурациях.

Снимок операций

  • Запуск: openclaw gateway (на переднем плане, логи в stdout).
  • Проверка состояния: health через WS (также включено в hello-ok).
  • Наблюдение: launchd/systemd для автоматического перезапуска.

Инварианты

  • Ровно один Шлюз управляет единственной сессией Baileys на хост.
  • Подтверждение соединения обязательно; любой первый фрейм, не являющийся JSON или не connect, приводит к немедленному закрытию.
  • События не воспроизводятся повторно; клиенты должны обновлять данные при пропусках.

Архитектура интеграции с PiСреда выполнения агента