文档SDK

协议

核心协议

Nexting 开发者文档 | 2026 年 8 月

1. 简介

OpenClaw 核心协议定义了四个参与方之间的通信方式：设备（Nexting 夹子）、客户端（iPhone 应用）、网关（插件服务器）和 AI 服务。协议涵盖 BLE 音频传输、WebSocket 消息、HTTP 回退、会话生命周期以及网关 RPC。

版本 0.2.0，2026 年 7 月。

设计理念

原则描述
语音优先所有交互均针对语音输入/输出进行优化。
离线可用待发队列与 HTTP 回退机制确保消息在断连期间不会丢失。
默认隐私STT 通过 Nexting Cloud Whisper 代理运行；当云端不可达时，回退到设备端 Apple Speech 识别。
传输无关核心消息语义独立于 BLE、WebSocket 或 HTTP。
本文档中的关键词 MUST、MUST NOT、 REQUIRED、SHALL、 SHALL NOT、SHOULD、 SHOULD NOT、RECOMMENDED、 MAY 和 OPTIONAL 的含义遵循 RFC 2119 的定义。

2. 架构

协议横跨四个层级，通过三种不同的传输方式连接：

Architecture Overview
Device (Nexting PIN)  ─── BLE ───  Client (iPhone App)  ─── WebSocket/HTTP ───  Gateway (Plugin Server)  ─── RPC ───  AI Service
在生产环境中，iPhone 应用通过 Nexting Cloud 中继连接（wss://api.nexting.ai/ws）。本文档描述的本地协议运行在云端中继客户端与 18790 端口上的插件服务器之间。
层级职责
设备通过 PDM 麦克风采集音频，编码并发送 BLE 数据包，发送心跳。
客户端组装 BLE 音频数据，运行 STT（云端 Whisper 代理，设备端 Apple Speech 兜底）/TTS，管理 WebSocket 连接和 HTTP 回退。
网关接受客户端连接，通过 RPC 将消息路由至 AI。
AI 服务处理自然语言，返回智能体响应（文本）。

3. 数据类型

类型格式示例
DeviceIdstring"iphone-Eric's iPhone", "pin-001"
Tokenstring用于认证的 Bearer 令牌
TimestampnumberUnix 毫秒时间戳（Date.now()）
MessageIdstring (UUID v4)crypto.randomUUID()
AudioCodecuint80x01=AAC（旧版）, 0x03=IMA ADPCM, 0x14 (20)=Opus
PacketTypeuint80x01=START, 0x02=DATA, 0x03=END, 0x04=HEARTBEAT

4. 传输层：BLE

BLE 是 Nexting 夹子与 iPhone 应用之间的连接。设备暴露一个包含五个特征值的主 GATT 服务，以及独立的按键、存储和 DFU 服务。

BLE 服务

Nexting 服务 UUID：12345678-1234-1234-1234-123456789ABC

特征值UUID属性
Text / Format12345678-1234-1234-1234-123456789ABDRead, Write, Notify — 手机写入命令（如 0x01 开始、0x40 关机）
Audio12345678-1234-1234-1234-123456789ABERead, Notify
Heartbeat / Speaker12345678-1234-1234-1234-123456789ABFWrite, Notify
Speaker12345678-1234-1234-1234-123456789AC0Write
Hardware ID12345678-1234-1234-1234-123456789AC1Read

设备还额外暴露独立的按键、存储和 DFU（固件更新）服务。

MTU：协商确定（固件支持最大 498 字节 L2CAP 载荷；最低要求 100 字节）。

数据包格式

START

[0x01][codec:1B][totalSize/reserved:4B BE] — 宣告一段新的音频录制。编解码 0x14（Opus）携带 4 个保留零字节；编解码 0x03（ADPCM）携带 totalSize（编码音频的预期总字节数）；旧版编解码 0x01（AAC）省略 codec 字节。

DATA

[0x02][seqNo:2B BE][payload ≤320B] — 按序音频分片。seqNo 用于排序和缺口检测。

END

[0x03][totalFrames:4B BE] — 录制结束。Opus 使用帧计数；旧版 AAC/ADPCM 则发送 CRC32 校验和。

HEARTBEAT

[0x04][counter:2B BE][flags:1B][battMv:2B BE] — 周期性保活信号。counter 每次心跳递增；flags bit0 = 正在录音，bit1 = 正在充电；battMv 为电池电压（毫伏）。

Binary Packet Layout
┌──────────────────────────────────────────────────────────────┐
│ 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)│
└──────────────────────────────────────────────────────────────┘

（仅旧版 AAC/ADPCM）CRC32 算法：标准 CRC32（多项式 0xEDB88320），对完整组装的音频数据进行计算。

5. 传输层：WebSocket

参数值
连接 URIws://{host}:{port} 或 wss://{host}:{port}
默认端口18790
认证超时10 秒（若未认证，服务器以代码 4001 关闭连接）
保活服务器每 30 秒发送 ping
重连指数退避：延迟 = min(2^attempt, 15) 秒

连接状态

WebSocket State Machine
disconnected → connecting → authenticating → connected ↔ reconnecting

客户端 MUST 在连接建立后 10 秒内发送 auth 消息。网关 MUST 响应 auth_ok 或以代码 4001 关闭连接。

6. 消息类型

所有消息均为 JSON 编码，通过 WebSocket 传输。

入站（客户端 → 网关）

auth

客户端认证。MUST 作为第一条消息发送。

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

text

将用户输入（通常为 STT 输出）发送至网关。

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

ping

客户端发起的保活消息。

ping
{ "type": "ping" }

出站（网关 → 客户端）

auth_ok

确认认证成功。

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

agent_message

AI 响应发送至客户端。

agent_message
{
  "type": "agent_message",
  "content": "string",
  "proactive": true | false,
  "requestId": "string?"
}
字段描述
content完整的 AI 响应文本。
proactivetrue 表示 AI 主动发起（非用户请求），例如定时提醒。
requestId可选的请求关联 ID。

error

报告网关或 AI 错误。

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

pong

对客户端 ping 的响应。

pong
{ "type": "pong" }

7. HTTP 回退

当 WebSocket 断连时使用（例如应用被 BLE 从后台唤醒）。客户端 SHOULD 优先使用 WebSocket，但 MUST 支持 HTTP 回退。

POST /message

发送用户文本，同步获取 AI 响应。

POST /message
Request:  { "token": "string", "deviceId": "string", "content": "string" }
Response: { "content": "string" }

POST /push

智能体主动推送。

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

GET /health

健康检查端点。

GET /health
Response: { "ok": true, "devices": 1, "gateway": true }

8. 会话生命周期

BLE 状态机

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

WebSocket 状态机

WebSocket States
disconnected → connecting → authenticating → connected ↔ reconnecting

语音管线状态机

Voice Pipeline States
idle → receivingAudio → transcribing → thinking → done / error

9. 音频管线

从按键到语音回复的端到端语音流程：

步骤描述
1用户按下夹子上的 PTT（按住说话）按钮。
2设备通过板载 PDM 麦克风采集音频。
3音频编码（Opus）并拆分为 BLE 数据包（START → DATA... → END）。
4iPhone 接收数据包，组装并验证帧计数（旧版编解码使用 CRC32）。
5云端 STT（Nexting Whisper 代理，设备端 Apple Speech 兜底）。
6转写文本通过 WebSocket 发送（若 WS 断连则使用 HTTP 回退）。
7网关路由至 AI（优先 Gateway RPC，备选直连 AI）。
8AI 响应返回至客户端。
9iPhone 扬声器播放 TTS。
隐私：原始音频发送至 Nexting 云端语音转写（火山流式与 Whisper 文件兜底）。定稿有字的录音会进入语音 History，最多保留 30 天。云端不可达时回退到设备端 Apple Speech。详见隐私政策。

10. 网关 RPC

网关通过基于 WebSocket 的 JSON-RPC 与 AI 服务通信，使用 Ed25519 签名进行认证。

设备身份

参数描述
密钥对位置~/.openclaw/pinclaw-device-identity.json
DeviceId 派生方式Ed25519 公钥原始值的 SHA-256 哈希（十六进制编码）
签名载荷v2|{deviceId}|{clientId}|{clientMode}|{role}|{scopes}|{signedAt}|{token}|{nonce}

chat.send RPC

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

响应事件（流式）

网关接收流式事件。delta 事件携带部分内容；final 表示完成。

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

11. 待发队列

插件本身没有待发队列。离线队列位于 Nexting Cloud，是一张 Postgres offline_queue表：当插件不可达时，云端中继将出站消息排队，并在插件重连时按序投递。

参数值
存储Nexting Cloud Postgres offline_queue 表
TTL24 小时
每设备上限无每设备上限
投递方式插件重连时按 FIFO 顺序投递，每轮最多 100 条。

12. 安全性

关注点机制
认证每设备 Bearer 令牌。
传输WS/WSS（生产环境 RECOMMENDED 使用 TLS）。
音频隐私云端语音转写；有字的录音进入语音 History，最多保留 30 天。
网关 RPCEd25519 签名 + 挑战-响应随机数。
在生产环境中，所有 WebSocket 连接 SHOULD 使用 wss://（TLS）。网关 MUST 在每次连接和 HTTP 请求时验证 Bearer 令牌。

13. 一致性

M = 必须, O = 可选, - = 不适用。

功能设备客户端网关
BLE PeripheralM--
BLE Central-M-
音频采集M--
音频编解码（Opus）MM-
数据包组装-M-
CRC32 校验-M-
WebSocket 客户端-M-
WebSocket 服务器--M
HTTP 回退-MM
STT（云端，设备端兜底）-M-
TTS 播放-M-
Gateway RPC--M
待发队列-OM
心跳发送M--
心跳接收-M-