grok-free-register 是一个命令行注册工具。程序会启动本机浏览器,完成页面操作、邮箱验证码处理和结果保存。
运行结果写入 keys/ 目录。
git clone https://github.com/hechuyi/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 停止,再次执行同一命令即可重启;不需要额外的会话管理或守护进程依赖。
需要代理时,在 .env 中加入:
HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890tempmail 是默认模式,不需要额外配置,适合快速试跑:
EMAIL_MODE=tempmailcustom 是自建域名邮箱模式,适合长时间运行。需要一个已接入 Cloudflare Email Routing 的域名,并在运行机器上启动本项目的收信服务。
配置步骤:
- 在 Cloudflare 为域名开启 Email Routing。
- 部署
cloudflare/email-worker.js。 - 在 Email Routing 中配置 catch-all,动作选择发送到该 Worker。
- 在运行机器上启动收信服务:
bash start.sh --email-service- 在
.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 | 运行平均 9.9/分 | 累计 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。
grok_register/ 注册核心与 custom 邮箱服务
xai_enroller/ OAuth 认证服务
cloudflare/email-worker.js Cloudflare Email Routing Worker 示例
start.sh 首次配置和运行
auth-service.sh 认证服务入口
setup.sh 安装依赖
.env.example 配置模板
tools/ 运行日志分析工具
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 -qxai_enroller/ 用于把已有 xAI 账号的 SSO 会话转换为 OAuth 凭据,并导入 CPA
凭据库。它独立于注册流程运行:注册机不需要启动,已有账号也不需要重新注册。
注册和认证在同一个项目目录运行时,无需配置来源:
bash auth-service.sh认证服务默认读取本项目的 keys/auth-sessions.jsonl 和历史
keys/accounts.txt,每 30 秒生成一次经过校验的原子快照。注册仍可同时运行;认证服务
只读取完整记录,不会读取正在追加的半行。
注册机和认证服务分开运行时,服务器继续写入注册结果,本地认证服务
每 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 记录并发模型、资源生命周期和必须保持的不变量。
MIT
xAI 设备授权已转到 accounts.x.ai 网页。请用:
- Path A:
scripts/browser_device_authorize.py - Path B:
scripts/device_flow_browser_complete.py(推荐闭环) - 导出标准凭证:
scripts/export_authenticated_json.py
成功认证 JSON 目录:
auth-local/authenticated/
详见 docs/guides/browser-device-authorize.md 与 docs/guides/authenticated-export.md。
cd E:\download\claude\CodeX\grok-free-register-main
.\start-full-to-grok2api.ps1| 模式 | 作用 |
|---|---|
all(默认) |
注册 + Path B 浏览器 OAuth + 导入 grok2api |
register-only |
仅 tempmail 注册 |
auth-only |
仅 accounts.x.ai 浏览器批准 → auth-local/authenticated |
import-only |
仅把 xai-*.json 导入本地 grok2api |
status / stop |
状态 / 停止本链路进程 |
管理端账号写在 keys/.credentials(ADMIN_USER / ADMIN_PASS)。
详见 PIPELINE.md 与 scripts/import_authenticated_to_grok2api.py。
Recent features are now first-class in this repo:
| Feature | Entry |
|---|---|
| CloakBrowser anti-detect browser | start-windows.ps1 (CLOAKBROWSER_CACHE_DIR=.cloakbrowser) |
| Path B OAuth (�ccounts.x.ai) | start-auth-windows.ps1 |
| One-click import to grok2api | scripts/import_authenticated_to_grok2api.py |
| Full chain register->auth->import | start-full-to-grok2api.ps1 |
| Unified entry | start-all-windows.cmd / start_all_windows.py |
| Custom mailbox long-run | start-email-service-windows.ps1 + CF Worker |
powershell cd E:\download\claude\CodeX\grok-free-register-main .\start-all-windows.cmd status .\start-all-windows.cmd up .\start-full-to-grok2api.ps1 .\start-full-to-grok2api.ps1 import-only
Docs: