> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS App

# 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:

```bash theme={"dark"}
wednesdayai gateway --port 18789
```

2. In the iOS app, open Settings and pick a discovered gateway (or enable Manual Host and enter host/port).

3. Approve the pairing request on the gateway host:

```bash theme={"dark"}
wednesdayai devices list
wednesdayai devices approve <requestId>
```

4. Verify connection:

```bash theme={"dark"}
wednesdayai nodes status
wednesdayai gateway call node.list --params "{}"
```

## 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](https://docs.wednesdayai.dev/next/admin/gateway/bonjour.md) 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:

```bash theme={"dark"}
wednesdayai nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__openclaw__/canvas/"}'
```

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

```bash theme={"dark"}
wednesdayai nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'
```

```bash theme={"dark"}
wednesdayai nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'
```

## 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](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md).
* 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.

## Related docs

* [Pairing](https://docs.wednesdayai.dev/next/admin/channels/pairing.md)
* [Discovery](https://docs.wednesdayai.dev/next/admin/gateway/discovery.md)
* [Bonjour](https://docs.wednesdayai.dev/next/admin/gateway/bonjour.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.