How to Connect OpenClaw to iOS

The OpenClaw iOS app is a companion node app, not a standalone gateway. According to the official docs, it connects to a gateway over WebSocket and exposes mobile capabilities such as Canvas, screen snapshots, camera capture, location, talk mode, and voice wake. That makes pairing more like joining a trusted device to your gateway than installing another full server.

When this is the right move

Use the iOS app when you want OpenClaw to reach your phone as a node or when you want a first-party mobile chat and device surface tied back to the main gateway. It is especially useful when the gateway lives on a Mac, Linux box, or Windows host and the phone is a peripheral rather than the control plane.

The practical workflow

1. Start the gateway on another machine and make sure the phone can reach it over the same LAN, a tailnet path, or a manual host and port.
2. Open the iOS app, go to Settings, and pick a discovered gateway or enter the manual host details when discovery is not enough.
3. Approve the pairing request from the gateway host with the device commands before expecting chat or node tools to work.
4. Verify that the node appears in gateway status, then test one simple capability such as chat, a node listing, or a canvas-related action.
5. If you are using an official distributed iOS build, add the documented relay base URL on the gateway so push-backed reconnect and wake flows can register cleanly.

Grounded command or config pattern

The docs keep the first pairing path short. Start the gateway, approve the node, and verify it is visible.

openclaw gateway --port 18789

openclaw devices list
openclaw devices approve <requestId>

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

If the same device retries pairing with changed auth details such as role, scopes, or public key, the docs say the pending request is superseded and a new requestId is created. That is a feature, not a bug: approve the current request, not the one you saw five minutes ago.

Operator notes

Official builds use a relay-backed push path rather than publishing the raw APNs token to the gateway. The docs show a gateway.push.apns.relay.baseUrl requirement for that path. Local or manually built iOS clients are different and may require direct APNs credentials on the gateway host. The important operational point is to match the build type and the gateway push configuration instead of assuming every iOS build behaves the same way.

Rollout approach

For connecting OpenClaw to iOS, I would keep the first pass narrow: one phone, one gateway, one simple verification, and one approved request. Mobile node setups get confusing when discovery, pairing, and push are all changing at once, so start with plain connectivity and only then layer on convenience features.

Common mistake

The common mistake is treating the command or config key as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and one small verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A short note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or host changes.

Safety checks

Do not approve broader scopes blindly if the app reconnects asking for more access. The docs say OpenClaw creates a fresh pending upgrade request rather than silently widening an already paired device. Review the new request, compare it to the currently approved access, and only approve what you intend to expose from the phone.

How to verify it worked

Run openclaw nodes status and openclaw gateway call node.list --params "{}" after approval. Then send one chat from the app or trigger one harmless node interaction to prove the connection is live. If the device never appears, fix reachability and pairing before you chase any app-side UI detail.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.