Android Setup

The Android app is best understood as a field device, not a pocket gateway. Your real gateway stays on a stable host. Android plugs into it as a node and brings the things your server rack does not have: motion, camera, screen, notifications, voice, and location.

That distinction saves a lot of wasted effort. If you expect Android to be the whole runtime, the setup feels wrong. If you treat it like a mobile extension of a real gateway, the design clicks into place fast.

What Android adds to OpenClaw

Think of the gateway as mission control and the Android phone as the rover. The host handles the orchestration. The phone goes out into the world and does the human-adjacent work.

• Persistent node connection through a foreground service
• Canvas presentation and snapshots
• Camera snaps and clips
• Notification forwarding and device status
• Voice capture, Talk Mode, and spoken replies
• Location-aware automation on a paired mobile device

That is a strong combination. It also comes with mobile rules. Android is more flexible than iOS in some places, but it still cares about permissions, foreground state, and secure network paths.

What you need before you start

• A working OpenClaw gateway on macOS, Linux, or Windows through WSL2
• An Android build of the OpenClaw app
• A reachable gateway endpoint
• CLI access to the gateway machine so you can approve pairing

You have three realistic connection paths:

1. Same LAN with mDNS or NSD discovery
2. Same Tailscale tailnet with a secure wss:// endpoint
3. Manual host and port entry as fallback

Start with the same LAN if you can. It is boring, which is exactly why it is useful.

Step 1: Start the gateway first

Before the Android app can connect, the gateway has to exist and be reachable.

openclaw gateway --port 18789 --verbose

On a normal LAN, plain ws:// is fine. For Tailscale or public access, the Android docs recommend using a proper secure endpoint instead of hoping a raw tailnet bind will behave like a finished setup.

openclaw gateway --tailscale serve

If you want one rule to remember, use this one: private network can be simple, remote network should be secure.

Step 2: Let Android find the gateway

Open the app, go to the Connect tab, then choose either Setup Code or Manual. Discovery is the smooth path. Manual host and port are the backup plan when your network is doing improv comedy.

Option A: Same LAN discovery

If the phone and gateway share a local network, the app can discover the gateway with mDNS or NSD. This is the least fragile route for first pairing.

Option B: Tailscale or remote access

For mobile pairing across networks, use a secure wss:// endpoint. The current docs specifically recommend Tailscale Serve or another real TLS endpoint. That is the difference between a setup that feels clean and one that feels like it was assembled from hope.

Option C: Manual host and port

If discovery fails, enter the host and port yourself. On a private LAN, ws://hostname.local:18789 is acceptable. For remote use, switch to wss://.

Step 3: Pair the Android device

Once the app can see the gateway, send the pairing request from Android and approve it on the host machine.

openclaw devices list
openclaw devices approve <requestId>

If the request fails once, do not keep approving the same stale ID forever. Refresh the request list. Mobile retries can replace an older request with a newer one.

Step 4: Verify the node is real, not hypothetical

A paired device should show up as a connected node with capabilities. Check from the gateway side instead of trusting the app screen.

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

Android also sends presence-alive events after the authenticated node session is connected, including when the app moves into the background while its foreground service stays active. That helps the gateway track recent activity, but it does not magically turn every feature into a background-safe feature.

What works well today

The Android app is already useful when you play to its strengths.

• Persistent gateway connection through a foreground service with a visible notification
• Chat access and session history
• Canvas navigation and snapshots while the app is foregrounded
• Camera capture while the app is foregrounded and permissions are granted
• Notification forwarding, contacts, calendar, photos, and device-health style commands when supported by the device and permissions
• Two voice modes: short mic capture and continuous Talk Mode

This is where Android gets interesting. A phone can become a live sensor, a quick control surface, and a conversation endpoint for your agent team.

The limits that matter

This is the part people skip, then rediscover with more emotion than necessary.

• Android does not host the gateway
• The app is not publicly released yet
• canvas.* and camera commands are foreground only
• Direct location.get requests are foreground only on Android today
• Voice wake is still disabled in the Android runtime and UX
• Remote pairing should use secure wss://, not plain tailnet ws://

Useful smoke tests

After pairing, test one thing from each capability family instead of trying everything at once.

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

openclaw nodes invoke --node "Android Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'

openclaw nodes location get --node "Android Node"

If the location command fails while the app is backgrounded, that is expected with the current permission model. Bring the app forward and try again.

Troubleshooting

The app cannot discover the gateway

Put both devices on the same LAN first. If that works, discovery is fine and your remote networking is the real problem.

Pairing requests appear, but approval does not stick

Run openclaw devices list again and approve the newest request ID. Stale auth data can leave you approving the wrong attempt.

Canvas or camera commands fail

Check that the app is in the foreground and the permission was granted. The current Android command surface is wide, but not every command is background-friendly.

Location commands time out or return background errors

Open the app, confirm location sharing is enabled, and keep expectations realistic. Android currently supports direct location reads only while the app is in use.

Remote access works on desktop but not on Android

Look at the endpoint scheme first. If you are still using plain ws:// on a tailnet or public route, that is probably the culprit.

Best practices

• Pair on the same LAN before attempting remote access
• Keep the gateway on a stable machine and use Android as the mobile node
• Prefer secure wss:// for remote setups
• Verify status from the CLI, not just the phone UI
• Start with one clean workflow before expanding into five half-working ones

Summary

The OpenClaw Android app already makes sense when you stop asking it to be the gateway and let it be the mobile edge of your system instead. Pair it to a solid host, respect the foreground limits, and use secure networking when you leave the LAN.

Do that, and Android stops feeling like a fragile preview and starts feeling like a practical field node. That is the right frame for it today.