Skip to content

Latest commit

 

History

335 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Grok Register — GUI, CLI and WebUI registration automation toolkit

简体中文 | English

Grok Register 是一个面向自动化流程研究、测试环境验证和个人学习的 Python 工具。项目提供 GUI / CLI / WebUI、四种临时邮箱与 Outlook 邮箱池、可选 1–8 线程并发与账号级代理池,并集成 Chromium 页面自动化、账号安全落盘、pending 恢复、grok2api token 入池和可选 CPA xAI OIDC 凭证导出。

License: MIT Python 3.9+ GUI + CLI + WebUI 1-8 Workers Proxy: direct / single / pool Chromium/Chrome PRs Welcome linux.do

Star History Rank


Important

本项目仅用于自动化流程研究、测试环境验证和个人学习。使用者应自行遵守目标网站服务条款、当地法律法规和第三方服务限制。请勿将本项目用于滥用、绕过平台限制或未经授权的商业用途。

目录

赞助商

需要稳定的住宅 IP?试试 IPWO住宅代理。

覆盖 195+ 国家和地区
真实住宅 IP 资源
灵活的 IP 轮换
支持 HTTP / HTTPS / SOCKS5

适用于自动化注册、账号管理、数据采集及跨境业务场景,可与浏览器自动化工具和代理池灵活搭配。免费试用,折扣码:0205

广告合作请联系我:2309501984

项目功能

Grok Register 使用真实 Chromium / Chrome 完成注册流程,并把 GUI、CLI 和 WebUI 都接到同一套注册核心上。

主要功能:

  • 自动打开注册页、提交邮箱、轮询验证码、填写资料并获取 SSO cookie。
  • 支持 DuckMail / YYDS / Cloudflare 临时邮箱 / Cloud Mail / Outlook 邮箱池 五种邮箱来源。
  • 支持 GUI / CLI / WebUI 三种操作入口。
  • 支持可选 1–8 线程并发注册;默认关闭。
  • 支持 direct / single / pool 代理模式、健康检查、冷却、订阅、固定/旋转节点和账号级稳定 Proxy Lease。
  • 代理池可混合解析 HTTP / HTTPS / SOCKS / VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks 节点。
  • 支持注册后尝试开启 NSFW;失败不会丢失已经注册成功的账号。
  • 支持 SSO 入库前筛查 botFlagSource / policy=deny;明确命中后隔离并跳过 grok2api / CPA。风控检查采用 fail-open:网络请求失败、HTTP 异常或未解析到风控字段时会记录诊断并继续入库。
  • 支持把 SSO token 写入 grok2api 本地池或远端池。
  • 支持可选 CPA xAI OIDC 凭证导出与 CLIProxyAPI hotload。
  • 成功账号实时落盘;主账号结果写入失败时会进入对应的 accounts_*.txt.pending.jsonl,可稍后幂等恢复。风控隔离写入失败使用独立的 risk pending,不与普通账号 pending 混用。
  • 支持停止任务、浏览器重启、邮箱重试、运行时清理和后处理错误隔离。

单个账号的主要流程:

打开注册页
  → 创建邮箱并提交
  → 获取并填写验证码
  → 填写资料
  → 获取 SSO cookie
  → 可选开启 NSFW
  → SSO 风控筛查(botFlagSource / policy)
  → 保存账号
  → 可选写入 grok2api
  → 可选导出 CPA/OIDC

grok2api 入池和 CPA/OIDC 都属于注册后的附加后处理。后处理失败会记录警告,但不会把已经保存成功的账号重新算作注册失败。SSO 风控命中时不会写入主账号文件,也不会进入 grok2api / CPA。

快速开始

1. 环境要求

  • Python 3.9+
  • Google Chrome 或 Chromium
  • 可访问注册页面和所选邮箱 API 的网络环境
  • GUI 需要 Tkinter;没有 Tkinter 时可以使用 CLI 或 WebUI
  • 仅当使用 VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks 节点时需要 sing-box;HTTP/HTTPS/SOCKS 继续使用项目原生代理实现

2. 安装

git clone https://github.com/AaronL725/grok-register.git
cd grok-register

python -m venv .venv

激活虚拟环境:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

安装核心依赖:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

复制配置文件:

# macOS / Linux
cp config.example.json config.json

# Windows CMD
copy config.example.json config.json

3. 先完成最小配置

如果先使用 DuckMail,可以从下面这组最小运行配置开始:

{
  "email_provider": "duckmail",
  "duckmail_api_key": "",
  "register_count": 1,
  "proxy_mode": "auto",
  "proxy": "",
  "multi_thread_enabled": false,
  "cpa_export_enabled": false
}

然后根据 email_provider 和需要启用的后处理功能继续填写对应配置。完整字段见 config.example.json。

config.example.json 是完整字段模板,其中的 example.com、temp-mail.example.com 等均为占位值,并不是可直接使用的服务地址。若使用 Cloudflare / Cloud Mail / YYDS,请先填写对应服务参数。

4. 启动

GUI:

python grok_register_ttk.py

WebUI:

python -m pip install -r requirements-web.txt
python -m web.server

访问:

http://127.0.0.1:8092

GUI、CLI 和 WebUI 共用同一个 config.json 和同一套注册逻辑。建议同一时间只使用一个入口启动任务。

运行方式

WebUI(可选)

python -m pip install -r requirements-web.txt
python -m web.server

WebUI 默认监听 127.0.0.1:8092,提供中英双语配置、开始/停止、批次统计、实时日志、代理池节点状态、订阅解析统计、重新加载和手动测试。

GUI

python grok_register_ttk.py

GUI 可以直接配置主要邮箱、代理、代理池、多线程和注册参数,然后点击“开始注册”。

CLI

以下三种写法等价:

python grok_register_ttk.py cli
python grok_register_ttk.py start
python grok_register_ttk.py --cli

CLI 读取 config.json,通过校验后提示:

> start

输入 start 才正式运行;按 Ctrl+C 可请求停止。

CLI 只是省略 Tk GUI,注册页面仍然会使用真实 Chromium / Chrome。

配置说明

项目启动时做结构校验,真正开始任务时再检查当前启用功能所需字段,因此可以先打开 GUI / WebUI 再逐步配置。

基础配置

配置项 说明
email_provider duckmail / yyds / cloudflare / cloudmail / outlook
register_count 本批次注册数量
enable_nsfw 注册后是否尝试开启 NSFW
sso_risk_gate_enabled 入库前是否检查 grok.com botFlagSource / policy=deny,默认 true
sso_risk_rejected_file 被风控隔离的 SSO 记录文件,默认 ./sso_risk_rejected.txt
user_agent Chromium 和请求使用的 User-Agent
proxy_mode auto / direct / single / pool
proxy 单代理地址;auto 模式下留空即直连
multi_thread_enabled 是否启用并发注册,默认 false
multi_thread_workers 并发 worker 数,范围 1–8

邮箱服务

DuckMail

{
  "email_provider": "duckmail",
  "duckmail_api_key": ""
}

YYDS

{
  "email_provider": "yyds",
  "yyds_api_key": "",
  "yyds_jwt": ""
}

yyds_api_key 和 yyds_jwt 至少填写一个。

Outlook 邮箱池

Outlook 模式使用已经存在、可通过 OAuth2 读取邮件的 Outlook / Microsoft 邮箱,不负责创建 Microsoft 邮箱。配置中只保存邮箱池文件路径:

{
  "email_provider": "outlook",
  "outlook_accounts_file": "./output/mailboxes/outlook-accounts.txt"
}

邮箱池每行格式:

email----password----clientId----refreshToken----auto

最后一列可选,支持 auto / imap / graph;省略时默认 auto。也兼容用 | 分隔的相同字段。password 字段会保留在池记录中,但验证码读取使用 clientId + refreshToken 获取 OAuth2 access token。

  • auto:提交邮箱前分别为 IMAP 与 Microsoft Graph 建立独立的发送前游标;轮询时只启用真正完成预检的通道,两者均可用时同时轮询。
  • imap:通过 outlook.office365.com:993 + XOAUTH2 读取收件箱、垃圾邮件、归档等常见文件夹;使用 UIDVALIDITY + UID 作为稳定增量游标,而不是易受删除/移动邮件影响的邮件数量或 sequence number。文件夹 LIST 结果和预检阶段的 IMAP 连接/access token 会在短暂验证码窗口内复用,断线或认证失效时再重连/刷新。
  • graph:通过 Microsoft Graph 同时监控 Inbox 与 JunkEmail;使用 immutable message ID + receivedDateTime 的发送前游标,日常轮询只拉取轻量消息前沿,确认有新邮件后才读取正文。
  • Microsoft OAuth/Graph 对超时、连接错误、429 和 5xx 做有限重试;429 优先遵守 Retry-After,其余使用带 jitter 的指数退避,并限制 Microsoft HTTP 并发。
  • 验证码仅在明确验证码语境,或发件人确认为 xAI/Grok 官方域名时提取,避免把普通工单号等 ABC-123 文本误识别成 OTP。
  • 每个邮箱在单次注册任务中最多领取一次;多线程 worker 共用同一个任务级分配器。邮箱会话使用一次性 opaque handle,开始取码后即失效,取码结束立即释放内存中的邮箱状态/access token。
  • 无法建立安全发送前游标的邮箱不会提交注册;若请求注册数量大于邮箱池有效账号数,本次任务会自动限制为邮箱池容量。
  • Outlook refresh token / access token 不会写入 mail_credentials.txt、普通日志或 config.json。邮箱池文件会尽量以 0600 权限原子写入,并已加入 .gitignore。

GUI 的“管理 Outlook 邮箱池”和 WebUI 邮箱池编辑区都提供健康检查,可在不触发 xAI 注册的情况下验证各邮箱的 IMAP/Graph 可用性;检查结果只返回邮箱、模式、通道状态和文件夹等安全元数据。Web 接口仅监听本机,并对邮箱池相关响应设置 no-store。

Cloudflare 临时邮箱

常用字段:

配置项 说明
cloudflare_api_base 邮箱 API 根地址
cloudflare_api_key 与 cloudflare_auth_mode 配套使用的认证凭据:none 时可留空;bearer 时作为 Bearer Token;x-api-key 时作为 X-API-Key;x-admin-auth 时作为 Admin Password;query-key 时作为 URL key 参数
cloudflare_auth_mode none / bearer / x-api-key / x-admin-auth / query-key
cloudflare_path_accounts 创建邮箱接口
cloudflare_path_messages 邮件列表接口
defaultDomains 默认收信域名;多个域名用英文逗号分隔

匿名创建示例:

{
  "email_provider": "cloudflare",
  "cloudflare_api_base": "https://你的-worker-api-域名",
  "cloudflare_api_key": "",
  "cloudflare_auth_mode": "none",
  "cloudflare_path_accounts": "/api/new_address",
  "cloudflare_path_messages": "/api/mails",
  "defaultDomains": "example.com"
}

Admin 创建示例:

{
  "email_provider": "cloudflare",
  "cloudflare_api_base": "https://你的-worker-api-域名",
  "cloudflare_api_key": "你的 ADMIN_PASSWORD",
  "cloudflare_auth_mode": "x-admin-auth",
  "cloudflare_path_accounts": "/admin/new_address",
  "cloudflare_path_messages": "/api/mails",
  "defaultDomains": "example.com"
}

Cloud Mail 无人收件模式

{
  "email_provider": "cloudmail",
  "cloudmail_api_base": "https://你的-Cloud-Mail-域名",
  "cloudmail_public_token": "公共 API Token",
  "cloudmail_domains": "example.com,example.net",
  "cloudmail_path_messages": "/api/public/emailList"
}

Cloud Mail 的 Public Token 直接放在 Authorization 请求头中,不需要添加 Bearer 前缀。上游当前只保存一个全局 Public Token,因此重新生成 token 后旧 token 会失效。

程序会在当前注册 slot / Proxy Lease 建立后、浏览器启动前使用同一个网络出口检查 Cloud Mail 鉴权。若遇到 401 token验证失败,会在同一出口内等待约 70 秒让 Workers KV 收敛,不会切换代理、自动生成新 token 或尝试其它鉴权格式。

如果等待窗口结束后仍持续返回 401,请检查 cloudmail_api_base、Public Token,以及 Cloud Mail Worker 实际绑定的 KV namespace 是否属于同一部署实例;不要连续重复生成 token。错误日志只记录 token 长度和 SHA-256 短指纹,不会输出完整 Public Token。

代理与代理池

默认:

{
  "proxy_mode": "auto",
  "proxy": ""
}

auto 用于兼容传统单代理配置:proxy 为空时直连,非空时使用该代理。

单代理

原生代理:

{
  "proxy_mode": "single",
  "proxy": "http://user:password@127.0.0.1:7890"
}

single 也可以直接填写受支持的高级协议 URI;高级协议需要本机可执行的 sing-box。

代理池

{
  "proxy_mode": "pool",
  "proxy_fallback": "none",
  "proxy_pool_file": "./proxies.txt",
  "proxy_pool_subscription_url": "",
  "proxy_pool_endpoint_mode": "auto",
  "proxy_pool_max_concurrent_per_node": 1,
  "proxy_protocol_backend": "auto",
  "proxy_singbox_path": "",
  "proxy_protocol_start_timeout_sec": 10,
  "proxy_runtime_idle_ttl_sec": 120,
  "proxy_runtime_cache_max": 32
}

代理源支持普通文本或整份 Base64 编码,解码后可以混合:

http://...
socks5://...
vless://...
vmess://...
trojan://...
hysteria2://...
tuic://...
ss://...

当前支持:

  • HTTP / HTTPS / SOCKS / SOCKS4 / SOCKS4A / SOCKS5 / SOCKS5H
  • VLESS / VMess / Trojan / Hysteria2 (hy2) / TUIC / Shadowsocks (ss)
  • 本地文件与 HTTP/HTTPS 订阅
  • 标准 Base64 与 URL-safe Base64 订阅
  • VLESS/VMess/Trojan 常见 TCP/WS/gRPC/HTTP/HTTPUpgrade/QUIC transport
  • VLESS TLS / uTLS / Reality 常见参数
  • 节点解析统计、健康探测、失败冷却和自动恢复
  • 固定/旋转入口、{account}、并发限制和账号级稳定 Proxy Lease

代理 runtime 采用 lazy + idle cache 机制:节点只有在实际被选中、probe 或 preflight 时才建立本地 runtime。需要统一 HTTP 出口的原生代理会使用 LocalProxyBridge;VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks 使用 sing-box。Lease 引用数降为 0 后 runtime 默认不会立即退出,而是进入空闲缓存;默认 proxy_runtime_idle_ttl_sec=120、proxy_runtime_cache_max=32,TTL 到期、缓存淘汰或 Manager shutdown 时才会关闭。设置 proxy_runtime_idle_ttl_sec=0 可恢复零引用立即关闭。

同一个账号 attempt 内,浏览器、邮箱、NSFW 和默认 CPA 保持同一个 Lease。等待验证码期间若确认尚未取得可用验证码,会在同一个 Lease 内更换邮箱重试;一旦进入验证码填写/提交阶段,后续异常不会再通过换邮箱或换代理重放注册,而会按“结果不确定”处理。

完整参数、协议映射、运行时和健康度规则见 docs/proxy-pool.md。

可选多线程注册

默认关闭:

{
  "multi_thread_enabled": false,
  "multi_thread_workers": 4
}

需要并发时:

{
  "multi_thread_enabled": true,
  "multi_thread_workers": 4
}
  • worker 范围 1–8,实际数量不会超过 register_count。
  • 每个 worker 使用独立邮箱模块和浏览器运行状态。
  • 共享输出使用锁保护。
  • 代理健康状态由所有 worker 共享,但每个账号拥有独立 Proxy Lease。

grok2api token 入池

所有入池功能都是可选的。

本地池

{
  "grok2api_auto_add_local": true,
  "grok2api_local_token_file": "",
  "grok2api_pool_name": "ssoBasic"
}

远端池

远端支持两种凭据方式,二选一:

  1. grok2api_remote_app_key
  2. grok2api_remote_admin_username + grok2api_remote_admin_password
{
  "grok2api_auto_add_remote": true,
  "grok2api_remote_base": "https://你的-grok2api-域名",
  "grok2api_remote_app_key": "",
  "grok2api_remote_admin_username": "admin",
  "grok2api_remote_admin_password": "你的管理员密码",
  "grok2api_pool_name": "ssoBasic",
  "grok2api_allow_legacy_full_save": false
}

两套远端凭据不能同时填写。新版管理员账号/密码模式对非本机地址强制要求 HTTPS;localhost / 127.0.0.1 / ::1 可以使用 HTTP。旧版 app_key 兼容接口当前接受 HTTP/HTTPS,但远程部署仍建议使用 HTTPS。

CPA / xAI OIDC 导出

{
  "cpa_export_enabled": true,
  "cpa_auth_dir": "./cpa_auths",
  "cpa_copy_to_hotload": false,
  "cpa_hotload_dir": "",
  "cpa_base_url": "https://cli-chat-proxy.grok.com/v1",
  "cpa_proxy": "",
  "cpa_headless": false,
  "cpa_force_standalone": true,
  "cpa_mint_timeout_sec": 300,
  "cpa_mint_cookie_inject": true,
  "cpa_oidc_request_timeout_sec": 15,
  "cpa_oidc_poll_timeout_sec": 15,
  "api_reverse_tools": ""
}
  • cpa_copy_to_hotload=true 时必须填写 cpa_hotload_dir。
  • 显式 cpa_proxy 始终优先。
  • 未配置 cpa_proxy 且当前账号使用 Proxy Lease 时,CPA 会继承同一个出口,包括高级协议对应的 localhost runtime。
  • CPA 导出失败只记录后处理警告,不会删除已保存账号。

输出与 pending 恢复

文件 / 目录 内容
accounts_*.txt 已成功保存的账号、密码和 SSO token
<sso_risk_rejected_file> 被 botFlagSource=1/2 或 policy=deny 隔离的 SSO;默认 ./sso_risk_rejected.txt
mail_credentials.txt 注册过程中创建的临时邮箱地址与邮箱凭据;邮箱创建后会在提交注册前提前持久化,因此可能包含后续失败、重试或结果不确定 attempt 的记录
accounts_*.txt.pending.jsonl 已注册成功但主账号结果文件未成功写入的普通账号 pending;可使用 retry-pending 恢复
<sso_risk_rejected_file>.pending.jsonl 风控账号写入主隔离文件失败后的独立 risk pending;不要使用普通 retry-pending 恢复
<grok2api_local_token_file> 可选 grok2api 本地 token 池;留空时默认项目目录下 token.json
<cpa_auth_dir>/xai-*.json 可选 CPA xAI OIDC 凭证;默认目录 ./cpa_auths
<cpa_auth_dir>/cpa_auth_failed.txt CPA 导出失败记录
screenshots/ CPA 浏览器失败调试截图

恢复 pending

python grok_register_ttk.py retry-pending <pending文件> [输出文件]

恢复过程使用文件锁、去重和原子替换,重复执行不会重复写入已经恢复成功的同一账号。

retry-pending 只用于普通账号结果 pending(例如 accounts_*.txt.pending.jsonl),不适用于 <sso_risk_rejected_file>.pending.jsonl。风控 risk pending 是独立隔离队列,成功恢复后应进入配置的 sso_risk_rejected_file;当前没有对应的 CLI 子命令,内部恢复入口为 sso_risk.retry_sso_risk_pending_file()。

项目结构

.
├── grok_register_ttk.py       # GUI / CLI 入口与主适配层
├── registration_flow.py       # GUI / CLI / WebUI 共用注册状态机、批量编排与阶段感知重试
├── registration_parallel.py   # 可选多 worker 并发协调器
├── registration_browser.py    # Chromium 注册页面状态与提交逻辑
├── browser_runtime.py         # 共享 HTTP、Chromium Options 与代理注入
├── proxy_pool.py              # proxy_pool_v3 的兼容导出层
├── proxy_pool_v3.py           # 代理池核心:Source、Lease、健康度、冷却、刷新与 Probe
├── proxy_bridge.py            # HTTP/HTTPS/SOCKS → localhost HTTP 代理桥与 Chromium 兼容
├── proxy_protocols.py         # HTTP/SOCKS/VLESS/VMess/Trojan/HY2/TUIC/SS 订阅解析
├── proxy_protocol_runtime.py  # Native bridge / sing-box lazy runtime 与 idle cache
├── mail_service.py            # 四种邮箱服务
├── app_config.py              # 默认配置、校验、加载与保存
├── account_outputs.py         # 账号、pending 与 token 输出
├── sso_risk.py                # SSO botFlag / policy 早停
├── cpa_export.py              # CPA/OIDC 导出入口
├── cpa_xai/                   # CPA 浏览器、OAuth、代理辅助与凭证写入
├── web/
│   ├── server.py              # FastAPI WebUI 控制层
│   ├── index.html             # WebUI 页面
│   ├── proxy-pool.js          # 代理池 WebUI 交互
│   └── proxy-pool.css         # 代理池 WebUI 样式
├── docs/proxy-pool.md         # 代理池详细说明
├── config.example.json        # 完整配置示例
├── requirements.txt           # 核心依赖
├── requirements-web.txt       # WebUI 可选依赖
└── tests/                     # 单元与兼容回归测试

常见问题

CLI 为什么仍然打开浏览器?

CLI 只是不启动 Tk GUI。注册页交互、验证码提交和 SSO cookie 获取仍依赖真实 Chromium / Chrome。

GUI 无法启动怎么办?

确认 Python 环境包含 Tkinter。Linux 发行版可能需要单独安装 python3-tk。也可以改用 CLI 或 WebUI。

为什么高级协议节点显示 unavailable?

VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks 需要本地 sing-box。默认从系统 PATH 查找,也可以在 WebUI / config.json 设置 proxy_singbox_path。HTTP/HTTPS/SOCKS 不受影响。

为什么某些 V2Ray 订阅节点会被跳过?

WebUI 会显示订阅协议数量和解析错误。无法映射的 transport 或无效 URI 会只跳过对应节点,不影响同一订阅里的其他有效节点。详细映射范围见 docs/proxy-pool.md。

为什么配置文件不完整时 GUI / WebUI 仍能打开?

配置保存和运行校验分开。界面允许先打开并编辑配置,开始注册时才检查当前启用服务所需字段。

注册成功后 grok2api 或 CPA 失败怎么办?

账号本身仍然属于成功。此类错误只计入“后处理警告”。

NSFW 开启失败会丢失账号吗?

不会。NSFW 是可选步骤,失败后仍会继续保存账号。

代理池为什么显示用户名和密码?

当前 WebUI 按个人部署场景设计,会显示完整代理节点和认证信息。不要把 WebUI 暴露到不受信任的网络环境。

如何查看代理池更详细的参数?

参见 docs/proxy-pool.md。

为什么账号会进入 pending?

普通 accounts_*.txt.pending.jsonl 表示注册已经完成,但主账号结果文件没有成功写入;使用 retry-pending 恢复即可,不需要重新注册。

如果是 <sso_risk_rejected_file>.pending.jsonl,则表示账号已经明确命中风控,但主隔离文件写入失败。这是独立 risk pending,不能使用普通 retry-pending。

License

MIT.

Acknowledgments

Thanks to linux.do — a vibrant tech community where this project is shared and discussed.

Star History

Star History Chart

About

批量稳定注册 Grok 账号,支持 WebUI/GUI/CLI、多邮箱服务、多线程并发、账号级多协议代理池、grok2api 入池、SSO 风控筛查与CPA OIDC 凭证导出。

Topics

Resources

Stars

2.3k stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages