> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Архитектура Gateway
## Обзор
* Единый долгоживущий **Gateway** управляет всеми каналами обмена сообщениями (WhatsApp через
Baileys, Telegram через grammY, Slack, Discord, Signal, iMessage, WebChat).
* Клиенты плоскости управления (приложение macOS, CLI, веб-интерфейс, автоматизации) подключаются к
Gateway через **WebSocket** на настроенном адресе привязки (по умолчанию
`127.0.0.1:18789`).
* **Узлы** (macOS/iOS/Android/без интерфейса) также подключаются через **WebSocket**, но
объявляют `role: node` с явным указанием возможностей и команд.
* На каждом хосте используется один Gateway; только он открывает сеанс WhatsApp.
* **Хост холста** обслуживается HTTP-сервером Gateway по следующим адресам:
* `/__openclaw__/canvas/` (доступные агенту для редактирования HTML/CSS/JS)
* `/__openclaw__/a2ui/` (хост A2UI)
Он использует тот же порт, что и Gateway (по умолчанию `18789`).
## Компоненты и потоки
### Gateway (демон)
* Поддерживает подключения к провайдерам.
* Предоставляет типизированный API WS (запросы, ответы, события, отправляемые сервером).
* Проверяет входящие кадры по JSON Schema.
* Отправляет такие события, как `agent`, `chat`, `presence`, `health`, `heartbeat`, `cron`.
### Клиенты (приложение Mac / CLI / веб-интерфейс администратора)
* Одно подключение WS на каждого клиента.
* Отправляют запросы (`health`, `status`, `send`, `agent`, `system-presence`).
* Подписываются на события (`tick`, `agent`, `presence`, `shutdown`).
### Узлы (macOS / iOS / Android / без интерфейса)
* Подключаются к **тому же серверу WS** с `role: node`.
* Передают идентификатор устройства в `connect`; сопряжение выполняется **на уровне устройства** (роль `node`), а
разрешение хранится в хранилище сопряжений устройств.
* Предоставляют такие команды, как `canvas.*`, `camera.*`, `screen.record`, `location.get`.
Подробности протокола: [Протокол Gateway](https://docs2.openclaw.ai/ru/gateway/protocol.md)
### WebChat
* Статический интерфейс, использующий API WS Gateway для получения истории чата и отправки сообщений.
* При удалённой настройке подключается через тот же туннель SSH/Tailscale, что и другие
клиенты.
## Жизненный цикл подключения (один клиент)
```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
sequenceDiagram
participant Client
participant Gateway
Client->>Gateway: запрос:connect
Gateway-->>Client: ответ (успешно)
Note right of Gateway: или ответ с ошибкой + закрытие
Note left of Client: полезная нагрузка=hello-ok
снимок: присутствие + состояние
Gateway-->>Client: событие:presence
Gateway-->>Client: событие:tick
Client->>Gateway: запрос:agent
Gateway-->>Client: ответ:agent
подтверждение {runId, status:"accepted"}
Gateway-->>Client: событие:agent
(потоковая передача)
Gateway-->>Client: ответ:agent
итог {runId, status, summary}
```
## Сетевой протокол (краткое описание)
* Транспорт: WebSocket, текстовые кадры с полезной нагрузкой JSON.
* Первым кадром **обязательно должен** быть `connect`.
* После установления соединения:
* Запросы: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
* События: `{type:"event", event, payload, seq?, stateVersion?}`
* `hello-ok.features.methods` / `events` — это метаданные обнаружения, а не
сгенерированный перечень всех доступных вспомогательных маршрутов.
* Аутентификация с общим секретом использует `connect.params.auth.token` или
`connect.params.auth.password` в зависимости от настроенного режима аутентификации Gateway.
* Режимы с идентификацией, такие как Tailscale Serve
(`gateway.auth.allowTailscale: true`) или не использующий loopback
`gateway.auth.mode: "trusted-proxy"`, выполняют аутентификацию по заголовкам запроса,
а не по `connect.params.auth.*`.
* При `gateway.auth.mode: "none"` для частного входящего трафика аутентификация с общим секретом
полностью отключается; не используйте этот режим для публичного или недоверенного входящего трафика.
* Ключи идемпотентности обязательны для методов с побочными эффектами (`send`, `agent`), чтобы
обеспечить безопасные повторные попытки; сервер хранит кратковременный кеш дедупликации.
* Узлы должны включать `role: "node"`, а также возможности, команды и разрешения в `connect`.
## Сопряжение и локальное доверие
* Все клиенты WS (операторы и узлы) указывают **идентификатор устройства** в `connect`.
* Новые идентификаторы устройств требуют подтверждения сопряжения; Gateway выдаёт **токен устройства**
для последующих подключений.
* Прямые локальные подключения через loopback могут подтверждаться автоматически, чтобы обеспечить удобную
работу на одном хосте.
* OpenClaw также предоставляет ограниченный путь самостоятельного подключения внутри бэкенда или контейнера для
доверенных вспомогательных потоков с общим секретом.
* Подключения через tailnet и локальную сеть, включая привязки tailnet на том же хосте, по-прежнему требуют
явного подтверждения сопряжения.
* Все подключения должны подписывать одноразовое значение `connect.challenge`. Полезная нагрузка подписи `v3`
также связывает `platform` и `deviceFamily`; при повторном подключении Gateway закрепляет сопряжённые метаданные
и при их изменении требует повторного сопряжения.
* **Нелокальные** подключения по-прежнему требуют явного подтверждения.
* Аутентификация Gateway (`gateway.auth.*`) по-прежнему применяется ко **всем** подключениям — локальным и
удалённым.
Подробности: [Протокол Gateway](https://docs2.openclaw.ai/ru/gateway/protocol.md), [Сопряжение](https://docs2.openclaw.ai/ru/channels/pairing.md),
[Безопасность](https://docs2.openclaw.ai/ru/gateway/security.md).
## Типизация протокола и генерация кода
* Схемы TypeBox определяют протокол.
* JSON Schema генерируется из этих схем.
* Модели Swift генерируются из JSON Schema.
## Удалённый доступ
* Предпочтительный вариант: Tailscale или VPN.
* Альтернативный вариант: туннель SSH
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
```
* При подключении через туннель используются те же процедура установления соединения и токен аутентификации.
* В удалённых конфигурациях для WS можно включить TLS и необязательное закрепление сертификата.
## Краткий обзор эксплуатации
* Запуск: `openclaw gateway` (на переднем плане, журналы выводятся в stdout).
* Проверка состояния: `health` через WS (также включена в `hello-ok`).
* Контроль процесса: launchd/systemd для автоматического перезапуска.
## Инварианты
* Ровно один Gateway управляет одним сеансом Baileys на каждом хосте.
* Установление соединения обязательно; любой первый кадр, который не является JSON или запросом подключения, приводит к немедленному закрытию соединения.
* События не воспроизводятся повторно; при наличии пропусков клиенты должны обновить данные.
## Связанные материалы
* [Цикл агента](https://docs2.openclaw.ai/ru/concepts/agent-loop.md) — подробный цикл выполнения агента
* [Протокол Gateway](https://docs2.openclaw.ai/ru/gateway/protocol.md) — контракт протокола WebSocket
* [Очередь](https://docs2.openclaw.ai/ru/concepts/queue.md) — очередь команд и параллелизм
* [Безопасность](https://docs2.openclaw.ai/ru/gateway/security.md) — модель доверия и усиление защиты