查看“自搭建指南/QQ”的源代码

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

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

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

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

因此，是否在 QQ 平台上搭建非官方机器人需要谨慎考虑。同时，第三方方案的可用性可能会随时间变化，我们无法提供任何保证。在 QQ 平台上选择使用何种方案取决于个人意愿。
{{Mbox
| text = 如果出现 QQ 账号被冻结等情况，我们无力解决此类问题，也不会为相应后果负责。
| type = danger
}}

== Lagrange ==
[https://github.com/KonataDev/Lagrange.Core Lagrange] 是一个 NTQQ 协议相关的开源项目。包括目前实现 Linux NTQQ 协议的 <code>Lagrange.Core</code> 和提供 OneBot-V11 API 的 <code>Lagrange.Onebot</code> 两部分。

=== 下载与安装 ===
如果你想使用 Docker 搭建 Lagrange，请转到[https://github.com/LagrangeDev/Lagrange.Core/blob/master/Docker_zh.md 使用 Docker]。

推荐前往 [https://github.com/LagrangeDev/Lagrange.Core/actions Github Actions]，找到 <code>Lagrange.OneBot Release</code>，点击最新的工作流，下拉找到并下载合适的版本。

或者从 Lagrange 的 [https://github.com/LagrangeDev/Lagrange.Core/releases GitHub Release] 上下载 Nightly 版本。

{| class="wikitable"
|-
! 系统类型 !!  压缩文件
|-
| Intel 版 MacOS ||  <code>Lagrange.OneBot_osx-x64_8.0.zip</code>
|-
| M1 版 MacOS || <code>Lagrange.OneBot_osx-arm64_8.0.zip</code>
|-
| 64 位 Linux || <code>Lagrange.Onebot_linux-x64_8.0.zip</code>
|-
| arm64 Linux || <code>Lagrange.OneBot_linux-arm64_8.0.zip</code>
|-
| armv7 Linux || <code>Lagrange.OneBot_linux-arm_8.0.zip</code>
|-
| 64 位 Linux (musl) || <code>Lagrange.Onebot_linux-musl-x64_8.0.zip</code>
|-
| arm64 Linux (musl) || <code>Lagrange.OneBot_linux-musl-arm64_8.0.zip</code>
|-
| armv7 Linux (musl) || <code>Lagrange.OneBot_linux-musl-arm_8.0.zip</code>
|-
| 32 位 Windows || <code>Lagrange.OneBot_win-x86_8.0.zip</code>
|-
| 64 位 Windows || <code>Lagrange.OneBot_win-x64_8.0.zip</code>
|}
解压下载好的文件到一个已经预先准备好的文件夹中。

运行 Lagrange。此时将提示：
<pre>
No exist config file, create it now...
Please Edit the appsettings.json to set configs and press any key to continue
</pre>

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

=== 配置 ===
请在机器人配置文件填写以下配置项：
:<code>qq_account =</code> - 机器人的 QQ 号。
:<code>qq_host = "127.0.0.1:11451"</code> - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 Lagrange 反向连接。
:<code>qq_frame_type = "Lagrange"</code> - 告诉机器人正在使用 Lagrange，以处理兼容性问题。

接下来，请在 Lagrange 的配置文件中设置对应的连接方式。
<syntaxhighlight lang=json>
 {
  ...
  "Implementations": [
    {
      // 使用反向 WebSocket 服务
      "Type": "ReverseWebSocket",
      // 此处填写先前的 IP 地址和端口
      "Host": "127.0.0.1",
      "Port": 11451,
      "Suffix": "/ws",
      ...
    }
    ...
  ]
}
</syntaxhighlight>
{{Mbox
| text = 请删除 JSON 文件的所有注释，否则无法正常读取。
| type = important
}}
修改完文件后扫码登录即可。
{{Mbox
| text = 若在配置中遇到问题，请参见 [https://github.com/LagrangeDev/Lagrange.Core/blob/master/README_zh.md Lagrange README 文件]。
| type = note
}}

== LLOneBot ==
[https://github.com/LLOneBot/LLOneBot LLOneBot] 是 Liteloader 的插件之一，可以使 NTQQ 支持 OneBot11 协议进行 QQ 机器人开发。

[https://github.com/LiteLoaderQQNT/LiteLoaderQQNT LiteLoaderQQNT]（LiteLoader）是 NTQQ 的插件加载器，允许通过插件注入 QQ 实现某些特定的功能。

=== 安装 ===
请参考[https://llonebot.github.io/zh-CN/guide/getting-started 官方文档]中的说明进行插件的安装。
{{Mbox
| text = 不建议用户使用此方案时随意更新 QQ 客户端。由于 QQ 客户端检测机制可能的变化，更新客户端可能会导致原有方案不可用。
| type = warning
}}

=== 配置 ===
请在机器人配置文件填写以下配置项：
:<code>qq_account =</code> - 机器人的 QQ 号。
:<code>qq_host = "127.0.0.1:11451"</code> - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 LLOnebot 反向连接。
:<code>qq_frame_type = "LLOneBot"</code> - 告诉机器人正在使用 LLOneBot，以处理兼容性问题。

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

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

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

== NapCatQQ ==
[https://github.com/NapNeko/NapCatQQ NapCatQQ] 是在后台低占用运行的无头（没有界面）NTQQ 机器人框架。

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

=== 安装 ===
请根据 [https://napneko.github.io/zh-CN/guide/getting-started#%E5%AE%89%E8%A3%85-qq NapCatQQ 手册]安装官方 QQ，若 QQ 版本过低可能会导致程序无法正常启动。

从 NapCatQQ 的 [https://github.com/NapNeko/NapCatQQ/releases GitHub Release] 下载最新的版本。
{{Mbox
| text = 不建议用户使用此方案时随意更新 QQ 客户端。由于 QQ 客户端检测机制可能的变化，更新可能会导致原有方案不可用。
| type = warning
}}

=== 配置 ===
请在机器人配置文件填写以下配置项：
:<code>qq_account =</code> - 机器人的 QQ 号。
:<code>qq_host = "127.0.0.1:11451"</code> - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 NapCatQQ 反向连接。
:<code>qq_frame_type = "NapCatQQ"</code> - 告诉机器人正在使用 NapCatQQ，以处理兼容性问题。

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

接下来，请在 NapCatQQ 的配置文件中设置对应的连接方式。
<syntaxhighlight lang=json>
{
    ...
    "reverseWs": {
        // 是否启用反向websocket服务
        "enable": true,
        // 反向websocket对接的地址, 如["ws://127.0.0.1:8080/onebot/v11/ws"]
        "urls": ["ws://127.0.0.1:11451/ws"]  // 此处填写先前的 IP 地址和端口，注意不要删去后面的“/ws”   
    },
    ...
}
</syntaxhighlight>
{{Mbox
| text = 请删除 JSON 文件的所有注释，否则无法正常读取。
| type = important
}}

也可以使用 WebUI 进行配置，详见 [https://napneko.github.io/zh-CN/guide/config NapCat 手册]。

修改完文件后请根据 [https://napneko.github.io/zh-CN/guide/getting-started#%E5%90%AF%E5%8A%A8 NapCatQQ 教程]启动程序，扫码登录即可。

== OpenShamrock ==
[https://github.com/whitechi73/OpenShamrock OpenShamrock] 是基于 Xposed 实现的 QQ 机器人框架，你可以在 Android 手机 / 模拟器中使用 OpenShamrock 运行机器人。
{{Mbox
| text = 2024 年 8 月 12 日，OpenShamrock 于 GitHub 中的存储库已被归档，开发者已无力继续维护此项目。
| type = danger
}}
{{Mbox
| text = 2024 年 4 月 2 日，OpenShamrock 开发组于 [https://github.com/whitechi73/OpenShamrock/discussions/272#discussion-6300354 openshamrock/discussion#272] 宣布，OpenShamrock 将会从 <code>1.1.0</code> 版本起弃用 OneBot V11 支持，迁移至新的 [https://github.com/KarinJS/kritor Kritor] 协议。<br>这意味着 <code>1.1.0</code> 及之后版本的 OpenShamrock 将不再支持 OneBot V11，以下内容也不再适用。请仔细辨别，以免带来不必要的困扰。
| type = danger
}}
{{Mbox
| text = 此方式需要一定的安卓（Android）的开发基础，可能需要对 Root、命令行等有一定了解。
| type = warning
}}

=== 安装 ===
请参考[https://whitechi73.github.io/OpenShamrock 官方文档]中的说明进行框架的安装。
{{Mbox
| text = 本文不会涉及对 Root 手机的说明，也不会对 Root 手机造成的任何后果负责。
| type = warning
}}

=== 配置 ===
请在机器人配置文件填写以下配置项：
:<code>qq_account =</code> - 机器人的 QQ 号。
:<code>qq_host = "127.0.0.1:11451"</code> - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 OpenShamrock 反向连接。
:<code>qq_frame_type = "OpenShamrock"</code> - 告诉机器人正在使用 OpenShamrock，以处理兼容性问题。

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

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

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

== Go-cqhttp ==
[https://github.com/Mrs4s/go-cqhttp Go-cqhttp] 是基于 [https://github.com/mamoe/mirai Mirai] 以及 [https://github.com/Mrs4s/MiraiGo MiraiGo] 的 OneBot Golang 原生实现。是基于 QQ Android 协议支持的机器人框架库。

一个新注册的 QQ 账号仅需完成基础配置即可，但为了避免在机器人使用后期时遇到 Code45 等问题，建议配置使用签名服务器。
{{Mbox
| text = 根据 [https://github.com/Mrs4s/go-cqhttp/issues/2471 go-cqhttp/issue#2471]，开发者已无力继续维护此项目。<br>在未来 qsign 签名服务彻底被官方封死之后，Go-cqhttp 将无法继续使用，请窒息。
| type = danger
}}
{{Mbox
| text = 由于 QQ 官方的持续检测，使用 Go-cqhttp 连接的成功率越来越低。即使成功连接，也可能面临频繁冻结等情况。不推荐任何用户再使用此方案连接 QQ 平台。
| type = danger
}}

=== 下载与安装 ===
如果你想使用 Docker 部署 Go-cqhttp，请转到[https://docs.go-cqhttp.org/guide/docker.html 使用 Docker]。

从 Go-cqhttp 的 [https://github.com/Mrs4s/go-cqhttp/releases/latest GitHub Release] 下载最新的版本。

{| class="wikitable"
|-
! 系统类型 !! 可执行文件 !! 压缩文件
|-
| Intel 版 MacOS || N/A || <code>go-cqhttp_darwin_amd64.tar.gz</code>
|-
| M1 版 MacOS || N/A || <code>go-cqhttp_darwin_arm64.tar.gz</code>
|-
| 32 位 Linux || N/A || <code>go-cqhttp_linux_386.tar.gz</code>
|-
| 64 位 Linux || N/A || <code>go-cqhttp_linux_amd64.tar.gz</code>
|-
| arm64 Linux || N/A || <code>go-cqhttp_linux_arm64.tar.gz</code>
|-
| armv7 Linux || N/A || <code>go-cqhttp_linux_armv7.tar.gz</code>
|-
| 32 位 Windows || <code>go-cqhttp_windows_386.exe</code> || <code>go-cqhttp_windows_386.zip</code>
|-
| 64 位 Windows || <code>go-cqhttp_windows_amd64.exe</code> || <code>go-cqhttp_windows_amd64.zip</code>
|-
| arm64 Windows || <code>go-cqhttp_windows_arm64.exe</code> || <code>go-cqhttp_windows_arm64.zip</code>
|-
| armv7 Windows || <code>go-cqhttp_windows_armv7.exe</code> || <code>go-cqhttp_windows_armv7.zip</code>
|}

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

运行 Go-cqhttp。此时将提示：
<pre>
[WARNING]: 尝试加载配置文件 config.yaml 失败: 文件不存在。
[INFO]: 默认配置文件已生成，请编辑 config.yaml 后重启程序。
</pre>

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

=== 基础配置 ===
请在机器人配置文件填写以下配置项：
:<code>qq_account =</code> - 机器人的 QQ 号。
:<code>qq_host = "127.0.0.1:11451"</code> - 将会在填写的 IP 地址和端口中开启一个 Websocket 服务器，用于 Go-cqhttp 反向连接。

接下来，请在 Go-cqhttp 的配置文件中设置对应的连接方式。
<syntaxhighlight lang=yaml>
    ...
    # 连接服务列表
    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 # 引用默认中间件
      ...
    ...
</syntaxhighlight>

{{Mbox
| text = 若在配置中遇到问题，请参见 [https://docs.go-cqhttp.org Go-cqhttp 官方文档]。
| type = note
}}

=== 签名服务 ===
部署签名服务，即使用开源签名服务 ''[https://github.com/fuqiuluo/unidbg-fetch-qsign <s>qsign</s>]''，是目前用来绕过检测的最有效手段。
{{Mbox
| text = 原 qsign 作者已因'''不可抗力'''无法再维护此项目，对应 GitHub 储存库也已删除，该方法会在未来逐渐失效，请做好预期准备。
| type = danger
}}
你可以使用别人搭好的 qsign 服务，也可以自己在本地搭建一个：
{{Mbox
| text = 如果你的动手能力足够强或者有足够的电脑知识，'''强烈推荐'''自己搭建本地签名服务器。
使用他人的签名服务可能会泄漏以下信息：
* 登录账号
* 登录时间
* 登录后发送的消息内容
* 登录后发送消息的群号/好友 ID
不会泄露的信息：
* 账号密码
* 账号 session
* 群列表/好友列表
* 接收的消息
* 除发送消息外的任何历史记录
使用共享签名服务可能会提高账号被冻结的概率。
| type = warning
}}

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

在 ''[https://github.com/fuqiuluo/unidbg-fetch-qsign <s>unidbg-fetch-qsign</s>]''的 Release 界面中下载最新版本，并解压到一个提前准备好的文件夹中。

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

在存放 unidbg-fetch-qsign 的文件夹中，运行以下命令：
<syntaxhighlight lang=sh>
bin/unidbg-fetch-qsign --basePath=txlib/<你要使用的版本>
</syntaxhighlight>

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

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

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

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

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

下载对应版本的[https://github.com/MrXiaoM/qsign/blob/mirai/txlib/ 安卓手机协议]并将其重命名为 <code>1.json</code>。将该文件储存在与 Go-cqhttp 同一目录下的 <code>data\versions</code> 文件夹中。

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

<syntaxhighlight lang=json>
    {
        "protocol": 1
    }
</syntaxhighlight>

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

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

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

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

{{Mbox
| text = 关于 Go-cqhttp 选用以上方式登录时出现的的 Code45 或其他登录问题，请根据 Go-cqhttp 官方 [https://github.com/Mrs4s/go-cqhttp Issue] 对照解决，或选用除以上协议外的其他协议。
| type = note
}}