Skip to content

快速上手 ​

这一页讲清楚从下载到看见第一条聊天记录的全过程,以及启动时那个 Bootstrap(主页)界面的 每一个按钮。

1. 下载与安装 ​

前往 Releases 下载与系统匹配的安装包。

系统WindowsmacOSLinux
架构x64(不支持 ARM)ARM / Intelx64 / arm64

首次启动需要保证本机已经安装 QQ NT:WeQ 读取的是 QQ 的本地数据库,没有 QQ 就没有数据。

macOS 的拖入安装与首次系统放行见 macOS 安装与首次打开,不需要终端命令或关闭 SIP。

Arch Linux 用户可以直接 paru -S weq-bin,见 Arch Linux 安装(AUR)。

2. 账号主页 ​

启动后直接进入紧凑的竖版账号主页,不再先选择「现有账号配置」或「新的开始」。右上角保留窗口级操作:

  • 打开日志目录:出问题时把最新日志一并附上;
  • 关闭(非 macOS):直接关窗。

主页显示当前账号与「打开账号」,下方列出最近使用的账号。每项显示来源、目录和上次打开时间;同一 QQ 的不同备份不会合并。账号操作菜单可以移除保存配置,确认后只删除 WeQ 配置,不动 QQ 数据或备份文件。

「添加账号」和「导入备份」分别进入独立子页面,底部居中的图标文字「返回」可回到账号主页;进入账号后窗口切换为聊天尺寸。页面不再提供独立密钥按钮,只有无法直接打开且自动获取失败时才弹出密钥输入窗口。

INFO

若启动时检测到「本地组件版本过旧」或「组件安装损坏」,会弹出不可关闭的提示框。版本过旧 的那张框内嵌了更新按钮,可直接检查 / 下载 / 重启安装;安装损坏则需重新安装。若未检测到 QQ 安装,同样会弹出提示。

自动进入 ​

勾选过「下次打开自动进入该账号」后,WeQ 会在后台静默测试密钥并打开账号,与窗口界面加载 同时进行,不再等待界面加载完才开始。界面就绪后接回同一次打开任务,失败才退回主页并提示原因。 进入工作区前仍会先把窗口调整成聊天尺寸并预热首屏查询,所以不会先闪一下空白头像。

同一行的「自动启用 QQ 在线能力」与账号内设置共用全局偏好,修改任意一处都会同步;它与是否自动进入账号分别控制。

在登录页完全退出 WeQ 后,下次打开会忽略一次自动进入,仍停留登录页;「下次打开自动进入该账号」及其目标不会被取消。从账号内退出则仍按原偏好启动。

3. 打开账号与环境诊断 ​

  • 在主页选择已保存账号后点「打开账号」;密钥仍会先验证,失效或缺失时自动获取,成功后继续验证并打开,获取失败才弹出手动输入窗口。
  • 「添加账号」展示本机发现的 QQ 账号,也可独立发起扫码。扫码账号没有对应本地记录时会明确提示先在本机 QQ 同步记录或导入备份,不把它的密钥绑定到原账号。
  • 「导入备份」不要求先选在线账号,也不要求本机有 QQ 登录历史。
  • 账号列表读取失败会显示原因,可点刷新图标重试;已有账号不会因为重新读取失败被隐藏。

环境诊断 ​

「环境诊断」按钮仅在「添加账号」页面显示,位于头像旁。点击后在独立弹窗中开始目录大小扫描与在线实例轮询,不撑长登录页,关闭后停止。顶部显示 QQ 版本与数据目录。点击路径可以重新指定 QQ 数据目录 (例如把 QQ 数据挪到了别的盘)。文件夹叫什么都行——老版本 QQ 迁移过来的目录通常不叫 Tencent Files——只要选到「存放 QQ 号子目录 / nt_qq 的那一层」即可;选成某个 QQ 号 子目录时会自动上溯一层。下方三张统计卡:

  • 本地账号:login.db 里发现的历史账号数;
  • 目录大小:当前选中账号目录的总大小,扫描时数字会实时向上滚动;
  • 在线实例:当前正在运行的 QQ 进程数;

再下面是「数据库占用」卡:按文件大小画出类似 GitHub 语言条的彩色条形,列出最大的若干个数据库。

4. 获取数据库密钥 ​

在「添加账号」中选中本机账号,点「打开账号」。有可复用的快速登录物料时先快速登录,否则显示二维码;快速登录失败也会转为扫码。确认提示按实际返回显示,不要求手动选择平台方案。

「扫码登录其他账号」是独立入口,无已发现账号时也可发起;无法直接打开且自动获取失败后,可在弹出的窗口手动填写密钥或重试获取。

验证后进入 ​

无论密钥从哪来,点「打开账号」时 WeQ 都会先测试密钥(testDatabaseKey):

  • 密钥不正确 → 自动尝试获取,仍失败才显示输入窗口,验证通过前拒绝进入;
  • 正确 → 打开账号、写入配置,进入主界面。

想省事可以勾选 下次打开自动进入该账号。

5. 本地备份(静态离线账号) ​

从账号主页进入 导入备份,选择包含 nt_msg.db、profile_info.db、group_info.db 的目录,导入一份静态离线账号:

  • 支持平铺数据库目录、Tencent Files 根目录、Windows 的 QQ 号目录,以及 Linux/macOS 的 nt_qq_<hash> 账号目录;所选目录没有账号时自动检查下一级,仍未找到则询问是否递归扫描。
  • 找到多个账号目录时自动弹出可滚动的选择窗口,逐项展示可验证的账号昵称、QQ 号、数据库数量和体积、媒体目录状态;点击「使用此目录」确认,之后可通过「切换账号目录」重新选择。取消或按 Escape 不改变已选目录。加密库尚无法识别身份时会标记待验证,不把目录名冒充实际身份。
  • 扫描发现目录后立即显示,数据库数量、大小与身份随后逐步补齐;未知大小不显示为零。扫描未结束时保留动画和已发现数量,已完成验证的目录可提前选择;停止扫描后不再追加结果。
  • 明文数据库无需密钥;Android 备份优先尝试自动推导(uid 取目录里的 gpro_v1-6_<uid>.db 文件名,没有这个频道库时改为读备份自带或本机的 login.db;两处都查不到就退回手输),再验证已有配置密钥。密钥推导成功即确定账号身份 —— uid 由密钥派生、库能开就说明它正确;QQ 号优先取推导链顺带带回的那一行(login.db 里有),其次从 nt_msg.db 的发送记录自证推断,资料库只用来补昵称。需要其他设备密钥时,先复用同账号已有且仍匹配当前 QQ 进程的会话物料;必要时读取该账号 QQ 内存并按平台流程请求提权,再请求和验证密钥。完全离线或获取失败时可手动输入密钥。
  • 备份包含标准 nt_data 目录时直接使用其中的图片、语音、视频、文件和表情;直接选择 nt_db 也会识别其所属标准布局中的资源。没有随附资源时使用既有在线补全,不再借用本机另一处同账号目录,也不提供额外关联开关。
  • 扫描结果显示包含数据库和媒体的完整账号文件夹,而不是仅显示 nt_db;内部会分别定位数据库与媒体。旧备份的 profile_info_v2 等资料表也可识别,自动取密钥成功后会显示对应状态。
  • 数据目录、密钥、算法都会记住,下次可直接打开;
  • 静态账号只有一个数据库快照,因此维护工具里的「本地缓存」入口会禁用;查看快照请用「QQ 数据库管理」。

桌面端各用途的文件、文件夹与保存弹窗分别记住上一次确认的位置,重启后仍有效;取消选择不会覆盖记忆。

三端的常见布局如下,迁移到其它位置后仍按目录结构识别,不依赖当前运行系统或根目录名称:

来源系统数据库目录媒体目录
WindowsTencent Files/<QQ号>/nt_qq/nt_db同层 nt_data
Linux~/.config/QQ/nt_qq_<UID哈希>/nt_db同层 nt_data
macOS~/Library/Containers/com.tencent.qq/Data/Library/Application Support/QQ/nt_qq_<UID哈希>/nt_db同层 nt_data
平铺导出所选目录中的 .db 文件所选目录中的 nt_data(如果有)

6. WeQ Web(浏览器版) ​

除桌面版外还提供 WeQ Web:同一套界面跑在浏览器里,适合无桌面环境的机器(NAS / 服务器 / WSL),或想从别的设备访问。

  • 每个平台一个压缩包,需自备 Node ≥ 22,无需联网安装依赖;
  • Windows 双击 start.bat,Linux / macOS 执行 ./start.sh;
  • 终端会打印地址和访问令牌,浏览器打开后粘贴令牌即可进入;
  • 默认只监听 127.0.0.1,对外暴露前必须显式设置 WEQ_TOKEN 并放在 HTTPS 反向代理之后。

网页版不提供窗口控制、文件管理器定位、系统应用锁、桌面应用更新和窗口截图。独立 Node 发布包未随包提供本地语音推理依赖,也没有 Electron 的报告 PDF / 图片捕获能力;桌面端 开启的内置 Web / Remote 可复用电脑离屏渲染。空间使用共享业务页,频道网站等外部网页入口 在浏览器新标签页打开;独立部署的导出默认落到 WEQ_EXPORT_DIR,浏览器下载位置另由浏览器控制。

已有桌面版时,可从「设置 → WeQ 服务 → Web 与 Remote」开启内置 Web,无需再启动另一份 后端。手机配对与文件发送的边界见Web 服务与手机连接;独立部署详见 apps/web/README.md。

Web/Remote 单次请求支持现有图片和附件分段上传,超出 16 MiB 的正文会拒绝接收。请求超过两分钟仍未完成时退出等待;写入操作显示结果暂未确认,先刷新核对结果再重试,不自动重复提交。

Linux AppImage 的应用内更新使用官方 Release 的文件大小与 SHA-256 核验镜像下载内容,版本、架构或摘要不匹配时不进入安装。官方核验暂不可用时保留当前应用,可稍后重试;发行版包管理器安装的副本仍由包管理器更新。

7. 首次进入的欢迎框 ​

第一次进入账号后会弹出一次欢迎说明框,点击「开始使用」后不再出现(无 ESC / 点遮罩关闭)。

v2.0.0 起这个框还负责征询是否扫描 QQ 内存(原先该开关默认开启,用户无从得知可以关):

  • 扫描登录中的 QQ 进程内存可解锁 QQ 在线能力 —— 拉取漫游消息、下载本地不存在的媒体、 发送消息、群操作与群管理、一键反馈 bug,以及群相册 / 空间 / 装扮等在线内容;
  • 开关默认勾选(推荐),不需要自动启用时可取消勾选,未另作手动请求时仅使用本地能力;
  • 可随时在 设置 → 常规 → 在线能力与授权 → 自动启用 QQ 在线能力 修改自动策略,关闭后仍能从受限详情手动启用当前来源。手动请求不修改下次启动偏好,也不等于所有 API 或 CDN 功能的网络总开关。

INFO

升级到 v2.0.0 时,确认过旧版欢迎框的用户会重新看到一次这个新版引导(以征得上述同意), 确认前扫描内存默认关闭。


下一步 → 主界面与账号

当前文档对应 v2.7.4 · 已发布内容以 CHANGELOG 为准