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

Протокол моста — это устаревший транспорт узлов (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, чтобы узлы могли закрепить сертификат.

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

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