Codex Auth v0.2 发布：API 用量、账号自动切换

2026年3月17日星期二

很高兴向大家宣布，Codex Auth v0.2 测试版本发布！🎉

在这个版本中，为了解决同一个普通账号下可能绑定多个不同团队（Team）工作区的问题，我们对底层架构进行了重构。与此同时，针对之前版本中本地会话文件用量跟踪不可靠的问题，我们加入了全新的 API 模式，同时，增加了实验性的后台自动切换账号的功能。

⚠️ 强烈建议：升级前请先备份
在升级之前，请务必先备份你当前的 ~/.codex/auth.json 文件。如果你之前已经使用 codex-auth 添加了多个账号，请一并备份你的 ~/.codex/accounts 整个目录，以防万一。

✅ 立即升级体验

v0.2 尚处于测试阶段，只推荐您更新后启用 api 用量查询，对于后台切换账号功能建议等后续持续迭代更新。

安装测试版本

npm install -g @loongphy/codex-auth@next

启用 API 查询用量

codex-auth config api enable

📖 关于 Codex Auth

如果你还不了解这个项目，Codex Auth 是一个专为管理和无缝切换多个 Codex 账号而生的本地命令行工具。它最大的特点在于零侵入性：你无需修改 Codex 的任何配置文件，也不必部署额外的代理服务，只需通过简单的命令行即可实现账号存取与切换。仓库地址：https://github.com/Loongphy/codex-auth

Codex Auth 完美兼容 Codex 的三种主流使用场景：

原生 Codex-CLI 命令行调用（使用官方 codex-cli，切换账号后需要重新退出，或者使用二开版本 codext）。相关介绍见构建比官方更顺手的 Codex，Skills 自动化同步上游。
独立运行的 Codex App
VSCode 插件 内置调用

以下是本次更新的核心亮点解读。

💡 核心特性

1. API 用量查询

原本并未打算在这个完全本地化的工具中引入任何 API 调用，以避免被 OpenAI 监测到造成账号封禁等风险。但最近通过本地文件（rollout-*.jsonl）跟踪用量变得非常不可靠，经常会遇到 rate_limits: null 的情况（详情见 OpenAI Codex Issue #14880）。

为了精确性，参考 Codex-CLI 的额度获取方式，引入了 API 获取实时用量的支持！

Caution

请注意：启用 API 方式获取用量可能违反 OpenAI 的使用条款并导致封号。请谨慎使用，风险自担。

启用方法：此功能当前默认处于禁用状态。你可以通过执行 codex-auth config api enable 手动开启，享受精准的额度监控。
未来规划：该模式计划在 v0.3 版本中作为默认的用量同步方式。

2. 智能后台自动切换 🧪 实验性功能

在日常高频使用场景中，配额耗尽后手动切换账号往往会打断心流。为了解决这个问题，v0.2 引入了全新的后台守护进程机制。

该进程能够在后台持续监控当前的用量状态，当剩余配额低于设定的阈值时，自动为你切换到当前最优的可用账号。

Tip

后台自动切换功能目前仍处于实验性（Experimental）。现阶段我们主要在 Linux（WSL2）环境下进行了充分的稳定性测试；对于 macOS 和 Windows 平台，目前仅实现并保留了兼容性支持。

默认设置为 5 小时内配额剩余 10% 或周配额剩余 5% 时触发切换。

常用命令：

# 启用
codex-auth config auto enable

# 禁用后台切换（默认）
codex-auth config auto disable

# 自定义触发阈值
codex-auth config auto --5h 15 --weekly 10

3. 多订阅用户福音：账号分组

这是一个底层的架构升级。过去我们使用邮箱作为主键存取账号信息，但这无法满足“同一个邮箱下可能绑定多个工作区或不同订阅计划（例如 Team、free/Plus/Pro 同时存在）”的复杂场景。

command list

v0.2 版本，当你运行 list 或 switch 时，程序会自动将同一邮箱下的多个订阅计划折叠分组显示，视觉上更加直观清晰，同时又保留了独立切换的灵活性。

其他新增命令

我们对日常的运维命令也进行了大规模增强，确保在各种极端边缘场景下都能让你的环境稳定可控：

codex-auth status：一键查看后台服务状态、自动切换开启情况和用量 API 模式情况。
codex-auth daemon --watch|--once：在前台运行或测试后台切换逻辑。
codex-auth clean：常规清理命令（不推荐执行），用于移除不再使用的失效授权快照与旧的备份文件。
codex-auth import --purge：灾难恢复专属命令。通过现存的授权快照文件，即可从零开始重新构建注册表，对于更新后无法正常使用的情况，可尝试使用该命令。

command status

📦 面向贡献者：PR 预览部署引入

为了加快社区贡献的审阅与测试，我们在 CI 流程中引入了 pkg.pr.new 支持。

现在每一个 Pull Request 都会自动构建和发布平台相关的预览包，且依旧保留了智能根据 OS/CPU 解析按需依赖包的特性。你甚至可以通过 --version 直观地看出预览构建来源： codex-auth 0.1.5 (preview pr-6 b6bfcf5)

想快速帮忙测试一个 PR？只需类似于这样执行：

npx https://pkg.pr.new/@loongphy/codex-auth@6

想要测试 PR 中某个 commit 构建，类似执行如下：

npx https://pkg.pr.new/@loongphy/codex-auth@e32a1

如果你在使用过程中遇到任何问题，欢迎到 GitHub 仓库与我们交流或提交 Issue！