openclaw node

Chạy một headless node host kết nối tới Gateway WebSocket và cung cấp system.run / system.which trên máy này.

Tại sao dùng node host?

Dùng node host khi các bạn muốn Agent chạy lệnh trên các máy khác trong mạng mà không cần cài đặt ứng dụng macOS đầy đủ ở đó.

Các trường hợp sử dụng phổ biến:

  • Chạy lệnh trên các máy Linux/Windows từ xa (build server, máy lab, NAS).
  • Giữ exec sandboxed trên gateway, nhưng ủy quyền các lệnh đã duyệt cho các host khác.
  • Cung cấp một execution target nhẹ, headless cho automation hoặc CI nodes.

Việc thực thi vẫn được bảo vệ bởi exec approvals và allowlist theo từng Agent trên node host, nên các bạn có thể kiểm soát quyền truy cập lệnh một cách rõ ràng.

Browser proxy (zero-config)

Node host tự động quảng bá browser proxy nếu browser.enabled không bị tắt trên node. Điều này cho phép Agent sử dụng browser automation trên node đó mà không cần cấu hình thêm.

Tắt nó trên node nếu cần:

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

Run (foreground)

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

Các tùy chọn:

  • --host <host>: Gateway WebSocket host (mặc định: 127.0.0.1)
  • --port <port>: Gateway WebSocket port (mặc định: 18789)
  • --tls: Dùng TLS cho kết nối gateway
  • --tls-fingerprint <sha256>: TLS certificate fingerprint mong đợi (sha256)
  • --node-id <id>: Ghi đè node id (xóa pairing token)
  • --display-name <name>: Ghi đè tên hiển thị của node

Service (background)

Cài đặt headless node host như một user service.

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

Các tùy chọn:

  • --host <host>: Gateway WebSocket host (mặc định: 127.0.0.1)
  • --port <port>: Gateway WebSocket port (mặc định: 18789)
  • --tls: Dùng TLS cho kết nối gateway
  • --tls-fingerprint <sha256>: TLS certificate fingerprint mong đợi (sha256)
  • --node-id <id>: Ghi đè node id (xóa pairing token)
  • --display-name <name>: Ghi đè tên hiển thị của node
  • --runtime <runtime>: Service runtime (node hoặc bun)
  • --force: Cài đặt lại/ghi đè nếu đã được cài

Quản lý service:

openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall

Dùng openclaw node run để chạy node host ở foreground (không phải service).

Các lệnh service chấp nhận --json để xuất output dạng machine-readable.

Pairing

Kết nối đầu tiên sẽ tạo một pending node pair request trên Gateway. Phê duyệt nó bằng:

openclaw nodes pending
openclaw nodes approve <requestId>

Node host lưu trữ node id, token, display name và thông tin kết nối gateway trong ~/.openclaw/node.json.

Exec approvals

system.run được kiểm soát bởi local exec approvals:

  • ~/.openclaw/exec-approvals.json
  • Exec approvals
  • openclaw approvals --node <id|name|ip> (chỉnh sửa từ Gateway)