grok-keygen/README.md

# grok-reg-protocol-cpa

基于 **Chromium + DrissionPage + turnstilePatch** 的免费 Grok 账号注册机。

注册成功后产出两类凭证：

| 产物 | 用途 | 路径 |
|------|------|------|
| **SSO** | grok.com / grok2api Web 池 | 账本第三段 + 可选推远端池 |
| **OIDC（CPA xAI）** | 免费 **Grok 4.5**（Grok Build / cli-chat-proxy） | `cpa_auths/xai-<email>.json` |

> **硬约束：SSO ≠ OIDC。**  
> 免费 Grok 4.5 **不能**用账本里的 sso JWT 直接打 API；必须再走  
> `accounts.x.ai` device-auth 铸 OIDC，写成 CPA 的 `type=xai` 认证文件。  
> 有 SSO 时优先走 **纯 HTTP Device Flow**；失败再回退浏览器 consent。

---

## 当前推荐链路（Gmail catch-all）

本仓库当前实配以 **Gmail IMAP + Cloudflare catch-all 域名** 为主：

1. 用 catch-all 域名生成随机注册邮箱（如 `xxx@zhangyunuo.net`）
2. 验证码转发到 Gmail，经 IMAP 拉取
3. 注册拿到 SSO
4. 协议优先 mint OIDC → `cpa_auths/xai-*.json`

```
[Cloudflare catch-all 域名 → Gmail]
            ↓  注册 accounts.x.ai
 accounts_cli.txt                 email----password----sso
            ↓
 grok2api 池 (可选)               SSO → Web 非 4.5 模型
            ↓
 OIDC mint（协议优先 → 浏览器回退）
            ↓
 cpa_auths/xai-email.json         【注册机主导出】
            ↓ (cpa_copy_to_hotload=true 时)
 CPA auth-dir 热加载              【可选·本地拷贝】
            ↓ (cpa_auto_import_remote=true 时)
 CPA Management API 导入          【可选·HTTP】
            ↓
 CLIProxyAPI :8317                model=grok-4.5
```

也支持：`cloudmail` / `hotmail|outlookmail` / `cloudflare` / `duckmail` / `yyds`。

---

## 环境

| 依赖 | 说明 |
|------|------|
| Linux / macOS | 协议 mint **不需要**浏览器；注册 / 回退浏览器需要 Chromium |
| 无桌面服务器 | **`./start.sh` 自动 Xvfb**（无 DISPLAY 时）；失败再回退 Python headless |
| `uv` + Python 3.13 | 见 `pyproject.toml` / `uv.lock`；可选 `mise` |
| Chromium / Chrome | 注册流程 + 协议失败回退时需要 |
| 代理（按需） | 访问 xAI / accounts.x.ai 不通时配置 `proxy` / `cpa_proxy` |
| 可选 | grok2api `:8000`、CLIProxyAPI(CPA) `:8317` |

无头服务器（推荐直接 `./start.sh`）：

```bash
# 一键：缺啥装啥 + 无 DISPLAY 自动 xvfb-run / 常驻 Xvfb
./start.sh --extra 1 --threads 1

# 跳过 Xvfb，强制走 Python 自动 headless
SKIP_XVFB=1 ./start.sh --extra 1

# 即使已有 DISPLAY 也包一层 xvfb-run
FORCE_XVFB=1 ./start.sh --extra 1

# 手动（不经过 start.sh）
sudo apt install -y xvfb google-chrome-stable
xvfb-run -a uv run python -u register_cli.py --extra 1 --threads 1
```

```bash
cd /path/to/grok-reg-protocol-cpa
uv sync
uv run python -c "from DrissionPage import Chromium; from curl_cffi import requests; print('OK')"
```

或用 mise：

```bash
mise install
mise run deps
```

---

## 快速开始（Gmail）

```bash
cd grok-reg-protocol-cpa
uv sync

# 1) 主配置
cp config.example.json config.json

# 2) 环境变量（可选；也可直接写进 config.json）
cp .env.example .env
# 编辑 .env：
#   GMAIL_USER=you@gmail.com
#   GMAIL_PASSWORD=xxxx xxxx xxxx xxxx   # Gmail 应用专用密码

# 3) 在 config.json 中至少确认：
#   "email_provider": "gmail",
#   "defaultDomains": "your-catchall-domain.com",
#   "gmail_imap_user": "you@gmail.com",      # 或依赖 .env 的 GMAIL_USER
#   "gmail_imap_password": "app password",   # 或依赖 .env 的 GMAIL_PASSWORD
#   "proxy": "",                             # 需要时填 http://127.0.0.1:7890
#   "cpa_export_enabled": true

# 4) 注册 1 个号（含 SSO + CPA 导出）
uv run python -u register_cli.py --extra 1 --threads 1
```

GUI：

```bash
uv run python grok_register_ttk.py
# 或 mise run gui
```

---


## Gmail + Cloudflare Email Worker（秒级取码）

推荐混合链路（**不需要公网 IP / 内网穿透**）：

```
xAI 发信
  → Cloudflare Email Routing（域名 catch-all）
  → Email Worker：解析验证码 → 写入 KV
  → （可选）forward 到 Gmail，保留 IMAP 兜底
  → 注册机：GET https://<worker>/code?to=alias@domain&key=...
  → 未命中再回退 Gmail IMAP
```

### 1. 部署 Worker

```bash
cd cf-email-worker
# 详见 cf-email-worker/README.md
npx wrangler login
npx wrangler kv namespace create GROK_MAIL_CODES   # id 写入 wrangler.toml
npx wrangler secret put CODE_API_KEY
# 可选：保留 Gmail 兜底
# printf 'you@gmail.com' | npx wrangler secret put GMAIL_FORWARD_TO
npx wrangler deploy
```

或用助手脚本：

```bash
export GMAIL_FORWARD_TO='you@gmail.com'   # 可选
bash scripts/setup_gmail_worker.sh
```

### 2. Email Routing

Dashboard → **Email Routing** → Catch-all → **Send to a Worker** → 选 `grok-xai-mail-codes`。

> 若以前 catch-all 只转发 Gmail：改成进 Worker，由 Worker 内 `GMAIL_FORWARD_TO` 再转到 Gmail。

### 3. 注册机配置

`config.json`（`email_provider` 仍为 `gmail`）：

```json
{
  "email_provider": "gmail",
  "defaultDomains": "your-domain.com",
  "gmail_imap_user": "you@gmail.com",
  "gmail_imap_password": "app-password",
  "gmail_worker_enabled": true,
  "gmail_worker_url": "https://grok-xai-mail-codes.<subdomain>.workers.dev",
  "gmail_worker_api_key": "与 CODE_API_KEY 相同",
  "gmail_worker_timeout_sec": 25,
  "gmail_worker_poll_interval": 0.4,
  "gmail_imap_fallback": true
}
```

### 4. 自测

```bash
# 模拟入库 + 取码
python scripts/test_gmail_worker.py --to test@your-domain.com --ingest-demo

# 真实邮件：给 random@your-domain.com 发信后轮询
python scripts/test_gmail_worker.py --to random@your-domain.com --timeout 60
```

日志里成功时会看到：

```text
[*] Gmail 取码：优先 Email Worker（timeout=25s），超时回退 IMAP
[*] Gmail Worker 取到验证码: ABC-DEF (elapsed=2.1s ...)
```

未命中 Worker 时：

```text
[*] Gmail Worker 未命中，回退 IMAP（剩余 timeout=...s）
[*] Gmail IMAP 从邮件中提取到验证码: ...
```


## 配置

1. 复制模板并编辑（模板内 `"//…"` 键是注释，加载时忽略）：

```bash
cp config.example.json config.json
```

2. **字段详解见 `config.example.json` 内注释键。**

### 环境变量（`.env`）

真实进程环境变量优先于 `.env`；多数项也可写在 `config.json`。

| 变量 | 用途 |
|------|------|
| `GMAIL_USER` / `GMAIL_PASSWORD` | Gmail IMAP（`email_provider=gmail`） |
| `MAIL_USER` / `MAIL_PASSWORD` | 兼容别名（`gmail_code_listener`） |
| `CLOUDMAIL_URL` / `CLOUDMAIL_ADMIN_EMAIL` / `CLOUDMAIL_PASSWORD` | CloudMail 管理端 |
| `GROK2API_APP_KEY` | 远端 grok2api Admin |
| `API_REVERSE_TOOLS` | 可选：外部 `cpa_xai` 父目录 |
| `CPA_EXPORT` | `auto_register` 是否导出 CPA（`0/false` 关） |
| `CPA_AUTO_IMPORT_REMOTE` | 是否自动导入远程 CPA（`1/true` 开，`0/false` 关；优先于 config） |
| `CPA_REMOTE_BASE` | 远程 CPA 根地址 |
| `CPA_REMOTE_PASSWORD` | 远程 CPA 管理密码 |
| `https_proxy` / `http_proxy` | 代理回退 |

模板见 `.env.example`。

### 邮箱模式

#### A. Gmail + catch-all（推荐）

```json
{
  "email_provider": "gmail",
  "defaultDomains": "your-catchall-domain.com",
  "gmail_imap_user": "you@gmail.com",
  "gmail_imap_password": "xxxx xxxx xxxx xxxx",
  "gmail_imap_host": "imap.gmail.com",
  "gmail_imap_port": 993,
  "gmail_resend_after_sec": 45
}
```

说明：

- `defaultDomains`：Cloudflare 等 catch-all 域名，用于生成注册邮箱
- 验证码实际进入 Gmail；用 **应用专用密码**，不是登录密码
- 也可把账号密码只写在 `.env` 的 `GMAIL_USER` / `GMAIL_PASSWORD`
- 取到验证码后默认 **删除该邮件**（`gmail_delete_after_code: true`），避免 catch-all 邮箱堆积；失败不影响注册

#### B. Hotmail / Outlook

```json
{
  "email_provider": "hotmail",
  "hotmail_accounts_file": "mail_credentials.txt",
  "hotmail_max_aliases_per_account": 5
}
```

```bash
cp mail_credentials.example.txt mail_credentials.txt
```

每行四段（`----` 分隔）：

```text
邮箱----密码----ClientID----Token
```

| 段 | 含义 |
|----|------|
| 邮箱 | Hotmail / Outlook 主邮箱 |
| 密码 | 邮箱登录密码（注册机侧保留；IMAP 走 OAuth） |
| ClientID | Azure AD 应用 Client ID |
| Token | Microsoft OAuth2 **refresh_token**（XOAUTH2 IMAP） |

运行时摘要：

- 默认先用原邮箱，后续用随机 plus alias
- `outlook.office365.com`（可回退 `imap-mail.outlook.com`）XOAUTH2 IMAP 收码
- refresh_token 轮换会**自动回写** `mail_credentials.txt`

#### C. CloudMail

需要 `cloudmail_url` / `cloudmail_admin_email` / `cloudmail_password` + `defaultDomains`。  
也可用环境变量 `CLOUDMAIL_*`。

### 代理优先级

| 字段 | 作用 |
|------|------|
| `proxy` | **注册** Chromium + 邮箱等 HTTP |
| `cpa_proxy` | **OIDC mint**（协议 HTTP + 回退浏览器 + probe） |

```
cpa_proxy  >  proxy  >  环境变量 https_proxy/http_proxy
```

### CPA / OIDC 关键项

| 字段 | 默认 | 含义 |
|------|------|------|
| `cpa_export_enabled` | `true` | 注册成功后是否 mint OIDC |
| `cpa_prefer_protocol` | `true` | 有 SSO 时先走纯 HTTP 协议 mint |
| `cpa_protocol_only` | `false` | `true`=协议失败也不回退浏览器 |
| `cpa_protocol_poll_timeout_sec` | `90` | 协议路径 token 轮询超时 |
| `cpa_auth_dir` | `./cpa_auths` | 主导出目录 |
| `cpa_copy_to_hotload` | `false` | 是否复制到 CPA 热加载目录 |
| `cpa_hotload_dir` | `""` | CPA `auth-dir`（仅 copy 时） |
| `cpa_base_url` | `https://cli-chat-proxy.grok.com/v1` | 免费 Build **必须**此上游 |
| `browser_headless` | `auto` | 注册浏览器：`auto`=无 DISPLAY 自动 headless；`true`/`false` 强制 |
| `cpa_headless` | `false` | 回退浏览器：有 DISPLAY 时建议有头；无 DISPLAY 时强制 headless |
| `cpa_force_standalone` | `true` | 回退时独立 Chromium |
| `cpa_mint_cookie_inject` | `true` | 回退时注入注册 cookie |
| `cpa_mint_workers` | `-1` | mint 并发：`-1` 自动；`0` 内联；`1-10` 固定 |
| `cpa_mint_required` | `false` | mint 失败是否整号失败 |
| `cpa_auto_import_remote` | `false` | 写出后是否自动导入远程 CPA |
| `cpa_remote_base` | `""` | CPA **根地址**，如 `http://127.0.0.1:8317` |
| `cpa_remote_password` | `""` | CPA 管理密码（也可用环境变量） |
| `cpa_remote_import_retries` | `3` | 远程导入重试次数 |
| `cpa_remote_import_retry_delay` | `2` | 重试间隔（秒） |

### 自动导入远程 CPA（Management API）

写出 `cpa_auths/xai-*.json` 后，可自动调用 CLIProxyAPI 管理接口导入，无需再手动 `cp` 到 auth-dir。

```json
{
  "cpa_export_enabled": true,
  "cpa_auto_import_remote": true,
  "cpa_remote_base": "http://127.0.0.1:8317",
  "cpa_remote_password": "你的管理密码"
}
```

或全部写在 `.env`（开关也可用环境变量）：

```bash
CPA_AUTO_IMPORT_REMOTE=1
CPA_REMOTE_BASE=http://127.0.0.1:8317
CPA_REMOTE_PASSWORD=你的管理密码
```

说明：

- `CPA_AUTO_IMPORT_REMOTE=1/true/yes` 开启，`0/false/no` 关闭；**env 优先于** `config.json`
- **只填根地址**（到端口即可）；程序会请求  
  `POST {base}/v0/management/auth-files?name=xai-email.json`
- 认证头：`Authorization: Bearer <管理密码>`（同时附带 `X-Management-Key`）
- 管理密码对应 CPA 的 `MANAGEMENT_PASSWORD` 或 `remote-management.secret-key` **原文**
- 远程访问需 CPA 允许管理端（设置 `MANAGEMENT_PASSWORD` 或 `allow-remote: true`）
- **导入失败不阻断注册**：本地文件已写出仍算成功，只打日志  
  `[cpa] remote import failed: ...`
- 成功日志：`[cpa] remote import ok -> http://host:8317 name=xai-....json`

等价手动调用：

```bash
curl -sS -X POST   "http://127.0.0.1:8317/v0/management/auth-files?name=xai-user@domain.json"   -H "Authorization: Bearer $CPA_REMOTE_PASSWORD"   -H "Content-Type: application/json"   --data-binary @./cpa_auths/xai-user@domain.json
```

### 落盘约定

| 路径 | 是否必须 | 说明 |
|------|----------|------|
| `.env` | 可选 | Gmail / CloudMail 等密钥（勿提交） |
| `config.json` | 是 | 本地实配（勿提交） |
| `mail_credentials.txt` | hotmail 模式必须 | 四段凭证池 |
| `accounts_cli.txt` / `accounts_*.txt` | 是 | 主账本 `email----password----sso` |
| `cpa_auths/xai-*.json` | 开 export 时 | CPA 格式 OIDC 归档 |
| `emails_used.txt` / `emails_error.txt` | 运行时 | 邮箱占用/失败记录 |
| CPA `…/auths/xai-*.json` | 可选 | 热加载；由 `cpa_copy_to_hotload` 控制 |

---

## 协议 OIDC → CPA（失败回退浏览器）

```
注册成功拿到 sso cookie
        ↓
【优先】protocol_mint：curl_cffi + sso
   device/code → verify → approve → token 轮询
        ↓ 成功
  cpa_auths/xai-<email>.json   mint_method=protocol
        ↓ 失败
【回退】browser_confirm：有头 Chromium + turnstilePatch
   同一套 device-auth，页面点「允许」
        ↓
  cpa_auths/xai-<email>.json   mint_method=browser
```

实测：协议路径约数秒级；浏览器路径约 40–60s/号。

日志示例：

```text
[cpa] mint try protocol (SSO HTTP device flow)
[cpa] protocol token ok ...
[cpa] mint protocol SUCCESS
[cpa] mint_method=protocol
```

本仓库自包含铸造代码：

| 路径 | 说明 |
|------|------|
| `cpa_xai/protocol_mint.py` | SSO → 纯 HTTP Device Flow |
| `cpa_xai/mint.py` | 协议优先，失败回退浏览器 |
| `cpa_xai/browser_confirm.py` | 有头 Chromium 完成 consent |
| `cpa_export.py` | 注册成功 hook |
| `scripts/backfill_cpa_xai_from_accounts.py` | 存量账号批量补 CPA |
| `scripts/export_cpa_xai_from_grok_auth.py` | 从 `~/.grok/auth.json` 导出 |

---

## 命令

前置：

```bash
cd /path/to/grok-reg-protocol-cpa
# 代理建议写在 config.json 的 proxy / cpa_proxy
# 回退浏览器时需要桌面会话
export DISPLAY=${DISPLAY:-:0}
```

### A. 新注册 N 个号（含 SSO + OIDC 导出）

```bash
# 再注册 1 个（推荐）
uv run python -u register_cli.py --extra 1 --threads 1

# 再注册 5 个
uv run python -u register_cli.py --extra 5 --threads 2

# GUI
uv run python grok_register_ttk.py
# 或 mise run gui / mise run register
```

成功时：

1. 追加账本 `email----password----sso`
2. 可选：推 grok2api
3. 若 `cpa_export_enabled`：协议 mint（失败则浏览器）→ `cpa_auths/xai-<email>.json`
4. 若 `cpa_copy_to_hotload`：再拷到 `cpa_hotload_dir`
5. 若 `cpa_auto_import_remote`：POST 导入到 CPA Management API（失败只记日志）

### B. 存量号补 CPA（只 mint，不重新注册）

账本需含 SSO（第三段）。有 SSO 时通常**无需**弹浏览器：

```bash
uv run python -u scripts/backfill_cpa_xai_from_accounts.py \
  --accounts accounts_cli.txt \
  --limit 1 --probe --timeout 300

# 全量缺失号
uv run python -u scripts/backfill_cpa_xai_from_accounts.py \
  --limit 0 --probe --timeout 300 --sleep 3
```

| 参数 | 含义 |
|------|------|
| `--limit N` | 本次最多 N 个缺失号；`0`=全部 |
| `--email x@y` | 只处理指定邮箱 |
| `--out-dir` | 主导出目录 |
| `--cpa-dir` | 成功后复制到 CPA 热加载目录 |
| `--probe` | 检查是否列出 `grok-4.5` |
| `--headless` | 强制无头浏览器（无 DISPLAY 时默认也会自动 headless） |
| `--headed` | 强制有头（需 DISPLAY / xvfb-run；无显示仍回退 headless） |

### C. 从 `~/.grok/auth.json` 导出

```bash
uv run python scripts/export_cpa_xai_from_grok_auth.py --out-dir ./cpa_auths
```

### D. 手动导入 CPA 热加载

```bash
cp -a ./cpa_auths/xai-USER@domain.json "$CPA_AUTH_DIR"/
chmod 600 "$CPA_AUTH_DIR"/xai-USER@domain.json
```

### E. 调用验证（免费 Grok 4.5）

```bash
KEY="<你的 CPA API KEY>"

curl -sS http://127.0.0.1:8317/v1/models -H "Authorization: Bearer $KEY" | head

curl -sS http://127.0.0.1:8317/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [{"role":"user","content":"Reply with exactly OK"}],
    "stream": false
  }'
```

---

## CLI 参数速查（`register_cli.py`）

| 参数 | 含义 |
|------|------|
| `--extra N` | **再新注册 N 个**（推荐） |
| `--count N` | 账号**总数目标**（含已有）；已达标则退出 |
| `--threads N` | 注册并发 1–10 |
| `--mint-workers N` | CPA mint 并发：`-1`=config/auto；`0`=内联；`1-10`=固定 |
| `--mint-queue-max N` | mint 队列背压：`-1`=auto(2×workers)；`0`=不限制 |
| `--accounts-file` | 账本路径 |
| `--fast` / `--no-fast` | 快速模式（默认开）/ 关闭 |
| `--no-browser-reuse` | 每号强制 quit 浏览器 |
| `--browser-recycle-every N` | 复用 N 次后完整回收 |
| `--cookie-snapshot` | 注册成功写 cookie 快照 |
| `--inline-mint` | 强制注册线程内联 mint（调试） |

---

## 故障排查

| 现象 | 原因 / 处理 |
|------|-------------|
| Gmail 收不到码 | 检查应用专用密码、catch-all 是否进 Gmail、`defaultDomains`、IMAP 是否开启 |
| 协议 `sso invalid` | SSO 过期/无效；会回退浏览器；检查账本第三段 |
| 协议 verify/approve 失败 | 会话态变化 / 风控；看日志后自动回退浏览器 |
| 一直 `authorization_pending` | 浏览器路径未完成 consent；需到「设备已授权」且 token 200 |
| Cloudflare / Turnstile | 必须用 **Chromium + turnstilePatch**（Chrome 无法 `--load-extension`，token 常为 0）；配合 `./start.sh` 自动 Xvfb |
| Turnstile token 长度=0 | 日志若 `skip turnstilePatch on Google Chrome`：`sudo apt install -y chromium` 后重跑；或 `browser_path` 指向 chromium |
| 浏览器 connection fails / no interface | 无 DISPLAY：`./start.sh` 自动 Xvfb / Python headless |
| Hotmail 收不到码 | 检查四段凭证、ClientID/Token、IMAP 主机与 alias 计数 |
| 有 token 但无 grok-4.5 | `cpa_base_url` 是否为 `cli-chat-proxy` |
| 注册成功但无 `cpa_auths` | `cpa_export_enabled`？看 `cpa_auths/cpa_auth_failed.txt` |
| 远程导入失败 | 检查 `cpa_remote_base` / 管理密码、CPA 是否开启 management、`allow-remote`；本地文件仍在 `cpa_auths/` |

调试原则：以 **token 端点返回 `access_token` + refresh_token** 为准；probe 看 `/v1/models` 是否含 `grok-4.5`。

---

## 目录结构

```
grok-reg-protocol-cpa/
  register_cli.py              # CLI 批量注册 + mint 流水线
  grok_register_ttk.py         # 浏览器注册核心（多邮箱 provider）
  auto_register.py             # 另一套自动注册入口
  gmail_code_listener.py       # Gmail 验证码监听辅助
  cpa_export.py                # 成功 hook
  cpa_xai/
    protocol_mint.py           # SSO 纯 HTTP Device Flow（协议优先）
    mint.py                    # 协议 → 浏览器回退编排
    browser_confirm.py         # 原浏览器 consent
    oauth_device.py / schema.py / writer.py / probe.py ...
  scripts/
    backfill_cpa_xai_from_accounts.py
    export_cpa_xai_from_grok_auth.py
  config.example.json
  .env.example
  config.json                  # 本地实配（勿提交）
  .env                         # 本地密钥（勿提交）
  mail_credentials.example.txt # Hotmail 四段模板
  mail_credentials.txt         # 本地邮箱池（勿提交）
  accounts_cli.txt             # 主账本（勿提交）
  cpa_auths/                   # xai-<email>.json（勿提交）
  turnstilePatch/
  pyproject.toml / uv.lock / mise.toml
```

---

## 安全

- `config.json`、`.env`、`mail_credentials.txt`、账本、`cpa_auths/*.json` 含密码与 token  
  **权限建议 600；勿提交 git；勿塞进分享包**
- 免费 Build 有额度与风控；批量 mint 请控速（`--sleep`）
- 仓库默认已 ignore：`.env`、`config.json`、`accounts_*.txt`、`emails_*.txt`、`cpa_auths/`、`cookies/`、`logs/` 等

---

## 相关

- CLIProxyAPI / CPA：自备；将 `cpa_auths/xai-*.json` 拷到 CPA auth-dir 即可
- 免费 Grok 4.5 只走 Build OIDC + `cli-chat-proxy`，不是网页 SSO