Skip to main content

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.invoke commands 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)

  1. Start the Gateway:
  1. In the iOS app, open Settings and pick a discovered gateway (or enable Manual Host and enter host/port).
  2. Approve the pairing request on the gateway host:
  1. 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 (default 18789).

Canvas + A2UI

The iOS node renders a WKWebView canvas. Use node.invoke to drive it:
Notes:
  • The Gateway canvas host serves /__openclaw__/canvas/ and /__openclaw__/a2ui/.
  • It is served from the Gateway HTTP server (same port as gateway.port, default 18789).
  • The iOS node auto-navigates to A2UI on connect when a canvas host URL is advertised.
  • Return to the built-in scaffold with canvas.navigate and {"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).
Alerts go only to the devices of the person who owns the session or account: the device must be linked to that person in 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. From the app you can mute reply alerts or inbox alerts for the whole account, or only a single inbox source or one of its accounts; the mute applies on every device linked to the person, and approval alerts always arrive. A replayed or re-synced message alerts a device at most once every 10 minutes; identical text no longer hides a different message (the 30-second limit still applies).

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; check canvasHost in Gateway configuration.
  • Pairing prompt never appears: run wednesdayai devices list and approve manually.
  • Reconnect fails after reinstall: the Keychain pairing token was cleared; re-pair the node.