自搭建指南/QQ

本文将包含你将机器人连接 QQ 平台时所需要了解的内容。

说明

目前，大多数群聊中的 QQ 机器人都采用“伪用户”的方式，即通过第三方软件接入已注册的 QQ 账号。从 QQ 官方的角度来看，这些软件属于“外挂软件”，QQ 官方对此类实现采取了各种技术和非技术手段进行打击。

QQ 官方会监测账号行为以区分正常用户和机器人，例如检测异常登录方式或频繁的多地区登录等。虽然具体的检测细节未知，但已经确认的是，当 QQ 账号被识别为机器人时，可能会面临警告、封禁，甚至临时或永久冻结的处罚。

虽然不同方案之间存在较大差异（例如基于 Android QQ 协议的 Go-cqhttp 已基本无法使用，而基于 NTQQ 协议的 Lagrange 和 LLOneBot 方案则较为稳定），但这些方案均由第三方软件社区提供，并不受到官方支持。

因此，是否在 QQ 平台上搭建非官方机器人需要谨慎考虑。同时，第三方方案的可用性可能会随时间变化，我们无法提供任何保证。在 QQ 平台上选择使用何种方案取决于个人意愿。

危险

如果出现 QQ 账号被冻结等情况，我们无力解决此类问题，也不会为相应后果负责。

Lagrange

Lagrange 是一个 NTQQ 协议相关的开源项目。包括目前实现 Linux NTQQ 协议的 Lagrange.Core 和提供 OneBot-V11 API 的 Lagrange.Onebot 两部分。

下载与安装

如果你想使用 Docker 搭建 Lagrange，请转到使用 Docker。

推荐前往 Github Actions，找到 Lagrange.OneBot Release，点击最新的工作流，下拉找到并下载合适的版本。

或者从 Lagrange 的 GitHub Release 上下载 Nightly 版本。

系统类型	压缩文件
Intel 版 MacOS	Lagrange.OneBot_osx-x64_8.0.zip
M1 版 MacOS	Lagrange.OneBot_osx-arm64_8.0.zip
64 位 Linux	Lagrange.Onebot_linux-x64_8.0.zip
arm64 Linux	Lagrange.OneBot_linux-arm64_8.0.zip
armv7 Linux	Lagrange.OneBot_linux-arm_8.0.zip
64 位 Linux (musl)	Lagrange.Onebot_linux-musl-x64_8.0.zip
arm64 Linux (musl)	Lagrange.OneBot_linux-musl-arm64_8.0.zip
armv7 Linux (musl)	Lagrange.OneBot_linux-musl-arm_8.0.zip
32 位 Windows	Lagrange.OneBot_win-x86_8.0.zip
64 位 Windows	Lagrange.OneBot_win-x64_8.0.zip

解压下载好的文件到一个已经预先准备好的文件夹中。

运行 Lagrange。此时将提示：

No exist config file, create it now...
Please Edit the appsettings.json to set configs and press any key to continue

程序将会自动在存放 Lagrange 文件夹的目录下生成一个默认配置文件 appsettings.json。

配置

请在机器人配置文件填写以下配置项：

qq_account = - 机器人的 QQ 号。

qq_host = "127.0.0.1:11451" - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 Lagrange 反向连接。

qq_frame_type = "Lagrange" - 告诉机器人正在使用 Lagrange，以处理兼容性问题。

接下来，请在 Lagrange 的配置文件中设置对应的连接方式。

 {
  ...
  // Linux NTQQ 签名服务，不可与 Android QQ 签名服务混用
  "SignServerUrl": "https://sign.lagrangecore.org/api/sign",
  ...
  "Message": {
    ...
    // 使用 CQ 码进行消息上报
    "StringPost": true
  },
  ...
  "Implementations": [
    {
      // 使用反向 WebSocket 服务
      "Type": "ReverseWebSocket",
      // 此处填写先前的 IP 地址和端口
      "Host": "127.0.0.1",
      "Port": 11451,
      "Suffix": "/ws",
      ...
    }
    ...
  ]
}

提示

请删除 JSON 文件的所有注释，否则无法正常读取。

修改完文件后扫码登录即可。

提示

若在配置中遇到问题，请参见 Lagrange README 文件。

LLOneBot

LLOneBot 是 Liteloader 的插件之一，可以使 NTQQ 支持 OneBot11 协议进行 QQ 机器人开发。

LiteLoaderQQNT（LiteLoader）是 NTQQ 的插件加载器，允许通过插件注入 QQ 实现某些特定的功能。

安装

请参考官方文档中的说明进行插件的安装。

配置

请在机器人配置文件填写以下配置项：

qq_account = - 机器人的 QQ 号。

qq_host = "127.0.0.1:11451" - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 LLOnebot 反向连接。

qq_frame_type = "LLOneBot" - 告诉机器人正在使用 LLOneBot，以处理兼容性问题。

安装 LLOneBot 完成后重新登录 QQ，进入 LLOneBot 的设置页。

打开“启用反向 Websocket 服务”，点击下方的“添加”，并添加好反向 Websocket 监听地址。在示例中为 ws://127.0.0.1:11451/ws，注意不要删去后面的 /ws。

将“新消息上报格式类型”更改为“CQ 码”。

关闭设置窗口，确认配置文件保存。

NapCatQQ

NapCatQQ 是在后台低占用运行的无头（没有界面）NTQQ 机器人框架。

注意相同账号不能同时登录原版 QQ 和 NapCatQQ。

安装

请根据 NapCatQQ 手册安装官方 QQ，若 QQ 版本过低可能会导致程序无法正常启动。

从 NapCatQQ 的 GitHub Release 下载最新的版本。

配置

请在机器人配置文件填写以下配置项：

qq_account = - 机器人的 QQ 号。

qq_host = "127.0.0.1:11451" - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 NapCatQQ 反向连接。

qq_frame_type = "NapCatQQ" - 告诉机器人正在使用 NapCatQQ，以处理兼容性问题。

安装 NapCatQQ 完成后，你需要修改 config/onebot11.json 的内容，并重名为 onebot11_<机器人 QQ 号>.json。

接下来，请在 NapCatQQ 的配置文件中设置对应的连接方式。

{
    ...
    "reverseWs": {
        // 是否启用反向websocket服务
        "enable": true,
        // 反向websocket对接的地址, 如["ws://127.0.0.1:8080/onebot/v11/ws"]
        "urls": ["ws://127.0.0.1:11451/ws"]  // 此处填写先前的 IP 地址和端口，注意不要删去后面的“/ws”   
    },
    ...
    // 消息上报格式，array为消息组，string为cq码字符串
    "messagePostFormat": "string",
    ...
}

提示

请删除 JSON 文件的所有注释，否则无法正常读取。

也可以使用 WebUI 进行配置，详见 NapCat 手册。

修改完文件后请根据 NapCatQQ 教程启动程序，扫码登录即可。

OpenShamrock

OpenShamrock 是基于 Xposed 实现的 QQ 机器人框架，你可以在 Android 手机 / 模拟器中使用 OpenShamrock 运行机器人。

危险

2024 年 8 月 12 日，OpenShamrock 于 GitHub 中的存储库已被归档，开发者已无力继续维护此项目。

危险

2024 年 4 月 2 日，OpenShamrock 开发组于 openshamrock/discussion#272 宣布，OpenShamrock 将会从 1.1.0 版本起弃用 OneBot V11 支持，迁移至新的 Kritor 协议。
这意味着 1.1.0 及之后版本的 OpenShamrock 将不再支持 OneBot V11，以下内容也不再适用。请仔细辨别，以免带来不必要的困扰。

警告

此方式需要一定的安卓（Android）的开发基础，可能需要对 Root、命令行等有一定了解。

安装

请参考官方文档中的说明进行框架的安装。

警告

本文不会涉及对 Root 手机的说明，也不会对 Root 手机造成的任何后果负责。

配置

请在机器人配置文件填写以下配置项：

qq_account = - 机器人的 QQ 号。

qq_host = "127.0.0.1:11451" - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 OpenShamrock 反向连接。

qq_frame_type = "OpenShamrock" - 告诉机器人正在使用 OpenShamrock，以处理兼容性问题。

安装 OpenShamrock 完成后，请配置以下选项：

打开“消息格式为 CQ 码”和“被动 WebSocket”，并添加好被动 Websocket 监听地址。在示例中为 ws://127.0.0.1:11451/ws，注意不要删去后面的 /ws。

强制杀死 QQ 进程并重新启动 QQ 来应用 OpenShamrock 配置文件。

Go-cqhttp

Go-cqhttp 是基于 Mirai 以及 MiraiGo 的 OneBot Golang 原生实现。是基于 QQ Android 协议支持的机器人框架库。

一个新注册的 QQ 账号仅需完成基础配置即可，但为了避免在机器人使用后期时遇到 Code45 等问题，建议配置使用签名服务器。

危险

根据 go-cqhttp/issue#2471，开发者已无力继续维护此项目。
在未来 qsign 签名服务彻底被官方封死之后，Go-cqhttp 将无法继续使用，请窒息。

危险

由于 QQ 官方的持续检测，使用 Go-cqhttp 连接的成功率越来越低。即使成功连接，也可能面临频繁冻结等情况。不推荐任何用户再使用此方案连接 QQ 平台。

下载与安装

如果你想使用 Docker 部署 Go-cqhttp，请转到使用 Docker。

从 Go-cqhttp 的 GitHub Release 下载最新的版本。

系统类型	可执行文件	压缩文件
Intel 版 MacOS	N/A	go-cqhttp_darwin_amd64.tar.gz
M1 版 MacOS	N/A	go-cqhttp_darwin_arm64.tar.gz
32 位 Linux	N/A	go-cqhttp_linux_386.tar.gz
64 位 Linux	N/A	go-cqhttp_linux_amd64.tar.gz
arm64 Linux	N/A	go-cqhttp_linux_arm64.tar.gz
armv7 Linux	N/A	go-cqhttp_linux_armv7.tar.gz
32 位 Windows	go-cqhttp_windows_386.exe	go-cqhttp_windows_386.zip
64 位 Windows	go-cqhttp_windows_amd64.exe	go-cqhttp_windows_amd64.zip
arm64 Windows	go-cqhttp_windows_arm64.exe	go-cqhttp_windows_arm64.zip
armv7 Windows	go-cqhttp_windows_armv7.exe	go-cqhttp_windows_armv7.zip

解压下载好的文件到一个已经预先准备好的文件夹中。

运行 Go-cqhttp。此时将提示：

[WARNING]: 尝试加载配置文件 config.yaml 失败: 文件不存在。
[INFO]: 默认配置文件已生成，请编辑 config.yaml 后重启程序。

程序将会自动在存放 Go-cqhttp 文件夹的目录下生成一个默认配置文件 config.yaml。请填写好配置文件中的 QQ 账号和密码。

基础配置

请在机器人配置文件填写以下配置项：

qq_account = - 机器人的 QQ 号。

qq_host = "127.0.0.1:11451" - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 Go-cqhttp 反向连接。

接下来，请在 Go-cqhttp 的配置文件中设置对应的连接方式。

    ...
    # 连接服务列表
    servers:
      # 添加方式，同一连接方式可添加多个，具体配置说明请查看文档
      #- http: # http 通信
      #- ws:   # 正向 Websocket
      #- ws-reverse: # 反向 Websocket
      #- pprof: # 性能分析服务器
      - ws-reverse:
          universal: ws://127.0.0.1:11451/ws # 此处填写先前的 IP 地址和端口，注意不要删去后面的“/ws”
          reconnect-interval: 3000
          middlewares:
            <<: *default # 引用默认中间件
      ...
    ...

提示

若在配置中遇到问题，请参见 Go-cqhttp 官方文档。

签名服务

部署签名服务，即使用开源签名服务 qsign，是目前用来绕过检测的最有效手段。

危险

原 qsign 作者已因不可抗力无法再维护此项目，对应 GitHub 储存库也已删除，该方法会在未来逐渐失效，请做好预期准备。

你可以使用别人搭好的 qsign 服务，也可以自己在本地搭建一个：

警告

如果你的动手能力足够强或者有足够的电脑知识，强烈推荐自己搭建本地签名服务器。

使用他人的签名服务可能会泄漏以下信息：

• 登录账号
• 登录时间
• 登录后发送的消息内容
• 登录后发送消息的群号/好友 ID

不会泄露的信息：

• 账号密码
• 账号 session
• 群列表/好友列表
• 接收的消息
• 除发送消息外的任何历史记录

使用共享签名服务可能会提高账号被冻结的概率。

自行安装 JRE 17（Java Runtime Environment 17），请善用搜索引擎查找安装方法。

在 unidbg-fetch-qsign的 Release 界面中下载最新版本，并解压到一个提前准备好的文件夹中。

删除与 go-cqhttp 同级目录下的 data 文件夹和 device.json 文件。

在存放 unidbg-fetch-qsign 的文件夹中，运行以下命令：

bin/unidbg-fetch-qsign --basePath=txlib/<你要使用的版本>

请替换 <你要使用的版本> 字段为在存放 qsign 的文件夹 txlib 目录存在的版本。例：--basePath=txlib/8.9.73

提示

在选择版本时，应当遵从以下原则：
升级版本应当一个一个版本升，以后冻结了可能就没机会回退版本了。发生 Code45 应当先尝试删除 go-cqhttp 的 device.json 文件和 data/cache 文件夹并重新登录，而不是第一时间升级版本。

接下来，请配置 Go-cqhttp 的配置文件中的签名服务器部分：

    account: # 账号相关
      # 数据包的签名服务器列表，第一个作为主签名服务器，后续作为备用
      sign-servers:
        - url: 'http://127.0.0.1:8080'  # 主签名服务器地址，必填
          key: '114514'  # 签名服务器所需要的 apikey, 如果签名服务器的版本在1.1.0及以下则此项无效
          authorization: '-'   # authorization 内容, 依服务端设置，如 'Bearer xxxx'
        ...
      ...
    ...

运行 go-cqhttp 以生成设备文件。

下载对应版本的安卓手机协议并将其重命名为 1.json。将该文件储存在与 Go-cqhttp 同一目录下的 data\versions 文件夹中。

在与 go-cqhttp 同一目录下的 device.json 文件夹中，并修改以下字段：

    {
        "protocol": 1
    }

重启 Go-cqhttp 来应用最终配置。

QQ 频道消息处理（Beta）

根据 Go-cqhttp 文档，iPad / Android Pad / Android Phone 协议支持处理 QQ 频道消息。

QQ 频道消息的处理仍然处于测试阶段，由于 Go-cqhttp 对频道消息支持的不完善，频道内消息无法撤回，且频道列表不会自动刷新（加入新频道需要手动重启一次 Go-cqhttp）。

在其生成的 device.json 中寻找 "protocol":6, 字段，将本处的数值修改为 1（Android Phone）、5（iPad）或 6（Android Pad）均可启用此功能。

提示

关于 Go-cqhttp 选用以上方式登录时出现的的 Code45 或其他登录问题，请根据 Go-cqhttp 官方 Issue 对照解决，或选用除以上协议外的其他协议。