Nodes

node는 role: "node"로 Gateway WebSocket (운영자와 동일한 포트)에 연결하고 node.invoke를 통해 명령 표면(예: canvas.*, camera.*, system.*)을 노출하는 동반 장치(macOS/iOS/Android/headless)입니다. 프로토콜 세부사항: Gateway protocol.

레거시 전송: Bridge protocol (TCP JSONL; 현재 노드에 대해 더 이상 사용되지 않음/제거됨).

macOS는 node 모드에서도 실행할 수 있습니다: 메뉴 막대 앱이 Gateway의 WS 서버에 연결하고 로컬 canvas/camera 명령을 노드로 노출합니다(따라서 openclaw nodes …가 이 Mac에 대해 작동).

참고:

  • 노드는 주변 장치이지 Gateway가 아닙니다. Gateway 서비스를 실행하지 않습니다.
  • Telegram/WhatsApp/등의 메시지는 노드가 아닌 Gateway에 도착합니다.

페어링 + 상태

WS 노드는 장치 페어링을 사용합니다. 노드는 connect 중에 장치 ID를 제시합니다; Gateway는 role: node에 대한 장치 페어링 요청을 생성합니다. devices CLI(또는 UI)를 통해 승인하세요.

빠른 CLI:

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

참고:

  • nodes status는 장치 페어링 역할에 node가 포함된 경우 노드를 페어링됨으로 표시합니다.
  • node.pair.* (CLI: openclaw nodes pending/approve/reject)는 별도의 Gateway 소유 node 페어링 저장소입니다; WS connect 핸드셰이크를 게이트하지 않습니다.

원격 node 호스트 (system.run)

Gateway가 한 머신에서 실행되고 명령을 다른 머신에서 실행하려는 경우 node 호스트를 사용하세요. 모델은 여전히 Gateway와 통신합니다; Gateway는 host=node가 선택된 경우 exec 호출을 node 호스트로 전달합니다.

어디서 무엇이 실행되는가

  • Gateway 호스트: 메시지를 받고, 모델을 실행하고, 도구 호출을 라우팅합니다.
  • Node 호스트: 노드 머신에서 system.run/system.which를 실행합니다.
  • 승인: ~/.openclaw/exec-approvals.json을 통해 노드 호스트에서 적용됩니다.

node 호스트 시작 (포그라운드)

노드 머신에서:

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

node 호스트 시작 (서비스)

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

페어링 + 이름 지정

Gateway 호스트에서:

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

이름 지정 옵션:

  • openclaw node run / openclaw node install의 --display-name (노드의 ~/.openclaw/node.json에 유지).
  • openclaw nodes rename --node <id|name|ip> --name "Build Node" (Gateway 재정의).

명령 허용 목록

Exec 승인은 node 호스트당입니다. Gateway에서 허용 목록 항목을 추가하세요:

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

승인은 ~/.openclaw/exec-approvals.json의 노드 호스트에 있습니다.

노드를 가리키는 exec

기본값 구성 (Gateway 구성):

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

또는 세션당:

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

설정되면 host=node인 모든 exec 호출은 노드 호스트에서 실행됩니다(노드 허용 목록/승인에 따라).

관련 자료:

명령 호출

저수준 (원시 RPC):

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

일반적인 "agent에게 MEDIA 첨부 파일 제공" 워크플로우를 위한 고수준 도우미가 있습니다.

스크린샷 (canvas 스냅샷)

노드가 Canvas (WebView)를 표시하는 경우 canvas.snapshot은 { format, base64 }를 반환합니다.

CLI 도우미 (임시 파일에 작성하고 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 제어

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"

참고:

  • canvas present는 URL 또는 로컬 파일 경로(--target)를 허용하며, 위치 지정을 위한 선택적 --x/--y/--width/--height를 허용합니다.
  • canvas eval은 인라인 JS(--js) 또는 위치 인수를 허용합니다.

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>

참고:

  • A2UI v0.8 JSONL만 지원됩니다(v0.9/createSurface는 거부됨).

사진 + 비디오 (node camera)

사진 (jpg):

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # 기본값: 양쪽 방향 (2개의 MEDIA 라인)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

비디오 클립 (mp4):

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

참고:

  • 노드는 canvas.* 및 camera.*를 위해 포그라운드여야 합니다(백그라운드 호출은 NODE_BACKGROUND_UNAVAILABLE을 반환).
  • 클립 길이는 클램프됩니다(현재 <= 60s) 과도한 base64 페이로드 방지.
  • Android는 가능한 경우 CAMERA/RECORD_AUDIO 권한을 요청합니다; 거부된 권한은 *_PERMISSION_REQUIRED로 실패.

화면 녹화 (nodes)

노드는 screen.record (mp4)를 노출합니다. 예:

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

참고:

  • screen.record는 노드 앱이 포그라운드여야 합니다.
  • Android는 녹화 전에 시스템 화면 캡처 프롬프트를 표시합니다.
  • 화면 녹화는 <= 60s로 클램프됩니다.
  • --no-audio는 마이크 캡처를 비활성화합니다(iOS/Android에서 지원; macOS는 시스템 캡처 오디오 사용).
  • 여러 화면이 있는 경우 --screen <index>를 사용하여 디스플레이를 선택하세요.

위치 (nodes)

노드는 설정에서 위치가 활성화된 경우 location.get을 노출합니다.

CLI 도우미:

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

참고:

  • 위치는 기본적으로 꺼져 있습니다.
  • "Always"는 시스템 권한이 필요합니다; 백그라운드 가져오기는 최선의 노력입니다.
  • 응답에는 위도/경도, 정확도(미터) 및 타임스탬프가 포함됩니다.

SMS (Android nodes)

Android 노드는 사용자가 SMS 권한을 부여하고 장치가 전화 통신을 지원하는 경우 sms.send를 노출할 수 있습니다.

저수준 호출:

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

참고:

  • 기능이 광고되기 전에 Android 장치에서 권한 프롬프트를 수락해야 합니다.
  • 전화 통신이 없는 Wi-Fi 전용 장치는 sms.send를 광고하지 않습니다.

시스템 명령 (node host / mac node)

macOS 노드는 system.run, system.notify 및 system.execApprovals.get/set을 노출합니다. headless node 호스트는 system.run, system.which 및 system.execApprovals.get/set을 노출합니다.

예:

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

참고:

  • system.run은 페이로드에 stdout/stderr/종료 코드를 반환합니다.
  • system.notify는 macOS 앱의 알림 권한 상태를 존중합니다.
  • system.run은 --cwd, --env KEY=VAL, --command-timeout 및 --needs-screen-recording을 지원합니다.
  • system.notify는 --priority <passive|active|timeSensitive> 및 --delivery <system|overlay|auto>를 지원합니다.
  • macOS 노드는 PATH 재정의를 삭제합니다; headless node 호스트는 노드 호스트 PATH를 앞에 추가하는 경우에만 PATH를 허용합니다.
  • macOS node 모드에서 system.run은 macOS 앱의 exec 승인에 의해 게이트됩니다(Settings → Exec approvals). Ask/allowlist/full은 headless node 호스트와 동일하게 작동합니다; 거부된 프롬프트는 SYSTEM_RUN_DENIED를 반환합니다.
  • headless node 호스트에서 system.run은 exec 승인(~/.openclaw/exec-approvals.json)에 의해 게이트됩니다.

Exec node 바인딩

여러 노드를 사용할 수 있는 경우 exec을 특정 노드에 바인딩할 수 있습니다. 이것은 exec host=node의 기본 노드를 설정합니다(agent당 재정의 가능).

전역 기본값:

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

Agent당 재정의:

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

모든 노드를 허용하려면 설정 해제:

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

권한 맵

노드는 node.list / node.describe에 권한 이름으로 키가 지정된 permissions 맵을 포함할 수 있습니다(예: screenRecording, accessibility) 부울 값(true = 부여됨).

Headless node 호스트 (크로스 플랫폼)

OpenClaw는 Gateway WebSocket에 연결하고 system.run / system.which를 노출하는 headless node 호스트(UI 없음)를 실행할 수 있습니다. Linux/Windows에서 또는 서버와 함께 최소 노드를 실행하는 데 유용합니다.

시작:

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

참고:

  • 페어링이 여전히 필요합니다(Gateway는 노드 승인 프롬프트를 표시함).
  • node 호스트는 노드 ID, 토큰, 표시 이름 및 Gateway 연결 정보를 ~/.openclaw/node.json에 저장합니다.
  • Exec 승인은 ~/.openclaw/exec-approvals.json을 통해 로컬로 적용됩니다 (Exec approvals 참조).
  • macOS에서 headless node 호스트는 도달 가능한 경우 동반 앱 exec 호스트를 선호하고 앱을 사용할 수 없는 경우 로컬 실행으로 폴백합니다. 앱을 요구하려면 OPENCLAW_NODE_EXEC_HOST=app를 설정하거나, 폴백을 비활성화하려면 OPENCLAW_NODE_EXEC_FALLBACK=0를 설정하세요.
  • Gateway WS가 TLS를 사용하는 경우 --tls / --tls-fingerprint를 추가하세요.

Mac node 모드

  • macOS 메뉴 막대 앱은 Gateway WS 서버에 노드로 연결합니다(따라서 openclaw nodes …가 이 Mac에 대해 작동).
  • 원격 모드에서 앱은 Gateway 포트에 대한 SSH 터널을 열고 localhost에 연결합니다.
← 문서로 돌아가기