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

Протокол моста — это устаревший транспорт узла (TCP JSONL). Новые клиенты узлов должны использовать унифицированный протокол WebSocket шлюза.

Если вы создаете оператора или клиента узла, используйте протокол шлюза.

Примечание: Текущие сборки OpenClaw больше не поставляют слушатель моста TCP; этот документ сохранен для исторической справки. Устаревшие ключи конфигурации bridge.* больше не являются частью схемы конфигурации.

Почему у нас есть оба

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

Транспорт

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

Когда TLS включен, записи обнаружения TXT включают bridgeTls=1 плюс bridgeTlsSha256, чтобы узлы могли закрепить сертификат.

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

  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: сигналы узла (голосовая транскрипция, запрос агента, подписка на чат, жизненный цикл exec)

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

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

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

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

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

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

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

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

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

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

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

← Назад к документации