Protokol Gateway

Protokol Gateway WS adalah bidang kontrol 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 saat handshake.

Transport

• WebSocket, frame teks dengan payload JSON.
• Frame pertama harus berupa permintaan connect.
• Frame pra-koneksi dibatasi hingga 64 KiB. Setelah handshake berhasil, klien sebaiknya mengikuti batas 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 menjatuhkan frame yang terdampak. Peristiwa ini menyimpan ukuran, batas, permukaan, dan kode alasan yang aman. Peristiwa ini tidak menyimpan isi pesan, konten lampiran, isi frame mentah, token, cookie, atau nilai rahasia.

Handshake (connect)

Gateway → Klien (tantangan pra-koneksi):

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

Klien → Gateway:

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

Gateway → Klien:

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

Saat Gateway masih menyelesaikan sidecar startup, permintaan connect dapat mengembalikan galat UNAVAILABLE yang dapat dicoba ulang dengan details.reason disetel ke "startup-sidecars" dan retryAfterMs. Klien sebaiknya mencoba ulang respons tersebut dalam anggaran koneksi keseluruhan mereka, bukan menampilkannya sebagai kegagalan handshake terminal.

server, features, snapshot, dan policy semuanya diwajibkan oleh skema (packages/gateway-protocol/src/schema/frames.ts). auth juga wajib dan melaporkan peran/cakupan yang dinegosiasikan. pluginSurfaceUrls bersifat opsional dan memetakan nama permukaan plugin, seperti canvas, ke URL ter-hosting bercakupan.

URL permukaan plugin bercakupan dapat kedaluwarsa. Node dapat memanggil node.pluginSurface.refresh dengan { "surface": "canvas" } untuk menerima entri baru di pluginSurfaceUrls. Refaktor plugin Canvas eksperimental tidak mendukung jalur kompatibilitas canvasHostUrl, canvasCapability, atau node.canvas.capability.refresh yang sudah tidak digunakan; klien native dan gateway saat ini harus menggunakan permukaan plugin.

Saat tidak ada token perangkat yang diterbitkan, hello-ok.auth melaporkan izin yang dinegosiasikan tanpa kolom token:

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

Klien backend proses-sama yang tepercaya (client.id: "gateway-client", client.mode: "backend") dapat menghilangkan device pada koneksi loopback langsung saat mereka mengautentikasi dengan token/kata sandi gateway bersama. Jalur ini dicadangkan untuk RPC bidang kontrol internal dan mencegah baseline pemasangan CLI/perangkat yang usang memblokir pekerjaan backend lokal seperti pembaruan sesi subagen. Klien jarak jauh, klien asal browser, klien node, dan klien token-perangkat/identitas-perangkat eksplisit tetap menggunakan pemeriksaan pemasangan dan peningkatan cakupan normal.

Saat token perangkat diterbitkan, hello-ok juga menyertakan:

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

Bootstrap kode QR/setup bawaan adalah jalur handoff mobile baru. Koneksi setup-code baseline yang berhasil mengembalikan token node utama plus satu token operator berbatas:

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

Handoff operator sengaja dibatasi agar onboarding QR dapat memulai loop operator mobile dan menyelesaikan setup native tanpa memberikan cakupan mutasi pemasangan atau operator.admin. Ini menyertakan operator.talk.secrets agar klien native dapat membaca konfigurasi Talk yang dibutuhkannya setelah bootstrap. Akses pemasangan dan admin yang lebih luas memerlukan pemasangan operator atau alur token terpisah yang disetujui. Klien sebaiknya mempertahankan hello-ok.auth.deviceTokens hanya saat koneksi menggunakan auth bootstrap pada transport tepercaya seperti wss:// atau pemasangan loopback/lokal.

Contoh node

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

Pembingkaian

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

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

Peran + cakupan

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

Peran

• operator = klien bidang kontrol (CLI/UI/otomasi).
• node = host kemampuan (camera/screen/canvas/system.run).

Cakupan (operator)

Cakupan umum:

• 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, klien sebaiknya membaca 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 admin inti yang dicadangkan (config.*, exec.approvals.*, wizard.*, update.*) selalu diselesaikan menjadi operator.admin.

Cakupan metode hanya gerbang pertama. Beberapa perintah slash yang dicapai melalui chat.send menerapkan pemeriksaan tingkat perintah yang lebih ketat di atasnya. Misalnya, penulisan /config set dan /config unset persisten memerlukan operator.admin.

node.pair.approve juga memiliki pemeriksaan cakupan tambahan 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, atau system.which: operator.pairing + operator.admin

Kapabilitas/perintah/izin (node)

Node mendeklarasikan klaim kemampuan saat koneksi:

• caps: kategori kemampuan tingkat tinggi seperti camera, canvas, screen, location, voice, dan talk.
• commands: allowlist perintah untuk invoke.
• permissions: toggle granular (mis. screen.record, camera.capture).

Gateway memperlakukan ini sebagai klaim dan memberlakukan allowlist sisi server.

Kehadiran

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

Peristiwa node aktif di latar belakang

Node dapat memanggil node.event dengan event: "node.presence.alive" untuk mencatat bahwa node yang dipasangkan aktif selama wake latar belakang tanpa menandainya 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, atau connect. String trigger yang tidak dikenal dinormalisasi menjadi background oleh gateway sebelum persistensi. Peristiwa ini hanya tahan lama untuk sesi perangkat node terautentikasi; 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 masih mengembalikan { "ok": true } untuk node.event; klien sebaiknya memperlakukannya sebagai RPC yang diakui, bukan sebagai persistensi kehadiran yang tahan lama.

Pencakupan peristiwa siaran

Peristiwa siaran WebSocket yang didorong server diberi gerbang cakupan sehingga sesi bercakupan pemasangan atau hanya-node tidak menerima konten sesi secara pasif.

• Frame chat, agen, dan hasil alat (termasuk peristiwa agent yang dialirkan dan hasil panggilan alat) memerlukan setidaknya operator.read. Sesi tanpa operator.read melewati frame ini sepenuhnya.
• Siaran plugin.* yang ditentukan plugin diberi gerbang ke operator.write atau operator.admin, tergantung pada cara plugin mendaftarkannya.
• Peristiwa status dan transport (heartbeat, presence, tick, siklus hidup connect/disconnect, dll.) tetap tidak dibatasi agar kesehatan transport tetap dapat diamati oleh setiap sesi terautentikasi.
• Keluarga peristiwa siaran yang tidak dikenal diberi gerbang cakupan secara default (fail-closed) kecuali handler terdaftar secara eksplisit melonggarkannya.

Setiap koneksi klien menyimpan nomor urut per-kliennya sendiri sehingga siaran mempertahankan urutan monotonik pada soket tersebut bahkan ketika klien berbeda melihat subset aliran peristiwa yang difilter cakupannya secara berbeda.

Keluarga metode RPC umum

Permukaan WS publik lebih luas daripada contoh handshake/auth di atas. Ini bukan dump yang dibuat otomatis — hello-ok.features.methods adalah daftar penemuan konservatif yang dibuat dari src/gateway/server-methods-list.ts plus ekspor metode plugin/channel yang dimuat. Perlakukan ini sebagai penemuan fitur, bukan enumerasi lengkap atas src/gateway/server-methods/*.ts.

Keluarga peristiwa umum

• chat: pembaruan chat UI seperti chat.inject dan peristiwa chat khusus transkrip lainnya. Dalam protokol v4, payload delta membawa deltaText; message tetap menjadi snapshot asisten kumulatif. Penggantian non-prefix menetapkan replace=true dan menggunakan deltaText sebagai teks pengganti.
• session.message, session.operation, dan session.tool: transkrip, operasi sesi yang sedang berjalan, dan pembaruan aliran peristiwa untuk sesi berlangganan.
• sessions.changed: indeks sesi atau metadata berubah.
• presence: pembaruan snapshot kehadiran sistem.
• tick: peristiwa keepalive / liveness berkala.
• health: pembaruan snapshot kesehatan gateway.
• heartbeat: pembaruan aliran peristiwa Heartbeat.
• cron: peristiwa perubahan run/pekerjaan Cron.
• shutdown: notifikasi shutdown gateway.
• node.pair.requested / node.pair.resolved: siklus hidup pemasangan node.
• node.invoke.request: siaran permintaan invoke node.
• device.pair.requested / device.pair.resolved: siklus hidup perangkat terpasang.
• voicewake.changed: konfigurasi pemicu kata wake berubah.
• exec.approval.requested / exec.approval.resolved: siklus hidup persetujuan exec.
• plugin.approval.requested / plugin.approval.resolved: siklus hidup persetujuan plugin.

Metode pembantu node

• Node dapat memanggil skills.bins untuk mengambil daftar executable skill saat ini untuk pemeriksaan izinkan-otomatis.

RPC ledger tugas

Klien operator dapat memeriksa dan membatalkan rekaman tugas latar belakang Gateway melalui RPC ledger tugas. Metode ini mengembalikan ringkasan tugas yang disanitasi, bukan status runtime mentah.

• tasks.list memerlukan operator.read.
  • Parameter: status opsional ("queued", "running", "completed", "failed", "cancelled", atau "timed_out") atau array 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 hilang mengembalikan bentuk galat tidak-ditemukan 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 seperti kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, stempel waktu, progres, ringkasan terminal, dan teks galat yang disanitasi. agentId mengidentifikasi agen yang mengeksekusi tugas; sessionKey dan ownerKey mempertahankan konteks peminta dan kontrol.

Metode pembantu operator

• Operator dapat memanggil commands.list (operator.read) untuk mengambil inventaris perintah runtime bagi agen.
  • agentId bersifat opsional; hilangkan untuk membaca workspace agen bawaan.
  • scope mengontrol permukaan yang ditargetkan oleh name utama:
    • text mengembalikan token perintah teks utama tanpa awalan /
    • native dan jalur bawaan both mengembalikan nama native yang sadar penyedia saat tersedia
  • textAliases membawa alias garis miring persis seperti /model dan /m.
  • nativeName membawa nama perintah native yang sadar penyedia saat ada.
  • provider bersifat opsional dan hanya memengaruhi penamaan native plus ketersediaan perintah Plugin native.
  • includeArgs=false menghilangkan metadata argumen berseri dari respons.
• Operator dapat memanggil tools.catalog (operator.read) untuk mengambil katalog tool runtime bagi agen. Respons mencakup tool yang dikelompokkan dan metadata asal:
  • source: core atau plugin
  • pluginId: pemilik plugin saat source="plugin"
  • optional: apakah tool plugin bersifat opsional
• Operator dapat memanggil tools.effective (operator.read) untuk mengambil inventaris tool yang efektif saat runtime bagi sesi.
  • sessionKey wajib diisi.
  • Gateway menurunkan konteks runtime tepercaya dari sesi di sisi server alih-alih menerima auth atau konteks pengiriman yang diberikan pemanggil.
  • Respons adalah proyeksi inventaris aktif berbasis server dengan cakupan sesi, mencakup tool core, plugin, channel, dan server MCP yang sudah ditemukan.
  • tools.effective bersifat hanya-baca untuk MCP: ia dapat memproyeksikan katalog MCP sesi hangat melalui kebijakan tool akhir, tetapi tidak membuat runtime MCP, menghubungkan transport, atau menerbitkan tools/list. Jika tidak ada katalog hangat yang cocok, respons dapat menyertakan pemberitahuan seperti mcp-not-yet-connected, mcp-not-yet-listed, atau mcp-stale-catalog.
  • Entri tool efektif menggunakan source="core", source="plugin", source="channel", atau source="mcp".
• Operator dapat memanggil tools.invoke (operator.write) untuk menjalankan satu tool 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 diselesaikan harus cocok dengan agentId.
  • Wrapper core khusus pemilik seperti cron, gateway, dan nodes memerlukan identitas pemilik/admin (operator.admin) meskipun metode tools.invoke sendiri adalah operator.write.
  • Respons adalah envelope yang menghadap SDK dengan kolom ok, toolName, output opsional, dan error bertipe. Penolakan approval atau kebijakan mengembalikan ok:false dalam payload alih-alih melewati pipeline kebijakan tool Gateway.
• Operator dapat memanggil skills.status (operator.read) untuk mengambil inventaris skill yang terlihat bagi agen.
  • agentId bersifat opsional; hilangkan untuk membaca workspace agen bawaan.
  • Respons mencakup kelayakan, persyaratan yang hilang, pemeriksaan konfigurasi, dan opsi instalasi yang sudah disanitasi tanpa mengekspos nilai rahasia mentah.
• Operator dapat memanggil skills.search dan skills.detail (operator.read) untuk metadata penemuan ClawHub.
• Operator dapat memanggil skills.upload.begin, skills.upload.chunk, dan skills.upload.commit (operator.admin) untuk menyiapkan arsip skill privat sebelum menginstalnya. Ini adalah jalur unggah admin terpisah untuk klien tepercaya, bukan alur instalasi skill ClawHub normal, dan dinonaktifkan secara bawaan kecuali skills.install.allowUploadedArchives diaktifkan.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) membuat unggahan yang terikat ke slug dan nilai force tersebut.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) menambahkan byte pada offset hasil dekode yang persis.
  • skills.upload.commit({ uploadId, sha256? }) memverifikasi ukuran akhir dan SHA-256. Commit hanya menyelesaikan unggahan; ini tidak menginstal skill.
  • Arsip skill yang diunggah adalah arsip zip yang berisi root SKILL.md. Nama direktori internal arsip tidak pernah memilih target instalasi.
• Operator dapat memanggil skills.install (operator.admin) dalam tiga mode:
  • Mode ClawHub: { source: "clawhub", slug, version?, force? } menginstal folder skill ke direktori skills/ workspace agen bawaan.
  • Mode unggahan: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } menginstal unggahan yang sudah dikomit ke direktori skills/<slug> workspace agen bawaan. Nilai slug dan force harus cocok dengan permintaan skills.upload.begin asli. Mode ini ditolak kecuali skills.install.allowUploadedArchives diaktifkan. Pengaturan ini tidak memengaruhi instalasi ClawHub.
  • Mode penginstal Gateway: { name, installId, timeoutMs? } menjalankan aksi metadata.openclaw.install yang dideklarasikan pada host Gateway. Klien lama mungkin masih mengirim dangerouslyForceUnsafeInstall; kolom ini sudah usang, diterima hanya untuk kompatibilitas protokol, dan diabaikan. Gunakan security.installPolicy untuk keputusan instalasi yang dimiliki operator.
• 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 bawaan.
  • Mode konfigurasi menambal nilai skills.entries.<skillKey> seperti enabled, apiKey, dan env.

Tampilan models.list

models.list menerima parameter view opsional:

• Dihilangkan atau "default": perilaku runtime saat ini. Jika agents.defaults.models dikonfigurasi, respons adalah katalog yang diizinkan, termasuk model yang ditemukan secara dinamis untuk entri provider/*. Jika tidak, respons adalah katalog Gateway lengkap.
• "configured": perilaku seukuran pemilih. Jika agents.defaults.models dikonfigurasi, itu tetap menang, termasuk penemuan bercakupan penyedia untuk entri provider/*. Tanpa allowlist, respons menggunakan entri models.providers.*.models eksplisit, dengan fallback ke katalog lengkap hanya ketika tidak ada baris model yang dikonfigurasi.
• "all": katalog Gateway lengkap, melewati agents.defaults.models. Gunakan ini untuk diagnostik dan UI penemuan, bukan pemilih model normal.

Approval exec

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

Fallback pengiriman agen

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

Pembuatan versi

• PROTOCOL_VERSION berada di packages/gateway-protocol/src/version.ts.
• Klien mengirim minProtocol + maxProtocol; server menolak rentang yang tidak menyertakan protokol saat ini. Klien dan server saat ini memerlukan protokol v4.
• Skema + model dihasilkan dari definisi TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Konstanta klien

Klien referensi di src/gateway/client.ts menggunakan nilai bawaan ini. Nilai stabil di seluruh protokol v4 dan merupakan baseline yang diharapkan untuk klien pihak ketiga.

Server mengiklankan policy.tickIntervalMs, policy.maxPayload, dan policy.maxBufferedBytes yang efektif di hello-ok; klien harus mematuhi nilai tersebut, bukan nilai bawaan pra-handshake.

Auth

• Auth Gateway rahasia bersama menggunakan connect.params.auth.token atau connect.params.auth.password, tergantung mode auth yang dikonfigurasi.
• Mode yang membawa identitas seperti Tailscale Serve (gateway.auth.allowTailscale: true) atau gateway.auth.mode: "trusted-proxy" non-loopback memenuhi pemeriksaan auth connect dari header permintaan, bukan dari connect.params.auth.*.
• Ingress privat gateway.auth.mode: "none" melewati auth connect rahasia bersama sepenuhnya; jangan ekspos mode tersebut pada ingress publik/tidak tepercaya.
• Setelah pairing, Gateway menerbitkan token perangkat yang dibatasi pada peran koneksi + cakupan. Token ini dikembalikan di hello-ok.auth.deviceToken dan harus dipersistenkan oleh klien untuk connect berikutnya.
• Klien harus mempersistenkan hello-ok.auth.deviceToken utama setelah connect berhasil.
• Menghubungkan ulang dengan token perangkat yang tersimpan tersebut juga harus menggunakan kembali set cakupan tersetujui yang tersimpan untuk token itu. Ini mempertahankan akses baca/probe/status yang sudah diberikan dan menghindari penyempitan diam-diam saat reconnect menjadi cakupan implisit khusus admin yang lebih sempit.
• Perakitan auth connect sisi klien (selectConnectAuth di src/gateway/client.ts):
  • auth.password bersifat ortogonal dan selalu diteruskan saat disetel.
  • auth.token diisi berdasarkan urutan prioritas: token bersama eksplisit lebih dulu, lalu deviceToken eksplisit, lalu token per-perangkat tersimpan (dikunci oleh deviceId + role).
  • auth.bootstrapToken dikirim hanya ketika tidak ada hal di atas yang menghasilkan auth.token. Token bersama atau token perangkat apa pun yang berhasil diselesaikan akan menekannya.
  • Promosi otomatis token perangkat tersimpan pada retry sekali jalan AUTH_TOKEN_MISMATCH dibatasi hanya untuk endpoint tepercaya - loopback, atau wss:// dengan tlsFingerprint yang dipin. wss:// publik tanpa pinning tidak memenuhi syarat.
• Bootstrap kode setup bawaan mengembalikan node utama hello-ok.auth.deviceToken plus token operator berbatas di hello-ok.auth.deviceTokens untuk handoff seluler tepercaya. Token operator menyertakan operator.talk.secrets untuk pembacaan konfigurasi Talk native, tetapi mengecualikan cakupan mutasi pairing dan operator.admin.
• Saat bootstrap kode setup non-baseline menunggu persetujuan, detail PAIRING_REQUIRED menyertakan recommendedNextStep: "wait_then_retry", retryable: true, dan pauseReconnect: false. Klien harus terus reconnect dengan token bootstrap yang sama hingga permintaan disetujui atau token menjadi tidak valid.
• Persistenkan hello-ok.auth.deviceTokens hanya ketika connect menggunakan auth bootstrap pada transport tepercaya seperti wss:// atau pairing loopback/local.
• Jika klien menyediakan deviceToken eksplisit atau scopes eksplisit, set cakupan yang diminta pemanggil tersebut tetap otoritatif; cakupan cache hanya digunakan kembali ketika klien menggunakan kembali token per-perangkat tersimpan.
• Token perangkat dapat dirotasi/dicabut melalui device.token.rotate dan device.token.revoke (memerlukan cakupan operator.pairing). Merotasi atau mencabut node atau peran non-operator lain juga memerlukan operator.admin.
• device.token.rotate mengembalikan metadata rotasi. Ini menggemakan token bearer pengganti hanya untuk panggilan perangkat yang sama yang sudah diautentikasi dengan token perangkat tersebut, sehingga klien khusus token dapat mempersistenkan penggantinya sebelum reconnect. Rotasi shared/admin tidak menggemakan token bearer.
• Penerbitan, rotasi, dan pencabutan token tetap dibatasi pada set peran tersetujui yang tercatat di entri pairing perangkat tersebut; mutasi token tidak dapat memperluas atau menargetkan peran perangkat yang tidak pernah diberikan oleh persetujuan pairing.
• Untuk sesi token perangkat yang dipairing, manajemen perangkat bersifat self-scoped kecuali pemanggil juga memiliki operator.admin: pemanggil non-admin hanya dapat mengelola token operator untuk entri perangkat miliknya sendiri. Manajemen token node dan non-operator lain hanya untuk admin, bahkan untuk perangkat milik pemanggil sendiri.
• device.token.rotate dan device.token.revoke juga memeriksa set cakupan token operator target terhadap cakupan sesi pemanggil saat ini. Pemanggil non-admin tidak dapat merotasi atau mencabut token operator yang lebih luas daripada yang sudah mereka miliki.
• Kegagalan auth menyertakan error.details.code plus 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 berbatas dengan token per-perangkat yang di-cache.
  • Jika retry tersebut gagal, klien harus menghentikan loop reconnect otomatis dan menampilkan panduan tindakan operator.
• AUTH_SCOPE_MISMATCH berarti token perangkat dikenali tetapi tidak mencakup peran/cakupan yang diminta. Klien tidak boleh menampilkannya sebagai token buruk; minta operator melakukan re-pair atau menyetujui kontrak cakupan yang lebih sempit/lebih luas.

Identitas perangkat + pairing

• Node harus menyertakan identitas perangkat stabil (device.id) yang berasal dari fingerprint keypair.
• Gateway menerbitkan token per perangkat + peran.
• Persetujuan pairing diperlukan untuk ID perangkat baru kecuali persetujuan otomatis lokal diaktifkan.
• Persetujuan otomatis pairing berpusat pada connect local loopback langsung.
• OpenClaw juga memiliki jalur self-connect backend/container-lokal sempit untuk alur helper rahasia bersama tepercaya.
• Connect tailnet atau LAN pada host yang sama tetap diperlakukan sebagai remote untuk pairing 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.
  • auth Control UI operator gateway.auth.mode: "trusted-proxy" yang berhasil.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, penurunan keamanan berat).
  • RPC backend gateway-client direct-loopback pada jalur helper internal yang dicadangkan.
• Menghilangkan identitas perangkat memiliki konsekuensi cakupan. Ketika koneksi operator tanpa perangkat diizinkan melalui jalur kepercayaan eksplisit, OpenClaw tetap mengosongkan cakupan yang dideklarasikan sendiri menjadi set kosong kecuali jalur tersebut memiliki pengecualian pelestarian cakupan bernama. Metode yang dibatasi cakupan kemudian gagal dengan missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true adalah jalur pelestarian cakupan break-glass Control UI. Ini tidak memberikan cakupan kepada klien WebSocket backend kustom atau berbentuk CLI secara sembarang.
• Jalur helper backend gateway-client direct-loopback yang dicadangkan mempertahankan cakupan hanya untuk RPC control-plane lokal internal; ID backend kustom tidak menerima pengecualian ini.
• Semua koneksi harus menandatangani nonce connect.challenge yang disediakan server.

Diagnostik migrasi auth perangkat

Untuk klien lama yang masih menggunakan perilaku penandatanganan sebelum challenge, connect sekarang 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.
• Tanda tangani payload v2 yang menyertakan nonce server.
• Kirim nonce yang sama di connect.params.device.nonce.
• Payload tanda tangan yang disukai adalah v3, yang mengikat platform dan deviceFamily selain field perangkat/klien/peran/cakupan/token/nonce.
• Tanda tangan v2 lama tetap diterima untuk kompatibilitas, tetapi pinning metadata perangkat yang dipairing tetap mengontrol kebijakan perintah saat reconnect.

TLS + pinning

• TLS didukung untuk koneksi WS.
• Klien dapat secara opsional mem-pin fingerprint sertifikat gateway (lihat konfigurasi gateway.tls plus gateway.remote.tlsFingerprint atau CLI --tls-fingerprint).

Cakupan

Protokol ini mengekspos API Gateway penuh (status, saluran, model, chat, agen, sesi, node, persetujuan, dll.). Permukaan persisnya didefinisikan oleh skema TypeBox di packages/gateway-protocol/src/schema.ts.

Terkait

• Protokol bridge
• Runbook Gateway