Gateway protokolü

Gateway WS protokolü, OpenClaw için tek kontrol düzlemi + node aktarımıdır. Tüm istemciler (CLI, web UI, macOS uygulaması, iOS/Android node'ları, başsız node'lar) WebSocket üzerinden bağlanır ve el sıkışma sırasında rol + kapsam bildirir.

Aktarım

• JSON yükleri içeren metin çerçeveleriyle WebSocket.
• İlk çerçeve mutlaka bir connect isteği olmalıdır.
• Bağlantı öncesi çerçeveler 64 KiB ile sınırlıdır. Başarılı bir el sıkışmadan sonra istemciler hello-ok.policy.maxPayload ve hello-ok.policy.maxBufferedBytes sınırlarına uymalıdır. Tanılama etkinleştirildiğinde, aşırı büyük gelen çerçeveler ve yavaş giden arabellekler, gateway etkilenen çerçeveyi kapatmadan veya düşürmeden önce payload.large olayları yayar. Bu olaylar boyutları, sınırları, yüzeyleri ve güvenli neden kodlarını saklar. İleti gövdesini, ek içeriklerini, ham çerçeve gövdesini, belirteçleri, çerezleri veya gizli değerleri saklamaz.

El Sıkışma (connect)

Gateway → İstemci (bağlantı öncesi challenge):

{  "type": "event",  "event": "connect.challenge",  "payload": { "nonce": "…", "ts": 1737264000000 }}

İstemci → Gateway:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "client": {      "id": "cli",      "version": "1.2.3",      "platform": "macos",      "mode": "operator"    },    "role": "operator",    "scopes": ["operator.read", "operator.write"],    "caps": [],    "commands": [],    "permissions": {},    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-cli/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Gateway → İstemci:

{  "type": "res",  "id": "…",  "ok": true,  "payload": {    "type": "hello-ok",    "protocol": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

Gateway başlangıç sidecar'larını hâlâ tamamlıyorken, connect isteği details.reason değeri "startup-sidecars" olarak ayarlanmış ve retryAfterMs içeren yeniden denenebilir bir UNAVAILABLE hatası döndürebilir. İstemciler bu yanıtı terminal el sıkışma hatası olarak göstermek yerine genel bağlantı bütçeleri içinde yeniden denemelidir.

server, features, snapshot ve policy öğelerinin tümü şema tarafından zorunludur (packages/gateway-protocol/src/schema/frames.ts). auth da zorunludur ve anlaşılan rol/kapsamları bildirir. pluginSurfaceUrls isteğe bağlıdır ve canvas gibi plugin yüzey adlarını kapsamlandırılmış barındırılan URL'lerle eşler.

Kapsamlandırılmış plugin yüzey URL'lerinin süresi dolabilir. Node'lar, pluginSurfaceUrls içinde yeni bir girdi almak için { "surface": "canvas" } ile node.pluginSurface.refresh çağırabilir. Deneysel Canvas plugin refaktörü, kullanımdan kaldırılmış canvasHostUrl, canvasCapability veya node.canvas.capability.refresh uyumluluk yolunu desteklemez; mevcut yerel istemciler ve gateway'ler plugin yüzeylerini kullanmalıdır.

Cihaz belirteci verilmediğinde, hello-ok.auth anlaşılan izinleri belirteç alanları olmadan bildirir:

{  "auth": {    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

Güvenilen aynı işlem backend istemcileri (client.id: "gateway-client", client.mode: "backend"), paylaşılan gateway belirteci/parolasıyla kimlik doğruladıklarında doğrudan local loopback bağlantılarında device alanını atlayabilir. Bu yol, dahili kontrol düzlemi RPC'leri için ayrılmıştır ve eski CLI/cihaz eşleştirme temel çizgilerinin subagent oturum güncellemeleri gibi yerel backend çalışmalarını engellemesini önler. Uzak istemciler, tarayıcı kökenli istemciler, node istemcileri ve açık cihaz belirteci/cihaz kimliği istemcileri normal eşleştirme ve kapsam yükseltme kontrollerini kullanmaya devam eder.

Cihaz belirteci verildiğinde, hello-ok şunu da içerir:

{  "auth": {    "deviceToken": "…",    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

Yerleşik QR/kurulum kodu bootstrap, yeni bir mobil devir yoludur. Başarılı temel kurulum kodu connect işlemi, birincil node belirteci ve sınırlandırılmış bir operator belirteci döndürür:

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

Operator devri kasıtlı olarak sınırlandırılmıştır; böylece QR ile onboarding, mobil operator döngüsünü başlatabilir ve eşleştirme mutasyon kapsamları veya operator.admin vermeden yerel kurulumu tamamlayabilir. Yerel istemcinin bootstrap sonrasında ihtiyaç duyduğu Talk yapılandırmasını okuyabilmesi için operator.talk.secrets içerir. Daha geniş eşleştirme ve admin erişimi, ayrı bir onaylanmış operator eşleştirmesi veya belirteç akışı gerektirir. İstemciler hello-ok.auth.deviceTokens değerini yalnızca connect, wss:// veya loopback/yerel eşleştirme gibi güvenilir aktarımda bootstrap auth kullandığında kalıcı hale getirmelidir.

Node örneği

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "client": {      "id": "ios-node",      "version": "1.2.3",      "platform": "ios",      "mode": "node"    },    "role": "node",    "scopes": [],    "caps": ["camera", "canvas", "screen", "location", "voice"],    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],    "permissions": { "camera.capture": true, "screen.record": false },    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-ios/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Çerçeveleme

• İstek: {type:"req", id, method, params}
• Yanıt: {type:"res", id, ok, payload|error}
• Olay: {type:"event", event, payload, seq?, stateVersion?}

Yan etki oluşturan yöntemler idempotency key'leri gerektirir (şemaya bakın).

Roller + kapsamlar

Tam operator kapsam modeli, onay zamanı kontrolleri ve paylaşılan gizli anlamları için bkz. Operator kapsamları.

Roller

• operator = kontrol düzlemi istemcisi (CLI/UI/otomasyon).
• node = yetenek barındırıcısı (kamera/ekran/canvas/system.run).

Kapsamlar (operator)

Yaygın kapsamlar:

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

includeSecrets: true ile talk.config, operator.talk.secrets (veya operator.admin) gerektirir. Gizliler dahil edildiğinde, istemciler etkin Talk sağlayıcı kimlik bilgisini talk.resolved.config.apiKey alanından okumalıdır; talk.providers.<id>.apiKey kaynak biçiminde kalır ve bir SecretRef nesnesi veya maskelenmiş bir dize olabilir.

Plugin tarafından kaydedilen gateway RPC yöntemleri kendi operator kapsamlarını isteyebilir, ancak ayrılmış core admin önekleri (config.*, exec.approvals.*, wizard.*, update.*) her zaman operator.admin değerine çözümlenir.

Yöntem kapsamı yalnızca ilk kapıdır. chat.send üzerinden ulaşılan bazı slash komutları bunun üzerine daha katı komut düzeyi kontroller uygular. Örneğin, kalıcı /config set ve /config unset yazmaları operator.admin gerektirir.

node.pair.approve, temel yöntem kapsamının üstünde ek bir onay zamanı kapsam kontrolüne de sahiptir:

• komutsuz istekler: operator.pairing
• exec olmayan node komutları içeren istekler: operator.pairing + operator.write
• system.run, system.run.prepare veya system.which içeren istekler: operator.pairing + operator.admin

Caps/commands/permissions (node)

Node'lar connect sırasında yetenek iddialarını bildirir:

• caps: camera, canvas, screen, location, voice ve talk gibi üst düzey yetenek kategorileri.
• commands: invoke için komut izin listesi.
• permissions: ayrıntılı anahtarlar (örn. screen.record, camera.capture).

Gateway bunları iddia olarak ele alır ve sunucu tarafı izin listelerini uygular.

Presence

• system-presence, cihaz kimliğine göre anahtarlanmış girdiler döndürür.
• Presence girdileri deviceId, roles ve scopes içerir; böylece UI'lar, cihaz hem operator hem node olarak bağlansa bile cihaz başına tek satır gösterebilir.
• node.list, isteğe bağlı lastSeenAtMs ve lastSeenReason alanlarını içerir. Bağlı node'lar, geçerli bağlantı zamanlarını connect nedeniyle lastSeenAtMs olarak bildirir; eşleştirilmiş node'lar, güvenilir bir node olayı eşleştirme metaverilerini güncellediğinde kalıcı arka plan presence'ı da bildirebilir.

Node arka plan alive olayı

Node'lar, eşleştirilmiş bir node'un arka plan uyanması sırasında bağlı olarak işaretlenmeden alive olduğunu kaydetmek için event: "node.presence.alive" ile node.event çağırabilir.

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger kapalı bir enum'dur: background, silent_push, bg_app_refresh, significant_location, manual veya connect. Bilinmeyen trigger dizeleri, kalıcılıktan önce gateway tarafından background değerine normalleştirilir. Olay yalnızca kimliği doğrulanmış node cihaz oturumları için kalıcıdır; cihazsız veya eşleştirilmemiş oturumlar handled: false döndürür.

Başarılı gateway'ler yapılandırılmış bir sonuç döndürür:

{  "ok": true,  "event": "node.presence.alive",  "handled": true,  "reason": "persisted"}

Daha eski gateway'ler, node.event için hâlâ { "ok": true } döndürebilir; istemciler bunu kalıcı presence saklama olarak değil, onaylanmış bir RPC olarak ele almalıdır.

Yayın olayı kapsamlandırması

Sunucu tarafından gönderilen WebSocket yayın olayları, eşleştirme kapsamlı veya yalnızca node oturumlarının oturum içeriğini pasif olarak almaması için kapsam kapılıdır.

• Sohbet, agent ve tool-result çerçeveleri (stream edilen agent olayları ve tool çağrısı sonuçları dahil) en az operator.read gerektirir. operator.read olmayan oturumlar bu çerçeveleri tamamen atlar.
• Plugin tanımlı plugin.* yayınları, plugin'in bunları nasıl kaydettiğine bağlı olarak operator.write veya operator.admin ile sınırlandırılır.
• Durum ve aktarım olayları (heartbeat, presence, tick, connect/disconnect yaşam döngüsü vb.), aktarım sağlığı her kimliği doğrulanmış oturum tarafından gözlemlenebilir kalsın diye kısıtlanmadan kalır.
• Bilinmeyen yayın olayı aileleri, kayıtlı bir işleyici bunları açıkça gevşetmediği sürece varsayılan olarak kapsam kapılıdır (fail-closed).

Her istemci bağlantısı kendi istemci başına sıra numarasını tutar; böylece yayınlar, farklı istemciler olay akışının farklı kapsam filtreli alt kümelerini görse bile o sokette monoton sıralamayı korur.

Yaygın RPC yöntem aileleri

Genel WS yüzeyi, yukarıdaki el sıkışma/auth örneklerinden daha geniştir. Bu oluşturulmuş bir döküm değildir — hello-ok.features.methods, src/gateway/server-methods-list.ts ve yüklenen plugin/channel yöntem dışa aktarımlarından oluşturulan muhafazakâr bir keşif listesidir. Bunu src/gateway/server-methods/*.ts öğelerinin tam sayımı olarak değil, özellik keşfi olarak ele alın.

Yaygın olay aileleri

• chat: chat.inject ve diğer yalnızca transkript sohbet olayları gibi UI sohbet güncellemeleri. Protokol v4'te delta yükleri deltaText taşır; message kümülatif asistan anlık görüntüsü olarak kalır. Önek olmayan değiştirmeler replace=true ayarlar ve deltaText değerini değiştirme metni olarak kullanır.
• session.message, session.operation ve session.tool: abone olunan bir oturum için transkript, uçuş hâlindeki oturum işlemi ve olay akışı güncellemeleri.
• sessions.changed: oturum dizini veya meta veriler değişti.
• presence: sistem presence anlık görüntüsü güncellemeleri.
• tick: periyodik keepalive / canlılık olayı.
• health: gateway sağlık anlık görüntüsü güncellemesi.
• heartbeat: heartbeat olay akışı güncellemesi.
• cron: cron çalıştırma/iş değişikliği olayı.
• shutdown: gateway kapatma bildirimi.
• node.pair.requested / node.pair.resolved: düğüm eşleştirme yaşam döngüsü.
• node.invoke.request: düğüm çağırma isteği yayını.
• device.pair.requested / device.pair.resolved: eşleştirilmiş cihaz yaşam döngüsü.
• voicewake.changed: uyandırma sözcüğü tetikleyici yapılandırması değişti.
• exec.approval.requested / exec.approval.resolved: exec onay yaşam döngüsü.
• plugin.approval.requested / plugin.approval.resolved: Plugin onay yaşam döngüsü.

Düğüm yardımcı yöntemleri

• Düğümler, otomatik izin kontrolleri için beceri çalıştırılabilirlerinin geçerli listesini almak üzere skills.bins çağırabilir.

Görev defteri RPC'leri

Operatör istemcileri, Gateway arka plan görev kayıtlarını görev defteri RPC'leri aracılığıyla inceleyebilir ve iptal edebilir. Bu yöntemler ham çalışma zamanı durumu değil, temizlenmiş görev özetleri döndürür.

• tasks.list, operator.read gerektirir.
  • Parametreler: isteğe bağlı status ("queued", "running", "completed", "failed", "cancelled" veya "timed_out") ya da bu durumların bir dizisi, isteğe bağlı agentId, isteğe bağlı sessionKey, 1 ile 500 arasında isteğe bağlı limit ve isteğe bağlı dize cursor.
  • Sonuç: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get, operator.read gerektirir.
  • Parametreler: { "taskId": string }.
  • Sonuç: { "task": TaskSummary }.
  • Eksik görev kimlikleri Gateway bulunamadı hata şeklini döndürür.
• tasks.cancel, operator.write gerektirir.
  • Parametreler: { "taskId": string, "reason"?: string }.
  • Sonuç: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found, defterde eşleşen bir görev olup olmadığını bildirir. cancelled, çalışma zamanının iptali kabul edip etmediğini veya kaydedip kaydetmediğini bildirir.

TaskSummary, id, status ve kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, zaman damgaları, ilerleme, terminal özeti ve temizlenmiş hata metni gibi isteğe bağlı meta verileri içerir. agentId, görevi yürüten ajanı tanımlar; sessionKey ve ownerKey, istekte bulunanı ve denetim bağlamını korur.

Operatör yardımcı yöntemleri

• Operatörler bir aracı için çalışma zamanı komut envanterini almak üzere commands.list (operator.read) çağırabilir.
  • agentId isteğe bağlıdır; varsayılan aracı çalışma alanını okumak için atlayın.
  • scope, birincil name alanının hangi yüzeyi hedeflediğini kontrol eder:
    • text, baştaki / olmadan birincil metin komutu belirtecini döndürür
    • native ve varsayılan both yolu, mevcut olduğunda sağlayıcıya duyarlı yerel adları döndürür
  • textAliases, /model ve /m gibi tam eğik çizgi takma adlarını taşır.
  • nativeName, varsa sağlayıcıya duyarlı yerel komut adını taşır.
  • provider isteğe bağlıdır ve yalnızca yerel adlandırmayı ve yerel plugin komutu kullanılabilirliğini etkiler.
  • includeArgs=false, serileştirilmiş argüman meta verilerini yanıttan çıkarır.
• Operatörler bir aracı için çalışma zamanı araç kataloğunu almak üzere tools.catalog (operator.read) çağırabilir. Yanıt, gruplanmış araçları ve köken meta verilerini içerir:
  • source: core veya plugin
  • pluginId: source="plugin" olduğunda plugin sahibi
  • optional: bir plugin aracının isteğe bağlı olup olmadığı
• Operatörler bir oturum için çalışma zamanında etkili araç envanterini almak üzere tools.effective (operator.read) çağırabilir.
  • sessionKey zorunludur.
  • Gateway, çağıranın sağladığı kimlik doğrulama veya teslimat bağlamını kabul etmek yerine güvenilir çalışma zamanı bağlamını oturumdan sunucu tarafında türetir.
  • Yanıt, çekirdek, plugin, kanal ve daha önce keşfedilmiş MCP sunucusu araçlarını içeren, etkin envanterin oturum kapsamlı ve sunucu tarafından türetilmiş bir projeksiyonudur.
  • tools.effective, MCP için salt okunurdur: sıcak bir oturum MCP kataloğunu nihai araç politikası üzerinden projekte edebilir, ancak MCP çalışma zamanları oluşturmaz, aktarımları bağlamaz veya tools/list yayınlamaz. Eşleşen sıcak katalog yoksa yanıt mcp-not-yet-connected, mcp-not-yet-listed veya mcp-stale-catalog gibi bir bildirim içerebilir.
  • Etkili araç girdileri source="core", source="plugin", source="channel" veya source="mcp" kullanır.
• Operatörler, /tools/invoke ile aynı Gateway politikası yolu üzerinden kullanılabilir bir aracı çağırmak için tools.invoke (operator.write) çağırabilir.
  • name zorunludur. args, sessionKey, agentId, confirm ve idempotencyKey isteğe bağlıdır.
  • Hem sessionKey hem de agentId mevcutsa çözümlenen oturum aracısı agentId ile eşleşmelidir.
  • cron, gateway ve nodes gibi yalnızca sahip çekirdek sarmalayıcıları, tools.invoke yönteminin kendisi operator.write olsa bile sahip/yönetici kimliği (operator.admin) gerektirir.
  • Yanıt, ok, toolName, isteğe bağlı output ve tipli error alanları içeren SDK'ya dönük bir zarftır. Onay veya politika retleri, Gateway araç politikası işlem hattını atlamak yerine yük içinde ok:false döndürür.
• Operatörler bir aracı için görünür skill envanterini almak üzere skills.status (operator.read) çağırabilir.
  • agentId isteğe bağlıdır; varsayılan aracı çalışma alanını okumak için atlayın.
  • Yanıt, ham gizli değerleri açığa çıkarmadan uygunluk, eksik gereksinimler, yapılandırma denetimleri ve temizlenmiş kurulum seçeneklerini içerir.
• Operatörler ClawHub keşif meta verileri için skills.search ve skills.detail (operator.read) çağırabilir.
• Operatörler, yüklemeden önce özel bir skill arşivini hazırlamak için skills.upload.begin, skills.upload.chunk ve skills.upload.commit (operator.admin) çağırabilir. Bu, güvenilir istemciler için ayrı bir yönetici yükleme yoludur; normal ClawHub skill kurulum akışı değildir ve skills.install.allowUploadedArchives etkinleştirilmediği sürece varsayılan olarak devre dışıdır.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }), bu slug ve force değerine bağlı bir yükleme oluşturur.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }), baytları tam çözümlenmiş ofsette ekler.
  • skills.upload.commit({ uploadId, sha256? }), nihai boyutu ve SHA-256 değerini doğrular. Commit yalnızca yüklemeyi sonlandırır; skill'i kurmaz.
  • Yüklenen skill arşivleri, bir SKILL.md kökü içeren zip arşivleridir. Arşivin iç dizin adı kurulum hedefini asla seçmez.
• Operatörler skills.install (operator.admin) öğesini üç modda çağırabilir:
  • ClawHub modu: { source: "clawhub", slug, version?, force? }, varsayılan aracı çalışma alanındaki skills/ dizinine bir skill klasörü kurar.
  • Yükleme modu: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? }, commit edilmiş bir yüklemeyi varsayılan aracı çalışma alanındaki skills/<slug> dizinine kurar. Slug ve force değeri özgün skills.upload.begin isteğiyle eşleşmelidir. Bu mod, skills.install.allowUploadedArchives etkinleştirilmedikçe reddedilir. Ayar, ClawHub kurulumlarını etkilemez.
  • Gateway kurucu modu: { name, installId, timeoutMs? }, Gateway ana makinesinde bildirilen bir metadata.openclaw.install eylemini çalıştırır. Eski istemciler hâlâ dangerouslyForceUnsafeInstall gönderebilir; bu alan kullanımdan kaldırılmıştır, yalnızca protokol uyumluluğu için kabul edilir ve yok sayılır. Operatörün sahip olduğu kurulum kararları için security.installPolicy kullanın.
• Operatörler skills.update (operator.admin) öğesini iki modda çağırabilir:
  • ClawHub modu, varsayılan aracı çalışma alanındaki izlenen tek bir slug'ı veya izlenen tüm ClawHub kurulumlarını günceller.
  • Yapılandırma modu, enabled, apiKey ve env gibi skills.entries.<skillKey> değerlerine yama uygular.

models.list görünümleri

models.list, isteğe bağlı bir view parametresi kabul eder:

• Atlanmış veya "default": geçerli çalışma zamanı davranışı. agents.defaults.models yapılandırılmışsa yanıt, provider/* girdileri için dinamik olarak keşfedilmiş modeller dahil olmak üzere izin verilen katalogdur. Aksi halde yanıt, tam Gateway kataloğudur.
• "configured": seçici boyutunda davranış. agents.defaults.models yapılandırılmışsa, provider/* girdileri için sağlayıcı kapsamlı keşif dahil olmak üzere yine önceliklidir. İzin listesi olmadan yanıt, açık models.providers.*.models girdilerini kullanır ve yalnızca yapılandırılmış model satırı yoksa tam kataloğa geri döner.
• "all": agents.defaults.models öğesini atlayarak tam Gateway kataloğu. Bunu normal model seçiciler için değil, tanılama ve keşif kullanıcı arayüzleri için kullanın.

Exec onayları

• Bir exec isteği onay gerektirdiğinde Gateway exec.approval.requested yayınlar.
• Operatör istemcileri exec.approval.resolve çağırarak çözer (operator.approvals kapsamı gerektirir).
• host=node için exec.approval.request, systemRunPlan içermelidir (kanonik argv/cwd/rawCommand/oturum meta verileri). systemRunPlan eksik olan istekler reddedilir.
• Onaydan sonra iletilen node.invoke system.run çağrıları, bu kanonik systemRunPlan öğesini yetkili komut/cwd/oturum bağlamı olarak yeniden kullanır.
• Bir çağıran, hazırlama ile nihai onaylı system.run iletimi arasında command, rawCommand, cwd, agentId veya sessionKey değerini değiştirirse Gateway, değiştirilen yüke güvenmek yerine çalıştırmayı reddeder.

Aracı teslimat geri dönüşü

• agent istekleri, dışa teslimat istemek için deliver=true içerebilir.
• bestEffortDeliver=false katı davranışı korur: çözümlenemeyen veya yalnızca dahili teslimat hedefleri INVALID_REQUEST döndürür.
• bestEffortDeliver=true, harici olarak teslim edilebilir hiçbir rota çözümlenemediğinde oturumla sınırlı yürütmeye geri dönüşe izin verir (örneğin dahili/webchat oturumları veya belirsiz çok kanallı yapılandırmalar).
• Nihai agent sonuçları, teslimat istendiğinde result.deliveryStatus içerebilir; openclaw agent --json --deliver için belgelenen aynı sent, suppressed, partial_failed ve failed durumlarını kullanır.

Sürümleme

• PROTOCOL_VERSION, packages/gateway-protocol/src/version.ts içinde bulunur.
• İstemciler minProtocol + maxProtocol gönderir; sunucu, kendi geçerli protokolünü içermeyen aralıkları reddeder. Geçerli istemciler ve sunucular protokol v4 gerektirir.
• Şemalar + modeller TypeBox tanımlarından oluşturulur:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

İstemci sabitleri

src/gateway/client.ts içindeki referans istemci bu varsayılanları kullanır. Değerler protokol v4 genelinde kararlıdır ve üçüncü taraf istemciler için beklenen taban çizgisidir.

Sunucu, etkin policy.tickIntervalMs, policy.maxPayload ve policy.maxBufferedBytes değerlerini hello-ok içinde duyurur; istemciler el sıkışma öncesi varsayılanlar yerine bu değerlere uymalıdır.

Kimlik Doğrulama

• Paylaşılan gizli anahtarlı gateway kimlik doğrulaması, yapılandırılmış kimlik doğrulama moduna bağlı olarak connect.params.auth.token veya connect.params.auth.password kullanır.
• Tailscale Serve gibi kimlik taşıyan modlar (gateway.auth.allowTailscale: true) veya loopback olmayan gateway.auth.mode: "trusted-proxy", bağlanma kimlik doğrulaması denetimini connect.params.auth.* yerine istek başlıklarından karşılar.
• Özel giriş gateway.auth.mode: "none", paylaşılan gizli anahtarlı bağlanma kimlik doğrulamasını tamamen atlar; bu modu herkese açık/güvenilmeyen girişlerde açığa çıkarmayın.
• Eşleştirmeden sonra Gateway, bağlantı rolü + kapsamlarıyla sınırlı bir cihaz belirteci yayınlar. Bu belirteç hello-ok.auth.deviceToken içinde döndürülür ve istemci tarafından gelecekteki bağlantılar için kalıcı olarak saklanmalıdır.
• İstemciler, başarılı herhangi bir bağlantıdan sonra birincil hello-ok.auth.deviceToken değerini kalıcı olarak saklamalıdır.
• Bu saklanmış cihaz belirteciyle yeniden bağlanmak, o belirteç için saklanmış onaylı kapsam kümesini de yeniden kullanmalıdır. Bu, daha önce verilmiş olan okuma/sondalama/durum erişimini korur ve yeniden bağlantıların sessizce daha dar örtük yalnızca yönetici kapsamına düşmesini önler.
• İstemci tarafı bağlanma kimlik doğrulaması derlemesi (src/gateway/client.ts içindeki selectConnectAuth):
  • auth.password bağımsızdır ve ayarlandığında her zaman iletilir.
  • auth.token öncelik sırasıyla doldurulur: önce açık paylaşılan belirteç, sonra açık bir deviceToken, ardından saklanmış cihaz başına belirteç (deviceId + role ile anahtarlanır).
  • auth.bootstrapToken, yalnızca yukarıdakilerin hiçbiri bir auth.token çözemediğinde gönderilir. Paylaşılan belirteç veya çözümlenen herhangi bir cihaz belirteci onu bastırır.
  • Tek seferlik AUTH_TOKEN_MISMATCH yeniden denemesinde saklanmış bir cihaz belirtecinin otomatik yükseltilmesi yalnızca güvenilir uç noktalarla sınırlıdır — loopback veya sabitlenmiş tlsFingerprint ile wss://. Sabitleme olmadan herkese açık wss:// uygun değildir.
• Yerleşik kurulum kodu bootstrap işlemi, birincil düğüm hello-ok.auth.deviceToken değerini ve güvenilir mobil devretme için hello-ok.auth.deviceTokens içinde sınırlı bir operatör belirtecini döndürür. Operatör belirteci, yerel Talk yapılandırması okumaları için operator.talk.secrets içerir, ancak eşleştirme mutasyonu kapsamlarını ve operator.admin kapsamını hariç tutar.
• Temel olmayan bir kurulum kodu bootstrap işlemi onay beklerken, PAIRING_REQUIRED ayrıntıları recommendedNextStep: "wait_then_retry", retryable: true ve pauseReconnect: false içerir. İstemciler, istek onaylanana veya belirteç geçersiz hale gelene kadar aynı bootstrap belirteciyle yeniden bağlanmayı sürdürmelidir.
• hello-ok.auth.deviceTokens değerini yalnızca bağlantı wss:// veya loopback/yerel eşleştirme gibi güvenilir bir aktarımda bootstrap kimlik doğrulaması kullandığında kalıcı olarak saklayın.
• Bir istemci açık bir deviceToken veya açık scopes sağlarsa, çağıranın istediği bu kapsam kümesi yetkili kalır; önbelleğe alınmış kapsamlar yalnızca istemci saklanmış cihaz başına belirteci yeniden kullandığında yeniden kullanılır.
• Cihaz belirteçleri device.token.rotate ve device.token.revoke ile döndürülebilir/iptal edilebilir (operator.pairing kapsamı gerekir). Bir düğüm veya başka bir operatör dışı rolü döndürmek ya da iptal etmek ayrıca operator.admin gerektirir.
• device.token.rotate, döndürme meta verilerini döndürür. Yerine geçen taşıyıcı belirteci yalnızca halihazırda o cihaz belirteciyle kimlik doğrulaması yapılmış aynı cihaz çağrıları için yansıtır; böylece yalnızca belirteç kullanan istemciler yeniden bağlanmadan önce yenisini kalıcı olarak saklayabilir. Paylaşılan/yönetici döndürmeleri taşıyıcı belirteci yansıtmaz.
• Belirteç yayınlama, döndürme ve iptal işlemleri, ilgili cihazın eşleştirme girdisine kaydedilmiş onaylı rol kümesiyle sınırlı kalır; belirteç mutasyonu, eşleştirme onayının hiç vermediği bir cihaz rolünü genişletemez veya hedefleyemez.
• Eşleştirilmiş cihaz belirteci oturumlarında, çağıranın ayrıca operator.admin kapsamı yoksa cihaz yönetimi kendi kapsamıyla sınırlıdır: yönetici olmayan çağıranlar yalnızca kendi cihaz girdileri için operatör belirtecini yönetebilir. Düğüm ve diğer operatör dışı belirteç yönetimi, çağıranın kendi cihazı için bile yalnızca yöneticilere açıktır.
• device.token.rotate ve device.token.revoke, hedef operatör belirteci kapsam kümesini çağıranın mevcut oturum kapsamlarına karşı da denetler. Yönetici olmayan çağıranlar, zaten sahip olduklarından daha geniş bir operatör belirtecini döndüremez veya iptal edemez.
• Kimlik doğrulama hataları error.details.code ve kurtarma ipuçları içerir:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• AUTH_TOKEN_MISMATCH için istemci davranışı:
  • Güvenilir istemciler, önbelleğe alınmış cihaz başına belirteçle bir sınırlı yeniden deneme yapabilir.
  • Bu yeniden deneme başarısız olursa, istemciler otomatik yeniden bağlanma döngülerini durdurmalı ve operatör eylemi rehberliğini göstermelidir.
• AUTH_SCOPE_MISMATCH, cihaz belirtecinin tanındığı ancak istenen rol/kapsamları kapsamadığı anlamına gelir. İstemciler bunu hatalı belirteç olarak sunmamalıdır; operatörden yeniden eşleştirme yapmasını veya daha dar/daha geniş kapsam sözleşmesini onaylamasını istemelidir.

Cihaz kimliği + eşleştirme

• Düğümler, anahtar çifti parmak izinden türetilmiş kararlı bir cihaz kimliği (device.id) içermelidir.
• Gateway'ler cihaz + rol başına belirteç yayınlar.
• Yerel otomatik onay etkinleştirilmemişse yeni cihaz kimlikleri için eşleştirme onayları gerekir.
• Eşleştirme otomatik onayı, doğrudan local loopback bağlantılarına odaklanır.
• OpenClaw ayrıca güvenilir paylaşılan gizli anahtar yardımcı akışları için dar bir backend/konteyner yerel kendi kendine bağlanma yoluna sahiptir.
• Aynı ana bilgisayar tailnet veya LAN bağlantıları eşleştirme için hâlâ uzak olarak değerlendirilir ve onay gerektirir.
• WS istemcileri normalde connect sırasında device kimliği içerir (operatör + düğüm). Cihazsız operatör için tek istisnalar açık güven yollarıdır:
  • Yalnızca localhost güvenli olmayan HTTP uyumluluğu için gateway.controlUi.allowInsecureAuth=true.
  • Başarılı gateway.auth.mode: "trusted-proxy" operatör Control UI kimlik doğrulaması.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (acil durum, ciddi güvenlik düşüşü).
  • Ayrılmış dahili yardımcı yoldaki direct-loopback gateway-client backend RPC'leri.
• Cihaz kimliğini atlamanın kapsam sonuçları vardır. Cihazsız bir operatör bağlantısına açık bir güven yolu üzerinden izin verildiğinde bile OpenClaw, bu yolun adlandırılmış bir kapsam koruma istisnası yoksa kendi beyan ettiği kapsamları boş kümeye temizler. Kapsam kapılı yöntemler daha sonra missing scope ile başarısız olur.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true, Control UI acil durum kapsam koruma yoludur. Rastgele özel backend veya CLI biçimli WebSocket istemcilerine kapsam vermez.
• Ayrılmış direct-loopback gateway-client backend yardımcı yolu, kapsamları yalnızca dahili yerel kontrol düzlemi RPC'leri için korur; özel backend kimlikleri bu istisnayı almaz.
• Tüm bağlantılar, sunucunun sağladığı connect.challenge nonce değerini imzalamalıdır.

Cihaz kimlik doğrulaması geçiş tanıları

Hâlâ challenge öncesi imzalama davranışı kullanan eski istemciler için, connect artık kararlı bir error.details.reason ile error.details.code altında DEVICE_AUTH_* ayrıntı kodları döndürür.

Yaygın geçiş hataları:

Geçiş hedefi:

• Her zaman connect.challenge için bekleyin.
• Sunucu nonce değerini içeren v2 yükünü imzalayın.
• Aynı nonce değerini connect.params.device.nonce içinde gönderin.
• Tercih edilen imza yükü v3 değeridir; bu, cihaz/istemci/rol/kapsamlar/belirteç/nonce alanlarına ek olarak platform ve deviceFamily değerlerini de bağlar.
• Eski v2 imzaları uyumluluk için kabul edilmeye devam eder, ancak eşleştirilmiş cihaz meta verisi sabitlemesi yeniden bağlantıda komut politikasını hâlâ kontrol eder.

TLS + sabitleme

• TLS, WS bağlantıları için desteklenir.
• İstemciler isteğe bağlı olarak gateway sertifika parmak izini sabitleyebilir (gateway.tls yapılandırmasına ve gateway.remote.tlsFingerprint veya CLI --tls-fingerprint değerine bakın).

Kapsam

Bu protokol tam gateway API'sini açığa çıkarır (durum, kanallar, modeller, sohbet, ajan, oturumlar, düğümler, onaylar vb.). Tam yüzey packages/gateway-protocol/src/schema.ts içindeki TypeBox şemaları tarafından tanımlanır.

İlgili

• Köprü protokolü
• Gateway çalışma kitabı