OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Pemasangan Node

Pemasangan Node memiliki dua lapisan, yang keduanya disimpan pada rekaman perangkat yang dipasangkan dalam basis data status SQLite milik Gateway:

  • Pemasangan perangkat (peran node) membatasi handshake connect. Lihat Persetujuan otomatis perangkat berdasarkan CIDR tepercaya di bawah dan Pemasangan saluran.
  • Persetujuan kapabilitas Node (node.pair.*) membatasi kapabilitas/perintah yang dideklarasikan dan boleh diekspos oleh Node yang terhubung. Gateway adalah sumber kebenaran; UI (aplikasi macOS, Control UI) merupakan antarmuka yang menyetujui atau menolak permintaan tertunda.

Penyimpanan pemasangan Node mandiri sebelumnya (nodes/paired.json dengan token per Node, dihentikan dari jalur koneksi pada Januari 2026) telah dihapus: Gateway menggabungkan semua baris yang tersisa ke dalam rekaman perangkat satu kali saat dimulai dan mengarsipkan berkas lama dengan akhiran .migrated. Dukungan bridge TCP lama telah dihapus.

Cara kerja persetujuan kapabilitas

  1. Node terhubung ke WS Gateway (pemasangan perangkat membatasi langkah ini).
  2. Gateway membandingkan cakupan kapabilitas/perintah yang dideklarasikan dengan cakupan yang disetujui; cakupan baru atau yang diperluas menyimpan permintaan tertunda pada rekaman perangkat dan memancarkan node.pair.requested.
  3. Anda menyetujui atau menolak permintaan tersebut (CLI atau UI).
  4. Hingga disetujui, perintah Node tetap difilter; persetujuan mengekspos cakupan yang dideklarasikan, dengan tetap tunduk pada kebijakan perintah normal.

Permintaan tertunda kedaluwarsa secara otomatis 5 menit setelah percobaan ulang terakhir Node — Node yang aktif menyambung kembali mempertahankan satu permintaan tertundanya tetap aktif, alih-alih membuat permintaan baru (dan perintah persetujuan) pada setiap percobaan.

Alur kerja CLI (cocok tanpa antarmuka grafis)

bash
openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw nodes remove --node <id|name|ip>openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status menampilkan Node yang dipasangkan/terhubung beserta kapabilitasnya.

Permukaan API (protokol Gateway)

Peristiwa:

  • node.pair.requested - dipancarkan saat permintaan tertunda baru dibuat.
  • node.pair.resolved - dipancarkan saat permintaan disetujui, ditolak, atau kedaluwarsa.

Metode:

  • node.pair.list - mencantumkan Node yang tertunda dan dipasangkan (operator.pairing).
  • node.pair.approve - menyetujui permintaan tertunda.
  • node.pair.reject - menolak permintaan tertunda.
  • node.pair.remove - menghapus Node yang dipasangkan. Tindakan ini mencabut peran node perangkat dalam penyimpanan perangkat terpasang, menghapus permukaan Node yang disetujui bersamanya, serta membatalkan/memutus sesi perangkat dengan peran Node tersebut. Perangkat dengan peran campuran (misalnya yang juga memiliki operator) mempertahankan barisnya dan hanya kehilangan peran node; baris perangkat yang hanya memiliki peran Node dihapus. Otorisasi: operator.pairing dapat menghapus baris Node non-operator; pemanggil dengan token perangkat yang mencabut peran Node miliknya sendiri pada perangkat dengan peran campuran juga memerlukan operator.admin.
  • node.rename - mengganti nama tampilan Node terpasang yang terlihat oleh operator.

Dihapus pada 2026.7: node.pair.request dan node.pair.verify. Permintaan tertunda dibuat oleh Gateway itu sendiri saat Node terhubung, dan token mandiri per Node yang dilayani keduanya sudah tidak ada; autentikasi Node menggunakan token pemasangan perangkat.

Catatan:

  • Penyambungan ulang dengan cakupan yang tidak berubah menggunakan kembali permintaan tertunda; permintaan berulang memperbarui metadata Node yang tersimpan dan snapshot terbaru perintah yang dideklarasikan serta masuk daftar izin agar dapat dilihat operator.
  • Tingkat cakupan operator dan pemeriksaan saat persetujuan dirangkum dalam Cakupan operator.
  • node.pair.approve menggunakan perintah yang dideklarasikan dalam permintaan tertunda untuk memberlakukan cakupan persetujuan tambahan:
    • permintaan tanpa perintah: operator.pairing
    • permintaan perintah non-eksekusi: operator.pairing + operator.write
    • permintaan system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Pembatasan perintah Node (2026.3.31+)

Saat Node terhubung untuk pertama kali, pemasangan diminta secara otomatis. Hingga permintaan tersebut disetujui, semua perintah Node tertunda dari Node tersebut difilter dan tidak akan dieksekusi. Setelah pemasangan disetujui, perintah yang dideklarasikan Node menjadi tersedia, dengan tetap tunduk pada kebijakan perintah normal.

Artinya:

  • Node yang sebelumnya hanya mengandalkan pemasangan perangkat untuk mengekspos perintah kini juga harus menyelesaikan pemasangan Node.
  • Perintah yang diantrekan sebelum persetujuan pemasangan akan dibuang, bukan ditunda.

Batas kepercayaan peristiwa Node (2026.3.31+)

Ringkasan yang berasal dari Node dan peristiwa sesi terkait dibatasi pada permukaan tepercaya yang dimaksudkan. Alur yang digerakkan oleh notifikasi atau dipicu Node, yang sebelumnya mengandalkan akses alat host atau sesi yang lebih luas, mungkin perlu disesuaikan. Penguatan ini mencegah peristiwa Node meningkatkan akses menjadi akses alat tingkat host melebihi batas kepercayaan yang diizinkan bagi Node tersebut.

Pembaruan keberadaan Node yang persisten mengikuti batas identitas yang sama: peristiwa node.presence.alive hanya diterima dari sesi perangkat Node yang terautentikasi, dan hanya memperbarui metadata pemasangan jika identitas perangkat/Node sudah dipasangkan. Nilai client.id yang dideklarasikan sendiri tidak cukup untuk menulis status terakhir terlihat.

Persetujuan otomatis perangkat yang diverifikasi melalui SSH (bawaan)

Pemasangan perangkat role: node pertama kali dari alamat privat/CGNAT disetujui secara otomatis ketika Gateway dapat membuktikan kepemilikan mesin melalui SSH: Gateway terhubung kembali ke host pemasangan (BatchMode, StrictHostKeyChecking=yes), menjalankan openclaw node identity --json di sana, dan hanya menyetujui jika ID perangkat jarak jauh dan kunci publik sama persis dengan permintaan tertunda. Kecocokan kunci inilah yang membuatnya aman: keterjangkauan saja tidak pernah menghasilkan persetujuan, sehingga sesama penyewa NAT, pengguna lain pada host bersama, dan pemalsuan LAN semuanya akan dialihkan ke perintah konfirmasi normal.

Diaktifkan secara bawaan. Persyaratan agar mekanisme ini berjalan:

  • Pengguna proses Gateway (atau sshVerify.user) dapat melakukan SSH ke host Node secara noninteraktif (kunci/agen; SSH Tailscale juga dapat digunakan), dan kunci host sudah dipercaya.
  • openclaw dapat ditemukan pada PATH jarak jauh untuk sh -lc noninteraktif.
  • IP yang terhubung adalah alamat privat, ULA, link-local, atau CGNAT langsung (tanpa proksi dan bukan local loopback), atau cocok dengan sshVerify.cidrs jika ditetapkan.
  • Ambang kelayakannya sama dengan persetujuan CIDR tepercaya: hanya pemasangan Node baru tanpa cakupan; peningkatan, browser, Control UI, dan WebChat selalu menampilkan perintah konfirmasi.

Saat pemeriksaan berjalan, klien Node diminta untuk terus mencoba kembali (wait_then_retry) alih-alih berhenti guna menunggu persetujuan manual; jika pemeriksaan gagal, percobaan berikutnya kembali ke alur perintah konfirmasi normal. Target yang gagal mendapat masa tunggu singkat (5 menit setelah ketidakcocokan kunci).

Perangkat yang disetujui merekam approvedVia: "ssh-verified" dan permukaan kapabilitas pertama yang dideklarasikannya disetujui dalam langkah yang sama — kecocokan kunci telah membuktikan bahwa Node berjalan di bawah akun operator pada mesin milik operator, yang merupakan klaim yang sama dengan persetujuan kapabilitas manual. Peningkatan permukaan berikutnya tetap menampilkan perintah konfirmasi.

Perkuat atau nonaktifkan:

json5
{  gateway: {    nodes: {      pairing: {        // Disable entirely:        sshVerify: false,        // ...or scope/tune the probe:        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },      },    },  },}

Persetujuan otomatis (aplikasi macOS)

Aplikasi macOS dapat mencoba persetujuan senyap atas permintaan kapabilitas Node ketika:

  • permintaan ditandai silent (Gateway menandai permukaan kapabilitas pertama sebagai senyap ketika pemasangan perangkat disetujui secara noninteraktif), dan
  • aplikasi dapat memverifikasi koneksi SSH ke host Gateway menggunakan pengguna yang sama.

Jika persetujuan senyap gagal, aplikasi kembali ke perintah konfirmasi normal Approve/Reject.

Persetujuan otomatis perangkat berdasarkan CIDR tepercaya

Pemasangan perangkat WS untuk role: node tetap manual secara bawaan. Untuk jaringan Node privat tempat Gateway telah memercayai jalur jaringan, operator dapat mengaktifkannya dengan CIDR eksplisit atau IP yang tepat:

json5
{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

Batas keamanan:

  • Dinonaktifkan ketika gateway.nodes.pairing.autoApproveCidrs tidak ditetapkan.
  • Tidak ada mode persetujuan otomatis menyeluruh untuk LAN atau jaringan privat; persetujuan otomatis yang diverifikasi melalui SSH (di atas) memerlukan kecocokan kriptografis kunci perangkat, bukan hanya kedekatan jaringan.
  • Hanya permintaan pemasangan 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 proksi tepercaya local loopback pada host yang sama tidak memenuhi syarat karena jalur tersebut dapat dipalsukan oleh pemanggil lokal.

Pembersihan penggantian pemasangan senyap

Persetujuan noninteraktif merekam asalnya pada baris perangkat terpasang: persetujuan kebijakan lokal pada host yang sama sebagai silent, persetujuan Node berdasarkan CIDR tepercaya sebagai trusted-cidr, dan persetujuan Node yang diverifikasi melalui SSH sebagai ssh-verified. Klien yang direktori statusnya bersifat sementara (direktori utama sementara, kontainer, sandbox per proses) membuat pasangan kunci perangkat baru pada setiap proses, dan setiap proses dipasangkan kembali secara senyap sebagai perangkat yang benar-benar baru — tanpa pembersihan, daftar perangkat terpasang bertambah satu baris usang per proses.

Ketika Gateway secara senyap menyetujui pemasangan perangkat lokal, Gateway menghentikan rekaman lama yang disetujui sebagai silent, yang termasuk dalam klaster klien yang sama (cocok berdasarkan clientId, clientMode, dan nama tampilan) serta sedang tidak terhubung. Klien lokal berjalan pada host Gateway itu sendiri, sehingga kunci klaster tidak mungkin cocok dengan mesin lain. Baris yang dihentikan langsung kehilangan tokennya; setiap entri pemasangan Node lama yang cocok dihapus dan peristiwa penghapusan node.pair.resolved disiarkan.

Batasan:

  • Hanya rekaman yang persetujuan terakhirnya berasal dari lokal pada host yang sama (silent) yang memenuhi syarat, baik sebagai pemicu maupun target. Pemasangan berdasarkan CIDR tepercaya dan yang diverifikasi melalui SSH melintasi host, tempat metadata tampilan bukan merupakan identitas mesin, sehingga tidak pernah dihapus secara otomatis — gunakan pembersihan Control UI atau openclaw nodes remove untuk pemasangan tersebut.
  • Pemasangan yang disetujui pemilik dan melalui kode QR/penyiapan (bootstrap) tidak pernah dihapus secara otomatis. Rekaman yang disetujui sebelum pencatatan asal tersedia tetap dilindungi, bahkan setelah persetujuan senyap berikutnya untuk ID perangkat yang sama.
  • Perangkat yang sedang terhubung dilewati, sehingga sesi lokal bersamaan dengan direktori status terpisah mempertahankan tokennya selama aktif. Rekaman yang disetujui dalam satu menit terakhir juga dilewati agar handshake pemasangan yang berlangsung bersamaan tidak dapat saling menghentikan sebelum koneksinya terdaftar.
  • Klien yang terpengaruh bersifat lokal berdasarkan konstruksinya, sehingga akan dipasangkan kembali secara senyap pada koneksi berikutnya.

Persetujuan otomatis peningkatan metadata

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

Pembantu pemasangan QR

/pair qr merender payload pemasangan sebagai media terstruktur agar klien seluler dan peramban dapat memindainya secara langsung.

Menghapus perangkat juga membersihkan setiap permintaan pemasangan tertunda yang sudah usang untuk id perangkat tersebut, sehingga nodes pending tidak menampilkan baris yatim setelah pencabutan.

Lokalitas dan header yang diteruskan

Pemasangan Gateway menganggap koneksi sebagai local loopback hanya jika soket mentah dan setiap bukti proksi hulu sama-sama menyetujuinya. Jika permintaan tiba melalui local loopback tetapi membawa bukti header Forwarded, X-Forwarded-*, atau X-Real-IP, bukti header yang diteruskan tersebut membatalkan klaim lokalitas local loopback, dan jalur pemasangan memerlukan persetujuan eksplisit alih-alih secara diam-diam menganggap permintaan sebagai koneksi dari host yang sama. Lihat Autentikasi Proksi Tepercaya untuk aturan yang setara pada autentikasi operator.

Penyimpanan (lokal, privat)

Status pemasangan berada dalam catatan perangkat yang dipasangkan di basis data status SQLite bersama pada direktori status Gateway (bawaan ~/.openclaw):

  • ~/.openclaw/state/openclaw.sqlite (perangkat yang dipasangkan dengan autentikasi perangkat, permukaan Node yang disetujui, permintaan permukaan tertunda, permintaan pemasangan perangkat tertunda, dan token bootstrap)

Jika Anda mengganti OPENCLAW_STATE_DIR, basis data akan ikut berpindah. Gateway yang ditingkatkan dari rilis dengan penyimpanan JSON akan mengimpornya saat mulai dan meninggalkan arsip devices/*.json.migrated serta nodes/*.json.migrated.

Catatan keamanan:

  • Token perangkat adalah rahasia; perlakukan basis data status sebagai data sensitif.
  • Rotasi token perangkat menggunakan openclaw devices rotate / device.token.rotate.

Perilaku transportasi

  • Transportasi bersifat tanpa status; transportasi tidak menyimpan keanggotaan.
  • Jika Gateway luring atau pemasangan dinonaktifkan, Node tidak dapat dipasangkan.
  • Dalam mode jarak jauh, pemasangan dilakukan terhadap penyimpanan Gateway jarak jauh.

Terkait

Was this useful?
On this page

On this page