Langsung ke konten utama
Dalam pairing yang dimiliki Gateway, Gateway adalah sumber kebenaran untuk node mana yang diizinkan bergabung. UI (aplikasi macOS, klien mendatang) hanyalah frontend yang menyetujui atau menolak permintaan tertunda. Penting: node WS menggunakan pairing perangkat (peran node) selama connect. node.pair.* adalah penyimpanan pairing terpisah dan tidak mengatur handshake WS. Hanya klien yang secara eksplisit memanggil node.pair.* yang menggunakan alur ini.

​
Konsep

  • Permintaan tertunda: node meminta bergabung; memerlukan persetujuan.
  • Node yang dipasangkan: node yang disetujui dengan token auth yang diterbitkan.
  • Transpor: endpoint WS Gateway meneruskan permintaan tetapi tidak memutuskan keanggotaan. (Dukungan bridge TCP lama telah dihapus.)

​
Cara kerja pairing

  1. Node terhubung ke WS Gateway dan meminta pairing.
  2. Gateway menyimpan permintaan tertunda dan memancarkan node.pair.requested.
  3. Anda menyetujui atau menolak permintaan (CLI atau UI).
  4. Saat disetujui, Gateway menerbitkan token baru (token dirotasi saat pairing ulang).
  5. Node terhubung ulang menggunakan token dan kini “dipasangkan”.
Permintaan tertunda kedaluwarsa otomatis setelah 5 menit.

​
Alur kerja CLI (ramah headless)

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
nodes status menampilkan node yang dipasangkan/terhubung dan kapabilitasnya.

​
Permukaan API (protokol gateway)

Event:
  • node.pair.requested - dipancarkan saat permintaan tertunda baru dibuat.
  • node.pair.resolved - dipancarkan saat permintaan disetujui/ditolak/kedaluwarsa.
Metode:
  • node.pair.request - membuat atau menggunakan ulang permintaan tertunda.
  • node.pair.list - mencantumkan node tertunda + dipasangkan (operator.pairing).
  • node.pair.approve - menyetujui permintaan tertunda (menerbitkan token).
  • node.pair.reject - menolak permintaan tertunda.
  • node.pair.remove - menghapus node yang dipasangkan. Untuk pairing yang didukung perangkat, ini mencabut peran node milik perangkat: ini mengubah devices/paired.json dan membatalkan/memutus sesi peran node perangkat tersebut. Perangkat peran campuran (misalnya juga memegang operator) mempertahankan barisnya dan hanya kehilangan peran node; baris perangkat khusus node dihapus. Ini juga menghapus entri pairing node lama yang dimiliki gateway jika cocok. Authz: operator.pairing dapat menghapus baris node non-operator; pemanggil token perangkat yang mencabut peran node miliknya sendiri pada perangkat peran campuran juga membutuhkan operator.admin.
  • node.pair.verify - memverifikasi { nodeId, token }.
Catatan:
  • node.pair.request bersifat idempoten per node: panggilan berulang mengembalikan permintaan tertunda yang sama.
  • Permintaan berulang untuk node tertunda yang sama juga menyegarkan metadata node yang tersimpan dan snapshot perintah terdeklarasi allowlist terbaru untuk visibilitas operator.
  • Persetujuan selalu menghasilkan token baru; tidak ada token yang pernah dikembalikan dari node.pair.request.
  • Tingkat cakupan operator dan pemeriksaan saat persetujuan dirangkum dalam Cakupan operator.
  • Permintaan dapat menyertakan silent: true sebagai petunjuk untuk alur persetujuan otomatis.
  • node.pair.approve menggunakan perintah terdeklarasi milik permintaan tertunda untuk memberlakukan cakupan persetujuan ekstra:
    • permintaan tanpa perintah: operator.pairing
    • permintaan perintah non-exec: operator.pairing + operator.write
    • permintaan system.run / system.run.prepare / system.which: operator.pairing + operator.admin
Pairing node adalah alur kepercayaan dan identitas plus penerbitan token. Ini tidak mem-pin permukaan perintah node live per node.
  • Perintah node live berasal dari apa yang dideklarasikan node saat connect setelah kebijakan perintah node global gateway (gateway.nodes.allowCommands dan denyCommands) diterapkan.
  • Kebijakan allow dan ask system.run per node berada di node dalam exec.approvals.node.*, bukan dalam catatan pairing.

​
Pengaturan perintah node (2026.3.31+)

Perubahan yang merusak kompatibilitas: Mulai 2026.3.31, perintah node dinonaktifkan sampai pairing node disetujui. Pairing perangkat saja tidak lagi cukup untuk mengekspos perintah node yang dideklarasikan.
Saat node terhubung untuk pertama kali, pairing diminta secara otomatis. Sampai permintaan pairing disetujui, semua perintah node tertunda dari node tersebut difilter dan tidak akan dieksekusi. Setelah kepercayaan ditetapkan melalui persetujuan pairing, perintah yang dideklarasikan node tersedia sesuai kebijakan perintah normal. Ini berarti:
  • Node yang sebelumnya hanya mengandalkan pairing perangkat untuk mengekspos perintah kini harus menyelesaikan pairing node.
  • Perintah yang diantrekan sebelum persetujuan pairing dibuang, bukan ditunda.

​
Batas kepercayaan event node (2026.3.31+)

Perubahan yang merusak kompatibilitas: Run yang berasal dari node kini tetap berada pada permukaan tepercaya yang dikurangi.
Ringkasan yang berasal dari node dan event sesi terkait dibatasi ke permukaan tepercaya yang dimaksud. Alur yang digerakkan notifikasi atau dipicu node yang sebelumnya mengandalkan akses alat host atau sesi yang lebih luas mungkin perlu disesuaikan. Pengerasan ini memastikan bahwa event node tidak dapat meningkat menjadi akses alat tingkat host di luar yang diizinkan batas kepercayaan node. Pembaruan keberadaan node yang tahan lama mengikuti batas identitas yang sama. Event node.presence.alive diterima hanya dari sesi perangkat node terautentikasi dan memperbarui metadata pairing hanya saat identitas perangkat/node sudah dipasangkan. Nilai client.id yang dideklarasikan sendiri tidak cukup untuk menulis status terakhir terlihat.

​
Persetujuan otomatis (aplikasi macOS)

Aplikasi macOS secara opsional dapat mencoba persetujuan senyap saat:
  • permintaan ditandai silent, dan
  • aplikasi dapat memverifikasi koneksi SSH ke host gateway menggunakan pengguna yang sama.
Jika persetujuan senyap gagal, alur kembali ke prompt “Setujui/Tolak” normal.

​
Persetujuan otomatis perangkat Trusted-CIDR

Pairing perangkat WS untuk role: node tetap manual secara default. Untuk jaringan node privat tempat Gateway sudah memercayai jalur jaringan, operator dapat ikut serta dengan CIDR eksplisit atau IP persis: 
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
Batas keamanan:
  • Dinonaktifkan saat gateway.nodes.pairing.autoApproveCidrs tidak disetel.
  • Tidak ada mode persetujuan otomatis blanket untuk LAN atau jaringan privat.
  • Hanya pairing perangkat role: node baru tanpa cakupan yang diminta yang memenuhi syarat.
  • Klien operator, browser, Control UI, dan WebChat tetap manual.
  • Peningkatan peran, cakupan, metadata, dan kunci publik tetap manual.
  • Jalur header trusted-proxy loopback host yang sama tidak memenuhi syarat karena jalur itu dapat dipalsukan oleh pemanggil lokal.

​
Persetujuan otomatis peningkatan metadata

Saat perangkat yang sudah dipasangkan terhubung ulang hanya dengan perubahan metadata non-sensitif (misalnya, nama tampilan atau petunjuk platform klien), OpenClaw memperlakukannya sebagai metadata-upgrade. Persetujuan otomatis senyap bersifat sempit: ini hanya berlaku untuk koneksi ulang lokal tepercaya non-browser yang sudah membuktikan kepemilikan kredensial lokal atau bersama, termasuk koneksi ulang aplikasi native host yang sama setelah perubahan metadata versi OS. Klien browser/Control UI dan klien jarak jauh tetap menggunakan alur persetujuan ulang eksplisit. Peningkatan cakupan (read ke write/admin) dan perubahan kunci publik tidak memenuhi syarat untuk persetujuan otomatis metadata-upgrade - semuanya tetap menjadi permintaan persetujuan ulang eksplisit.

​
Pembantu pairing QR

/pair qr merender payload pairing sebagai media terstruktur sehingga klien mobile dan browser dapat memindainya secara langsung. Menghapus perangkat juga membersihkan permintaan pairing tertunda yang usang untuk id perangkat tersebut, sehingga nodes pending tidak menampilkan baris yatim setelah pencabutan.

​
Lokalitas dan header yang diteruskan

Pairing Gateway memperlakukan koneksi sebagai loopback hanya saat socket mentah dan bukti proxy upstream sama-sama sepakat. Jika permintaan tiba di loopback tetapi membawa bukti header Forwarded, X-Forwarded-*, atau X-Real-IP, bukti header yang diteruskan itu mendiskualifikasi klaim lokalitas loopback. Jalur pairing kemudian memerlukan persetujuan eksplisit alih-alih secara senyap memperlakukan permintaan sebagai koneksi host yang sama. Lihat Auth Proxy Tepercaya untuk aturan yang setara pada auth operator.

​
Penyimpanan (lokal, privat)

Status pairing disimpan di bawah direktori status Gateway (default ~/.openclaw):
  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/nodes/pending.json
Jika Anda mengganti OPENCLAW_STATE_DIR, folder nodes/ ikut berpindah. Catatan keamanan:
  • Token adalah rahasia; perlakukan paired.json sebagai sensitif.
  • Merotasi token memerlukan persetujuan ulang (atau menghapus entri node).

​
Perilaku transpor

  • Transpor bersifat tanpa status; tidak menyimpan keanggotaan.
  • Jika Gateway offline atau pairing dinonaktifkan, node tidak dapat pairing.
  • Jika Gateway berada dalam mode jarak jauh, pairing tetap terjadi terhadap penyimpanan Gateway jarak jauh.

​
Terkait