OpenClaw 노드란? 폰·다른 PC를 붙였을 때 권한이 열리는 순서

OpenClaw를 쓰다 보면 언젠가 이런 상황이 옵니다. 게이트웨이는 서버 한 대에 올려 뒀는데, 정작 하고 싶은 일은 다른 기기에서 일어납니다. 사진은 폰으로 찍어야 하고, 빌드는 작업용 PC에서 돌려야 하고, 알림은 맥에 띄우고 싶습니다.

이때 쓰는 개념이 노드(node)입니다. 이 글은 OpenClaw 공식 문서의 Nodes 섹션(노드 개요, 페어링과 상태, 노드 명령 정책, 노드 실행)을 바탕으로, 노드를 처음 붙일 때 헷갈리기 쉬운 권한이 열리는 순서를 한국어 독자용으로 정리한 해설입니다. 제가 특정 기기 조합을 직접 운영해 같은 결과를 얻었다는 경험담이 아니라 문서가 정한 기준을 순서대로 풀어 쓴 글이니, 실제 명령과 동작은 쓰고 계신 버전에서 다시 확인하세요.

노드는 '작은 게이트웨이'가 아닙니다

가장 먼저 잡고 갈 구분이 이겁니다. 공식 문서는 노드를 주변기기(peripheral)라고 못 박습니다. 노드는 게이트웨이 서비스를 돌리지 않고, 텔레그램이나 왓츠앱 같은 채널 메시지도 노드가 아니라 게이트웨이로 도착합니다.

노드가 하는 일은 하나입니다. 게이트웨이에 role: "node"로 접속해서 자기가 할 수 있는 명령 표면(command surface)을 내놓는 것입니다. camera.*, device.*, notifications.*, system.* 같은 것들이고, 게이트웨이는 node.invoke로 그 명령을 부릅니다. 대부분의 노드는 오퍼레이터 포트의 게이트웨이 WebSocket을 쓰고, 애플워치만 예외적으로 서명된 HTTPS 폴링을 씁니다. watchOS가 일반 앱의 저수준 네트워킹을 막아 두기 때문입니다.

맥은 조금 특이합니다. 메뉴바 앱 자체가 노드 모드로 동작해서 그 맥 한 대가 곧 노드 하나가 됩니다. 그래서 같은 맥에서 CLI 노드를 따로 또 띄우면 안 됩니다. 앱이 내부 워커로 이미 같은 런타임을 돌리고 있고, 게이트웨이 입장에서의 연결과 노드 신원도 앱이 단독으로 갖습니다.

승인은 한 번이 아니라 두 번입니다

여기서 제일 많이 막힙니다. 노드를 붙이면 승인 창이 뜨고, 승인했으니 이제 쓸 수 있겠거니 하는데 아무 명령도 안 먹습니다. 버그가 아니라 설계입니다.

공식 문서는 기기 승인(device approval)과 명령 표면 승인(command surface approval)을 분리합니다. 기기 승인은 "이 기기의 접속을 받아들인다"까지고, "이 기기가 어떤 명령을 쓸 수 있다"는 별도 승인입니다. 그래서 요청 ID도 두 개가 따로 생깁니다.

게이트웨이에서의 흐름은 이렇습니다.

1. 기기 승인: openclaw devices list → openclaw devices approve <deviceRequestId>
2. 노드 재시작(openclaw node restart, 또는 포그라운드 openclaw node run 재실행). 이 재접속이 명령 표면 요청을 새로 만듭니다.
3. 표면 승인: openclaw nodes pending → openclaw nodes approve <nodeRequestId>
4. 확인: openclaw nodes status, openclaw nodes describe --node <idOrNameOrIp>

문서 표현 그대로 옮기면, 승인되지 않은 최초 표면에는 유효한 명령이 하나도 없습니다. 나중에 노드가 명령을 늘리면 그것도 다시 nodes pending에 걸리고 다시 승인해야 합니다. 반대로 노드가 선언을 줄이는 것은 새 권한을 주는 일이 아니라서 승인이 필요 없습니다.

대기 중인 요청의 수명도 둘이 다릅니다. 기기 페어링 요청은 기기의 마지막 재시도로부터 5분 뒤 만료되는데, 계속 재접속하는 기기는 새 요청을 계속 만들지 않고 기존 요청 하나를 살려 둡니다. 반면 명령 표면 요청은 시간이 지난다고 그냥 만료되지 않습니다.

승인 자체를 누가 할 수 있는지도 요청 내용에 따라 달라집니다. 명령이 없는 요청은 operator.pairing, 실행 계열이 아닌 노드 명령은 operator.pairing + operator.write, system.run 계열은 operator.pairing + operator.admin이 필요합니다. 기기를 승인하는 일과 그 기기에 셸을 여는 일의 무게가 다르다는 뜻입니다.

승인 흐름 자체가 낯설다면 이전 글 OpenClaw 페어링이란? 낯선 DM·새 기기를 승인하기 전에 확인할 점을 먼저 보시면 연결이 쉽습니다.

명령 하나가 실제로 실행되려면 세 관문을 통과해야 합니다

페어링이 끝난 뒤에도 노드 명령은 다음 세 조건을 모두 만족해야 호출됩니다.

1. 노드가 접속 메타데이터(connect.commands)에 그 명령을 선언했을 것
2. 그 명령이 해당 기기의 페어링 기록에 있는 승인된 명령 표면에 들어 있을 것
3. 게이트웨이의 플랫폼·승인 기반 allowlist에 그 명령이 포함될 것

그리고 이 셋을 통과한 뒤에도 로컬 exec 승인과 운영체제 권한은 그대로 남아 있습니다. 즉 "게이트웨이가 허용" → "노드가 선언" → "OS가 허가"가 전부 맞아떨어져야 실제로 동작합니다.

이 구조가 낯설지 않다면 이유가 있습니다. 실행 위치·도구 정책·권한 상승을 나눠 보는 사고방식은 OpenClaw 도구가 막힐 때｜샌드박스·도구 정책·Elevated 권한을 구분하는 법에서 다룬 것과 같은 결입니다. 한 겹만 보고 "왜 안 되지"를 판단하면 대개 틀립니다.

플랫폼마다 기본 허용 범위가 다릅니다

문서는 플러그인 기본값과 commands.allow/commands.deny 조정 이전의 플랫폼별 기본 allowlist를 표로 제공합니다. 대략의 감만 옮기면 이렇습니다.

• iOS: camera.list, location.get, device.info, device.status, contacts.search, calendar.events, reminders.list, photos.latest, 모션 관련, system.notify
• Android: iOS 범위에 더해 notifications.list, notifications.actions, device.permissions, device.health, device.apps, callLog.search, 모바일 UI 관련 명령까지 가장 넓습니다
• macOS: 카메라 목록·위치·기기 정보 계열과 system.notify, computer.act
• Windows: camera.list, location.get, device.info, device.status, system.notify, computer.act
• watchOS: device.info, device.status, system.notify로 가장 좁습니다
• Linux: system.notify와 computer.act 정도이고, system.run 같은 노드 호스트 명령은 승인으로 열립니다

중요한 단서가 하나 붙습니다. 이 표는 게이트웨이 정책의 상한이지 모든 노드 앱이 실제로 구현한 명령 목록이 아닙니다. 노드가 선언하지 않으면 정책상 허용돼도 쓸 수 없습니다. 예컨대 안드로이드는 접근성 제어가 켜져 있을 때만 모바일 UI 명령을 알리고, 데스크톱 노드는 로컬 컴퓨터 제어 기능이 켜져 있을 때만 computer.act를 알립니다. 문서는 현재 macOS 앱이 정책 표에 적힌 기기·개인정보 계열을 실제로는 선언하지 않는다는 점도 따로 밝혀 둡니다.

system.run, system.run.prepare, system.which, browser.proxy, screen.snapshot 같은 데스크톱 호스트 명령은 위 표에 아예 들어 있지 않습니다. 이들은 해당 명령을 선언한 페어링 요청을 운영자가 승인한 뒤에야 쓸 수 있고, 한 번 승인되면 재접속 후에도 승인된 집합에 남습니다.

위험한 명령은 '한 번 더' 열어야 합니다

카메라 촬영처럼 민감한 명령은 노드가 선언하고 표면 승인까지 끝났어도 그대로는 안 열립니다. 설정에서 gateway.nodes.commands.allow로 일회성이지만 지속되는 opt-in을 따로 해야 합니다. 문서가 이 범주로 드는 명령은 camera.snap, camera.clip, camera.ptz.control, desktop.stream, screen.record, contacts.add, calendar.add, reminders.add, health.summary, sms.send, sms.search입니다.

반대 방향 스위치도 있습니다. gateway.nodes.commands.deny는 기본값이든 allow 항목이든 항상 이깁니다. 정확한 명령 이름으로 적어야 하고, "이건 절대 안 됨"을 못 박고 싶을 때 쓰는 자리입니다.

설정은 gateway.nodes 아래에 모여 있습니다. 신뢰하는 대역에서의 최초 페어링을 자동 승인하는 pairing.autoApproveCidrs도 여기 있는데, 주석이 중요한 말을 합니다. 이건 기기만 승인하는 것이고 명령 표면은 여전히 따로 승인해야 합니다. 기기 페어링만으로 명령이 열려서는 안 된다는 원칙이 설정 주석에까지 적혀 있는 셈입니다.

노드에서 명령을 돌릴 때

노드를 실행 장소로 쓰려면 exec를 그쪽으로 돌립니다.

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

세션 단위로는 /exec host=node security=allowlist node=<id-or-name>를 씁니다. 여기서도 문서가 선을 분명히 긋습니다. host=auto는 알아서 노드를 고르지 않습니다. 샌드박스 런타임이 돌고 있지 않을 때에 한해 호출별 host=node를 허용하고, 샌드박스가 활성이면 거부합니다.

exec 승인은 노드 호스트별이라는 점도 기억할 만합니다. allowlist 항목은 게이트웨이에서 openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"처럼 추가하지만, 실제 승인 상태는 노드 쪽 ~/.openclaw/state/openclaw.sqlite에 남습니다.

저수준 호출은 openclaw nodes invoke --node <idOrNameOrIp> --command device.info --params '{}' 형태인데, nodes invoke는 system.run과 system.run.prepare를 막습니다. 이 둘은 반드시 host=node인 exec 도구를 거쳐야 합니다. 임의 셸 실행만큼은 승인 경로를 우회할 수 없게 한 것입니다.

실행 가능한 노드가 여러 대 붙어 있으면 호출마다 대상을 고르거나 exec를 한 노드에 묶어야 합니다. 묶어 둔 대상이 오프라인이면 다른 노드로 알아서 넘어가지 않고 그냥 거부됩니다. 조용히 엉뚱한 기기에서 명령이 도는 것보다 실패하는 편이 낫다는 판단이겠지요.

정리하면

• 노드는 게이트웨이가 아니라 주변기기다. 채널 메시지는 여전히 게이트웨이로 온다.
• 승인은 기기 승인과 명령 표면 승인 두 번이고, 요청 ID도 다르다. 최초 미승인 표면에는 유효 명령이 없다.
• 명령 하나가 돌려면 노드 선언 · 승인된 표면 · 게이트웨이 allowlist 세 가지가 모두 맞아야 하고, 그 뒤에도 exec 승인과 OS 권한이 남는다.
• 플랫폼 기본 허용 범위는 다르고, 그 표는 상한일 뿐 노드가 선언해야 실제로 쓸 수 있다.
• 카메라·화면 녹화·SMS 같은 명령은 gateway.nodes.commands.allow로 따로 열어야 하고, deny는 항상 이긴다.
• system.run은 nodes invoke로 못 부르고 exec 경로로만 간다.

노드를 처음 붙일 때 "승인했는데 왜 아무것도 안 되지"로 시간을 버리기 쉬운데, 대부분 두 번째 승인이 남아 있거나 노드가 그 명령을 선언하지 않은 경우입니다. 이 순서만 머리에 넣어 두면 디버깅이 훨씬 빨라집니다.

출처: OpenClaw 공식 문서 Nodes 섹션 — Nodes 개요, Node pairing and status, Node command policy, Run commands on a node (docs.openclaw.ai). 설정 필드와 명령 이름은 버전에 따라 달라질 수 있으니 실제 환경의 문서를 확인하세요.

OpenClaw 자체가 처음이시라면 OpenClaw란? 카톡·텔레그램으로 AI 에이전트를 부리는 셀프호스팅 게이트웨이부터 보시는 편이 순서상 편합니다.