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: Google Play or OpenClaw-Android.apk from a GitHub Release that lists both required assets (see Install outside Google Play), Getting Started for the Gateway, then Pairing.
• Gateway: Runbook + Configuration.
  • Protocols: Gateway protocol (nodes + control plane).
• Select an agent in the sidebar to view its credential status in Settings → Providers & Models. The page updates when the Gateway publishes model, credential, or config changes. Use Refresh to recheck model availability.
• The sidebar marks sessions waiting for an answer or approval, including inactive sessions and collapsed groups. Tap the attention icon, hover over it, or focus it with a keyboard to read the oldest pending request and the count of additional requests of the same kind. The indicator clears when requests resolve, are canceled, or expire. Question previews never include answer drafts.
• 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

​

Dictation and attachments

​

Wear OS companion

​

Install outside Google Play

gh api --paginate "repos/openclaw/openclaw/releases?per_page=50" \
  --jq '.[] | select(.draft | not) | {
    tag: .tag_name,
    apk: ([.assets[].name] | any(. == "OpenClaw-Android.apk")),
    checksum: ([.assets[].name] | any(. == "OpenClaw-Android-SHA256SUMS.txt"))
  } | select(.apk and .checksum)'

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

​

Before you begin

• 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 debugging under Settings → System → Developer options. See Android developer options.
• Install scrcpy and ADB on the Mac:
  brew install scrcpy
  brew install --cask android-platform-tools
  
• Keep the Android device available for the first connection. Android must approve each Mac’s ADB key before that Mac can control the device.

​

Enable ADB over TCP

adb devices
adb tcpip 5555

​

Allow only the controller Mac

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

​

Connect and start mirroring

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

​

Troubleshooting

• Connection timed out: verify the tailnet grant for TCP 5555. A successful tailscale ping proves peer reachability, not that policy permits this TCP port. Test with nc -vz <android-tailnet-ip> 5555 from the Mac.
• unauthorized: unlock Android and approve the remote Mac’s ADB key, or remove the stale workstation under Wireless debugging → Paired devices and pair it again.
• 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

• 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

​

Prerequisites

• 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

openclaw config set gateway.bind lan
openclaw gateway --port 18789

openclaw config set gateway.bind loopback
openclaw config set gateway.tailscale.mode serve
openclaw gateway --port 18789

​

2. Verify discovery (optional)

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

openclaw gateway discover --json

​

Cross-network discovery via unicast DNS-SD

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.

​

3. Connect from Android

1. plugins.entries.device-pair.config.publicUrl, unless remote preference was requested.
2. gateway.remote.url when explicitly preferred.
3. Managed Tailscale Serve or Funnel.
4. The ordinary gateway.remote.url setting.
5. A usable configured bind, such as the LAN bind from step 1.

• The app keeps its Gateway connection alive via a foreground service (persistent notification).
• During first-run setup, choose Scan QR or setup code or Set up manually.
• After setup, open Settings → Gateway. Add Gateway lets you scan or paste a setup code, or connect to a discovered Gateway.
• If discovery is blocked, use Manual Gateway on that page: enter the host and port, select Connection security, and tap Save & Connect. Private LAN hosts support ws://; for Tailscale/public hosts, use Secure (TLS) with a wss:// / Tailscale Serve endpoint.

​

Manage paired Gateways

• Settings → Gateway lists paired Gateways in the Gateways section, with a checkmark beside the focused one. Tap another 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.
• 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

​

4. Approve pairing (CLI)

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

• 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)
• Long replies: tap View all on a capped assistant reply to load the full formatted text inline. Attachments stay in the conversation, and message actions use the expanded text. Tap Show less or press Back to restore the preview; reopening reuses the loaded reply. Loading, retryable failures, unavailable messages, and required reconnects or Gateway updates appear in the message rather than an alert. Synthetic message-tool and commentary previews retain their existing display and actions but do not offer View all, because their copied transcript ID cannot retrieve that synthesized text. This also recognizes the older capped-preview format from released Gateways such as v2026.7.1-2. Android requests up to 1,000,000 characters per text field, matching the Gateway’s default retrieval limit; oversized or still-capped results show The full message is too large to display. instead of an incomplete reply.
• Large code blocks scroll within a bounded viewport, with Start of code, End of code, and Copy code controls. Start and End also reveal that end of the block in the conversation. Selection stays within the displayed text segment; Copy code copies the entire block. The separate message Select text action opens a plain-text selection reader; long answers use bounded pages, and selection applies to the displayed page.
• Reading: scrolling up or using View all, Start of code, or End of code pauses automatic following. Incoming content and window-size changes preserve your reading position, moving text or images into view when space shrinks. Resizing an idle conversation so that all content fits resumes following. Jump to latest in the chat header resumes following; it appears only while newer content is below the visible history and never covers messages.
• Mermaid code blocks render as diagrams after the closing fence arrives or the reply finishes. Tap a diagram to open a full-screen view with pinch-to-zoom and panning. The small corner controls copy the source or open a menu to switch between diagram and source. Rendering works offline with bundled assets. Failed diagrams keep their readable source, and temporary failures offer retry. Other code block languages remain code.
• Thread activity: search results and sidebar rows use each thread’s own reported activity. An inactive run does not keep a working or queued indicator solely because its last status was running or queued.
• Session selection: while the app is running, each Gateway and agent remembers the last chat you explicitly selected. Returning to an agent checks an older chat directly if it is outside the recent page; temporary lookup failures show an error without forgetting that choice.
• Archiving the open session returns to the app’s main chat only if that same session is still selected. Switching sessions, agents, or Gateways while the archive finishes preserves your newer selection. A successful archive also retires the archived chat’s remembered selection even if its push notification is missed.
• New in the sidebar creates and selects a fresh chat from any page without clearing the previous session. The sidebar and chat header show progress during creation and initial loading, and duplicate New actions are disabled. History refreshes do not cancel creation; selecting another session, agent, or Gateway while it finishes preserves that newer selection.
• Offline history: cached transcripts update in the order live histories are accepted, so a delayed reconnect health check cannot restore an older snapshot. Switching sessions preserves queued cache updates for the session you left.
• Refresh chat in chat actions reloads history and rechecks Gateway health without clearing pending messages. Chat readiness is separate from the Gateway connection: an empty connected thread shows Chat not ready while health is unconfirmed or a check has failed. Use Refresh chat to check again; Gateway offline indicates a disconnected Gateway. History failures do not stop subsequent health checks. Once Android observes a recovered run finish, a delayed history response does not bring back that run’s Stop button or partial reply.
• Send: chat.send. Outside an active Talk session, you can send text or staged attachments while the agent is working. A new draft brings back Send; clearing it restores Stop. The Gateway applies the existing queue mode, so steering does not require stopping the current run. Sending remains disabled while another submission, attachment staging, or microphone capture owns the draft.
• Queued message controls: Delete removes the local queued copy, including when a reconnect refresh is still finishing. It does not undo a message already accepted by the Gateway; use Stop to cancel an active turn.
• 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. Acknowledged reconnect sends show the same streaming progress as online sends; requests that never reach the socket queue remain queued for the next connection. 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. If refreshed history changes branches, earlier queued input keeps its text and attachments but requires explicit retry; input admitted after that history is displayed can send normally when reconnecting to the same branch. 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.
• Completed answers show up to eight compact source cards for cited pages found in that run’s successful web searches and fetches. Tap a card to read its recorded search snippet or page excerpt and open the source. The cards do not fetch page content; favicons come through the Gateway and honor gateway.controlUi.automaticallyFetchFavicons, with a globe when disabled or unavailable.
• Image input works through the picker and Android Sharesheet. Assistant-generated images resolve through the paired Gateway connection, render inline with a full-screen preview, and retain only their small artifact references in the offline transcript cache. Downloads are capped at 12 MiB and decoded to bounded display bitmaps.
• 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. Camera

​

8. Voice + expanded Android command surface

• Navigate through the sidebar’s Pages menu. Voice input belongs to the Chat composer; there is no separate Voice tab.
• Tap the composer microphone for on-device speech recognition that inserts a transcript into the draft. While listening, a Stop icon replaces the microphone; tap it to finish listening. While starting or transcribing, a Close icon cancels that attempt. Long-press the microphone to open Voice options, then choose Record voice note to create an attachment. The UI reports unavailable recognition, missing permission, busy/network failures, and no-speech outcomes instead of silently dropping the attempt. If dictation is unavailable and a Gateway is selected, Record voice note offers a new recording while keeping the draft. It does not recover speech from the failed dictation attempt or send anything automatically.
• To start continuous Talk, long-press the microphone and choose Start Talk. Dictation, voice-note recording, and Talk are mutually exclusive microphone paths.
• Your selected agent stays bound to Talk and the main chat when the same Gateway reconnects, including while its agent list refreshes. Removing that agent falls back to the Gateway default. Switching Gateways or restarting the app clears this in-memory choice.
• 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. It inherits the session’s thinking setting. Local system TTS is used only when talk.speak is unavailable.
• Gateway config changes refresh Android’s cached Talk settings on the next use, without reconnecting or interrupting an active capture.
• Android Talk uses realtime Gateway relay only when talk.realtime.mode is realtime and talk.realtime.transport is gateway-relay.
• Enable Settings → Voice → Listen for wake words for foreground on-device Voice Wake. Android advertises voiceWake only when enabled, on-device recognition and microphone permission are available, and wake words are synchronized with the current Gateway.
• 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)

​

Review command approvals

​

Answer agent questions

​

Assistant entrypoints

​

Notification forwarding

​

Related

• iOS app
• Nodes
• Android node troubleshooting
• Stable HTTPS URL — give a loopback-only Gateway a stable, tailnet-only HTTPS URL with Tailscale Serve