{"_id":"@dsw0000/xiaozhi","name":"@dsw0000/xiaozhi","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@dsw0000/xiaozhi","version":"1.0.0","description":"Xiaozhi (小智) ESP32 integration plugin for OpenClaw - WebSocket client for xiaozhi-esp32-server","type":"module","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest","test:coverage":"vitest --coverage","prepublishOnly":"pnpm build","release":"pnpm build && npm publish","release:patch":"npm version patch && pnpm release","release:minor":"npm version minor && pnpm release","release:major":"npm version major && pnpm release"},"keywords":["openclaw","openclaw-plugin","xiaozhi","esp32","websocket","iot","smart-home","ai-assistant"],"author":{"name":"OpenClaw Contributors"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/dsw0000/xiaozhi-openclaw-plugin.git"},"homepage":"https://github.com/dsw0000/xiaozhi-openclaw-plugin#readme","bugs":{"url":"https://github.com/dsw0000/xiaozhi-openclaw-plugin/issues"},"peerDependencies":{"openclaw":">=2026.2.0"},"dependencies":{"ws":"^8.18.0","zod":"^4.3.6","@sinclair/typebox":"^0.33.0"},"devDependencies":{"@types/node":"^22.0.0","@types/ws":"^8.5.10","typescript":"^5.6.0","vitest":"^2.0.0","@vitest/coverage-v8":"^2.0.0"},"engines":{"node":">=22.0.0"},"openclaw":{"id":"xiaozhi","name":"Xiaozhi Integration","description":"WebSocket client for xiaozhi-esp32-server integration","version":"1.0.0","config":{"uiHints":{"serverUrl":{"label":"Server URL","help":"WebSocket server URL (e.g., ws://localhost:8080/ws)","placeholder":"ws://localhost:8080/ws"},"authToken":{"label":"Auth Token","help":"Optional authentication token","sensitive":true},"reconnectInterval":{"label":"Reconnect Interval","help":"Time between reconnection attempts (milliseconds)","advanced":true},"maxReconnectAttempts":{"label":"Max Reconnect Attempts","help":"Maximum number of reconnection attempts before giving up","advanced":true},"heartbeatInterval":{"label":"Heartbeat Interval","help":"Heartbeat/ping interval (milliseconds)","advanced":true}}}},"gitHead":"58ff68fe0aa711e40a4fb68e31eb51b4e2fcf98b","_id":"@dsw0000/xiaozhi@1.0.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-vRunnLVuVVr4RXkgeVLsLO9Kyme0vjQOvr5C1rq/LKghDtmowry0BrHnUtT/e07Stjg3+wGwQdjCSYvW/663Eg==","shasum":"def750275120b6e96b6faf38b16dac7abeecdc60","tarball":"https://registry.npmjs.org/@dsw0000/xiaozhi/-/xiaozhi-1.0.0.tgz","fileCount":36,"unpackedSize":55820,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDlVQzU63AeQTaPEsbb01Y7k1WG346/5w/kMejhVeeGzAiEArDsa7iZikBoF42GnDPb6dRmCgwnYzUizKdvTpGaurns="}]},"_npmUser":{"name":"d_shao5","email":"ivo_d@icloud.com"},"directories":{},"maintainers":[{"name":"d_shao5","email":"ivo_d@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xiaozhi_1.0.0_1770255162365_0.21441964363958266"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-05T01:32:42.258Z","1.0.0":"2026-02-05T01:32:42.521Z","modified":"2026-02-05T01:32:42.764Z"},"maintainers":[{"name":"d_shao5","email":"ivo_d@icloud.com"}],"description":"Xiaozhi (小智) ESP32 integration plugin for OpenClaw - WebSocket client for xiaozhi-esp32-server","homepage":"https://github.com/dsw0000/xiaozhi-openclaw-plugin#readme","keywords":["openclaw","openclaw-plugin","xiaozhi","esp32","websocket","iot","smart-home","ai-assistant"],"repository":{"type":"git","url":"git+https://github.com/dsw0000/xiaozhi-openclaw-plugin.git"},"author":{"name":"OpenClaw Contributors"},"bugs":{"url":"https://github.com/dsw0000/xiaozhi-openclaw-plugin/issues"},"license":"MIT","readme":"# @openclaw/xiaozhi\n\n> **Xiaozhi (小智) ESP32 集成插件** - 为 OpenClaw 提供与小智 ESP32 服务器的 WebSocket 通信能力\n\n[![npm version](https://badge.fury.io/js/%40openclaw%2Fxiaozhi.svg)](https://www.npmjs.com/package/@openclaw/xiaozhi)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## 📖 简介\n\n这是一个 [OpenClaw](https://github.com/openclaw/openclaw) 插件，用于连接到 [xiaozhi-esp32-server](https://github.com/xiaozhi-esp32-server) 项目。通过这个插件，OpenClaw 网关可以与小智 ESP32 智能硬件设备进行双向通信，实现：\n\n- 📤 发送消息到配置的渠道（Telegram、Discord、微信等）\n- 🏠 控制 IoT 设备（灯光、开关、传感器等）\n- 🤖 执行/查询 Agent 任务\n\n## ✨ 功能特性\n\n- 🔌 **双向通信** - 基于 WebSocket 的实时通信\n- 🔄 **自动重连** - 连接断开时自动重连，可配置重连次数和间隔\n- 💓 **心跳检测** - 定期发送心跳保持连接活跃\n- 🔐 **认证支持** - 可选的 Bearer Token 认证\n- 🛠️ **三个工具** - `xiaozhi_send_message`、`xiaozhi_device_control`、`xiaozhi_agent_task`\n\n## 📋 系统要求\n\n- **Node.js**: >= 22.0.0\n- **OpenClaw**: >= 2026.2.0\n- **xiaozhi-esp32-server**: 任意版本（需启用 OpenClaw 适配器）\n\n## 🚀 安装\n\n### 方式一：通过 npm 安装（推荐）\n\n```bash\n# 使用 OpenClaw CLI 安装\nopenclaw plugins install @openclaw/xiaozhi\n\n# 或手动安装\nnpm install -g @openclaw/xiaozhi\n```\n\n### 方式二：从 GitHub 安装\n\n```bash\n# 克隆仓库\ngit clone https://github.com/openclaw/xiaozhi-openclaw-plugin.git\ncd xiaozhi-openclaw-plugin\n\n# 安装依赖\nnpm install\n\n# 构建\nnpm run build\n\n# 安装到 OpenClaw\nopenclaw plugins install .\n```\n\n## ⚙️ 配置\n\n在 `~/.openclaw/config.yaml` 中添加以下配置：\n\n```yaml\nplugins:\n  xiaozhi:\n    enabled: true\n    config:\n      # WebSocket 服务器地址（必填）\n      serverUrl: ws://localhost:8080/ws\n\n      # 认证令牌（可选）\n      authToken: your-auth-token-here\n\n      # 重连间隔（毫秒），默认 5000\n      reconnectInterval: 5000\n\n      # 最大重连次数，默认 10\n      maxReconnectAttempts: 10\n\n      # 心跳间隔（毫秒），默认 30000\n      heartbeatInterval: 30000\n\n      # 连接超时（毫秒），默认 10000\n      connectionTimeout: 10000\n```\n\n### 配置说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `serverUrl` | string | ✅ | - | xiaozhi WebSocket 服务器 URL |\n| `authToken` | string | ❌ | null | Bearer Token 认证令牌 |\n| `reconnectInterval` | number | ❌ | 5000 | 重连间隔（毫秒） |\n| `maxReconnectAttempts` | number | ❌ | 10 | 最大重连次数 |\n| `heartbeatInterval` | number | ❌ | 30000 | 心跳间隔（毫秒） |\n| `connectionTimeout` | number | ❌ | 10000 | 连接超时（毫秒） |\n\n## 🛠️ 可用工具\n\n安装插件后，以下工具将在 OpenClaw 中可用：\n\n### 1. xiaozhi_send_message\n\n发送消息到配置的渠道（Telegram、Discord、微信等）。\n\n**参数：**\n```json\n{\n  \"to\": \"string\",      // 必填 - 接收者标识符\n  \"text\": \"string\",    // 必填 - 消息内容\n  \"channel\": \"string\"  // 可选 - 渠道名称（telegram/discord/wechat）\n}\n```\n\n**示例：**\n```json\n{\n  \"to\": \"123456789\",\n  \"text\": \"你好，这是一条测试消息\",\n  \"channel\": \"telegram\"\n}\n```\n\n### 2. xiaozhi_device_control\n\n控制连接到小智的 IoT 设备。\n\n**参数：**\n```json\n{\n  \"deviceId\": \"string\",  // 必填 - 设备标识符\n  \"action\": \"string\",    // 必填 - 操作类型\n  \"value\": \"number\"      // 可选 - 设置值（0-100，用于 set_value）\n}\n```\n\n**操作类型：** `turn_on`、`turn_off`、`toggle`、`set_value`\n\n**示例：**\n```json\n{\n  \"deviceId\": \"light_01\",\n  \"action\": \"turn_on\"\n}\n```\n\n```json\n{\n  \"deviceId\": \"dimmer_01\",\n  \"action\": \"set_value\",\n  \"value\": 50\n}\n```\n\n### 3. xiaozhi_agent_task\n\n执行或查询 Agent 任务。\n\n**参数：**\n```json\n{\n  \"action\": \"string\",  // 必填 - 操作类型\n  \"taskId\": \"string\",  // 可选 - 任务 ID（用于 status/cancel）\n  \"prompt\": \"string\"   // 可选 - 任务提示（用于 execute）\n}\n```\n\n**操作类型：** `execute`、`status`、`cancel`\n\n**示例：**\n```json\n{\n  \"action\": \"execute\",\n  \"prompt\": \"总结最近的对话历史\"\n}\n```\n\n## 🏗️ 小智服务器配置\n\n在 xiaozhi-esp32-server 端，需要启用 OpenClaw 适配器。\n\n配置文件：`xiaozhi-esp32-server/main/xiaozhi-server/data/.openclaw_adapter_settings.json`\n\n```json\n{\n  \"websocketServer\": {\n    \"enabled\": true,\n    \"host\": \"0.0.0.0\",\n    \"port\": 8080,\n    \"authToken\": null\n  }\n}\n```\n\n启动小智服务器后，WebSocket 服务器将在 `ws://host:port/ws` 监听连接。\n\n## 📡 通信协议\n\n插件使用 JSON-RPC 2.0 协议与 xiaozhi 服务器通信。\n\n**请求格式：**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"xiaozhi_send_message\",\n    \"arguments\": {\n      \"to\": \"user123\",\n      \"text\": \"Hello\",\n      \"channel\": \"telegram\"\n    }\n  }\n}\n```\n\n**响应格式（成功）：**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"success\": true,\n    \"data\": {\n      \"messageId\": \"msg_123\",\n      \"timestamp\": 1707895200\n    }\n  }\n}\n```\n\n**响应格式（错误）：**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"error\": {\n    \"code\": -32000,\n    \"message\": \"工具执行失败\",\n    \"data\": {\n      \"details\": \"接收者未找到\"\n    }\n  }\n}\n```\n\n## 🔄 工作流程\n\n```\n用户说话\n    ↓\n小志 ASR 识别\n    ↓\n小志 Agent 判断意图\n    ↓\n    ├─→ 简单对话 → 直接回复 → TTS播报\n    │\n    └─→ 需要工具 → 异步调用 OpenClaw → 等待结果 → TTS播报\n```\n\n## 🐛 故障排查\n\n### 插件无法连接到 xiaozhi 服务器\n\n1. 确认 xiaozhi 服务器已启动\n2. 检查 `serverUrl` 配置是否正确\n3. 确认防火墙允许 WebSocket 连接\n4. 查看 OpenClaw 日志：`openclaw logs`\n\n### 工具调用失败\n\n1. 确认 xiaozhi 服务器启用了 OpenClaw 适配器\n2. 检查工具参数是否正确\n3. 查看 xiaozhi 服务器日志\n\n### 重连失败\n\n- 增加 `maxReconnectAttempts` 值\n- 检查网络连接稳定性\n- 确认服务器地址和端口正确\n\n## 📦 开发\n\n### 克隆仓库\n\n```bash\ngit clone https://github.com/openclaw/xiaozhi-openclaw-plugin.git\ncd xiaozhi-openclaw-plugin\n```\n\n### 安装依赖\n\n```bash\nnpm install\n```\n\n### 构建\n\n```bash\nnpm run build\n```\n\n### 运行测试\n\n```bash\nnpm test\nnpm run test:coverage\n```\n\n### 项目结构\n\n```\nxiaozhi-openclaw-plugin/\n├── src/\n│   ├── client/          # WebSocket 客户端\n│   │   ├── websocket.ts\n│   │   └── protocol.ts\n│   ├── config/          # 配置管理\n│   │   ├── schema.ts\n│   │   └── types.ts\n│   ├── tools/           # 工具实现\n│   │   ├── send-message.ts\n│   │   ├── device-control.ts\n│   │   ├── agent-task.ts\n│   │   └── index.ts\n│   ├── types.ts         # 类型定义\n│   ├── runtime.ts       # 插件生命周期\n│   └── index.ts         # 入口文件\n├── test/                # 测试文件\n├── dist/                # 构建输出\n├── package.json\n├── tsconfig.json\n├── vitest.config.ts\n└── README.md\n```\n\n## 📄 许可证\n\n[MIT](LICENSE)\n\n## 🙏 致谢\n\n- [OpenClaw](https://github.com/openclaw/openclaw) - 强大的 AI Agent 网关系统\n- [xiaozhi-esp32-server](https://github.com/xiaozhi-esp32-server) - ESP32 智能硬件服务器\n\n## 📮 联系方式\n\n- GitHub Issues: https://github.com/openclaw/xiaozhi-openclaw-plugin/issues\n- OpenClaw Discord: https://discord.gg/openclaw\n\n---\n\n**注意**: 此插件需要同时运行 xiaozhi-esp32-server 并启用其 OpenClaw 适配器功能。\n","readmeFilename":"README.md","_rev":"1-a35fc997a3c1d77b073e2b3b000e5f95"}