控制 OpenClaw - 插件版

INFO

小智是一款实时语音交互助手，OpenClaw 是一个开源的 AI Agent 网关，支持接入多种智能体和工具。通过安装 xiaozhi-pro 插件，你可以用语音指挥小智调度 OpenClaw 上的智能体，让小智成为你的 AI 助手调度中心。

相比 API 版的优势

插件版无需公网 IP、无需在控制台配置 Gateway 地址和 Token，只需给 OpenClaw 安装 xiaozhi-pro 插件即可自动连接，消息实时双向推送，体验更流畅。

1. 基本原理

小智设备与 OpenClaw 通过 WebSocket 长连接 通信，由 OpenClaw 端的插件主动连接到小智Pro服务端：

小智设备 ────> 小智Pro服务端 <──(WebSocket)──> OpenClaw (xiaozhi-pro 插件主动连入)
                        │                      │
小智设备 <──── 小智Pro服务端 <──(WS 实时推送)────┘

小智服务端和 OpenClaw 内部之间隔着一层插件，插件做双向翻译：

方向1：小智 → OpenClaw（用户发消息）

  小智服务端                     OpenClaw 小智插件                  OpenClaw 内部
  ┌──────────┐   WS:            ┌──────────────┐                  ┌──────────┐
  │ push_to  │──{"type":        │ WS client    │  ingest()       │          │
  │ openclaw │─ "message",      │ 收到         │──翻译成 inbound │─ agent   │
  │          │  "text":"你好"}  │              │  event          │  处理    │
  └──────────┘                  └──────────────┘                  └──────────┘

方向2：OpenClaw → 小智（agent 回复）

  OpenClaw 内部                  OpenClaw 小智插件                  小智服务端
  ┌──────────┐                  ┌──────────────┐   WS:            ┌──────────┐
  │ agent    │──→ outbound.     │ WS client    │──{"type":       │ _message_│
  │ 回复     │   sendText()    │ .send_json() │─ "response",...}│ loop 收到│
  └──────────┘                  └──────────────┘                  └──────────┘

1.1 连接建立

用户在小智Pro平台获取 API 密钥
在 OpenClaw 上安装 @xiaozhi-pro/openclaw-plugin 插件，配置 API 密钥
openclaw重启，插件自动通过 WebSocket 连接到小智Pro服务端
插件发送 auth 消息完成认证，认证成功后进入双向通信

1.2 消息投递策略

插件发来的 response 消息有两种来源，通过 device_id 是否存在区分投递策略：

来源	触发场景	device_id	投递策略
回复（reply）	用户发消息 → agent 回复	✅ 有值	精确投递到该设备
主动推送（push）	cron 定时任务、agent 主动发起	❌ 为空	广播该用户所有设备

1.3 关键设计

特性	说明
实时通信	WebSocket 全双工长连接，消息即时推送，无轮询延迟
无需公网	OpenClaw 主动连接服务端，无需暴露端口
心跳保活	30 秒心跳检测，60 秒无响应自动断开
自动重连	插件内置指数退避重连（1s → 2s → 4s → ... → 30s 上限）
消息去重	插件侧 dedup 保证幂等，重复推送自动跳过
精确投递	支持指定设备投递或广播所有设备
自动踢旧	同一账号新连接自动踢掉旧连接

2. 操作指南

太长不看版

把下面这段话直接发给 OpenClaw，让它帮你完成安装和配置：

请帮我安装并配置小智Pro OpenClaw插件：

安装插件：openclaw plugins install @xiaozhi-pro/openclaw-plugin
如已安装旧版，更新：openclaw plugins install @xiaozhi-pro/openclaw-plugin --force
在 openclaw.json 的 channels 中添加配置：

json

"xiaozhi-pro": {
  "token": "<我的API密钥>",
  "agentId": "main"
}

token（必填）：小智Pro API密钥
agentId（可选）：智能体ID，不填默认 main

2.1 获取 API 密钥

前往小智Pro 控制台
进入 API 密钥页面
点击 创建密钥，复制生成的密钥

WARNING

API 密钥是插件连接小智Pro的唯一凭证，请勿泄露给他人。

2.2 安装/更新插件

在 OpenClaw 所在服务器上执行：

bash

openclaw plugins install @xiaozhi-pro/openclaw-plugin

国内镜像若因同步延迟导致 404，可临时切官方源：npm config set registry https://registry.npmjs.org，装完切回即可。

如果已经安装过，可采用如下命令，更新到最新版本：

bash

openclaw plugins install @xiaozhi-pro/openclaw-plugin --force

2.3 配置插件

编辑 OpenClaw 的配置文件 openclaw.json，添加通道配置：

json

{
  "channels": {
    "xiaozhi-pro": {
      "token": "你的小智Pro平台API密钥",
      "agentId": "main"
    }
  }
}

token：小智Pro平台的API密钥，在「用户中心 → API Key」页面创建获取。可以通过环境变量 XIAOZHI_PRO_TOKEN 设置 Token，无需修改配置文件。
agentId：可选，支持指定接入的智能体ID。不填则接入默认智能体（main）。

2.4 重启 OpenClaw Gateway

安装插件和更新配置后，OpenClaw 通常会自动重启 Gateway。

如果没有重启，可以手动执行：

bash

systemctl --user restart openclaw-gateway.service
# or
openclaw gateway restart

插件会自动连接小智Pro 服务端，发送 {"type":"auth","token":"..."} 完成认证后进入双向通信。

查看 OpenClaw 日志确认连接状态：

bash

journalctl --user -u openclaw-gateway.service -f

2.5 管理插件启用状态

安装插件后会自动启用。

如果没有启动，可手动开启插件：

bash

openclaw plugins enable xiaozhi-pro

启用后，可用以下命令确认插件状态：

bash

openclaw plugins list

停用插件（保留安装）

如果只是暂时不用，停用即可，插件包仍保留在本地，随时可再次启用：

bash

openclaw plugins disable xiaozhi-pro

再次需要时直接 openclaw plugins enable xiaozhi-pro 即可，无需重新安装。

卸载插件（彻底移除）

如果确定不再使用，可彻底卸载，插件包会从 OpenClaw 的 npm 沙箱中删除：

bash

openclaw plugins uninstall xiaozhi-pro

2.6 验证连接

进入小智Pro控制台，点击左侧菜单 设备端MCP → 龙虾插件版
点击 检查连接 按钮
如果显示绿色"已连接"标签，说明插件已成功连接

2.7 测试发送消息

在龙虾插件版页面底部：

选择目标设备：从下拉框选择要接收回复的小智设备（留空则广播到所有设备）
输入消息内容：输入要发送给 OpenClaw 的消息
点击发送或按 Enter 键

发送成功后，稍等片刻点击刷新按钮查看 OpenClaw 的回复记录。

2.8 通过设备语音操控

WARNING

设备固件版本需为 v2.2.5.1 以上：https://github.com/hougeai/xiaozhiPro/releases

配置好连接后，你可以直接对小智说：

- '问问欧克劳现在都有哪些定时任务'
- '让欧克劳给我的飞书发一条消息'
- '让欧克劳立刻完成今天的AI资讯整理任务'

成功调用后，屏幕或日志中会看到 self.openclaw.send 工具调用，欧克劳回复后，服务端会自动推送到设备，设备随即播报回复内容。

3. 插件版 vs API 版

插件版和 API 版是两种不同的接入方式，插件版更适合大多数用户，API 版适合需要精细管理 OpenClaw 会话的高级用户。以下是两者的对比：
OpenClaw 控制 API 版

对比项	插件版（推荐）	API 版
网络要求	OpenClaw 无需公网 IP	OpenClaw 需要公网可访问
连接方式	插件主动 WS 连接服务端	服务端调用 OpenClaw HTTP API
消息延迟	实时推送，毫秒级	异步轮询，有延迟
配置方式	安装插件 + API 密钥	控制台配置 Gateway URL + Token
控制台操作	查看状态和对话记录	完整的会话管理和智能体切换
主动推送	即时，零延迟	受轮询间隔制约
流式回复	天然支持	需额外处理
适合场景	大多数用户	需要精细管理 OpenClaw 会话的高级用户

4. 常见问题

连接状态显示"未连接"？

确认插件已安装：openclaw plugins list 查看 @xiaozhi-pro/openclaw-plugin 是否在列表中
检查 openclaw.json 中 channels.xiaozhi-pro.token 是否配置了有效的 API 密钥
检查 OpenClaw 服务是否正常运行
检查网络是否正常
查看 OpenClaw 日志排查连接错误

插件连接后频繁断开？

检查网络稳定性
确认 OpenClaw 服务器时间同步（NTP）
插件内置自动重连机制（指数退避），短暂断开后会自动恢复
服务端 30 秒心跳检测，60 秒无 pong 响应会断开，插件会自动重连

设备端没有收到欧克劳的回复？

确认设备已绑定到小智Pro账号
确认设备固件版本为 v2.2.5.1 以上
确认控制台显示"已连接"状态
如果设备正在说话，服务端会自动等待，最多等待 120 秒，消息最多缓存 1 天

如何同时使用插件版和 API 版？

插件版和 API 版共享同一套设备端 MCP 工具，设备发送消息时服务端会优先走 WebSocket 通道（插件版），如果插件未连接则自动回退到 HTTP API（API 版）。因此建议优先使用插件版，API 版作为备用。

控制 OpenClaw - 插件版 ​

1. 基本原理 ​

1.1 连接建立 ​

1.2 消息投递策略 ​

1.3 关键设计 ​

2. 操作指南 ​

2.1 获取 API 密钥 ​

2.2 安装/更新插件 ​

2.3 配置插件 ​

2.4 重启 OpenClaw Gateway ​

2.5 管理插件启用状态 ​

停用插件（保留安装） ​

卸载插件（彻底移除） ​

2.6 验证连接 ​

2.7 测试发送消息 ​

2.8 通过设备语音操控 ​

3. 插件版 vs API 版 ​

4. 常见问题 ​

连接状态显示"未连接"？ ​

插件连接后频繁断开？ ​

设备端没有收到欧克劳的回复？ ​

如何同时使用插件版和 API 版？ ​

控制 OpenClaw - 插件版

1. 基本原理

1.1 连接建立

1.2 消息投递策略

1.3 关键设计

2. 操作指南

2.1 获取 API 密钥

2.2 安装/更新插件

2.3 配置插件

2.4 重启 OpenClaw Gateway

2.5 管理插件启用状态

停用插件（保留安装）

卸载插件（彻底移除）

2.6 验证连接

2.7 测试发送消息

2.8 通过设备语音操控

3. 插件版 vs API 版

4. 常见问题

连接状态显示"未连接"？

插件连接后频繁断开？

设备端没有收到欧克劳的回复？

如何同时使用插件版和 API 版？