Gateway
Протокол моста
Навіщо він існував
- Межа безпеки: міст відкриває невеликий список дозволеного замість повної поверхні API Gateway.
- Сполучення + ідентичність вузла: допуск вузла належить Gateway і прив’язаний до токена для окремого вузла.
- UX виявлення: вузли можуть виявляти Gateway через Bonjour у LAN або підключатися безпосередньо через tailnet.
- Локальний WS: повна площина керування WS залишається локальною, якщо її не тунельовано через SSH.
Транспорт
- TCP, по одному JSON-об’єкту на рядок (JSONL).
- Необов’язковий TLS (коли
bridge.tls.enabledмає значення true). - Історичний стандартний порт прослуховувача був
18790(поточні збірки не запускають TCP-міст).
Коли TLS увімкнено, записи TXT виявлення містять bridgeTls=1 плюс
bridgeTlsSha256 як несекретну підказку. Зауважте, що записи TXT Bonjour/mDNS
не автентифікуються; клієнти не повинні вважати оголошений відбиток
авторитетним закріпленням без явного наміру користувача або іншої позасмугової перевірки.
Рукостискання + сполучення
- Клієнт надсилає
helloз метаданими вузла + токеном (якщо вже сполучено). - Якщо не сполучено, Gateway відповідає
error(NOT_PAIRED/UNAUTHORIZED). - Клієнт надсилає
pair-request. - Gateway чекає на схвалення, потім надсилає
pair-okіhello-ok.
Історично hello-ok повертав serverName; розміщені поверхні Plugin тепер
оголошуються через pluginSurfaceUrls. Canvas/A2UI використовує
pluginSurfaceUrls.canvas; застарілий псевдонім canvasHostUrl не є частиною
переробленого протоколу.
Фрейми
Клієнт → Gateway:
req/res: обмежений за областю RPC Gateway (чат, сеанси, конфігурація, справність, voicewake, skills.bins)event: сигнали вузла (голосова транскрипція, запит агента, підписка на чат, життєвий цикл виконання)
Gateway → клієнт:
invoke/invoke-res: команди вузла (canvas.*,camera.*,screen.record,location.get,sms.send)event: оновлення чату для сеансів із підпискоюping/pong: підтримання з’єднання
Застаріле застосування списку дозволеного містилося в src/gateway/server-bridge.ts (видалено).
Події життєвого циклу виконання
Вузли можуть випромінювати події exec.finished, щоб показувати завершену активність system.run.
Вони зіставляються із системними подіями в Gateway. (Застарілі вузли все ще можуть випромінювати exec.started.)
Вузли можуть випромінювати exec.denied для відхилених спроб system.run; Gateway приймає
подію як кінцеву відмову й не ставить системну подію в чергу та не пробуджує роботу агента.
Поля корисного навантаження (усі необов’язкові, якщо не зазначено інше):
sessionKey(обов’язкове): сеанс агента для кореляції подій і, дляexec.finished, доставки системної події.runId: унікальний ідентифікатор виконання для групування.command: сирий або форматований рядок команди.exitCode,timedOut,success,output: деталі завершення (лише завершені).reason: причина відмови (лише відхилені).
Історичне використання tailnet
- Прив’язати міст до IP tailnet:
bridge.bind: "tailnet"у~/.openclaw/openclaw.json(лише історично;bridge.*більше не є чинним). - Клієнти підключаються через ім’я MagicDNS або IP tailnet.
- Bonjour не проходить між мережами; за потреби використовуйте ручний хост/порт або широкозонний DNS-SD.
Версіювання
Міст був неявною v1 (без узгодження мінімуму/максимуму). Цей розділ є лише історичною довідкою; поточні клієнти вузлів/операторів використовують WebSocket протокол Gateway.
