Android app

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 (

).

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

• Preferred: Tailscale Serve / Funnel with
  text

  Copy

  https://<magicdns>
  /
  text

  Copy

  wss://<magicdns>
• Also supported: any other
  text

  Copy

  wss://
  Gateway URL with a real TLS endpoint
• Cleartext
  text

  Copy

  ws://
  remains supported on private LAN addresses /
  text

  Copy

  .local
  hosts, plus
  text

  Copy

  localhost
  ,
  text

  Copy

  127.0.0.1
  , and the Android emulator bridge (
  text

  Copy

  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
  text

  Copy

  ws://
  endpoints. Use Tailscale Serve or another
  text

  Copy

  wss://
  URL instead.
• You can run the CLI (
  text

  Copy

  openclaw
  ) on the gateway machine (or via SSH).

1) Start the Gateway

bash
Copy
openclaw gateway --port 18789 --verbose

Confirm in logs you see something like:

• text

  Copy

  listening on ws://0.0.0.0:18789

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

bash
Copy
openclaw gateway --tailscale serve

This gives Android a secure

/ endpoint. A plain setup is not enough for first-time remote Android pairing unless you also terminate TLS separately.

2) Verify discovery (optional)

From the gateway machine:

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

More debugging notes: Bonjour.

If you also configured a wide-area discovery domain, compare against:

bash
Copy
openclaw gateway discover --json

That shows

plus the configured wide-area domain in one pass and uses the resolved service endpoint instead of TXT-only hints.

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 (

or Tailscale Serve):

1. Set up a DNS-SD zone (example
   text

   Copy

   openclaw.internal.
   ) on the gateway host and publish
   text

   Copy

   _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,
  text

  Copy

  ws://
  still works. For Tailscale/public hosts, turn on TLS and use a
  text

  Copy

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

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

with . The gateway records this as / on the paired node/device metadata only after the authenticated node device identity is known.

The app counts the beacon as successfully recorded only when the gateway response includes

. Older gateways may acknowledge with ; that response is compatible but does not count as a durable last-seen update.

4) Approve pairing (CLI)

On the gateway machine:

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

Pairing details: Pairing.

Optional: if the Android node always connects from a tightly controlled subnet, you can opt in to first-time node auto-approval with explicit CIDRs or exact IPs:

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

This is disabled by default. It applies only to fresh

pairing with no requested scopes. Operator/browser pairing and any role, scope, metadata, or public-key change still require manual approval.

5) Verify the node is connected

• Via nodes status:

  bash
  Copy
  openclaw nodes status
  

• Via Gateway:

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

6) Chat + history

The Android Chat tab supports session selection (default

, plus other existing sessions):

• History:
  text

  Copy

  chat.history
  (display-normalized; inline directive tags are stripped from visible text, plain-text tool-call XML payloads (including
  text

  Copy

  <tool_call>...</tool_call>
  ,
  text

  Copy

  <function_call>...</function_call>
  ,
  text

  Copy

  <tool_calls>...</tool_calls>
  ,
  text

  Copy

  <function_calls>...</function_calls>
  , and truncated tool-call blocks) and leaked ASCII/full-width model control tokens are stripped, pure silent-token assistant rows such as exact
  text

  Copy

  NO_REPLY
  /
  text

  Copy

  no_reply
  are omitted, and oversized rows can be replaced with placeholders)
• Send:
  text

  Copy

  chat.send
• Push updates (best-effort):
  text

  Copy

  chat.subscribe
  →
  text

  Copy

  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.

1. Create

   text

   Copy

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

2. Navigate the node to it (LAN):

bash
Copy
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

, e.g. .

This server injects a live-reload client into HTML and reloads on file changes. The A2UI host lives at

.

Canvas commands (foreground only):

• text

  Copy

  canvas.eval
  ,
  text

  Copy

  canvas.snapshot
  ,
  text

  Copy

  canvas.navigate
  (use
  text

  Copy

  {"url":""}
  or
  text

  Copy

  {"url":"/"}
  to return to the default scaffold).
  text

  Copy

  canvas.snapshot
  returns
  text

  Copy

  { format, base64 }
  (default
  text

  Copy

  format="jpeg"
  ).
• A2UI:
  text

  Copy

  canvas.a2ui.push
  ,
  text

  Copy

  canvas.a2ui.reset
  (
  text

  Copy

  canvas.a2ui.pushJSONL
  legacy alias)

Camera commands (foreground only; permission-gated):

• text

  Copy

  camera.snap
  (jpg)
• text

  Copy

  camera.clip
  (mp4)

See Camera node for parameters and CLI helpers.

8) Voice + expanded Android command surface

• Voice tab: Android has two explicit capture modes. Mic is a manual Voice-tab session that sends each pause as a chat turn and stops when the app leaves the foreground or the user leaves the Voice tab. Talk is continuous Talk Mode and keeps listening until toggled off or the node disconnects.
• Talk Mode promotes the existing foreground service from
  text

  Copy

  dataSync
  to
  text

  Copy

  dataSync|microphone
  before capture starts, then demotes it when Talk Mode stops. Android 14+ requires the
  text

  Copy

  FOREGROUND_SERVICE_MICROPHONE
  declaration, the
  text

  Copy

  RECORD_AUDIO
  runtime grant, and the microphone service type at runtime.
• Spoken replies use
  text

  Copy

  talk.speak
  through the configured gateway Talk provider. Local system TTS is used only when
  text

  Copy

  talk.speak
  is unavailable.
• Voice wake remains disabled in the Android UX/runtime.
• Additional Android command families (availability depends on device + permissions):
  • text

    Copy

    device.status
    ,
    text

    Copy

    device.info
    ,
    text

    Copy

    device.permissions
    ,
    text

    Copy

    device.health
  • text

    Copy

    notifications.list
    ,
    text

    Copy

    notifications.actions
    (see Notification forwarding below)
  • text

    Copy

    photos.latest
  • text

    Copy

    contacts.search
    ,
    text

    Copy

    contacts.add
  • text

    Copy

    calendar.events
    ,
    text

    Copy

    calendar.add
  • text

    Copy

    callLog.search
  • text

    Copy

    sms.search
  • text

    Copy

    motion.activity
    ,
    text

    Copy

    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.

Notification forwarding

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

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

Example configuration:

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

Related

• iOS app
• Nodes
• Android node troubleshooting