Перейти к основному содержимому

Протоколы и 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 не аутентифицированы; клиенты не должны рассматривать рекламируемый отпечаток как авторитетную привязку без явного намерения пользователя или другой проверки вне канала.

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

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

Протокол GatewayOpenAI Chat Completions