<!-- source: https://deepwiki.com/openclaw/openclaw/1.3-platform-architecture -->

# Platform Architecture

- 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
- docs/plugins/plugin-inventory.md
- docs/plugins/reference.md
- extensions/tsconfig.package-boundary.paths.json
- extensions/xai/tsconfig.json
- scripts/check-plugin-sdk-exports.mjs
- scripts/lib/bundled-plugin-build-entries.mjs
- scripts/lib/extension-package-boundary.ts
- scripts/lib/plugin-sdk-entries.d.mts
- scripts/lib/plugin-sdk-entries.mjs
- scripts/prepare-extension-package-boundary-artifacts.mjs
- scripts/protocol-gen-swift.ts
- scripts/release-check.ts
- scripts/run-node-watch-paths.mjs
- scripts/watch-node.mjs
- scripts/write-plugin-sdk-entry-dts.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/infra/tsdown-config.test.ts
- src/infra/watch-node.test.ts
- src/plugins/plugin-sdk-native-resolver.test.ts
- src/plugins/plugin-sdk-native-resolver.ts
- src/plugins/provider-auth-choice-helpers.test.ts
- src/plugins/provider-auth-choice-helpers.ts
- src/plugins/sdk-alias.test.ts
- src/plugins/sdk-alias.ts
- test/release-check.test.ts
- test/scripts/bundled-plugin-build-entries.test.ts
- test/scripts/prepare-extension-package-boundary-artifacts.test.ts
- test/scripts/watch-node.test.ts
- test/vitest/vitest.shared.config.ts
- tsconfig.json
- tsdown.config.ts

## Purpose and Scope

This document provides a high-level architectural overview of OpenClaw, explaining how the major subsystems interact to deliver a self-hosted multi-platform AI gateway. It covers the core Node.js gateway, native clients (iOS/Android/macOS), Docker-based sandboxing, and the cross-platform build system.

OpenClaw is designed as a **hub-and-spoke** system where the central Gateway coordinates agent execution, messaging channels, and native device nodes.

## Architectural Overview

The architecture is centered around the **Gateway Control Plane**, which manages state, routing, and communication between various clients and the agent runtime.

### System Components Diagram

The following diagram maps high-level system components to their corresponding entities in the codebase.

```

```

**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/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt182-188](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt#L182-L188) [scripts/protocol-gen-swift.ts26-36](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L26-L36)

## Core Platform Subsystems

### 1. Gateway Control Plane

The Gateway is a WebSocket-based RPC server. It serves as the single source of truth for sessions and configuration. It manages the lifecycle of the AI assistant, including automated updates and service health.

- Protocol Versioning: The gateway currently uses Protocol v4 apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 5-6
- RPC Framing: Communication is handled via standardized RequestFrame apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 153-177 ResponseFrame apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 179-207 and EventFrame apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 209-237
- Presence & Heartbeats: Nodes report status using PresenceEntry , tracking metadata like platform , devicefamily , and lastinputseconds apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 239-256
- Error Handling: A centralized ErrorCode enum defines platform-wide error states such as AGENT_TIMEOUT and NOT_PAIRED apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 23-30

**Sources:** [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift5-256](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L5-L256) [docs/gateway/protocol.md15-26](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/protocol.md?plain=1#L15-L26)

### 2. Shared Packages Layer ( packages/ )

OpenClaw utilizes a monorepo structure where core logic is extracted into shared TypeScript packages.

- gateway-protocol: Defines the source-of-truth schemas using TypeBox scripts/protocol-gen-swift.ts 8-9
- sdk: The @openclaw/sdk provides a programmatic interface for external integrations to interact with the Gateway.
- llm-core & agent-core: Contain the foundational logic for model interaction and agent execution cycles.
- terminal-core: Manages TTY and shell execution logic used by both the Gateway and sandboxed environments.

### 3. Native Clients (iOS / macOS / Android)

OpenClaw provides native applications that act as **Device Nodes**. These nodes connect to the gateway to provide hardware-level capabilities to the AI agents.

- Android Runtime: The Android app implements a NodeRuntime apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 78-82 that coordinates hardware handlers including CameraHandler apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 110-118 LocationHandler apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 126-133 and SmsHandler apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 177-180
- Voice Integration: Real-time voice interaction is managed by TalkModeManager apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeManager.kt 90-100 It handles audio capture and playback synchronization, including PTT (Push-To-Talk) payloads apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeManager.kt 56-75
- UI State: The Android client uses MainViewModel to expose gateway and node states (e.g., isConnected , isNodeConnected , statusText ) to the Jetpack Compose UI apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt 82-94
- A2UI Canvas: Native clients support the A2UI standard for rich UI rendering, managed by A2UIHandler which links the native CanvasController to the gateway's canvas host URLs apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt 182-188

**Sources:** [apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt78-188](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt#L78-L188) [apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeManager.kt56-100](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/android/app/src/main/java/ai/openclaw/app/voice/TalkModeManager.kt#L56-L100) [apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt82-118](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt#L82-L118)

## Build and Release System

OpenClaw uses a multi-platform build system to target Node.js, native mobile, and desktop environments.

### Build Tooling

- tsdown: Used for bundling the Node.js core and shared packages. It handles environment variable injection and source map generation tsdown.config.ts 37-41
- Native Code Generation: The scripts/protocol-gen-swift.ts script automatically generates Swift models from the TypeScript protocol schema defined in packages/gateway-protocol , ensuring the iOS/macOS clients stay in sync with the Gateway scripts/protocol-gen-swift.ts 1-9
- SDK Aliasing: The system includes sophisticated logic to resolve the plugin-sdk during development and production, allowing plugins to consume shared logic seamlessly src/plugins/sdk-alias.ts 14-29

### Asset Bundling

- Bundled Assets: Assets for extensions, such as Chrome extension components, are managed within the extensions/ directory and bundled during the release process tsdown.config.ts 157-162
- Artifact Inventory: The release process validates that all required artifacts (e.g., npm-shrinkwrap.json , dist/index.js , plugin-sdk files) are present in the final package scripts/release-check.ts 72-101

**Sources:** [tsdown.config.ts1-162](https://github.com/openclaw/openclaw/blob/fbdf5937/tsdown.config.ts#L1-L162) [scripts/protocol-gen-swift.ts1-36](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L1-L36) [src/plugins/sdk-alias.ts14-29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/sdk-alias.ts#L14-L29) [scripts/release-check.ts72-101](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-check.ts#L72-L101)

## Data Flow: Native Node Invocation

When an agent needs to access device hardware, the request flows through the Gateway's RPC layer to the native client.

```

```

**Key Implementation Details:**

- Serialization: All platforms use the same GatewayModels schema to ensure binary-compatible JSON serialization apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 1-10
- Asynchronous Flow: Requests are tracked by id apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 155 in the RequestFrame , allowing for non-blocking hardware operations.

**Sources:** [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift1-179](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L1-L179) [apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt110-118](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt#L110-L118)
