AI·업무운영 · OpenClaw Node Runbook
OpenClaw 안드로이드 폰을 노드로 붙이는 법
pairing required부터 실행 테스트까지
OpenClaw는 PC나 서버의 Gateway에 다른 기기를 노드로 붙여 원격 실행·브라우저 프록시 같은 기능을 확장할 수 있다. 이 글은 안드로이드 스마트폰을 같은 와이파이의 OpenClaw Gateway에 노드로 연결하고, 실제 명령 실행까지 검증하는 절차를 정리한 실전 가이드다.
시각자료로 먼저 보는 Android 노드 연결 흐름
이 작업은 복잡해 보여도 네트워크 연결, pairing 승인, 권한 allowlist, 실행 테스트를 분리하면 훨씬 단순해진다. 문제가 생겼을 때는 “폰이 Gateway에 닿는가”와 “노드 런타임이 정상인가”를 따로 확인하는 것이 핵심이다.
1. 전체 흐름: 연결은 네 단계로 끝난다
PC에서 `openclaw qr --json`으로 폰이 접속할 WebSocket 주소를 확인한다.
Android 터미널에서 Gateway host, port, token을 넣어 노드 호스트를 실행한다.
처음 연결은 `device pairing required`가 뜬다. PC에서 requestId를 승인한다.
`nodes status`, `system.which`, allowlist 기반 `system.run`으로 실제 작동을 확인한다.
OpenClaw 문서 기준으로 노드는 Gateway가 아니다. 메시지와 세션의 중심은 Gateway이고, 노드는 Gateway에 붙는 주변 장치다. 따라서 Android 폰에서 새 Gateway를 띄우려는 것이 아니라, 이미 켜진 Gateway에 `role: node`로 연결하는 방향을 잡아야 한다.
2. 먼저 PC Gateway가 어떤 주소를 광고하는지 확인한다
같은 와이파이에서 붙일 때는 LAN 주소가 가장 단순하다. PC에서 아래 명령으로 실제 setup payload와 Gateway URL을 확인한다.
openclaw qr --json
openclaw devices list
openclaw nodes status정상이라면 `gatewayUrl`이 `ws://192.168.x.x:18789`처럼 사설 LAN 주소로 나온다. 반대로 `127.0.0.1`, `localhost`, loopback-only 오류가 나오면 폰에서는 절대 접속할 수 없다. 이때는 Gateway bind를 LAN으로 바꾸고, 새 setup code를 다시 만들어야 한다.
| 상태 | 의미 | 처리 |
|---|---|---|
| `gateway.bind=lan` | 같은 와이파이에서 접속 가능한 LAN 주소를 광고 | 폰도 같은 와이파이에 두고 진행 |
| loopback 또는 localhost | PC 자기 자신만 접속 가능 | LAN·Tailscale Serve·공개 URL 중 하나로 route 재설정 |
| Tailscale/public | 원격 네트워크에서 접속 예정 | Android는 `wss://` 보안 endpoint를 우선 사용 |
3. Android 터미널에서는 Gateway가 아니라 node host를 실행한다
터미널형 OpenClaw Android 앱이라면 핵심 명령은 `openclaw node run`이다. 아래 명령은 구조 예시이며, 실제 토큰과 IP는 각자 환경에서 확인한 값으로 바꿔야 한다.
unset LD_PRELOAD
unset NODE_OPTIONS
OPENCLAW_NO_RESPAWN=1 \
OPENCLAW_NODE_OPTIONS_READY=1 \
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
OPENCLAW_GATEWAY_TOKEN="<gateway-auth-token>" \
openclaw node run --host <gateway-lan-ip> --port 18789 --display-name "Android Phone"여기서 `OPENCLAW_GATEWAY_TOKEN`은 setup code의 bootstrap token이 아니라 Gateway auth token이다. 공개 글이나 메신저에 토큰을 그대로 남기면 안 된다. 재현용 문서에는 반드시 `
4. 첫 실행에서 `device pairing required`가 나오면 성공에 가깝다
처음 연결할 때 아래와 비슷한 메시지가 나오면 네트워크와 인증은 대체로 통과한 것이다. 아직 승인되지 않은 새 장치라서 Gateway가 연결을 닫은 상태다.
node host gateway connect failed: device pairing required (requestId: ...)
gateway connect failed: device pairing required
node host gateway closed (1008): pairing required이때 PC에서 requestId를 승인한다.
openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status승인 직후에는 폰의 `node run` 프로세스가 이미 종료되어 있을 수 있다. 같은 명령을 한 번 더 실행하면 이번에는 approved device로 연결된다. `nodes status`에서 `paired: true`, `connected: true`가 보이면 연결 단계는 완료다.
5. 이번 세팅에서 실제로 만난 오류와 해결 순서
Android 쪽 CLI는 일반 PC Linux와 다르게 앱 내부 파일시스템, glibc 번들, wrapper, Termux 계열 환경변수의 영향을 받는다. 아래 표는 실제로 문제를 좁혀간 순서다.
| 증상 | 진단 | 해결 방향 |
|---|---|---|
| `ld-linux-aarch64.so.1: unrecognized option '--disable-warning=ExperimentalWarning'` | OpenClaw CLI respawn이 Android에서 loader를 Node 실행 파일로 오인 | `OPENCLAW_NO_RESPAWN=1`, `OPENCLAW_NODE_OPTIONS_READY=1`, `NODE_OPTIONS` 제거 |
| `libc.so: invalid ELF header` | glibc linker script 안에 오래된 `/data/data/com.termux/files` 경로가 남아 있음 | 스크립트의 경로를 현재 앱 경로로 치환. `libc.so`를 무작정 `libc.so.6` 링크로 바꾸지 않음 |
| `version 'LIBC' not found` | `LD_PRELOAD=libtermux-exec.so`가 glibc 실행과 충돌 | 실행 전 `unset LD_PRELOAD` 또는 `env -u LD_PRELOAD` 사용 |
| `unauthorized: gateway token mismatch` | 폰의 저장 token 또는 환경변수 token이 PC Gateway와 다름 | PC Gateway의 auth token을 `OPENCLAW_GATEWAY_TOKEN`에 명시 |
| `pairing required` | 정상적인 최초 pairing 요청 | PC에서 requestId 승인 후 폰 명령 재실행 |
6. glibc 경로 문제를 확인하고 고치는 방법
일부 Android 빌드에서는 `libc.so`나 `libm.so`가 실제 ELF 바이너리가 아니라 GNU ld script다. 이 파일 안에 과거 Termux 경로가 박혀 있으면 Node 실행이 실패한다. 먼저 확인한다.
GLIBC="/data/user/0/com.openclaw.android/files/usr/glibc/lib"
cd "$GLIBC" || exit 1
head -20 libc.so
ls -l libc.so libc.so.6스크립트 안에 `/data/data/com.termux/files`가 보이면 현재 앱 경로로 치환한다. 단, 이 작업은 앱 내부 런타임을 임시 보정하는 것이므로 업데이트 후 원복될 수 있다.
GLIBC="/data/user/0/com.openclaw.android/files/usr/glibc/lib"
APP="/data/user/0/com.openclaw.android/files"
cd "$GLIBC" || exit 1
for f in libc.so libm.so libgcc_s.so; do
if [ -f "$f" ] && grep -q "/data/data/com.termux/files" "$f" 2>/dev/null; then
cp "$f" "$f.path-bak"
sed "s#/data/data/com.termux/files#$APP#g" "$f.path-bak" > "$f"
fi
done
grep -n "com.termux\|com.openclaw.android" libc.so libm.so libgcc_s.so 2>/dev/null || true검증은 간단하다. `node --version`과 `openclaw --version`이 출력되면 런타임은 살아난 것이다.
7. 연결 후에는 노드 상태와 명령 경로를 검증한다
연결만 됐다고 끝난 것은 아니다. 노드가 어떤 capability를 광고하는지, 명령 실행이 어디에서 되는지 확인해야 한다.
openclaw nodes status정상 연결된 node host는 대체로 `system.run`, `system.run.prepare`, `system.which` 같은 명령을 광고한다. 이후 `system.which`로 폰 안의 실행 파일 경로를 확인한다.
openclaw nodes invoke --node "Android Phone" \
--command system.which \
--params '{"bins":["uname","node","openclaw","bash"]}'8. 실제 `system.run`은 allowlist로 작게 열어 테스트한다
OpenClaw node host의 명령 실행은 안전장치가 있다. 아무 명령이나 바로 실행되는 구조가 아니라 approval 또는 allowlist가 필요하다. 처음에는 `/bin/uname`처럼 위험이 낮은 명령 하나만 허용해서 테스트한다.
openclaw approvals allowlist add --node "Android Phone" "/bin/uname"
# 이후 agent/exec 쪽에서 node host를 지정해 실행
/bin/uname -a`Linux localhost ... aarch64 Toybox`처럼 Android 커널과 아키텍처가 나오면 실제로 PC가 아니라 폰에서 실행된 것이다. 이 검증까지 해야 “등록만 된 노드”와 “실행 가능한 노드”를 구분할 수 있다.
9. 나중에 다시 세팅할 때 쓰는 체크리스트
`openclaw qr --json`으로 LAN URL을 확인하고, auth token은 공개 문서에 남기지 않는다.
`node --version`, `openclaw --version`이 먼저 성공해야 node run이 의미 있다.
최초 `pairing required`는 실패가 아니라 승인 대기다. 승인 후 같은 명령을 다시 실행한다.
`openclaw nodes status`에서 `paired: true`, `connected: true`를 확인한다.
`system.which`, `system.run`이 광고되는지 확인한다. 모바일 companion 앱이면 camera/location 계열도 별도 확인한다.
실행 권한은 작게 열고, 테스트 후 필요 없는 권한은 제거한다.
10. 결론: 성공의 핵심은 “한 번에 다 고치지 않는 것”
이번 유형의 문제는 겉으로는 “폰이 Gateway에 연결되지 않는다”로 보이지만, 실제로는 여러 층이 섞여 있다. route가 맞는지, token이 맞는지, pairing이 필요한지, Android 런타임이 정상인지, node host가 어떤 명령을 광고하는지 순서대로 나눠 봐야 한다.
좋은 해결 순서는 Gateway URL 확인 → Android 런타임 복구 → token 명시 → pairing 승인 → 재실행 → system.which → allowlist 실행 테스트다. 이 순서를 따르면 같은 증상이 다시 나와도 어디서 멈췄는지 빠르게 찾을 수 있다.