vpn-tool

安装与连接教程

先按 macOS 安装 或 Android 安装 把客户端装好，再照「操作步骤」登录、订阅并连接。文中截图来自真机运行的桌面客户端。

Before you start

开始之前

请确认本机可访问 api.vpntool.vip（TCP 443），且网络未封禁 UDP 51820 出站——隧道数据走 UDP，若该端口被拦截，连接会失败。另需安装 WireGuard 工具（macOS：brew install wireguard-tools；Android：官方 WireGuard App）。

macOS install

macOS 安装（未签名包，需手动放行一次）

本安装包没有 Apple 开发者签名，也没有经过公证，所以 macOS 首次打开一定会拦截，这是预期行为。走完下面 6 步即可正常使用，系统会记住你的放行选择。

  1. 下载并校验安装包

    在下载页点 macOS 直链，得到 vpntool-macos.dmg（196,971,137 字节，约 188 MiB）。建议先在终端校验完整性：

    shasum -a 256 ~/Downloads/vpntool-macos.dmg

    输出应等于下载页登记的 SHA256：8fbf597c17071397cf8fe9156f98ffd82611e2fb877805075a6455b88a4065fe。

  2. 打开磁盘映像

    双击 dmg，Finder 会挂载出名为「vpn-tool」的磁盘映像，里面是 vpn-tool.app 和一个指向「应用程序」的快捷方式。

  3. 拖入「应用程序」

    把 vpn-tool.app 拖到映像里的「应用程序」快捷方式上（或直接拖到「应用程序」文件夹），随后可在 Finder 侧边栏推出该磁盘映像。

  4. 首次打开被拦截（正常现象）

    到「应用程序」里双击 vpn-tool。因为是「从互联网下载 + 未公证」，macOS 会拦下来，弹窗标题为「“vpn-tool”是从互联网下载的App。确定要打开它吗？」，正文包含「Apple无法验证“vpn-tool”是否包含可能危害Mac安全或泄漏隐私的恶意软件。」。此时先关掉这个弹窗（只有「完成」或「取消」就点它），进入下一步从系统设置放行。

  5. 系统设置 → 隐私与安全性 → 点「仍要打开」

    打开「系统设置」→「隐私与安全性」，向下滚动到「安全性」区域，会出现与 vpn-tool 相关的提示（「Apple无法验证“vpn-tool”是否包含…」或「已阻止“vpn-tool”以保护Mac。」），点右侧的「仍要打开」按钮。

  6. 再次确认

    系统会要求输入登录密码或使用 Touch ID 确认；确认后若再弹一次确认框，选「打开」。此后从「应用程序」双击即可正常启动，不再需要放行。

看不到那条提示怎么办：先在「应用程序」里双击一次 vpn-tool.app（会再次被拦截），再打开「系统设置 → 隐私与安全性」，「安全性」区域就会出现该提示。

WireGuard 依赖：客户端建立隧道要调用 wg-quick。macOS 上先执行 brew install wireguard-tools；未安装时客户端会提示「未检测到 WireGuard」。

上面引用的弹窗与按钮措辞取自本机 macOS 26.4.1 自带的 Gatekeeper 文案资源（CoreServicesUIAgent.app/…/Quarantine.loctable、SecurityPrivacyExtension.appex/…/Localizable.loctable）。受执行环境限制，本轮未能在真机上复现完整的首次打开弹窗流程；若与你屏幕上的文字略有出入，以系统实际提示为准。

Steps

操作步骤（安装完成后）

  1. 启动客户端并登录

    启动客户端后进入登录页，输入注册邮箱与密码，点「登录」。登录态保存在本机，下次启动免登录。密码错误会显示内联提示「邮箱或密码不正确，请检查后重试」。

    vpn-tool 客户端登录界面
    登录界面：输入注册邮箱与密码

  2. 确认订阅状态

    未订阅的账号，主控按钮置灰带锁，顶部出现引导横幅「账号未订阅，连接功能已锁定」。点横幅上的「立即订阅」在客户端内完成订阅（套餐与价格见 价格页）。订阅生效后，主控按钮变为可点击。

    未订阅状态：连接功能已锁定，提示立即订阅
    未订阅状态：连接功能锁定，点「立即订阅」完成订阅

  3. 点主控按钮建立连接

    已订阅状态下，点圆形主控按钮。系统会弹出授权框要求输入 Mac 登录密码——这是建立 WireGuard 隧道的必要提权，每次连接都会弹出，属 macOS 安全机制。

    已订阅且未连接状态，主控按钮可点击
    已订阅、未连接：主控按钮可点击

  4. 等待连接完成

    按钮显示旋转环并提示「正在连接…正在建立加密隧道…」即为连接中；变为稳定状态、顶部状态点转青即为已连接。再次点击主控按钮即可断开。

    连接中状态：按钮显示旋转环
    连接中：旋转环 + 呼吸状态点

  5. 选择出口节点（可选）

    底部「节点」一行默认「自动 · 最优节点」，由服务端自动选择最快节点；展开后可手动指定具体节点。

    节点选择列表，默认自动最优节点
    节点选择：默认「自动 · 最优节点」，可展开手动指定

  6. 验证是否生效

    连接成功后客户端会显示当前出口 IP。也可在终端验证：返回值应为网关出口 IP，而不是你的本地公网 IP。

    curl -s ifconfig.me      # 返回网关出口 IP，而非你的本地公网 IP

Android install

Android 安装与配置导入

Android 客户端负责登录、订阅状态、选节点、领取 WireGuard 配置；真正的隧道由官方 WireGuard App 建立。先装好官方 WireGuard（应用商店搜索 WireGuard，或 wireguard.com/install，包名 com.wireguard.android）。

  1. 下载并校验 APK

    在下载页点 Android 直链，得到 vpntool-android.apk（2,145,899 字节）。校验：

    shasum -a 256 ~/Downloads/vpntool-android.apk

    输出应等于下载页登记的 SHA256：c2b19938137c786b13d8bf6af1b70fc4b4d8d3bd8d69f4eb067561d896b00da9。直接在手机上下载时，可用文件管理器的「校验和」功能或校验工具比对同一个值。

  2. 允许「安装未知来源应用」

    系统设置 → 应用 → 特殊应用权限 → 安装未知应用，选中你用来打开 APK 的应用（浏览器或文件管理器）并允许。然后点开 APK 完成安装并启动 vpn-tool。

  3. 登录或注册

    用邮箱与密码登录；没有账号就注册。注册表单里有可选的邀请码输入框，填写邀请码后双方各得 10G 赠送流量。

  4. 查看订阅与剩余流量

    状态页展示套餐、到期时间与剩余流量（含赠送流量）。未订阅时无法领取配置，先在客户端内完成订阅（套餐见价格页）。

  5. 选节点并领取配置

    在节点列表里选一个出口节点，点「领取配置」，App 会展示 WireGuard 配置文本，可复制备用。若提示「当前账号未订阅」，说明套餐未生效。

  6. 导入官方 WireGuard 并连接

    打开官方 WireGuard App → 点右下角「+」→ 选「从文件导入」或「扫描二维码」→ 导入刚领取的配置 → 打开对应隧道的开关即可连接。

以上步骤按 Android 客户端的实际实现（仓库 client/android/）与本轮接口联调结果整理。交付方未做真机 UI 实测（本机没有模拟器与真机），如与你手机上的界面文字有差异，以 App 实际界面为准。

Troubleshooting

常见问题

现象原因处理
提示「“vpn-tool”是从互联网下载的App」或「Apple无法验证…是否包含可能危害Mac安全或泄漏隐私的恶意软件」安装包未签名、未公证，被 macOS Gatekeeper 拦截按 macOS 安装 第 4~6 步：先在「系统设置 → 隐私与安全性 → 安全性」里点「仍要打开」，输入密码 / Touch ID 确认后再打开一次
双击客户端毫无反应，或只出现「完成」按钮同上，系统静默拦截了这次启动先在「应用程序」双击一次 vpn-tool.app，再到「系统设置 → 隐私与安全性」的「安全性」区域点「仍要打开」
点连接提示找不到 wg-quick系统未装 WireGuard 命令行工具macOS 执行 brew install wireguard-tools（App Store 的 WireGuard 图形版不含 wg-quick）；Linux 执行 apt install wireguard
Android 提示「无法安装未知来源应用」系统默认禁止侧载 APK系统设置 → 应用 → 特殊应用权限 → 安装未知应用，为你当前使用的浏览器 / 文件管理器放行（见 Android 安装）
Android 领到配置却连不上网配置还没导入官方 WireGuard App，或隧道开关未打开把配置导入官方 WireGuard App 并打开开关；只复制配置文本不会建立隧道
wg-quick 报需要 bash 4 以上macOS 自带 bash 仅 3.2brew install bash 后重试
一直「连接中」后失败网络封禁 UDP 51820 出站换一个网络；确认防火墙未拦截 UDP 51820
登录提示「邮箱或密码不正确」凭据输入错误核对邮箱与密码，注意大小写
提示「未订阅，连接功能已锁定」订阅未激活或已到期在客户端完成订阅（见 价格页）
提示流量已用尽套餐流量额度用完续费后额度累加，立即可用
授权框反复弹出macOS 对提权命令的限制属正常现象
连接后无法上网DNS 或路由异常断开重连；查看官网状态公告

反馈问题时，请附客户端「复制诊断信息」按钮输出的内容。

Uninstall

卸载

退出客户端（菜单栏图标 → 退出）→ 打开「应用程序」把 vpn-tool 拖入废纸篓 → 清理本地配置与登录态：

rm -rf ~/.vpntool

若卸载后网络异常，重启一次系统即可恢复。

Android：先在官方 WireGuard App 里关闭隧道开关并删除对应配置，再到 系统设置 → 应用 → vpn-tool → 卸载。卸载前请先断开隧道，避免残留连接。