Перейти к основному содержанию
TCP-мост был удален. Текущие сборки OpenClaw не поставляют слушатель моста, а ключей конфигурации bridge.* больше нет в схеме. Эта страница сохранена только для исторической справки. Используйте Протокол 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 не аутентифицированы; клиенты не должны считать объявленный отпечаток авторитетным закреплением без явного намерения пользователя или другой внеполосной проверки.

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

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

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