Android 앱 (Node)

지원 현황

  • 역할: 컴패니언 node 앱 (Android는 Gateway를 호스팅하지 않습니다).
  • Gateway 필요: 예 (macOS, Linux 또는 Windows WSL2에서 실행).
  • 설치: 시작하기 + 페어링.
  • Gateway: 가이드 + 구성.

시스템 제어

시스템 제어(launchd/systemd)는 Gateway 호스트에 있습니다. Gateway를 참조하세요.

연결 가이드

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

Android는 Gateway WebSocket(기본값 ws://<host>:18789)에 직접 연결하며 Gateway 소유의 페어링을 사용합니다.

전제 조건

  • "마스터" 머신에서 Gateway를 실행할 수 있어야 합니다.
  • Android 기기/에뮬레이터가 gateway WebSocket에 도달할 수 있어야 합니다:
    • 동일 LAN에서 mDNS/NSD 사용, 또는
    • Wide-Area Bonjour / unicast DNS-SD를 사용하는 동일 Tailscale tailnet (아래 참조), 또는
    • 수동 gateway host/port (대체 방법)
  • Gateway 머신에서 CLI(openclaw)를 실행할 수 있어야 합니다 (또는 SSH를 통해).

1) Gateway 시작

openclaw gateway --port 18789 --verbose

로그에서 다음과 같은 내용을 확인하세요:

  • listening on ws://0.0.0.0:18789

Tailnet 전용 설정(Vienna ⇄ London 권장)의 경우, gateway를 tailnet IP에 바인드하세요:

  • Gateway 호스트의 ~/.openclaw/openclaw.json에서 gateway.bind: "tailnet"을 설정합니다.
  • Gateway / macOS 메뉴바 앱을 재시작합니다.

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

Gateway 머신에서:

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

더 많은 디버깅 참고사항: Bonjour.

Tailnet (Vienna ⇄ London) unicast DNS-SD를 통한 검색

Android NSD/mDNS 검색은 네트워크를 넘어가지 못합니다. Android node와 gateway가 서로 다른 네트워크에 있지만 Tailscale로 연결된 경우, Wide-Area Bonjour / unicast DNS-SD를 대신 사용하세요:

  1. Gateway 호스트에서 DNS-SD 영역(예: openclaw.internal.)을 설정하고 _openclaw-gw._tcp 레코드를 게시합니다.
  2. 선택한 도메인에 대해 해당 DNS 서버를 가리키는 Tailscale split DNS를 구성합니다.

세부사항 및 CoreDNS 구성 예시: Bonjour.

3) Android에서 연결

Android 앱에서:

  • 앱은 포그라운드 서비스(영구 알림)를 통해 gateway 연결을 유지합니다.
  • 설정을 엽니다.
  • 검색된 Gateway 아래에서 gateway를 선택하고 연결을 누릅니다.
  • mDNS가 차단된 경우, 고급 → 수동 Gateway(host + port)를 사용하고 **연결(수동)**을 누릅니다.

첫 페어링 성공 후, Android는 실행 시 자동으로 재연결합니다:

  • 수동 엔드포인트(활성화된 경우), 그렇지 않으면
  • 마지막으로 검색된 gateway (최선의 노력).

4) 페어링 승인 (CLI)

Gateway 머신에서:

openclaw nodes pending
openclaw nodes approve <requestId>

페어링 세부사항: Gateway 페어링.

5) Node 연결 확인

  • nodes status를 통해: 
    openclaw nodes status
  • Gateway를 통해: 
    openclaw gateway call node.list --params "{}"

6) 채팅 + 기록

Android node의 채팅 시트는 gateway의 primary session key(main)를 사용하므로, 기록과 답장이 WebChat 및 다른 클라이언트와 공유됩니다:

  • 기록: chat.history
  • 전송: chat.send
  • 푸시 업데이트(최선의 노력): chat.subscribe → event:"chat"

7) Canvas + camera

Gateway Canvas Host (웹 콘텐츠에 권장)

Node가 agent가 디스크에서 편집할 수 있는 실제 HTML/CSS/JS를 표시하도록 하려면, node를 Gateway canvas host로 지정하세요.

참고: nodes는 canvasHost.port(기본값 18793)의 독립형 canvas host를 사용합니다.

  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:18793/__openclaw__/canvas/"}'

Tailnet (선택사항): 두 기기가 모두 Tailscale에 있는 경우, .local 대신 MagicDNS 이름 또는 tailnet IP를 사용하세요. 예: http://<gateway-magicdns>:18793/__openclaw__/canvas/.

이 서버는 HTML에 라이브 리로드 클라이언트를 주입하고 파일 변경 시 리로드합니다. A2UI 호스트는 http://<gateway-host>:18793/__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 명령 (포그라운드만; 권한 필요):

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

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

← 문서로 돌아가기