English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Penyandingan yang dikelola Gateway

Dalam penyandingan milik Gateway, Gateway adalah sumber kebenaran untuk menentukan Node mana yang diizinkan bergabung. UI (aplikasi macOS, klien masa depan) hanyalah antarmuka yang menyetujui atau menolak permintaan tertunda.

Penting: Node WS menggunakan penyandingan perangkat (role node) selama connect. node.pair.* adalah penyimpanan penyandingan terpisah dan tidak mengendalikan jabat tangan WS. Hanya klien yang secara eksplisit memanggil node.pair.* yang menggunakan alur ini.

Konsep

  • Permintaan tertunda: sebuah Node meminta untuk bergabung; memerlukan persetujuan.
  • Node tersanding: Node yang disetujui dengan token autentikasi yang diterbitkan.
  • Transpor: titik akhir WS Gateway meneruskan permintaan tetapi tidak menentukan keanggotaan. (Dukungan jembatan TCP lama telah dihapus.)

Cara kerja penyandingan

  1. Sebuah Node terhubung ke WS Gateway dan meminta penyandingan.
  2. Gateway menyimpan permintaan tertunda dan memancarkan node.pair.requested.
  3. Anda menyetujui atau menolak permintaan tersebut (CLI atau UI).
  4. Saat disetujui, Gateway menerbitkan token baru (token dirotasi saat penyandingan ulang).
  5. Node terhubung ulang menggunakan token dan sekarang "tersanding".

Permintaan tertunda kedaluwarsa otomatis setelah 5 menit.

Alur kerja CLI (ramah tanpa antarmuka grafis)

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 tersanding/terhubung beserta kapabilitasnya.

Permukaan API (protokol Gateway)

Peristiwa:

  • node.pair.requested - dipancarkan ketika permintaan tertunda baru dibuat.
  • node.pair.resolved - dipancarkan ketika permintaan disetujui/ditolak/kedaluwarsa.

Metode:

  • node.pair.request - membuat atau menggunakan ulang permintaan tertunda.
  • node.pair.list - mencantumkan Node tertunda + tersanding (operator.pairing).
  • node.pair.approve - menyetujui permintaan tertunda (menerbitkan token).
  • node.pair.reject - menolak permintaan tertunda.
  • node.pair.remove - menghapus entri Node tersanding yang usang.
  • 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 disimpan dan snapshot perintah terdeklarasi terbaru yang diizinkan 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 di Cakupan operator.
  • Permintaan dapat menyertakan silent: true sebagai petunjuk untuk alur persetujuan otomatis.
  • node.pair.approve menggunakan perintah terdeklarasi milik permintaan tertunda untuk menerapkan 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+)

Ketika sebuah Node terhubung untuk pertama kali, penyandingan diminta secara otomatis. Sampai permintaan penyandingan disetujui, semua perintah Node tertunda dari Node tersebut difilter dan tidak akan dijalankan. Setelah kepercayaan ditetapkan melalui persetujuan penyandingan, perintah yang dideklarasikan Node menjadi tersedia dengan tetap tunduk pada kebijakan perintah normal.

Ini berarti:

  • Node yang sebelumnya hanya mengandalkan penyandingan perangkat untuk mengekspos perintah kini harus menyelesaikan penyandingan Node.
  • Perintah yang diantrekan sebelum persetujuan penyandingan 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 dipicu notifikasi atau dipicu Node yang sebelumnya mengandalkan akses alat host atau sesi yang lebih luas mungkin perlu disesuaikan. Pengerasan keamanan ini memastikan peristiwa Node tidak dapat meningkat menjadi akses alat tingkat host di luar batas kepercayaan yang diizinkan Node.

Pembaruan kehadiran Node yang persisten mengikuti batas identitas yang sama. Peristiwa node.presence.alive hanya diterima dari sesi perangkat Node yang terautentikasi dan memperbarui metadata penyandingan hanya ketika identitas perangkat/Node sudah tersanding. Nilai client.id yang dideklarasikan sendiri tidak cukup untuk menulis status terakhir terlihat.

Persetujuan otomatis (aplikasi macOS)

Aplikasi macOS dapat secara opsional mencoba persetujuan senyap ketika:

  • permintaan ditandai silent, dan
  • aplikasi dapat memverifikasi koneksi SSH ke host Gateway menggunakan pengguna yang sama.

Jika persetujuan senyap gagal, alur akan kembali ke prompt "Setujui/Tolak" normal.

Persetujuan otomatis perangkat CIDR tepercaya

Penyandingan perangkat WS untuk role: node tetap manual secara bawaan. Untuk jaringan Node privat tempat Gateway sudah memercayai jalur jaringan, operator dapat memilih ikut serta dengan CIDR eksplisit atau IP persis:

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

Batas keamanan:

  • Dinonaktifkan ketika gateway.nodes.pairing.autoApproveCidrs tidak diatur.
  • Tidak ada mode persetujuan otomatis menyeluruh untuk LAN atau jaringan privat.
  • Hanya penyandingan 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 proxy tepercaya loopback pada host yang sama tidak memenuhi syarat karena jalur tersebut dapat dipalsukan oleh pemanggil lokal.

Persetujuan otomatis peningkatan metadata

Ketika perangkat yang sudah tersanding terhubung ulang hanya dengan perubahan metadata yang tidak sensitif (misalnya, nama tampilan atau petunjuk platform klien), OpenClaw memperlakukan itu sebagai metadata-upgrade. Persetujuan otomatis senyap bersifat sempit: hanya berlaku untuk penyambungan ulang lokal tepercaya non-browser yang sudah membuktikan kepemilikan kredensial lokal atau bersama, termasuk penyambungan ulang aplikasi asli 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 ke tulis/admin) dan perubahan kunci publik tidak memenuhi syarat untuk persetujuan otomatis peningkatan metadata - keduanya tetap menjadi permintaan persetujuan ulang eksplisit.

Pembantu penyandingan QR

/pair qr merender payload penyandingan sebagai media terstruktur sehingga klien seluler dan browser dapat memindainya langsung.

Menghapus perangkat juga membersihkan permintaan penyandingan tertunda yang usang untuk ID perangkat tersebut, sehingga nodes pending tidak menampilkan baris tersisa setelah pencabutan.

Lokalitas dan header yang diteruskan

Penyandingan Gateway memperlakukan koneksi sebagai loopback hanya ketika socket mentah dan bukti proxy hulu sama-sama sesuai. Jika permintaan tiba melalui loopback tetapi membawa header X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto yang menunjuk ke asal non-lokal, bukti header yang diteruskan tersebut menggugurkan klaim lokalitas loopback. Jalur penyandingan kemudian memerlukan persetujuan eksplisit alih-alih secara senyap memperlakukan permintaan sebagai koneksi host yang sama. Lihat Autentikasi Proxy Tepercaya untuk aturan setara pada autentikasi operator.

Penyimpanan (lokal, privat)

Status penyandingan disimpan di bawah direktori status Gateway (bawaan ~/.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; transpor tidak menyimpan keanggotaan.
  • Jika Gateway tidak online atau penyandingan dinonaktifkan, Node tidak dapat melakukan penyandingan.
  • Jika Gateway berada dalam mode jarak jauh, penyandingan tetap terjadi terhadap penyimpanan Gateway jarak jauh.

Terkait