OpenClaw Android 앱 연결: 5분 만에 게이트웨이 설정하기

모바일 기기를 개발 워크플로우에 통합하는 건 생각보다 까다로운 일이죠. 특히 로컬 서버와 모바일 앱 사이의 통신을 설정하다 보면 네트워크 설정이나 페어링 문제로 시간을 허비하기 일쑤입니다. OpenClaw의 Android 앱을 사용하면 이런 복잡한 과정을 줄이고 Android 기기를 하나의 Node로 간편하게 연결할 수 있어요.

Android 앱 (Node)

참고: Android 앱은 아직 공개적으로 출시되지 않았습니다. 소스 코드는 OpenClaw 저장소의 apps/android 디렉토리에서 확인할 수 있습니다. Java 17과 Android SDK를 사용하여 직접 빌드할 수 있습니다 (./gradlew :app:assembleDebug). 빌드 방법은 apps/android/README.md를 확인해 주세요.

지원 현황 (Support snapshot)

• 역할: 컴패니언 Node 앱 (Android는 Gateway를 호스팅하지 않아요).
• Gateway 필요 여부: 예 (macOS, Linux 또는 WSL2를 통한 Windows에서 실행하세요).
• 설치: 시작하기 + 페어링.
• Gateway: Runbook + 설정.
• 프로토콜: Gateway 프로토콜 (Nodes + Control plane).

시스템 제어 (System control)

시스템 제어(launchd/systemd)는 Gateway 호스트에서 이루어져요. 자세한 내용은 Gateway 문서를 참고해 주세요.

연결 가이드 (Connection Runbook)

Android Node 앱 ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway

Android는 Gateway WebSocket(기본값 ws://<host>:18789)에 직접 연결하며 기기 페어링(role: node)을 사용해요.

사전 준비 사항

• “master” 머신에서 Gateway를 실행할 수 있어야 해요.
• Android 기기나 에뮬레이터가 Gateway WebSocket에 접속할 수 있어야 해요:
  • mDNS/NSD를 사용하는 동일한 LAN 환경, 또는
  • Wide-Area Bonjour / 유니캐스트 DNS-SD를 사용하는 동일한 Tailscale tailnet (아래 내용 참고), 또는
  • 수동 Gateway 호스트/포트 설정 (대체 방법)
• Gateway 머신에서 직접 또는 SSH를 통해 CLI(openclaw)를 실행할 수 있어야 해요.

1) Gateway 시작하기

openclaw gateway --port 18789 --verbose

로그에서 다음과 같은 메시지가 보이는지 확인하세요:

• listening on ws://0.0.0.0:18789

Tailnet 전용 설정(비엔나 ⇄ 런던 연결 등에 권장)의 경우, Gateway를 Tailnet IP에 바인딩하세요:

• Gateway 호스트의 ~/.openclaw/openclaw.json 파일에서 gateway.bind: "tailnet"으로 설정하세요.
• Gateway 또는 macOS 메뉴바 앱을 재시작하세요.

2) 검색 확인 (선택 사항)

Gateway 머신에서 다음 명령어를 실행해 보세요:

dns-sd -B _openclaw-gw._tcp local.

더 자세한 디버깅 노트는 Bonjour에서 확인할 수 있어요.

유니캐스트 DNS-SD를 통한 Tailnet (비엔나 ⇄ 런던) 검색

Android의 NSD/mDNS 검색은 네트워크 경계를 넘지 못해요. Android Node와 Gateway가 서로 다른 네트워크에 있지만 Tailscale로 연결되어 있다면, Wide-Area Bonjour 또는 유니캐스트 DNS-SD를 사용하세요:

1. Gateway 호스트에 DNS-SD 존(예: openclaw.internal.)을 설정하고 _openclaw-gw._tcp 레코드를 게시하세요.
2. 해당 DNS 서버를 가리키도록 선택한 도메인에 대해 Tailscale split DNS를 설정하세요.

자세한 내용과 CoreDNS 설정 예시는 Bonjour를 참고하세요.

3) Android에서 연결하기

Android 앱에서 다음을 수행하세요:

• 앱은 포그라운드 서비스(지속 알림)를 통해 Gateway 연결을 유지해요.
• Connect 탭을 여세요.
• Setup Code 또는 Manual 모드를 사용하세요.
• 검색이 차단된 경우, Advanced controls에서 수동으로 호스트/포트(필요 시 TLS/토큰/비밀번호 포함)를 입력하세요.

첫 번째 페어링에 성공하면, 이후에는 앱 실행 시 자동으로 다시 연결됩니다:

• 수동 엔드포인트가 활성화된 경우 해당 주소로 연결하고,
• 그렇지 않으면 마지막으로 검색된 Gateway로 연결을 시도해요.

4) 페어링 승인 (CLI)

Gateway 머신에서 다음 명령어를 사용하세요:

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

페어링에 대한 자세한 내용은 페어링 문서를 확인하세요.

5) Node 연결 확인

• Node 상태 확인:

  openclaw nodes status

• Gateway를 통한 확인:

  openclaw gateway call node.list --params "{}"

6) Chat + 히스토리

Android Chat 탭은 세션 선택을 지원해요(기본값 main 및 기타 기존 세션):

• 히스토리: chat.history
• 전송: chat.send
• 푸시 업데이트: chat.subscribe → event:"chat"

7) Canvas + 카메라

Gateway Canvas Host (웹 콘텐츠 권장)

Node에서 에이전트가 디스크에서 편집할 수 있는 실제 HTML/CSS/JS를 보여주고 싶다면, Node가 Gateway canvas host를 가리키도록 설정하세요.

참고: Node는 Gateway HTTP 서버( gateway.port와 동일한 포트, 기본값 18789)에서 canvas를 로드해요.

1. Gateway 호스트에 ~/.openclaw/workspace/canvas/index.html 파일을 만드세요.

2. Node를 해당 주소로 이동시키세요 (LAN):

openclaw nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'

Tailnet (선택 사항): 두 기기가 모두 Tailscale에 있다면 .local 대신 MagicDNS 이름이나 Tailnet IP를 사용하세요. 예: http://<gateway-magicdns>:18789/__openclaw__/canvas/.

이 서버는 HTML에 live-reload 클라이언트를 주입하여 파일이 변경될 때마다 자동으로 새로고침해 줍니다. A2UI 호스트 주소는 http://<gateway-host>:18789/__openclaw__/a2ui/입니다.

Canvas 명령어 (포그라운드 전용):

• canvas.eval, canvas.snapshot, canvas.navigate (기본 스캐폴드로 돌아가려면 {"url":""} 또는 {"url":"/"} 사용). canvas.snapshot은 { format, base64 }를 반환해요 (기본값 format="jpeg").
• A2UI: canvas.a2ui.push, canvas.a2ui.reset (canvas.a2ui.pushJSONL은 이전 버전 호환용 별칭)

카메라 명령어 (포그라운드 전용, 권한 필요):

• camera.snap (jpg)
• camera.clip (mp4)

매개변수와 CLI 헬퍼는 Camera node를 참고하세요.

8) 음성 + 확장된 Android 명령어 범위

• 음성: Android는 Voice 탭에서 단일 마이크 온/오프 흐름을 사용하며, 텍스트 변환 캡처 및 TTS 재생(설정된 경우 ElevenLabs, 기본은 시스템 TTS)을 지원해요. 앱이 포그라운드를 벗어나면 음성 기능이 중단됩니다.
• 음성 호출(Wake) 및 대화 모드 토글은 현재 Android UX/런타임에서 제거되었습니다.
• 추가 Android 명령어 제품군 (기기 및 권한에 따라 사용 가능 여부 다름):
  • device.status, device.info, device.permissions, device.health
  • notifications.list, notifications.actions
  • photos.latest
  • contacts.search, contacts.add
  • calendar.events, calendar.add
  • callLog.search
  • motion.activity, motion.pedometer

---

다음 단계

• 페어링 가이드
• Gateway 설정
• Bonjour 디버깅

AI Setup Assistant