@qingtui/qingtui-openclaw-plugin

v2026.3.28

Published

20 hours ago

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

0High
0Medium
0Low

qingtui

qingtui openclaw qingtui-openclaw-plugin

📋 目录

前置要求

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

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

1. OpenClaw Gateway

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

⚠️ 版本兼容性要求

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

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

如何检查版本：

# 检查 OpenClaw 版本
openclaw --version

# 检查插件版本
openclaw plugins list

如何升级：

# 升级 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 包安装（推荐）

openclaw plugins install @qingtui/qingtui-openclaw-plugin

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

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

# 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，可临时为该次安装指定镜像源：

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

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

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

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

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

或写入 ~/.npmrc：

registry=https://registry.npmmirror.com

验证安装：

openclaw plugins list

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

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

2.1 访问开发平台

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

2.2 创建应用

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

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

步骤 3：配置 OpenClaw

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

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

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

openclaw channels add

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

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

方式 B：CLI 快速设置

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

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

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

步骤 4：重启并测试

# 重启 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 | 是否发送"思考中"占位消息 |

完整配置示例

{
  "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，确保无空格

测试网络连接：

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

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

配对码问题

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

解决方案：

查看待处理的配对请求：
```
openclaw pairing list qingtui
```
批准配对请求：
```
openclaw pairing approve qingtui <CODE>
```

或者切换到开放模式：

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

访问控制

私聊 (Direct Message) 访问

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

批准配对

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

白名单模式

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

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

开放模式

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

禁用模式

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

群聊访问

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

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

群聊配置示例

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

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

仅允许特定群组

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

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

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

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

进阶主题

多 Agent 配置

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

{
  "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 配置指南。

调试模式

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

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

然后查看日志：

openclaw logs --follow

性能优化

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

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

📦 更新

openclaw plugins update qingtui-openclaw-plugin

查看更新日志

查看可用版本：

npm view @qingtui/qingtui-openclaw-plugin versions

卸载插件

openclaw plugins uninstall qingtui-openclaw-plugin

项目结构

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