iOS App Setup

The OpenClaw iOS app is not a tiny gateway stuffed into your phone. It is better thought of as a mobile field kit. Your real gateway stays on a Mac, Linux box, or Windows machine with WSL2. The iPhone connects to that gateway and adds the sensors and surfaces a desktop machine does not carry in its pocket.

That distinction matters because it saves you from the wrong setup plan. If you expect the phone to be the whole runtime, you will get frustrated fast. If you treat it like a trusted node with mobile powers, the design makes sense.

What the iOS app actually adds

A good way to think about it is this: your gateway is the control room, your iPhone is the scout. It can move, see, listen, wake you, and report back from places your server never will.

• Canvas rendering on the phone
• Screen snapshots
• Camera capture
• Location signals
• Talk mode and voice wake
• Node status and presence updates back to the gateway

That is why the app is useful even though it does not host the gateway itself. It extends OpenClaw into the physical world in a way your rack server cannot.

What you need before you start

• A working OpenClaw gateway on macOS, Linux, or Windows via WSL2
• An iPhone build of the OpenClaw app, either from internal distribution or your own source build
• A network path between phone and gateway
• A few spare minutes and one device that can approve pairing

For networking, you have three realistic options:

1. Same LAN with discovery
2. Tailnet with unicast DNS-SD
3. Manual host and port entry as fallback

If you are new to OpenClaw, same LAN is the least annoying starting point.

Step 1: Start the gateway first

The phone cannot pair into thin air. Start or confirm the gateway on the host machine before touching the app.

openclaw gateway --port 18789

That default port matters because many later examples assume it. Change it if you want, but then stay consistent everywhere else.

Step 2: Pick how the iPhone will find the gateway

Option A: Same LAN discovery

This is the smooth path. If the iPhone and gateway are on the same network, the app can discover the gateway automatically.

Option B: Tailnet

This is the better remote path for most people. You get stable connectivity without exposing the gateway to the open internet. It is cleaner than heroic port-forwarding experiments that feel clever right until they are not.

Option C: Manual host and port

Use this when discovery fails or your network is unusual. In the iOS app settings, enable Manual Host and enter the gateway host plus port. Default port is 18789.

Step 3: Pair the iPhone with the gateway

Once the app sees the gateway, select it in Settings. The app will request pairing. Approval happens on the gateway host, not on the phone.

openclaw devices list
openclaw devices approve <requestId>

One subtle trap: if the app retries with changed auth details, the old pending request can be replaced by a new one. If approval fails, run openclaw devices list again and approve the fresh request ID, not the stale one.

Step 4: Verify that the node is really connected

Do not trust vibes. Verify the node from the gateway side.

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

You want to see the iPhone show up as a node with active capabilities. If it is missing, you do not have a working setup yet, only optimism.

What works well today

Right now the iOS app is strongest when you keep it in the foreground and use it as an active device node. That covers more than most people expect:

• Chat and operator session access
• Canvas presentation and navigation
• Camera snapshot or clip capture
• Screen tools
• Location-driven automation signals
• Share extension handoff into a connected session

This opens some genuinely useful workflows. Your agent can inspect what the phone camera sees, receive a location event when you arrive somewhere, or show a canvas UI on the device itself.

The limits you should know before promising too much

iOS cares deeply about battery, privacy, and whether your app deserves to exist in the background. That means some OpenClaw behaviors are best-effort, not guaranteed.

• Foreground use is the reliable mode today
• Background sockets can be suspended
• canvas.*, camera.*, screen.*, and talk.* are limited when the app is backgrounded
• Background location requires Always permission
• Reinstalling the app can clear pairing state and force re-pairing

Useful test commands after pairing

Once the node is visible, you can smoke-test a canvas flow from the gateway host.

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

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

If commands fail with background-related errors, bring the app to the foreground and try again. That is not you doing something wrong. That is the current operating reality.

Troubleshooting

The pairing prompt never seems to finish

Check pending requests directly on the gateway host with openclaw devices list. The app may have created a newer request than the one you first saw.

The node appears, then disappears

This often points to network reachability or iOS background suspension. Test on the same LAN first. If that works, your remote path is the real issue.

Canvas says host is not configured

That usually means the gateway did not advertise the canvas host URL correctly. Check your canvas plugin host configuration on the gateway.

Reconnect fails after reinstalling the app

Reinstalling can clear the Keychain pairing token. Re-pair the iPhone rather than trying to revive the old trust state.

Location automations do not fire in the background

Confirm that the app has Always location permission and that your automation is designed around real movement events, not constant polling.

Best practices

• Start with same-LAN pairing before attempting remote access
• Keep the gateway on a stable host and treat the phone as a node, not the core runtime
• Verify pairing and node status from the CLI, not just the app UI
• Design around foreground-friendly actions first
• Use tailnet-style networking when you need remote reach without public exposure

Summary

The OpenClaw iOS app is promising because it gives your agent a phone body, not because it replaces the gateway. Pair it to a stable host, keep expectations realistic about background behavior, and focus on workflows where a mobile node adds something your server cannot.

Do that, and the app feels less like a fragile preview and more like a very capable scout. That is a good place to start.