Gateway

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

Зачем он существовал

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

Транспорт

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

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

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

Клиент отправляет hello с метаданными узла + токеном (если уже сопряжен).
Если сопряжение отсутствует, Gateway отвечает error (NOT_PAIRED/UNAUTHORIZED).
Клиент отправляет pair-request.
Gateway ожидает одобрения, затем отправляет pair-ok и hello-ok.

Исторически hello-ok возвращал serverName; размещенные поверхности Plugin теперь объявляются через pluginSurfaceUrls. Canvas/A2UI использует pluginSurfaceUrls.canvas; устаревший псевдоним canvasHostUrl не является частью переработанного протокола.

Фреймы

Клиент → Gateway:

req / res: RPC Gateway с ограниченной областью действия (чат, сеансы, конфигурация, здоровье, voicewake, skills.bins)
event: сигналы узла (голосовая расшифровка, запрос агента, подписка на чат, жизненный цикл exec)

Gateway → Клиент:

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

Устаревшее применение списка разрешений находилось в src/gateway/server-bridge.ts (удалено).

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

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

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

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

Историческое использование tailnet

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

Версионирование

Мост был неявной v1 (без согласования min/max). Этот раздел приведен только для исторической справки; текущие клиенты узлов и операторов используют WebSocket Протокол Gateway.

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

Was this useful?