---
read_when:
    - Menjalankan host Node tanpa antarmuka grafis
    - Memasangkan Node non-macOS untuk system.run
summary: Referensi CLI untuk `openclaw node` (host node tanpa antarmuka grafis)
title: Node
x-i18n:
    generated_at: "2026-07-19T04:52:49Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: c229e50dcff790a08ef155561a15a39220d6dccdc263d4a3d01ab8592f48de73
    source_path: cli/node.md
    workflow: 16
---

# `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](/id/nodes#node-hosted-mcp-servers).

## 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:

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

## Menjalankan (latar depan)

```bash
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).

```bash
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:

```bash
openclaw node status
openclaw node start
openclaw node stop
openclaw node restart
openclaw 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](/id/gateway/pairing#ssh-verified-device-auto-approval-default)
untuk persyaratan dan cara menonaktifkannya (`gateway.nodes.pairing.sshVerify: false`).

Jika tidak, setujui secara manual melalui:

```bash
openclaw devices list
openclaw devices approve <requestId>
```

Periksa identitas node lokal yang digunakan Gateway untuk verifikasi:

```bash
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:

```json5
{
  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):

| State                                                    | Tujuan                                                                                                                          |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `state/openclaw.sqlite` (`node_host_config`)             | ID instans klien, nama tampilan, dan metadata koneksi Gateway. Klien mengirim ID ini sebagai `instanceId`.                     |
| `state/openclaw.sqlite` (`device_identities`, `primary`) | Pasangan kunci Ed25519 bertanda tangan dan ID perangkat turunannya. Untuk koneksi bertanda tangan, ID perangkat ini adalah ID node yang dirutekan dan identitas pemasangan. |
| `identity/device-auth.json`                              | Token perangkat yang dipasangkan, dengan kunci berupa ID perangkat kriptografis dan peran.                                                                 |

`--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](/id/tools/exec-approvals)
- `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](/id/cli)
- [Node](/id/nodes)
