<!-- source: https://deepwiki.com/openclaw/openclaw/2.1-websocket-protocol-and-rpc -->

# WebSocket Protocol & RPC

- 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/automation/hooks.md
- docs/gateway/protocol.md
- docs/reference/AGENTS.default.md
- docs/reference/templates/AGENTS.md
- packages/sdk/src/client.ts
- packages/sdk/src/index.test.ts
- packages/sdk/src/normalize.ts
- scripts/protocol-gen-swift.ts
- skills/model-usage/SKILL.md
- src/agents/agent-run-terminal-outcome.test.ts
- src/agents/agent-run-terminal-outcome.ts
- src/agents/model-ref-shared.test.ts
- src/agents/model-ref-shared.ts
- src/agents/run-wait.test.ts
- src/agents/run-wait.ts
- src/cli/gateway-cli/lifecycle.runtime.ts
- src/cli/gateway-cli/run-loop.test.ts
- src/cli/gateway-cli/run-loop.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/gateway/method-scopes.test.ts
- src/gateway/method-scopes.ts
- src/gateway/methods/core-descriptors.ts
- src/gateway/methods/descriptor.ts
- src/gateway/methods/registry.test.ts
- src/gateway/methods/registry.ts
- src/gateway/server-close.test.ts
- src/gateway/server-close.ts
- src/gateway/server-methods-list.test.ts
- src/gateway/server-methods-list.ts
- src/gateway/server-methods.ts
- src/gateway/server-methods/agent-job.ts
- src/gateway/server-methods/agent-wait-dedupe.test.ts
- src/gateway/server-methods/agent-wait-dedupe.ts
- src/gateway/server-methods/models-auth-status.test.ts
- src/gateway/server-methods/models-auth-status.ts
- src/gateway/server-methods/server-methods.test.ts
- src/gateway/server-reload-handlers.test.ts
- src/gateway/server-reload-handlers.ts
- src/gateway/server-startup-post-attach.test.ts
- src/gateway/server-startup-post-attach.ts
- src/gateway/server.impl.ts
- src/gateway/session-lifecycle-state.test.ts
- src/gateway/session-lifecycle-state.ts
- src/infra/agent-events.test.ts
- src/infra/agent-events.ts
- src/infra/infra-runtime.test.ts
- src/infra/restart.deferral-timeout.test.ts
- src/infra/restart.ts
- src/plugins/provider-auth-choice-helpers.test.ts
- src/plugins/provider-auth-choice-helpers.ts

The Gateway WebSocket protocol defines how clients communicate with the Gateway server using a JSON-based RPC (Remote Procedure Call) system. This page documents protocol version 4, including frame structures, the 30+ RPC methods available, and the authorization system with Swift code generation.

## Protocol Architecture

The Gateway protocol is a bidirectional WebSocket protocol with four core message types: connect frames (client handshake), request frames (client->server), response frames (server->client), and event frames (server->client push notifications). All messages are JSON-encoded and validated against schemas defined using TypeBox.

### System Architecture & Code Entities

The following diagram bridges the protocol concepts to the specific code entities implementing them, highlighting the flow from WebSocket message handling to method dispatch.

Title: Gateway Protocol Implementation Map

```

```

Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift5-207](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L5-L207) [src/gateway/methods/registry.ts63-70](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/registry.ts#L63-L70) [src/gateway/server.impl.ts60-70](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L60-L70) [src/gateway/methods/core-descriptors.ts60-67](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/core-descriptors.ts#L60-L67) [packages/sdk/src/client.ts1-50](https://github.com/openclaw/openclaw/blob/fbdf5937/packages/sdk/src/client.ts#L1-L50)

## Frame Types

The protocol defines four core frame types used for communication. All frames are validated against the schema source of truth via TypeBox, which is then used to generate Swift models [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift1](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L1-L1)

### ConnectParams (Handshake)

The initial message sent by a client immediately after establishing the WebSocket connection. It includes protocol version negotiation and authentication [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift49-109](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L49-L109)

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)

### RequestFrame (RPC Call)

Used by clients to invoke server-side methods. It includes a unique `id` for correlation and a `method` name [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift153-177](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L153-L177)

```

```

Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift153-177](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L153-L177)

### ResponseFrame (RPC Result)

The server's response to a `RequestFrame`, correlated by the `id`. It indicates success via the `ok` boolean [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift179-207](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L179-L207)

```

```

Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift179-207](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L179-L207)

### EventFrame (Server Push)

Server-initiated messages for streaming or status updates. Optional `seq` and `stateVersion` fields assist with synchronization [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift209-237](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L209-L237)

```

```

Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift209-237](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L209-L237)

## RPC Methods & Implementation

The Gateway exposes over 30 RPC methods. Core methods are registered via `createCoreGatewayMethodDescriptors` [src/gateway/methods/registry.ts63](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/registry.ts#L63-L63)

### Core Method Handlers

Methods are organized into functional groups such as agent interaction, chat management, and session control [src/gateway/server-methods-list.ts1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods-list.ts#L1-L20)

- Agent Interaction : agent.send and agent.wait handle message ingestion and long-polling for terminal responses src/agents/run-wait.ts 202-219 waitForAgentJob manages the lifecycle of these requests, mapping lifecycle end events to terminal statuses src/gateway/server-methods/agent-job.ts 27-111
- Chat Management : chat.send and chat.history provide high-level chat abstractions src/gateway/server-methods/server-methods.test.ts 25-37
- Presence & Health : server.health and presence versioning provide visibility into system state src/gateway/server.impl.ts 101-107

### Steering Queue & Delivery

For active-run message delivery, the Gateway manages an internal steering queue and event handling system.

- Deduplication : Idempotency is managed for agent operations to prevent duplicate execution on retry via setGatewayDedupeEntry src/gateway/server-methods/agent-wait-dedupe.ts 20
- Presence : PresenceEntry returns entries keyed by device identity for UI visibility, including versioning via presenceVersion apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 239-256 src/gateway/server.impl.ts 104-105
- Safe Restart & Draining : The Gateway can defer restarts if active work is in progress. The runGatewayLoop uses waitForActiveTasks and waitForActiveEmbeddedRuns to ensure a clean handoff or shutdown src/cli/gateway-cli/run-loop.ts 124-180 It specifically checks getActiveEmbeddedRunCount to avoid interrupting LLM interactions src/gateway/server.impl.ts 3

Sources: [src/gateway/server.impl.ts2-106](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L2-L106) [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift239-256](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L239-L256) [src/agents/run-wait.ts195-227](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/run-wait.ts#L195-L227) [src/cli/gateway-cli/run-loop.ts124-180](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/gateway-cli/run-loop.ts#L124-L180)

## TypeBox & Schema Validation

TypeBox serves as the source of truth for the protocol. Every inbound request is validated against these schemas before dispatching to the appropriate handler [scripts/protocol-gen-swift.ts8-9](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L8-L9)

Title: Schema Validation and Code Generation Flow

```

```

Sources: [scripts/protocol-gen-swift.ts1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L1-L10) [src/gateway/methods/registry.ts60-70](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/registry.ts#L60-L70) [src/gateway/server.impl.ts60-70](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L60-L70)

## Swift Code Generation

To maintain parity between the TypeScript Gateway and native clients (iOS/macOS), TypeBox schemas are used to generate Swift models [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift1](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L1-L1)

- Generation Script : scripts/protocol-gen-swift.ts iterates over ProtocolSchemas to produce native Swift types scripts/protocol-gen-swift.ts 1-40 It handles mapping TypeScript types to Swift struct and enum declarations, including special handling for optional parameters in initializers scripts/protocol-gen-swift.ts 43-81
- Protocol Parity : Both Swift and TypeScript define GATEWAY_PROTOCOL_VERSION = 4 apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 5
- Native Types : Generates struct and enum types with Codable and Sendable conformance for thread-safe native use apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift 23-237

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-186](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/protocol-gen-swift.ts#L1-L186)

## Error Handling

Errors are returned in a standard format using `ErrorCode` enums, providing clear failure reasons for the client [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift23-30](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L23-L30)

Sources: [apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift23-30](https://github.com/openclaw/openclaw/blob/fbdf5937/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift#L23-L30)
