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）：

# 一键：缺啥装啥 + 无 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

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：

mise install
mise run deps

---

快速开始（Gmail）

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：

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

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

或用助手脚本：

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）：

{
  "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. 自测

# 模拟入库 + 取码
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

日志里成功时会看到：

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

未命中 Worker 时：

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

配置

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

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（推荐）

{
  "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

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

cp mail_credentials.example.txt mail_credentials.txt

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

邮箱----密码----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。

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

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

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

等价手动调用：

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/号。

日志示例：

[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 导出

---

命令

前置：

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

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

# 再注册 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 时通常无需弹浏览器：

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 导出

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

D. 手动导入 CPA 热加载

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

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

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 / 选中 Chrome：装 Chromium 或设 browser_path；② 扩展已加载仍为 0：代码侧已用 cf_sleep（不受 --fast 0.15x 过度压缩）+ 多轮 shadow 点击；可再 --no-fast 或加大 turnstile_max_rounds/profile_timeout；③ 看日志 Turnstile 初始态 iframe= 是否为 0（widget 未挂载 / IP 被拦）
浏览器 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