Android 앱 (노드)

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

지원 현황

시스템 제어

시스템 제어(launchd/systemd)는 게이트웨이 호스트에서 실행됩니다. 게이트웨이를 참조하세요.

연결 가이드

Android 노드 앱 ⇄ (mDNS/NSD + WebSocket) ⇄ 게이트웨이

Android는 게이트웨이 WebSocket(기본 ws://<host>:18789)에 직접 연결하며, 디바이스 페어링(role: node)을 사용합니다.

사전 요구 사항

  • “마스터” 머신에서 게이트웨이를 실행할 수 있어야 합니다.
  • Android 디바이스/에뮬레이터가 게이트웨이 WebSocket에 접근할 수 있어야 합니다:
    • mDNS/NSD를 사용하는 동일 LAN, 또는
    • Wide-Area Bonjour / 유니캐스트 DNS-SD를 사용하는 동일 Tailscale 테일넷(아래 참조), 또는
    • 수동 게이트웨이 호스트/포트 (대안)
  • 게이트웨이 머신에서 CLI(openclaw)를 실행할 수 있어야 합니다 (또는 SSH를 통해).

1) 게이트웨이 시작

openclaw gateway --port 18789 --verbose

로그에서 다음과 비슷한 내용을 확인하세요:

  • listening on ws://0.0.0.0:18789

테일넷 전용 설정의 경우 (비엔나 ⇄ 런던 등에 권장), 게이트웨이를 테일넷 IP에 바인딩하세요:

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

2) 디스커버리 확인 (선택 사항)

게이트웨이 머신에서:

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

추가 디버깅 정보: Bonjour.

테일넷 (비엔나 ⇄ 런던) 유니캐스트 DNS-SD를 통한 디스커버리

Android NSD/mDNS 디스커버리는 네트워크를 넘나들 수 없습니다. Android 노드와 게이트웨이가 서로 다른 네트워크에 있지만 Tailscale로 연결되어 있다면, Wide-Area Bonjour / 유니캐스트 DNS-SD를 사용하세요:

  1. 게이트웨이 호스트에 DNS-SD 존(예: openclaw.internal.)을 설정하고 _openclaw-gw._tcp 레코드를 등록합니다.
  2. 해당 도메인에 대해 DNS 서버를 가리키도록 Tailscale 분할 DNS를 설정합니다.

자세한 내용 및 CoreDNS 설정 예시: Bonjour.

3) Android에서 연결

Android 앱에서:

  • 앱은 포그라운드 서비스(지속 알림)를 통해 게이트웨이 연결을 유지합니다.
  • Connect 탭을 엽니다.
  • Setup Code 또는 Manual 모드를 사용합니다.
  • 디스커버리가 차단된 경우, Advanced controls에서 수동 호스트/포트(및 TLS/토큰/비밀번호)를 사용합니다.

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

  • 수동 엔드포인트 (활성화된 경우), 그렇지 않으면
  • 마지막으로 발견된 게이트웨이 (최선 노력 기반).

4) 페어링 승인 (CLI)

게이트웨이 머신에서:

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

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

5) 노드 연결 확인

  • 노드 상태를 통해:

    openclaw nodes status

  • 게이트웨이를 통해:

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

6) 채팅 + 기록

Android 채팅 탭은 세션 선택을 지원합니다 (기본 main 및 기존 세션):

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

7) Canvas + 카메라

게이트웨이 Canvas 호스트 (웹 콘텐츠에 권장)

노드에서 에이전트가 디스크에서 편집할 수 있는 실제 HTML/CSS/JS를 표시하려면, 노드를 게이트웨이 Canvas 호스트에 연결하세요.

참고: 노드는 게이트웨이 HTTP 서버(포트 gateway.port와 동일, 기본 18789)에서 Canvas를 로드합니다.

  1. 게이트웨이 호스트에 ~/.openclaw/workspace/canvas/index.html을 생성합니다.

  2. 노드를 해당 URL로 이동시킵니다 (LAN):

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

테일넷 (선택): 두 디바이스 모두 Tailscale에 연결되어 있다면, .local 대신 MagicDNS 이름이나 테일넷 IP를 사용하세요. 예: http://<gateway-magicdns>:18789/__openclaw__/canvas/.

이 서버는 HTML에 라이브 리로드 클라이언트를 주입하고, 파일 변경 시 리로드합니다. 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 헬퍼에 대해서는 카메라 노드를 참조하세요.

8) 음성 + 확장된 Android 명령 체계

  • 음성: Android는 Voice 탭에서 마이크 켜기/끄기 흐름을 사용하며, 음성 인식 캡처 및 TTS 재생(ElevenLabs 설정 시 사용, 시스템 TTS로 대체 가능)을 지원합니다. 앱이 포그라운드를 벗어나면 음성이 중단됩니다.
  • Voice 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
    • motion.activity, motion.pedometer
arrow_back
이전
Windows
다음
iOS
arrow_forward