QQ Bot channel plugin for Claude Code
npx claudepluginhub hank9999/claude-qq-channelQQ Bot channel for Claude Code — messaging bridge with built-in access control. Manage pairing, allowlists, and policy via /qqbot:access.
Share bugs, ideas, or general feedback.
QQ Bot channel plugin for Claude Code — 将 QQ 私聊消息桥接到 Claude Code 会话,支持双向对话、文件附件和完整的访问控制。
QQ 用户 ──私聊──▶ QQ 开放平台 ──WebSocket──▶ channel server ──stdio──▶ Claude Code
◀── reply tool ──
<channel> 事件推送到 Claude Code 会话reply tool 回复,消息经 QQ Bot API 发回给用户curl -fsSL https://bun.sh/install | bash1. 获取 QQ Bot 凭证
前往 QQ 开放平台 点击龙虾专用入口,扫码登录。创建一个机器人应用,在应用管理页面获取 AppID 和 AppSecret。
2. 安装插件
以下为 Claude Code 命令 — 先运行 claude 启动会话。
/plugin marketplace add hank9999/claude-qq-channel
/plugin install qqbot@claude-qq-channel
3. 配置凭证
/qqbot:configure <AppID>:<AppSecret>
凭证保存到 ~/.claude/channels/qqbot/.env。也可以手动写入该文件,或在启动 Claude Code 前设置环境变量 QQBOT_CREDENTIALS=AppID:AppSecret。
4. 启动 channel
退出当前会话,使用 channel 标志重新启动:
claude --dangerously-load-development-channels plugin:qqbot@claude-qq-channel
5. 配对
在上一步启动的 Claude Code 会话中,用 QQ 向你的 Bot 发送任意私聊消息 — Bot 会回复一个配对码。在 Claude Code 中运行:
/qqbot:access pair <code>
你的下一条 QQ 私聊消息就会到达 Claude。
6. 锁定访问
配对完成后,切换到 allowlist 模式,阻止陌生人触发配对码:
/qqbot:access policy allowlist
channel 采用白名单机制保护:只有经过配对批准的 QQ 用户才能向 Claude 发送消息。
| 命令 | 说明 |
|---|---|
/qqbot:access | 查看当前状态:策略、白名单、待配对列表 |
/qqbot:access pair <code> | 批准配对请求 |
/qqbot:access deny <code> | 拒绝配对请求 |
/qqbot:access allow <openid> | 手动添加用户到白名单 |
/qqbot:access remove <openid> | 从白名单移除用户 |
/qqbot:access policy <mode> | 设置策略:pairing、allowlist、disabled |
| 策略 | 行为 |
|---|---|
pairing(默认) | 未知用户发消息会收到配对码,等待终端批准。适合初始设置阶段 |
allowlist | 仅白名单中的用户可发消息,其他人静默丢弃。推荐的长期策略 |
disabled | 所有消息静默丢弃 |
| 工具 | 用途 |
|---|---|
reply | 回复 QQ 消息。传入 chat_id + text,可选 msg_id(被动回复)和 files(绝对路径,附件)。长文本自动分段(单条上限 2000 字符),支持图片和文件附件,单文件上限 50MB。 |
download_attachment | 下载 QQ 消息中的附件到 ~/.claude/channels/qqbot/inbox/。当 <channel> 标签包含 attachment_count 时使用。 |
收到消息时自动发送输入状态提示。
附件不会自动下载。<channel> 通知中列出附件名称、类型和大小 — Claude 在需要时调用 download_attachment 获取文件,下载到 ~/.claude/channels/qqbot/inbox/。
所有状态文件位于 ~/.claude/channels/qqbot/:
| 文件 | 说明 |
|---|---|
.env | Bot 凭证(QQBOT_CREDENTIALS=AppID:AppSecret) |
access.json | 访问控制状态:策略、白名单、待配对列表 |
session.json | WebSocket session 信息(用于断线恢复) |
inbox/ | 下载的附件文件 |
approved/ | 配对批准标记(channel server 轮询后自动清理) |
allowlist 策略.env 文件权限为 600,仅当前用户可读。不要将凭证提交到版本控制reply tool 禁止发送 channel 状态目录中的文件(inbox/ 除外),防止泄露 access.json 等敏感信息channel server 在启动时读取 .env。更新凭证后需要重启 Claude Code 会话,或运行 /reload-plugins。