QQ 机器人

用 QQ 官方机器人 向 zqagent 发起任务，并在任务完成时通过 邮件（SMTP） 通知你。支持单聊、群聊（@机器人）、频道，以及审批 / 提问 / 中断等完整交互。

官方机器人走出站长连接，无需公网入站，自建/内网服务器也能收消息。

平台准备（一次性）

在 QQ 开放平台注册并创建机器人，获得 AppID + AppSecret。
申请 GROUP_AND_C2C_EVENT（1<<25） 等 intents 权限（单聊+群聊消息事件属特殊权限，需申请；否则网关鉴权会拒绝）。频道 @ 与频道私信分别对应 PUBLIC_GUILD_MESSAGES（1<<30）与 DIRECT_MESSAGE（1<<12）。
联调阶段使用沙箱环境（仅沙箱成员可测试），正式上线需审核。

配置

方式一：.env 环境变量（启动时读入）

bash

# .env
QQ_BOT_APP_ID=你的AppID
QQ_BOT_APP_SECRET=你的AppSecret
QQ_BOT_SANDBOX=1          # 沙箱=1；正式环境=0 或留空

方式二：热配置（server 已启动时，无需重启，立即重连生效）

bash

# 查看当前配置（脱敏）
curl -s -H "Authorization: Bearer <租户apiKey>" http://localhost:8787/api/v1/qq/config

# 配置 / 更新
curl -s -X POST -H "Authorization: Bearer <租户apiKey>" -H "Content-Type: application/json" \
  -d '{"appId":"你的AppID","appSecret":"你的AppSecret","sandbox":true}' \
  http://localhost:8787/api/v1/qq/config

# 删除配置（断开）
curl -s -X DELETE -H "Authorization: Bearer <租户apiKey>" http://localhost:8787/api/v1/qq/config

设置后日志出现 QQ 机器人: 已启用。热配置会随服务端保存，重启后仍生效（配置来源优先级：环境变量 > 保存的配置）。

多租户绑定

方式一：单租户免绑定（推荐个人使用）

系统只有一个租户（如默认的 demo）时，无需任何绑定操作，直接发消息即自动绑定到唯一租户并开始任务。

方式二：配对码绑定（多租户）

bash

# 生成配对码（管理员，REST API）
curl -X POST http://localhost:8787/api/v1/qq/pairing-code \
  -H "Authorization: Bearer <租户apiKey>"
# → { "data": { "code": "AB3CD5K7", "expiresIn": 300 } }

用户在 QQ 内绑定：

/bind AB3CD5K7
→ 绑定成功 ✅ 租户：demo。现在直接发消息即可开始任务。

配对码 5 分钟有效、单次使用（避免 apiKey 明文进入聊天记录）。
每个 QQ 会话对应一个租户 + 一个 zqagent session；首次发任务时自动创建会话。
绑定映射落盘于 {DATA_DIR}/qq/bindings.json。

命令列表

命令	行为
直接发消息	提交任务（等待提问时作为答案；任务运行中则作为补充信息）
`/bind <配对码>`	绑定当前 QQ 会话到租户
`/unbind`	解除绑定
`/new`	新建会话并切换绑定
`/status`	查看当前会话状态
`/list`	会话列表
`/stop`	中断当前任务
`/approve <once\|always_tool\|always_command\|deny>`	审批（也可直接发「同意/全部同意/拒绝」）
`/answer <内容>`	回答提问
`/help`	帮助

任务运行中直接发消息，会作为**补充信息（steering）**注入当前任务；需要另起任务时请先 /stop 或等任务结束。

通知回发与审批

任务执行中的关键事件会回发到对应 QQ 会话。审批请求会附上工具名 + 工具参数 + 原因：

需要审批：write_file
参数：
{
  "path": "/tmp/a.txt",
  "content": "hello"
}
原因：需要写文件
回复：同意(仅本次) / 全部同意(总是允许) / 拒绝

同意 / 允许 / y → 仅本次允许（once）
全部同意 / 总是允许 → 本会话内总是允许该工具（always_tool）
拒绝 / n → 拒绝（deny）

⚠️ QQ 官方机器人对主动消息有严格配额；任务完成通常超出「被动回复 5 分钟窗口」，因此完成通知以邮件为可靠通道，QQ 内回发尽力而为。

配置邮件通知

bash

curl -X POST http://localhost:8787/api/v1/notifications \
  -H "Authorization: Bearer <租户apiKey>" -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "enabled": true,
    "config": {
      "host": "smtp.qq.com",
      "port": "465",
      "secure": "true",
      "user": "you@qq.com",
      "pass": "<QQ邮箱授权码>",
      "from": "you@qq.com",
      "to": "you@qq.com"
    },
    "events": { "approval": false, "question": false, "completed": true, "error": true }
  }'

QQ 邮箱：smtp.qq.com:465（SSL）+ 授权码（不是登录密码）。
163：smtp.163.com:465；Gmail：smtp.gmail.com:587（secure:"false"）。
pass 等敏感字段会用 SECRET_KEY AES 加密落盘。
events 控制触发时机；上例只在「完成/错误」时发邮件。
短任务不打扰：minDurationSeconds（默认 60）——任务成功完成且执行时长未超过该阈值时不发邮件。

QQ 机器人 ​

平台准备（一次性） ​

配置 ​

多租户绑定 ​

命令列表 ​

通知回发与审批 ​

配置邮件通知 ​

QQ 机器人

平台准备（一次性）

配置

多租户绑定

命令列表

通知回发与审批

配置邮件通知