QQ 个人号（icqq）

QQ 个人号（基于 icqq 库，QQ 安卓协议）。用真实 QQ 号直接登录（密码 / 扫码），群管理能力较全：禁言 / 移出 / 设管理 / 改群名片 / 发文件 / 点赞等。

适配器类型："icqq"　源码：src/adapter/icqq/ 协议：基于 icqq（oicq 分支，QQ 安卓协议），用 QQ 号直接登录。

icqq 是登录式机器人——用真实 QQ 号登录，需要处理扫码/设备锁/滑块验证。QQ 协议（安卓端）属于非官方协议，账号有被限制风险，请自行评估使用。

说明

特点

用真实 QQ 号直接登录（密码或扫码）
群管理能力全面：禁言、移出、设管理、改群名片、发文件、点赞
支持文本、图片、语音、视频、文件、引用、@、表情、合并转发等
登录 token 本地保存，首次验证后免重新登录

原理

登录：icqq 库模拟 QQ 安卓协议登录，支持密码和扫码两种方式
接收：icqq 事件回调（message.group / message.private / notice / request）
发送：调用 icqq 客户端方法（sendGroupMsg / sendPrivateMsg 等）

前提

一个可登录的 QQ 号
建议自建 qsign 签名服务器（未配置可能登录失败/无法收发）
密码登录需处理设备锁验证；扫码登录需用手机 QQ 扫码

安装

适配器安装

bash

van adapter install icqq

依赖库

bash

npm install icqq

配置

jsonc

{
  "botId": "Icqq-Bot",
  "type": "icqq",
  "account": 123456789,
  "password": "",
  "platform": 1,
  "dataDir": "",
  "signApiAddr": "",
  "qrcodeDir": "",
  "logLevel": "error",
  "ignoreSelf": true
}

配置项	必填	说明
`account`	✅	QQ 号
`password`	可选	填了走密码登录（安卓协议），为空走扫码登录（Watch 协议）
`platform`	可选	登录协议：1=安卓(默认) 2=安卓平板 3=手表(可扫码) 4=MacOS 5=iPad 6=Tim
`dataDir`	可选	数据目录（设备信息/会话 token），默认 icqq 的 ./data
`signApiAddr`	可选	签名服务器地址（建议自建 qsign）
`qrcodeDir`	可选	扫码时二维码图片保存目录，默认 ./data/icqq_qrcode
`logLevel`	可选	icqq 内部日志级别，默认 error
`ignoreSelf`	可选	忽略机器人自己发的消息，默认 true

登录方式

密码登录：填 password，走安卓协议，首次验证设备后长期有效
扫码登录：不填 password，启动后控制台打印二维码 URL，用手机 QQ 扫码
滑块验证：触发时控制台打印 URL，浏览器打开完成验证
设备锁：触发时用手机 QQ 打开提示链接完成验证后自动登录

接收事件

icqq 事件	框架事件	说明
`message.group`	`group_message`	群消息（`groupId`=群号、`userId`=QQ号）
`message.private`	`private_message`	私聊（好友/群临时会话）
`notice.group.*`	`notice`	群通知（加人/退群/撤回/戳一戳/禁言/管理变更/转让）
`notice.friend.*`	`notice`	好友通知（加好友/删好友/撤回/戳一戳）
`request.friend`	`request`	好友申请
`request.group.add` / `request.group.invite`	`request`	加群申请 / 群邀请

消息段

类型	消息段
文本	`text`
@某人	`at`（qq, name）
表情	`face`（id）
图片/闪照	`image`（url, file, flash?）
语音	`record`（url, file）
视频	`video`（url, file）
引用回复	`reply`（id, text）
JSON/XML 卡片	`json` / `xml`
链接分享	`share`
文件	`file`（name, fid）
合并转发	`forward`（nodes）

用户昵称/群名片：event.raw.sender.nickname、event.raw.sender.card、event.raw.sender.role。

API 调用

适配器自动把 OneBot 风格 action 映射到 icqq 方法：

action	说明
`send_group_msg`	发群消息
`send_private_msg`	发私聊
`send_msg`	有 group_id 走群，否则私聊
`send_temp_msg`	群临时会话
`delete_msg`	撤回
`get_group_list`	群列表
`get_group_member_list`	群成员列表
`get_group_member_info`	群成员资料
`set_group_kick`	踢人
`set_group_ban`	禁言（秒，0=解除）
`set_group_whole_ban`	全员禁言
`set_group_admin`	设置管理员
`set_group_card`	设置群名片
`set_group_name`	设置群名
`send_like`	点赞
`send_group_file`	发群文件（本地路径）

await bot.callApi("send_group_msg", { group_id: 123456789, message: "你好" })
await bot.callApi("send_private_msg", { user_id: 123456, message: "你好" })
await bot.callApi("set_group_ban", { group_id: 123456789, user_id: 123456, duration: 600 })

发送时 image/record/video 的 file 支持本地路径或 URL（URL 自动下载再发送）；at 的 qq 为 "all" 时发 @全体。markdown / button 段不支持。

常见问题

扫码时一直刷"获取二维码失败"：icqq 0.6.x 依赖签名服务器，请配置 signApiAddr（自建 qsign）。
登录不上：icqq 属非官方协议，QQ 风控严格。优先密码登录 + 自建签名服务器。
dataDir 的作用：存放设备信息与登录 token，首次登录后不要删除。
收不到自己的消息：ignoreSelf 默认 true 过滤自己发的消息。
合并转发：能收到（forward 段），但发送暂不支持。

QQ 个人号（icqq） ​

说明 ​

特点 ​

原理 ​

前提 ​

安装 ​

适配器安装 ​

依赖库 ​

配置 ​

登录方式 ​

接收事件 ​

消息段 ​

API 调用 ​

常见问题 ​

相关项目 ​