@onebots/adapter-icqq

onebots ICQQ 适配器 - 基于 ICQQ 协议的 QQ 机器人

📦 安装

1. 配置 GitHub Packages 访问

由于 @icqqjs/icqq 是托管在 GitHub Packages 的私有包，需要先配置访问权限。

在项目根目录的 .npmrc 文件中添加：

@icqqjs:registry=https://npm.pkg.github.com

2. 登录 GitHub Packages

npm login --scope=@icqqjs --auth-type=legacy --registry=https://npm.pkg.github.com

• UserName: 你的 GitHub 账号
• Password: 前往 https://github.com/settings/tokens/new 获取，scopes 勾选 read:packages
• E-Mail: 你的公开邮箱地址

3. 安装依赖

npm install @onebots/adapter-icqq
# 或
pnpm add @onebots/adapter-icqq

⚙️ 配置

在 config.yaml 中配置 ICQQ 账号：

# ICQQ 机器人账号配置
icqq.123456789:  # 你的 QQ 号
  # 密码登录（可选，不填则扫码登录）
  password: 'your_password'
  
  # 协议配置
  protocol:
    # 登录平台: 1=安卓手机, 2=安卓平板, 3=安卓手表, 4=MacOS, 5=iPad, 6=Tim
    platform: 2
    # 签名服务器地址（重要！未配置可能导致登录失败）
    sign_api_addr: 'http://your-sign-server:8080'
    # 数据存储目录
    data_dir: './data/icqq'
    # 群聊和频道中过滤自己的消息
    ignore_self: true
    # 被风控时是否尝试用分片发送
    resend: true
    # 触发离线事件后的重新登录间隔秒数
    reconn_interval: 5
    # 是否缓存群员列表
    cache_group_member: true
    # 自动选择最优服务器
    auto_server: true
  
  # OneBot V11 协议配置
  onebot.v11:
    access_token: 'your_v11_token'
  
  # OneBot V12 协议配置
  onebot.v12:
    access_token: 'your_v12_token'

📋 配置项说明

基础配置

| 配置项 | 类型 | 必填 | 说明 | |--------|------|------|------| | password | string | 否 | QQ 密码，不填则扫码登录 | | protocol | object | 否 | 协议配置 |

协议配置 (protocol)

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | platform | number | 2 | 登录平台 | | sign_api_addr | string | - | 签名服务器地址 | | data_dir | string | ./data | 数据存储目录 | | ignore_self | boolean | true | 群聊和频道中过滤自己的消息 | | resend | boolean | true | 被风控时是否尝试用分片发送 | | reconn_interval | number | 5 | 重新登录间隔秒数 | | cache_group_member | boolean | true | 是否缓存群员列表 | | auto_server | boolean | true | 自动选择最优服务器 | | ffmpeg_path | string | - | ffmpeg 路径 | | ffprobe_path | string | - | ffprobe 路径 |

登录平台 (platform)

| 值 | 平台 | |----|------| | 1 | 安卓手机 | | 2 | 安卓平板（推荐） | | 3 | 安卓手表 | | 4 | MacOS | | 5 | iPad | | 6 | Tim |

🔐 签名服务器

ICQQ 协议需要签名服务器才能正常登录和收发消息。签名服务器的部署请参考：

• unidbg-fetch-qsign
• 其他兼容的签名服务

配置示例：

protocol:
  sign_api_addr: 'http://127.0.0.1:8080'

🚀 使用示例

启动服务

# 注册 ICQQ 适配器和 OneBot V11 协议
onebots -r icqq -p onebot.v11

扫码登录

如果不配置密码，启动时会提示扫码登录。控制台会输出二维码图片路径或显示二维码。

滑块验证

如果触发滑块验证，控制台会输出验证链接，需要手动完成验证后将 ticket 提交。

设备锁验证

如果触发设备锁验证，控制台会输出验证链接和手机号，需要手动完成验证。

📝 支持的功能

消息类型

| 类型 | 发送 | 接收 | 说明 | |------|:----:|:----:|------| | 文本 | ✅ | ✅ | 纯文本消息 | | 表情 | ✅ | ✅ | QQ 表情 | | 图片 | ✅ | ✅ | 图片消息 | | 语音 | ✅ | ✅ | 语音消息 | | 视频 | ✅ | ✅ | 视频消息 | | @提及 | ✅ | ✅ | @某人或@全体 | | 回复 | ✅ | ✅ | 引用回复 | | 分享 | ✅ | ✅ | 链接分享 | | JSON | ✅ | ✅ | JSON 卡片 | | XML | ✅ | ✅ | XML 卡片 |

API 功能

| 功能 | 支持 | 说明 | |------|:----:|------| | 发送私聊消息 | ✅ | | | 发送群消息 | ✅ | | | 撤回消息 | ✅ | | | 获取消息 | ✅ | | | 获取好友列表 | ✅ | | | 获取群列表 | ✅ | | | 获取群成员列表 | ✅ | | | 获取群成员信息 | ✅ | | | 设置群名片 | ✅ | | | 踢出群成员 | ✅ | | | 禁言群成员 | ✅ | | | 全员禁言 | ✅ | | | 设置群管理员 | ✅ | | | 退出群 | ✅ | | | 处理好友申请 | ✅ | | | 处理群申请 | ✅ | |

事件支持

| 事件 | 支持 | 说明 | |------|:----:|------| | 私聊消息 | ✅ | | | 群消息 | ✅ | | | 好友申请 | ✅ | | | 群申请/邀请 | ✅ | | | 群成员增加 | ✅ | | | 群成员减少 | ✅ | | | 群禁言 | ✅ | | | 群管理员变动 | ✅ | | | 消息撤回 | ✅ | | | 戳一戳 | ✅ | |

⚠️ 注意事项

1. 签名服务器必须配置：ICQQ 协议需要签名服务器才能正常工作
2. 账号安全：建议使用小号测试，避免账号被封禁风险
3. 协议更新：QQ 协议可能随时更新，如遇问题请更新 ICQQ 和签名服务
4. 数据目录：建议配置独立的 data_dir，避免数据混乱

🔗 相关链接

• ICQQ GitHub
• onebots 文档
• 签名服务部署教程