npm package: @qingtui/qingtui-openclaw-plugin
Description: OpenClaw QingTui (轻推) channel plugin (official by CISDI QingTui team)
Latest version: 2026.3.28

<div align="center">
  <img alt="QingTui" src="https://www.qingtui.com/devdoc/assets/qt_logo.svg" width="72" height="72" />
  <h1>轻推 OpenClaw 插件</h1>
  <p>将轻推智能助理连接到 OpenClaw Gateway，支持 WebSocket 持久连接和流式响应</p>
  
  <p>
    <a href="https://www.qingtui.com/devdoc/zhi-neng-zhu-li-kai-fa/zhi-neng-zhu-li-kai-fa.html">官方文档</a> •
    <a href="#更新日志">更新日志</a>
  </p>
</div>

---

## 📋 目录

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

---

## 前置要求

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

> 本插件作为 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.27+ 需要 **OpenClaw SDK v2026.2.13 或更高版本**。

| 插件版本 | 最低 OpenClaw SDK 版本 | 说明 |
|---------|----------------------|------|
| v2026.3.27+ | 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. 轻推智能助理账号

- 你需要一个轻推智能助理账号来创建应用
- 访问 [轻推智能助理开发平台](https://www.qingtui.com/devdoc/) 获取 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：手动安装

1. 将本仓库下载或复制到 `~/.openclaw/extensions/qingtui-openclaw-plugin`。
2. 确保包含 `index.ts`、`openclaw.plugin.json` 和 `package.json`。
3. 在该目录下运行 `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`：

```
registry=https://registry.npmmirror.com
```

**验证安装**：
```bash
openclaw plugins list
```
你应该看到 `✓ Qingtui（轻推） channel (v2026.3.28) - loaded`

---

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

#### 2.1 访问开发平台

1. 访问 [轻推智能助理开发平台](https://www.qingtui.com/devdoc/zhi-neng-zhu-li-kai-fa/zhi-neng-zhu-li-kai-fa.html)
2. 登录你的账号

#### 2.2 创建应用

1. 在控制台点击 **"创建应用"**
2. 填写应用基本信息
3. 完成创建后，你将获得：
   - **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
```

**测试你的机器人**：
1. 打开轻推 App
2. 在联系人列表中找到你的机器人
3. 发送消息：`你好`
4. 你应该在 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
    }
  }
}
```

---

## 常见问题

### 机器人不回复

**症状**：机器人不回复消息

**解决方案**：
1. 检查插件状态：`openclaw plugins list`
2. 检查网关状态：`openclaw gateway status`
3. 查看日志：`openclaw logs --follow`
4. 确认 WebSocket 连接是否成功
5. 检查 appId 和 secret 是否正确

---

### WebSocket 连接失败

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

**常见原因**：

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

**验证步骤**：

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

2. **测试网络连接**：
   ```bash
   # 测试是否能访问轻推服务
   curl -I https://open.qingtui.com
   ```

3. **重启插件**：
   ```bash
   openclaw gateway restart
   ```

---

### 配对码问题

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

**解决方案**：
1. 查看待处理的配对请求：
   ```bash
   openclaw pairing list qingtui
   ```
2. 批准配对请求：
   ```bash
   openclaw pairing approve qingtui <CODE>
   ```
3. 或者切换到开放模式：
   ```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 配置指南](https://gist.github.com/smallnest/c5c13482740fd179e40070e620f66a52)。

---

### 调试模式

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

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

然后查看日志：

```bash
openclaw logs --follow
```

---

### 性能优化

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

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

---

## 📦 更新

```bash
openclaw plugins update qingtui-openclaw-plugin
```

### 查看更新日志

查看可用版本：
```bash
npm view @qingtui/qingtui-openclaw-plugin versions
```

### 卸载插件

```bash
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](LICENSE)

---

## 支持

- **问题反馈**：[GitHub Issues](https://github.com/nudgeandroid/qingtui-openclaw-plugin/issues)
- **官方文档**：[轻推智能助理开发文档](https://www.qingtui.com/devdoc/zhi-neng-zhu-li-kai-fa/zhi-neng-zhu-li-kai-fa.html)
- **更新日志**：查看 [Git History](https://github.com/nudgeandroid/qingtui-openclaw-plugin/commits/main)
- **GitHub 仓库**：[nudgeandroid/qingtui-openclaw-plugin](https://github.com/nudgeandroid/qingtui-openclaw-plugin)