OpenClaw mobile app: pair iOS or Android with your Gateway
The OpenClaw mobile app is a companion for a running Gateway, not another place to run the Gateway itself. Pairing gives a phone access to the right control surface: selected sessions, approved actions, and device capabilities, without turning a QR code into a permanent all-access credential. The safe sequence is simple: give the phone a private reachable route, create a short-lived setup code from an authenticated admin session, then review the requested role and scopes before approval.
This is different from connecting OpenClaw to Telegram or WhatsApp. A messaging channel delivers conversations. The official iOS and Android apps connect to the Gateway as a device and operator surface, so the pairing decision needs the same care as any other administrative connection.
Table of contents
- What the OpenClaw mobile app connects to
- Prepare a reachable and authenticated Gateway
- Pair the OpenClaw mobile app
- Review access before approving the device
- Use mobile control without creating a second control plane
- FAQ
What the OpenClaw mobile app connects to
The OpenClaw mobile app extends an existing Gateway. The Gateway still owns agent sessions, channel routing, configuration, and the durable record of work. The phone can become the focused companion device for that Gateway, giving you a place to read recent sessions, send a reply, handle an approval, use Talk, or access the device capabilities that the app is allowed to expose.
That distinction prevents a common setup mistake: treating a phone as a standalone agent host. The Android documentation is explicit that the app is a companion node and requires a running Gateway. The iOS documentation makes the same point by requiring a Gateway on another device. If the Gateway is unavailable, the mobile app can show cached or queued state in some cases, but it cannot replace the system that owns the agent run.
| Surface | Primary job | What it should not become |
|---|---|---|
| Gateway | Own sessions, policies, routing, and the system record | An unauthenticated public endpoint |
| Control UI | Create setup codes, inspect status, review pairing and approvals | A dashboard exposed to the public internet |
| OpenClaw mobile app | Let a trusted operator follow and control the selected Gateway | A second independent source of session truth |
| Chat channel | Deliver messages in a familiar app | A substitute for device-scoped administrative access |
For the broader runtime model, start with how OpenClaw works. If you only need to chat with an agent from a familiar messenger, the existing phone connection guide covers that separate channel setup.
Prepare a reachable and authenticated Gateway
A phone cannot use the default loopback-only Gateway address. Before creating a pairing code, confirm that the phone has a route to the Gateway and that the Gateway requires authentication.
For remote use, OpenClaw documents a secure wss:// route, such as Tailscale Serve. For a trusted same-LAN setup, an authenticated LAN binding can work. A raw public ws:// address is the wrong shortcut: the Control UI documentation limits plain WebSocket usage to loopback and private LAN addresses, and the iOS and Android setup paths limit access when the transport is not protected.
A minimal remote starting point from the OpenClaw documentation is:
openclaw gateway --port 18789 --tailscale serveRun onboarding first if the Gateway has never been configured. Pairing relies on a real token or password authentication path; an ephemeral runtime token is not a durable substitute for a configured setup.
Pair the OpenClaw mobile app
OpenClaw’s current Control UI has a direct mobile-pairing path. You do not need to copy a gateway token into an app setting by hand.
- Sign in to the Control UI with an already paired administrator session.
- Open Devices, then select Pair mobile device in the Devices card.
- Create the setup code. The UI requires
operator.adminfor this step. - On iOS or Android, open Settings and then Gateway.
- Scan the QR code or paste the setup code.
- Let the app connect, then check for a pending approval request.
The QR code is a convenience for moving a short-lived secret between two trusted screens. It is not an authorization decision by itself. OpenClaw’s Control UI docs say to treat the code like a password while it remains valid.
On iOS, the app can try both LAN and Tailscale routes when the setup code contains them, then save the first reachable endpoint. The app keeps paired Gateways in a list, but the focused Gateway owns the phone’s capability-bearing node session. That makes camera, screen, location, and other device actions attributable to one Gateway at a time instead of silently sharing the phone across several systems.
Android follows the same architectural rule: it pairs with the Gateway over the device connection and treats the focused Gateway as the owner of the Android node session. Switching focus does not need to erase every saved Gateway, but it should not leave two Gateways competing for the same device controls.
Review access before approving the device
If the app shows Pending approval, stop there and inspect the request. Pairing is where OpenClaw turns a reachable phone into an approved device. The Control UI and the openclaw devices commands allow an operator to review the request ID before approval.
Check these four things:
- Gateway identity: confirm this is the Gateway you meant to reach, not a similarly named host on an untrusted network.
- Role and scopes: a request for broader access should be explicit. OpenClaw treats an existing browser moving from read access to write or admin access as an approval upgrade rather than a silent reconnect.
- Transport: remote pairing should resolve to
wss://. If a setup falls back to plaintext LAN WebSocket, accept the resulting limited access rather than trying to work around the safety boundary. - Device ownership: approve only the phone you control. Replacing, reinstalling, or changing a device’s pairing identity can require a new request.
If you need a terminal fallback, list the request on the Gateway host and approve the current request ID:
openclaw devices list
openclaw devices approve <requestId>Do not reuse an old request ID after the app retries with changed role, scope, or key details. OpenClaw supersedes the previous pending request in that case, so the current request is the one that needs review.
For a deeper look at the browser-side control surface that creates these codes, see the OpenClaw Control UI guide. For the operational problem after pairing, including reconnects and approvals while away from the desk, read mobile AI agent sessions.
Use mobile control without creating a second control plane
Once paired, the mobile app can make an agent more usable away from the host machine. It can surface a session, a waiting question, a pending approval, or a short reply without forcing the operator to reconstruct the work from a notification.
The app should still defer to the Gateway for authoritative state. A phone can sleep, change networks, or reconnect after another operator has already resolved an approval. OpenClaw’s iOS documentation describes a useful pattern: approval actions remain unavailable until the app reads back the Gateway’s canonical terminal record. That prevents a late tap on the phone from pretending it changed an approval that another surface already resolved.
Keep the mobile workflow narrow:
- Use the phone to inspect, steer, answer, or approve the work that belongs to a selected session.
- Keep broad configuration edits on a screen where you can inspect their full scope.
- Revoke a device when it is lost, replaced, or no longer belongs to an operator.
- Use a private remote path, not a publicly reachable dashboard.
OpenClaw v2026.7.1 made this pairing flow easier to find in the Control UI and continued the iOS and Android work around setup, recovery, sessions, and device controls. The useful outcome is not “agent access everywhere.” It is a clear handoff from a Gateway you control to a phone you recognize, with enough context to make a real decision.
FAQ
Does the OpenClaw mobile app run the Gateway?
No. The official iOS and Android apps are companion apps for a running OpenClaw Gateway. The Gateway owns the agent session, policies, and system state; the phone connects as a selected operator and device surface.
How do I pair the OpenClaw mobile app?
In the Control UI, open Devices and choose Pair mobile device from an authenticated administrator session. Create a short-lived setup code, then scan its QR code or paste the code in the mobile app under Settings and Gateway. Review any pending approval request before accepting it.
Should I use ws:// to pair a phone remotely?
No. Use a protected wss:// route for remote access, such as Tailscale Serve or another TLS-terminated Gateway endpoint. Plain WebSocket has restricted use on private LAN and loopback paths and can result in limited mobile access.
Can one phone control several Gateways?
The apps can retain paired Gateways, but the focused Gateway owns the phone’s capability-bearing node session. This keeps device actions tied to one active Gateway rather than allowing several systems to issue commands to the same phone at once.