Stats
Actions
Available In
Tags
ClaudeClaw for QQ
将你的 Claude Code 转换为在后台持久运行的 QQ 机器人 — 类似 OpenClaw，但免费、本地运行，且完全由你掌控。
这是什么？
这是 ClaudeClaw 的一个分支，集成了 QQ 官方机器人 API。它允许你：
- 将 Claude Code 连接到 QQ — 直接在 QQ 上与 AI 助手聊天（C2C 私信、群组 @提及、频道消息）
- 24/7 后台运行 — 作为守护进程，始终监听你的消息
- 无 API 额外开销 — 直接使用你现有的 Claude Code / Claude Max 订阅
- 多通道支持 — QQ + Telegram + Discord，全部同时支持
工作原理
┌─────────────┐ WebSocket ┌──────────────────┐ CLI invoke ┌─────────────┐
│ QQ Official │ ◄──────────────► │ ClaudeClaw │ ◄────────────────► │ Claude Code │
│ Bot Gateway │ Events / Send │ Daemon (Bun) │ --resume mode │ Session │
└─────────────┘ └──────────────────┘ └─────────────┘
│
┌─────┴─────┐
│ Telegram │
│ Discord │
│ Web UI │
│ Cron Jobs │
└───────────┘
ClaudeClaw 通过 WebSocket 网关连接到腾讯 QQ 官方机器人 API，实时接收消息，并使用 --resume 调用 Claude Code CLI，在消息之间保持对话上下文。
QQ 机器人功能
| 功能 | 状态 |
|---|---|
| C2C（私聊）消息 | 支持 |
| 群组 @提及 消息 | 支持 |
| 频道 @提及 消息 | 支持 |
| 频道私信 | 支持 |
| 斜杠命令（/start、/reset） | 支持 |
| 图片附件 | 支持 |
| 文件附件（接收） | 支持（所有场景） |
| 文件回传（发送） | C2C 全支持；群聊/频道仅限图片和视频 |
| 消息分割（>2000 字符） | 自动 |
| 正在输入指示器 | 自动 |
| 自动重连 | 是（指数退避） |
| 用户白名单（union_openid） | 支持 |
| 群组监听模式（无需 @提及） | 支持 |
| 启动型定时任务（launch jobs） | 支持 |
| 定时结果回发到原 QQ 对话 | 私聊、群聊支持 |
| Linux crontab 调度 | 支持 |
定时任务
Claude 可以在 QQ 回复中输出一个 <qq-launch-job> 任务块，系统会自动把它落地为 launch job，并用 Linux crontab 调度执行。
当前支持的创建入口：
- C2C 私聊
- 群聊消息
当前支持的回发目标：
- 私聊
private - 群聊
group
任务声明格式：
<qq-launch-job>
name: daily-report
schedule: 0 9 * * *
recurring: true
prompt:
生成今日 AI 行业日报
</qq-launch-job>
prompt 同时兼容两种写法：
prompt: 单行内容prompt:后接多行正文
任务落地位置：
- job 文件：
.claude/claudeclaw/jobs/*.md - 执行日志：
.claude/claudeclaw/logs/ - cron 标记：
# claudeclaw:launch:<job-name>
手动执行入口：
bun run src/index.ts run-job <job-name>
行为说明：
- 定时任务使用固定项目目录作为
cwd - 执行结果会格式化后回发到创建时的 QQ 会话
recurring: false的 one-shot 任务执行后会自动移除 cron 条目- 私聊任务保存并回发使用
user_openid - launch 模式目前依赖 Linux
crontab
文件处理
用户可以通过 QQ 向 Bot 发送文件，Claude 会读取并处理文件内容，处理结果文件会自动发送回 QQ。
工作流程：
- 用户发送文件附件 + 文字说明（例如"帮我分析这个 PDF"）
- Bot 将收到的文件下载到
~/tmp/ - Claude 从
~/tmp/或~/下其他路径读取文件并处理 - Claude 将结果文件写入
~/tmp/或其他~/路径 - Bot 扫描工作区并发送本轮新生成的文件
- 文件会保留，供后续对话继续使用，直到被明确删除
QQ 官方频道机器人文件发送 API 限制：
| 文件类型 | 支持格式 | C2C 私聊 | 群聊 | 频道 |
|---|---|---|---|---|
| 图片 | png, jpg | 支持 | 支持 | 支持 |
| 视频 | mp4 | 支持 | 支持 | 支持 |
| 语音 | silk, wav, mp3, flac | 支持 | 不支持 | 不支持 |
| 文件 | pdf, doc, txt 等 | 支持 | 不支持 | 不支持 |
注意： QQ 官方 Bot API 对群聊和频道场景不支持发送语音和通用文件（pdf/doc/txt 等）。在这些场景下，Bot 只能回传图片和视频。如需 Claude 返回文档类结果，请使用 C2C 私聊。
快速开始
前置要求
第一步：克隆并安装
git clone https://github.com/YYMLVU/claudeclaw_for_qq.git
cd claudeclaw_for_qq
bun install
第二步：配置 QQ 机器人
在项目目录下创建设置文件 .claude/claudeclaw/settings.json：
{
"model": "",
"api": "",
"fallback": { "model": "", "api": "" },
"agentic": { "enabled": false, "defaultMode": "implementation", "modes": [] },
"timezone": "Asia/Shanghai",
"timezoneOffsetMinutes": -480,
"heartbeat": {
"enabled": false,
"interval": 15,
"prompt": "",
"excludeWindows": [],
"forwardToTelegram": true
},
"telegram": { "token": "", "allowedUserIds": [] },
"discord": { "token": "", "allowedUserIds": [], "listenChannels": [] },
"qq": {
"appId": "YOUR_QQ_BOT_APP_ID",
"clientSecret": "YOUR_QQ_BOT_CLIENT_SECRET",
"allowedUserIds": [],
"groupOpenIds": []
},
"security": { "level": "moderate", "allowedTools": [], "disallowedTools": [] },
"web": { "enabled": false, "host": "127.0.0.1", "port": 4632 },
"stt": { "baseUrl": "", "model": "" }
}
