openclaw node

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

Di macOS, aplikasi bilah menu sudah menyematkan runtime host node ini ke dalam koneksi node-nya sendiri dan menambahkan kemampuan native Mac. Gunakan openclaw node run di Mac hanya jika Anda sengaja menginginkan node tanpa antarmuka tanpa aplikasi. Menjalankan keduanya akan membuat dua identitas node untuk mesin yang sama.

Mengapa menggunakan host node?

Gunakan host node ketika 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 lab, NAS).
• Menjaga exec tetap dalam sandbox di gateway, tetapi mendelegasikan eksekusi yang disetujui ke host lain.
• Menyediakan target eksekusi tanpa antarmuka yang ringan 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 yang didukung plugin atau MCP setelah terhubung. Gateway memercayai deskriptor dari node yang telah dipasangkan secara default, sambil mewajibkan perintah setiap deskriptor tetap berada dalam cakupan perintah yang disetujui pada node. Agen melihat setiap deskriptor yang diterima sebagai alat plugin biasa, tetapi eksekusi tetap melewati node.invoke, sehingga memutus koneksi node akan 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 nantinya tidak memerlukan pemasangan ulang. Lihat Server MCP yang dihosting node.

Proksi browser (tanpa konfigurasi)

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

Secara default, proksi menyediakan cakupan profil browser normal milik node. Jika Anda menetapkan nodeHost.browserProxy.allowProfiles, proksi menjadi restriktif: penargetan profil yang tidak ada dalam daftar izin akan ditolak, dan rute pembuatan/penghapusan profil persisten akan 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>: Port WebSocket Gateway (default: 18789)
• --context-path <path>: Jalur konteks WebSocket Gateway (misalnya /openclaw-gw). Ditambahkan ke URL WebSocket.
• --tls: Gunakan TLS untuk koneksi gateway
• --no-tls: Paksa koneksi Gateway teks biasa meskipun konfigurasi Gateway lokal mengaktifkan TLS
• --tls-fingerprint <sha256>: Sidik jari sertifikat TLS yang diharapkan (sha256)
• --node-id <id>: Timpa ID instans klien yang disimpan dalam state SQLite bersama (tidak mengatur ulang pemasangan)
• --display-name <name>: Timpa nama tampilan node

Autentikasi Gateway untuk host node

openclaw node run dan openclaw node install menyelesaikan autentikasi gateway dari konfigurasi/lingkungan (tanpa flag --token/--password pada perintah node):

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

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

Layanan (latar belakang)

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

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

Opsi:

• --host <host>: Host WebSocket Gateway (default: 127.0.0.1)
• --port <port>: Port WebSocket Gateway (default: 18789)
• --context-path <path>: Jalur konteks WebSocket Gateway (misalnya /openclaw-gw). Ditambahkan ke URL WebSocket.
• --tls: Gunakan TLS untuk koneksi gateway
• --tls-fingerprint <sha256>: Sidik jari sertifikat TLS yang diharapkan (sha256)
• --node-id <id>: Timpa ID instans klien yang disimpan dalam state SQLite bersama (tidak mengatur ulang pemasangan)
• --display-name <name>: Timpa nama tampilan node
• --runtime <runtime>: Runtime layanan (node)
• --force: Instal ulang/timpa jika sudah terinstal

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 setelah Gateway dimulai ulang dan koneksi jaringan ditutup di dalam proses. Jika Gateway melaporkan jeda autentikasi terminal untuk token/kata sandi/bootstrap, 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.

Jika host Gateway dapat terhubung melalui SSH ke host node secara noninteraktif (pengguna yang sama, kunci host tepercaya), permintaan yang tertunda disetujui secara otomatis: Gateway menjalankan openclaw node identity --json pada host node melalui SSH dan menyetujuinya jika kunci perangkat cocok persis. Ini diaktifkan secara default; lihat Persetujuan otomatis perangkat yang diverifikasi melalui 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 digunakan Gateway untuk verifikasi:

openclaw node identity --json

Perintah ini mencetak ID perangkat dan kunci publik dari baris primary dalam state/openclaw.sqlite dan tidak pernah membuat basis data atau identitas baru.

Pada jaringan node yang dikontrol 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"],      },    },  },}

Ini dinonaktifkan secara default (autoApproveCidrs tidak ditetapkan). Ini hanya berlaku untuk pemasangan role: node baru tanpa cakupan yang diminta, dari IP klien yang dipercayai Gateway. Klien operator/browser, 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 persetujuan.

State identitas dan pemasangan

Node tanpa antarmuka memisahkan ID instans kliennya dari identitas perangkat bertanda tangan yang digunakan Gateway untuk pemasangan dan perutean. State ini berada dalam direktori state OpenClaw (~/.openclaw secara default, atau $OPENCLAW_STATE_DIR jika ditetapkan):

--node-id hanya mengubah ID instans klien dalam state SQLite bersama. Ini tidak mengubah ID perangkat kriptografis atau menghapus autentikasi pemasangan. Memigrasikan node.json yang dihentikan dengan openclaw doctor --fix juga tidak mengatur ulang 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 terinstal 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 melanjutkan 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 merupakan pemeriksaan terpisah.

Rilis OpenClaw lama menyimpan state host node dalam node.json dan identitas bertanda tangan dalam identity/device.json. Hentikan host node dan jalankan openclaw doctor --fix satu kali; Doctor mengklaim setiap sumber yang dihentikan, memvalidasinya, mengimpor dan memverifikasi baris SQLite kanonis, lalu menghapus file lama. Perintah node normal gagal secara tertutup dengan instruksi perbaikan ini selama salah satu file yang dihentikan atau klaim Doctor yang terinterupsi masih ada. Jaga kerahasiaan state/openclaw.sqlite dan identity/device-auth.json; keduanya berisi pasangan kunci perangkat dan token autentikasi. Autentikasi perangkat tetap berada di penyimpanan terpisah dan tidak ditulis ulang oleh migrasi identitas.

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> (edit dari Gateway)

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

Terkait

• Referensi CLI
• Node