openclaw/docs/platforms/android.md

summary, read_when, title

summary	read_when	title
Android app (node): connection runbook + Connect/Chat/Voice/Canvas command surface	Pairing or reconnecting the Android node Debugging Android gateway discovery or auth Verifying chat history parity across clients	Android App

Android App (Node)

Note: The Android app has not been publicly released yet. The source code is available in the OpenClaw repository under apps/android. You can build it yourself using Java 17 and the Android SDK (./gradlew :app:assemblePlayDebug). See apps/android/README.md for build instructions.

Support snapshot

• Role: companion node app (Android does not host the Gateway).
• Gateway required: yes (run it on macOS, Linux, or Windows via WSL2).
• Install: Getting Started + Pairing.
• Gateway: Runbook + Configuration.
  • Protocols: Gateway protocol (nodes + control plane).

System control

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

Connection Runbook

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

Android connects directly to the Gateway WebSocket and uses device pairing (role: node).

For Tailscale or public hosts, Android requires a secure endpoint:

• 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)

Prerequisites

• You can run the Gateway on the “master” machine.
• 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.
• You can run the CLI (openclaw) on the gateway machine (or via SSH).

1) Start the Gateway

openclaw gateway --port 18789 --verbose

Confirm in logs you see something like:

• listening on ws://0.0.0.0:18789

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

openclaw gateway --tailscale serve

This gives Android a secure wss:// / https:// endpoint. A plain gateway.bind: "tailnet" setup is not enough for first-time remote Android pairing unless you also terminate TLS separately.

2) Verify discovery (optional)

From the gateway machine:

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

More debugging notes: Bonjour.

Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD

Android NSD/mDNS discovery won’t cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead.

Discovery alone is not sufficient for tailnet/public Android pairing. The discovered route still needs a secure endpoint (wss:// or Tailscale Serve):

1. Set up a DNS-SD zone (example openclaw.internal.) on the gateway host and publish _openclaw-gw._tcp records.
2. Configure Tailscale split DNS for your chosen domain pointing at that DNS server.

Details and example CoreDNS config: Bonjour.

3) Connect from Android

In the Android app:

• 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.

After the first successful pairing, Android auto-reconnects on launch:

• Manual endpoint (if enabled), otherwise
• The last discovered gateway (best-effort).

4) Approve pairing (CLI)

On the gateway machine:

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

Pairing details: Pairing.

5) Verify the node is connected

• Via nodes status:

  openclaw nodes status
  

• Via Gateway:

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

6) Chat + history

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

• History: chat.history
• Send: chat.send
• Push updates (best-effort): chat.subscribe → event:"chat"

7) Canvas + camera

Gateway Canvas Host (recommended for web content)

If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.

Note: nodes load canvas from the Gateway HTTP server (same port as gateway.port, default 18789).

1. Create ~/.openclaw/workspace/canvas/index.html on the gateway host.

2. Navigate the node to it (LAN):

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

Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of .local, e.g. http://<gateway-magicdns>:18789/__openclaw__/canvas/.

This server injects a live-reload client into HTML and reloads on file changes. The A2UI host lives at http://<gateway-host>:18789/__openclaw__/a2ui/.

Canvas commands (foreground only):

• 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)

Camera commands (foreground only; permission-gated):

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

See Camera node for parameters and CLI helpers.

8) Voice + expanded Android command surface

• Voice: Android uses a single mic on/off flow in the Voice tab with transcript capture and TTS playback (ElevenLabs when configured, system TTS fallback). Voice stops when the app leaves the foreground.
• Voice wake/talk-mode toggles are currently removed from Android UX/runtime.
• Additional Android command families (availability depends on device + permissions):
  • device.status, device.info, device.permissions, device.health
  • 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

Assistant entrypoints

Android supports launching OpenClaw from the system assistant trigger (Google Assistant). When configured, holding the home button or saying "Hey Google, ask OpenClaw..." opens the app and hands the prompt into the chat composer.

This uses Android App Actions metadata declared in the app manifest. No extra configuration is needed on the gateway side -- the assistant intent is handled entirely by the Android app and forwarded as a normal chat message.

App Actions availability depends on the device, Google Play Services version, and whether the user has set OpenClaw as the default assistant app.

Notification forwarding

Android can forward device notifications to the gateway as events. Several controls let you scope which notifications are forwarded and when.

Key	Type	Description
notifications.allowPackages	string[]	Only forward notifications from these package names. If set, all other packages are ignored.
notifications.denyPackages	string[]	Never forward notifications from these package names. Applied after allowPackages.
notifications.quietHours.start	string (HH:mm)	Start of quiet hours window (local device time). Notifications are suppressed during this window.
notifications.quietHours.end	string (HH:mm)	End of quiet hours window.
notifications.rateLimit	number	Maximum forwarded notifications per package per minute. Excess notifications are dropped.

The notification picker also uses safer behavior for forwarded notification events, preventing accidental forwarding of sensitive system notifications.

Example configuration:

{
  notifications: {
    allowPackages: ["com.slack", "com.whatsapp"],
    denyPackages: ["com.android.systemui"],
    quietHours: {
      start: "22:00",
      end: "07:00",
    },
    rateLimit: 5,
  },
}

Notification forwarding requires the Android Notification Listener permission. The app prompts for this during setup.