Gateway

Protokol jembatan

Alasan keberadaannya

Batas keamanan: mengekspos daftar izin terbatas alih-alih seluruh permukaan API Gateway.
Pemasangan + identitas node: penerimaan node dikelola oleh Gateway dan dikaitkan dengan token per node.
Pengalaman pengguna penemuan: node dapat menemukan Gateway melalui Bonjour di LAN, atau terhubung langsung melalui tailnet.
WS loopback: seluruh bidang kendali WS tetap lokal kecuali diteruskan melalui tunnel SSH.

Transportasi

TCP, satu objek JSON per baris (JSONL).
TLS opsional (bridge.tls.enabled: true).
Port listener bawaannya adalah 18790.

Saat TLS diaktifkan, rekaman TXT penemuan menyertakan bridgeTls=1 beserta bridgeTlsSha256 sebagai petunjuk nonrahasia. Rekaman TXT Bonjour/mDNS tidak diautentikasi; klien tidak dapat memperlakukan sidik jari yang diumumkan sebagai pin otoritatif tanpa verifikasi luar jalur lainnya.

Handshake dan pemasangan

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

hello-ok sebelumnya mengembalikan serverName; permukaan Plugin yang dihosting kini diumumkan melalui pluginSurfaceUrls pada protokol Gateway saat ini (Canvas/A2UI menggunakan pluginSurfaceUrls.canvas).

Bingkai

Klien ke Gateway:

req / res: RPC Gateway dengan cakupan terbatas (obrolan, sesi, konfigurasi, kesehatan, voicewake, skills.bins).
event: sinyal node (transkrip suara, permintaan agen, langganan obrolan, siklus hidup eksekusi).

Gateway ke klien:

invoke / invoke-res: perintah node (canvas.*, camera.*, screen.record, location.get, sms.send).
event: pembaruan obrolan untuk sesi yang dilanggani.
ping / pong: penjaga koneksi.

Pemberlakuan daftar izin berada di src/gateway/server-bridge.ts (telah dihapus).

Peristiwa siklus hidup eksekusi

Node memancarkan exec.finished untuk menampilkan aktivitas system.run yang telah selesai, yang dipetakan menjadi peristiwa sistem oleh Gateway (node lama juga dapat memancarkan exec.started). exec.denied menandai upaya system.run yang ditolak sebagai penolakan terminal tanpa mengantrekan peristiwa sistem atau membangunkan pekerjaan agen.

Kolom muatan (semuanya opsional kecuali dinyatakan lain):

Kolom	Catatan
`sessionKey`	Wajib. Sesi agen untuk korelasi peristiwa dan, untuk `exec.finished`, pengiriman peristiwa sistem.
`runId`	ID eksekusi unik untuk pengelompokan.
`command`	String perintah mentah atau yang telah diformat.
`exitCode`, `timedOut`, `output`	Detail penyelesaian (hanya untuk yang selesai).
`reason`	Alasan penolakan (hanya untuk yang ditolak).

Penggunaan tailnet historis

Ikat bridge ke alamat IP tailnet: bridge.bind: "tailnet" dalam ~/.openclaw/openclaw.json (hanya historis; bridge.* tidak lagi merupakan konfigurasi yang valid).
Klien terhubung melalui nama MagicDNS atau alamat IP tailnet.
Bonjour tidak melintasi jaringan; jika tidak, DNS-SD area luas atau host/port manual diperlukan.

Pembuatan versi

Bridge menggunakan v1 implisit, tanpa negosiasi minimum/maksimum. Klien node/operator saat ini menggunakan protokol Gateway WebSocket, yang menegosiasikan rentang versi protokol.

Terkait

Was this useful?