Протоколы и API

Протокол Bridge

Протокол Bridge — это устаревший транспорт для узлов (TCP JSONL). Новым клиентам узлов следует использовать унифицированный протокол Gateway WebSocket. Если вы создаёте оператора или клиент узла, используйте протокол Gateway. Примечание: Текущие сборки OpenClaw больше не включают TCP-слушатель bridge; этот документ сохранён для исторической справки. Устаревшие ключи конфигурации bridge.* больше не являются частью схемы конфигурации.

Почему существуют оба протокола

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

Транспорт

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

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

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

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

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

Фреймы

Клиент → Шлюз:

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

Шлюз → Клиент:

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

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

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

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

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

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

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

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

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

Протокол Gateway OpenAI Chat Completions