Android app

기준일: 2026-07-26
공식 기준: Android app

Android app 문서는 OpenClaw 공식 문서(platforms/android)를 한국어로 정리한 가이드입니다. Android app (node): connection runbook + Connect/Chat/OpenClaw/Voice/Canvas command surface 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Android app (node): connection runbook + Connect/Chat/OpenClaw/Voice/Canvas command surface

한국어 가이드 범위: platforms/android 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Support snapshot
• Simultaneous gateway sessions
• Wear OS companion
• Install outside Google Play
• Mirror and control Android from a remote Mac
• 시작하기 전에
• Enable ADB over TCP
• Allow only the controller Mac
• Connect and start mirroring
• 트러블슈팅
• Connection runbook
• 사전 요구사항
• 1. Start the Gateway
• 2. Verify discovery (optional)
• 3. Connect from Android
• Manage paired gateways
• Presence alive beacons
• 4. Approve pairing (CLI)
• 5. Verify the node is connected
• 6. Chat + history
• 7. Canvas + camera
• 8. Voice + expanded Android command surface
• 9. Workspace files (read-only)
• Review command approvals
• Answer agent questions
• Assistant entrypoints
• Notification forwarding
• 관련 문서

상세 내용

본문

The official Android app is available on Google Play and as a signed standalone APK on supported GitHub Releases. It is a companion node and requires a running OpenClaw Gateway. Source: apps/android (build instructions).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Support snapshot

System control (launchd/systemd) lives on the Gateway host — see Gateway.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Role: companion node app (Android does not host the Gateway).
• Gateway required: yes (run it on macOS, Linux, or Windows via WSL2).
• Install: Google Play or OpenClaw-Android.apk from a supported GitHub Release, Getting Started for the Gateway, then Pairing.
• Gateway: Runbook + Configuration.
• Protocols: Gateway protocol (nodes + control plane).
• Settings → OpenClaw opens a dedicated Gateway settings assistant when the operator connection has operator.admin and the Gateway supports openclaw.chat. Its setup conversation stays separate from ordinary Chat, redacts secret replies locally, and moves to Chat only after you tap Open Chat.

Simultaneous gateway sessions

Pair each Gateway once, then open Settings → Gateway. The checkmark marks the focused Gateway and each switch controls whether a non-focused Gateway's operator session stays connected. Enabled Gateways reconnect independently while the app is in the foreground, so switching focus does not tear down the others. The focused Gateway alone owns the Android node session and device capabilities; this prevents simultaneous Gateways from issuing camera, location, screen, or notification commands to the same phone. Android can suspend the secondary connections after the app leaves the foreground.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Wear OS companion

The Wear OS companion uses the paired Android phone's authenticated Gateway connection; the watch never receives or stores Gateway credentials. It can select agents and sessions, read bounded transcripts, send text or dictated replies, abort an active run, start realtime Talk inside the selected session, and connect or disconnect the paired phone's Gateway. It also offers local reply notifications, dark or light appearance, and optional automatic speech for replies. Agent and Gateway controls are capability-negotiated for staggered phone/watch updates. Realtime Talk streams microphone and playback audio over a temporary Wear OS Data Layer channel and stops when the selected phone, Gateway connection, or audio channel is lost.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Install outside Google Play

Regular final and correction GitHub Releases include a universal OpenClaw-Android.apk and OpenClaw-Android-SHA256SUMS.txt. The APK is built from the release tag, signed with the OpenClaw Android release key, and carries GitHub Actions provenance.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

release_tag=vYYYY.M.PATCH
gh release download "$release_tag" \
  --repo openclaw/openclaw \
  --pattern OpenClaw-Android.apk \
  --pattern OpenClaw-Android-SHA256SUMS.txt
sha256sum --check OpenClaw-Android-SHA256SUMS.txt
gh attestation verify OpenClaw-Android.apk \
  --repo openclaw/openclaw \
  --signer-workflow openclaw/openclaw/.github/workflows/android-release.yml \
  --source-ref "refs/tags/${release_tag}" \
  --deny-self-hosted-runners

Mirror and control Android from a remote Mac

scrcpy mirrors an Android screen in a macOS window and forwards keyboard and pointer input through Android Debug Bridge (ADB). This is an operator-side workflow, separate from the OpenClaw node connection. It is useful when the Android device and the Mac are in different locations but share a private Tailscale network.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

시작하기 전에

debugging** under Settings > System > Developer options. See Android developer options.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Install Tailscale on the Android device and the Mac, and connect both to the same tailnet.
• On Android, enable Developer options and USB debugging. Android 16 places **Wireless
• Install scrcpy and ADB on the Mac:
• Keep the Android device available for the first connection. Android must approve each Mac's ADB

brew install scrcpy
  brew install --cask android-platform-tools

Enable ADB over TCP

For the initial setup, connect the Android device by USB to a trusted computer and approve its debugging prompt. Then run:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

adb devices
adb tcpip 5555

Allow only the controller Mac

Tailnets with restrictive grants must explicitly allow the controller Mac to reach TCP port 5555 on the Android device. Add a narrow rule to the tailnet policy, replacing the example addresses with the two devices' stable Tailscale IPs:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  grants: [
    {
      src: ["<remote-mac-tailnet-ip>"],
      dst: ["<android-tailnet-ip>"],
      ip: ["tcp:5555"],
    },
  ],
}

Connect and start mirroring

The first adb connect from this Mac shows an authorization dialog on Android. Unlock the device, confirm the key fingerprint, and select Always allow from this computer only when the Mac is trusted. A successful adb devices entry ends in device; unauthorized means the on-device prompt has not been approved.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

adb connect <android-tailnet-ip>:5555
adb devices
scrcpy --serial <android-tailnet-ip>:5555

트러블슈팅

peer reachability, not that policy permits this TCP port. Test with nc -vz 5555 from the Mac.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Connection timed out: verify the tailnet grant for TCP 5555. A successful tailscale ping proves
• unauthorized: unlock Android and approve the remote Mac's ADB key, or remove the stale workstation
• Connection refused: reconnect locally and run adb tcpip 5555 again.
• More than one device listed: keep the explicit --serial <android-tailnet-ip>:5555 argument.

adb disconnect <android-tailnet-ip>:5555

Connection runbook

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Preferred: Tailscale Serve / Funnel with https://<magicdns> / wss://<magicdns>
• Also supported: any other wss:// Gateway URL with a real TLS endpoint
• Cleartext ws:// remains supported on private LAN addresses / .local hosts, plus localhost, 127.0.0.1, and the Android emulator bridge (10.0.2.2); non-loopback setup automatically uses limited operator access

사전 요구사항

주요 항목:

• Gateway running on another machine (or reachable via SSH).
• Android device/emulator can reach the gateway WebSocket:
• Same LAN with mDNS/NSD, or
• Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), or
• Manual gateway host/port (fallback)
• Tailnet/public mobile pairing does not use raw tailnet IP ws:// endpoints. Use Tailscale Serve or another wss:// URL instead.
• The openclaw CLI available on the gateway machine (or via SSH), to approve pairing requests.

1. Start the Gateway

For remote Android access over Tailscale, prefer Serve/Funnel instead of a raw tailnet bind:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• listening on ws://0.0.0.0:18789

openclaw gateway --port 18789 --verbose

openclaw gateway --tailscale serve

2. Verify discovery (optional)

More debugging notes: Bonjour.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

openclaw gateway discover --json

3. Connect from Android

After the first successful pairing, Android auto-reconnects on launch to the active paired gateway (best-effort for discovered gateways, which must be visible on the network).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• The app keeps its gateway connection alive via a foreground service (persistent notification).
• Open the Connect tab.
• Use Setup Code or Manual mode.
• If discovery is blocked, use manual host/port in Advanced controls. For private LAN hosts, ws:// still works. For Tailscale/public hosts, turn on TLS and use a wss:// / Tailscale Serve endpoint.

Manage paired gateways

The app keeps a registry of every gateway it has paired with, so you can keep operator sessions connected and change focus without pairing again:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Settings → Gateway lists paired gateways with the focused one marked. Tap an entry to focus it; the other enabled operator sessions remain connected.
• Each switch controls whether that non-focused Gateway stays connected while the app is in the foreground. The focused Gateway remains enabled and owns the phone's node connection and device capabilities.
• The Connect tab shows a quick switcher when more than one gateway is paired.
• Credentials, device tokens, TLS trust, chat history, and queued offline messages are stored per Gateway. Changing focus never mixes state between Gateways, and messages queued while offline are delivered only to the Gateway they were written for.
• Forget removes a gateway's registry entry together with its credentials, device tokens, TLS pin, and cached chats.

Presence alive beacons

After the authenticated node session connects, and when the app moves to the background while the foreground service is still connected, Android calls node.event with event: "node.presence.alive". The gateway records this as lastSeenAtMs/lastSeenReason on the paired node/device metadata only after the authenticated node device identity is known.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

4. Approve pairing (CLI)

Pairing details: Pairing.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

5. Verify the node is connected

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

6. Chat + history

The Android Chat tab supports session selection (default main, plus other existing sessions):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• History: chat.history (display-normalized — inline directive tags, plain-text tool-call XML payloads (<tool_call>, <function_call>, <tool_calls>, <function_calls>, and truncated variants), and leaked ASCII/full-width model control tokens are stripped; silent-token assistant rows such as exact NO_REPLY / no_reply are omitted; oversized rows can be replaced with placeholders)
• Send: chat.send
• Durable sending: every send (text, picked images, and voice notes) is journaled to a per-gateway on-device outbox before any network attempt, so app termination cannot lose submitted input. Sends queued while offline deliver in order on reconnect with stable idempotency keys, and a send is retired only after the turn is visible in canonical chat.history — an acknowledgement alone is not treated as proof of delivery. Ambiguous outcomes (lost acknowledgement, app killed mid-send, gateway restart before the transcript write) surface as visible rows with explicit Retry/Delete instead of auto-resending. Slash commands never auto-replay across a reconnect; they park for explicit retry. The queue is bounded (50 messages and 48 MB of attachment bytes per gateway) and unsent rows expire after 48 hours. Composer drafts that were never submitted are not process-durable.
• Push updates (best-effort): chat.subscribe -> event:"chat"
• Listen: long-press an assistant message and choose Listen to hear it; audio renders via gateway tts.speak with the configured TTS provider chain, and on-device system TTS is used when the gateway cannot render audio. Playback stops on session switch, new chat, app backgrounding, or chat close.

7. Canvas + camera

To have the node show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• canvas.eval, canvas.snapshot, canvas.navigate (use {"url":""} or {"url":"/"} to return to the default scaffold). canvas.snapshot returns { format, base64 } (default format="jpeg").
• A2UI: canvas.a2ui.push, canvas.a2ui.reset (canvas.a2ui.pushJSONL legacy alias). These use the bundled app-owned A2UI page for action-capable rendering.

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

8. Voice + expanded Android command surface

belongs to the Chat composer; there is no separate Voice tab.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Android's shell navigation is Home, Chat, and Settings. Voice input
• Tap the composer microphone for on-device speech recognition that inserts a
• Start continuous Talk from the Chat waveform. Dictation, voice-note
• Talk Mode promotes the existing foreground service from connectedDevice to connectedDevice|microphone before capture starts, then demotes it when Talk Mode stops. The node service declares FOREGROUND_SERVICE_CONNECTED_DEVICE with CHANGE_NETWORK_STATE; Android 14+ also requires the FOREGROUND_SERVICE_MICROPHONE declaration, the RECORD_AUDIO runtime grant, and the microphone service type at runtime.
• By default, Android Talk uses native speech recognition, Gateway chat, and talk.speak through the configured gateway Talk provider. Local system TTS is used only when talk.speak is unavailable.
• Android Talk uses realtime Gateway relay only when talk.realtime.mode is realtime and talk.realtime.transport is gateway-relay.
• Android does not advertise the voiceWake capability. Use Chat dictation,
• Additional Android command families (availability depends on device, permissions, and user settings):
• device.status, device.info, device.permissions, device.health
• device.apps only when Settings > Phone Capabilities > Installed Apps is enabled; it lists launcher-visible apps by default (pass includeNonLaunchable for the full list).
• notifications.list, notifications.actions (see Notification forwarding below)
• photos.latest
• contacts.search, contacts.add
• calendar.events, calendar.add
• callLog.search
• sms.search
• motion.activity, motion.pedometer

9. Workspace files (read-only)

The Home overview includes a Files card that browses the active agent's workspace through the read-only agents.workspace.list / agents.workspace.get gateway RPCs: directory drill-down, text and image previews, and export through the Android share sheet. There are no write operations, and previews are size-capped by the gateway.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Review command approvals

An operator connection with operator.admin, or a paired operator.approvals connection explicitly targeted by the Gateway, can review pending exec requests under Settings -> Approvals. The app loads the Gateway's sanitized approval record before enabling its buttons, shows any security warning and the exact decisions offered by that request, and submits the approval ID and owner kind back to the Gateway.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Answer agent questions

Chat shows pending Gateway questions as native cards for operator connections with operator.questions (or operator.admin). Cards support single- and multi-select options, option descriptions, free-text Other answers, and an expiry countdown. Reconnects reload pending questions from the Gateway. A card locks when this device answers it, another surface answers it first, or the question expires or is cancelled.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Assistant entrypoints

Android supports launching OpenClaw from the system assistant trigger (Google Assistant). Holding the home button (or another ACTION_ASSIST trigger) opens the app; saying "Hey Google, ask OpenClaw ``" matches the app's declared App Actions query pattern and hands the prompt into the chat composer without auto-sending it.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Notification forwarding

Android can forward device notifications to the gateway as node.event items. This is configured on the device, in the app's Settings sheet — not in gateway/openclaw.json config.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Setting	Description
Forward Notification Events	Master toggle. Off by default; requires Notification Listener Access to be granted first.
Package Filter	Allowlist (only listed package IDs forwarded) or Blocklist (default: all packages except listed IDs). OpenClaw's own package is always excluded in Blocklist mode to prevent forwarding loops.
Quiet Hours	Local HH:mm start/end window that suppresses forwarding. Disabled by default; defaults to 22:00-07:00 once enabled.
Max Events / Minute	Per-device rate limit on forwarded notifications. Default 20.
Route Session Key	Optional. Pins forwarded notification events into a specific session instead of the device's default notification route.

관련 문서

주요 항목:

• iOS app
• Nodes
• Android node troubleshooting

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/android
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

release_tag=vYYYY.M.PATCH
gh release download "$release_tag" \
  --repo openclaw/openclaw \
  --pattern OpenClaw-Android.apk \
  --pattern OpenClaw-Android-SHA256SUMS.txt
sha256sum --check OpenClaw-Android-SHA256SUMS.txt
gh attestation verify OpenClaw-Android.apk \
  --repo openclaw/openclaw \
  --signer-workflow openclaw/openclaw/.github/workflows/android-release.yml \
  --source-ref "refs/tags/${release_tag}" \
  --deny-self-hosted-runners

brew install scrcpy
  brew install --cask android-platform-tools

adb devices
adb tcpip 5555

{
  grants: [
    {
      src: ["<remote-mac-tailnet-ip>"],
      dst: ["<android-tailnet-ip>"],
      ip: ["tcp:5555"],
    },
  ],
}

adb connect <android-tailnet-ip>:5555
adb devices
scrcpy --serial <android-tailnet-ip>:5555

adb disconnect <android-tailnet-ip>:5555

관련 링크

• 공식 원문: platforms/android
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.