使用说明
qqbot频道
QQ Bot MCP通道服务器的CodeBuddy代码插件。
通过MCP协议将QQ消息（C2C私聊、群聊、公会频道、公会DM）连接到CodeBuddy代码。
特性
- 消息转发 -在CodeBuddy代码中接收QQ消息作为MCP通知
- 回复 -将文字、图片、语音、视频和文件信息发送回QQ
- 预定提醒 -通过MCP工具设置和取消基于cron的提醒
- 权限中继 -将工具调用批准请求转发给QQ用户进行远程审核
- 富媒体 -完全支持图像、语音（Edge TTS+SILK编码）、视频和文件附件
- 多聊天 -支持C2C、群组、公会频道、公会DM对话
先决条件
- 支持插件的CodeBuddy代码
- QQ Bot应用程序（应用程序ID+应用程序密码） QQ开放平台
- ffmpeg/ffprobe -音频处理（语音信息编码/格式转换）所需
- 边缘tts -语音信息合成（文本到语音）所需。由自动安装
setup.sh或通过pip install edge-tts
安装ffmpeg
# Debian/Ubuntu
sudo apt install ffmpeg
# macOS
brew install ffmpeg
# Windows (via Chocolatey)
choco install ffmpeg
安装边缘tts
pip install edge-tts
# 或
pip3 install edge-tts
支持平台
| 操作系统 | 架构 | 环境 |
|---|---|---|
| Linux | x86_64，aarch64 | 本机 |
| macOS | x86_64，aarch64 | 原生 |
| Windows | x86_64，aarch64 | Git Bash/MSYS2/Cygwin |
安装
1.添加市场
codebuddy plugin marketplace add https://github.com/holy-tiger/qqbot-channel-codebuddy
2.安装插件
codebuddy plugin install qqbot-channel@qqbot-channel-codebuddy
3.启用插件
codebuddy plugin enable qqbot-channel
4.运行安装程序
手动运行安装脚本，按提示完成配置：
# 交互式安装（推荐）
bash ~/.codebuddy/plugins/cache/qqbot-channel-qqbot-channel-codebuddy/scripts/setup.sh
# 或直接传入凭证
bash ~/.codebuddy/plugins/cache/qqbot-channel-qqbot-channel-codebuddy/scripts/setup.sh YOUR_APP_ID YOUR_APP_SECRET
安装向导会依次提示输入：
| 配置项 | 说明 | 默认值 |
|---|---|---|
| appId | QQ Bot 应用 ID（https://q.qq.com 获取） | 无，必填 |
| clientSecret | QQ Bot 客户端密钥 | 无，必填 |
| Bot 名称 | 机器人显示名称 | My QQ Bot |
| System Prompt | 系统提示词 | You are a helpful assistant. |
| 私聊策略 | open / whitelist / close | open |
如需修改配置，重新运行 setup.sh 即可（会提示是否覆盖现有配置）。
文件位置
| 文件 | 路径 |
|---|---|
| qqbot 二进制 | ~/.local/bin/qqbot |
| 配置文件 | ~/.local/bin/qqbot-config.yaml |
配置
MCP工具
reply - 回复 QQ 消息
发送文本或富媒体消息到指定的会话。不设置 media_type 则发送纯文本。
| 参数 | 必填 | 说明 |
|---|---|---|
chat_id |
Yes | 会话 ID，格式见下方 chat_id Format |
text |
Yes | 要发送的文本内容。纯文本消息时为消息正文；媒体消息时为图片说明/文件描述等 |
media_type |
No | 媒体类型，可选: image (图片), file (文件), voice (语音), video (视频)。不设置则发送纯文本 |
media_url |
No | 媒体文件的 URL。media_type 为 image/file/video 时必填 |
语音消息说明: media_type 设为 voice 时，插件使用 Edge TTS 将 text 转为语音发送。请确保已安装 edge-tts（运行 setup.sh 会自动检测并安装）。无需提供 media_url。
使用示例:
# 发送纯文本
reply(chat_id="c2c:o_abc123", text="你好！")
# 发送语音（text 内容会被 Edge TTS 转为语音）
reply(chat_id="group:grp_abc123", text="这是一条语音消息", media_type="voice")
# 发送图片
reply(chat_id="c2c:o_abc123", text="看这张图", media_type="image", media_url="https://example.com/photo.jpg")
remind - 设置定时提醒
到时间后通过 qqbot 向指定会话发送文本消息。不设置 schedule 则立即发送一次。仅支持 c2c 和 group 类型会话。
| 参数 | 必填 | 说明 |
|---|---|---|
chat_id |
Yes | 会话 ID，格式: c2c:user_openid (私聊) 或 group:group_openid (群聊) |
text |
Yes | 提醒内容文本 |
schedule |
No | 定时规则。支持 @every 30m (间隔) 或 5 字段 cron 表达式。不设置则立即发送一次 |
使用示例:
# 立即发送一次
remind(chat_id="c2c:o_abc123", text="该喝水了！")
# 每 30 分钟提醒一次
remind(chat_id="c2c:o_abc123", text="该喝水了！", schedule="@every 30m")
# 使用 cron 表达式（每天 9:00）
remind(chat_id="group:grp_abc123", text="早上好！", schedule="0 9 * * *")
cancel_reminder - 取消定时提醒
取消一个已设置的定时提醒。
| 参数 | 必填 | 说明 |
|---|---|---|
job_id |
Yes | 提醒任务 ID（由 remind 工具返回） |
使用示例:
cancel_reminder(job_id="abc123")
chat_id格式
| 类型 | 格式 | 示例 |
|---|---|---|
| C2C（私人） | c2c:{user_openid} |
c2c:o_abc123 |
| 集团 | group:{group_openid} |
group:grp_abc123 |
| 公会频道 | channel:{channel_id} |
channel:12345 |
| 公会DM | dm:{channel_id} |
dm:54321 |
权限中继
启用后，来自CodeBuddy Code的工具调用批准请求将转发给QQ用户。用户回复如下 yes <id> 或 no <id> 批准或拒绝。
故障排除
二进制文件下载失败
安装脚本从GitHub发布版下载。如果失败：
- 从手动下载 qqbot go发布
- 提取
qqbot和qqbot-channel到~/.local/bin/ - 使可执行文件：
chmod +x ~/.local/bin/qqbot ~/.local/bin/qqbot-channel
手动创建配置
如果你不能跑 setup.sh，手动创建配置文件：
cat > ~/.local/bin/qqbot-config.yaml <<'YAML'
qqbot:
appId: "YOUR_APP_ID"
clientSecret: "YOUR_APP_SECRET"
enabled: true
name: "My QQ Bot"
systemPrompt: "You are a helpful assistant."
dmPolicy: "open"
YAML
市场更新失败（git pull错误128）
网络连接问题——插件市场从GitHub获取更新。如果您的网络阻止GitHub访问：
- 设置代理：
export https_proxy=http://your-proxy:port - 或者使用GitHub镜像
- 然后重试：
codebuddy plugin marketplace add https://github.com/holy-tiger/qqbot-channel-codebuddy
相关
- qqbot去 -QQ Bot API服务
- qqbot频道代码库发布
许可证
麻省理工学院