Core Protocol

1. Introduction

The OpenClaw Core Protocol defines the communication between four participants: Device (Nexting PIN), Client (iPhone app), Gateway (plugin server), and AI Service. It covers BLE audio transport, WebSocket messaging, HTTP fallback, session lifecycle, and gateway RPC.

Version 0.2.0, July 2026.

Design Philosophy

2. Architecture

The protocol spans four layers connected by three distinct transports:

Device (Nexting PIN)  ─── BLE ───  Client (iPhone App)  ─── WebSocket/HTTP ───  Gateway (Plugin Server)  ─── RPC ───  AI Service

3. Data Types

4. Transport: BLE

BLE is the link between the Nexting PIN and the iPhone app. The device exposes a main GATT service with five characteristics, plus separate button, storage, and DFU services.

BLE Service

Nexting service UUID: 12345678-1234-1234-1234-123456789ABC

The device additionally exposes separate button, storage, and DFU (firmware update) services.

MTU: negotiated (firmware supports up to a 498-byte L2CAP payload; minimum 100 bytes required).

Packet Format

START

[0x01][codec:1B][totalSize/reserved:4B BE] — Announces a new audio recording. Codec 0x14 (Opus) carries 4 reserved zero bytes; codec 0x03 (ADPCM) carries totalSize (total expected bytes of the encoded audio); legacy codec 0x01 (AAC) omits the codec byte.

DATA

[0x02][seqNo:2B BE][payload ≤320B] — Sequential audio chunks. seqNo is used for ordering and gap detection.

END

[0x03][totalFrames:4B BE] — End of recording. Frame count for Opus; legacy AAC/ADPCM send a CRC32 checksum instead.

HEARTBEAT

[0x04][counter:2B BE][flags:1B][battMv:2B BE] — Periodic keepalive. counter increments each heartbeat; flags bit0 = recording active, bit1 = charging; battMv is the battery voltage in millivolts.

┌──────────────────────────────────────────────────────────────┐
│ START   │ 0x01 │ codec (1B) │ totalSize/reserved (4B BE)    │
├──────────────────────────────────────────────────────────────┤
│ DATA    │ 0x02 │ seqNo (2B BE) │ payload (up to 320 bytes)  │
├──────────────────────────────────────────────────────────────┤
│ END     │ 0x03 │ totalFrames (4B BE)                        │
├──────────────────────────────────────────────────────────────┤
│ HEARTBT │ 0x04 │ counter (2B BE) │ flags (1B) │ battMv (2B)│
└──────────────────────────────────────────────────────────────┘

(Legacy AAC/ADPCM only) CRC32 algorithm: Standard CRC32 (polynomial 0xEDB88320), computed over the fully assembled audio data.

5. Transport: WebSocket

Connection States

disconnected → connecting → authenticating → connected ↔ reconnecting

The client MUST send an auth message within 10 seconds of connection. The gateway MUST respond with auth_ok or close with code 4001.

6. Message Types

All messages are JSON-encoded and transmitted over WebSocket.

Inbound (Client → Gateway)

auth

Authenticates the client. MUST be the first message sent.

{ "type": "auth", "deviceId": "string", "token": "string" }

text

Sends user input (typically STT output) to the gateway.

{ "type": "text", "content": "string" }

ping

Client-initiated keepalive.

{ "type": "ping" }

Outbound (Gateway → Client)

auth_ok

Confirms successful authentication.

{ "type": "auth_ok", "deviceId": "string" }

agent_message

AI response delivered to the client.

{
  "type": "agent_message",
  "content": "string",
  "proactive": true | false,
  "requestId": "string?"
}

error

Reports a gateway or AI error.

{ "type": "error", "message": "string" }

pong

Response to client ping.

{ "type": "pong" }

7. HTTP Fallback

Used when WebSocket is disconnected (e.g., app woken from background by BLE). The client SHOULD prefer WebSocket but MUST support HTTP fallback.

POST /message

Send user text, get AI response synchronously.

Request:  { "token": "string", "deviceId": "string", "content": "string" }
Response: { "content": "string" }

POST /push

Proactive push from agent.

Request:  { "token": "string", "deviceId": "string", "text": "string" }
Response: { "ok": true, "deviceId": "string" }

GET /health

Health check endpoint.

Response: { "ok": true, "devices": 1, "gateway": true }

8. Session Lifecycle

BLE State Machine

idle → scanning → connecting → discovering → ready → disconnected (auto-reconnect)

WebSocket State Machine

disconnected → connecting → authenticating → connected ↔ reconnecting

Voice Pipeline State Machine

idle → receivingAudio → transcribing → thinking → done / error

9. Audio Pipeline

End-to-end voice flow from button press to spoken response:

10. Gateway RPC

The gateway communicates with the AI service via JSON-RPC over WebSocket, authenticated with Ed25519 signatures.

Device Identity

chat.send RPC

{
  "type": "req",
  "id": "uuid",
  "method": "chat.send",
  "params": {
    "sessionKey": "main",
    "message": "string",
    "idempotencyKey": "uuid"
  }
}

Response Events (Streaming)

The gateway receives streaming events. A delta event carries partial content; final signals completion.

{ "type": "event", "event": "chat", "payload": { "state": "delta", "message": { ... } } }

{ "type": "event", "event": "chat", "payload": { "state": "final", "message": { ... } } }

11. Pending Queue

The plugin itself has no pending queue. The offline queue lives in Nexting Cloud as a Postgres offline_queue table: when the plugin is unreachable, the cloud relay queues outbound messages and drains them when the plugin reconnects.

12. Security

13. Conformance

M = Mandatory, O = Optional, - = Not applicable.