Protokol Gateway

Gateway protokol WS adalah bidang kontrol tunggal dan transportasi Node untuk OpenClaw. Klien operator dan Node (CLI, UI web, aplikasi macOS, Node iOS/Android, Node headless) terhubung melalui WebSocket dan mendeklarasikan peran serta cakupan saat handshake.

Paket npm

Paket-paket ini disertakan dalam rangkaian rilis OpenClaw. Selama peluncuran awal, npm mungkin mengembalikan E404 hingga rilis pertama yang memuat paket dipublikasikan.

• @openclaw/gateway-protocol memublikasikan skema, validator, tipe TypeScript, pembantu frame dan galat yang ringan, serta konstanta versi. Tarball-nya menyertakan kontrak yang dapat dibaca mesin protocol.schema.json yang dihasilkan.
• @openclaw/gateway-client memublikasikan klien Node referensi dan titik masuk yang aman untuk peramban di @openclaw/gateway-client/browser.

Untuk panduan siklus hidup aplikasi, lihat Membangun klien Gateway. Untuk aplikasi yang mengawasi Gateway sebagai proses anak, lihat Menyematkan OpenClaw.

Transportasi dan framing

• WebSocket, frame teks, payload JSON.
• Frame pertama harus berupa permintaan connect.
• Frame prapenyambungan dibatasi hingga 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). Setelah handshake, ikuti hello-ok.policy.maxPayload dan hello-ok.policy.maxBufferedBytes. Dengan diagnostik diaktifkan, frame masuk yang terlalu besar dan buffer keluar yang lambat memancarkan peristiwa payload.large sebelum gateway menutup atau membuang frame. Peristiwa ini membawa surface, ukuran byte, batas, dan kode alasan yang aman, tetapi tidak pernah memuat isi pesan, konten lampiran, byte frame mentah, token, cookie, atau rahasia.

Bentuk frame:

• Permintaan: {type:"req", id, method, params}
• Respons: {type:"res", id, ok, payload|error}
• Peristiwa: {type:"event", event, payload, seq?, stateVersion?}

Galat respons menggunakan { code, message, details?, retryable?, retryAfterMs? }. Klien sebaiknya membuat percabangan berdasarkan code dan details.code; message tetap dapat dibaca manusia dan dapat berubah, kecuali jika catatan kompatibilitas menyatakan sebaliknya. Kegagalan otorisasi tingkat metode menggunakan code: "FORBIDDEN" tingkat atas dengan detail cakupan yang tidak tersedia secara terstruktur:

• Cakupan tidak tersedia: { code: "MISSING_SCOPE", missingScope, requiredScopes }. requiredScopes adalah kumpulan lengkap cakupan yang diketahui untuk operasi yang diminta. Pesan lama missing scope: <scope> dipertahankan untuk klien lama.

Klien sebaiknya membaca details terlebih dahulu dan menggunakan pesan lama hanya sebagai fallback kompatibilitas. readMissingScopeError dan readMissingScopeErrorDetails diekspor dari @openclaw/gateway-protocol/gateway-error-details; klien gateway yang aman untuk peramban mengekspornya kembali dari @openclaw/gateway-client/browser.

Skema diekspor sebagai GatewayErrorDetailsSchema, MissingScopeErrorDetailsSchema dari @openclaw/gateway-protocol/schema. Kegagalan cakupan HTTP mencerminkan objek MISSING_SCOPE di bawah error.details dan menggunakan status HTTP 403.

Metode yang menimbulkan efek samping memerlukan kunci idempotensi (lihat skema).

Handshake

Gateway mengirimkan tantangan prapenyambungan:

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

Klien membalas dengan connect:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "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 merespons dengan hello-ok:

{  "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    }  }}

server, features, snapshot, policy, dan auth semuanya diwajibkan oleh HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts). auth melaporkan peran/cakupan yang dinegosiasikan meskipun tidak ada token perangkat yang diterbitkan (bentuk di atas). pluginSurfaceUrls bersifat opsional dan memetakan nama permukaan plugin (mis. canvas) ke URL terhosting dengan cakupan; URL tersebut dapat kedaluwarsa, sehingga Node memanggil node.pluginSurface.refresh dengan { "surface": "canvas" } untuk mendapatkan entri baru. Jalur canvasHostUrl / canvasCapability / node.canvas.capability.refresh yang tidak digunakan lagi tidak didukung; gunakan permukaan plugin. appliedConfigHash opsional pada snapshot adalah revisi konfigurasi sumber yang telah diuraikan dan diterima oleh runtime Gateway aktif. Klien dapat membandingkannya dengan config.get.configRevisionHash untuk menentukan apakah konfigurasi tersimpan yang lebih baru masih memerlukan mulai ulang. config.get.hash tetap menjadi revisi berkas akar mentah yang digunakan oleh pelindung konflik penulisan konfigurasi.

Saat gateway masih menyelesaikan sidecar startup, connect dapat mengembalikan galat UNAVAILABLE yang dapat dicoba ulang dengan details.reason: "startup-sidecars" dan retryAfterMs. Coba ulang dalam anggaran koneksi Anda, alih-alih menganggapnya sebagai kegagalan handshake terminal.

Saat token perangkat diterbitkan, hello-ok.auth menambahkannya:

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

Bootstrap kode QR/penyiapan bawaan adalah jalur serah terima seluler. Koneksi kode penyiapan dasar yang berhasil mengembalikan satu token Node utama ditambah satu token operator terbatas:

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

Serah terima operator ini sengaja dibatasi: cukup untuk memulai loop operator seluler dan penyiapan native, termasuk operator.talk.secrets untuk pembacaan konfigurasi Talk, tetapi tanpa cakupan mutasi pemasangan dan tanpa operator.admin. Akses pemasangan/admin yang lebih luas memerlukan pemasangan atau alur token terpisah yang disetujui. Persistenkan hello-ok.auth.deviceTokens hanya ketika autentikasi bootstrap dijalankan melalui transportasi tepercaya (wss:// atau pemasangan loopback/lokal).

Klien backend dalam proses yang sama dan tepercaya (client.id: "gateway-client", client.mode: "backend") dapat menghilangkan device pada koneksi loopback langsung saat melakukan autentikasi dengan token/kata sandi gateway bersama. Jalur ini disediakan untuk RPC bidang kontrol internal (mis. pembaruan sesi subagen) dan mencegah dasar pemasangan CLI/perangkat yang usang memblokir pekerjaan backend lokal. Klien jarak jauh, berasal dari peramban, Node, dan klien token perangkat/identitas perangkat eksplisit tetap melalui pemeriksaan pemasangan serta peningkatan cakupan normal.

Peran worker dan protokol tertutup

Worker cloud menggunakan ingress loopback khusus melalui tunnel SSH milik gateway dengan kunci host yang disematkan. Ingress ini hanya menerima identitas worker dan tidak pernah meneruskan autentikasi umum, peristiwa Node, RPC operator, atau metode plugin. connect yang ketat memverifikasi kredensial berumur pendek dengan hash saat tersimpan yang terikat pada lingkungan, hash bundel, epoch pemilik, versi kumpulan RPC, kedaluwarsa, dan satu sesi yang dapat bernilai null; secara terpisah, kredensial ini memeriksa versi dan kumpulan fitur saat ini. Keberhasilan mengembalikan worker-hello-ok minimal; negosiasi fitur tidak bergantung pada versi protokol umum. Ukuran frame tetap di bawah 64 KiB, kecuali frame worker.inference.start yang dinegosiasikan dapat mencapai 25 MiB. Daftar izin tertutup berisi worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start, dan worker.inference.cancel.

Commit transkrip menggunakan fencing epoch pemilik, pengikatan sesi milik gateway, compare-and-swap daun dasar, serta pemutaran ulang urutan yang tahan lama; gateway menghasilkan entri transkrip dan ID induk melalui penulis sesi normal. Kepemilikan dan kedaluwarsa diperiksa ulang pada setiap RPC.

Kapabilitas klien

Klien operator dapat mengiklankan kapabilitas opsional dalam connect.params.caps:

• tool-events: menerima peristiwa siklus hidup alat yang terstruktur.
• inline-widgets: dapat merender hasil alat widget inline yang dihosting.

Kapabilitas klien menjelaskan klien yang terhubung, bukan otorisasi. Alat agen dapat mendeklarasikan kapabilitas yang diperlukan; Gateway menghilangkan alat tersebut kecuali setiap persyaratan muncul dalam caps milik klien asal. Eksekusi yang berasal dari saluran tidak memiliki kapabilitas klien Gateway, sehingga alat yang dibatasi kapabilitas tidak tersedia meskipun kebijakan alat secara eksplisit mengizinkannya.

Contoh koneksi Node

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "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": "…"    }  }}

Node mendeklarasikan klaim kapabilitas saat koneksi:

• caps: kategori tingkat tinggi seperti camera, canvas, screen, location, voice, talk.
• commands: daftar izin perintah untuk pemanggilan.
• permissions: sakelar terperinci (mis. screen.record, camera.capture).

Gateway memperlakukan ini sebagai klaim dan memberlakukan daftar izin di sisi server.

Peran dan cakupan

Untuk model cakupan operator lengkap, pemeriksaan saat persetujuan, dan semantik rahasia bersama, lihat Cakupan operator.

Peran:

• operator: klien bidang kontrol (CLI/UI/otomatisasi).
• node: host kapabilitas (kamera/layar/kanvas/system.run).
• worker: host eksekusi cloud pada protokol worker khusus yang tertutup.

Cakupan operator (src/gateway/operator-scopes.ts), kumpulan tertutup lengkap:

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

talk.config dengan includeSecrets: true memerlukan operator.talk.secrets (atau operator.admin). Saat rahasia disertakan, baca kredensial penyedia Talk aktif dari talk.resolved.config.apiKey; talk.providers.<id>.apiKey tetap berbentuk sumber dan dapat berupa objek SecretRef atau string yang disunting.

Metode RPC gateway yang didaftarkan plugin dapat meminta cakupan operatornya sendiri, tetapi prefiks inti yang dicadangkan ini selalu diuraikan menjadi operator.admin (src/shared/gateway-method-policy.ts): config.*, exec.approvals.*, wizard.*, update.*.

Cakupan metode hanyalah gerbang pertama. Beberapa perintah garis miring yang dicapai melalui chat.send menerapkan pemeriksaan tingkat perintah yang lebih ketat: penulisan persisten /config set dan /config unset memerlukan operator.admin, bahkan untuk klien gateway yang sudah memiliki cakupan operator yang lebih rendah.

node.pair.approve memiliki pemeriksaan cakupan tambahan saat persetujuan di atas cakupan metode dasar (operator.pairing), berdasarkan commands (src/infra/node-pairing-authz.ts) yang dideklarasikan oleh permintaan tertunda:

Kapabilitas/perintah/izin (node)

Node mendeklarasikan klaim kapabilitas saat terhubung:

• caps: kategori kapabilitas tingkat tinggi seperti camera, canvas, screen, location, voice, dan talk.
• commands: daftar izin perintah untuk pemanggilan.
• permissions: pengaturan terperinci (misalnya screen.record, camera.capture).

Gateway memperlakukan ini sebagai klaim dan memberlakukan daftar izin di sisi server. Node yang terhubung dapat menerbitkan deskriptor Plugin atau alat MCP opsional yang terlihat oleh agen dengan node.pluginTools.update setelah berhasil terhubung atau terhubung kembali. Host node tanpa antarmuka memulai ulang untuk menerapkan perubahan inventaris MCP deklaratif. Metode pembaruan ini adalah satu-satunya jalur penerbitan; deskriptor alat Plugin tidak diterima dalam parameter connect. Setiap deskriptor harus menggunakan name alat yang aman bagi penyedia dan menyebutkan command dalam daftar izin perintah node saat ini. Gateway memercayai metadata deskriptor dari node yang dipasangkan, memfilter deskriptor di luar permukaan perintah yang disetujui, menghapusnya saat node terputus, dan menolak upaya operator untuk mengubah katalog node lain. Atur gateway.nodes.pluginTools.enabled: false untuk mengabaikan deskriptor yang diterbitkan node.

Host node yang terhubung menerbitkan katalog pengganti skill lengkapnya dengan node.skills.update. Metode peran node ini adalah satu-satunya jalur penerbitan skill node; skill tidak diterima dalam parameter connect. Setiap deskriptor berisi nama yang aman, deskripsi, dan konten SKILL.md yang dibatasi. Gateway mengurai konten tersebut dengan pemuat Skills normal, menyertakannya dalam snapshot Skills agen selama node terhubung, dan menghapusnya saat terputus. Atur gateway.nodes.skills.enabled: false untuk mengabaikan Skills yang diterbitkan node.

Kehadiran

• system-presence mengembalikan entri yang dikunci berdasarkan identitas perangkat, termasuk deviceId, roles, dan scopes, sehingga UI dapat menampilkan satu baris per perangkat bahkan ketika perangkat terhubung sebagai operator dan node sekaligus.
• node.list mencakup lastSeenAtMs dan lastSeenReason opsional. Node yang terhubung melaporkan waktu koneksi saat ini dengan alasan connect; node yang dipasangkan juga dapat melaporkan kehadiran latar belakang yang persisten melalui peristiwa node tepercaya.

Node macOS native juga dapat mengirim peristiwa node.presence.activity yang diautentikasi dengan waktu input tidak aktif yang dibatasi. Gateway memperoleh stempel waktu aktivitas menggunakan waktunya sendiri, mengekspos Mac terhubung yang paling baru melalui node.list dan node.describe, serta menyiarkan pembaruan node.presence kepada klien dengan cakupan baca. Lihat Kehadiran komputer aktif untuk perilaku pemilihan, privasi, konteks model, dan perutean notifikasi.

Peristiwa node tetap aktif di latar belakang

Node memanggil node.event dengan event: "node.presence.alive" untuk mencatat bahwa node yang dipasangkan aktif selama pembangkitan latar belakang, tanpa menandainya sebagai terhubung:

{  "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 adalah enum tertutup: background, silent_push, bg_app_refresh, significant_location, manual, connect. Nilai yang tidak dikenal dinormalisasi menjadi background (src/shared/node-presence.ts). Peristiwa hanya dipersistenkan untuk sesi perangkat node yang diautentikasi; sesi tanpa perangkat atau tidak dipasangkan mengembalikan handled: false.

Gateway yang berhasil mengembalikan hasil terstruktur:

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

Gateway lama mungkin hanya mengembalikan { "ok": true } untuk node.event; perlakukan hal tersebut sebagai RPC yang diakui, bukan persistensi kehadiran yang tahan lama.

Pencakupan peristiwa siaran

Peristiwa siaran yang didorong server dibatasi berdasarkan cakupan sehingga sesi yang hanya memiliki cakupan pemasangan atau node tidak menerima konten sesi secara pasif (src/gateway/server-broadcast.ts):

• Bingkai percakapan, agen, dan hasil alat (peristiwa agent yang dialirkan, peristiwa hasil alat) memerlukan setidaknya operator.read. Sesi yang tidak memilikinya melewati bingkai ini sepenuhnya.
• Siaran plugin.* yang ditentukan Plugin secara default dibatasi untuk operator.write atau operator.admin; entri eksplisit seperti plugin.approval.requested / plugin.approval.resolved menggunakan operator.approvals sebagai gantinya.
• Peristiwa status/transportasi (heartbeat, presence, tick, siklus hidup sambung/putus) tetap tidak dibatasi agar kesehatan transportasi dapat diamati oleh setiap sesi yang diautentikasi.
• Keluarga peristiwa siaran yang tidak dikenal dibatasi berdasarkan cakupan secara default (gagal-tertutup) kecuali pengendali terdaftar secara eksplisit melonggarkannya.

Setiap koneksi klien mempertahankan nomor urut per kliennya sendiri, sehingga siaran tetap diurutkan secara monoton pada soket tersebut meskipun klien yang berbeda melihat subset aliran peristiwa terfilter cakupan yang berbeda.

Keluarga metode RPC

hello-ok.features.methods adalah daftar penemuan konservatif yang dibuat dari src/gateway/server-methods-list.ts ditambah ekspor metode Plugin/saluran yang dimuat—ini bukan dump yang dihasilkan dari setiap metode, dan beberapa metode (misalnya push.test, web.login.start, web.login.wait, sessions.usage) sengaja dikecualikan dari penemuan meskipun merupakan metode nyata yang dapat dipanggil. Perlakukan ini sebagai penemuan fitur, bukan enumerasi lengkap src/gateway/server-methods/*.ts.

Kelompok peristiwa umum

• chat: pembaruan obrolan UI seperti chat.inject dan peristiwa obrolan lain yang hanya ada dalam transkrip. Dalam protokol v4, payload delta membawa deltaText; message tetap menjadi snapshot kumulatif asisten. Penggantian nonprefiks menetapkan replace=true dan menggunakan deltaText sebagai teks pengganti.
• session.message, session.operation, session.tool: pembaruan transkrip, operasi sesi yang sedang berlangsung, dan aliran peristiwa untuk sesi yang dilanggani.
• session.approval: status sebenarnya persetujuan tertunda dan terminal yang telah disanitasi untuk pelanggan sesi persis yang secara eksplisit ikut serta. Persetujuan turunan menggunakan audiens leluhur yang dipersistenkan; peristiwa tidak pernah mengubah transkrip atau membangunkan agen.
• sessions.changed: indeks atau metadata sesi berubah.
• presence: pembaruan snapshot keberadaan sistem.
• tick: peristiwa keepalive/keaktifan berkala.
• health: pembaruan snapshot kesehatan Gateway.
• heartbeat: pembaruan aliran peristiwa Heartbeat.
• cron: peristiwa perubahan eksekusi/tugas Cron.
• shutdown: notifikasi penonaktifan Gateway.
• node.pair.requested / node.pair.resolved: siklus hidup pemasangan Node.
• node.invoke.request: penyiaran permintaan pemanggilan Node.
• device.pair.requested / device.pair.resolved: siklus hidup perangkat yang dipasangkan.
• voicewake.changed: konfigurasi pemicu kata aktivasi berubah.
• config.changed: penulisan konfigurasi dipersistenkan (payload membawa jalur konfigurasi, hash snapshot baru, dan stempel waktu—tidak pernah membawa isi konfigurasi). Berada dalam cakupan baca operator; klien menyegarkan melalui config.get.
• exec.approval.requested / exec.approval.resolved: siklus hidup persetujuan eksekusi.
• plugin.approval.requested / plugin.approval.resolved: siklus hidup persetujuan plugin.

Metode pembantu Node

Node dapat memanggil skills.bins untuk mengambil daftar executable Skills saat ini untuk pemeriksaan izin otomatis.

RPC buku besar audit

audit.activity.list memberikan kepada klien operator tampilan stabil dari yang terbaru atas metadata siklus hidup eksekusi agen, tindakan alat, dan pesan yang disertakan secara opsional. Metode ini memerlukan operator.read. Kueri mengecualikan catatan yang berusia lebih dari 30 hari, dan buku besar SQLite bersama dibatasi hingga 100,000 catatan. Baris kedaluwarsa dihapus saat Gateway dimulai, pemeliharaan setiap jam, dan penulisan berikutnya. Lihat Riwayat audit untuk model data dan semantik privasi.

• Parameter: agentId, sessionKey, atau runId persis yang bersifat opsional; kind opsional ("agent_run", "tool_action", atau "message"); status opsional ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked", atau "unknown"); direction pesan opsional ("inbound" atau "outbound") dan channel persis; batas milidetik Unix inklusif after / before yang bersifat opsional; limit opsional dari 1 hingga 500; dan string cursor opsional dari halaman sebelumnya.
• Hasil: { "events": AuditActivityEventV1[], "nextCursor"?: string }.

Union hasil V1 bernama memiliki skema terpisah untuk eksekusi agen, tindakan alat, pesan masuk, dan pesan keluar. Diskriminator eventType masing-masing adalah agent_run, tool_action, inbound_message, atau outbound_message; kind dan direction pesan tetap tersedia untuk pemfilteran dan tampilan. Setiap peristiwa memiliki schemaVersion: 1 bilangan bulat. Referensi identitas pesan menggunakan format hmac-sha256:v1:<32 hex key id>:<64 hex digest> yang persis; ID aktor pengirim kanal menggunakan format yang sama.

Semua varian mewajibkan eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor, dan redaction. Bidang varian adalah:

Enum pesan tertutup adalah:

• conversationKind: direct, group, channel, atau unknown.
• outcome masuk: completed, skipped, atau failed; reasonCode opsional: duplicate, reply_operation_active, reply_operation_aborted, fast_abort, plugin_bound_handled, plugin_bound_unavailable, plugin_bound_declined, plugin_bound_error, before_dispatch_handled, acp_dispatch_completed, acp_dispatch_failed, acp_dispatch_empty, atau acp_dispatch_aborted.
• outcome keluar: sent, suppressed, failed, atau unknown; reasonCode opsional: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook, atau no_visible_payload. Adaptor yang tidak mengembalikan identitas platform adalah unknown, karena efek samping eksternal tidak dapat dibuktikan tidak terjadi.
• deliveryKind: text, media, atau other; failureStage: platform_send, queue, atau unknown.

Bidang terminal saling berkorelasi, bukan opsional secara independen:

Setiap peristiwa aktivitas mencakup id peristiwa yang stabil, urutan ledger monotonik, urutan peristiwa sumber, stempel waktu, pelaku, tindakan, status, bilangan bulat schemaVersion: 1, dan redaction: "metadata_only". Rekaman eksekusi dan alat memerlukan asal-usul agen dan eksekusi serta dapat mencakup asal-usul sesi. Rekaman pesan dapat mencakup id agen dan eksekusi, tetapi secara sengaja tidak pernah mencakup sessionKey atau sessionId; karena itu, filter kueri sessionKey hanya berlaku untuk baris eksekusi dan alat. Peristiwa alat dapat mencakup id panggilan alat dan nama alat.

Rekaman pesan menggunakan message.inbound.processed atau message.outbound.finished dan menambahkan arah, saluran, jenis percakapan, hasil yang dinormalisasi, serta jenis pengiriman, tahap kegagalan, durasi, jumlah hasil, kode alasan, dan pseudonim akun/percakapan/pesan/target berkunci yang bersifat lokal untuk instalasi dan opsional. Pseudonim ini membantu korelasi, tetapi bukan anonimisasi: basis data status berisi kuncinya, sedangkan ekspor RPC dan CLI tidak. Ledger tidak menyimpan prompt, isi pesan, argumen alat, hasil alat, keluaran perintah, atau teks kesalahan mentah. Nilai sessionKey eksekusi/alat tetap berupa metadata korelasi mentah dan dapat menyematkan id akun platform atau rekan; rekaman pesan tidak menyertakan kunci sesi.

Untuk baris masuk, durationMs mengukur pengiriman inti hingga terminalnya dan resultCount menghitung muatan alat, pemblokiran, dan balasan dalam antrean yang telah difinalisasi. Untuk baris keluar, durationMs mencakup kepemilikan pengiriman hingga pengakuan, surat mati, atau rekonsiliasi (termasuk waktu tunggu dalam antrean), dan resultCount menghitung pengiriman fisik platform yang teridentifikasi. deliveryKind, jika ada, menjelaskan muatan efektif setelah hook dan perenderan; baris yang disupresi atau ambigu akibat crash tidak menyertakannya.

Cakupan pesan saat ini mencakup pesan masuk yang diterima dan mencapai pengiriman inti, termasuk hasil duplikat/terminal inti. Cakupan keluar menulis satu baris terminal per muatan balasan logis asli yang mencapai pengiriman bersama yang tahan lama; pemotongan dan fan-out adaptor diagregasikan dalam resultCount. Pengiriman dalam antrean yang dapat dicoba ulang atau ambigu hanya dicatat setelah pengakuan, surat mati, atau rekonsiliasi. Jalur lokal Plugin dan pengiriman langsung yang melewati batas bersama tersebut belum dicakup. Antrean pekerja terbatas bersifat upaya terbaik dan dapat menghilangkan rekaman saat terjadi kegagalan atau kejenuhan, sehingga permukaan ini bukan arsip kepatuhan tanpa kehilangan data.

Pencatatan aktif secara default dan dikendalikan oleh audit.enabled. Pencatatan pesan dikendalikan secara terpisah oleh audit.messages dan secara default bernilai "off". Saat pencatatan dinonaktifkan, audit.activity.list tetap menyajikan rekaman yang ditulis sebelumnya hingga kedaluwarsa.

Skema permintaan, hasil, dan AuditEvent dari audit.list yang dirilis tetap tidak berubah dan hanya mengembalikan rekaman eksekusi agen dan tindakan alat. Klien operator baru harus memanggil audit.activity.list saat Gateway mengiklankannya. Gateway lama dapat melaporkan unknown method: audit.activity.list atau, karena otorisasi mendahului pencarian metode dalam versi yang dirilis, missing scope: operator.admin terhadap permintaan dengan cakupan baca. Perlakukan yang terakhir sebagai ketiadaan metode hanya jika metode tersebut tidak diiklankan. Klien kemudian dapat mencoba ulang audit.list hanya jika filternya tidak memerlukan dukungan jenis pesan, arah, atau saluran.

Gunakan openclaw audit untuk kueri teks dan ekspor JSON terbatas.

RPC ledger tugas

Klien operator memeriksa dan membatalkan rekaman tugas latar belakang gateway melalui RPC ledger tugas (packages/gateway-protocol/src/schema/tasks.ts). RPC ini mengembalikan ringkasan tugas yang telah disanitasi, bukan status runtime mentah.

• tasks.list memerlukan operator.read.
  • Parameter: status opsional ("queued", "running", "completed", "failed", "cancelled", atau "timed_out") atau larik status tersebut, agentId opsional, sessionKey opsional, limit opsional dari 1 hingga 500, dan string cursor opsional.
  • Hasil: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get memerlukan operator.read.
  • Parameter: { "taskId": string }.
  • Hasil: { "task": TaskSummary }.
  • Id tugas yang tidak ditemukan mengembalikan bentuk kesalahan tidak ditemukan milik gateway.
• tasks.cancel memerlukan operator.write.
  • Parameter: { "taskId": string, "reason"?: string }.
  • Hasil: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found melaporkan apakah ledger memiliki tugas yang cocok. cancelled melaporkan apakah runtime menerima atau mencatat pembatalan.

TaskSummary mencakup id, status, dan metadata opsional: kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, stempel waktu, progres, ringkasan terminal, dan teks kesalahan yang telah disanitasi. agentId mengidentifikasi agen yang menjalankan tugas; sessionKey dan ownerKey mempertahankan konteks peminta dan kontrol.

Metode pembantu operator

• commands.list (operator.read) mengambil inventaris perintah runtime untuk sebuah agen.
  • agentId bersifat opsional; hilangkan untuk membaca ruang kerja agen default.
  • scope mengontrol permukaan yang ditargetkan oleh name utama: text mengembalikan token perintah teks utama tanpa / di awal; native dan jalur default both mengembalikan nama native yang mempertimbangkan penyedia jika tersedia.
  • textAliases membawa alias garis miring yang persis seperti /model dan /m.
  • nativeName membawa nama perintah native yang mempertimbangkan penyedia jika tersedia.
  • provider bersifat opsional dan hanya memengaruhi penamaan native serta ketersediaan perintah Plugin native.
  • includeArgs=false menghilangkan metadata argumen yang diserialisasi dari respons.
• tools.catalog (operator.read) mengambil katalog alat runtime untuk sebuah agen. Respons mencakup alat yang dikelompokkan dan metadata asal:
  • source: core atau plugin
  • pluginId: pemilik Plugin ketika source="plugin"
  • optional: apakah alat Plugin bersifat opsional
• tools.effective (operator.read) mengambil inventaris alat yang berlaku efektif saat runtime untuk sebuah sesi.
  • sessionKey wajib diisi.
  • Gateway memperoleh konteks runtime tepercaya dari sesi di sisi server alih-alih menerima konteks autentikasi atau pengiriman yang diberikan pemanggil.
  • Respons merupakan proyeksi inventaris aktif yang berasal dari server dan tercakup pada sesi, termasuk alat inti, Plugin, saluran, dan server MCP yang telah ditemukan.
  • tools.effective bersifat hanya-baca untuk MCP: ini dapat memproyeksikan katalog MCP sesi yang telah siap melalui kebijakan alat akhir, tetapi tidak membuat runtime MCP, menghubungkan transportasi, atau menerbitkan tools/list. Jika tidak ada katalog siap yang cocok, respons dapat menyertakan pemberitahuan seperti mcp-not-yet-connected, mcp-not-yet-listed, atau mcp-stale-catalog.
  • Entri alat efektif menggunakan source="core", source="plugin", source="channel", atau source="mcp".
• tools.invoke (operator.write) memanggil satu alat yang tersedia melalui jalur kebijakan Gateway yang sama seperti /tools/invoke.
  • name wajib diisi. args, sessionKey, agentId, confirm, dan idempotencyKey bersifat opsional.
  • Jika sessionKey dan agentId sama-sama ada, agen sesi yang diresolusikan harus cocok dengan agentId.
  • Pembungkus inti khusus pemilik seperti cron, gateway, dan nodes memerlukan identitas pemilik/admin (operator.admin) meskipun tools.invoke sendiri adalah operator.write.
  • Respons merupakan amplop yang ditujukan untuk SDK dengan bidang ok, toolName, output opsional, dan error bertipe. Penolakan persetujuan atau kebijakan mengembalikan ok:false dalam muatan alih-alih melewati Pipeline kebijakan alat Gateway.
• skills.status (operator.read) mengambil inventaris Skills yang terlihat untuk sebuah agen.
  • agentId bersifat opsional; hilangkan untuk membaca ruang kerja agen default.
  • Respons mencakup kelayakan, persyaratan yang belum terpenuhi, pemeriksaan konfigurasi, dan opsi instalasi yang disanitasi tanpa mengekspos nilai rahasia mentah.
• skills.search dan skills.detail (operator.read) mengembalikan metadata penemuan ClawHub.
• skills.upload.begin, skills.upload.chunk, dan skills.upload.commit (operator.admin) menyiapkan arsip skill privat sebelum menginstalnya. Ini adalah jalur unggah admin terpisah untuk klien tepercaya, bukan alur instalasi skill ClawHub normal, dan dinonaktifkan secara default kecuali skills.install.allowUploadedArchives diaktifkan.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) membuat unggahan yang terikat pada slug dan nilai force tersebut.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) menambahkan byte pada offset terdekode yang persis.
  • skills.upload.commit({ uploadId, sha256? }) memverifikasi ukuran akhir dan SHA-256. Commit hanya menyelesaikan unggahan; tindakan ini tidak menginstal skill.
  • Arsip skill yang diunggah adalah arsip zip yang berisi akar SKILL.md. Nama direktori internal arsip tidak pernah menentukan target instalasi.
• skills.install (operator.admin) memiliki tiga mode:
  • Mode ClawHub: { source: "clawhub", slug, version?, force? } menginstal sebuah folder skill ke direktori skills/ pada ruang kerja agen default.
  • Mode unggah: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } menginstal unggahan yang telah di-commit ke direktori skills/<slug> pada ruang kerja agen default. Slug dan nilai force harus cocok dengan permintaan skills.upload.begin awal. Ditolak kecuali skills.install.allowUploadedArchives diaktifkan; pengaturan ini tidak memengaruhi instalasi ClawHub.
  • Mode penginstal Gateway: { name, installId, timeoutMs? } menjalankan tindakan metadata.openclaw.install yang dideklarasikan pada host Gateway. Klien lama mungkin masih mengirim dangerouslyForceUnsafeInstall; bidang ini tidak digunakan lagi, hanya diterima untuk kompatibilitas protokol, dan diabaikan. Gunakan security.installPolicy untuk keputusan instalasi yang dimiliki operator.
• skills.update (operator.admin) memiliki dua mode:
  • Mode ClawHub memperbarui satu slug terlacak atau semua instalasi ClawHub terlacak di ruang kerja agen default.
  • Mode konfigurasi menambal nilai skills.entries.<skillKey> seperti enabled, apiKey, dan env.

Tampilan models.list

models.list menerima parameter view opsional (src/agents/model-catalog-visibility.ts):

• Dihilangkan atau "default": jika agents.defaults.modelPolicy.allow dikonfigurasi, responsnya adalah katalog yang diizinkan, termasuk model yang ditemukan secara dinamis untuk entri provider/*. Jika tidak, responsnya adalah katalog Gateway lengkap.
• "configured": perilaku berukuran pemilih. Jika agents.defaults.modelPolicy.allow dikonfigurasi, ini tetap diprioritaskan, termasuk penemuan yang tercakup pada penyedia untuk entri provider/*. Tanpa daftar izin, respons menggunakan entri models.providers.<provider>.models eksplisit, dengan kembali ke katalog lengkap hanya ketika tidak ada baris model yang dikonfigurasi.
• "provider-config": inventaris models.providers.*.models yang ditulis oleh sumber, terlepas dari daftar izin pemilih. Baris mencakup kapabilitas model publik dan ketersediaan yang mempertimbangkan rute, tetapi menghilangkan endpoint penyedia, materi autentikasi, dan konfigurasi permintaan runtime.
• "all": katalog Gateway lengkap, melewati agents.defaults.modelPolicy.allow. Gunakan untuk UI diagnostik/penemuan, bukan pemilih model normal.

Persetujuan eksekusi

• Ketika permintaan eksekusi memerlukan persetujuan, Gateway menyiarkan exec.approval.requested.
• Klien operator menyelesaikannya dengan memanggil exec.approval.resolve (memerlukan operator.approvals).
• Untuk host=node, exec.approval.request harus menyertakan systemRunPlan (metadata argv/cwd/rawCommand/sesi kanonis). Permintaan tanpa systemRunPlan ditolak.
• Setelah disetujui, panggilan node.invoke system.run yang diteruskan menggunakan kembali systemRunPlan kanonis tersebut sebagai konteks perintah/cwd/sesi yang otoritatif.
• Jika pemanggil mengubah command, rawCommand, cwd, agentId, atau sessionKey di antara persiapan dan penerusan system.run yang akhirnya disetujui, Gateway menolak eksekusi alih-alih memercayai muatan yang telah diubah.

Fallback pengiriman agen

• Permintaan agent dapat menyertakan deliver=true untuk meminta pengiriman keluar.
• bestEffortDeliver=false (default) mempertahankan perilaku ketat: target pengiriman yang tidak dapat diresolusikan atau hanya internal mengembalikan INVALID_REQUEST.
• bestEffortDeliver=true mengizinkan fallback ke eksekusi khusus sesi ketika tidak ada rute eksternal yang dapat dikirimi yang bisa diresolusikan (misalnya sesi internal/webchat atau konfigurasi multi-saluran yang ambigu).
• Hasil akhir agent dapat menyertakan result.deliveryStatus ketika pengiriman diminta, menggunakan status sent, suppressed, partial_failed, dan failed yang sama seperti yang didokumentasikan untuk openclaw agent --json --deliver.

Pembuatan versi

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION, dan MIN_PROBE_PROTOCOL_VERSION berada di packages/gateway-protocol/src/version.ts.
• Klien mengirim minProtocol + maxProtocol. Klien operator dan UI harus menyertakan protokol saat ini dalam rentang tersebut; klien dan server saat ini menjalankan protokol v4.
• Klien terautentikasi yang memiliki role: "node" dan client.mode: "node" dapat menggunakan protokol Node N-1 (saat ini v3). Probe mulai ulang ringan menggunakan jendela N-1 yang sama. Autentikasi perangkat, pemasangan, cakupan, kebijakan perintah, dan persetujuan eksekusi tidak berubah oleh jendela kompatibilitas ini. Kapabilitas dan perintah Node milik Plugin tidak diberikan hingga Node ditingkatkan ke protokol saat ini karena permukaan yang di-host bukan bagian dari kontrak N-1.
• Skema dan model dihasilkan dari definisi TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Konstanta klien

Implementasi klien referensi berada di packages/gateway-client/src/ (OpenClaw membungkusnya melalui fasad tipis src/gateway/client.ts). Nilai default ini stabil di seluruh protokol v4 dan merupakan dasar yang diharapkan untuk klien pihak ketiga.

Server mengumumkan policy.tickIntervalMs, policy.maxPayload, dan policy.maxBufferedBytes efektif dalam hello-ok; klien harus mengikuti nilai tersebut, bukan default sebelum handshake.

Klien referensi mengizinkan permintaan terbatas memiliki tenggat terkonfigurasinya ketika setiap permintaan tertunda memilikinya. Permintaan expectFinal tanpa timeoutMs terbatas, permintaan apa pun dengan timeoutMs: null, atau campuran permintaan terbatas dan tanpa batas membuat watchdog tick tetap aktif. Jika event masuk dan respons tetap tidak ada hingga melewati ambang batas waktu tick, klien menutup soket dengan kode 4000, menolak setiap permintaan tertunda, dan menghubungkan ulang. Klien tidak memutar ulang permintaan yang ditolak setelah menghubungkan ulang.

Autentikasi

• Autentikasi Gateway dengan rahasia bersama menggunakan connect.params.auth.token atau connect.params.auth.password, bergantung pada gateway.auth.mode yang dikonfigurasi ("none" | "token" | "password" | "trusted-proxy").
• Mode yang memuat identitas seperti Tailscale Serve (gateway.auth.allowTailscale: true) atau gateway.auth.mode: "trusted-proxy" non-loopback memenuhi pemeriksaan autentikasi koneksi dari header permintaan, bukan dari connect.params.auth.*.
• gateway.auth.mode: "none" ingress privat sepenuhnya melewati autentikasi koneksi dengan rahasia bersama; jangan mengekspos mode tersebut pada ingress publik/tidak tepercaya.
• Setelah pemasangan, Gateway menerbitkan token perangkat yang cakupannya dibatasi pada peran + cakupan koneksi, yang dikembalikan dalam hello-ok.auth.deviceToken. Klien harus menyimpannya setelah setiap koneksi yang berhasil.
• Saat menghubungkan ulang dengan token perangkat tersimpan tersebut, gunakan kembali juga kumpulan cakupan tersimpan yang telah disetujui untuk token itu. Hal ini mempertahankan akses baca/probe/status yang telah diberikan dan mencegah koneksi ulang secara diam-diam menyusut menjadi cakupan implisit yang lebih sempit dan khusus admin.
• Penyusunan autentikasi koneksi di sisi klien (selectConnectAuth dalam packages/gateway-client/src/client.ts):
  • auth.password bersifat ortogonal dan selalu diteruskan ketika ditetapkan.
  • auth.token diisi berdasarkan urutan prioritas: token bersama eksplisit terlebih dahulu, kemudian deviceToken eksplisit, lalu token per perangkat tersimpan (dikunci berdasarkan deviceId + role).
  • auth.bootstrapToken dikirim hanya jika tidak satu pun dari hal di atas menghasilkan auth.token. Token bersama atau token perangkat apa pun yang berhasil ditentukan akan menonaktifkannya.
  • Promosi otomatis token perangkat tersimpan pada retry satu kali AUTH_TOKEN_MISMATCH dibatasi hanya untuk endpoint tepercaya: loopback, atau wss:// dengan tlsFingerprint yang dipasangi pin. wss:// publik tanpa pin tidak memenuhi syarat.
• Bootstrap kode penyiapan bawaan mengembalikan hello-ok.auth.deviceToken Node utama beserta token operator terbatas dalam hello-ok.auth.deviceTokens untuk penyerahan seluler tepercaya. Token operator menyertakan operator.talk.secrets untuk pembacaan konfigurasi Talk native, tetapi mengecualikan cakupan mutasi pemasangan dan operator.admin.
• Saat bootstrap kode penyiapan non-baseline menunggu persetujuan, detail PAIRING_REQUIRED mencakup recommendedNextStep: "wait_then_retry", retryable: true, dan pauseReconnect: false. Terus hubungkan ulang dengan token bootstrap yang sama hingga permintaan disetujui atau token menjadi tidak valid.
• Simpan hello-ok.auth.deviceTokens hanya ketika koneksi menggunakan autentikasi bootstrap pada transport tepercaya seperti wss:// atau pemasangan loopback/lokal.
• Jika klien memberikan deviceToken eksplisit atau scopes eksplisit, kumpulan cakupan yang diminta pemanggil tersebut tetap menjadi acuan; cakupan yang di-cache hanya digunakan kembali ketika klien menggunakan kembali token per perangkat yang tersimpan.
• Token perangkat dapat dirotasi/dicabut melalui device.token.rotate dan device.token.revoke (memerlukan operator.pairing). Merotasi atau mencabut token Node atau peran non-operator lainnya juga memerlukan operator.admin.
• device.token.rotate mengembalikan metadata rotasi. Metadata tersebut menyertakan token bearer pengganti hanya untuk panggilan dari perangkat yang sama yang telah diautentikasi dengan token perangkat tersebut, sehingga klien yang hanya menggunakan token dapat menyimpan penggantinya sebelum menghubungkan ulang. Rotasi bersama/admin tidak menyertakan token bearer.
• Penerbitan, rotasi, dan pencabutan token tetap dibatasi pada kumpulan peran yang disetujui dan tercatat dalam entri pemasangan perangkat tersebut; mutasi token tidak dapat memperluas atau menargetkan peran perangkat yang tidak pernah diberikan oleh persetujuan pemasangan.
• Untuk sesi token perangkat terpasang, pengelolaan perangkat terbatas pada diri sendiri kecuali pemanggil juga memiliki operator.admin: pemanggil non-admin hanya dapat mengelola token operator untuk entri perangkatnya sendiri. Pengelolaan token Node dan non-operator lainnya hanya untuk admin, bahkan untuk perangkat pemanggil sendiri.
• device.token.rotate dan device.token.revoke juga memeriksa kumpulan cakupan token operator target terhadap cakupan sesi pemanggil saat ini. Pemanggil non-admin tidak dapat merotasi atau mencabut token operator yang cakupannya lebih luas daripada yang telah mereka miliki.
• Kegagalan autentikasi mencakup error.details.code beserta petunjuk pemulihan:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep: salah satu dari retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts).
• Perilaku klien untuk AUTH_TOKEN_MISMATCH:
  • Klien tepercaya dapat mencoba satu retry terbatas dengan token per perangkat yang di-cache.
  • Jika retry tersebut gagal, hentikan loop koneksi ulang otomatis dan tampilkan panduan tindakan operator.
• AUTH_SCOPE_MISMATCH berarti token perangkat dikenali tetapi tidak mencakup peran/cakupan yang diminta. Jangan menampilkannya sebagai token yang salah; minta operator untuk memasangkan ulang atau menyetujui kontrak cakupan yang lebih sempit/luas.

Identitas dan pemasangan perangkat

• Node harus menyertakan identitas perangkat stabil (device.id) yang berasal dari fingerprint pasangan kunci.
• Gateway menerbitkan token per perangkat + peran.
• Persetujuan pemasangan diperlukan untuk ID perangkat baru kecuali persetujuan otomatis lokal diaktifkan.
• Persetujuan otomatis pemasangan berpusat pada koneksi loopback lokal langsung.
• OpenClaw juga memiliki jalur koneksi mandiri backend/kontainer-lokal yang sempit untuk alur helper rahasia bersama tepercaya.
• Koneksi tailnet atau LAN pada host yang sama tetap diperlakukan sebagai koneksi jarak jauh untuk pemasangan dan memerlukan persetujuan.
• Klien WS biasanya menyertakan identitas device selama connect (operator + Node). Satu-satunya pengecualian operator tanpa perangkat adalah jalur kepercayaan eksplisit:
  • gateway.controlUi.allowInsecureAuth=true untuk kompatibilitas HTTP tidak aman khusus localhost.
  • autentikasi Control UI operator gateway.auth.mode: "trusted-proxy" yang berhasil.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, penurunan keamanan yang parah).
  • RPC backend gateway-client loopback langsung pada jalur helper internal yang dicadangkan.
• Menghilangkan identitas perangkat memiliki konsekuensi terhadap cakupan. Ketika koneksi operator tanpa perangkat diizinkan melalui jalur kepercayaan eksplisit, OpenClaw tetap mengosongkan cakupan yang dideklarasikan sendiri kecuali jalur tersebut memiliki pengecualian preservasi cakupan bernama. Metode yang dibatasi cakupan kemudian gagal dengan missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true adalah jalur preservasi cakupan break-glass Control UI. Jalur ini tidak memberikan cakupan kepada klien WebSocket backend kustom atau berbentuk CLI secara sembarang.
• Jalur helper backend gateway-client loopback langsung yang dicadangkan mempertahankan cakupan hanya untuk RPC bidang kontrol lokal internal; ID backend kustom tidak menerima pengecualian ini.
• Semua koneksi harus menandatangani nonce connect.challenge yang disediakan server.

Diagnostik migrasi autentikasi perangkat

Untuk klien lama yang masih menggunakan perilaku penandatanganan sebelum tantangan, connect mengembalikan kode detail DEVICE_AUTH_* di bawah error.details.code dengan error.details.reason yang stabil.

Kegagalan migrasi umum:

Target migrasi:

• Selalu tunggu connect.challenge.
• Tandatangani payload v2 yang menyertakan nonce server.
• Kirim nonce yang sama dalam connect.params.device.nonce.
• Payload tanda tangan yang disarankan adalah v3 (buildDeviceAuthPayloadV3 dalam packages/gateway-client/src/device-auth.ts), yang mengikat platform dan deviceFamily selain bidang perangkat/klien/peran/cakupan/token/nonce.
• Tanda tangan v2 lama tetap diterima untuk kompatibilitas, tetapi penyematan metadata perangkat yang dipasangkan tetap mengendalikan kebijakan perintah saat tersambung kembali.

TLS dan penyematan

• TLS didukung untuk koneksi WS (konfigurasi gateway.tls).
• Klien dapat secara opsional menyematkan sidik jari sertifikat Gateway melalui gateway.remote.tlsFingerprint atau CLI --tls-fingerprint.

Cakupan

Protokol ini mengekspos API Gateway lengkap: status, saluran, model, obrolan, agen, sesi, node, persetujuan, dan lainnya. Permukaan persisnya ditentukan oleh skema TypeBox yang diekspor ulang dari packages/gateway-protocol/src/schema.ts.

Terkait

• Membangun klien Gateway
• Menyematkan OpenClaw
• Protokol bridge
• Panduan operasional Gateway