<!-- source: https://deepwiki.com/openclaw/openclaw/6.3-ios-and-macos-apps -->

# iOS & macOS Apps

- apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt
- apps/ios/Sources/Design/TalkProTab.swift
- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
- apps/shared/OpenClawKit/Sources/OpenClawProtocol/WakeParamsCompatibility.swift
- docs/gateway/protocol.md
- docs/install/migrating-hermes.md
- extensions/codex/src/migration/auth.ts
- extensions/migrate-hermes/auth-config.ts
- extensions/migrate-hermes/auth.ts
- extensions/migrate-hermes/items.ts
- extensions/migrate-hermes/secrets.test.ts
- extensions/migrate-hermes/secrets.ts
- extensions/migrate-hermes/source.ts
- extensions/openai/realtime-provider-shared.ts
- extensions/openai/realtime-voice-provider.test.ts
- extensions/openai/realtime-voice-provider.ts
- scripts/protocol-gen-swift.ts
- src/agents/model-ref-shared.test.ts
- src/agents/model-ref-shared.ts
- src/cli/system-cli.test.ts
- src/config/config.agent-concurrency-defaults.test.ts
- src/config/cron-limits.ts
- src/config/defaults.test.ts
- src/config/defaults.ts
- src/config/io.write-prepare.test.ts
- src/config/io.write-prepare.ts
- src/config/materialize.ts
- src/config/model-alias-defaults.test.ts
- src/cron/service.ts
- src/cron/service/ops.ts
- src/plugin-sdk/provider-auth.test.ts
- src/plugin-sdk/provider-auth.ts
- src/plugins/provider-auth-choice-helpers.test.ts
- src/plugins/provider-auth-choice-helpers.ts
- src/talk/provider-types.ts

OpenClaw ships native Swift applications for iOS, watchOS, and macOS. These apps connect to the Gateway via WebSocket, expose device capabilities through the `node.invoke` protocol, and provide platform-native UI for chat, voice interaction, and agent management.

The iOS app includes multiple components: the main app, a share extension, a watch companion app, and an activity widget. The macOS app is a lightweight menubar utility integrating chat, agent selection, and gateway control features. Both platforms share common code through `OpenClawKit` and use code-generated Gateway protocol models, configured via XcodeGen.

Additionally, OpenClaw integrates with the Swabble wake-word daemon for voice activation, uses Sparkle for auto-updates on macOS, and supports the A2UI canvas rendering for rich agent-driven UI.

## iOS App Structure

The iOS app comprises four primary targets built using XcodeGen (configured in `apps/ios/project.yml`):

All targets share the common bundle ID prefix `ai.openclaw.ios.*` and are synced in versioning through build settings. The protocol version is synchronized across all clients to ensure compatibility with the Gateway. The current protocol version is 4.
Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift5-6](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L5-L6) [apps/ios/project.yml1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/ios/project.yml#L1-L20)

### Share Extension

The share extension enables OpenClaw to receive shared content from other iOS apps. It bundles shared data and forwards it to the Gateway via the protocol for further processing by the main app.

- Supports shared content types: plain text, URLs, images, and videos.
- Converts shared data into agent requests handled by the node transport.

### Watch App

The watchOS companion app provides a minimal interface for quick agent interactions and status updates, relaying messages bidirectionally between the Apple Watch and iOS device.

### Activity Widget (Live Activities)

The `OpenClawLiveActivity` provides real-time feedback of agent runs and session status directly on the Lock Screen or Dynamic Island. It consumes `EventFrame` updates from the Gateway to refresh its view state.
Sources: [apps/ios/ActivityWidget/OpenClawLiveActivity.swift1-30](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/ios/ActivityWidget/OpenClawLiveActivity.swift#L1-L30)

## macOS App Structure

The macOS app is a lightweight menu bar utility designed for quick agent interaction and Gateway control. It is configured to run without a Dock icon (`LSUIElement`).

### Key Components

## Sparkle Auto-Update (macOS)

OpenClaw leverages the Sparkle framework on macOS to provide seamless app updates with cryptographic verification.

### Update Flow

```

```

## iOS & macOS Architecture

The native apps revolve around WebSocket connections to the Gateway. These connections use the Gateway Protocol v4, with models generated from the TypeScript schema using `scripts/protocol-gen-swift.ts`.

### Architecture Diagram: Code Entity Mapping

This diagram maps the high-level architecture to specific code entities within the Swift and TypeScript codebases.

```

```

The protocol uses `ConnectParams` to define client capabilities and roles (e.g., `role` property).
Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift49-109](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L49-L109) [docs/gateway/protocol.md172-202](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L172-L202) [scripts/protocol-gen-swift.ts1-9](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L1-L9) [apps/ios/Sources/Gateway/GatewayConnectionController.swift1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/ios/Sources/Gateway/GatewayConnectionController.swift#L1-L20) [apps/ios/Sources/Model/NodeAppModel.swift1-50](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/ios/Sources/Model/NodeAppModel.swift#L1-L50)

## Device Pairing & Protocol

Device pairing is anchored in the `operator.pairing` scope, which governs methods like `node.pair.request` and `device.token.rotate`.

### Gateway Protocol Models

The protocol models are shared via code-generated Swift files. Key structures include:

- ConnectParams : Defines the client capabilities, roles, and authentication.
- RequestFrame / ResponseFrame : Standardized RPC containers.
- EventFrame : For asynchronous server-to-client notifications.
- HelloOk : The server response upon successful connection, containing negotiated features and snapshot .
- PresenceEntry : Reports device state, including platform , modelidentifier , and lastinputseconds .

Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift49-251](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L49-L251) [docs/gateway/protocol.md222-231](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L222-L231) [scripts/protocol-gen-swift.ts86-117](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L86-L117)

## Voice & Talk Mode

The iOS app implements a robust voice interaction system through `TalkModeManager` and specialized session types.

- TalkModeManager : Orchestrates the voice lifecycle, handling permissions and session transitions.
- RealtimeTalkRelaySession : Handles audio relaying through the Gateway for backend-only voice providers.
- TalkRealtimeWebRTCSession : Facilitates direct low-latency WebRTC voice sessions (e.g., with OpenAI Realtime).
- Audio Formats : Supports REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ and REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ .

Sources: [apps/ios/Sources/Voice/TalkModeManager.swift1-50](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/ios/Sources/Voice/TalkModeManager.swift#L1-L50) [apps/ios/Sources/Voice/RealtimeTalkRelaySession.swift1-40](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/ios/Sources/Voice/RealtimeTalkRelaySession.swift#L1-L40) [apps/ios/Sources/Voice/TalkRealtimeWebRTCSession.swift1-40](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/ios/Sources/Voice/TalkRealtimeWebRTCSession.swift#L1-L40) [extensions/openai/realtime-voice-provider.ts25-28](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/realtime-voice-provider.ts#L25-L28)

## A2UI Canvas Rendering

The apps visualize rich agent-driven UI components via the A2UI canvas.

### Implementation Details

- Integration : The Gateway provides scoped plugin surface URLs in the HelloOk frame. Nodes can refresh these via node.pluginSurface.refresh for the canvas surface.
- Rendering : The native app hosts a web view that renders the A2UI components provided by the Gateway's canvas plugin.

```

```

Sources: [docs/gateway/protocol.md108-117](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L108-L117) [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift111-151](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L111-L151)

## Swabble Wake-Word Daemon Integration

OpenClaw integrates with the Swabble wake-word daemon for voice activation.

### Integration Details

- RPC Interface : The app manages wake-word settings via specific RPC methods.
- Status Reporting : The node reports presence and wake status via PresenceEntry , using NodePresenceAliveReason to indicate triggers like manual , bg_app_refresh , or significant_location .

Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift40-47](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L40-L47) [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift239-256](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L239-L256)

## Sources

- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 1-256
- docs/gateway/protocol.md 1-210
- scripts/protocol-gen-swift.ts 1-223
- apps/ios/Sources/Gateway/GatewayConnectionController.swift 1-20
- apps/ios/Sources/Voice/TalkModeManager.swift 1-50
- apps/ios/ActivityWidget/OpenClawLiveActivity.swift 1-30
- apps/ios/Sources/Model/NodeAppModel.swift 1-50
- apps/ios/Sources/Voice/RealtimeTalkRelaySession.swift 1-40
- apps/ios/Sources/Voice/TalkRealtimeWebRTCSession.swift 1-40
- extensions/openai/realtime-voice-provider.ts 1-240
- apps/ios/project.yml 1-20
