> ## 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** на настроенном bind-хосте (по умолчанию
  `127.0.0.1:18789`).
* **Узлы** (macOS/iOS/Android/headless) также подключаются по **WebSocket**, но
  объявляют `role: node` с явными возможностями/командами.
* Один Gateway на хост; это единственное место, открывающее сеанс WhatsApp.
* **Хост canvas** обслуживается HTTP-сервером Gateway по адресам:
  * `/__openclaw__/canvas/` (HTML/CSS/JS, редактируемые агентом)
  * `/__openclaw__/a2ui/` (хост A2UI)
    Он использует тот же порт, что и Gateway (по умолчанию `18789`).

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

### Gateway (демон)

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

### Клиенты (приложение macOS / 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`.

Сведения о протоколе:

* [Протокол Gateway](/ru/gateway/protocol)

### WebChat

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

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

```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok<br>snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>final {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 выдает **токен устройства**
  для последующих подключений.
* Прямые подключения через local loopback могут подтверждаться автоматически, чтобы UX на том же хосте
  оставался плавным.
* OpenClaw также имеет узкий backend/container-local путь самостоятельного подключения для
  доверенных вспомогательных потоков с общим секретом.
* Подключения через tailnet и LAN, включая bind на tailnet того же хоста, по-прежнему требуют
  явного подтверждения сопряжения.
* Все подключения должны подписывать nonce `connect.challenge`.
* Полезная нагрузка подписи `v3` также привязывает `platform` + `deviceFamily`; Gateway
  закрепляет сопряженные метаданные при повторном подключении и требует ремонтного сопряжения при изменениях
  метаданных.
* **Нелокальные** подключения по-прежнему требуют явного подтверждения.
* Аутентификация Gateway (`gateway.auth.*`) по-прежнему применяется ко **всем** подключениям, локальным и
  удаленным.

Подробности: [Протокол Gateway](/ru/gateway/protocol), [Сопряжение](/ru/channels/pairing),
[Безопасность](/ru/gateway/security).

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

* Схемы 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@host
  ```

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

* TLS + необязательное закрепление можно включить для WS в удаленных настройках.

## Операционный снимок

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

## Инварианты

* Ровно один Gateway управляет одним сеансом Baileys на хост.
* Рукопожатие обязательно; любой не-JSON или не-connect первый кадр приводит к жесткому закрытию.
* События не воспроизводятся повторно; клиенты должны обновляться при пропусках.

## Связанные материалы

* [Цикл агента](/ru/concepts/agent-loop) — подробный цикл выполнения агента
* [Протокол Gateway](/ru/gateway/protocol) — контракт протокола WebSocket
* [Очередь](/ru/concepts/queue) — очередь команд и конкурентность
* [Безопасность](/ru/gateway/security) — модель доверия и усиление защиты