iOS App (Node)
Availability: internal preview. The iOS app is not publicly distributed yet.What it does
- Connects to a Gateway over WebSocket (LAN or tailnet).
- Exposes node capabilities: Canvas, Screen snapshot, Camera capture, Location, Talk mode, Voice wake.
- Receives
node.invokecommands and reports node status events.
Requirements
- Gateway running on another device (macOS, Linux, or Windows via WSL2).
- Network path:
- Same LAN via Bonjour, or
- Tailnet via unicast DNS-SD (example domain:
openclaw.internal.), or - Manual host/port (fallback).
Quick start (pair + connect)
- Start the Gateway:
- In the iOS app, open Settings and pick a discovered gateway (or enable Manual Host and enter host/port).
- Approve the pairing request on the gateway host:
- Verify connection:
Discovery paths
Bonjour (LAN)
The Gateway advertises_openclaw-gw._tcp on local.. The iOS app lists these automatically.
Tailnet (cross-network)
If mDNS is blocked, use a unicast DNS-SD zone (choose a domain; example:openclaw.internal.) and Tailscale split DNS.
See Bonjour for the CoreDNS example.
Manual host/port
In Settings, enable Manual Host and enter the gateway host + port (default18789).
Canvas + A2UI
The iOS node renders a WKWebView canvas. Usenode.invoke to drive it:
- The Gateway canvas host serves
/__openclaw__/canvas/and/__openclaw__/a2ui/. - It is served from the Gateway HTTP server (same port as
gateway.port, default18789). - The iOS node auto-navigates to A2UI on connect when a canvas host URL is advertised.
- Return to the built-in scaffold with
canvas.navigateand{"url":""}.
Canvas eval / snapshot
Voice wake + talk mode
- Voice wake and talk mode are available in Settings.
- iOS may suspend background audio; treat voice features as best-effort when the app is not active.
Alerts
When the Gateway has APNs credentials (OPENCLAW_APNS_TEAM_ID, OPENCLAW_APNS_KEY_ID, and
OPENCLAW_APNS_PRIVATE_KEY_P8 or OPENCLAW_APNS_PRIVATE_KEY_PATH), it sends alert pushes to a
registered iOS device for:
- a final reply in a session the device follows (opened in the app);
- a pending exec approval in a session the device’s person owns;
- a new inbound inbox item on an account the device’s person owns (bound with
wednesdayai inbox owners bind).
session.identityLinks (device:<id>), and the session must record that
person as its actor. Sessions with no recorded person (main-scope session.dmScope, cron,
heartbeat) send no reply or approval alerts. A followed session stays followed after the app
disconnects, so alerts still arrive while it is in the background.
Alerts show “New reply”, “Approval needed”, or “New inbox item” unless message previews are turned
on in the app, in which case replies and inbox items show their text (up to 200 characters).
Approval alerts never show the command. Each device gets at most one alert per session (or inbox
account) and kind every 30 seconds, and newer alerts replace older ones for the same session.
If the phone is offline, Apple holds the newest reply or inbox alert for up to a day; an approval
alert is dropped once the approval expires.
Common errors
NODE_BACKGROUND_UNAVAILABLE: bring the iOS app to the foreground (canvas/camera/screen commands require it).A2UI_HOST_NOT_CONFIGURED: the Gateway did not advertise a canvas host URL; checkcanvasHostin Gateway configuration.- Pairing prompt never appears: run
wednesdayai devices listand approve manually. - Reconnect fails after reinstall: the Keychain pairing token was cleared; re-pair the node.