Ana içeriğe atla

​
Köprü protokolü (eski düğüm taşıması)

Köprü protokolü eski bir düğüm taşımasıdır (TCP JSONL). Yeni düğüm istemcileri bunun yerine birleşik Gateway WebSocket protokolünü kullanmalıdır. Bir operatör veya düğüm istemcisi geliştiriyorsanız, Gateway protokolü kullanın. Not: Güncel OpenClaw sürümleri artık TCP köprü dinleyicisini dağıtmamaktadır; bu belge tarihsel referans için tutulmaktadır. Eski bridge.* yapılandırma anahtarları artık yapılandırma şemasının parçası değildir.

​
Neden ikisi de var

  • Güvenlik sınırı: köprü, tam gateway API yüzeyi yerine küçük bir izin listesi açığa çıkarır.
  • Eşleştirme + düğüm kimliği: düğüm kabulü gateway tarafından yönetilir ve düğüm başına bir belirtece bağlanır.
  • Keşif UX’i: düğümler LAN üzerinde Bonjour aracılığıyla gateway’leri keşfedebilir veya bir tailnet üzerinden doğrudan bağlanabilir.
  • Loopback WS: tam WS kontrol düzlemi, SSH ile tünellenmedikçe yerel kalır.

​
Taşıma

  • TCP, satır başına bir JSON nesnesi (JSONL).
  • İsteğe bağlı TLS (bridge.tls.enabled true olduğunda).
  • Eski varsayılan dinleyici portu 18790 idi (güncel sürümler TCP köprüsü başlatmaz).
TLS etkinleştirildiğinde, keşif TXT kayıtları bridgeTls=1 ile birlikte bridgeTlsSha256 içerir; böylece düğümler sertifikayı sabitleyebilir. Bonjour/mDNS TXT kayıtlarının kimliği doğrulanmamıştır; istemciler, açık kullanıcı niyeti veya bant dışı başka bir doğrulama olmadan ilan edilen parmak izini yetkili bir pin olarak değerlendirmemelidir.

​
El sıkışma + eşleştirme

  1. İstemci, düğüm meta verileri + belirteç (zaten eşleştirilmişse) ile hello gönderir.
  2. Eşleştirilmemişse, gateway error (NOT_PAIRED/UNAUTHORIZED) ile yanıtlar.
  3. İstemci pair-request gönderir.
  4. Gateway onayı bekler, ardından pair-ok ve hello-ok gönderir.
hello-ok, serverName döndürür ve canvasHostUrl içerebilir.

​
Çerçeveler

İstemci → Gateway:
  • req / res: kapsamlı gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
  • event: düğüm sinyalleri (ses dökümü, ajan isteği, sohbet aboneliği, çalıştırma yaşam döngüsü)
Gateway → İstemci:
  • invoke / invoke-res: düğüm komutları (canvas.*, camera.*, screen.record, location.get, sms.send)
  • event: abone olunan oturumlar için sohbet güncellemeleri
  • ping / pong: keepalive
Eski izin listesi zorlaması src/gateway/server-bridge.ts içinde yer alıyordu (kaldırıldı).

​
Exec lifecycle events

Düğümler, system.run etkinliğini yüzeye çıkarmak için exec.finished veya exec.denied olayları yayımlayabilir. Bunlar gateway’de sistem olaylarına eşlenir. (Eski düğümler hâlâ exec.started yayımlayabilir.) Yük alanı alanları (belirtilmedikçe tümü isteğe bağlıdır):
  • sessionKey (zorunlu): sistem olayını alacak ajan oturumu.
  • runId: gruplama için benzersiz çalıştırma kimliği.
  • command: ham veya biçimlendirilmiş komut dizesi.
  • exitCode, timedOut, success, output: tamamlanma ayrıntıları (yalnızca finished).
  • reason: reddedilme nedeni (yalnızca denied).

​
Tailnet kullanımı

  • Köprüyü bir tailnet IP’sine bağlayın: bridge.bind: "tailnet", ~/.openclaw/openclaw.json içinde.
  • İstemciler MagicDNS adı veya tailnet IP’si üzerinden bağlanır.
  • Bonjour ağlar arası geçmez; gerektiğinde manuel ana makine/port veya geniş alan DNS‑SD kullanın.

​
Versioning

Köprü şu anda örtük v1’dir (min/maks müzakere yok). Geriye dönük uyumluluk beklenir; herhangi bir kırıcı değişiklikten önce bir köprü protokolü sürüm alanı ekleyin.