openclaw node

Jalankan host node tanpa antarmuka yang terhubung ke WebSocket Gateway dan mengekspos system.run / system.which pada mesin ini.

Mengapa menggunakan host node?

Gunakan host node saat Anda ingin agen menjalankan perintah pada mesin lain di jaringan Anda tanpa memasang aplikasi pendamping macOS lengkap di sana.

Kasus penggunaan umum:

• Menjalankan perintah pada mesin Linux/Windows jarak jauh (server build, mesin laboratorium, NAS).
• Menjaga exec tetap terisolasi di Gateway, tetapi mendelegasikan eksekusi yang disetujui ke host lain.
• Menyediakan target eksekusi ringan tanpa antarmuka untuk otomatisasi atau node CI.

Eksekusi tetap dilindungi oleh persetujuan exec dan daftar izin per agen pada host node, sehingga Anda dapat menjaga akses perintah tetap terbatas dan eksplisit.

openclaw node run dapat memublikasikan alat berbasis Plugin atau MCP setelah terhubung. Secara default, Gateway memercayai deskriptor dari node yang dipasangkan, dengan tetap mengharuskan perintah setiap deskriptor berada dalam cakupan perintah node yang disetujui. Agen melihat setiap deskriptor yang diterima sebagai alat Plugin biasa, tetapi eksekusi tetap berlangsung melalui node.invoke, sehingga pemutusan koneksi node menghapus alat tersebut dari eksekusi agen baru. Operator Gateway dapat menonaktifkan publikasi dengan gateway.nodes.pluginTools.enabled: false.

Untuk alat MCP deklaratif, tambahkan struktur server MCP biasa di bawah nodeHost.mcp.servers dalam openclaw.json pada mesin node, lalu mulai ulang host node. Node mendeklarasikan kelompok perintah mcp.tools.call.v1 yang memerlukan persetujuan dan memublikasikan alat yang tercantum setelah terhubung; mengubah daftar server kemudian tidak memerlukan pemasangan ulang. Lihat Server MCP yang dihost di node.

Proksi peramban (tanpa konfigurasi)

Host node secara otomatis mengiklankan proksi peramban jika browser.enabled tidak dinonaktifkan pada node. Hal ini memungkinkan agen menggunakan otomatisasi peramban pada node tersebut tanpa konfigurasi tambahan.

Secara default, proksi mengekspos cakupan profil peramban normal milik node. Jika Anda menetapkan nodeHost.browserProxy.allowProfiles, proksi menjadi terbatas: penargetan profil yang tidak tercantum dalam daftar izin ditolak, dan rute pembuatan/penghapusan profil persisten diblokir melalui proksi.

Nonaktifkan pada node jika diperlukan:

{  nodeHost: {    browserProxy: {      enabled: false,    },  },}

Menjalankan (latar depan)

openclaw node run --host <gateway-host> --port 18789

Opsi:

• --host <host>: Host WebSocket Gateway (default: 127.0.0.1)
• --port <port>: Porta WebSocket Gateway (default: 18789)
• --context-path <path>: Jalur konteks WebSocket Gateway (misalnya /openclaw-gw). Ditambahkan ke URL WebSocket.
• --tls: Menggunakan TLS untuk koneksi Gateway
• --no-tls: Memaksakan koneksi Gateway teks biasa meskipun konfigurasi Gateway lokal mengaktifkan TLS
• --tls-fingerprint <sha256>: Sidik jari sertifikat TLS yang diharapkan (sha256)
• --node-id <id>: Mengganti ID instans klien lama yang disimpan dalam node.json (tidak mereset pemasangan)
• --display-name <name>: Mengganti nama tampilan node

Autentikasi Gateway untuk host node

openclaw node run dan openclaw node install menentukan autentikasi Gateway dari konfigurasi/variabel lingkungan (tidak ada flag --token/--password pada perintah node):

• OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD diperiksa terlebih dahulu.
• Kemudian cadangan konfigurasi lokal: gateway.auth.token / gateway.auth.password.
• Dalam mode lokal, host node secara sengaja tidak mewarisi gateway.remote.token / gateway.remote.password.
• Jika gateway.auth.token / gateway.auth.password dikonfigurasi secara eksplisit melalui SecretRef dan tidak dapat ditentukan, penentuan autentikasi node gagal secara tertutup (tanpa cadangan jarak jauh yang menyamarkan kegagalan).
• Dalam gateway.mode=remote, kolom klien jarak jauh (gateway.remote.token / gateway.remote.password) juga dapat digunakan sesuai aturan prioritas jarak jauh.
• Penentuan autentikasi host node hanya mematuhi variabel lingkungan OPENCLAW_GATEWAY_*.

Untuk node yang terhubung ke Gateway ws:// teks biasa, local loopback, literal IP privat, .local, dan host Tailnet *.ts.net diterima. Untuk nama DNS privat tepercaya lainnya, tetapkan OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1; tanpanya, proses awal node gagal secara tertutup dan meminta Anda menggunakan wss://, terowongan SSH, atau Tailscale. Ini adalah pilihan eksplisit melalui lingkungan proses, bukan kunci konfigurasi openclaw.json. openclaw node install menyimpannya dalam layanan node yang diawasi jika variabel tersebut ada dalam lingkungan perintah pemasangan.

Layanan (latar belakang)

Pasang host node tanpa antarmuka sebagai layanan pengguna (launchd pada macOS, systemd pada Linux, Windows Task Scheduler pada Windows).

openclaw node install --host <gateway-host> --port 18789

Opsi:

• --host <host>: Host WebSocket Gateway (default: 127.0.0.1)
• --port <port>: Porta WebSocket Gateway (default: 18789)
• --context-path <path>: Jalur konteks WebSocket Gateway (misalnya /openclaw-gw). Ditambahkan ke URL WebSocket.
• --tls: Menggunakan TLS untuk koneksi Gateway
• --tls-fingerprint <sha256>: Sidik jari sertifikat TLS yang diharapkan (sha256)
• --node-id <id>: Mengganti ID instans klien lama yang disimpan dalam node.json (tidak mereset pemasangan)
• --display-name <name>: Mengganti nama tampilan node
• --runtime <runtime>: Runtime layanan (node atau bun)
• --force: Memasang ulang/menimpa jika sudah terpasang

Kelola layanan:

openclaw node statusopenclaw node startopenclaw node stopopenclaw node restartopenclaw node uninstall

Gunakan openclaw node run untuk host node latar depan (tanpa layanan).

Perintah layanan menerima --json untuk keluaran yang dapat dibaca mesin.

Host node mencoba kembali ketika Gateway dimulai ulang atau koneksi jaringan ditutup, dalam proses yang sama. Jika Gateway melaporkan jeda autentikasi token/kata sandi/bootstrap yang bersifat terminal, host node mencatat detail penutupan dan keluar dengan status bukan nol agar launchd/systemd/Task Scheduler dapat memulai ulang dengan konfigurasi dan kredensial baru. Jeda yang memerlukan pemasangan tetap berada dalam alur latar depan agar permintaan yang tertunda dapat disetujui.

Pemasangan

Koneksi pertama membuat permintaan pemasangan perangkat yang tertunda (role: node) pada Gateway.

Saat host Gateway dapat menggunakan SSH ke host node secara noninteraktif (pengguna yang sama, kunci host tepercaya), permintaan tertunda disetujui secara otomatis: Gateway menjalankan openclaw node identity --json pada host node melalui SSH dan menyetujui jika kunci perangkat cocok persis. Ini aktif secara default; lihat Persetujuan otomatis perangkat yang diverifikasi SSH untuk persyaratan dan cara menonaktifkannya (gateway.nodes.pairing.sshVerify: false).

Jika tidak, setujui secara manual melalui:

openclaw devices listopenclaw devices approve <requestId>

Periksa identitas node lokal yang diverifikasi oleh Gateway:

openclaw node identity --json

Perintah ini mencetak ID perangkat dan kunci publik dari identity/device.json dan tidak pernah membuat atau mengubah berkas identitas.

Pada jaringan node yang dikontrol secara ketat, operator Gateway dapat secara eksplisit memilih untuk menyetujui secara otomatis pemasangan node pertama kali dari CIDR tepercaya:

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

Fitur ini dinonaktifkan secara default (autoApproveCidrs tidak ditetapkan). Fitur ini hanya berlaku untuk pemasangan role: node baru tanpa cakupan yang diminta, dari IP klien yang dipercayai Gateway. Klien operator/peramban, Control UI, WebChat, serta peningkatan peran, cakupan, metadata, atau kunci publik tetap memerlukan persetujuan manual.

Jika node mencoba kembali pemasangan dengan detail autentikasi yang berubah (peran/cakupan/kunci publik), permintaan tertunda sebelumnya digantikan dan requestId baru dibuat. Jalankan kembali openclaw devices list sebelum memberikan persetujuan.

Status identitas dan pemasangan

Node tanpa antarmuka memisahkan ID instans klien lamanya dari identitas perangkat bertanda tangan yang digunakan Gateway untuk pemasangan dan perutean. Berkas-berkas ini berada di direktori status OpenClaw (~/.openclaw secara default, atau $OPENCLAW_STATE_DIR jika ditetapkan):

--node-id hanya mengubah ID instans klien dalam node.json. Flag ini tidak mengubah ID perangkat kriptografis atau menghapus autentikasi pemasangan. Demikian pula, hanya menghapus node.json tidak mereset pemasangan. Untuk mencabut dan memasangkan ulang node:

1. Pada Gateway, jalankan openclaw nodes remove --node <id|name|ip>.
2. Pada node, mulai ulang layanan yang terpasang dengan openclaw node restart, atau hentikan dan jalankan kembali perintah latar depan openclaw node run. Ini memulai alur pemasangan perangkat. Jika openclaw devices list tidak menampilkan permintaan dan node melaporkan AUTH_DEVICE_TOKEN_MISMATCH, mulai ulang atau jalankan kembali sekali lagi. Percobaan yang ditolak menghapus token lokal yang kini telah dicabut; percobaan berikutnya dapat meminta pemasangan.
3. Pada Gateway, jalankan openclaw devices list, lalu openclaw devices approve <deviceRequestId>.
4. Mulai ulang atau jalankan kembali node sekali lagi. Klien yang dijeda untuk pemasangan tidak dilanjutkan secara otomatis setelah persetujuan; koneksi ulang ini membuat permintaan cakupan perintah yang terpisah.
5. Pada Gateway, jalankan openclaw nodes pending, lalu openclaw nodes approve <nodeRequestId>.

Kedua ID permintaan tersebut berbeda. Kebijakan CIDR tepercaya yang berlaku dapat menyetujui secara otomatis langkah pemasangan perangkat pertama kali; persetujuan cakupan perintah tetap menjadi pemeriksaan terpisah.

Rilis OpenClaw lama dapat meninggalkan kolom token lama dalam node.json. OpenClaw saat ini tidak menggunakan kolom tersebut dan menghapusnya saat host node menyimpan berkas itu lagi. Jaga kerahasiaan kedua berkas di bawah identity/; berkas tersebut berisi pasangan kunci perangkat dan token autentikasi.

Persetujuan exec

system.run dibatasi oleh persetujuan exec lokal:

• $OPENCLAW_STATE_DIR/exec-approvals.json, atau ~/.openclaw/exec-approvals.json jika variabel tidak ditetapkan
• Persetujuan exec
• openclaw approvals --node <id|name|ip> (sunting dari Gateway)

Untuk exec node asinkron yang disetujui, OpenClaw menyiapkan systemRunPlan kanonis sebelum meminta persetujuan. Penerusan system.run yang kemudian disetujui menggunakan kembali rencana tersimpan tersebut, sehingga perubahan pada kolom perintah/cwd/sesi setelah permintaan persetujuan dibuat akan ditolak alih-alih mengubah apa yang dijalankan node.

Terkait

• Referensi CLI
• Node