Note
这是什么？ 一个小工具，帮你在 Codex 桌面端登录时跳过海外手机号验证， 并让界面正常显示你的头像、姓名、档位和额度条。
Important
它不修改 Codex 程序，不注入、不破解、不上传任何数据。 只是把你自己账号在浏览器里已经拿到的登录凭据，放到桌面端读取的位置。 用你自己账号的合法凭据 —— 详见 原理。
Codex 桌面端点「Sign in with ChatGPT」后会跳到 auth.openai.com/add-phone，
强制要求海外手机号，而且没有跳过按钮。
但诡异的是：同一个账号，浏览器网页版 chatgpt.com 登录完全不要手机号。
于是你的 Codex 桌面端陷入这种状态：
| 你看到的 | 你想要的 |
|---|---|
| 「已通过 API 密钥登录」 | 头像 + 姓名 + 档位 |
| 看不到剩余额度 | 额度条 + 重置日期 |
插件市场报 api key auth is not supported |
插件市场正常可用 |
| 模型列表残缺 | 完整模型列表 |
本工具就是来解决这一段的。
浏览器登录 https://chatgpt.com/，确认能正常聊天。然后按 F12 → 切到 Console → 粘贴回车：
fetch('/api/auth/session').then(r=>r.json()).then(d=>console.log(d.accessToken))控制台会打印一串以 eyJ 开头的长字符串 —— 复制它。
Tip
用 codex-web-login 自带的引导助手可以省掉手敲：
python scripts/get_token.py它会把上面那行 JS 直接放进你的剪贴板，并帮你确认复制到的是正确的 token。
没看到输出？点这里看常见情况
| 现象 | 原因 | 解决 |
|---|---|---|
copy is not defined |
copy() 在 Console 里不可用 |
改用上面的 console.log，别用 copy() |
输出 undefined |
没登录 / 登录态过期 | 先刷新页面确认能正常聊天 |
输出 {...} 一堆对象 |
拿错字段了 | 确认用 d.accessToken（不是 d.session） |
Failed to fetch |
网络/代理问题 | 换个网络或开启代理后重试 |
pip install git+https://github.com/X1F2Y3/codex-web-login其他安装方式 / 装不上怎么办
# 推荐：用 pipx 装成独立命令，不污染任何环境
pipx install git+https://github.com/X1F2Y3/codex-web-login
# Windows 上 pip 命令找不到？用
py -m pip install git+https://github.com/X1F2Y3/codex-web-login
# 不想安装，直接跑（把 <repo> 换成本仓库路径）
python <repo>/scripts/get_token.py注意：pip install codex-web-login（不带 git+）会装到 PyPI 上同名但无关的包，
请务必用上面的完整形式。
装完验证：
codex-web-login --versioncodex-web-login login --from-clipboard它会自动：「校验 token → 关闭 Codex → 备份原配置 → 写入 → 验证 → 重启桌面端」
然后复查：
codex-web-login check看到这个就成功了：
[OK ] auth.json mode=chatgpt email=you@example.com plan=plus
[OK ] codex login status Logged in using ChatGPT
[OK ] scope_v3.user {"authMethod": "chatgpt", ...}
[OK ] 服务端额度 allowed=True used=0% limit_reached=False
--------------------------------------------------------------
判定：PASS 账号信息通道已打通
登录成功后，左下角会显示真实账号与额度条
| 命令 | 用途 |
|---|---|
codex-web-login login --from-clipboard |
最常用 —— 从剪贴板读 token 并登录 |
codex-web-login login --token-file f.txt |
从文件读 token |
codex-web-login login --dry-run |
先看看会发生什么，不改动任何文件 |
codex-web-login check |
只读自检（4 项判据） |
codex-web-login doctor |
环境诊断（排查问题先跑这个） |
codex-web-login backups |
列出所有备份 |
codex-web-login restore <关键词> |
一键回滚 |
codex-web-login login --help |
全部选项 |
同一个命令，只换 token。 工具从 token 里自己读出邮箱、档位、账号 ID， 不会串号，也不依赖旧账号的任何数据。
# 1. 浏览器切到新账号，重新取一次 token
# 2. 跑同一个命令
codex-web-login login --from-clipboard
# 3. 复查
codex-web-login check换回去也简单：
codex-web-login backups找到旧备份，codex-web-login restore <关键词>。
安全吗？会不会动我的系统？
不会。工具只读写一个文件：~/.codex/auth.json（Codex 自己的配置）。
- 每次修改前自动备份，文件名带时间戳
- 写入后自动验证，失败自动回滚
- 不注入进程、不打补丁、不联网上传，无遥测
- 想先确认它会做什么：
codex-web-login login --dry-run
为什么取 token 要手动复制？不能全自动吗？
试过了，三条自动化路线全部走不通（实测）：
| 路线 | 结果 |
|---|---|
读桌面端 cookie 库 → 调 /api/auth/session |
❌ WinError 32 文件被绝对独占，进程运行时读不到 |
codex login --with-access-token |
❌ 报 agent identity JWT payload is not valid JSON |
codex login --device-auth |
❌ 卡在 add-phone 手机号墙 |
关键：/api/auth/session 走的正是那个不要求手机号的 OAuth client。
所以这一行复制既是唯一的手工环节，也正是整个方案能成立的原因。
除了这一步，剩下全部自动化：路径发现、代理探测、进程管理、备份、写入、校验、启动。
显示账号信息了，但发消息还是失败？
这是两件事。 账号信息显示 ≠ 额度可用。
免费档每月有额度上限，用完就发不了 —— 那是服务端额度池，不是配置问题。
跑 codex-web-login check 看最后一行：
[OK ] 服务端额度 allowed=False used=100% limit_reached=True
limit_reached=True 就是额度用完了，等重置或升级档位。
过几天又会要求重新登录？
取决于 refresh_token，不是 access_token 的 exp。 这两件事必须分开看：
| 时长 | 会不会自动续 | |
|---|---|---|
access_token（网页 token） |
10 天（iat + 240h） |
—— 它只是"当前这张票" |
tokens.refresh_token |
不固定，通常长期有效 | —— Codex 靠它自动换新票 |
Codex 的 Rust 侧（auth/manager.rs）里有完整的刷新逻辑：
"Refreshing token" ← 会主动刷新
"last_refresh is in the past" ← 触发条件
"Skipping token refresh because auth changed
after guarded reload." ← 换账号后的保护
not_refreshable_auth ← 不可刷新状态
关键：access_token 到期前，Codex 会自动拿 refresh_token 换一张新的，写入 auth.json，
登录态一直保持。 所以正常情况下你不需要每 10 天重跑一次。
真正会让登录态失效的是这三种：
| 情况 | 为什么 |
|---|---|
| 你在网页端点了「退出登录」 | 触发服务端 revoke，refresh_token 当场作废 |
官方把 refresh_token 轮换掉了 |
若别处先用过一次（换账号、清 Cookie 重登），旧的即失效 |
auth.json 里的 refresh_token 不是本账号的 |
刷新会拿错账号的票，或直接报不可刷新 |
[!IMPORTANT] 本工具的已知短板正在这里。 它从浏览器只能拿到
access_token（/api/auth/session不返回refresh_token），所以refresh_token是从历史备份里借的占位。 这不影响首次登录成功，但如果那个借来的refresh_token不属于当前账号， 10 天后就无法自动续期，需要重跑一次。若你有办法拿到本账号真实的
refresh_token（例如从官方 OAuth 流程产的auth.json里）， 本工具会优先保留它，登录态即可长期保持。
提示「有 BOM」或 `expected value at line 1 column 1`？
这是手动用 PowerShell 改过 auth.json 的典型症状 —— PowerShell 5.1 的
Set-Content -Encoding UTF8 会写入 BOM，Codex 无法解析。
用本工具重跑一次就会修好（它保证写入无 BOM）。
我之前用 API Key 登录过，会冲突吗？
不会。反过来，如果你现在的 auth.json 是 API Key 形态，界面上就只会显示「已通过 API 密钥登录」，
看不到账号信息 —— 这正是需要用本工具修正的场景。
本工具会把它替换成 chatgpt 形态（原文件自动备份）。
一句话：Codex 对 auth.json 里的 tokens 段只做结构校验，不验签。
所以浏览器网页版 session 的 accessToken（标准 JWT）可以直接写进去，
Codex 会走 chatgpt 协议分支，界面于是渲染真实账号信息。
这不是伪造凭据。 用的是你自己账号真实签发的合法 session token， 只是把它放到了桌面端读取的位置。
想看源码级证据（从 app.asar 反编译出来的判定函数）
Codex 判定登录态的唯一函数：
function UN(e){
return e == null ? `response_null`
: e.authMethod !== `chatgpt` && e.authMethod !== `chatgptAuthTokens`
? `auth_method_not_chatgpt`
: e.authToken == null ? `auth_token_missing`
: null
}判空 → 判字符串 → 判非 null。没有签名验证、没有 iss/aud、没有在线校验。
完整分析（含解包方法、界面渲染分支、官方可修复性评估）见 docs/MECHANISM.md。
不会「封」。但要说清楚：
- 官方能修 —— 客户端加
iss/aud白名单约 5 行代码。但根治需要服务端架构改动。 - 短期大概率不修 —— 给网页版加手机号墙等于砍掉大量普通用户注册，是产品决策而非安全决策。
- 届时会怎样 ——
codex-web-login check会先报错，然后你只需停用本工具。
请仅用于你自己的账号。不要用于批量注册、账号交易或规避服务条款的场景。
代码里没有任何硬编码路径。 所有位置都通过平台惯例自动发现，需要时可覆盖：
| 环境变量 | 作用 | 默认 |
|---|---|---|
CODEX_HOME |
Codex 配置目录 | ~/.codex |
CODEX_WEB_LOGIN_PROXY |
代理地址 | 自动探测常见本地端口 |
CODEX_WEB_LOGIN_LAUNCHER |
自定义启动器 | 见下方策略链 |
CODEX_WEB_LOGIN_APP |
桌面端程序路径 | 自动发现 |
每个人启动 Codex 的方式都不同，所以启动做成了可插拔策略链， 按序尝试、第一个成功即停：
CODEX_WEB_LOGIN_LAUNCHER环境变量~/.codex/web-login-launchers.json（自定义列表）- 开始菜单 / 桌面的
.lnk快捷方式（Windows） - 系统 shell 转发（
explorer.exe/open -a） - 直接启动
用你自己的管理器？写个 JSON 就行（把路径换成你自己机器上的启动器）：
{ "launchers": ["D:/tools/codex-manager.exe"] }
D:/tools/codex-manager.exe只是示例；列表里的每个路径都会被Path解析， Windows 下写正斜杠或反斜杠都可以。
如果你觉得官方安装方式太慢、或者总是卡住，强烈建议试试 Codex App Manager —— 一个专门管理 Codex 桌面端的开源工具，下载速度比官方好太多。
| 官方安装 | App Manager | |
|---|---|---|
| 下载速度 | 慢，经常卡住 | 明显更快，国内可达 |
| 安装 / 更新 / 卸载 | 手动处理 MSIX | 一站式检测、安装、更新、卸载 |
| 启动 Codex | 自己找快捷方式 | 一键启动 |
| 代理配置 | 需自行处理 | 内置可配 |
| 增量更新 | 无 | 有（macOS Sparkle 差量 + 校验 + 失败回滚） |
| 主题 / 皮肤 | 无 | 在线库，支持试穿和导入 |
| 多语言 | 跟随系统 | 11 种语言（含阿语 RTL） |
安装方式：
# macOS
brew install --cask wangnov/tap/codex-app-managerWindows / 其他平台 → 下载最新版，
国内镜像：codexapp.agentsmirror.com/manager/latest/
Note
本工具对它是原生友好的 —— 启动策略链会自动识别它的启动器。 但不依赖它：不用 App Manager 也完全能跑，用官方安装同样可以。
| 限制 | 说明 |
|---|---|
| 额度是账号真实上限 | 显示账号信息 ≠ 能用。额度耗尽需等重置或升级 |
access_token 10 天到期 |
有有效 refresh_token 时会自动续期，无需手动干预 |
本工具借来的 refresh_token 可能续不上 |
浏览器只给 access_token；若非本账号的，10 天后需重跑一次 |
| 网页端「退出登录」会作废 | 触发服务端 revoke，refresh_token 失效，需重新取 token |
| 依赖客户端不验签 | 官方若加校验会失效，届时 check 会报错 |
git clone https://github.com/X1F2Y3/codex-web-login
cd codex-web-login
pip install -e ".[dev]"
pytest # 36 个单元测试
ruff check . # lintsrc/codex_web_login/
├── config.py # 路径发现 / 设置（零硬编码）
├── token.py # JWT 解析 / auth.json 原子写入
├── process.py # 进程管理
├── launcher.py # 可插拔启动策略链
├── verify.py # 4 项判据 + 服务端额度查询
└── cli.py # 命令行入口
欢迎 PR —— 见 CONTRIBUTING.md。 特别欢迎非 Windows 平台的实测反馈。
如果它帮到了你：
- ⭐ 点个 Star —— 这比什么都管用，能让更多人找到它
- 🐛 提 Issue —— 遇到问题先跑
codex-web-login doctor，把输出贴上来 - ☕ 请我喝杯咖啡（完全自愿，不付费也能用全部功能）
| 微信赞赏码 | 支付宝 |
|---|---|
 |
 |
完全自愿。不付费也能使用全部功能。
MIT · 仅供学习研究与个人使用
如果这个项目帮到了你，一个 Star 就是最好的回报