> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Протокол моста

# Протокол моста (устаревший транспорт узлов)

Протокол моста — это **устаревший** транспорт узлов (TCP JSONL). Новым клиентам
узлов следует использовать унифицированный протокол Gateway (шлюз) на базе WebSocket.

Если вы разрабатываете оператор или клиент узла, используйте
[протокол Gateway](/gateway/protocol).

**Примечание:** Текущие сборки OpenClaw больше не поставляются с TCP‑слушателем моста; этот документ сохранён для исторической справки.
Устаревшие ключи конфига `bridge.*` больше не входят в схему конфигурации.

## Зачем нужны оба

* **Граница безопасности**: мост предоставляет небольшой список разрешённых
  операций вместо полной поверхности API шлюза.
* **Сопряжение + идентичность узла**: допуск узла контролируется шлюзом и привязан
  к токену на каждый узел.
* **UX обнаружения**: узлы могут обнаруживать шлюзы через Bonjour в LAN
  или подключаться напрямую через tailnet.
* **Loopback WS**: полный плоскостной контроль WS остаётся локальным,
  если не туннелируется через SSH.

## Транспорт

* TCP, по одному объекту JSON на строку (JSONL).
* Необязательный TLS (когда `bridge.tls.enabled` равен true).
* Устаревший порт слушателя по умолчанию — `18790` (текущие сборки не запускают TCP‑мост).

Когда TLS включён, TXT‑записи обнаружения включают `bridgeTls=1` плюс
`bridgeTlsSha256`, чтобы узлы могли закрепить сертификат. Обратите внимание, что Bonjour/mDNS TXT-записи являются
unauthenticated; клиенты не должны считать рекламируемый отпечаток
авторитетным пином без явного намерения пользователя или иной внеполосной проверки.

## Рукопожатие и сопряжение

1. Клиент отправляет `hello` с метаданными узла и токеном (если уже сопряжён).
2. Если не сопряжён, шлюз отвечает `error` (`NOT_PAIRED`/`UNAUTHORIZED`).
3. Клиент отправляет `pair-request`.
4. Шлюз ожидает подтверждения, затем отправляет `pair-ok` и `hello-ok`.

`hello-ok` возвращает `serverName` и может включать `canvasHostUrl`.

## Frames

Клиент → Gateway (шлюз):

* `req` / `res`: ограниченный RPC шлюза (chat, sessions, config, health, voicewake, skills.bins)
* `event`: сигналы узла (транскрипт голоса, запрос агента, подписка на чат, жизненный цикл exec)

Gateway (шлюз) → Клиент:

* `invoke` / `invoke-res`: команды узлу (`canvas.*`, `camera.*`, `screen.record`,
  `location.get`, `sms.send`)
* `event`: обновления чата для подписанных сеансов
* `ping` / `pong`: сигналы keepalive

Контроль устаревшего allowlist находился в `src/gateway/server-bridge.ts` (удалён).

## События жизненного цикла Exec

Узлы могут отправлять события `exec.finished` или `exec.denied`, чтобы отразить активность system.run.
Они сопоставляются с системными событиями в шлюзе. (Устаревшие узлы всё ещё могут отправлять `exec.started`.)

Поля полезной нагрузки (все необязательны, если не указано иное):

* `sessionKey` (обязательно): сеанс агента для получения системного события.
* `runId`: уникальный идентификатор exec для группировки.
* `command`: исходная или отформатированная строка команды.
* `exitCode`, `timedOut`, `success`, `output`: детали завершения (только для завершённых).
* `reason`: причина отказа (только для отказанных).

## Использование tailnet

* Привяжите мост к IP tailnet: `bridge.bind: "tailnet"` в
  `~/.openclaw/openclaw.json`.
* Клиенты подключаются через имя MagicDNS или IP tailnet.
* Bonjour **не** пересекает сети; при необходимости используйте ручной host/port
  или широкозонный DNS‑SD.

## Versioning

В настоящее время мост — **неявная v1** (без согласования min/max). Ожидается обратная совместимость; перед любыми несовместимыми изменениями следует добавить поле версии протокола моста.