接入小龙虾OpenClaw最佳实践
更新时间：2026-05-16
概览
本文介绍如何将用户本地的OpenClaw 小龙虾接入百度 RTC 大模型智能体系统（RTCAgent），实现双向实时通信。
整体方案通过 ClawGateway 作为中间网关完成对接，用户在本地小龙虾侧安装OpenClawPlugin插件：
- Q&A 模式：RTCAgent 向小龙虾发送文本/图片消息，小龙虾处理后流式返回文字/图片/文件回复，RTCAgent 实时播报给用户。
- EVENT 模式：小龙虾主动向 RTCAgent 推送消息（定时提醒、Skill 执行结果等），RTCAgent 实时播报给用户。
系统架构
Plain Text
1RTCAgent (Java/云端)
2 │
3 ├── HTTP POST /v1/chat/completions ──► ClawGateway ──► WebSocket ──► OpenclawIMPlugin (小龙虾)
4 │ (SSE 流式响应) │
5 │◄─────────────────────────────────────────────────────────────────────┘
6 │
7 └── WebSocket /client ◄──────────── ClawGateway ◄──── WebSocket ──── OpenclawIMPlugin
8 (接收主动推送)部署说明：ClawGateway 和 RTCAgent 部署在云端；OpenclawIMPlugin 作为插件运行在用户的小龙虾上。
| 参数 | 说明 |
|---|---|
appId |
创建互动实例传入 |
clawGatewayToken |
Gateway Token，用于 WebSocket 连接和 HTTP 接口鉴权 |
clawGatewayUrl |
ClawGateway 访问地址:rtc-aiagent.baidubce.com |
创建完成之后点击互动应用实例详情查看相关信息
步骤二：部署 OpenclawIMPlugin
OpenclawIMPlugin 是运行在小龙虾上的 TypeScript 插件，需安装到小龙虾服务器中。
请安装：openclaw-baidu-rtc-interactive-plugin
YAML
1#解压到当前目录
2unzip openclaw-baidu-rtc-interactive-plugin-v1.0.0.zip
3
4#解压到指定目录
5unzip openclaw-baidu-rtc-interactive-plugin-v1.0.0.zip -d /path/to/dir必要配置项（在小龙虾插件配置里面填写）：
| 配置项 | 是否必填 | 说明 |
|---|---|---|
clawGatewayUrl |
是 | Gateway WebSocket 地址，如 wss://api.example.com/plugin |
clawGatewayToken |
是 | 接入凭证中的 Gateway Token |
appId |
是 | 应用标识 |
userId |
是 | 用户标识，与 RTCAgent 侧保持一致 |
deviceId |
否 | 设备标识（建议默认为空） |
clawName |
是 | 小龙虾名称 |
插件启动后，会自动以如下 URL 连接 ClawGateway：
Plain Text
1wss://api.example.com/plugin?token=<token>&identity=<appId>:<userId>:<deviceId>:<clawName>配置方式：
方式一：通过脚本快速配置（首次配置）
打开插件根目录，运行sh setup.sh
按照提示快速进行插件的安装和部署
首次配置需要安装依赖，需要稍等一会
方式二：通过配置rtc-config.yaml配置文件进行配置
用户可读取配置文件中的参数，并为后续业务进行可编程式的扩展
编辑完成之后需要重启小龙虾
方式三：通过openclaw命令进行配置
配置相关的交互方式：
| 方式 | 命令 | 说明 |
|---|---|---|
| 查看所有配置 | openclaw rtc:config |
显示所有配置项 |
| 设置配置 | openclaw rtc:config <key> <value> |
修改单个配置项 |
| 设置 Gateway 地址 | openclaw rtc:config clawGatewayUrl <value> |
设置 Gateway 服务地址 |
| 设置 Gateway Token | openclaw rtc:config clawGatewayToken <value> |
设置连接 Gateway 的鉴权 Token，从百度控制台申请 |
| 设置 App ID | openclaw rtc:config appId <value> |
设置应用标识 |
| 设置 User ID | openclaw rtc:config userId <value> |
设置用户标识 |
| 设置小龙虾名称 | openclaw rtc:config clawName <value> |
设置小龙虾实例名称 |
| ClawToken 管理 | openclaw rtc:claw_token [--new] |
查看/重新生成 Claw Token |
| 查看路径 | openclaw rtc:path |
显示插件加载路径 |
按用户场景分：
- 新手首次配置：
sh ./setup.sh - 开发者日常：直接编辑
rtc-config.yaml - OpenClaw命令配置：
openclaw rtc:config key value - 查看 Claw Token：
openclaw rtc:claw_token
配置完成之后启动小龙虾：
YAML
1#启动小龙虾
2openclaw gateway start
3
4#停止小龙虾
5openclaw gateway stop
6
7#重启小龙虾
8openclaw gateway restart步骤三：RTCAgent 接入
调用创建大模型互动实例接口（generateAIAgentCall）时，通过配置小龙虾相关参数完成接入。支持两种方式指定大模型类型：
方式一：通过 LLMModeName（config 中配置 llm 字段）
在 config 的 JSON 字符串中指定 "llm": "ClawChat"：
Plain Text
1POST /api/v1/aiagent/generateAIAgentCall HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
5
6{
7 "app_id": "your_app_id",
8 "config": "{\"llm\":\"ClawChat\",\"user_id\":\"user_001\",\"openclawConfig\":{\"enabled\":true,\"clawGatewayUrl\":\"https://your-gateway:8710\",\"claws\":[{\"type\":\"openclaw\",\"name\":\"my-claw\",\"claw_token\":\"xxx\"}]}}"
9}config 展开后：
JSON
1{
2 "llm": "ClawChat",
3 "user_id": "user_001",
4 "openclawConfig": {
5 "enabled": true,
6 "clawGatewayUrl": "https://your-gateway",
7 "claws": [
8 {
9 "type": "openclaw",
10 "name": "my-claw",
11 "claw_token": "xxx"
12 }
13 ]
14 }
15}方式二：通过 InstanceType（请求体 instance_type 字段）
将大模型类型提取为请求体的独立字段 instance_type，config 中不再包含 llm：
Plain Text
1POST /api/v1/aiagent/generateAIAgentCall HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
5
6{
7 "app_id": "your_app_id",
8 "instance_type": "ClawChat",
9 "config": "{\"user_id\":\"user_001\",\"openclawConfig\":{\"enabled\":true,\"clawGatewayUrl\":\"https://your-gateway\",\"claws\":[{\"type\":\"openclaw\",\"name\":\"my-claw\",\"claw_token\":\"xxx\"}]}}"
10}两种方式对比：
| 方式一（LLMModeName） | 方式二（InstanceType） | |
|---|---|---|
ClawChat 配置位置 |
config 内的 llm 字段 |
请求体独立字段 instance_type |
config 是否含 llm |
是 | 否 |
openclawConfig 参数说明
| 参数 | 是否必填 | 说明 |
|---|---|---|
enabled |
是 | 是否启用 OpenClaw 接入，固定填 true |
clawGatewayUrl |
是 | ClawGateway 地址，填 Gateway 的 HTTP/WebSocket 根地址 |
claws |
是 | 小龙虾列表，每项对应一台小龙虾 |
claws[].type |
是 | 小龙虾类型 |
claws[].name |
是 | 小龙虾名称（即插件配置中的 clawName），用于路由匹配 |
claws[].claw_token |
是 | Claw Token，RTCAgent 发 Q&A 请求时带上，Plugin 侧用于验证请求合法性 |
注意：
user_id必须与小龙虾插件配置中的userId**保持一致。
鉴权说明
Gateway Token（clawGatewayToken）
用于 WebSocket 连接和 HTTP 接口鉴权，通过控制台接口统一管理。创建互动应用成功后生成，表明外部连接Gateway的身份凭证，配置小龙虾插件时传入。
使用方式：
- WebSocket 连接：URL 参数
?token=<token> - HTTP 接口：
Authorization: Bearer <token>
Claw Token（claw_token）
在创建互动大模型实例时传入。
用于 Plugin 侧验证 Q&A 请求的来源合法性，防止非授权方伪造请求。
Q&A 请求体中的 claw_token 字段必须传入，Plugin 侧会验证其合法性。
通信模式详解
Q&A 模式（RTCAgent → 小龙虾 → RTCAgent）
完整流程：
Plain Text
11. RTCAgent POST /v1/chat/completions
22. Gateway 按 appId:userId 查找已连接的小龙虾 Plugin
33. Gateway 找不到 Plugin → 返回 503 {code: "CLAW_OFFLINE"}
44. Gateway 通过 WebSocket 把请求发给 Plugin
55. Plugin 调用 OpenClaw Agent 处理
66. Plugin 流式回复 {action: "reply", chunk: "...", done: false}
77. Gateway 把每个 chunk 转成 SSE 推给 RTCAgent
88. Plugin 发送最后一帧 {done: true}，请求结束流式响应格式（SSE）：
Plain Text
1data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"app:user:device:claw","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}
2
3data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"app:user:device:claw","choices":[{"index":0,"delta":{"content":"，"},"finish_reason":null}]}
4
5data: [DONE]图片回复格式（通过 media_url 字段传递）：
JSON
1{
2 "choices": [{
3 "delta": {
4 "content": "",
5 "media_url": "data:image/jpeg;base64,/9j/...",
6 "media_type": "image"
7 }
8 }]
9}请求中断：用户连续发消息时，新请求会自动中断旧请求，Gateway 会通知 Plugin 停止生成。业务侧无需额外处理。
EVENT 模式（小龙虾主动推送）
小龙虾通过 OpenClaw Skill 或定时任务主动发出消息，Gateway 转发给已连接的 RTCAgent。
RTCAgent 接收的 push 消息格式：
JSON
1{
2 "action": "push",
3 "id": "req_xxx",
4 "type": "text",
5 "chunk": "提醒您：会议将在5分钟后开始",
6 "done": true,
7 "from": "appId:userId:deviceId:clawName",
8 "timestamp": 1234567890
9}| 字段 | 说明 |
|---|---|
type |
消息类型：text / image / file |
chunk |
消息内容（文本）或 base64 数据（图片） |
done |
是否为最后一帧，流式文本推送时多帧 done=false 后接一帧 done=true |
from |
发送方 identity（小龙虾的完整 identity） |
filename |
文件名（type=file 时有值） |
上下线状态通知
小龙虾上下线时，Gateway 会通过 Client WebSocket 通知 RTCAgent：
JSON
1{
2 "action": "status",
3 "type": "plugin",
4 "online": true,
5 "identity": "appId:userId:deviceId:clawName",
6 "display_name": "my_claw",
7 "timestamp": 1234567890
8}注意事项
- 小龙虾不在线时：Q&A 请求会立即返回 503，错误码为
CLAW_OFFLINE，RTCAgent 侧会提示小龙虾不在线。 - 心跳保活：Gateway 每 60 秒发一次 ping，超过 30 秒未收到 pong 会断开连接。RTCAgent 侧必须实现 pong 回复逻辑。
- 鉴权失败：Token 验证失败或 identity 格式错误时，Gateway 会先推送错误并告知失败原因，再以 WebSocket code=1008 关闭连接；插件侧应监听该消息并向用户展示错误提示，避免静默失败。
- 图片大小：通过 BCE API 网关传输时，单帧限制 32KB，ClawGateway 已内置分块传输机制（WS Chunker），业务侧无需处理，但建议图片适当压缩（建议 ≤ 500KB）以提升响应速度。
- 连接替换：同一 identity 重复连接时，旧连接会收到
code=1001 reason=replaced关闭信号。这是正常行为，不应触发重连。 - 集群部署：ClawGateway 支持多节点水平扩展，所有路由逻辑对接入方透明，接入方无需关心集群细节。
评价此篇文章