Hoppa till huvudinnehåll

​
Bridge-protokoll (äldre nodtransport)

Bro protokollet är en legacy nod transport (TCP JSONL). Nya nodklienter bör använda det enhetliga Gateway WebSocket-protokollet istället. Om du bygger en operatör eller nodklient, använd Gateway-protokollet. Observera: Nuvarande OpenClaw bygger skickar inte längre TCP-brygglyssnaren, detta dokument hålls för historisk referens. Legacy bridge.* config nycklar är inte längre en del av konfigurationsschemat.

​
Varför vi har båda

  • Säkerhetsgräns: bridgen exponerar en liten tillåtelselista i stället för hela gatewayns API‑yta.
  • Parkoppling + nodidentitet: nodantagning ägs av gatewayn och är knuten till en per‑nod‑token.
  • Discovery‑UX: noder kan upptäcka gateways via Bonjour på LAN, eller ansluta direkt över ett tailnet.
  • Loopback WS: hela WS‑kontrollplanet förblir lokalt om det inte tunnlas via SSH.

​
Transport

  • TCP, ett JSON‑objekt per rad (JSONL).
  • Valfri TLS (när bridge.tls.enabled är true).
  • Äldre standardlyssnarport var 18790 (aktuella byggen startar inte en TCP‑bridge).
När TLS är aktiverat inkluderar discovery-TXT-poster bridgeTls=1 samt bridgeTlsSha256 som en icke-hemlig hint. Observera att Bonjour/mDNS TXT-poster är oautentiserade; klienter får inte behandla det annonserade fingeravtrycket som en autoritativ pin utan uttrycklig användaravsikt eller annan verifiering utanför bandet.

​
Handshake + parkoppling

  1. Klienten skickar hello med nodmetadata + token (om redan parkopplad).
  2. Om inte parkopplad svarar gatewayn med error (NOT_PAIRED/UNAUTHORIZED).
  3. Klienten skickar pair-request.
  4. Gatewayn väntar på godkännande och skickar därefter pair-ok och hello-ok.
hello-ok returnerar serverName och kan inkludera canvasHostUrl.

​
Ramar

Klient → Gateway:
  • req / res: avgränsad gateway‑RPC (chatt, sessioner, konfig, hälsa, voicewake, skills.bins)
  • event: nodsignaler (rösttranskript, agentbegäran, chattprenumeration, exec‑livscykel)
Gateway → Klient:
  • invoke / invoke-res: nodkommandon (canvas.*, camera.*, screen.record, location.get, sms.send)
  • event: chattuppdateringar för prenumererade sessioner
  • ping / pong: keepalive
Äldre tillåtelseliste‑tillämpning låg i src/gateway/server-bridge.ts (borttagen).

​
Exec‑livscykelhändelser

Noder kan sända ut exec.finished eller exec.denied händelser till ytans system.run aktivitet. Dessa kartläggs till systemhändelser i porten. (Legacy noder kan fortfarande avge exec.started.) Payload‑fält (alla valfria om inget annat anges):
  • sessionKey (obligatoriskt): agentsession som ska ta emot systemhändelsen.
  • runId: unikt exec‑id för gruppering.
  • command: rå eller formaterad kommandosträng.
  • exitCode, timedOut, success, output: avslutningsdetaljer (endast vid färdig).
  • reason: orsak till nekande (endast vid nekad).

​
Tailnet‑användning

  • Bind bridgen till en tailnet‑IP: bridge.bind: "tailnet" i ~/.openclaw/openclaw.json.
  • Klienter ansluter via MagicDNS‑namn eller tailnet‑IP.
  • Bonjour korsar inte nätverk; använd manuell värd/port eller DNS‑SD för breda nät när det behövs.

​
Versionering

Bridge är för närvarande implicit v1 (ingen min/max förhandling). Bakåt-compat förväntas; lägg till en bro protokoll versionsfält innan några brytningsändringar.