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。