OpenClaw 노드 설정 가이드: 기기 연결 및 원격 호스트 구성

여러 기기에서 명령어를 실행하거나 원격으로 작업을 제어하고 싶을 때, 각 장치를 일일이 설정하는 건 정말 번거로운 일이죠. OpenClaw의 노드 시스템을 활용하면 이런 복잡한 과정을 깔끔하게 해결할 수 있어요.

페어링 및 상태 확인

WS 노드는 디바이스 페어링 방식을 사용해요. 노드가 connect할 때 디바이스 식별 정보를 제공하면, 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>

만약 노드가 인증 정보(role, scopes, public key 등)를 변경하여 다시 연결을 시도하면, 이전의 대기 중인 요청은 대체되고 새로운 requestId가 생성돼요. 승인하기 전에 openclaw devices list를 다시 실행해서 확인해 보세요.

참고 사항:

nodes status는 디바이스 페어링 역할에 node가 포함되어 있을 때 해당 노드를 paired 상태로 표시해요.
node.pair.* (CLI: openclaw nodes pending/approve/reject)는 Gateway가 소유한 별도의 노드 페어링 저장소이며, WS connect 핸드셰이크를 차단하지는 않아요.

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

Gateway는 한 장치에서 실행 중이지만 명령은 다른 장치에서 실행하고 싶을 때 노드 호스트를 사용해 보세요. 모델은 여전히 gateway와 통신하며, host=node가 선택되면 Gateway가 exec 호출을 노드 호스트로 전달하는 구조예요.

구성 요소별 역할

Gateway host: 메시지를 수신하고, 모델을 실행하며, 도구 호출(tool calls)을 라우팅해요.
Node host: 노드 머신에서 system.run 및 system.which를 직접 실행합니다.
승인(Approvals): 노드 호스트의 ~/.openclaw/exec-approvals.json을 통해 실행 권한을 강제해요.

승인 관련 참고 사항:

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

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

노드 머신에서 다음 명령어를 실행하세요:

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

SSH 터널을 통한 원격 Gateway 연결 (loopback bind)

Gateway가 루프백(gateway.bind=loopback, 로컬 모드 기본값)에 바인딩된 경우, 원격 노드 호스트가 직접 연결할 수 없어요. 이럴 때는 SSH 터널을 만들고 노드 호스트가 터널의 로컬 끝을 바라보게 설정하세요.

예시 (노드 호스트 -> Gateway 호스트):

# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
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.auth.* SecretRefs가 설정되었지만 해결되지 않은 경우, 노드 호스트 인증은 안전을 위해 실패 처리돼요.
노드 호스트 인증 확인 시에는 OPENCLAW_GATEWAY_* 환경 변수만 참조합니다.

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

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

페어링 및 이름 지정

Gateway 호스트에서 다음을 실행하세요:

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

노드가 변경된 인증 정보로 다시 시도하는 경우, openclaw devices list를 다시 실행하여 현재의 requestId를 승인해 주세요.

이름 지정 옵션:

openclaw node run 또는 openclaw node install 실행 시 --display-name 사용 (노드의 ~/.openclaw/node.json에 저장됨).
openclaw nodes rename --node <id|name|ip> --name "Build Node" (Gateway에서 덮어쓰기).

명령어 허용 목록(Allowlist) 설정

실행 승인은 노드 호스트별로 관리돼요. Gateway에서 허용 목록 항목을 추가할 수 있습니다:

openclaw approvals allowlist add --node &lt;id|name|ip&gt; "/usr/bin/uname"
openclaw approvals allowlist add --node &lt;id|name|ip&gt; "/usr/bin/sw_vers"

승인 정보는 노드 호스트의 ~/.openclaw/exec-approvals.json에 저장됩니다.

실행 대상을 노드로 지정하기

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

명령어 호출하기

로우 레벨(raw RPC) 호출 방식은 다음과 같아요:

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

에이전트에게 MEDIA 첨부 파일을 제공하는 일반적인 워크플로우를 위해 더 편리한 헬퍼 기능들이 마련되어 있습니다.

스크린샷 (canvas snapshots)

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

AI Setup Assistant

다음 단계

사진 및 동영상 (node camera)

사진(jpg)을 찍는 방법이에요:

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
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가 반드시 foreground 상태여야 해요. background 상태에서 호출하면 NODE_BACKGROUND_UNAVAILABLE 에러를 반환합니다.
클립 길이는 base64 페이로드가 너무 커지는 것을 방지하기 위해 현재 60초 이하로 제한되어 있어요.
Android에서는 가능할 때 CAMERA 및 RECORD_AUDIO 권한을 요청하며, 권한을 거부하면 *_PERMISSION_REQUIRED 에러와 함께 실패해요.

화면 녹화 (nodes)

지원되는 node는 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 사용 가능 여부는 node 플랫폼에 따라 달라요.
화면 녹화 시간은 60초 이하로 제한됩니다.
지원되는 플랫폼에서 --no-audio 옵션을 쓰면 마이크 캡처를 비활성화할 수 있어요.
화면이 여러 개인 경우 --screen <index>를 사용해서 녹화할 디스플레이를 선택하세요.

위치 정보 (nodes)

설정에서 위치 서비스가 활성화된 경우 node에서 location.get 기능을 노출해요.

CLI 헬퍼 사용법이에요:

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

참고할 내용:

위치 정보 기능은 기본적으로 꺼져 있어요.
“항상 허용” 설정은 시스템 권한이 필요하며, background 위치 정보 가져오기는 best-effort 방식으로 동작해요.
응답 데이터에는 위도/경도, 정확도(미터 단위), 타임스탬프가 포함됩니다.

SMS (Android nodes)

사용자가 SMS 권한을 허용하고 기기가 전화 기능을 지원한다면, Android node에서 sms.send 기능을 사용할 수 있어요.

Low-level 호출 방식이에요:

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

참고할 내용:

해당 기능이 활성화되기 전에 Android 기기에서 권한 요청 팝업을 반드시 승인해야 해요.
전화 기능이 없는 Wi-Fi 전용 기기에서는 sms.send 기능이 표시되지 않아요.

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

Android Node는 해당 기능(capabilities)이 활성화되면 추가적인 명령어 패밀리를 제공해요.

사용 가능한 패밀리는 다음과 같아요:

device.status, device.info, device.permissions, device.health
notifications.list, notifications.actions
photos.latest
contacts.search, contacts.add
calendar.events, calendar.add
callLog.search
sms.search
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}'

참고 사항:

Motion 명령어는 사용 가능한 센서에 따라 기능이 제한될 수 있어요.

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

macOS node는 system.run과 system.notify를 노출하며, system.execApprovals.get/set 기능도 제공해요. headless node host는 system.run 및 system.which와 더불어 system.execApprovals.get/set을 노출해요.

예시:

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"name":"git"}'

참고 사항:

system.run은 페이로드에 stdout/stderr/exit code를 반환해요.
Shell 실행은 이제 host=node와 함께 exec 도구를 통해 이루어져요. nodes는 명시적인 node 명령어를 위한 직접 RPC 인터페이스로 유지돼요.
nodes invoke는 system.run이나 system.run.prepare를 노출하지 않아요. 이들은 exec 경로에만 남아 있어요.
system.notify는 macOS 앱의 알림 권한 상태를 준수해요.
인식되지 않는 node platform / deviceFamily 메타데이터는 system.run과 system.which를 제외하는 보수적인 기본 allowlist를 사용해요. 알 수 없는 플랫폼에서 이 명령어들이 꼭 필요하다면 gateway.nodes.allowCommands를 통해 명시적으로 추가해 주세요.
system.run은 --cwd, --env KEY=VAL, --command-timeout, --needs-screen-recording 옵션을 지원해요.
bash, sh, zsh 같은 shell wrapper(... -c/-lc)의 경우, 요청 범위의 --env 값은 명시적인 allowlist(TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR)로 축소돼요.
allowlist 모드에서 항상 허용(allow-always) 결정을 내릴 때, 알려진 dispatch wrapper(env, nice, nohup, stdbuf, timeout)는 wrapper 경로 대신 내부 실행 파일 경로를 유지해요. 언래핑(unwrapping)이 안전하지 않으면 allowlist 항목이 자동으로 저장되지 않아요.
allowlist 모드의 Windows node host에서 cmd.exe /c를 통한 shell-wrapper 실행은 승인이 필요해요. allowlist 항목만으로는 wrapper 형태를 자동 허용하지 않아요.
system.notify는 --priority <passive|active|timeSensitive>와 --delivery <system|overlay|auto> 옵션을 지원해요.
node host는 PATH 재정의를 무시하고 위험한 startup/shell 키(DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4)를 제거해요. 추가적인 PATH 항목이 필요하다면 --env를 통해 PATH를 전달하는 대신 node host 서비스 환경을 구성하거나 표준 위치에 도구를 설치하세요.
macOS node 모드에서 system.run은 macOS 앱의 실행 승인(Settings → Exec approvals)에 의해 제어돼요.
Ask/allowlist/full 방식은 headless node host와 동일하게 작동하며, 거부된 프롬프트는 SYSTEM_RUN_DENIED를 반환해요.
headless node host에서 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

권한 맵 (Permissions map)

노드는 node.list나 node.describe 결과에 permissions 맵을 포함할 수 있어요. 이 맵은 screenRecording이나 accessibility 같은 권한 이름을 키(key)로 사용하며, 해당 권한이 부여되었는지를 나타내는 boolean 값(true는 권한 허용)을 가집니다.

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

OpenClaw는 UI 없이 실행되는 헤드리스 노드 호스트를 지원해요. Gateway WebSocket에 연결해서 system.run이나 system.which 기능을 제공하죠. Linux나 Windows 환경, 또는 서버와 함께 가벼운 노드를 실행하고 싶을 때 아주 유용해요.

실행 방법은 다음과 같아요:

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

참고할 내용:

페어링 과정은 여전히 필요해요 (Gateway에서 디바이스 페어링 프롬프트가 뜰 거예요).
노드 호스트는 노드 ID, 토큰, 표시 이름, Gateway 연결 정보를 ~/.openclaw/node.json에 저장해요.
실행 승인(Exec approvals)은 ~/.openclaw/exec-approvals.json을 통해 로컬에서 강제 적용돼요 (Exec approvals 문서를 참고하세요).
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 서버에 노드로 연결돼요 (그래서 이 Mac을 대상으로 openclaw nodes … 명령어를 사용할 수 있어요).
원격 모드에서 앱은 Gateway 포트를 위해 SSH 터널을 열고 localhost에 연결해요.

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.