Gateway protokolü (WebSocket)
Gateway WS protokolü, OpenClaw için tek denetim düzlemi + düğüm taşımasıdır. Tüm istemciler (CLI, web UI, macOS uygulaması, iOS/Android düğümleri, başsız düğümler) WebSocket üzerinden bağlanır ve el sıkışma sırasında rollerini + kapsamlarını bildirir.Taşıma
- WebSocket, JSON yükleri içeren metin çerçeveleri.
- İlk çerçeve zorunlu olarak bir
connectisteği olmalıdır.
El sıkışma (connect)
Gateway → İstemci (bağlantı öncesi challenge):
hello-ok ayrıca şunları içerir:
hello-ok.auth, deviceTokens içinde ek sınırlı rol girdileri de içerebilir:
scopes: [] olarak kalır ve devredilen herhangi bir operatör token’ı bootstrap
operatör izin listesiyle sınırlı kalır (operator.approvals, operator.read,
operator.talk.secrets, operator.write). Bootstrap kapsam denetimleri
rol önekli kalır: operatör girdileri yalnızca operatör isteklerini karşılar ve
operatör olmayan rollerin kendi rol önekleri altında yine kapsamları olması gerekir.
Düğüm örneği
Çerçeveleme
- İstek:
{type:"req", id, method, params} - Yanıt:
{type:"res", id, ok, payload|error} - Olay:
{type:"event", event, payload, seq?, stateVersion?}
Roller + kapsamlar
Roller
operator= denetim düzlemi istemcisi (CLI/UI/otomasyon).node= yetenek barındırıcısı (camera/screen/canvas/system.run).
Kapsamlar (operator)
Yaygın kapsamlar:
operator.readoperator.writeoperator.adminoperator.approvalsoperator.pairingoperator.talk.secrets
talk.config içinde includeSecrets: true, operator.talk.secrets
(veya operator.admin) gerektirir.
Plugin kaydıyla eklenen gateway RPC yöntemleri kendi operatör kapsamını isteyebilir, ancak
ayrılmış çekirdek yönetici önekleri (config.*, exec.approvals.*, wizard.*,
update.*) her zaman operator.admin olarak çözülür.
Yöntem kapsamı yalnızca ilk geçittir. Bazı slash komutları
chat.send üzerinden ulaşıldığında bunun üzerine daha katı komut düzeyi denetimleri uygular. Örneğin kalıcı
/config set ve /config unset yazmaları operator.admin gerektirir.
node.pair.approve ayrıca temel yöntem kapsamına ek olarak ek bir onay zamanı kapsam denetimi içerir:
- komutsuz istekler:
operator.pairing execolmayan düğüm komutlu istekler:operator.pairing+operator.writesystem.run,system.run.prepareveyasystem.whichiçeren istekler:operator.pairing+operator.admin
caps/commands/permissions (node)
Düğümler bağlantı anında yetenek beyanlarını bildirir:
caps: üst düzey yetenek kategorileri.commands:invokeiçin komut izin listesi.permissions: ayrıntılı açma/kapama anahtarları (ör.screen.record,camera.capture).
Presence
system-presence, cihaz kimliğine göre anahtarlanmış girdiler döndürür.- Presence girdileri
deviceId,rolesvescopesiçerir; böylece kullanıcı arayüzleri bir cihaz hem operator hem de node olarak bağlandığında bile cihaz başına tek satır gösterebilir.
Yaygın RPC yöntem aileleri
Bu sayfa oluşturulmuş tam bir döküm değildir, ancak genel WS yüzeyi yukarıdaki el sıkışma/kimlik doğrulama örneklerinden daha geniştir. Bunlar Gateway’in bugün sunduğu başlıca yöntem aileleridir.hello-ok.features.methods, src/gateway/server-methods-list.ts ile yüklenen plugin/kanal yöntem dışa aktarımlarından oluşturulan muhafazakâr bir keşif listesidir.
Bunu özellik keşfi olarak değerlendirin; src/gateway/server-methods/*.ts içinde uygulanan her çağrılabilir yardımcı işlevin oluşturulmuş tam dökümü olarak değil.
Sistem ve kimlik
health, önbelleğe alınmış veya yeni yoklanmış gateway sağlık anlık görüntüsünü döndürür.status,/statusbenzeri gateway özetini döndürür; hassas alanlar yalnızca yönetici kapsamlı operator istemcilerine dahil edilir.gateway.identity.get, relay ve eşleştirme akışlarında kullanılan gateway cihaz kimliğini döndürür.system-presence, bağlı operator/node cihazları için geçerli presence anlık görüntüsünü döndürür.system-event, bir sistem olayı ekler ve presence bağlamını güncelleyebilir/yayınlayabilir.last-heartbeat, en son kalıcılaştırılmış heartbeat olayını döndürür.set-heartbeats, gateway üzerinde heartbeat işlemeyi açar/kapatır.
Modeller ve kullanım
models.list, çalışma zamanında izin verilen model kataloğunu döndürür.usage.status, sağlayıcı kullanım pencerelerini/kalan kota özetlerini döndürür.usage.cost, bir tarih aralığı için birleştirilmiş maliyet kullanım özetlerini döndürür.doctor.memory.status, etkin varsayılan ajan çalışma alanı için vektör bellek / embedding hazırlığını döndürür.sessions.usage, oturum başına kullanım özetlerini döndürür.sessions.usage.timeseries, tek bir oturum için zaman serisi kullanımını döndürür.sessions.usage.logs, tek bir oturum için kullanım günlüğü girdilerini döndürür.
Kanallar ve giriş yardımcıları
channels.status, yerleşik + paketlenmiş kanal/plugin durum özetlerini döndürür.channels.logout, kanal çıkışı destekliyorsa belirli bir kanal/hesap için oturumu kapatır.web.login.start, mevcut QR destekli web kanal sağlayıcısı için bir QR/web giriş akışı başlatır.web.login.wait, bu QR/web giriş akışının tamamlanmasını bekler ve başarı durumunda kanalı başlatır.push.test, kayıtlı bir iOS düğümüne test APNs push’u gönderir.voicewake.get, depolanan uyandırma kelimesi tetikleyicilerini döndürür.voicewake.set, uyandırma kelimesi tetikleyicilerini günceller ve değişikliği yayınlar.
Mesajlaşma ve günlükler
send, sohbet çalıştırıcısı dışındaki kanal/hesap/konu hedefli gönderimler için doğrudan giden teslim RPC’sidir.logs.tail, imleç/sınır ve en fazla bayt denetimleriyle yapılandırılmış gateway dosya günlüğü sonunu döndürür.
Talk ve TTS
talk.config, etkin Talk yapılandırma yükünü döndürür;includeSecrets,operator.talk.secrets(veyaoperator.admin) gerektirir.talk.mode, WebChat/Control UI istemcileri için geçerli Talk modu durumunu ayarlar/yayınlar.talk.speak, etkin Talk konuşma sağlayıcısı üzerinden konuşma sentezler.tts.status, TTS etkin durumunu, etkin sağlayıcıyı, yedek sağlayıcıları ve sağlayıcı yapılandırma durumunu döndürür.tts.providers, görünür TTS sağlayıcı envanterini döndürür.tts.enablevetts.disable, TTS tercih durumunu açar/kapatır.tts.setProvider, tercih edilen TTS sağlayıcısını günceller.tts.convert, tek seferlik metinden konuşmaya dönüşüm çalıştırır.
Secrets, yapılandırma, update ve wizard
secrets.reload, etkin SecretRef’leri yeniden çözümler ve çalışma zamanı secret durumunu yalnızca tam başarıda değiştirir.secrets.resolve, belirli bir komut/hedef kümesi için komut hedefli secret atamalarını çözümler.config.get, geçerli yapılandırma anlık görüntüsünü ve hash’ini döndürür.config.set, doğrulanmış bir yapılandırma yükü yazar.config.patch, kısmi bir yapılandırma güncellemesini birleştirir.config.apply, tam yapılandırma yükünü doğrular + değiştirir.config.schema, Control UI ve CLI araçları tarafından kullanılan canlı yapılandırma şeması yükünü döndürür: şema,uiHints, sürüm ve üretim meta verisi, buna çalışma zamanı yükleyebildiğinde plugin + kanal şeması meta verisi de dahildir. Şema, kullanıcı arayüzü tarafından kullanılan aynı etiketlerden ve yardım metninden türetilen alantitle/descriptionmeta verisini içerir; buna eşleşen alan belgeleri mevcut olduğunda iç içe nesne, joker karakter, dizi öğesi veanyOf/oneOf/allOfbileşim dalları da dahildir.config.schema.lookup, tek bir yapılandırma yolu için yol kapsamlı bir arama yükü döndürür: normalized yol, sığ bir şema düğümü, eşleşenhint+hintPathve UI/CLI ayrıntılı inceleme için hemen alt çocuk özetleri.- Arama şema düğümleri kullanıcıya dönük belgeleri ve yaygın doğrulama alanlarını korur:
title,description,type,enum,const,format,pattern, sayısal/string/dizi/nesne sınırları veadditionalProperties,deprecated,readOnly,writeOnlygibi boolean bayraklar. - Çocuk özetleri
key, normalizedpath,type,required,hasChildrenile eşleşenhint/hintPathdeğerlerini gösterir.
- Arama şema düğümleri kullanıcıya dönük belgeleri ve yaygın doğrulama alanlarını korur:
update.run, gateway update akışını çalıştırır ve yalnızca update işleminin kendisi başarılıysa yeniden başlatma zamanlar.wizard.start,wizard.next,wizard.statusvewizard.cancel, onboarding wizard’ını WS RPC üzerinden sunar.
Mevcut büyük aileler
Ajan ve çalışma alanı yardımcıları
agents.list, yapılandırılmış ajan girdilerini döndürür.agents.create,agents.updateveagents.delete, ajan kayıtlarını ve çalışma alanı bağlantılarını yönetir.agents.files.list,agents.files.getveagents.files.set, bir ajan için açılan bootstrap çalışma alanı dosyalarını yönetir.agent.identity.get, bir ajan veya oturum için etkin asistan kimliğini döndürür.agent.wait, bir çalıştırmanın bitmesini bekler ve mevcutsa son durum anlık görüntüsünü döndürür.
Oturum denetimi
sessions.list, geçerli oturum dizinini döndürür.sessions.subscribevesessions.unsubscribe, geçerli WS istemcisi için oturum değişikliği olay aboneliklerini açar/kapatır.sessions.messages.subscribevesessions.messages.unsubscribe, tek bir oturum için transcript/mesaj olay aboneliklerini açar/kapatır.sessions.preview, belirli oturum anahtarları için sınırlı transcript önizlemeleri döndürür.sessions.resolve, bir oturum hedefini çözümler veya kanonikleştirir.sessions.create, yeni bir oturum girdisi oluşturur.sessions.send, mevcut bir oturuma mesaj gönderir.sessions.steer, etkin bir oturum için kes-ve-yönlendir varyantıdır.sessions.abort, bir oturum için etkin işleri durdurur.sessions.patch, oturum meta verilerini/override’larını günceller.sessions.reset,sessions.deletevesessions.compact, oturum bakım işlemlerini yürütür.sessions.get, depolanan tam oturum satırını döndürür.- sohbet yürütmesi yine de
chat.history,chat.send,chat.abortvechat.injectkullanır. chat.history, UI istemcileri için gösterim-normalized’dir: satır içi directive etiketleri görünür metinden kaldırılır, düz metin tool-call XML yükleri (<tool_call>...</tool_call>,<function_call>...</function_call>,<tool_calls>...</tool_calls>,<function_calls>...</function_calls>ve kırpılmış tool-call blokları dahil) ve sızdırılmış ASCII/tam genişlikte model kontrol token’ları kaldırılır, tam olarakNO_REPLY/no_replygibi yalnızca sessiz token içeren asistan satırları atlanır ve aşırı büyük satırlar yer tutucularla değiştirilebilir.
Cihaz eşleştirme ve cihaz token’ları
device.pair.list, bekleyen ve onaylanmış eşleştirilmiş cihazları döndürür.device.pair.approve,device.pair.rejectvedevice.pair.remove, cihaz eşleştirme kayıtlarını yönetir.device.token.rotate, onaylanmış rol ve kapsam sınırları içinde eşleştirilmiş bir cihaz token’ını döndürür.device.token.revoke, eşleştirilmiş bir cihaz token’ını iptal eder.
Düğüm eşleştirme, invoke ve bekleyen işler
node.pair.request,node.pair.list,node.pair.approve,node.pair.rejectvenode.pair.verify, düğüm eşleştirme ve bootstrap doğrulamayı kapsar.node.listvenode.describe, bilinen/bağlı düğüm durumunu döndürür.node.rename, eşleştirilmiş bir düğüm etiketini günceller.node.invoke, bir komutu bağlı bir düğüme iletir.node.invoke.result, bir invoke isteğinin sonucunu döndürür.node.event, düğüm kaynaklı olayları tekrar gateway’e taşır.node.canvas.capability.refresh, kapsamlı canvas yetenek token’larını yeniler.node.pending.pullvenode.pending.ack, bağlı düğüm kuyruk API’leridir.node.pending.enqueuevenode.pending.drain, çevrimdışı/bağlantısız düğümler için kalıcı bekleyen işleri yönetir.
Onay aileleri
exec.approval.requestveexec.approval.resolve, tek seferlik exec onay isteklerini kapsar.exec.approval.waitDecision, tek bir bekleyen exec onayını bekler ve son kararı döndürür (veya zaman aşımındanull).exec.approvals.getveexec.approvals.set, gateway exec onay ilke anlık görüntülerini yönetir.exec.approvals.node.getveexec.approvals.node.set, düğüm yerel exec onay ilkesini düğüm relay komutları üzerinden yönetir.plugin.approval.request,plugin.approval.waitDecisionveplugin.approval.resolve, plugin tanımlı onay akışlarını kapsar.
Diğer büyük aileler
- otomasyon:
wake, anında veya sonraki heartbeat için metin ekleme zamanlarcron.list,cron.status,cron.add,cron.update,cron.remove,cron.run,cron.runs
- skills/tools:
skills.*,tools.catalog,tools.effective
Yaygın olay aileleri
chat:chat.injectve diğer yalnızca transcript sohbet olayları gibi UI sohbet güncellemeleri.session.messagevesession.tool: abone olunan bir oturum için transcript/olay akışı güncellemeleri.sessions.changed: oturum dizini veya meta veri 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ırması/iş değişikliği olayı.shutdown: gateway kapanış bildirimi.node.pair.requested/node.pair.resolved: düğüm eşleştirme yaşam döngüsü.node.invoke.request: düğüm invoke isteği yayını.device.pair.requested/device.pair.resolved: eşleştirilmiş cihaz yaşam döngüsü.voicewake.changed: uyandırma kelimesi 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 denetimleri için geçerli skill çalıştırılabilir dosyaları listesini almak üzere
skills.binsçağırabilir.
Operatör yardımcı yöntemleri
- Operatörler, bir ajanın çalışma zamanı tool kataloğunu almak için
tools.catalog(operator.read) çağırabilir. Yanıt gruplanmış tools ve kaynak meta verisi içerir:source:coreveyapluginpluginId:source="plugin"olduğunda plugin sahibioptional: bir plugin tool’unun isteğe bağlı olup olmadığı
- Operatörler, bir oturum için çalışma zamanında etkin tool
envanterini almak üzere
tools.effective(operator.read) çağırabilir.sessionKeygereklidir.- Gateway, çağıranın sağladığı kimlik doğrulama veya teslim bağlamını kabul etmek yerine güvenilir çalışma zamanı bağlamını oturumdan sunucu tarafında türetir.
- Yanıt oturum kapsamlıdır ve etkin konuşmanın şu anda kullanabileceği şeyi yansıtır; buna çekirdek, plugin ve kanal tools da dahildir.
- Operatörler, bir ajan için görünür
skill envanterini almak üzere
skills.status(operator.read) çağırabilir.agentIdisteğe bağlıdır; varsayılan ajan çalışma alanını okumak için bunu atlayın.- Yanıt uygunluk, eksik gereksinimler, yapılandırma denetimleri ve ham secret değerlerini açığa çıkarmadan temizlenmiş kurulum seçenekleri içerir.
- Operatörler, ClawHub keşif meta verisi için
skills.searchveskills.detail(operator.read) çağırabilir. - Operatörler,
skills.install(operator.admin) yöntemini iki modda çağırabilir:- ClawHub modu:
{ source: "clawhub", slug, version?, force? }, bir skill klasörünü varsayılan ajan çalışma alanıskills/dizinine kurar. - Gateway installer modu:
{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }gateway ana makinesinde tanımlanmış birmetadata.openclaw.installeylemi çalıştırır.
- ClawHub modu:
- Operatörler,
skills.update(operator.admin) yöntemini iki modda çağırabilir:- ClawHub modu, varsayılan ajan çalışma alanındaki bir izlenen slug’ı veya tüm izlenen ClawHub kurulumlarını günceller.
- Yapılandırma modu,
skills.entries.<skillKey>değerlerini (enabled,apiKeyveenvgibi) patch eder.
Exec onayları
- Bir exec isteği onay gerektirdiğinde gateway
exec.approval.requestedyayınlar. - Operatör istemcileri
exec.approval.resolveçağırarak çözümler (operator.approvalskapsamı gerekir). host=nodeiçinexec.approval.request,systemRunPlaniçermelidir (kanonikargv/cwd/rawCommand/oturum meta verisi).systemRunPlaneksik istekler reddedilir.- Onaydan sonra iletilen
node.invoke system.runçağrıları, bu kanoniksystemRunPlandeğerini yetkili komut/cwd/oturum bağlamı olarak yeniden kullanır. - Bir çağıran hazırlık ile son onaylı
system.runiletimi arasındacommand,rawCommand,cwd,agentIdveyasessionKeydeğerlerini değiştirirse gateway, değiştirilen yüke güvenmek yerine çalıştırmayı reddeder.
Ajan teslim geri dönüşü
agentistekleri giden teslim istemek içindeliver=trueiçerebilir.bestEffortDeliver=false, katı davranışı korur: çözümlenmemiş veya yalnızca dahili teslim hedefleriINVALID_REQUESTdöndürür.bestEffortDeliver=true, harici teslim edilebilir bir rota çözümlenemediğinde oturum-only yürütmeye geri dönüşe izin verir (örneğin dahili/webchat oturumları veya belirsiz çok kanallı yapılandırmalar).
Sürümleme
PROTOCOL_VERSION,src/gateway/protocol/schema.tsiçinde bulunur.- İstemciler
minProtocol+maxProtocolgönderir; sunucu uyumsuzlukları reddeder. - Şemalar + modeller TypeBox tanımlarından üretilir:
pnpm protocol:genpnpm protocol:gen:swiftpnpm protocol:check
Kimlik doğrulama
- Paylaşılan secret gateway kimlik doğrulaması, yapılandırılmış auth moduna bağlı olarak
connect.params.auth.tokenveyaconnect.params.auth.passwordkullanır. - Tailscale Serve
(
gateway.auth.allowTailscale: true) veya loopback dışıgateway.auth.mode: "trusted-proxy"gibi kimlik taşıyan modlar,connect.params.auth.*yerine istek başlıklarından gelen bağlantı auth denetimini karşılar. - Özel giriş
gateway.auth.mode: "none", paylaşılan secret bağlantı auth’unu tamamen atlar; bu modu genel/güvenilmeyen girişte açmayın. - Eşleştirmeden sonra Gateway, bağlantı
rolü + kapsamlarına sınırlı bir cihaz token’ı verir. Bu,
hello-ok.auth.deviceTokeniçinde döner ve istemci tarafından gelecekteki bağlantılar için kalıcılaştırılmalıdır. - İstemciler, başarılı herhangi bir bağlantıdan sonra birincil
hello-ok.auth.deviceTokendeğerini kalıcılaştırmalıdır. - Bu depolanan cihaz token’ıyla yeniden bağlanma, o token için depolanan onaylı kapsam kümesini de yeniden kullanmalıdır. Bu, zaten verilmiş okuma/yoklama/status erişimini korur ve yeniden bağlantıların daha dar örtük bir yönetici-only kapsama sessizce düşmesini önler.
- Normal bağlantı auth önceliği şu şekildedir: önce açık paylaşılan token/parola, sonra
açık
deviceToken, sonra cihaz başına depolanan token, sonra bootstrap token. - Ek
hello-ok.auth.deviceTokensgirdileri bootstrap devir token’larıdır. Bunları yalnızca bağlantıwss://veya loopback/yerel eşleştirme gibi güvenilir bir taşıma üzerinde bootstrap auth kullandıysa kalıcılaştırın. - Bir istemci açık bir
deviceTokenveya açıkscopessağlarsa bu çağıranın istediği kapsam kümesi yetkili kalır; önbelleğe alınmış kapsamlar yalnızca istemci depolanan cihaz başına token’ı yeniden kullanıyorsa yeniden kullanılır. - Cihaz token’ları
device.token.rotatevedevice.token.revokeile döndürülebilir/iptal edilebilir (operator.pairingkapsamı gerekir). - Token verme/döndürme, o cihazın eşleştirme girdisinde kaydedilmiş onaylı rol kümesine sınırlı kalır; bir token’ı döndürmek cihazı eşleştirme onayının hiç vermediği bir role genişletemez.
- Eşleştirilmiş cihaz token oturumları için, çağıranın ayrıca
operator.adminkapsamı yoksa cihaz yönetimi öz-kapsamlıdır: yönetici olmayan çağıranlar yalnızca kendi cihaz girdilerini kaldırabilir/iptal edebilir/döndürebilir. device.token.rotate, istenen operatör kapsam kümesini çağıranın geçerli oturum kapsamlarına göre de denetler. Yönetici olmayan çağıranlar bir token’ı hâlihazırda sahip olduklarından daha geniş bir operatör kapsam kümesine döndüremez.- Kimlik doğrulama hataları
error.details.codeile birlikte 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_MISMATCHiçin istemci davranışı:- Güvenilen istemciler, önbelleğe alınmış cihaz başına token ile 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 eylem rehberliği göstermelidir.
Cihaz kimliği + eşleştirme
- Düğümler, bir anahtar çifti fingerprint’inden türetilmiş kararlı bir cihaz kimliği (
device.id) içermelidir. - Gateway’ler cihaz + rol başına token verir.
- Yerel otomatik onay etkin değilse yeni cihaz kimlikleri için eşleştirme onayı gerekir.
- Eşleştirme otomatik onayı doğrudan yerel loopback bağlantıları etrafında merkezlenmiştir.
- OpenClaw ayrıca güvenilen paylaşılan secret yardımcı akışları için dar bir backend/container yerel self-connect yoluna da sahiptir.
- Aynı ana makine üzerindeki tailnet veya LAN bağlantıları hâlâ uzak kabul edilir ve eşleştirme için onay gerektirir.
- Tüm WS istemcileri
connectsırasındadevicekimliği içermelidir (operator+node). Control UI bunu yalnızca şu modlarda atlayabilir:- localhost-only güvensiz HTTP uyumluluğu için
gateway.controlUi.allowInsecureAuth=true. - başarılı
gateway.auth.mode: "trusted-proxy"operator Control UI auth. gateway.controlUi.dangerouslyDisableDeviceAuth=true(acil durum cam kırma, ciddi güvenlik düşüşü).
- localhost-only güvensiz HTTP uyumluluğu için
- Tüm bağlantılar sunucu tarafından sağlanan
connect.challengenonce’unu imzalamalıdır.
Cihaz kimlik doğrulama geçiş tanılamaları
Hâlâ challenge öncesi imzalama davranışını kullanan eski istemciler içinconnect,
şimdi error.details.reason altında kararlı bir error.details.reason ile error.details.code içinde
DEVICE_AUTH_* ayrıntı kodları döndürür.
Yaygın geçiş hataları:
| Mesaj | details.code | details.reason | Anlamı |
|---|---|---|---|
device nonce required | DEVICE_AUTH_NONCE_REQUIRED | device-nonce-missing | İstemci device.nonce değerini atladı (veya boş gönderdi). |
device nonce mismatch | DEVICE_AUTH_NONCE_MISMATCH | device-nonce-mismatch | İstemci eski/yanlış nonce ile imzaladı. |
device signature invalid | DEVICE_AUTH_SIGNATURE_INVALID | device-signature | İmza yükü v2 yüküyle eşleşmiyor. |
device signature expired | DEVICE_AUTH_SIGNATURE_EXPIRED | device-signature-stale | İmzalanan zaman damgası izin verilen sapmanın dışında. |
device identity mismatch | DEVICE_AUTH_DEVICE_ID_MISMATCH | device-id-mismatch | device.id, genel anahtar fingerprint’iyle eşleşmiyor. |
device public key invalid | DEVICE_AUTH_PUBLIC_KEY_INVALID | device-public-key | Genel anahtar biçimi/kanonikleştirmesi başarısız oldu. |
- Her zaman
connect.challengebekleyin. - Sunucu nonce’unu içeren v2 yükünü imzalayın.
- Aynı nonce’u
connect.params.device.nonceiçinde gönderin. - Tercih edilen imza yükü, device/client/role/scopes/token/nonce alanlarına ek olarak
platformvedeviceFamilybağlayanv3’tür. - Eski
v2imzaları uyumluluk için kabul edilmeye devam eder, ancak eşleştirilmiş cihaz meta veri sabitleme yine de yeniden bağlantıda komut ilkesini denetler.
TLS + sabitleme
- WS bağlantıları için TLS desteklenir.
- İstemciler isteğe bağlı olarak gateway sertifika fingerprint’ini sabitleyebilir (bkz.
gateway.tlsyapılandırması ilegateway.remote.tlsFingerprintveya CLI--tls-fingerprint).
Kapsam
Bu protokol tam gateway API’sini açar (status, channels, models, chat, agent, sessions, nodes, approvals, vb.). Tam yüzeysrc/gateway/protocol/schema.ts içindeki
TypeBox şemaları tarafından tanımlanır.