grok-free-register-oss/README.md

grok-free-register

grok-free-register 是一个命令行注册工具。程序会启动本机浏览器，完成页面操作、邮箱验证码处理和结果保存。

运行结果写入 keys/ 目录。

快速开始

git clone <your-fork-or-mirror>/grok-free-register.git
cd grok-free-register
bash start.sh

首次运行会自动创建 .venv、安装依赖，并引导生成 .env。

需要完整说明时，按用途查看：

• 注册教程
• 本地认证服务
• 凭据库存与取用
• 运行状态与排障

常用命令：

bash start.sh               # 按当前 .env 前台运行
bash start.sh --target 100  # 成功 100 个后停止
bash start.sh --max-mem 6G  # 自动估算并发时最多使用 6G 内存
bash start.sh --reconfig    # 重新选择邮箱模式

start.sh 直接在当前终端显示状态。按 Ctrl-C 停止，再次执行同一命令即可重启；不需要额外的会话管理或守护进程依赖。

代理与 CF 清障是两套配置，不要混：

# 本进程出口（Playwright + httpx 显式挂载；Playwright 不会自己读 env）
REGISTER_PROXY=http://127.0.0.1:40080
# 或兜底：
# HTTP_PROXY=http://127.0.0.1:7890
# HTTPS_PROXY=http://127.0.0.1:7890

# 清障预热：调用外部 FlareSolverr（本仓不跑 FS）
CLEARANCE_ENABLED=1
FLARESOLVERR_URL=http://127.0.0.1:8191
CLEARANCE_URLS=https://accounts.x.ai,https://x.ai,https://status.x.ai,https://console.x.ai,https://auth.x.ai
# FS 容器内出口（容器可达名）；走 WARP 时用 docker 网内 privoxy
# CLEARANCE_PROXY=http://privoxy:8118

邮箱模式

tempmail 是默认模式，不需要额外配置，适合快速试跑：

EMAIL_MODE=tempmail

custom 是自建域名邮箱模式，适合长时间运行。需要一个已接入 Cloudflare Email Routing 的域名，并在运行机器上启动本项目的收信服务。

配置步骤：

1. 在 Cloudflare 为域名开启 Email Routing。
2. 部署 cloudflare/email-worker.js。
3. 在 Email Routing 中配置 catch-all，动作选择发送到该 Worker。
4. 在运行机器上启动收信服务：

bash start.sh --email-service

5. 在 .env 中配置：

EMAIL_MODE=custom
EMAIL_DOMAIN=example.com
EMAIL_API=http://127.0.0.1:8080

如果 Worker 需要回调本机服务，WEBHOOK_URL 应使用可访问的域名地址。

配置

完整模板见 .env.example。日常使用通常只需要配置邮箱模式、代理、目标数量和内存预算。

配置	默认值	说明
EMAIL_MODE	tempmail	邮箱模式，支持 tempmail 和 custom
EMAIL_DOMAIN	空	custom 模式使用的域名
EMAIL_API	http://127.0.0.1:8080	本地收信服务地址
TARGET	0	成功数量目标，0 表示不限
PHYSICAL_CAP	0	浏览器并发上限，0 表示启动时自动估算
PHYSICAL_PER_CPU	2	自动估算时每个 CPU 核心对应的并发参考值
PHYSICAL_MEM_MB	512	自动估算时每个浏览器任务的内存预算
MIN_FREE_MEM_MB	500	自动估算时保留的内存
T_SLOT_CAP	8	token 缓冲容量
Q_SLOT_CAP	8	验证码缓冲容量
Q_PENDING_CAP	12	等待验证码返回的请求上限
SOLVER_MOUSE_CLICK_RETRIES	3	token 验证框中心点击次数，0 表示关闭
PAGE_BLOCK_STATIC_ASSETS	0	可选：阻断部分静态资源，降低页面准备成本
C_HOT_PAGE_POOL	0	可选：复用消费阶段页面，减少页面重建开销

不确定怎么设置时，先保持默认值。性能压测时优先观察 PHYSICAL_CAP 和内存，不建议先改 Worker 数量。

运行日志

直接运行 bash start.sh 时，终端只输出任务开始、成功或失败、本次运行平均速度、累计数量和限流等待：

[→] 开始注册 #38
[✓] 注册成功 #38 | 运行平均 47/分 | 累计 38
[⏸] 触发限流 | 60秒后恢复探测
[▶] 限流解除 | 实际等待 61秒

需要调试并发、库存和阶段耗时时，使用：

bash start.sh --debug

它会在上述任务事件之外，每 8 秒输出一次完整的 T/Q、物理并发和阶段耗时面板。已有自动化环境也可继续使用 REGISTER_LOG_MODE=debug。

常用字段：

字段	含义
T	当前可用 token 数量
Q	当前可用验证码数量
phys	空闲浏览器并发许可
s_phys / p_phys / c_phys	S/P/C 获取浏览器许可的平均等待秒数 / 平均持有秒数
p_stage	P 阶段平均耗时：建邮箱 / 准备页面 / 发送请求
c_stage	C 阶段平均耗时：拿页面 / 验证码校验 / 注册提交
c_hot	C 热页池命中 / 未命中次数
t_solve_avg	平均 token 获取时间
q_sent / q_ret	已发送 / 已收到的验证码数量
pair	已配对消费次数
ok / fail	成功 / 失败数量
rate	当前累计成功速率

简单判断：

• T 长期为 0 且 Q 有库存，通常是 token 获取较慢。
• Q 长期为 0 且 T 有库存，通常是邮箱或验证码链路较慢。
• phys 长期为 0，说明浏览器并发已经用满。
• t_solve_avg 明显升高，通常表示浏览器压力、网络质量或 token 服务响应变慢。

可以用日志分析工具解析已有日志：

python3 - <<'PY'
from pathlib import Path
from tools.runtime_log_analyzer import analyze_text
print(analyze_text(Path("run.log").read_text()))
PY

输出文件

成功结果写入：

keys/accounts.txt
keys/grok.txt

accounts.txt 每行格式：

email:password:sso_token

keys/ 目录包含运行结果，默认不会提交到 Git。

认证成功后的 OAuth 出货默认在：

~/Downloads/grok-free-register-auth/authenticated/

可用 keys/async_auth.sh 把出货整备成 keys/cpa_ready/ 并同步探活通过的 access_token 到 keys/acc.md。

清零流水线（删库跑路）

只删 keys/acc.md / accounts.txt 不够：acpa_watchdog 会从 ~/Downloads/grok-free-register-auth/authenticated/ 把旧号再整备进 keys/cpa_ready/，sync_acc 再写回 acc.md。状态文件 _state.tsv 也会残留幽灵 alive。

全量清零用项目根的 reset_pipeline.sh（默认 dry-run，必须加 --yes 才真删）：

# 建议先停 register / auth-service / async_auth
bash reset_pipeline.sh              # dry-run，只列将删内容
bash reset_pipeline.sh --yes        # 真删：注册源 + 认证出货 + cpa_ready + state
bash reset_pipeline.sh --yes --keep-register
                                    # 只清认证/CPA，保留 keys 里新注册的 SSO 源
bash reset_pipeline.sh --yes --keep-cpa
                                    # 只清认证账本/源快照，保留 cpa_ready（少用）
bash reset_pipeline.sh --yes --wipe-salt
                                    # 连 enrollment ledger salt 一并清（极少需要）

会清掉的大致范围：

范围	路径
注册源	keys/accounts.txt、keys/grok.txt、keys/auth-sessions.jsonl、keys/acc.md
CPA	keys/cpa_ready/xai-*.json、_state.tsv、_discarded/
认证出货	$XAI_AUTH_SERVICE_LOCAL_DIR（默认 ~/Downloads/grok-free-register-auth）下的 authenticated/、claimed/、enrollment-ledger.db*、source-snapshot.jsonl

认证目录可用环境变量覆盖：

export XAI_AUTH_SERVICE_LOCAL_DIR=~/Downloads/grok-free-register-auth
# 或
export XAI_ENROLLER_LOCAL_AUTH_DIR=~/Downloads/grok-free-register-auth

只清历史归档、不动现网号池用 scripts/clean_history.sh：

bash scripts/clean_history.sh              # dry-run
bash scripts/clean_history.sh --yes        # 清 zip / _discarded / logs / 杂包
bash scripts/clean_history.sh --yes --deep # 再清 source-snapshot 等更深一层

清完后重开：

bash start.sh                  # 或远端注册机继续跑
bash auth-service.sh           # device-flow → authenticated/
bash keys/async_auth.sh        # acpa_watchdog + sync_acc

项目结构

grok_register/              注册核心与 custom 邮箱服务
xai_enroller/               OAuth 认证服务
keys/                       acpa_watchdog / sync_acc / async_auth（运行时产物 gitignore）
cloudflare/email-worker.js  Cloudflare Email Routing Worker 示例
start.sh                    首次配置和运行
auth-service.sh             认证服务入口
reset_pipeline.sh           全量清零注册→认证→CPA 运行时数据
scripts/clean_history.sh    只清历史归档，不动现网号池
scripts/push_keys_to_auth.sh  本机 SSO 源推远端 auth（需显式 AUTH_SSH_*）
setup.sh                    安装依赖
.env.example                配置模板
tools/                      日志分析 + GrokSession→CPA/sub2api 前端转换
tests/                      自动化测试
docs/architecture.md        并发架构说明

测试

测试依赖与运行依赖分开安装：

.venv/bin/pip install -r tests/requirements.txt

快速检查：

python3 -m unittest tests.test_admission_gate tests.test_register_runtime_unittest tests.test_inventory_unittest tests.test_runtime_log_analyzer -v

完整测试：

python3 -m pytest tests -q

xAI OAuth Enroller

xai_enroller/ 用于把已有 xAI 账号的 SSO 会话转换为 OAuth 凭据，并导入 CPA 凭据库。它独立于注册流程运行：注册机不需要启动，已有账号也不需要重新注册。

默认同机模式

注册和认证在同一个项目目录运行时，无需配置来源：

bash auth-service.sh

认证服务默认读取本项目的 keys/auth-sessions.jsonl 和历史 keys/accounts.txt，每 30 秒生成一次经过校验的原子快照。注册仍可同时运行；认证服务 只读取完整记录，不会读取正在追加的半行。

分离设备的 SSH 模式

注册机和认证服务分开运行时，服务器继续写入注册结果，本地认证服务 每 30 秒通过一次性 SSH 导出全量 JSONL 快照。快照经逐行校验、fsync 后原子替换到 ~/Downloads/grok-free-register-auth/source-snapshot.jsonl；同步失败会继续使用上一份有效快照。 认证使用本机 CloakBrowser Chromium， 成功结果写入 ~/Downloads/grok-free-register-auth/authenticated/，运行状态、同步快照与 认证文件分开保存；认证文件格式可以直接供 CPA 使用。

先把导出器同步到注册机的 scripts/ 目录：

scp scripts/export_registered_sessions.py user@your-server:/opt/grok-free-register/scripts/

然后在本地配置 SSH 连接：

下面这些变量既可在终端 export，也可写入由 .env.example 复制出的 .env； auth-service.sh 会自动读取该文件。

export XAI_AUTH_SERVICE_SSH_HOST=user@your-server
export XAI_AUTH_SERVICE_SSH_IDENTITY=/path/to/ssh-key.pem  # 使用 ssh-agent 时可省略
export XAI_AUTH_SERVICE_REMOTE_ROOT=/opt/grok-free-register
export XAI_AUTH_SERVICE_SYNC_SEC=30

存在 XAI_AUTH_SERVICE_SSH_HOST 时会自动选择 SSH。也可显式设置 XAI_AUTH_SERVICE_SOURCE=local|ssh；默认值 auto 优先兼容已有 SSH 配置，否则使用同机来源。

启动认证服务：

bash auth-service.sh

需要查看队列、重试、节拍和冷却探针时使用：

bash auth-service.sh --debug

默认每次认证至少间隔 10 秒；实测该值比无间隔运行有更高的长期平均成功速率。限流后 每 60 秒只进行一次恢复探测。需要覆盖时使用：

export XAI_AUTH_SERVICE_MIN_INTERVAL_SEC=10
export XAI_AUTH_SERVICE_RETRY_SEC=60

终端只在账号开始、认证结果、限流状态或控制状态变化时输出，并在底部保持 认证> 输入行。s 查看状态，p 暂停， r 恢复，c 取消当前账号，q 退出；Ctrl-C 同样会退出。在输入行键入 take 100 会把最新的 100 个可用凭证登记为已取用，并移动到独立批次目录。认证记录仍保留为 imported，不会因为凭证被取出而重新认证。

可用凭证保存在：

~/Downloads/grok-free-register-auth/authenticated/

已取用批次保存在：

~/Downloads/grok-free-register-auth/claimed/<batch-id>/

库存状态保存在 enrollment-ledger.db 的 credential_inventory 表中，状态为 available、claiming 或 claimed。每条记录预留 note 字段，默认留空。

auth-service.sh 首次运行会自动安装项目依赖。正式用户流程只需要这个 Bash 入口；底层 Python 模块保留给开发和测试，不作为另一套使用方式。

开发文档

docs/architecture.md 记录并发模型、资源生命周期和必须保持的不变量。

License

MIT