<!-- source: https://deepwiki.com/openclaw/openclaw/6-native-clients-and-nodes -->

# Native Clients & Nodes

- apps/android/app/src/debug/AndroidManifest.xml
- apps/android/app/src/debug/java/ai/openclaw/app/VoiceE2eReceiver.kt
- apps/android/app/src/main/java/ai/openclaw/app/AssistantLaunch.kt
- apps/android/app/src/main/java/ai/openclaw/app/MainActivity.kt
- apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt
- apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt
- apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayHostSecurity.kt
- apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt
- apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt
- apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayTls.kt
- apps/android/app/src/main/java/ai/openclaw/app/node/ConnectionManager.kt
- apps/android/app/src/main/java/ai/openclaw/app/ui/ConnectTabScreen.kt
- apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt
- apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayDiagnostics.kt
- apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayPairingRetry.kt
- apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt
- apps/android/app/src/main/java/ai/openclaw/app/ui/VoiceTabScreen.kt
- apps/android/app/src/main/java/ai/openclaw/app/voice/MicCaptureManager.kt
- apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeGatewayConfig.kt
- apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeManager.kt
- apps/android/app/src/test/java/ai/openclaw/app/GatewayBootstrapAuthTest.kt
- apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionInvokeTest.kt
- apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionReconnectTest.kt
- apps/android/app/src/test/java/ai/openclaw/app/node/ConnectionManagerTest.kt
- apps/android/app/src/test/java/ai/openclaw/app/ui/GatewayConfigResolverTest.kt
- apps/android/app/src/test/java/ai/openclaw/app/ui/OnboardingFlowLogicTest.kt
- apps/android/app/src/test/java/ai/openclaw/app/voice/MicCaptureManagerTest.kt
- apps/android/app/src/test/java/ai/openclaw/app/voice/TalkModeConfigParsingTest.kt
- apps/android/app/src/test/java/ai/openclaw/app/voice/TalkModeManagerTest.kt
- apps/android/scripts/voice-e2e.sh
- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
- apps/shared/OpenClawKit/Sources/OpenClawProtocol/WakeParamsCompatibility.swift
- docs/gateway/protocol.md
- docs/platforms/android.md
- 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/plugins/provider-auth-choice-helpers.test.ts
- src/plugins/provider-auth-choice-helpers.ts

This document provides a high-level introduction to OpenClaw's native client applications for iOS, macOS, and Android. These apps serve as both **Gateway clients** connecting to the Gateway server via WebSocket, and **Device Nodes** that expose rich, platform-specific device capabilities to the agent runtime. Integration with the agent runtime occurs through the `node.invoke` RPC method, enabling agents to control native features like camera, screen capture, notifications, and location on the device.

For the Gateway WebSocket protocol and RPC methods, see [WebSocket Protocol & RPC](/openclaw/openclaw/2.1-websocket-protocol-and-rpc). For the web-based Control UI dashboard, see [Gateway](/openclaw/openclaw/2-gateway).

## Overview

OpenClaw's native clients differ from CLI clients and web Control UI in three key ways:

1. Platform Integration: Native clients access platform-specific APIs that are not available to Node.js or browser clients, such as: Android's CameraX, Location, and SMS/Call Log APIs apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 141-146 iOS's AVFoundation, CoreLocation, and UserNotifications. macOS ScreenCaptureKit, AppleScript automation, and menubar integrations.
2. Device Node Protocol: Native clients register with the Gateway as device nodes , providing device identity and capabilities. They handle node.invoke RPC calls routed from the Gateway, which allows agents to invoke native tools like camera.snap , screen.record , and location.get docs/gateway/protocol.md 196-199 The node.invoke method requires appropriate authorization on the Gateway docs/gateway/protocol.md 231-236
3. Native UI: They provide rich, platform-native user experiences-SwiftUI on iOS/macOS, Jetpack Compose on Android-supporting OS-level features such as share extensions, widgets, background daemons, and auto-update mechanisms.

Behind the scenes, all clients share a code-generated protocol layer based on Gateway TypeScript schemas to guarantee type safety and protocol consistency [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift1-5](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L1-L5)

Sources:

- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 1-5
- docs/gateway/protocol.md 196-199
- docs/gateway/protocol.md 231-236
- apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 141-146

## Multi-Platform Architecture

OpenClaw's native client architecture bridges high-level agent requests to native platform implementations using a consistent RPC dispatching pattern. This architecture enables seamless integration of the Gateway, native clients, and platform-specific handlers.

### System Mapping: Logic to Code Entities

```

```

Summary:

- The Gateway accepts connections from native clients identified as device nodes ( role: 'node' ) docs/gateway/protocol.md 194-197
- It routes node.invoke RPC calls through server-side handlers to the connected native client.
- Native client runtimes (Swift, Kotlin) parse the protocol using code-generated models and dispatch calls to platform-specific handlers that implement tools like camera, location, and notifications apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 116-194

For detailed architecture and client codebases, see [Platform Overview](/openclaw/openclaw/6.1-platform-overview).

Sources:

- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 1-92
- docs/gateway/protocol.md 10-13
- apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 116-194
- apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt 29-32

## Device Node Protocol

Native clients connect to the Gateway with device-specific metadata in the `ConnectParams` payload, registering as device nodes to receive commands [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift49-62](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L49-L62) The Gateway maintains a dynamic registry of **paired nodes**, enabling secure RPC dispatch to the correct native client.

### Protocol Flow: Request to Native Execution

```

```

The device pairing process establishes mutual trust between the Gateway and native nodes using cryptographic tokens. Device tokens are rotated periodically to maintain secure authorization scopes [docs/gateway/protocol.md138-148](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L138-L148) The Android client manages tokens via `DeviceAuthStore` and `DeviceIdentityStore` [apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt97-112](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt#L97-L112)

Detailed node-specific tools include native APIs for camera, location, SMS, notifications, and system information. Command policy enforcement ensures only authorized RPCs are executed.

For comprehensive protocol details, pairing system, native node tooling, and command policy documentation, see [Device Node Protocol](/openclaw/openclaw/6.2-device-node-protocol).

Sources:

- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 49-62
- docs/gateway/protocol.md 138-148
- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 153-207
- apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 97-112

## iOS & macOS Ecosystem

The iOS and macOS clients share common code and patterns via `OpenClawKit`, providing deep integration into native platform frameworks.

### iOS App Structure

The iOS app combines multiple components for flexibility:

- Main App: Primary interface with chat, voice, and device node management features.
- Extensions: Share extension for quick content sharing, Activity widget for glanceable info, and Watch app for Apple Watch integration.

### macOS App Structure

The macOS menubar app integrates tightly with system services:

- Daemon Management: Uses launchd for managing service lifecycle-installing, restarting, and status checking the node process.
- Canvas Rendering: Implements the A2UI open standard canvas rendering for rich UI surfaces using plugin surface URLs docs/gateway/protocol.md 108-111
- Auto-Update: Supports Sparkle framework for secure background updates.
- Wake-word Daemon: Integrates with Swabble for voice wake trigger support.

For detailed iOS/macOS architecture, build process, and platform capabilities, see [iOS & macOS Apps](/openclaw/openclaw/6.3-ios-and-macos-apps).

Sources:

- docs/gateway/protocol.md 108-111
- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 239-256

## Android Ecosystem

The Android native client is implemented in Kotlin, emphasizing modern Android development practices and rich native capabilities.

### Build System and UI

- Gradle Build: Official Android build system with multi-ABI support and signing configurations.
- Jetpack Compose: Fully declarative UI framework providing Material 3 components and smooth UI state management apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt 29-32

### Native Capabilities

- Hardware and System Integration: Managers for camera ( CameraCaptureManager ), location ( LocationCaptureManager ), SMS ( SmsManager ), and mic handle direct platform APIs and permission requests apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 99-102
- Voice Interaction: TalkModeManager supports real-time voice capture and synthesis, TTS and ASR, with server relay fallback apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeManager.kt 96-106
- Node Presence & Alive Reasons: The client reports presence reasons such as background app refresh and manual activation using standardized reason codes apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 40-47

For detailed Android client internals, UI, and build configuration, see [Android App](/openclaw/openclaw/6.4-android-app).

Sources:

- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 40-47
- apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 99-102
- apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeManager.kt 96-106

## Summary

OpenClaw's native clients function as the essential bridge connecting the Gateway and agent runtime to the native device capabilities:

- They implement a type-safe protocol layer with code-generated Swift and Kotlin models ensuring consistency apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 1-5
- They support a secure device node protocol , enabling the Gateway to route RPCs to native tools exposing hardware and OS features over WebSocket.
- They provide rich native user experiences using SwiftUI (iOS/macOS) and Jetpack Compose (Android), built with attention to platform specifics like extensions, widgets, menubar apps, and voice daemons.

For thorough technical documentation on the native client architecture, detailed device node protocol, and platform-specific apps, consult the child pages:

- Platform Overview
- Device Node Protocol
- iOS & macOS Apps
- Android App

Sources:

- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 1-5
