Codex Auth 是一款专为 OpenAI Codex 用户开发的第三方命令行（CLI）增强工具，其核心目的在于解决开发者在使用 AI 编程助手时面临的多账号管理繁琐和请求限流问题。OpenAI Codex 作为强大的 Agentic 编程伙伴，其原生系统在多环境鉴权和额度状态显示上存在局限。Codex Auth 填补了这一空白，允许用户在本地设备上集中管理、无缝切换多个身份凭证。
该工具以“结果导向”和“自动化”为核心设计理念，不仅仅是一个单纯的切换开关，更是一个可视化的调度中心。通过直观的终端交互界面（TUI），开发者可以实时掌握每个账号的套餐类型（如 Pro、Team、Pro Lite）、5 小时高频用量以及周级别总用量的消耗占比。在此基础上，工具提供了创新的“自动轮换（Auto-switch）”功能——当活跃账号触及自定义的使用率阈值时，自动在后台将其切换为备用账号，确保 AI 编程心流不被中断。Codex Auth 全平台兼容 Windows、macOS 和 Linux，并可与 Codex CLI、桌面应用及 VS Code 插件完美协同，是企业级团队及重度 AI 开发者不可或缺的效能基建。
功能列表
- 交互式多账号切换：内置终端交互界面（TUI），支持通过上下键、行号或自定义别名在多个 Codex 账号之间快速执行身份凭证的无缝切换。
- 实时用量与套餐监控：支持通过抓取本地安全日志或直接调用底层 API，实时展示账号所处的订阅计划，以及当前账号的 5 小时调用率和周使用率状态。
- 后台自动轮换（Auto-switch）：允许用户自定义调用额度阈值（如设定 5小时使用率达到 80%），系统会在后台自动监测并无缝切换到下一个可用账号，规避官方限流机制引发的中断。
- 灵活的登录鉴权集成：深度集成底层登录逻辑，支持调用标准网页授权（Web Auth）与远程无头服务器设备码授权（Device Auth），录入后自动归档到管理库。
- 批量导入与清理维护：支持单文件和多文件目录的智能批量导入（Import），快速同步团队分享的鉴权文件；并提供冗余、过期文件的交互式清理功能。
- 多客户端及平台兼容：全面兼容 Windows、macOS 和 Linux 架构，生成的认证状态直接服务于 Codex CLI（@openai/codex）、VS Code 插件及 Codex App 客户端。
使用帮助
欢迎使用 Codex Auth！为了确保您能顺畅地在实际开发工作流中发挥本工具的最大价值，请仔细阅读以下详细的操作及配置指南。这套系统采用严格的模块化设计，无论是基础的本地部署，还是进阶的自动资源调度，都可以通过简明的命令行完成。
一、 运行环境准备与安装流程
Codex Auth 运行依赖于 Node.js 运行时环境，并且底层逻辑需要与原生官方 Codex CLI 客户端配合。
第一步：安装前置依赖
确保您的操作系统中已安装 Node.js（推荐 22+ 版本）。接着，强烈建议您先安装官方的 Codex CLI 工具，以便自动生成默认的环境目录和依赖凭证配置。
npm install -g @openai/codex
第二步：安装 Codex Auth
您可以通过 npm 包管理器将工具全局安装至您的操作系统中，这样您可以在任意项目文件夹下直接使用 codex-auth 命令：
npm install -g @loongphy/codex-auth
（免安装执行方案：如果您只偶尔使用查询功能，可以直接使用 npx 进行内存调用：npx @loongphy/codex-auth list）
二、 基础操作：账号的接入与查询
1. 添加与登录账号
在系统内管理多个身份凭证前，您需要将它们录入。只需在终端输入：
# 启动标准图形化登录流程
codex-auth login
系统会自动唤起浏览器，引导您完成 ChatGPT 账号登录。若您在一台没有图形界面的云端虚拟机（如 Ubuntu Server）上操作，请使用设备码登录模式：
codex-auth login --device-auth
此时终端会生成一串验证码，您可以在本地电脑的浏览器中输入该码完成授权，凭证会自动同步至服务器中枢。
2. 查阅全局账号状态（核心仪表盘）
通过 list 命令可以一目了然地看到所有被托管账号的存活状态与负载压力。这是开发过程中最常用的检查手段：
codex-auth list
在美观的数据表格中，您将看到各账号分别对应 ACCOUNT（邮箱账户）、PLAN（如 Team 或 Pro Lite 套餐）、5H USAGE（5小时动态配额消耗百分比）以及 WEEKLY USAGE（周调用总量百分比）。在后面加上 --live 参数可以强制触发实时用量请求：
codex-auth list --live
三、 进阶调度：环境切换与自动化防限流
多账号管理的核心诉求在于应对大范围重构时单个账号算力耗尽的场景。
1. 交互式与定向切换
当您的活跃账号（带 * 标识）出现额度告警时，输入以下命令即可激活 TUI 选择器：
codex-auth switch
界面将通过高亮列表列出当前所有库内账号。使用键盘的上下箭头选定健康账号后回车，凭证立刻完成替换。
如果您熟悉了账号的列表编号或者设定的别名，可以跳过交互界面执行热切换：
codex-auth switch 02
codex-auth switch work-account
【关键注意事项】：完成切换后，VS Code 原生插件和桌面端应用由于运行机制，需重启客户端才能重新读取鉴权文件。如果您希望实现代码编辑时的免重启无缝切换，强烈推荐卸载原生 CLI，改用改良版的核心依赖：
npm uninstall -g @openai/codex
npm install -g @loongphy/codext
2. 开启自动流转（Auto-switch）保护机制
不要让人工切换打断您的编码心流。您可以配置 Codex Auth，让其作为一个后台驻留服务，监控到配额触及红线时自动换用下一个健康账户。
首先，激活自动模式：
codex-auth config auto enable
接着，设定熔断阈值。例如，我们要求：当 5 小时限制耗用达 80% 或者一周限额达到 95% 时，工具自动进行账号轮换：
codex-auth config auto --5h 80 --weekly 95
这一操作尤为适合搭配自动化测试流水线和夜间编译脚本，保证 AI Agent 拥有源源不断的算力支持。
四、 资产维护：账号凭证的导入与更新
1. 企业与团队资产导入
企业 IT 或研发组长通常会统一下发鉴权 JSON 文件。使用以下命令可以无缝并入现有管理池：
# 导入单独的鉴权文件，并指派别名为 team-alpha
codex-auth import /path/to/auth.json --alias team-alpha
# 批量扫描并导入某个目录下的所有合规配置
codex-auth import /path/to/auth_folder/
2. 刷新机制的数据源管理
为了获取刚才提到的 5H USAGE 精确数值，Codex Auth 默认会采用直连 API 的模式进行 HTTPS 轮询（需要消耗一定网络资源）。如果遇到网络受限，或您更倾向于保守地只读取本地请求日志，可以关闭 API 轮询功能：
# 开启（默认推荐，数据最精确）
codex-auth config api enable
# 关闭（改为读取 ~/.codex/sessions 本地日志，会有少许延迟）
codex-auth config api disable
最后，您可以随时使用 codex-auth status 指令来核对所有后台守护任务的配置和存活情况。
应用场景
- 重度全栈开发的额度接力
在利用 OpenAI Codex 执行整库代码重构、全文件静态类型推导等高并发 Agent 任务时，开发者极易耗尽当前账号的 5 小时请求上限。通过配置codex-auth config auto自动轮转机制，开发者可以将 3 至 5 个订阅账号打包为一个算力池，保证代码生成过程无需暂停等待限流恢复。 - 开发团队基础算力资源的共享配置
项目组采购了数个 ChatGPT Team 账号并共享给初级程序员执行代码 Review 等常规操作。管理员将授权文件分发给组员，组员利用codex-auth import进行批量导入，并通过list视图实时观测各账号的负载情况，人工规避拥堵账号，极大提升团队内部的资源利用率。 - 远程无头服务器的自动化脚本护航
在 CI/CD 流水线或云端沙盒（如 NVIDIA 部署在后台运行的 Codex 实例）中，开发者由于无法操作系统图形界面，依靠原生客户端极难处理会话过期的问题。使用codex-auth login --device-auth在云原生环境中完成认证绑定，同时利用命令行实现多版本测试环境之间的快速身份切换，确保持续集成不会因鉴权失效而崩溃。
QA
- 为什么在终端中我的用量状态（Usage limits）刷新滞后甚至不更新？
这通常是因为数据刷新模式被设为只读本地日志（Local-only）。原生 Codex 经常会在新版本的日志反馈中出现rate_limits: null，导致本地文件数据可能比真实发生的时间滞后几个小时。您可以执行codex-auth config api enable切换至 API 实时获取模式来解决此问题。 - 如何确保开启实时 API 获取不会导致封号？
开启 API 获取模式（API mode）意味着该工具会直接提取您的 Access Token，向官方后台端点发送状态查询请求。该动作通过模拟官方接口读取，虽然满足正常使用的逻辑，但如果由于人为修改造成极高频率并发访问，可能触及风控规则。普通强度的查询在合规范围内，工具本身不对不可抗力的风控承担风险，用户需合理使用。 - 切换完成后，为什么 Codex App 或者 VS Code 中依然报错额度不足？
原生 Codex 及其官方扩展的设计是在应用启动时读取一次鉴权文件并驻留内存。因此，在使用codex-auth switch成功变更底层配置后，您必须重启 IDE（VS Code）或桌面端程序使其重载配置文件。如果希望免除重启操作，需卸载原生库并安装定制版@loongphy/codext。 - 支持清理过期或失效的凭证信息吗？
支持。在终端运行codex-auth remove将调出图形化多选菜单，您可以勾选并清理掉已经失效或被封禁的账号配置文件，保持系统环境干净。或者通过codex-auth remove <别名>指向性删除。
