<!-- source: https://deepwiki.com/openclaw/openclaw/6.1-platform-overview -->

# Platform Overview

- apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt
- apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
- apps/shared/OpenClawKit/Sources/OpenClawProtocol/WakeParamsCompatibility.swift
- docs/gateway/protocol.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

## Purpose and Scope

This page provides a detailed technical explanation of OpenClaw's native client architecture, covering the iOS, macOS, and Android platforms. It explains how the platform-native codebases (Swift for Apple platforms and Kotlin for Android) interact with the Gateway server via a robust, versioned WebSocket RPC protocol. It also describes the automated code generation process that derives native data model classes and protocol structures directly from TypeScript protocol schemas.

For more platform-centric details, see the linked pages: [Device Node Protocol (6.2)](https://github.com/openclaw/openclaw/blob/fbdf5937/Device Node Protocol (6.2)) [iOS & macOS Apps (6.3)](https://github.com/openclaw/openclaw/blob/fbdf5937/iOS & macOS Apps (6.3)) and [Android App (6.4)](https://github.com/openclaw/openclaw/blob/fbdf5937/Android App (6.4))

## Multi-Platform Architecture

OpenClaw supports native client applications for three major platforms:

- iOS/iPadOS/watchOS : Built with Swift using SwiftUI. The codebase includes main apps, share extensions, Live Activities widgets, and watchOS companion apps.
- macOS : A lightweight Swift-based menu bar app focused on background operations and system automation.
- Android : Written in Kotlin using Jetpack Compose UI toolkit. The Android app features a central NodeRuntime that orchestrates platform handlers (Camera, Location, SMS, etc.) and manages the GatewaySession lifecycle.

All native clients communicate with the OpenClaw Gateway server via a standardized protocol called **Gateway Protocol v4** [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift5-6](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L5-L6) This protocol operates over a WebSocket connection using JSON-encoded RPC frames [docs/gateway/protocol.md15-18](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L15-L18) Its schemas and RPC method specifications are authored in TypeScript and code-generated into native Swift types to ensure strong typing and version consistency [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift1-3](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L1-L3)

### Architecture Diagram: Platform Codebases & Gateway Communication

```

```

**Sources:**
[apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift1-6](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L1-L6) [scripts/protocol-gen-swift.ts1-9](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L1-L9) [docs/gateway/protocol.md10-15](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L10-L15)

## Gateway Protocol Code Generation

OpenClaw's Gateway protocol is specified in TypeScript schemas. The **Swift** code for clients is automatically generated by `scripts/protocol-gen-swift.ts`. This script translates TypeScript/JSON schema definitions into Swift `struct`s that conform to `Codable` and `Sendable` [scripts/protocol-gen-swift.ts185-212](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L185-L212)

The generated Swift code includes core protocol frames like `ConnectParams`, `HelloOk`, `RequestFrame`, `ResponseFrame`, and `EventFrame` [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift49-237](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L49-L237) It also includes enumerations such as `ErrorCode` for protocol error reasons (e.g., `NOT_LINKED`, `AGENT_TIMEOUT`, `INVALID_REQUEST`) [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift23-30](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L23-L30)

### Key Protocol Frame Structures

**Sources:**
[apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift1-237](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L1-L237) [scripts/protocol-gen-swift.ts1-176](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L1-L176)

## Native Client to Gateway Data Flow

### Connection and Handshake

The connection lifecycle involves a specific handshake sequence [docs/gateway/protocol.md27-28](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L27-L28):

1. Challenge : Gateway sends a connect.challenge event with a nonce docs/gateway/protocol.md 29-37
2. Connect Request : The client sends a connect request containing ConnectParams including protocol versions, client metadata, and auth credentials docs/gateway/protocol.md 39-72
3. Response : The Gateway responds with HelloOk , which provides server features, policy limits (e.g., maxPayload ), and negotiated auth scopes docs/gateway/protocol.md 74-98

### RPC and Event Handling

Clients use `RequestFrame` to invoke server methods and listen for `EventFrame` for real-time updates [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift153-237](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L153-L237)

- Framing : All communication follows a standard JSON framing: {type, id, method, params} for requests and {type, id, ok, payload|error} for responses docs/gateway/protocol.md 215-220
- Streaming : The Gateway supports streaming responses, particularly for AI completions via v1/chat/completions which can be consumed by native clients as WebSocket event frames docs/gateway/protocol.md 219-220

### Message Flow Entity Map

```

```

### Roles and Scopes

Gateway connections are defined by roles and authorized by scopes.

- Roles : operator for control plane clients and node for capability hosts (e.g., camera/screen) docs/gateway/protocol.md 228-232
- Scopes : Scopes determined during handshake (e.g., operator.read , operator.write , operator.admin ) determine which RPC methods are available to the client docs/gateway/protocol.md 233-240

**Sources:**
[apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift49-151](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L49-L151) [docs/gateway/protocol.md9-105](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L9-L105)
