iOS app

iOS app 문서는 OpenClaw 공식 문서(platforms/ios)를 한국어로 정리한 가이드입니다. iOS node app: connect to the Gateway, pairing, canvas, and troubleshooting 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

iOS node app: connect to the Gateway, pairing, canvas, and troubleshooting

한국어 가이드 범위: platforms/ios 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What it does
요구사항
Quick start (pair + connect)
Health summaries
Review command approvals
Answer agent questions
Optional direct Apple Watch node
Relay-backed push for official builds
Background alive beacons
Authentication and trust flow
Discovery paths
Bonjour (LAN)
Tailnet (cross-network)
Manual host/port
Multiple gateways
Canvas + A2UI
Computer Use relationship
Canvas eval / snapshot
Voice wake + talk mode
Common errors
Related docs

상세 내용

본문

Availability: iPhone app builds are distributed through Apple channels when enabled for a release. Local development builds can also run from source.

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, and opt-in Health summaries.
Receives node.invoke commands and reports node status events.
Browses the selected agent's workspace read-only from the Agents surface (Files): directory drill-down, syntax-highlighted text previews, image previews, and share-sheet export. No write operations; previews are size-capped by the gateway.
Keeps a small read-only offline cache of recent chat sessions and transcripts per paired gateway: cold opens paint the last known transcript immediately and refresh once the gateway responds, recent chats stay browsable while disconnected, and reset/forget purges the protected local cache.
Queues text messages sent while disconnected in a durable per-gateway outbox (up to 50): queued bubbles show in the transcript, flush in order on reconnect with idempotent retries, remain durable until canonical history confirms the send, retry with backoff before surfacing a retry/delete action, and expire instead of sending after 48 hours offline; reset/forget clears the queue with the cache.
Chat is the single text-and-voice surface. Chat actions can open the full Sessions screen without leaving Chat and can show or hide assistant reasoning and tool activity. Tap the microphone for draft dictation, open its menu to record a voice note, or use the inline Talk control for realtime voice; the Talk control animates from live microphone or playback level while listening or speaking.
Settings -> OpenClaw opens a dedicated Gateway settings assistant when the operator connection has operator.admin and the Gateway supports openclaw.chat. Its setup conversation stays separate from ordinary Chat, redacts secret replies locally, and moves to Chat only after you tap Open Chat.
Speaks assistant messages on demand: long-press a message in Chat and choose Listen. The app plays supported gateway tts.speak clips with the configured TTS provider and falls back to on-device speech when gateway audio is unavailable or unplayable. Playback stops on session switch or backgrounding.

요구사항

주요 항목:

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)

On first launch the app walks through a short pairing explainer and a permissions page (notifications, camera, microphone, photos, contacts, calendar, reminders, location). Every grant is optional and can be changed later in Settings -> Permissions, or in the iOS Settings app.

openclaw gateway --port 18789 --tailscale serve

openclaw devices list
openclaw devices approve <requestId>

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

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

Health summaries

The iOS node can return an opt-in, read-only HealthKit aggregate for the current calendar day. iOS device consent and explicit Gateway command authorization are independent gates. See HealthKit summaries for setup, invocation, payload fields, privacy behavior, and troubleshooting.

Review command approvals

An operator connection with operator.admin, or a paired operator.approvals connection explicitly targeted by the Gateway, can review pending exec requests on iPhone. The approval card shows the Gateway's sanitized command preview, warning, host context, expiry, and only the decisions offered by that request. The paired Apple Watch receives the same reviewer-safe prompt through the existing iPhone relay and offers the compact allow-once/deny decision subset. Direct Watch Gateway mode does not carry approval prompts.

Answer agent questions

Chat shows pending Gateway questions as native cards for operator connections with operator.questions (or operator.admin). Cards support single- and multi-select options, option descriptions, free-text Other answers, and an expiry countdown. Reconnects reload pending questions from the Gateway. A card locks when this device answers it, another surface answers it first, or the question expires or is cancelled.

Optional direct Apple Watch node

Direct mode gives the watch its own signed node identity and Gateway connection. Supported node commands continue to work over watch Wi-Fi or cellular while OpenClaw is active, even when the paired iPhone is unavailable.

주요 항목:

The iPhone is connected to the Gateway with operator.admin scope.
The setup code advertises a wss:// Gateway endpoint with a certificate trusted
Cellular use requires a cellular-capable Apple Watch with active service.
OpenClaw is active on the watch. Apple does not allow ordinary watchOS apps to

Surface	Commands	Notes
Device	`device.info`, `device.status`	Watch identity, battery, thermal, storage, and network.
Notifications	`system.notify`	While the app is active; requires watch permission.

Relay-backed push for official builds

Official distributed iOS builds use an external push relay instead of publishing the raw APNs token to the gateway. Official App Store builds from the public release lane use the hosted relay at https://ios-push-relay.openclaw.ai; this base URL is hardcoded for App Store distribution and does not read any override.

주요 항목:

The iOS app registers with the relay using App Attest and a StoreKit app transaction JWS.
The relay returns an opaque relay handle plus a registration-scoped send grant.
The iOS app fetches the paired gateway identity (gateway.identity.get) and includes it in relay registration, so the relay-backed registration is delegated to that specific gateway.
The app forwards that relay-backed registration to the paired gateway with push.apns.register.
The gateway uses that stored relay handle for push.test, background wakes, and wake nudges.
If the app later connects to a different gateway or a build with a different relay base URL, it refreshes the relay registration instead of reusing the old binding.

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
        },
      },
    },
  },
}

Background alive beacons

When iOS wakes the app for a silent push, background refresh, or significant-location event, the app attempts a short node reconnect and then calls node.event with event: "node.presence.alive". The gateway records this as lastSeenAtMs/lastSeenReason on the paired node/device metadata only after the authenticated node device identity is known.

주요 항목:

OPENCLAW_APNS_RELAY_BASE_URL still works as a temporary env override for the gateway (gateway.push.apns.relay.baseUrl is the config-first path).
The App Store release build's push mode hardcodes the hosted relay host and never reads a relay-URL override — the OPENCLAW_PUSH_RELAY_BASE_URL build-time env var only affects local/sandbox iOS build modes.

Authentication and trust flow

The relay exists to enforce two constraints direct APNs-on-gateway cannot provide for official iOS builds:

주요 항목:

Only genuine OpenClaw iOS builds distributed through Apple can use the hosted relay.
A gateway can send relay-backed pushes only for iOS devices that paired with that specific gateway.

mkdir -p ~/.openclaw/credentials/apns
chmod 700 ~/.openclaw/credentials/apns
mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8

Discovery paths

이 섹션의 세부 항목은 공식 문서 Discovery paths를 참고하세요.

Bonjour (LAN)

The iOS app browses _openclaw-gw._tcp on local. and, when configured, the same wide-area DNS-SD discovery domain. Same-LAN gateways appear automatically from local.; cross-network discovery can use the configured wide-area domain without changing the beacon type.

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

Multiple gateways

The app keeps a registry of every gateway it has paired with, so you can switch between them without pairing again:

주요 항목:

Settings -> Gateway shows a Paired Gateways list with the active gateway marked. Tap an entry to switch; the app tears down the current sessions and reconnects to the selected gateway. A quick-switch menu appears next to the connection row when more than one gateway is paired.
Credentials, TLS trust decisions, per-gateway preferences, and cached chat history are stored per gateway. Switching never mixes state between gateways, and push registration follows the active gateway.
Swipe a paired gateway (or use its context menu) to Forget it, which removes its credentials, device tokens, TLS pin, and cached chats.
Discovered gateways must be visible on the network to switch to them; manual gateways reconnect by saved host and port.

Canvas + A2UI

The iOS node renders a WKWebView canvas. Use node.invoke to drive it:

주요 항목:

The Gateway canvas host serves /__openclaw__/canvas/ and /__openclaw__/a2ui/, from the Gateway HTTP server (same port as gateway.port, default 18789).
The iOS node keeps the built-in scaffold as the connected default view. canvas.a2ui.push and canvas.a2ui.reset use the bundled app-owned A2UI page.
Remote Gateway A2UI pages are render-only on iOS; native A2UI button actions are accepted only from bundled app-owned pages.
Return to the built-in scaffold with canvas.navigate and {"url":""}.

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

Computer Use relationship

The iOS app is a mobile node surface, not a Codex Computer Use backend. Codex Computer Use and cua-driver mcp control a local macOS desktop through MCP tools; the iOS app exposes iPhone capabilities through OpenClaw node commands such as canvas.*, camera.*, screen.*, location.*, and talk.*.

Canvas eval / snapshot

openclaw 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\"; })()"}'

openclaw 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.
OpenAI realtime Talk uses client-owned WebRTC when talk.realtime.transport is webrtc; an explicit gateway-relay configuration remains Gateway-owned. See Talk mode.
Talk-capable iOS nodes advertise the talk capability and can declare talk.ptt.start, talk.ptt.stop, talk.ptt.cancel, and talk.ptt.once; the Gateway allows those push-to-talk commands by default for trusted Talk-capable nodes.
iOS may suspend background audio; treat voice features as best-effort when the app is not active.

Common errors

and watchAppInstalled: true in watch.status. If pairing is false, pair the Watch in Apple's Watch app. If installation is false, install the companion from My Watch -> Available Apps. After either change, open OpenClaw on the Watch once; immediate reachability still requires both apps to be running, while queued updates can arrive later in the background.

주요 항목:

NODE_BACKGROUND_UNAVAILABLE: bring the iOS app to the foreground (canvas/camera/screen commands require it).
A2UI_HOST_UNAVAILABLE: the bundled A2UI page was not reachable in the app WebView; keep the app foregrounded on the Screen tab and retry.
Pairing prompt never appears: run openclaw devices list and approve manually.
Watch shows no iPhone state: confirm the iPhone reports watchPaired: true
Reconnect fails after reinstall: the Keychain pairing token was cleared; re-pair the node.

주요 항목:

Pairing
Discovery
Bonjour

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/ios
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw gateway --port 18789 --tailscale serve

openclaw devices list
openclaw devices approve <requestId>

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

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

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
        },
      },
    },
  },
}

iOS app

핵심 요약

iOS node app: connect to the Gateway, pairing, canvas, and troubleshooting

한국어 가이드 범위: platforms/ios 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What it does
요구사항
Quick start (pair + connect)
Health summaries
Review command approvals
Answer agent questions
Optional direct Apple Watch node
Relay-backed push for official builds
Background alive beacons
Authentication and trust flow
Discovery paths
Bonjour (LAN)
Tailnet (cross-network)
Manual host/port
Multiple gateways
Canvas + A2UI
Computer Use relationship
Canvas eval / snapshot
Voice wake + talk mode
Common errors
Related docs

상세 내용

본문

Availability: iPhone app builds are distributed through Apple channels when enabled for a release. Local development builds can also run from source.

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, and opt-in Health summaries.
Receives node.invoke commands and reports node status events.
Browses the selected agent's workspace read-only from the Agents surface (Files): directory drill-down, syntax-highlighted text previews, image previews, and share-sheet export. No write operations; previews are size-capped by the gateway.
Keeps a small read-only offline cache of recent chat sessions and transcripts per paired gateway: cold opens paint the last known transcript immediately and refresh once the gateway responds, recent chats stay browsable while disconnected, and reset/forget purges the protected local cache.
Queues text messages sent while disconnected in a durable per-gateway outbox (up to 50): queued bubbles show in the transcript, flush in order on reconnect with idempotent retries, remain durable until canonical history confirms the send, retry with backoff before surfacing a retry/delete action, and expire instead of sending after 48 hours offline; reset/forget clears the queue with the cache.
Chat is the single text-and-voice surface. Chat actions can open the full Sessions screen without leaving Chat and can show or hide assistant reasoning and tool activity. Tap the microphone for draft dictation, open its menu to record a voice note, or use the inline Talk control for realtime voice; the Talk control animates from live microphone or playback level while listening or speaking.
Settings -> OpenClaw opens a dedicated Gateway settings assistant when the operator connection has operator.admin and the Gateway supports openclaw.chat. Its setup conversation stays separate from ordinary Chat, redacts secret replies locally, and moves to Chat only after you tap Open Chat.
Speaks assistant messages on demand: long-press a message in Chat and choose Listen. The app plays supported gateway tts.speak clips with the configured TTS provider and falls back to on-device speech when gateway audio is unavailable or unplayable. Playback stops on session switch or backgrounding.

요구사항

주요 항목:

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)

openclaw gateway --port 18789 --tailscale serve

openclaw devices list
openclaw devices approve <requestId>

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

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

Health summaries

Review command approvals

Answer agent questions

Optional direct Apple Watch node

주요 항목:

The iPhone is connected to the Gateway with operator.admin scope.
The setup code advertises a wss:// Gateway endpoint with a certificate trusted
Cellular use requires a cellular-capable Apple Watch with active service.
OpenClaw is active on the watch. Apple does not allow ordinary watchOS apps to

Surface	Commands	Notes
Device	`device.info`, `device.status`	Watch identity, battery, thermal, storage, and network.
Notifications	`system.notify`	While the app is active; requires watch permission.

Relay-backed push for official builds

주요 항목:

The iOS app registers with the relay using App Attest and a StoreKit app transaction JWS.
The relay returns an opaque relay handle plus a registration-scoped send grant.
The iOS app fetches the paired gateway identity (gateway.identity.get) and includes it in relay registration, so the relay-backed registration is delegated to that specific gateway.
The app forwards that relay-backed registration to the paired gateway with push.apns.register.
The gateway uses that stored relay handle for push.test, background wakes, and wake nudges.
If the app later connects to a different gateway or a build with a different relay base URL, it refreshes the relay registration instead of reusing the old binding.

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
        },
      },
    },
  },
}

Background alive beacons

주요 항목:

OPENCLAW_APNS_RELAY_BASE_URL still works as a temporary env override for the gateway (gateway.push.apns.relay.baseUrl is the config-first path).
The App Store release build's push mode hardcodes the hosted relay host and never reads a relay-URL override — the OPENCLAW_PUSH_RELAY_BASE_URL build-time env var only affects local/sandbox iOS build modes.

Authentication and trust flow

The relay exists to enforce two constraints direct APNs-on-gateway cannot provide for official iOS builds:

주요 항목:

Only genuine OpenClaw iOS builds distributed through Apple can use the hosted relay.
A gateway can send relay-backed pushes only for iOS devices that paired with that specific gateway.

mkdir -p ~/.openclaw/credentials/apns
chmod 700 ~/.openclaw/credentials/apns
mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8

Discovery paths

이 섹션의 세부 항목은 공식 문서 Discovery paths를 참고하세요.

Bonjour (LAN)

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

Multiple gateways

The app keeps a registry of every gateway it has paired with, so you can switch between them without pairing again:

주요 항목:

Settings -> Gateway shows a Paired Gateways list with the active gateway marked. Tap an entry to switch; the app tears down the current sessions and reconnects to the selected gateway. A quick-switch menu appears next to the connection row when more than one gateway is paired.
Credentials, TLS trust decisions, per-gateway preferences, and cached chat history are stored per gateway. Switching never mixes state between gateways, and push registration follows the active gateway.
Swipe a paired gateway (or use its context menu) to Forget it, which removes its credentials, device tokens, TLS pin, and cached chats.
Discovered gateways must be visible on the network to switch to them; manual gateways reconnect by saved host and port.

Canvas + A2UI

The iOS node renders a WKWebView canvas. Use node.invoke to drive it:

주요 항목:

The Gateway canvas host serves /__openclaw__/canvas/ and /__openclaw__/a2ui/, from the Gateway HTTP server (same port as gateway.port, default 18789).
The iOS node keeps the built-in scaffold as the connected default view. canvas.a2ui.push and canvas.a2ui.reset use the bundled app-owned A2UI page.
Remote Gateway A2UI pages are render-only on iOS; native A2UI button actions are accepted only from bundled app-owned pages.
Return to the built-in scaffold with canvas.navigate and {"url":""}.

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

Computer Use relationship

Canvas eval / snapshot

openclaw 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\"; })()"}'

openclaw 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.
OpenAI realtime Talk uses client-owned WebRTC when talk.realtime.transport is webrtc; an explicit gateway-relay configuration remains Gateway-owned. See Talk mode.
Talk-capable iOS nodes advertise the talk capability and can declare talk.ptt.start, talk.ptt.stop, talk.ptt.cancel, and talk.ptt.once; the Gateway allows those push-to-talk commands by default for trusted Talk-capable nodes.
iOS may suspend background audio; treat voice features as best-effort when the app is not active.

Common errors

주요 항목:

NODE_BACKGROUND_UNAVAILABLE: bring the iOS app to the foreground (canvas/camera/screen commands require it).
A2UI_HOST_UNAVAILABLE: the bundled A2UI page was not reachable in the app WebView; keep the app foregrounded on the Screen tab and retry.
Pairing prompt never appears: run openclaw devices list and approve manually.
Watch shows no iPhone state: confirm the iPhone reports watchPaired: true
Reconnect fails after reinstall: the Keychain pairing token was cleared; re-pair the node.

주요 항목:

Pairing
Discovery
Bonjour

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/ios
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw gateway --port 18789 --tailscale serve

openclaw devices list
openclaw devices approve <requestId>

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

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

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
        },
      },
    },
  },
}

iOS app

핵심 요약

문서 구성

상세 내용

본문

What it does

요구사항

Quick start (pair + connect)

Health summaries

Review command approvals

Answer agent questions

Optional direct Apple Watch node

Relay-backed push for official builds

Background alive beacons

Authentication and trust flow

Discovery paths

Bonjour (LAN)

Tailnet (cross-network)

Manual host/port

Multiple gateways

Canvas + A2UI

Computer Use relationship

Canvas eval / snapshot

Voice wake + talk mode

Common errors

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

iOS app

핵심 요약

문서 구성

상세 내용

본문

What it does

요구사항

Quick start (pair + connect)

Health summaries

Review command approvals

Answer agent questions

Optional direct Apple Watch node

Relay-backed push for official builds

Background alive beacons

Authentication and trust flow

Discovery paths

Bonjour (LAN)

Tailnet (cross-network)

Manual host/port

Multiple gateways

Canvas + A2UI

Computer Use relationship

Canvas eval / snapshot

Voice wake + talk mode

Common errors

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드