Nodes

Node là thiết bị đi kèm (macOS/iOS/Android/headless) kết nối với Gateway qua WebSocket (cùng port với operators) với role: "node" và cung cấp các lệnh (ví dụ canvas.*, camera.*, system.*) thông qua node.invoke. Chi tiết giao thức: Gateway protocol.

Legacy transport: Bridge protocol (TCP JSONL; đã deprecated/loại bỏ cho các node hiện tại).

macOS cũng có thể chạy ở node mode: ứng dụng menubar kết nối với WS server của Gateway và cung cấp các lệnh canvas/camera local như một node (để openclaw nodes … hoạt động với Mac này).

Lưu ý:

  • Nodes là thiết bị ngoại vi, không phải gateways. Chúng không chạy gateway service.
  • Tin nhắn từ Telegram/WhatsApp/v.v. đến gateway, không phải nodes.

Pairing + trạng thái

WS nodes dùng device pairing. Nodes trình diện device identity trong quá trình connect; Gateway tạo device pairing request với role: node. Phê duyệt qua devices CLI (hoặc UI).

Các lệnh CLI nhanh:

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

Lưu ý:

  • nodes status đánh dấu node là paired khi device pairing role của nó bao gồm node.
  • node.pair.* (CLI: openclaw nodes pending/approve/reject) là một gateway-owned node pairing store riêng biệt; nó không kiểm soát WS connect handshake.

Remote node host (system.run)

Dùng node host khi Gateway của các bạn chạy trên một máy và các bạn muốn lệnh thực thi trên máy khác. Model vẫn giao tiếp với gateway; gateway chuyển tiếp các lệnh exec đến node host khi chọn host=node.

Cái gì chạy ở đâu

  • Gateway host: nhận tin nhắn, chạy model, định tuyến tool calls.
  • Node host: thực thi system.run/system.which trên máy node.
  • Approvals: được thực thi trên node host qua ~/.openclaw/exec-approvals.json.

Khởi động node host (foreground)

Trên máy node:

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

Remote gateway qua SSH tunnel (loopback bind)

Nếu Gateway bind với loopback (gateway.bind=loopback, mặc định ở local mode), các remote node hosts không thể kết nối trực tiếp. Tạo SSH tunnel và trỏ node host đến local end của tunnel.

Ví dụ (node host -> gateway host):

# Terminal A (giữ chạy): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export gateway token và kết nối qua tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Lưu ý:

  • Token là gateway.auth.token từ gateway config (~/.openclaw/openclaw.json trên gateway host).
  • openclaw node run đọc OPENCLAW_GATEWAY_TOKEN để xác thực.

Khởi động node host (service)

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

Pair + đặt tên

Trên gateway host:

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes list

Các tùy chọn đặt tên:

  • --display-name trên openclaw node run / openclaw node install (lưu trong ~/.openclaw/node.json trên node).
  • openclaw nodes rename --node <id|name|ip> --name "Build Node" (gateway override).

Allowlist các lệnh

Exec approvals là per node host. Thêm allowlist entries từ gateway:

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

Approvals nằm trên node host tại ~/.openclaw/exec-approvals.json.

Trỏ exec đến node

Cấu hình mặc định (gateway config):

openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

Hoặc per session:

/exec host=node security=allowlist node=<id-or-name>

Sau khi đặt, bất kỳ lệnh exec nào với host=node sẽ chạy trên node host (tuân theo node allowlist/approvals).

Liên quan:

Gọi lệnh

Low-level (raw RPC):

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

Các helpers cấp cao hơn tồn tại cho các workflow “cung cấp MEDIA attachment cho agent” phổ biến.

Screenshots (canvas snapshots)

Nếu node đang hiển thị Canvas (WebView), canvas.snapshot trả về { format, base64 }.

CLI helper (ghi vào temp file và in MEDIA:<path>):

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas controls

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

Lưu ý:

  • canvas present chấp nhận URLs hoặc local file paths (--target), cộng với --x/--y/--width/--height tùy chọn để định vị.
  • canvas eval chấp nhận inline JS (--js) hoặc positional arg.

A2UI (Canvas)

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

Lưu ý:

  • Chỉ hỗ trợ A2UI v0.8 JSONL (v0.9/createSurface bị từ chối).

Photos + videos (node camera)

Photos (jpg):

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # mặc định: cả hai facings (2 dòng MEDIA)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

Video clips (mp4):

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

Lưu ý:

  • Node phải được foregrounded cho canvas.* và camera.* (các lệnh gọi background trả về NODE_BACKGROUND_UNAVAILABLE).
  • Clip duration bị giới hạn (hiện tại <= 60s) để tránh base64 payloads quá lớn.
  • Android sẽ nhắc cấp quyền CAMERA/RECORD_AUDIO khi có thể; quyền bị từ chối sẽ fail với *_PERMISSION_REQUIRED.

Screen recordings (nodes)

Nodes cung cấp screen.record (mp4). Ví dụ:

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

Lưu ý:

  • screen.record yêu cầu node app được foregrounded.
  • Android sẽ hiển thị system screen-capture prompt trước khi ghi.
  • Screen recordings bị giới hạn ở <= 60s.
  • --no-audio tắt microphone capture (hỗ trợ trên iOS/Android; macOS dùng system capture audio).
  • Dùng --screen <index> để chọn màn hình khi có nhiều screens.

Location (nodes)

Nodes cung cấp location.get khi Location được bật trong settings.

CLI helper:

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

Lưu ý:

  • Location tắt mặc định.
  • “Always” yêu cầu system permission; background fetch là best-effort.
  • Response bao gồm lat/lon, accuracy (meters), và timestamp.

SMS (Android nodes)

Android nodes có thể cung cấp sms.send khi người dùng cấp quyền SMS và thiết bị hỗ trợ telephony.

Low-level invoke:

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

Lưu ý:

  • Permission prompt phải được chấp nhận trên thiết bị Android trước khi capability được quảng cáo.
  • Thiết bị chỉ Wi-Fi không có telephony sẽ không quảng cáo sms.send.

System commands (node host / mac node)

macOS node cung cấp system.run, system.notify, và system.execApprovals.get/set. Headless node host cung cấp system.run, system.which, và system.execApprovals.get/set.

Ví dụ:

openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"

Lưu ý:

  • system.run trả về stdout/stderr/exit code trong payload.
  • system.notify tuân theo notification permission state trên macOS app.
  • system.run hỗ trợ --cwd, --env KEY=VAL, --command-timeout, và --needs-screen-recording.
  • system.notify hỗ trợ --priority <passive|active|timeSensitive> và --delivery <system|overlay|auto>.
  • macOS nodes bỏ qua PATH overrides; headless node hosts chỉ chấp nhận PATH khi nó prepend node host PATH.
  • Trên macOS node mode, system.run được kiểm soát bởi exec approvals trong macOS app (Settings → Exec approvals). Ask/allowlist/full hoạt động giống như headless node host; denied prompts trả về SYSTEM_RUN_DENIED.
  • Trên headless node host, system.run được kiểm soát bởi exec approvals (~/.openclaw/exec-approvals.json).

Exec node binding

Khi có nhiều nodes, các bạn có thể bind exec với một node cụ thể. Điều này đặt node mặc định cho exec host=node (và có thể override per agent).

Global default:

openclaw config set tools.exec.node "node-id-or-name"

Per-agent override:

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

Unset để cho phép bất kỳ node nào:

openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

Permissions map

Nodes có thể bao gồm permissions map trong node.list / node.describe, được key bởi permission name (ví dụ screenRecording, accessibility) với giá trị boolean (true = granted).

Headless node host (cross-platform)

OpenClaw có thể chạy headless node host (không UI) kết nối với Gateway WebSocket và cung cấp system.run / system.which. Điều này hữu ích trên Linux/Windows hoặc để chạy minimal node cùng với server.

Khởi động:

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

Lưu ý:

  • Pairing vẫn được yêu cầu (Gateway sẽ hiển thị node approval prompt).
  • Node host lưu node id, token, display name, và gateway connection info trong ~/.openclaw/node.json.
  • Exec approvals được thực thi locally qua ~/.openclaw/exec-approvals.json (xem Exec approvals).
  • Trên macOS, headless node host ưu tiên companion app exec host khi có thể kết nối và fallback sang local execution nếu app không khả dụng. Đặt OPENCLAW_NODE_EXEC_HOST=app để yêu cầu app, hoặc OPENCLAW_NODE_EXEC_FALLBACK=0 để tắt fallback.
  • Thêm --tls / --tls-fingerprint khi Gateway WS dùng TLS.

Mac node mode

  • macOS menubar app kết nối với Gateway WS server như một node (để openclaw nodes … hoạt động với Mac này).
  • Ở remote mode, app mở SSH tunnel cho Gateway port và kết nối với localhost.