<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
• 验证安装：

  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 版本
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：

下文中出现的 ~/.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：手动安装

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

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.29) - loaded

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

2.1 访问开发平台

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

2.2 创建应用

1. 在控制台点击 "创建应用"
2. 填写应用基本信息
3. 完成创建后，你将获得：

• 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

测试你的机器人：

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

配置说明

基础配置

高级配置

完整配置示例

{
  "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 连接失败或反复重连

常见原因：

验证步骤：

1. 检查凭证：

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

1. 测试网络连接：

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

1. 重启插件：

   openclaw gateway restart

配对码问题

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

解决方案：

1. 查看待处理的配对请求：

   openclaw pairing list qingtui

1. 批准配对请求：

   openclaw pairing approve qingtui <CODE>

1. 或者切换到开放模式：

   {
     "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

性能优化

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

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

📦 更新

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               # 项目文档

依赖

开发依赖：

许可证

MIT

支持

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