qingtui

OpenClaw QingTui (轻推) channel plugin (official by CISDI QingTui team)

Install

openclaw plugins install clawhub:@qingtui/qingtui-openclaw-plugin

轻推 OpenClaw 插件

将轻推智能助理连接到 OpenClaw Gateway，支持 WebSocket 持久连接和流式响应

官方文档 • 更新日志

📋 目录

前置要求
快速开始
功能特性
配置说明
常见问题
进阶主题
许可证

前置要求

开始之前，请确保你已经：

本插件作为 OpenClaw Gateway 插件使用，一般无需你单独安装或管理 Node.js 运行时。

1. OpenClaw Gateway

官方网站：https://openclaw.ai/
安装说明：按照官方指南安装 OpenClaw
验证安装：
bash
```
openclaw gateway status
```
预期输出：✓ Gateway is running on http://127.0.0.1:18789

⚠️ 版本兼容性要求

重要：qingtui-openclaw-plugin v2026.3.29+ 需要 OpenClaw SDK v2026.2.13 或更高版本。

插件版本	最低 OpenClaw SDK 版本	说明
v2026.3.29+	v2026.2.13+	使用 WebSocket 持久连接，支持流式响应

如何检查版本：

bash

# 检查 OpenClaw 版本
openclaw --version

# 检查插件版本
openclaw plugins list

如何升级：

bash

# 升级 OpenClaw 到最新版本
npm install -g openclaw@latest

# 或使用 yarn
yarn global add openclaw@latest

版本不兼容时的表现：

插件加载时会显示详细的错误提示
提示信息会包含升级命令和降级方案
插件会自动停止加载，不影响其他插件

2. 轻推智能助理账号

你需要一个轻推智能助理账号来创建应用
访问轻推智能助理开发平台获取 App ID 和 Secret

功能特性

✅ 核心功能

WebSocket 持久连接 - 稳定的长连接，确保消息实时送达
流式响应 - 打字机效果，实时显示回复内容
会话管理 - 私聊和群聊独立维护会话上下文
自动心跳保活 - 自动维持连接活跃，最多 100 次重连尝试
富媒体支持 - 接收并处理图像和文件消息，自动下载
Markdown 格式 - 回复支持 Markdown 格式化输出
主动消息推送 - 程序化地向特定用户或群组发送消息
访问控制 - 内置配对码、白名单等多种访问策略
交互式 CLI - 提供友好的设置向导和管理命令

🚀 快速开始

💡 目标：5 分钟内让你的轻推机器人运行起来

操作系统支持

macOS / Linux：使用默认的 Shell 终端（zsh、bash 等）。
Windows：
- 推荐使用 PowerShell 或 Windows Terminal。
- OpenClaw 配置文件路径默认为：C:\Users\<你的用户名>\.openclaw\openclaw.json。

下文中出现的 ~/.openclaw/openclaw.json，在 Windows 上等价于以上路径。

步骤 1：安装插件

方法 A：通过 npm 包安装（推荐）

bash

openclaw plugins install @qingtui/qingtui-openclaw-plugin

方法 B：通过本地源码安装

如果你想对插件进行二次开发，可以先克隆仓库：

bash

# 1. 克隆插件仓库
git clone https://github.com/nudgeandroid/qingtui-openclaw-plugin.git
cd qingtui-openclaw-plugin

# 2. 安装依赖（必需）
npm install

# 3. 以链接模式安装（方便修改代码后实时生效）
openclaw plugins install -l .

方法 C：手动安装

将本仓库下载或复制到 ~/.openclaw/extensions/qingtui-openclaw-plugin。
确保包含 index.ts、openclaw.plugin.json 和 package.json。
在该目录下运行 npm install 安装依赖。

方法 D：国内网络环境安装（npm 镜像源）

如果你在国内网络环境下执行 openclaw plugins install 时卡在 Installing plugin dependencies... 或出现 npm install failed，可临时为该次安装指定镜像源：

bash

NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @qingtui/qingtui-openclaw-plugin

如果插件已处于半安装状态（例如扩展目录存在但依赖未装全），可进入插件目录手动补装依赖：

bash

cd ~/.openclaw/extensions/qingtui-openclaw-plugin
rm -rf node_modules package-lock.json
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm install

如果希望长期生效，可设置 npm 默认镜像：

bash

npm config set registry https://registry.npmmirror.com

或写入 ~/.npmrc：

text

registry=https://registry.npmmirror.com

验证安装：

bash

openclaw plugins list

你应该看到 ✓ Qingtui（轻推） channel (v2026.3.29) - loaded

步骤 2：获取轻推智能助理凭证

2.1 访问开发平台

访问轻推智能助理开发平台
登录你的账号

2.2 创建应用

在控制台点击 "创建应用"
填写应用基本信息
完成创建后，你将获得：
- App ID（应用唯一标识）
- Secret（应用密钥）

⚠️ 重要：App ID 和 Secret 是机器人的唯一凭证。请妥善保管，不要泄露给他人。

步骤 3：配置 OpenClaw

你有三种方式配置连接器：

方式 A：配置向导（推荐新手使用）

你可以直接复制粘贴下面的命令，在终端中运行配置向导。

bash

openclaw channels add

选择 "轻推 (QingTui)"，然后按提示输入：

appId（轻推应用 App ID）
secret（轻推应用 Secret）

方式 B：CLI 快速设置

bash

openclaw config set channels.qingtui.appId <YOUR_APP_ID>
openclaw config set channels.qingtui.secret <YOUR_SECRET>
openclaw config set channels.qingtui.enabled true
openclaw gateway restart

方式 C：编辑配置文件

编辑配置文件：

macOS / Linux：~/.openclaw/openclaw.json
Windows：C:\Users\<你的用户名>\.openclaw\openclaw.json

json

{
  "channels": {
    "qingtui": {
      "enabled": true,
      "appId": "your_app_id",
      "secret": "your_app_secret"
    }
  }
}

💡 提示：如果文件已有内容，在 channels 节点下添加 qingtui 部分即可。

步骤 4：重启并测试

bash

# 重启 OpenClaw Gateway
openclaw gateway restart

# 实时查看日志
openclaw logs --follow

测试你的机器人：

打开轻推 App
在联系人列表中找到你的机器人
发送消息：你好
你应该在 10 秒内收到回复

配置说明

基础配置

选项	环境变量	说明
`appId`	—	轻推智能助理应用 ID
`secret`	—	轻推智能助理应用密钥
`enabled`	—	是否启用频道（`true` / `false`）

高级配置

选项	默认值	说明
`websocketUrl`	`wss://open.qingtui.com`	WebSocket 端点地址
`dmPolicy`	`pairing`	私聊访问策略（`pairing` / `open` / `allowlist` / `disabled`）
`allowFrom`	`[]`	私聊白名单（用户 ID 列表）
`groupPolicy`	`open`	群聊访问策略（`open` / `allowlist` / `disabled`）
`groupAllowFrom`	`[]`	群聊白名单（群组 ID 列表）
`sendThinkingMessage`	`true`	是否发送"思考中"占位消息

完整配置示例

json

{
  "channels": {
    "qingtui": {
      "enabled": true,
      "appId": "your_app_id",
      "secret": "your_app_secret",
      "websocketUrl": "wss://open.qingtui.com",
      "dmPolicy": "pairing",
      "allowFrom": [],
      "groupPolicy": "open",
      "groupAllowFrom": [],
      "sendThinkingMessage": true
    }
  }
}

常见问题

机器人不回复

症状：机器人不回复消息

解决方案：

检查插件状态：openclaw plugins list
检查网关状态：openclaw gateway status
查看日志：openclaw logs --follow
确认 WebSocket 连接是否成功
检查 appId 和 secret 是否正确

WebSocket 连接失败

症状：日志显示 WebSocket 连接失败或反复重连

常见原因：

原因	解决方案
网络问题	检查网络连接，确认可以访问 `wss://open.qingtui.com`
凭证错误	检查 `appId`/`secret` 是否有拼写错误或多余空格
服务端问题	联系轻推技术支持确认服务状态

验证步骤：

检查凭证：
- 登录轻推智能助理开发平台
- 确认应用已创建且状态正常
- 重新复制 App ID 和 Secret，确保无空格

测试网络连接：

bash

# 测试是否能访问轻推服务
curl -I https://open.qingtui.com

重启插件：
bash
```
openclaw gateway restart
```

配对码问题

症状：用户收到配对码但无法连接

解决方案：

查看待处理的配对请求：
bash
```
openclaw pairing list qingtui
```

批准配对请求：

bash

openclaw pairing approve qingtui <CODE>

或者切换到开放模式：

json

{
  "channels": {
    "qingtui": {
      "dmPolicy": "open"
    }
  }
}

访问控制

私聊 (Direct Message) 访问

默认: dmPolicy: "pairing" — 未识别的用户将收到配对码。

批准配对

bash

openclaw pairing list qingtui            # View pending pairing requests
openclaw pairing approve qingtui <CODE>  # Approve a pairing request

白名单模式

通过 channels.qingtui.allowFrom 配置允许的用户 ID：

json

{
  "channels": {
    "qingtui": {
      "dmPolicy": "allowlist",
      "allowFrom": ["user_id_1", "user_id_2"]
    }
  }
}

开放模式

设置 dmPolicy: "open" 以允许所有用户发送私聊消息，无需批准。

禁用模式

设置 dmPolicy: "disabled" 以完全阻止所有私聊消息。

群聊访问

群聊策略 (`channels.qingtui.groupPolicy`)

"open" — 允许来自所有群组的聊天（默认）
"allowlist" — 仅允许 groupAllowFrom 中列出的群组
"disabled" — 禁用所有群聊消息

群聊配置示例

允许所有群组（默认行为）

json

{
  "channels": {
    "qingtui": {
      "groupPolicy": "open"
    }
  }
}

仅允许特定群组

json

{
  "channels": {
    "qingtui": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["group_id_1", "group_id_2"]
    }
  }
}

允许群组内的特定发送者（发送者白名单）

除了群组白名单外，还可以限制群组内哪些成员可以与智能助理交互。只有 groups.<chatId>.allowFrom 中列出的用户发送的消息才会被处理；其他成员发送的消息将被静默忽略。这是适用于所有消息的发送者级别白名单。

json

{
  "channels": {
    "qingtui": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["group_id_1"],
      "groups": {
        "group_id_1": {
          "allowFrom": ["user_id_1", "user_id_2"]
        }
      }
    }
  }
}

进阶主题

多 Agent 配置

配置多个轻推机器人连接到不同的 Agent：

json5

{
  "agents": {
    "list": [
      {
        "id": "qing-bot1",
        "name": "轻推客服机器人",
        "model": "your-model-config",
        "workspace": "~/.openclaw/workspace-bot1",
        "identity": {
          "name": "客服小助手",
          "theme": "专业客服",
          "emoji": "🤝"
        }
        // 其他 agent 配置...
      },
      {
        "id": "qing-bot2",
        "name": "轻推技术支持机器人",
        "model": "your-model-config",
        "workspace": "~/.openclaw/workspace-bot2",
        "identity": {
          "name": "技术专家",
          "theme": "技术支持",
          "emoji": "🔧"
        }
        // 其他 agent 配置...
      }
    ]
  },
  "channels": {
    "qingtui": {
      "enabled": true,
      "accounts": {
        "bot1": {
          "enabled": true,
          "appId": "bot1_app_id",
          "secret": "bot1_secret"
        },
        "bot2": {
          "enabled": true,
          "appId": "bot2_app_id",
          "secret": "bot2_secret"
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "qing-bot1",
      "match": {
        "channel": "qingtui",
        "accountId": "bot1"
      }
    },
    {
      "agentId": "qing-bot2",
      "match": {
        "channel": "qingtui",
        "accountId": "bot2"
      }
    }
  ]
}

更多详情请参考 OpenClaw 多 Agent 配置指南。

调试模式

如需查看详细日志进行调试，可以在配置中启用调试模式：

json

{
  "channels": {
    "qingtui": {
      "debug": true
    }
  }
}

然后查看日志：

bash

openclaw logs --follow

性能优化

对于高并发场景，可以考虑以下优化：

调整 WebSocket 重连策略：修改最大重连次数和重连间隔
启用消息队列：对于大量主动消息，可以实现消息队列机制
会话超时管理：合理设置会话超时时间，释放资源

📦 更新

bash

openclaw plugins update qingtui-openclaw-plugin

查看更新日志

查看可用版本：

bash

npm view @qingtui/qingtui-openclaw-plugin versions

卸载插件

bash

openclaw plugins uninstall qingtui-openclaw-plugin

项目结构

text

qingtui-openclaw-plugin/
├── src/
│   ├── channel.ts          # 频道主逻辑
│   ├── ws-client.ts        # WebSocket 客户端
│   ├── message-parser.ts   # 消息解析器
│   ├── message-sender.ts   # 消息发送器
│   ├── media-handler.ts    # 媒体文件处理器
│   ├── state-manager.ts    # 状态管理器
│   ├── timeout.ts          # 超时处理
│   ├── utils.ts            # 工具函数
│   ├── logger.ts           # 日志模块
│   ├── const.ts            # 常量定义
│   ├── interface.ts        # 接口定义
│   ├── dm-policy.ts        # 私聊策略
│   ├── group-policy.ts     # 群聊策略
│   ├── reqid-store.ts      # 请求 ID 存储
│   ├── runtime.ts          # 运行时管理
│   ├── setup-core.ts       # 核心设置
│   ├── setup-surface.ts    # 界面设置
│   └── onboarding.ts       # 入门引导
├── index.ts                # 插件入口
├── openclaw.plugin.json    # 插件清单
├── package.json            # npm 依赖
└── README.md               # 项目文档

依赖

包	用途
`socket.io-client`	WebSocket 客户端库
`file-type`	文件类型检测

开发依赖：

包	用途
`openclaw`	OpenClaw SDK
`rollup`	打包工具
`typescript`	TypeScript 编译器

许可证

MIT

支持

问题反馈：GitHub Issues
官方文档：轻推智能助理开发文档
更新日志：查看 Git History
GitHub 仓库：nudgeandroid/qingtui-openclaw-plugin

qingtui

Install

轻推 OpenClaw 插件

📋 目录

前置要求

1. OpenClaw Gateway

⚠️ 版本兼容性要求

2. 轻推智能助理账号

功能特性

✅ 核心功能

🚀 快速开始

操作系统支持

步骤 1：安装插件

方法 A：通过 npm 包安装（推荐）

方法 B：通过本地源码安装

方法 C：手动安装

方法 D：国内网络环境安装（npm 镜像源）

步骤 2：获取轻推智能助理凭证

2.1 访问开发平台

2.2 创建应用

步骤 3：配置 OpenClaw

方式 A：配置向导（推荐新手使用）

方式 B：CLI 快速设置

方式 C：编辑配置文件

步骤 4：重启并测试

配置说明

基础配置

高级配置

完整配置示例

常见问题

机器人不回复

WebSocket 连接失败

配对码问题

访问控制

私聊 (Direct Message) 访问

批准配对

白名单模式

开放模式

禁用模式

群聊访问

群聊策略 (channels.qingtui.groupPolicy)

群聊配置示例

允许所有群组（默认行为）

仅允许特定群组

允许群组内的特定发送者（发送者白名单）

进阶主题

多 Agent 配置

调试模式

性能优化

📦 更新

查看更新日志

卸载插件

项目结构

依赖

许可证

支持

群聊策略 (`channels.qingtui.groupPolicy`)