OpenClaw 实战指南

Appearance

7.5 QQ 接入 ​

QQ 是国内用户量最大的 IM 工具之一，尤其在年轻用户群体中拥有大量活跃用户。

把 OpenClaw 接入 QQ，可以让 AI 助手在 QQ 中回答问题、处理任务，支持私聊、群聊、频道消息等多种场景。

前提条件 ​

在开始之前，确保你已经完成：

  • 拥有一个 QQ 账号
  • OpenClaw 已安装并正常运行（安装方式参考第 3 章）

⚠️ 重要：本地安装 OpenClaw 仅支持 Mac 系统，暂不支持 Windows。如果不想本地安装，可以使用阿里云的 OpenClaw 一键部署。

第一步：创建 QQ 机器人 ​

1.1 进入 QQ 开放平台 ​

  1. 访问 QQ 开放平台
  2. 使用手机 QQ 扫描二维码登录
  3. 如果是首次使用，扫描后会自动完成注册并绑定 QQ 账号

1.2 创建机器人 ​

  1. 登录后，点击 创建机器人
  2. 填写机器人名称、头像等信息
  3. 创建成功后，在机器人页面找到：
    • AppID
    • AppSecret

⚠️ 注意：AppSecret 不支持明文保存，如果离开页面前没有保存，需要重新生成。请务必妥善保管。

机器人创建后会自动出现在你的 QQ 消息列表中，并发送一条欢迎消息。但在完成配置前，它会回复"机器人已去火星"，表示还未接入 AI。

第二步：安装 QQ 插件 ​

运行以下命令安装 QQ 插件：

bash
openclaw plugins install @sliverp/qqbot@latest

或者从源码安装：

bash
git clone https://github.com/sliverp/qqbot.git && cd qqbot
openclaw plugins install .

第三步：配置 QQ 对接 ​

方式一：命令行配置（推荐） ​

使用 CLI 向导快速配置：

bash
openclaw channels add --channel qqbot --token "AppID:AppSecret"

将 AppID 和 AppSecret 替换为你在第一步获取的凭证。

方式二：手动配置 ​

编辑配置文件：

bash
vim ~/.openclaw/openclaw.json

添加以下配置：

json5
{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "你的AppID",
      "clientSecret": "你的AppSecret"
    }
  }
}

第四步：重启 Gateway 并测试 ​

重启 Gateway ​

配置完成后，重启 Gateway 使配置生效：

bash
openclaw gateway restart

验证 Gateway 是否正常运行：

bash
curl http://127.0.0.1:18789/health

测试机器人 ​

  1. 打开 QQ，找到你创建的机器人
  2. 发送消息测试
你：你好，请介绍一下自己

机器人：你好！我是你的 AI 助手，可以帮你回答问题、处理任务...

QQ 插件支持的功能 ​

这个插件支持丰富的功能，具体能力取决于你配置的 AI 模型和安装的技能：

功能说明
多场景私聊、群聊 @ 消息、频道消息、频道私信
富媒体发送和接收图片、语音、视频、文件
语音识别语音消息自动转文字（需要配置 STT）
语音回复AI 可以用语音消息回复（需要配置 TTS）
文件理解发送文件，AI 可以阅读并理解内容
图片理解发送图片，AI 可以描述和分析（需要视觉模型）
图片生成让 AI 画图，自动发送结果
URL 支持私聊中可以直接发送链接
Markdown完整支持 Markdown 格式
正在输入实时显示"正在输入..."状态

功能演示示例 ​

语音消息（STT）：AI 理解语音消息，自动转录为文字

你：（发送语音）"明天深圳天气怎么样？"

机器人：明天（3月7日，周六）深圳天气预报 🌤️ ...

文件理解：发送任意文件，AI 阅读并理解

你：（发送《战争与和平》TXT 文件）

机器人：收到！你上传的是列夫·托尔斯泰的《战争与和平》中文版...

图片理解：发送图片，AI 描述和分析

你：（发送一张图片）

机器人：哈哈，好可爱！是穿着龙虾服装的 QQ 企鹅吗？🦞🐧

常见问题 ​

Q: 机器人回复"已去火星" ​

说明配置还未生效，检查：

  • [ ] 插件是否安装成功
  • [ ] AppID 和 AppSecret 是否正确
  • [ ] Gateway 是否正在运行

Q: 机器人不响应 ​

检查清单：

  • [ ] Gateway 正在运行：curl http://127.0.0.1:18789/health
  • [ ] 配置文件中 enabled: true
  • [ ] AppID 和 AppSecret 正确

Q: 图片不显示或无法理解 ​

图片理解需要配置支持视觉能力的模型（如 qwen-vl、gpt-4-vision 等）。

Q: 语音消息无法转文字 ​

需要配置 STT（语音转文字）服务。在配置文件中添加：

json5
{
  "channels": {
    "qqbot": {
      "stt": {
        "provider": "your-provider",
        "model": "your-stt-model"
      }
    }
  }
}

Q: 升级后插件异常 ​

重新安装插件：

bash
openclaw plugins uninstall @sliverp/qqbot
openclaw plugins install @sliverp/qqbot@latest

实际应用场景 ​

场景一：个人学习助手 ​

在 QQ 私聊中使用：

你：帮我解释一下什么是机器学习

机器人：机器学习是人工智能的一个分支...

场景二：社群问答机器人 ​

在 QQ 群中接入机器人：

用户：@机器人 今天的天气怎么样？

机器人：【天气预报】
城市：杭州
天气：多云
气温：18-25°C
建议：适合外出

场景三：文件处理助手 ​

你：（发送一个 PDF 文件）帮我总结这个文档

机器人：【文档摘要】
这是一份关于...的报告
主要内容：
1. ...
2. ...

QQ 接入的注意事项 ​

事项说明
AppSecret 安全只显示一次，务必保存，泄露需重新生成
消息频率避免频繁发送消息，遵守平台规则
模型能力图片、语音、文件理解等能力取决于 AI 模型
系统支持本地安装仅支持 Mac，Windows 用户建议用云部署

关于微信接入 ​

微信个人号接入是非官方方案，存在封号风险，本书不做推荐。

如果你需要在微信中使用 AI 助手，推荐以下方案：

  1. WorkBuddy：微信官方推出的 AI 助手，安全可靠
  2. 企业微信：通过企业微信官方 API 接入，适合企业用户

这一节，你做了什么 ​

步骤做了什么
创建 QQ 机器人在 QQ 开放平台创建机器人，获取 AppID 和 AppSecret
安装 QQ 插件安装 @sliverp/qqbot
配置对接信息通过 CLI 或配置文件配置 QQ 渠道
测试验证在 QQ 中与机器人对话测试

下一节，我们学习如何配置多渠道路由。

基于 MIT 许可发布

Copyright © 2025 Gleam2Torch