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

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

Протокол моста — это устаревший транспорт узлов (TCP JSONL). Новым клиентам узлов следует использовать унифицированный протокол Gateway (шлюз) на базе WebSocket. Если вы разрабатываете оператор или клиент узла, используйте протокол Gateway. Примечание: Текущие сборки 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). Ожидается обратная совместимость; перед любыми несовместимыми изменениями следует добавить поле версии протокола моста.