Gateway

Protokol bridge

Mengapa ini pernah ada

Batas keamanan: jembatan mengekspos allowlist kecil alih-alih seluruh permukaan API Gateway.
Pairing + identitas Node: penerimaan Node dimiliki oleh Gateway dan terikat ke token per Node.
UX penemuan: Node dapat menemukan Gateway melalui Bonjour di LAN, atau terhubung langsung melalui tailnet.
Loopback WS: control plane WS penuh tetap lokal kecuali ditunnel melalui SSH.

Transport

TCP, satu objek JSON per baris (JSONL).
TLS opsional (ketika bridge.tls.enabled bernilai true).
Port listener default historis adalah 18790 (build saat ini tidak memulai jembatan TCP).

Ketika TLS diaktifkan, record TXT penemuan menyertakan bridgeTls=1 plus bridgeTlsSha256 sebagai petunjuk non-rahasia. Perhatikan bahwa record TXT Bonjour/mDNS tidak diautentikasi; klien tidak boleh memperlakukan fingerprint yang diiklankan sebagai pin otoritatif tanpa niat pengguna yang eksplisit atau verifikasi out-of-band lainnya.

Handshake + pairing

Klien mengirim hello dengan metadata Node + token (jika sudah dipairing).
Jika belum dipairing, Gateway membalas error (NOT_PAIRED/UNAUTHORIZED).
Klien mengirim pair-request.
Gateway menunggu persetujuan, lalu mengirim pair-ok dan hello-ok.

Secara historis, hello-ok mengembalikan serverName; permukaan Plugin yang dihosting kini diiklankan melalui pluginSurfaceUrls. Canvas/A2UI menggunakan pluginSurfaceUrls.canvas; alias usang canvasHostUrl bukan bagian dari protokol yang telah direfaktor.

Frame

Klien → Gateway:

req / res: RPC Gateway berskop (chat, sesi, konfigurasi, kesehatan, voicewake, skills.bins)
event: sinyal Node (transkrip suara, permintaan agen, berlangganan chat, siklus hidup exec)

Gateway → Klien:

invoke / invoke-res: perintah Node (canvas.*, camera.*, screen.record, location.get, sms.send)
event: pembaruan chat untuk sesi yang dilanggan
ping / pong: keepalive

Penegakan allowlist lama berada di src/gateway/server-bridge.ts (dihapus).

Peristiwa siklus hidup exec

Node dapat memancarkan peristiwa exec.finished untuk menampilkan aktivitas system.run yang selesai. Ini dipetakan ke peristiwa sistem di Gateway. (Node lama mungkin masih memancarkan exec.started.) Node dapat memancarkan exec.denied untuk percobaan system.run yang ditolak; Gateway menerima peristiwa tersebut sebagai penolakan terminal dan tidak mengantrekan peristiwa sistem atau membangunkan pekerjaan agen.

Field payload (semua opsional kecuali disebutkan):

sessionKey (wajib): sesi agen untuk korelasi peristiwa dan, untuk exec.finished, pengiriman peristiwa sistem.
runId: id exec unik untuk pengelompokan.
command: string perintah mentah atau terformat.
exitCode, timedOut, success, output: detail penyelesaian (hanya selesai).
reason: alasan penolakan (hanya ditolak).

Penggunaan tailnet historis

Bind jembatan ke IP tailnet: bridge.bind: "tailnet" di ~/.openclaw/openclaw.json (hanya historis; bridge.* tidak lagi valid).
Klien terhubung melalui nama MagicDNS atau IP tailnet.
Bonjour tidak melintasi jaringan; gunakan host/port manual atau DNS-SD area luas saat diperlukan.

Versioning

Jembatan adalah v1 implisit (tanpa negosiasi min/maks). Bagian ini adalah referensi historis saja; klien Node/operator saat ini menggunakan WebSocket Protokol Gateway.

Terkait

Was this useful?