Protokol Gateway (WebSocket)
Protokol WS Gateway adalah control plane tunggal + transport node untuk OpenClaw. Semua klien (CLI, UI web, aplikasi macOS, node iOS/Android, node headless) terhubung melalui WebSocket dan mendeklarasikan peran + cakupan mereka pada saat handshake.Transport
- WebSocket, frame teks dengan payload JSON.
- Frame pertama harus berupa permintaan
connect.
Handshake (connect)
Gateway → Klien (tantangan pra-koneksi):server, features, snapshot, dan policy semuanya wajib menurut skema
(src/gateway/protocol/schema/frames.ts). canvasHostUrl bersifat opsional. auth
melaporkan peran/cakupan yang dinegosiasikan saat tersedia, dan menyertakan deviceToken
saat gateway menerbitkannya.
Saat tidak ada token perangkat yang diterbitkan, hello-ok.auth masih dapat melaporkan
izin yang dinegosiasikan:
hello-ok juga menyertakan:
hello-ok.auth juga dapat menyertakan entri peran
tambahan yang dibatasi dalam deviceTokens:
scopes: [] dan token operator yang di-handoff tetap dibatasi pada daftar izin operator bootstrap
(operator.approvals, operator.read,
operator.talk.secrets, operator.write). Pemeriksaan cakupan bootstrap tetap
berawalan peran: entri operator hanya memenuhi permintaan operator, dan peran
non-operator tetap memerlukan cakupan di bawah awalan perannya sendiri.
Contoh node
Framing
- Permintaan:
{type:"req", id, method, params} - Respons:
{type:"res", id, ok, payload|error} - Event:
{type:"event", event, payload, seq?, stateVersion?}
Peran + cakupan
Peran
operator= klien control plane (CLI/UI/otomasi).node= host kapabilitas (camera/screen/canvas/system.run).
Cakupan (operator)
Cakupan umum:operator.readoperator.writeoperator.adminoperator.approvalsoperator.pairingoperator.talk.secrets
talk.config dengan includeSecrets: true memerlukan operator.talk.secrets
(atau operator.admin).
Metode RPC gateway yang didaftarkan Plugin dapat meminta cakupan operatornya sendiri, tetapi
awalan admin inti yang dicadangkan (config.*, exec.approvals.*, wizard.*,
update.*) selalu diresolusikan ke operator.admin.
Cakupan metode hanyalah gerbang pertama. Beberapa perintah slash yang dicapai melalui
chat.send menerapkan pemeriksaan tingkat perintah yang lebih ketat di atasnya. Sebagai
contoh, penulisan persisten /config set dan /config unset memerlukan operator.admin.
node.pair.approve juga memiliki pemeriksaan cakupan tambahan pada saat persetujuan di atas
cakupan metode dasar:
- permintaan tanpa perintah:
operator.pairing - permintaan dengan perintah node non-exec:
operator.pairing+operator.write - permintaan yang menyertakan
system.run,system.run.prepare, atausystem.which:operator.pairing+operator.admin
Caps/commands/permissions (node)
Node mendeklarasikan klaim kapabilitas saat waktu connect:caps: kategori kapabilitas tingkat tinggi.commands: daftar izin perintah untuk invoke.permissions: toggle terperinci (misalnyascreen.record,camera.capture).
Kehadiran
system-presencemengembalikan entri yang dikunci oleh identitas perangkat.- Entri kehadiran mencakup
deviceId,roles, danscopesagar UI dapat menampilkan satu baris per perangkat bahkan saat perangkat terhubung sebagai operator dan node.
Keluarga metode RPC umum
Halaman ini bukan dump penuh yang dihasilkan, tetapi permukaan WS publik lebih luas daripada contoh handshake/auth di atas. Ini adalah keluarga metode utama yang diekspose Gateway saat ini.hello-ok.features.methods adalah daftar penemuan konservatif yang dibangun dari
src/gateway/server-methods-list.ts ditambah ekspor metode Plugin/channel yang dimuat.
Perlakukan ini sebagai penemuan fitur, bukan sebagai dump yang dihasilkan dari setiap helper yang dapat dipanggil
yang diimplementasikan di src/gateway/server-methods/*.ts.
Sistem dan identitas
healthmengembalikan snapshot kesehatan gateway yang di-cache atau baru diprobe.statusmengembalikan ringkasan gateway bergaya/status; field sensitif disertakan hanya untuk klien operator dengan cakupan admin.gateway.identity.getmengembalikan identitas perangkat gateway yang digunakan oleh alur relay dan pairing.system-presencemengembalikan snapshot kehadiran saat ini untuk perangkat operator/node yang terhubung.system-eventmenambahkan event sistem dan dapat memperbarui/menyiarkan konteks kehadiran.last-heartbeatmengembalikan event Heartbeat persisten terbaru.set-heartbeatsmengaktifkan atau menonaktifkan pemrosesan Heartbeat pada gateway.
Model dan penggunaan
models.listmengembalikan katalog model yang diizinkan saat runtime.usage.statusmengembalikan ringkasan jendela penggunaan/kuota tersisa penyedia.usage.costmengembalikan ringkasan penggunaan biaya agregat untuk rentang tanggal.doctor.memory.statusmengembalikan kesiapan vector-memory / embedding untuk workspace agen default yang aktif.sessions.usagemengembalikan ringkasan penggunaan per sesi.sessions.usage.timeseriesmengembalikan deret waktu penggunaan untuk satu sesi.sessions.usage.logsmengembalikan entri log penggunaan untuk satu sesi.
Channel dan helper login
channels.statusmengembalikan ringkasan status channel/Plugin bawaan + bundled.channels.logoutlogout dari channel/akun tertentu jika channel tersebut mendukung logout.web.login.startmemulai alur login QR/web untuk penyedia channel web saat ini yang mendukung QR.web.login.waitmenunggu alur login QR/web tersebut selesai dan memulai channel jika berhasil.push.testmengirim push APNs uji ke node iOS yang terdaftar.voicewake.getmengembalikan pemicu wake word yang tersimpan.voicewake.setmemperbarui pemicu wake word dan menyiarkan perubahannya.
Pesan dan log
sendadalah RPC pengiriman keluar langsung untuk pengiriman yang ditargetkan ke channel/akun/thread di luar chat runner.logs.tailmengembalikan tail file-log gateway yang dikonfigurasi dengan cursor/limit dan kontrol byte maksimum.
Talk dan TTS
talk.configmengembalikan payload konfigurasi Talk efektif;includeSecretsmemerlukanoperator.talk.secrets(atauoperator.admin).talk.modemenetapkan/menyiarkan status mode Talk saat ini untuk klien WebChat/Control UI.talk.speakmensintesis ucapan melalui penyedia speech Talk yang aktif.tts.statusmengembalikan status TTS aktif, penyedia aktif, penyedia fallback, dan status konfigurasi penyedia.tts.providersmengembalikan inventaris penyedia TTS yang terlihat.tts.enabledantts.disablemengaktifkan atau menonaktifkan status preferensi TTS.tts.setProvidermemperbarui penyedia TTS pilihan.tts.convertmenjalankan konversi text-to-speech sekali jalan.
Secret, config, update, dan wizard
secrets.reloadme-resolve ulang SecretRef aktif dan menukar state secret runtime hanya jika sepenuhnya berhasil.secrets.resolveme-resolve penetapan secret target perintah untuk kumpulan perintah/target tertentu.config.getmengembalikan snapshot config saat ini dan hash-nya.config.setmenulis payload config yang tervalidasi.config.patchmenggabungkan pembaruan config parsial.config.applymemvalidasi + mengganti seluruh payload config.config.schemamengembalikan payload skema config live yang digunakan oleh Control UI dan tooling CLI: skema,uiHints, versi, dan metadata generasi, termasuk metadata skema Plugin + channel saat runtime dapat memuatnya. Skema ini mencakup metadata fieldtitle/descriptionyang diturunkan dari label yang sama dan teks bantuan yang digunakan oleh UI, termasuk object bertingkat, wildcard, item array, dan cabang komposisianyOf/oneOf/allOfsaat dokumentasi field yang cocok tersedia.config.schema.lookupmengembalikan payload lookup berbatas path untuk satu path config: path yang dinormalisasi, node skema dangkal, hint yang cocok +hintPath, dan ringkasan child langsung untuk drill-down UI/CLI.- Node skema lookup mempertahankan dokumen yang menghadap pengguna dan field validasi umum:
title,description,type,enum,const,format,pattern, batas numerik/string/array/object, dan flag boolean sepertiadditionalProperties,deprecated,readOnly,writeOnly. - Ringkasan child mengekspose
key,pathyang dinormalisasi,type,required,hasChildren, ditambahhint/hintPathyang cocok.
- Node skema lookup mempertahankan dokumen yang menghadap pengguna dan field validasi umum:
update.runmenjalankan alur pembaruan gateway dan menjadwalkan restart hanya jika pembaruan itu sendiri berhasil.wizard.start,wizard.next,wizard.status, danwizard.cancelmengekspose wizard onboarding melalui WS RPC.
Keluarga utama yang sudah ada
Helper agen dan workspace
agents.listmengembalikan entri agen yang dikonfigurasi.agents.create,agents.update, danagents.deletemengelola rekaman agen dan wiring workspace.agents.files.list,agents.files.get, danagents.files.setmengelola file workspace bootstrap yang diekspose untuk sebuah agen.agent.identity.getmengembalikan identitas asisten efektif untuk sebuah agen atau sesi.agent.waitmenunggu sebuah run selesai dan mengembalikan snapshot terminal saat tersedia.
Kontrol sesi
sessions.listmengembalikan indeks sesi saat ini.sessions.subscribedansessions.unsubscribemengaktifkan atau menonaktifkan langganan event perubahan sesi untuk klien WS saat ini.sessions.messages.subscribedansessions.messages.unsubscribemengaktifkan atau menonaktifkan langganan event transkrip/pesan untuk satu sesi.sessions.previewmengembalikan pratinjau transkrip terbatas untuk key sesi tertentu.sessions.resolveme-resolve atau mengkanonisasi target sesi.sessions.createmembuat entri sesi baru.sessions.sendmengirim pesan ke sesi yang sudah ada.sessions.steeradalah varian interrupt-and-steer untuk sesi aktif.sessions.abortmembatalkan pekerjaan aktif untuk sebuah sesi.sessions.patchmemperbarui metadata/override sesi.sessions.reset,sessions.delete, dansessions.compactmelakukan pemeliharaan sesi.sessions.getmengembalikan baris sesi tersimpan lengkap.- eksekusi chat tetap menggunakan
chat.history,chat.send,chat.abort, danchat.inject. chat.historydinormalisasi untuk tampilan bagi klien UI: tag direktif inline dihapus dari teks yang terlihat, payload XML panggilan tool dalam plain-text (termasuk<tool_call>...</tool_call>,<function_call>...</function_call>,<tool_calls>...</tool_calls>,<function_calls>...</function_calls>, dan blok panggilan tool yang terpotong) serta token kontrol model ASCII/full-width yang bocor dihapus, baris asisten token senyap murni sepertiNO_REPLY/no_replyyang persis cocok dihilangkan, dan baris yang terlalu besar dapat diganti dengan placeholder.
Pairing perangkat dan token perangkat
device.pair.listmengembalikan perangkat berpasangan yang tertunda dan yang disetujui.device.pair.approve,device.pair.reject, dandevice.pair.removemengelola rekaman pairing perangkat.device.token.rotatemerotasi token perangkat berpasangan dalam batas peran dan cakupan yang telah disetujui.device.token.revokemencabut token perangkat berpasangan.
Pairing node, invoke, dan pekerjaan tertunda
node.pair.request,node.pair.list,node.pair.approve,node.pair.reject, dannode.pair.verifymencakup pairing node dan verifikasi bootstrap.node.listdannode.describemengembalikan status node yang diketahui/terhubung.node.renamememperbarui label node berpasangan.node.invokemeneruskan perintah ke node yang terhubung.node.invoke.resultmengembalikan hasil untuk permintaan invoke.node.eventmembawa event yang berasal dari node kembali ke gateway.node.canvas.capability.refreshme-refresh token kapabilitas canvas yang dibatasi cakupan.node.pending.pulldannode.pending.ackadalah API antrean node yang terhubung.node.pending.enqueuedannode.pending.drainmengelola pekerjaan tertunda yang tahan lama untuk node offline/tidak terhubung.
Keluarga approval
exec.approval.request,exec.approval.get,exec.approval.list, danexec.approval.resolvemencakup permintaan approval exec sekali jalan plus lookup/replay approval tertunda.exec.approval.waitDecisionmenunggu satu approval exec yang tertunda dan mengembalikan keputusan final (ataunullsaat timeout).exec.approvals.getdanexec.approvals.setmengelola snapshot kebijakan approval exec gateway.exec.approvals.node.getdanexec.approvals.node.setmengelola kebijakan approval exec lokal node melalui perintah relay node.plugin.approval.request,plugin.approval.list,plugin.approval.waitDecision, danplugin.approval.resolvemencakup alur approval yang didefinisikan Plugin.
Keluarga utama lainnya
- otomasi:
wakemenjadwalkan injeksi teks bangun segera atau pada Heartbeat berikutnyacron.list,cron.status,cron.add,cron.update,cron.remove,cron.run,cron.runs
- Skills/tools:
commands.list,skills.*,tools.catalog,tools.effective
Keluarga event umum
chat: pembaruan chat UI sepertichat.injectdan event chat lain yang hanya untuk transkrip.session.messagedansession.tool: pembaruan transkrip/aliran event untuk sesi yang dilanggan.sessions.changed: indeks sesi atau metadata berubah.presence: pembaruan snapshot kehadiran sistem.tick: event keepalive / liveness berkala.health: pembaruan snapshot kesehatan gateway.heartbeat: pembaruan aliran event Heartbeat.cron: event perubahan job/run Cron.shutdown: notifikasi gateway shutdown.node.pair.requested/node.pair.resolved: siklus hidup pairing node.node.invoke.request: siaran permintaan invoke node.device.pair.requested/device.pair.resolved: siklus hidup perangkat berpasangan.voicewake.changed: config pemicu wake word berubah.exec.approval.requested/exec.approval.resolved: siklus hidup approval exec.plugin.approval.requested/plugin.approval.resolved: siklus hidup approval Plugin.
Metode helper node
- Node dapat memanggil
skills.binsuntuk mengambil daftar executable skill saat ini untuk pemeriksaan auto-allow.
Metode helper operator
- Operator dapat memanggil
commands.list(operator.read) untuk mengambil inventaris perintah runtime untuk sebuah agen.agentIdbersifat opsional; hilangkan untuk membaca workspace agen default.scopemengontrol permukaan mana yang ditargetkannameutama:textmengembalikan token perintah teks utama tanpa awalan/nativedan jalur defaultbothmengembalikan nama native yang sadar penyedia saat tersedia
textAliasesmembawa alias slash yang persis seperti/modeldan/m.nativeNamemembawa nama perintah native yang sadar penyedia saat tersedia.providerbersifat opsional dan hanya memengaruhi penamaan native ditambah ketersediaan perintah Plugin native.includeArgs=falsemenghilangkan metadata argumen yang diserialisasi dari respons.
- Operator dapat memanggil
tools.catalog(operator.read) untuk mengambil katalog tool runtime untuk sebuah agen. Respons mencakup tool yang dikelompokkan dan metadata asal:source:coreataupluginpluginId: pemilik plugin saatsource="plugin"optional: apakah tool plugin bersifat opsional
- Operator dapat memanggil
tools.effective(operator.read) untuk mengambil inventaris tool efektif runtime untuk sebuah sesi.sessionKeywajib.- Gateway menurunkan konteks runtime tepercaya dari sesi di sisi server, bukan menerima auth atau konteks pengiriman yang disuplai pemanggil.
- Respons dibatasi pada sesi dan mencerminkan apa yang dapat digunakan percakapan aktif saat ini, termasuk tool core, plugin, dan channel.
- Operator dapat memanggil
skills.status(operator.read) untuk mengambil inventaris skill yang terlihat untuk sebuah agen.agentIdbersifat opsional; hilangkan untuk membaca workspace agen default.- Respons mencakup kelayakan, persyaratan yang belum terpenuhi, pemeriksaan config, dan opsi install yang telah disanitasi tanpa mengekspos nilai secret mentah.
- Operator dapat memanggil
skills.searchdanskills.detail(operator.read) untuk metadata penemuan ClawHub. - Operator dapat memanggil
skills.install(operator.admin) dalam dua mode:- Mode ClawHub:
{ source: "clawhub", slug, version?, force? }memasang folder skill ke direktoriskills/workspace agen default. - Mode installer gateway:
{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }menjalankan aksimetadata.openclaw.installyang dideklarasikan pada host gateway.
- Mode ClawHub:
- Operator dapat memanggil
skills.update(operator.admin) dalam dua mode:- Mode ClawHub memperbarui satu slug yang dilacak atau semua instalasi ClawHub yang dilacak di workspace agen default.
- Mode config menambal nilai
skills.entries.<skillKey>sepertienabled,apiKey, danenv.
Approval exec
- Saat permintaan exec memerlukan approval, gateway menyiarkan
exec.approval.requested. - Klien operator me-resolve dengan memanggil
exec.approval.resolve(memerlukan cakupanoperator.approvals). - Untuk
host=node,exec.approval.requestharus menyertakansystemRunPlan(metadataargv/cwd/rawCommand/sesi kanonis). Permintaan yang tidak memilikisystemRunPlanakan ditolak. - Setelah approval, panggilan
node.invoke system.runyang diteruskan menggunakan kembalisystemRunPlankanonis tersebut sebagai konteks perintah/cwd/sesi yang otoritatif. - Jika pemanggil mengubah
command,rawCommand,cwd,agentId, atausessionKeyantara prepare dan penerusansystem.runfinal yang disetujui, gateway menolak eksekusi alih-alih memercayai payload yang telah diubah.
Fallback pengiriman agen
- Permintaan
agentdapat menyertakandeliver=trueuntuk meminta pengiriman keluar. bestEffortDeliver=falsemempertahankan perilaku ketat: target pengiriman yang tidak ter-resolve atau hanya internal mengembalikanINVALID_REQUEST.bestEffortDeliver=truememungkinkan fallback ke eksekusi hanya-sesi saat tidak ada rute pengiriman eksternal yang dapat di-resolve (misalnya sesi internal/webchat atau config multi-channel yang ambigu).
Pembuatan versi
PROTOCOL_VERSIONberada disrc/gateway/protocol/schema/protocol-schemas.ts.- Klien mengirim
minProtocol+maxProtocol; server menolak ketidakcocokan. - Skema + model dihasilkan dari definisi TypeBox:
pnpm protocol:genpnpm protocol:gen:swiftpnpm protocol:check
Konstanta klien
Klien referensi disrc/gateway/client.ts menggunakan default ini. Nilai-nilai ini
stabil di seluruh protokol v3 dan merupakan baseline yang diharapkan untuk klien pihak ketiga.
| Konstanta | Default | Sumber |
|---|---|---|
PROTOCOL_VERSION | 3 | src/gateway/protocol/schema/protocol-schemas.ts |
| Timeout permintaan (per RPC) | 30_000 ms | src/gateway/client.ts (requestTimeoutMs) |
| Timeout preauth / connect-challenge | 10_000 ms | src/gateway/handshake-timeouts.ts (clamp 250–10_000) |
| Backoff reconnect awal | 1_000 ms | src/gateway/client.ts (backoffMs) |
| Backoff reconnect maksimum | 30_000 ms | src/gateway/client.ts (scheduleReconnect) |
| Clamp retry cepat setelah penutupan device-token | 250 ms | src/gateway/client.ts |
Grace force-stop sebelum terminate() | 250 ms | FORCE_STOP_TERMINATE_GRACE_MS |
Timeout default stopAndWait() | 1_000 ms | STOP_AND_WAIT_TIMEOUT_MS |
Interval tick default (pra hello-ok) | 30_000 ms | src/gateway/client.ts |
| Penutupan karena timeout tick | kode 4000 saat senyap melebihi tickIntervalMs * 2 | src/gateway/client.ts |
MAX_PAYLOAD_BYTES | 25 * 1024 * 1024 (25 MB) | src/gateway/server-constants.ts |
policy.tickIntervalMs, policy.maxPayload,
dan policy.maxBufferedBytes efektif dalam hello-ok; klien harus mematuhi nilai tersebut
alih-alih default pra-handshake.
Auth
- Autentikasi gateway dengan shared secret menggunakan
connect.params.auth.tokenatauconnect.params.auth.password, bergantung pada mode auth yang dikonfigurasi. - Mode yang membawa identitas seperti Tailscale Serve
(
gateway.auth.allowTailscale: true) ataugateway.auth.mode: "trusted-proxy"non-loopback memenuhi pemeriksaan auth connect dari header permintaan, bukan dariconnect.params.auth.*. gateway.auth.mode: "none"untuk private-ingress sepenuhnya melewati auth connect berbasis shared secret; jangan ekspose mode tersebut pada ingress publik/tidak tepercaya.- Setelah pairing, Gateway menerbitkan token perangkat yang dibatasi ke peran + cakupan
koneksi. Token ini dikembalikan di
hello-ok.auth.deviceTokendan harus dipersistenkan oleh klien untuk koneksi berikutnya. - Klien harus mempersistenkan
hello-ok.auth.deviceTokenutama setelah setiap koneksi berhasil. - Saat terhubung ulang dengan token perangkat yang tersimpan itu, klien juga harus menggunakan kembali kumpulan cakupan tersetujui yang tersimpan untuk token tersebut. Ini mempertahankan akses baca/probe/status yang sudah diberikan dan mencegah reconnect diam-diam menyusut ke cakupan implicit admin-only yang lebih sempit.
- Perakitan auth connect sisi klien (
selectConnectAuthdisrc/gateway/client.ts):auth.passwordbersifat ortogonal dan selalu diteruskan saat disetel.auth.tokendiisi dalam urutan prioritas: shared token eksplisit terlebih dahulu, laludeviceTokeneksplisit, lalu token per perangkat yang tersimpan (dikunci olehdeviceId+role).auth.bootstrapTokendikirim hanya saat tidak satu pun dari yang di atas menghasilkanauth.token. Shared token atau token perangkat apa pun yang berhasil di-resolve akan menekannya.- Auto-promotion token perangkat tersimpan pada retry sekali jalan
AUTH_TOKEN_MISMATCHdibatasi hanya untuk endpoint tepercaya — loopback, atauwss://dengantlsFingerprintyang dipin.wss://publik tanpa pinning tidak memenuhi syarat.
- Entri tambahan
hello-ok.auth.deviceTokensadalah token handoff bootstrap. Persistenkan hanya jika koneksi menggunakan auth bootstrap pada transport tepercaya sepertiwss://atau loopback/local pairing. - Jika klien menyuplai
deviceTokeneksplisit atauscopeseksplisit, kumpulan cakupan yang diminta pemanggil tersebut tetap menjadi otoritatif; cakupan cache hanya digunakan kembali saat klien menggunakan ulang token per perangkat yang tersimpan. - Token perangkat dapat dirotasi/dicabut melalui
device.token.rotatedandevice.token.revoke(memerlukan cakupanoperator.pairing). - Penerbitan/rotasi token tetap dibatasi pada kumpulan peran tersetujui yang tercatat dalam entri pairing perangkat tersebut; merotasi token tidak dapat memperluas perangkat ke peran yang tidak pernah diberikan oleh persetujuan pairing.
- Untuk sesi token perangkat berpasangan, manajemen perangkat dibatasi ke diri sendiri kecuali
pemanggil juga memiliki
operator.admin: pemanggil non-admin hanya dapat menghapus/mencabut/merotasi entri perangkat miliknya sendiri. device.token.rotatejuga memeriksa kumpulan cakupan operator yang diminta terhadap cakupan sesi pemanggil saat ini. Pemanggil non-admin tidak dapat merotasi token ke kumpulan cakupan operator yang lebih luas daripada yang sudah mereka miliki.- Kegagalan auth menyertakan
error.details.codeplus petunjuk pemulihan:error.details.canRetryWithDeviceToken(boolean)error.details.recommendedNextStep(retry_with_device_token,update_auth_configuration,update_auth_credentials,wait_then_retry,review_auth_configuration)
- Perilaku klien untuk
AUTH_TOKEN_MISMATCH:- Klien tepercaya dapat mencoba satu retry terbatas dengan token per perangkat yang di-cache.
- Jika retry itu gagal, klien harus menghentikan loop reconnect otomatis dan menampilkan panduan tindakan operator.
Identitas perangkat + pairing
- Node harus menyertakan identitas perangkat yang stabil (
device.id) yang diturunkan dari fingerprint keypair. - Gateway menerbitkan token per perangkat + peran.
- Persetujuan pairing diperlukan untuk ID perangkat baru kecuali auto-approval lokal diaktifkan.
- Auto-approval pairing berpusat pada koneksi loopback lokal langsung.
- OpenClaw juga memiliki jalur self-connect backend/kontainer-lokal yang sempit untuk alur helper shared secret tepercaya.
- Koneksi tailnet atau LAN host yang sama tetap diperlakukan sebagai koneksi remote untuk pairing dan memerlukan persetujuan.
- Semua klien WS harus menyertakan identitas
deviceselamaconnect(operator + node). Control UI hanya dapat menghilangkannya dalam mode ini:gateway.controlUi.allowInsecureAuth=trueuntuk kompatibilitas HTTP tidak aman khusus localhost.- auth operator Control UI
gateway.auth.mode: "trusted-proxy"yang berhasil. gateway.controlUi.dangerouslyDisableDeviceAuth=true(break-glass, penurunan keamanan yang parah).
- Semua koneksi harus menandatangani nonce
connect.challengeyang diberikan server.
Diagnostik migrasi auth perangkat
Untuk klien lama yang masih menggunakan perilaku penandatanganan pra-challenge,connect kini mengembalikan
kode detail DEVICE_AUTH_* di bawah error.details.code dengan error.details.reason yang stabil.
Kegagalan migrasi umum:
| Pesan | details.code | details.reason | Arti |
|---|---|---|---|
device nonce required | DEVICE_AUTH_NONCE_REQUIRED | device-nonce-missing | Klien tidak menyertakan device.nonce (atau mengirim kosong). |
device nonce mismatch | DEVICE_AUTH_NONCE_MISMATCH | device-nonce-mismatch | Klien menandatangani dengan nonce yang basi/salah. |
device signature invalid | DEVICE_AUTH_SIGNATURE_INVALID | device-signature | Payload tanda tangan tidak cocok dengan payload v2. |
device signature expired | DEVICE_AUTH_SIGNATURE_EXPIRED | device-signature-stale | Timestamp yang ditandatangani berada di luar skew yang diizinkan. |
device identity mismatch | DEVICE_AUTH_DEVICE_ID_MISMATCH | device-id-mismatch | device.id tidak cocok dengan fingerprint kunci publik. |
device public key invalid | DEVICE_AUTH_PUBLIC_KEY_INVALID | device-public-key | Format/kanonisasi kunci publik gagal. |
- Selalu tunggu
connect.challenge. - Tanda tangani payload v2 yang menyertakan nonce server.
- Kirim nonce yang sama di
connect.params.device.nonce. - Payload tanda tangan yang disarankan adalah
v3, yang mengikatplatformdandeviceFamilyselain field device/client/role/scopes/token/nonce. - Tanda tangan
v2lama tetap diterima untuk kompatibilitas, tetapi pinning metadata perangkat berpasangan tetap mengontrol kebijakan perintah saat reconnect.
TLS + pinning
- TLS didukung untuk koneksi WS.
- Klien dapat secara opsional mem-pin fingerprint sertifikat gateway (lihat config
gateway.tlsplusgateway.remote.tlsFingerprintatau CLI--tls-fingerprint).
Cakupan
Protokol ini mengekspos API gateway lengkap (status, channel, model, chat, agent, sesi, node, approval, dll.). Permukaan tepatnya didefinisikan oleh skema TypeBox disrc/gateway/protocol/schema.ts.