@nxxt/codex-auth

v0.1.3

Published

a month ago

Save, switch, import, export, and inspect Codex auth.json accounts from the CLI.

0High
0Medium
0Low

nxxt

@nxxt/codex-auth

@nxxt/codex-auth 是一个面向 Codex CLI 登录态的 npm CLI 工具，用来管理当前机器的 ~/.codex/auth.json，并维护一个本地账号实例库。

当前版本是一次破坏性升级：

账号库存储已切换为 StoreV2
不再兼容旧版 StoreV1
不再以 accountId 作为主标识，而是以账号实例 id 作为主标识
同一 accountId 的不同 team/组织现在会被隔离保存

它支持：

保存当前 auth.json 到本地账号池
查询账号最近一次缓存的 5h / 1week 用量
手动刷新指定账号或全部账号的用量
自动切换到当前“最佳可用账号”
直接把某个账号实例写回当前电脑的 ~/.codex/auth.json
从本地文件或 URL 导入完整 StoreV2
导入和导出完整账号库配置

安装与开发

bun install

本地开发运行：

bun run index.ts

运行测试：

bun test

构建 npm 发布产物：

bun run build

直接使用

默认进入交互菜单：

npx @nxxt/codex-auth

也支持子命令：

npx @nxxt/codex-auth save --label "主账号"
npx @nxxt/codex-auth save --refresh
npx @nxxt/codex-auth list
npx @nxxt/codex-auth show <id>
npx @nxxt/codex-auth refresh
npx @nxxt/codex-auth refresh <id>
npx @nxxt/codex-auth use <id>
npx @nxxt/codex-auth remove <id>
npx @nxxt/codex-auth use-best
npx @nxxt/codex-auth proxy
npx @nxxt/codex-auth proxy show
npx @nxxt/codex-auth proxy set --port 7897
npx @nxxt/codex-auth proxy auto
npx @nxxt/codex-auth proxy off
npx @nxxt/codex-auth export ./accounts.json
npx @nxxt/codex-auth import ./accounts.json
npx @nxxt/codex-auth import https://example.com/accounts.json

如果你已经全局安装过，也可以直接运行二进制命令：

codex-auth

命令说明

`save`

读取当前 ~/.codex/auth.json，解析账号实例信息，并按 id 保存到本地账号库。

实例 id 基于 accountId + scopeId 稳定生成，其中 scopeId 提取顺序为：

organizations 中 is_default=true 的组织 ID
organizations[0].id
groups[0].id
回退到 plan:<planType>

可选参数：

--label <label>: 自定义账号标签
--refresh: 保存时顺带刷新一次最新用量

`list`

查看当前账号库里的所有账号实例，并标记当前机器正在使用的实例。

列表会显示：

标签
scope 名称
plan
实例 id
首次加入时间，例如 加入=3天前（03-10 14:20）
5h / 1week 剩余额度
语义化重置时间，例如 2小时后（今天 18:30）

`show <id>`

查看单个账号实例详情，包括：

id
accountId
scopeName / scopeId
邮箱
plan
最近缓存的 5h / 1week 用量
首次加入时间、最近更新时间、最近刷新时间
错误信息

`refresh [id]`

手动刷新一个或全部账号实例的用量信息。

传入 id 时直接刷新该实例
不传参数时会弹出选择器，支持“全部账号”或“单个账号”

刷新时会尝试以下候选地址：

<chatgpt_base_url>/backend-api/wham/usage
<chatgpt_base_url>/wham/usage
<chatgpt_base_url>/api/codex/usage

如果 ~/.codex/config.toml 中配置了 chatgpt_base_url，会优先使用该地址；否则默认使用 https://chatgpt.com。

当刷新遇到 401 / unauthorized / invalid token / expired / deactivated_workspace，或者接口返回成功但没有 plan_type 时，工具会自动使用当前账号的 refresh_token 调用 /oauth/token 刷新令牌后再重试一次。

如果全部候选地址都失败，CLI 会直接打印失败原因，例如超时、网络错误或上游返回码。

`use <id>`

把本地账号库中选中的账号实例完整写回当前机器的 ~/.codex/auth.json。

注意：

该命令会直接覆盖本机 auth.json
当前版本不会自动备份，也不会二次确认

交互菜单中的“使用某个账号”会直接展示缓存的 1week / 5h 剩余额度，并按剩余额度从高到低排序，不会触发刷新。

`remove <id>`

从本地账号库删除一个账号实例。

可选参数：

--force: 跳过二次确认，直接删除

说明：

删除的是账号库里的实例，不会改动当前机器已经生效的 ~/.codex/auth.json
如果删除的是当前正在使用的实例，CLI 会额外提示本机登录态未改动

`use-best`

自动切换到当前最佳可用账号实例。

执行顺序：

刷新全部账号实例用量
过滤不可用实例
按 1week 剩余额度优先、其次 5h 剩余额度排序
自动写回最佳实例到 ~/.codex/auth.json

严格可用判定：

刷新成功
没有 usageError
同时存在 oneWeek 和 fiveHour
两个窗口剩余额度都大于 0

如果当前实例已经是最佳账号，只会提示，不会重复切换。

`proxy`

查看当前 CLI 实际会使用的代理来源与地址。

默认优先级：手动配置 > 环境变量 > 当前系统代理
环境变量支持：CODEX_AUTH_PROXY、HTTPS_PROXY、HTTP_PROXY、ALL_PROXY
macOS 下如果没有环境变量，工具会自动读取当前系统代理端口，例如 127.0.0.1:7897

常见子命令：

proxy show: 显示当前代理模式、来源和生效地址
proxy set <url>: 手动固定代理地址，例如 http://127.0.0.1:7897
proxy set --port 7899: 基于当前代理主机，只修改端口
proxy set --port 7899 --host 127.0.0.1: 同时指定主机和端口
proxy auto: 清除手动配置，恢复自动读取环境变量/系统代理
proxy off: 对当前 CLI 显式关闭代理

当前版本仅支持 http/https 代理地址。

`export <file>`

导出完整账号库，格式为 StoreV2。

`import <source>`

导入完整账号库，支持：

本地文件路径
http:// / https:// URL

注意：

只接受本工具导出的 StoreV2
不支持旧版 StoreV1
不支持 raw auth.json 的 URL 导入

配置与存储

当前登录态：

~/.codex/auth.json

账号库存储：

~/.codex/accounts/accounts.json

CLI 代理设置：

~/.codex/accounts/settings.json

内部格式固定为 StoreV2：

savedAt 表示该账号实例第一次加入账号库的时间
updatedAt 表示该账号实例最近一次被保存或刷新缓存的时间

{
  "version": 2,
  "accounts": {
    "acct_1234567890ab": {
      "id": "acct_1234567890ab",
      "accountId": "account-id",
      "scopeId": "org_xxx",
      "scopeName": "Personal",
      "label": "主账号",
      "email": "[email protected]",
      "planType": "team",
      "authJson": {},
      "usage": {
        "fetchedAt": 1700000000,
        "planType": "team",
        "fiveHour": {
          "usedPercent": 12.5,
          "windowSeconds": 18000,
          "resetAt": 1700010000
        },
        "oneWeek": {
          "usedPercent": 42.1,
          "windowSeconds": 604800,
          "resetAt": 1700600000
        },
        "credits": null
      },
      "usageError": null,
      "savedAt": 1700000000,
      "updatedAt": 1700000100
    }
  }
}

安全说明

导出文件默认包含完整 authJson 与最近一次用量缓存，请妥善保管
use 和 use-best 都是立即覆盖行为，不做自动备份
工具会尽量把写出的配置文件权限收紧到私有权限

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@nxxt/codex-auth

安装与开发

直接使用

命令说明

save

list

show <id>

refresh [id]

use <id>

remove <id>

use-best

proxy

export <file>

import <source>

配置与存储

安全说明

`save`

`list`

`show <id>`

`refresh [id]`

`use <id>`

`remove <id>`

`use-best`

`proxy`

`export <file>`

`import <source>`