---
> [!IMPORTANT]
> 本项目仅用于自动化流程研究、测试环境验证和个人学习。使用者应自行遵守目标网站服务条款、当地法律法规和第三方服务限制。请勿将本项目用于滥用、绕过平台限制或未经授权的商业用途。
## 目录
- [当前功能](#当前功能)
- [运行流程](#运行流程)
- [环境要求](#环境要求)
- [安装](#安装)
- [配置](#配置)
- [运行方式](#运行方式)
- [输出与 pending 恢复](#输出与-pending-恢复)
- [稳定性与安全机制](#稳定性与安全机制)
- [项目架构](#项目架构)
- [常见问题](#常见问题)
- [License](#license)
- [Acknowledgments](#acknowledgments)
- [Star History](#star-history)
## 当前功能
- 使用真实 Chromium / Chrome 页面完成注册、验证码、资料填写、Turnstile 与 SSO cookie 获取。
- 支持四种邮箱服务：
- DuckMail
- YYDS
- Cloudflare 临时邮箱
- Cloud Mail 无人收件模式
- 成功账号实时写入 `accounts/accounts_*.txt`。
- 主结果写入失败时自动写入 `*.pending.jsonl`，可稍后幂等恢复。
- 支持将 SSO token 写入 grok2api，并将本地生成的 xAI OAuth 凭据写入 sub2api。
- 支持注册成功后可选导出 CLIProxyAPI 使用的 CPA xAI OIDC 凭证。
- 支持注册后尝试开启 NSFW；失败不会影响账号保存。
- 支持浏览器重启、卡住重试、邮箱更换、定期内存清理和安全取消。
- GUI / CLI 均展示四项批次状态：
- 成功
- 失败
- 待恢复
- 后处理警告
## 运行流程
单个账号的主要流程如下：
```text
打开注册页
→ 创建临时邮箱并提交
→ 轮询并填写验证码
→ 填写资料
→ 等待 SSO cookie
→ 可选开启 NSFW
→ 保存账号
→ 可选写入 grok2api
→ 可选导出 CPA/OIDC
→ 可选将 CPA/OIDC 凭据写入 sub2api
```
账号已经注册成功后，token 入池或 CPA 导出属于**附加后处理**。附加功能失败只会增加“后处理警告”，不会把已经保存的账号重新统计为注册失败。
## 环境要求
- Python **3.9+**
- Google Chrome 或 Chromium
- 可访问注册页面和所选邮箱 API 的网络环境
- GUI 模式需要 Tkinter；没有 Tkinter 时可使用 CLI 模式
## 安装
克隆仓库：
```bash
git clone https://github.com/AaronL725/grok-register.git
cd grok-register
```
建议创建虚拟环境：
```bash
python -m venv .venv
```
激活虚拟环境：
```bash
# Windows PowerShell
.venv\Scripts\Activate.ps1
# macOS / Linux
source .venv/bin/activate
```
安装依赖：
```bash
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```
复制配置文件：
```bash
# macOS / Linux
cp config.example.json config.json
# Windows CMD
copy config.example.json config.json
```
然后编辑 `config.json`。该文件包含 API Key、JWT、代理和远端服务密钥等。
## 配置
配置校验分为两层：
1. **结构校验**：检查类型、枚举、URL 和数值范围。GUI 启动时只执行这一层，因此旧配置缺少当前服务所需字段时仍可打开界面修改。
2. **运行校验**：点击“开始注册”或启动 CLI 任务时，检查当前启用功能所需的配置。
### 基础配置
| 配置项 | 说明 |
| --- | --- |
| `email_provider` | `duckmail`、`yyds`、`cloudflare` 或 `cloudmail` |
| `register_count` | 本批次目标数量，允许范围由配置校验控制 |
| `proxy` | 主注册流程代理，可留空 |
| `enable_nsfw` | 注册后是否尝试开启 NSFW |
| `user_agent` | 浏览器和请求使用的 User-Agent |
### DuckMail
| 配置项 | 说明 |
| --- | --- |
| `duckmail_api_key` | 可选 DuckMail API Key |
### YYDS
| 配置项 | 说明 |
| --- | --- |
| `yyds_api_key` | YYDS API Key |
| `yyds_jwt` | YYDS JWT |
选择 `yyds` 时，`yyds_api_key` 和 `yyds_jwt` 至少配置一个，否则运行校验会直接拒绝启动。
### Cloudflare 临时邮箱
| 配置项 | 说明 |
| --- | --- |
| `cloudflare_api_base` | Cloudflare 临时邮箱 API 根地址 |
| `cloudflare_api_key` | 匿名模式留空；admin 模式填写 `ADMIN_PASSWORD` |
| `cloudflare_auth_mode` | `none`、`bearer`、`x-api-key`、`x-admin-auth` 或 `query-key` |
| `cloudflare_path_domains` | 域名列表路径，默认 `/api/domains` |
| `cloudflare_path_accounts` | 创建邮箱路径，默认 `/api/new_address` |
| `cloudflare_path_token` | token 路径，默认 `/api/token` |
| `cloudflare_path_messages` | 收件列表路径，默认 `/api/mails` |
| `defaultDomains` | 默认收信域名；多个域名用英文逗号分隔并轮换使用 |
#### 匿名创建模式
```json
{
"email_provider": "cloudflare",
"cloudflare_api_base": "https://你的-worker-api-域名",
"cloudflare_api_key": "",
"cloudflare_auth_mode": "none",
"cloudflare_path_domains": "/api/domains",
"cloudflare_path_accounts": "/api/new_address",
"cloudflare_path_token": "/api/token",
"cloudflare_path_messages": "/api/mails",
"defaultDomains": "example.com"
}
```
#### Admin 创建模式
当匿名 `/api/new_address` 受 Turnstile 限制时，可使用：
```json
{
"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"
}
```
Admin 密码只用于创建邮箱。读取邮件仍使用创建接口返回的邮箱 JWT。
可先使用调试脚本验证接口：
```bash
python cf_mail_debug.py \
--api-base "https://你的-worker-api-域名" \
--auth-mode x-admin-auth \
--api-key "你的 ADMIN_PASSWORD" \
--create-path /admin/new_address \
--domain "example.com"
```
### Cloud Mail 无人收件模式
| 配置项 | 说明 |
| --- | --- |
| `cloudmail_api_base` | Cloud Mail 站点根地址 |
| `cloudmail_public_token` | 公共收件 API Token |
| `cloudmail_domains` | 无人收件域名，多个域名用英文逗号分隔 |
| `cloudmail_path_messages` | 默认 `/api/public/emailList` |
示例：
```json
{
"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 模式直接生成随机地址，不预先创建邮箱账户。公共 Token 只从 `config.json` 读取，不会作为邮箱 credential 写入 `mail_credentials.txt`。
### grok2api token 池
| 配置项 | 说明 |
| --- | --- |
| `grok2api_auto_add_local` | 是否写入本地 token 池 |
| `grok2api_local_token_file` | 本地 `token.json` 路径；留空使用项目默认路径 |
| `grok2api_pool_name` | `ssoBasic` 或 `ssoSuper` |
| `grok2api_auto_add_remote` | 是否写入远端 token 池 |
| `grok2api_remote_base` | 站点根地址、`/admin` 或 `/admin/api` 地址 |
| `grok2api_remote_app_key` | 远端管理 API 的 app key |
| `grok2api_allow_legacy_full_save` | 是否允许旧版全量保存回退；默认关闭 |
远端入池优先尝试增量 `/tokens/add`。旧版全量保存默认关闭，以避免并发覆盖；即使显式开启，也要求远端返回 ETag，并通过 `If-Match` 保护写入。
```json
{
"grok2api_auto_add_remote": true,
"grok2api_remote_base": "https://你的-grok2api-域名/admin/api",
"grok2api_remote_app_key": "你的 app_key",
"grok2api_pool_name": "ssoBasic",
"grok2api_allow_legacy_full_save": false
}
```
### sub2api 远端账号池
启用后，项目先通过本地 CPA 浏览器流程生成 xAI OAuth 凭据，再调用
`POST /api/v1/admin/accounts` 创建远端 Grok OAuth 账号。该路径不依赖 sub2api
服务端的 SSO 转换器，可避免普通 HTTP 客户端被 xAI Cloudflare 拦截。
导入账号默认并发数为 `10`、优先级为 `1`。创建时只刷新 OAuth，不立即执行 quota
或模型探测。本批账号全部创建后等待 10 秒，再按创建顺序使用 `grok-4.5`
逐个检查。明确返回 401/403/Forbidden 的新账号会被删除；网络超时、5xx
或响应不确定时保留账号。全部检查结束后，程序按实际删除数量补注册一次，
回补账号不在同一轮重复检查，以避免无限循环。
| 配置项 | 说明 |
| --- | --- |
| `sub2api_auto_add_remote` | 是否在注册成功后写入 sub2api |
| `sub2api_remote_base` | sub2api 站点根地址或 `/api/v1` 地址 |
| `sub2api_admin_api_key` | sub2api 管理员 API Key，请求使用 `x-api-key` 鉴权 |
| `sub2api_group_ids` | 可选分组 ID，多个值用英文逗号分隔 |
| `sub2api_delete_unusable_after_reauth` | 是否删除重登后仍不可用，或首次 403/Forbidden 且无法重登的账号；默认关闭 |
| `sub2api_auto_replenish` | 维护结束后是否按 grok-4.5 可用账号数自动补号 |
| `sub2api_replenish_target` | 自动补号的可用账号目标，范围 1-2500 |
| `sub2api_scheduled_maintenance` | 是否在 GUI 运行期间定时执行完整维护周期 |
| `sub2api_maintenance_interval_hours` | 定时维护间隔小时数，范围 1-168 |
启用 sub2api 远端入池时必须同时启用 `cpa_export_enabled`。
```json
{
"sub2api_auto_add_remote": true,
"sub2api_remote_base": "https://你的-sub2api-域名",
"sub2api_admin_api_key": "admin-开头的管理员 API Key",
"sub2api_group_ids": "1,2",
"sub2api_delete_unusable_after_reauth": false,
"sub2api_auto_replenish": false,
"sub2api_replenish_target": 100,
"sub2api_scheduled_maintenance": false,
"sub2api_maintenance_interval_hours": 24
}
```
管理员 API Key 可在 sub2api 管理后台的“设置 → 安全 → Admin API Key”中生成，典型格式为
`admin-<64hex>`。远端入池失败会记录为后处理警告，不影响已保存的注册账号。
GUI 的“检测并重登”会先扫描全部远端 Grok OAuth 账号，并逐个通过账号测试接口明确使用
`grok-4.5` 验证。只有模型测试或 usage 状态明确标记为 `needs_reauth`、401/403、
Forbidden 或缺少 OAuth token 时才会重登，并从本地 `accounts/accounts_*.txt` 查找对应密码和
SSO。全部扫描完成后才开始重登；重登后再次使用 `grok-4.5` 复检。启用自动删除时，
首次检测明确为 403/Forbidden，但本地无凭据或重登失败的账号会直接删除。
网络超时、5xx、服务端实际使用其他模型或无法确认的响应只记录警告，不会删除账号。
启动具有自动删除能力的手动任务前会要求二次确认。
启用“自动补号”后，维护周期按通过 `grok-4.5` 实测的账号数计算缺口。例如可用 92 个、
目标 100 个时，本轮注册 8 个。新增账号会在本轮完成延迟检查，并按删除数量
回补一次。自动补号要求同时启用 sub2api 远端入池及 CPA/OIDC 导出。
启用“定时执行”并运行一次维护保存配置后，GUI 会在每个维护周期结束后重新计时；GUI
重启时也会恢复计时。到点时若另一个任务仍在运行，会在 5 分钟后重试。
### CPA / xAI OIDC 导出
| 配置项 | 说明 |
| --- | --- |
| `cpa_export_enabled` | 是否在注册成功后导出 CPA xAI OIDC 凭证 |
| `cpa_auth_dir` | 输出目录，默认 `./cpa_auths` |
| `cpa_copy_to_hotload` | 是否复制到 CLIProxyAPI auth-dir |
| `cpa_hotload_dir` | 热加载目录；仅导出开启且复制开启时必填 |
| `cpa_base_url` | CPA 凭证中的 API Base URL |
| `cpa_proxy` | CPA 专用代理；留空回退到主 `proxy` |
| `cpa_headless` | CPA 浏览器是否无头；默认建议 `false` |
| `cpa_force_standalone` | 是否使用独立 CPA 浏览器会话 |
| `cpa_mint_timeout_sec` | 浏览器授权整体超时 |
| `cpa_mint_cookie_inject` | 是否向 CPA 会话注入已取得的 cookie |
| `cpa_oidc_request_timeout_sec` | Device Authorization 请求超时 |
| `cpa_oidc_poll_timeout_sec` | 单次 token 轮询请求超时 |
| `api_reverse_tools` | 可选外部 `cpa_xai` 包目录 |
最小配置：
```json
{
"cpa_export_enabled": true,
"cpa_auth_dir": "./cpa_auths",
"cpa_base_url": "https://cli-chat-proxy.grok.com/v1",
"cpa_proxy": "",
"cpa_headless": false,
"cpa_force_standalone": true,
"cpa_mint_cookie_inject": true
}
```
CPA 浏览器直接复用 `browser_runtime.py` 的 Chromium options 和 `cpa_xai/proxyutil.py` 的代理桥，不会反向导入主程序或创建第二份主模块全局状态。
## 运行方式
### GUI
```bash
python grok_register_ttk.py
```
GUI 启动时读取配置并执行结构校验。填写配置后点击“开始注册”，程序会执行完整运行校验，只保存一次配置，然后启动后台线程。
每个新批次开始前，成功、失败、待恢复和后处理警告四项统计都会全部清零。
### CLI
以下命令等价：
```bash
python grok_register_ttk.py cli
python grok_register_ttk.py start
python grok_register_ttk.py --cli
```
CLI 读取 `config.json` 中的 `register_count`，通过运行校验后提示：
```text
> start
```
输入 `start` 才会开始。按 `Ctrl+C` 可请求停止并执行最终清理。
> CLI 只是不启动 Tk GUI，注册过程仍会打开 Chromium / Chrome。
### 恢复 pending 结果
```bash
python grok_register_ttk.py retry-pending 
