노드

노드는 Gateway WebSocket에 role: "node"로 연결되는 컴패니언 디바이스(macOS/iOS/Android/헤드리스)로, node.invoke를 통해 명령 인터페이스(예: canvas.*, camera.*, device.*, notifications.*, system.*)를 제공합니다. 프로토콜 세부사항: Gateway 프로토콜.

레거시 전송: Bridge 프로토콜 (TCP JSONL; 현재 노드에서는 폐기/제거됨).

macOS도 노드 모드로 실행할 수 있습니다: 메뉴바 앱이 Gateway의 WS 서버에 연결하여 로컬 canvas/camera 명령어를 노드로 노출합니다 (openclaw nodes …가 이 Mac에서 작동).

참고:

노드는 주변장치이며, 게이트웨이가 아닙니다. 게이트웨이 서비스를 실행하지 않습니다.
Telegram/WhatsApp 등의 메시지는 노드가 아닌 게이트웨이에 도착합니다.
문제 해결 가이드: /nodes/troubleshooting

페어링 + 상태

WS 노드는 디바이스 페어링을 사용합니다. 노드는 connect 시 디바이스 신원을 제시하고, Gateway는 role: node에 대한 디바이스 페어링 요청을 생성합니다. 디바이스 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)는 게이트웨이 소유의 별도 노드 페어링 저장소이며, WS connect 핸드셰이크를 게이트하지 않습니다.

원격 노드 호스트 (system.run)

Gateway가 한 머신에서 실행되고 명령어를 다른 머신에서 실행하고 싶을 때 노드 호스트를 사용하세요. 모델은 여전히 게이트웨이와 통신하고, 게이트웨이는 host=node가 선택되면 exec 호출을 노드 호스트로 전달합니다.

각 위치에서 실행되는 것

게이트웨이 호스트: 메시지 수신, 모델 실행, 도구 호출 라우팅.
노드 호스트: 노드 머신에서 system.run/system.which 실행.
승인: ~/.openclaw/exec-approvals.json을 통해 노드 호스트에서 적용.

승인 참고:

승인 기반 노드 실행은 정확한 요청 컨텍스트에 바인딩됩니다.
직접 셸/런타임 파일 실행의 경우, OpenClaw는 하나의 구체적인 로컬 파일 피연산자에 최선의 노력으로 바인딩하고, 실행 전에 해당 파일이 변경되면 실행을 거부합니다.
OpenClaw가 인터프리터/런타임 명령어에 대해 정확히 하나의 구체적인 로컬 파일을 식별할 수 없는 경우, 전체 런타임 범위를 가장하는 대신 승인 기반 실행이 거부됩니다. 더 넓은 인터프리터 의미론을 위해 샌드박싱, 별도 호스트 또는 명시적 신뢰 허용 목록/전체 워크플로를 사용하세요.

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

노드 머신에서:

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

SSH 터널을 통한 원격 게이트웨이 (루프백 바인딩)

Gateway가 루프백에 바인딩되면 (gateway.bind=loopback, 로컬 모드 기본값), 원격 노드 호스트는 직접 연결할 수 없습니다. SSH 터널을 생성하고 노드 호스트를 터널의 로컬 끝에 연결하세요.

예시 (노드 호스트 -> 게이트웨이 호스트):

# 터미널 A (계속 실행): 로컬 18790 -> 게이트웨이 127.0.0.1:18789로 포워딩
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# 터미널 B: 게이트웨이 토큰을 내보내고 터널을 통해 연결
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

참고:

openclaw node run은 토큰 또는 비밀번호 인증을 지원합니다.
환경 변수 우선: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
설정 폴백: gateway.auth.token / gateway.auth.password.
로컬 모드에서 노드 호스트는 의도적으로 gateway.remote.token / gateway.remote.password를 무시합니다.
원격 모드에서 gateway.remote.token / gateway.remote.password는 원격 우선순위 규칙에 따라 적용됩니다.
활성 로컬 gateway.auth.* SecretRef가 구성되었지만 해석되지 않으면, 노드 호스트 인증은 안전하게 실패합니다.
레거시 CLAWDBOT_GATEWAY_* 환경 변수는 노드 호스트 인증 해석에서 의도적으로 무시됩니다.

노드 호스트 시작 (서비스)

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

페어링 + 이름 지정

게이트웨이 호스트에서:

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

이름 지정 옵션:

openclaw node run / openclaw node install의 --display-name (노드의 ~/.openclaw/node.json에 저장).
openclaw nodes rename --node <id|name|ip> --name "Build Node" (게이트웨이 재정의).

명령어 허용 목록

실행 승인은 노드 호스트별입니다. 게이트웨이에서 허용 목록 항목을 추가하세요:

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를 노드로 지정

기본값 구성 (게이트웨이 설정):

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 호출은 노드 호스트에서 실행됩니다 (노드 허용 목록/승인에 따름).

명령어 호출

저수준 (raw RPC):

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

일반적인 “에이전트에게 MEDIA 첨부파일 제공” 워크플로를 위한 상위 수준 헬퍼가 있습니다.

스크린샷 (캔버스 스냅샷)

노드가 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

캔버스 제어

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는 거부됨).

사진 + 동영상 (노드 카메라)

사진 (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 반환).
클립 길이는 현재 <= 60초로 제한되어 base64 페이로드 초과를 방지합니다.
Android는 가능한 경우 CAMERA/RECORD_AUDIO 권한을 요청합니다. 거부된 권한은 *_PERMISSION_REQUIRED로 실패합니다.

화면 녹화 (노드)

지원되는 노드는 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 가용성은 노드 플랫폼에 따라 다릅니다.
화면 녹화는 <= 60초로 제한됩니다.
--no-audio는 지원되는 플랫폼에서 마이크 캡처를 비활성화합니다.
여러 화면이 있는 경우 --screen <index>로 디스플레이를 선택할 수 있습니다.

위치 (노드)

노드는 설정에서 위치가 활성화되면 location.get을 제공합니다.

CLI 헬퍼:

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

참고:

위치는 기본적으로 비활성화되어 있습니다.
“항상”은 시스템 권한이 필요합니다. 백그라운드 가져오기는 최선의 노력입니다.
응답에는 위도/경도, 정확도(미터), 타임스탬프가 포함됩니다.

SMS (Android 노드)

Android 노드는 사용자가 SMS 권한을 부여하고 디바이스가 전화 기능을 지원하면 sms.send를 제공할 수 있습니다.

저수준 호출:

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

참고:

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

Android 디바이스 + 개인 데이터 명령어

Android 노드는 해당 기능이 활성화되면 추가 명령 패밀리를 광고할 수 있습니다.

사용 가능한 패밀리:

device.status, device.info, device.permissions, device.health
notifications.list, notifications.actions
photos.latest
contacts.search, contacts.add
calendar.events, calendar.add
motion.activity, motion.pedometer

호출 예시:

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

참고:

모션 명령어는 사용 가능한 센서에 의해 기능이 제한됩니다.

시스템 명령어 (노드 호스트 / Mac 노드)

macOS 노드는 system.run, system.notify, system.execApprovals.get/set을 제공합니다. 헤드리스 노드 호스트는 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 앱의 알림 권한 상태를 존중합니다.
인식되지 않는 노드 platform / deviceFamily 메타데이터는 system.run과 system.which를 제외하는 보수적인 기본 허용 목록을 사용합니다. 알 수 없는 플랫폼에서 이러한 명령어가 필요한 경우, gateway.nodes.allowCommands를 통해 명시적으로 추가하세요.
system.run은 --cwd, --env KEY=VAL, --command-timeout, --needs-screen-recording을 지원합니다.
셸 래퍼(bash|sh|zsh ... -c/-lc)의 경우, 요청 범위 --env 값은 명시적 허용 목록(TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR)으로 축소됩니다.
허용 목록 모드에서 allow-always 결정 시, 알려진 디스패치 래퍼(env, nice, nohup, stdbuf, timeout)는 래퍼 경로 대신 내부 실행 파일 경로를 저장합니다. 언래핑이 안전하지 않으면, 허용 목록 항목이 자동으로 저장되지 않습니다.
Windows 노드 호스트의 허용 목록 모드에서 cmd.exe /c를 통한 셸 래퍼 실행은 승인이 필요합니다 (허용 목록 항목만으로는 래퍼 형태를 자동 허용하지 않습니다).
system.notify는 --priority <passive|active|timeSensitive>와 --delivery <system|overlay|auto>를 지원합니다.
노드 호스트는 PATH 재정의를 무시하고 위험한 시작/셸 키(DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4)를 제거합니다. 추가 PATH 항목이 필요하면, --env를 통해 PATH를 전달하는 대신 노드 호스트 서비스 환경을 구성하거나 표준 위치에 도구를 설치하세요.
macOS 노드 모드에서 system.run은 macOS 앱의 실행 승인에 의해 게이트됩니다 (설정 → 실행 승인). Ask/허용 목록/전체는 헤드리스 노드 호스트와 동일하게 동작합니다. 거부된 프롬프트는 SYSTEM_RUN_DENIED를 반환합니다.
헤드리스 노드 호스트에서 system.run은 실행 승인에 의해 게이트됩니다 (~/.openclaw/exec-approvals.json).

Exec 노드 바인딩

여러 노드가 사용 가능한 경우, exec를 특정 노드에 바인딩할 수 있습니다. 이는 exec host=node의 기본 노드를 설정합니다 (에이전트별로 재정의 가능).

전역 기본값:

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

에이전트별 재정의:

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에 권한 이름(예: screenRecording, accessibility)을 키로 하고 boolean 값(true = 부여됨)을 가진 permissions 맵을 포함할 수 있습니다.

헤드리스 노드 호스트 (크로스 플랫폼)

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

시작:

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

참고:

페어링이 여전히 필요합니다 (Gateway에 디바이스 페어링 프롬프트가 표시됩니다).
노드 호스트는 ~/.openclaw/node.json에 노드 ID, 토큰, 표시 이름 및 게이트웨이 연결 정보를 저장합니다.
실행 승인은 ~/.openclaw/exec-approvals.json을 통해 로컬에서 적용됩니다 (Exec 승인 참조).
macOS에서 헤드리스 노드 호스트는 기본적으로 system.run을 로컬에서 실행합니다. 컴패니언 앱 실행 호스트를 통해 system.run을 라우팅하려면 OPENCLAW_NODE_EXEC_HOST=app을 설정하세요. 앱 호스트를 필수로 하고 사용 불가 시 안전하게 실패하려면 OPENCLAW_NODE_EXEC_FALLBACK=0을 추가하세요.
Gateway WS가 TLS를 사용하는 경우 --tls / --tls-fingerprint를 추가하세요.

Mac 노드 모드

macOS 메뉴바 앱이 Gateway WS 서버에 노드로 연결됩니다 (openclaw nodes …가 이 Mac에서 작동).
원격 모드에서 앱은 Gateway 포트를 위한 SSH 터널을 열고 localhost에 연결합니다.