QQ 经典农场「取码插件」安装与使用教程

⭐ 最省事的一条路（Windows 用户，先看这里）
napcat-qq9.9.32-ready.zip（Windows 一键版）必须进群才能拿到，见文末「一键进群」链接。它是把 QQ 客户端 + NapCat + 本插件 打包好了的成品，插件已装好、已启用、napcat.mjs 已打好白名单补丁，你不用手动下载插件、不用改任何文件，双击 napcat.bat 即可。
就 4 步：
进群拿到 napcat-qq9.9.32-ready.zip，解压。
进入解压出的 napcat 文件夹，双击 napcat.bat（无需管理员权限，用的是内置 Node）。
浏览器打开 http://127.0.0.1:6099，输入 WebUI token（默认 73272ddc531a，在 napcat\napcat\config\webui.json 里），扫码登录你的 QQ。
登录成功即自动加载插件，直接取码：
curl "http://127.0.0.1:6099/plugin/napcat-plugin-qq-farm-code/api/proto/login"
💡 用一键版的用户，做到上面第 4 步就已经能用。后面章节讲的是原理 + 手动安装 / Linux 的方法，可跳过。

一、先看懂它在干什么

它就做了两件事，都在 QQ 内核会话里完成：

签发 code —— 调用内核 misc.loginWithAppId('1112386029')，直接给「经典农场」小程序签出登录 code。
直连农场网关登录 —— 拿 code 用 protobuf 连 wss://gate-obt.nqf.qq.com/prod/ws，发一条 gamepb.userpb.UserService.Login（空 body 即可），网关返回农场身份（GID / 昵称 / open_id / 等级）。

它把这两个动作暴露成 HTTP 接口，你的网页或脚本直接 curl 就能用。

整体关系：

[ 你的 QQ 号 ]（已授权账户）
      │  登录 / 会话
      ▼
[ NapCat(QQNT 内核会话) ]  ← 登录成功后插件才会加载
   ┌──────────────────────────────────┐
   │ napcat-plugin-qq-farm-code        │
   │  · misc.loginWithAppId() 签发code  │
   │  · protobuf 直连农场网关           │
   └──────────────────────────────────┘
     │                      │
     │ HTTP 接口             │ WebSocket · Login
     ▼                      ▼
[ 你的脚本/网页(curl) ]  [ 腾讯农场网关 gate-obt.nqf.qq.com ]

二、为什么以前拿不到 code

QQ 经典农场的登录 code，传统上只能在 QQ 客户端里打开「经典农场」小程序时才生成，是「客户端行为」的产物，普通脚本拿不到。

以前有人用 GitHub 扫码 / API 方式（q.qq.com/ide/login）去拿，但这条路已被腾讯封禁。所以本插件换成协议自动化：不打开界面，让内核代签 code，再用 protobuf 直连网关。

三、一次请求是怎么走完的（

脚本向插件发 GET /proto/login。
插件调用内核 misc.loginWithAppId(appid)，签发小游戏登录 code。
插件拿到 code，连接网关 wss://...?code=xxx&ver=xxx。
插件发送 gamepb.userpb.UserService.Login（空 body 即可）。
网关返回 LoginReply（GID / 昵称 / open_id / 等级等）。
插件把结果以 HTTP JSON 返回，并在成功时把 code 缓存到 data/codes.json。

💡 为什么「空 body」就行？代码注释写明：网上逆向出的 LoginRequest 字段（device_info=5 / scene_id=7 / report_data=8）与农场真实 schema 不符，按它编码会被 grpc 以 cannot parse invalid wire-format data 拒绝；实测发空 body 反而返回 err=0 并建立真实账户会话。

⚠️ 插件只负责「取码 + 农场登录」。出码、扫码、状态维护、被踢重登这些账号登录编排不归它管——你需要先让 QQ 号登录上，插件在登录成功后才加载。

四、开始前要准备什么

一个自己名下 / 已授权的 QQ 号（必须）
已安装并能正常登录的 NapCat（必须；用上面「Windows 一键版」则已包含在包里，无需单独装）
Node 环境：Windows 一键版自带；Linux 容器需 ≥ 22.4（必须）
一个 HTTP 请求工具：curl / Postman / 浏览器（必须）
能访问外网（要连 QQ 与腾讯网关）(必须)

⚠️ 这个号必须是自己名下 / 已获授权的。自动化访问腾讯小游戏并改写设备标识，可能违反 QQ 服务条款，风险自负（见文末）。

五、第一步：装好 NapCat 并登录

已装好且登录成功的，跳到【六】。

5.1 Windows

到 NapCat 官方仓库下载对应版本，解压到任意目录。
启动（双击 exe 或运行启动脚本）。
打开 NapCat 的 WebUI（浏览器自动打开，或访问 http://127.0.0.1:6099）。
在 WebUI 里扫码登录你的 QQ。
等状态变成「已登录 / 在线」。

5.2 Docker / Linux

Linux 容器特别注意 Node 版本：插件用了全局 WebSocket，需要 Node ≥ 22.4。太老的镜像会报 no-ws。

参考官方 NapCat-Docker 镜像，挂载目录后同样在 WebUI 扫码登录。容器内插件路径一般在 /app/napcat/plugins。

5.3 记住 WebUI 端口 & Token

后面所有请求都用到这个端口。默认常见是 6099，以你实际显示的为准（也能在配置里改）。

首次打开 WebUI 要输入 token。一键版默认是 73272ddc531a（在 napcat\napcat\config\webui.json 里），你可以自己改。

🔑 一定要先让 QQ 登录成功。插件在登录成功后才加载——号没登录，插件没加载，自然取不到 code。

⚠️ 安全提示（一键版尤其重要）：打包默认 data/config.json 的 key 是空的（接口不鉴权），WebUI token 也是默认值，且 accessControlMode 是 none、没有 IP 白名单。千万别把 6099 端口暴露到公网——能连到的人就能代取你号的 code。建议至少：① 给 config.json 的 key 设一个值；② 修改 WebUI 的 token；③ 只在本机 / 内网访问。

六、第二步：安装本插件（

插件已提交到 NapCat 官方插件索引（PR #394），所以有两种装法：

方式一（推荐，索引合入后免补丁）：装 Release zip。
方式二（索引未合入、被白名单拦截时）：临时放开第三方插件校验。

不管哪种，装完都要重启 NapCat。

方式一：下载 Release zip（开箱即用）

到 Releases 页面下载 napcat-plugin-qq-farm-code.zip。
解压，得到 napcat-plugin-qq-farm-code/ 目录。
⚠️ 注意目录层级：解压后要能直接看到 index.mjs、package.json、data/config.json，别多套一层目录。
把整个目录放到 NapCat 的 plugins/ 下：
- Windows：<NapCat目录>/plugins/
- Linux 容器：/app/napcat/plugins/
在 NapCat 配置里启用它。找到 config/plugins.json，加入：
```
{ "napcat-plugin-qq-farm-code": true }
```
保存后重启 NapCat。

方式二：被白名单拦截时，临时放开第三方插件校验

如果索引还没合入，NapCat 会对非官方插件报 not in official plugin whitelist。手动放开一下（Windows / Linux 通用）：

找到 napcat.mjs（与 loadNapCat.js 同目录；Linux 容器一般在 /app/napcat/napcat.mjs）。
先复制一份备份，比如 napcat.mjs.bak。

用编辑器打开，整段查找：

return this.isOfficialPlugin(e) ? null : r ? `sensitive keyword "${r}"` : "not in official plugin whitelist";

替换为（去掉「非官方即拒」，只保留敏感词拦截）：

return r ? `sensitive keyword "${r}"` : null

保存（UTF-8），重启 NapCat。Windows 上要完全退出，包括托盘里的图标。
如果搜不到整段，说明版本不同：搜索 not in official plugin whitelist 定位到那一行，把其中的 this.isOfficialPlugin(e) ? null : 判定去掉即可。

✅ 一旦商店 PR #394 合入，插件进入官方白名单，方式二就不用了。

七、第三步：重启并验证加载

重启后看 NapCat 日志。插件加载成功会输出类似：

[QQ农场] 插件已加载（协议自动化版）。鉴权: 未启用(本地无鉴权，建议设 key 或绑本机)
[QQ农场] 取 code:  GET /plugin/napcat-plugin-qq-farm-code/api/proto/code
[QQ农场] 登录验证: GET /plugin/napcat-plugin-qq-farm-code/api/proto/login
[QQ农场] 历史 code: 0 条（最多保留 100 条）

看到 插件已加载 即成功。
没看到，多数是 QQ 没登录成功（插件只在登录后加载），或目录层级放错。

八、第四步：调用接口

接口前缀：

<webui端口>/plugin/napcat-plugin-qq-farm-code/api/

假设端口是 6099。

8.1 只取 code

curl "http://127.0.0.1:6099/plugin/napcat-plugin-qq-farm-code/api/proto/code"

返回示例：

{
  "ok": true,
  "uin": 10001,
  "appid": "1112386029",
  "code": "xxxxxxxx",
  "raw": { "...": "内核返回的原始信息" }
}

字段	含义
`ok`	是否成功
`uin`	取码的 QQ 号
`appid`	用的小程序 appid
`code`	你要的农场登录 code
`raw`	内核原始返回（调试用）

8.2 取 code 并一步登录农场

curl "http://127.0.0.1:6099/plugin/napcat-plugin-qq-farm-code/api/proto/login"

返回示例：

{
  "uin": 10001,
  "appid": "1112386029",
  "code": "xxxxxxxx",
  "ok": true,
  "login": {
    "gid": 123456,
    "name": "昵称",
    "level": 3,
    "exp": 100,
    "gold": 500,
    "open_id": "xxxxxxxx"
  },
  "url": "wss://gate-obt.nqf.qq.com/prod/ws?platform=qq&os=iOS&ver=...&code=...",
  "gate": "open",
  "stage": "done",
  "note": "登录成功"
}

字段	含义
`login.gid`	农场 GID
`login.name`	昵称
`login.level` / `exp` / `gold`	等级 / 经验 / 金币
`login.open_id`	网关 open_id
`url` / `gate` / `stage` / `note`	连接与执行阶段信息

8.3 可选参数

参数	作用	示例
`?appid=`	换成另一个小程序 appid	`?appid=1112386029`
`?ver=`	覆盖版本号，探测新版本用	`?ver=1.13.3.14_20260826`
`?key=`	配置了鉴权 key 后需带	`?key=xxx`

九、进阶实战（`appid` / `ver` / 读历史 code）

scripts/ 目录里有一整套可直接运行的脚本：

文件	作用
`scripts/取码.ps1`	PowerShell 取码 / 登录，支持 `-Api -Key -Appid -Ver`
`scripts/取码.mjs`	Node 版（需 Node ≥ 18）
`scripts/取码.py`	Python 版（仅标准库）
`scripts/probe-version.mjs`	批量探测哪个 `ver` 能用
`scripts/index.html`	浏览器「请求生成器」，填参数自动生成四种命令

9.1 换小程序（`?appid=`）

默认 appid=1112386029（经典农场）。给其它小程序取码：

.\scripts\取码.ps1 -Api /proto/code -Appid 1xxxxxxxxxx

9.2 探测 / 覆盖版本号（`?ver=`）

农场升级后默认版本可能被踢（reason=10「客户端版本过低」）。先覆盖试新版本，不改代码：

.\scripts\取码.ps1 -Api /proto/login -Ver 1.13.3.15_20260901

再批量探测哪个版本能用（从高到低、别频繁）：

node scripts\probe-version.mjs 1.13.5.0_20261001 1.13.4.0_20260901 1.13.3.15_20260901

找到「能用的最低版本」后，写回 data/config.json 的 ver，重启生效。

⚠️ probe-version.mjs 每测一个版本都会新取一次 code，有频率限制，请克制。

9.3 读取历史 code（`data/codes.json`）

插件把取到的 code 缓存到 data/codes.json（最多 100 条），字段结构：

[
  {
    "code": "xxxxxxxx",
    "uin": 10001,
    "time": "2026-08-26T12:00:00.000Z",
    "source": "proto"
  }
]

字段	含义
`code`	农场登录 code（账号身份凭证，勿泄露）
`uin`	取码的 QQ 号
`time`	取得时间（ISO）
`source`	来源（这里是 `proto`）

⚠️ 该文件已被 .gitignore 忽略，绝不提交。

十、配置文件逐字段详解

配置在 data/config.json。改完要重启插件 / NapCat 才生效。缺省项用内置默认值，所以可以只写想改的字段。

字段	说明	默认值（内置）
`appid`	小程序 appid，默认就是经典农场	`1112386029`
`serverUrl`	农场网关 WebSocket 地址	`wss://gate-obt.nqf.qq.com/prod/ws`
`platform`	平台标识，通常保持 `qq`	`qq`
`os`	操作系统标识，默认 `iOS`	`iOS`
`ver`	客户端版本号。不能低于网关下限，否则被踢（reason=10）	`1.13.3.14_20260826`
`wsHeaders.User-Agent`	连网关时的 UA	内置一段微信小程序 UA
`wsHeaders.Origin`	连网关时的 Origin	`https://gate-obt.nqf.qq.com`
`key`	鉴权密钥。留空 = 不鉴权	`""`（空）
`name`	自定义名称	`""`

典型配置文件：

{
  "appid": "1112386029",
  "serverUrl": "wss://gate-obt.nqf.qq.com/prod/ws",
  "platform": "qq",
  "os": "iOS",
  "ver": "1.13.3.14_20260826",
  "wsHeaders": {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36 MicroMessenger/7.0.20.1781(0x6700143B) NetType/WIFI MiniProgramEnv/Windows WindowsWechat/WMPF WindowsWechat(0x63090a13)",
    "Origin": "https://gate-obt.nqf.qq.com"
  },
  "key": "",
  "name": ""
}

关于 `key`：这一条必须理解

留空 ""：接口不鉴权。任何能连到你 WebUI 端口的人都能代取该号 code。只建议内网 / 本机用。
配置了值：访问接口必须带 ?key=xxx 或 header x-napcat-farm-key，之一与配置一致才能通过。

带鉴权请求：

curl "http://127.0.0.1:6099/plugin/napcat-plugin-qq-farm-code/api/proto/code?key=你的key"

或：

curl -H "x-napcat-farm-key: 你的key" \
  "http://127.0.0.1:6099/plugin/napcat-plugin-qq-farm-code/api/proto/code"

关于 `ver`：版本号

不能低于网关下限，否则连上被踢（reason=10「客户端版本过低」）。
默认值 1.13.3.14_20260826，低于 20260801 会被踢。
农场升级后取码失败，用 ?ver= 先试新版本，不用改代码（见第九章）。

十一、安全与使用建议

code 是账号身份凭证，别写进公开日志、别公开群聊或仓库。
WebUI 端口别暴露公网。能直连者即可代取该号 code。公网务必设 key，并只在内网/本机访问。
只用于自己名下 / 已授权号，不要批量、他人账号或对抗性用途。
data/codes.json 含真实凭证，已被 .gitignore 忽略，不要提交。
定期看 NapCat 日志，确认没有异常请求。

十二、常见问题排查

<details> <summary>Q1：日志里没有「插件已加载」</summary>

QQ 没登录成功：插件只在登录成功后加载。先扫码登录，确认在线。
目录层级放错：确认 plugins/ 下直接就是 napcat-plugin-qq-farm-code/（里面有 index.mjs、package.json、data/config.json）。
没在 config/plugins.json 启用：确认写了 { "napcat-plugin-qq-farm-code": true }。

</details>

<details> <summary>Q2：报「not in official plugin whitelist」</summary>

商店索引还没合入，走【第六章 · 方式二】放开校验。合入后自愈。

</details>

<details> <summary>Q3：请求返回「no session」</summary>

core.context.session 为空，即 QQ 会话未建立。确认 QQ 已登录、插件已加载。

</details>

<details> <summary>Q4：返回「当前 Node 无全局 WebSocket（需 >=22.4）」</summary>

Linux 容器 Node 太老。升级到 Node ≥ 22.4，或换内置新版 Node 的 NapCat 镜像。

</details>

<details> <summary>Q5：连网关报「客户端版本过低」或 reason=10</summary>

ver 太低。用 ?ver= 传更高版本，或改 config.json 的 ver。参考第九章 / 第十章。

</details>

<details> <summary>Q6：农场拒绝 code（errCode 非 0）</summary>

code 可能失效或会话异常。重新取一次；持续失败可能农场升级了，换 ?ver= 试新版本，或加群找作者。

</details>

<details> <summary>Q7：Windows 改了 napcat.mjs 重启没生效</summary>

Windows 需完全退出 NapCat（含右下角托盘图标），再重新启动。

</details>

十三、联系与免责声明

联系 / 交流

作者 QQ：2682281633
QQ 群：1082900520（取码插件交流群）
一键进群：点击加入 QQ 群
项目仓库：fubiwangluo/qq-code

免责声明

本插件仅供自己名下 / 已获授权的 QQ 号使用。自动化访问腾讯小游戏并改写设备标识，可能违反 QQ 服务条款，由此产生的后果与账号风险由使用者自行承担。请勿用于批量、他人账号或任何对抗性用途。

教程基于 napcat-plugin-qq-farm-code 源码与 README。默认端口 6099 为示例，请以实际 WebUI 端口为准。配图在 img/（01-架构图 / 02-数据流图 / 03-安装流程图），进阶脚本在 scripts/。

Hello,Ethereal!

QQ 经典农场「取码插件」安装与使用教程

一、先看懂它在干什么

二、为什么以前拿不到 code

三、一次请求是怎么走完的（

四、开始前要准备什么

五、第一步：装好 NapCat 并登录

5.1 Windows

5.2 Docker / Linux

5.3 记住 WebUI 端口 & Token

六、第二步：安装本插件（

方式一：下载 Release zip（开箱即用）

方式二：被白名单拦截时，临时放开第三方插件校验

七、第三步：重启并验证加载

八、第四步：调用接口

8.1 只取 code

8.2 取 code 并一步登录农场

8.3 可选参数

九、进阶实战（`appid` / `ver` / 读历史 code）

9.1 换小程序（`?appid=`）

9.2 探测 / 覆盖版本号（`?ver=`）

9.3 读取历史 code（`data/codes.json`）

十、配置文件逐字段详解

关于 `key`：这一条必须理解

关于 `ver`：版本号

十一、安全与使用建议

十二、常见问题排查

十三、联系与免责声明

评论

Hello,Ethereal!

QQ 经典农场「取码插件」安装与使用教程

一、先看懂它在干什么

二、为什么以前拿不到 code

三、一次请求是怎么走完的（

四、开始前要准备什么

五、第一步：装好 NapCat 并登录

5.1 Windows

5.2 Docker / Linux

5.3 记住 WebUI 端口 & Token

六、第二步：安装本插件（

方式一：下载 Release zip（开箱即用）

方式二：被白名单拦截时，临时放开第三方插件校验

七、第三步：重启并验证加载

八、第四步：调用接口

8.1 只取 code

8.2 取 code 并一步登录农场

8.3 可选参数

九、进阶实战（appid / ver / 读历史 code）

9.1 换小程序（?appid=）

9.2 探测 / 覆盖版本号（?ver=）

9.3 读取历史 code（data/codes.json）

十、配置文件逐字段详解

关于 key：这一条必须理解

关于 ver：版本号

十一、安全与使用建议

十二、常见问题排查

十三、联系与免责声明

支持与分享

评论

九、进阶实战（`appid` / `ver` / 读历史 code）

9.1 换小程序（`?appid=`）

9.2 探测 / 覆盖版本号（`?ver=`）

9.3 读取历史 code（`data/codes.json`）

关于 `key`：这一条必须理解

关于 `ver`：版本号