npm package: @nxxt/codex-auth
Description: Save, switch, import, export, and inspect Codex auth.json accounts from the CLI.
Latest version: 0.1.3

# @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`
- 导入和导出完整账号库配置

## 安装与开发

```bash
bun install
```

本地开发运行：

```bash
bun run index.ts
```

运行测试：

```bash
bun test
```

构建 npm 发布产物：

```bash
bun run build
```

## 直接使用

默认进入交互菜单：

```bash
npx @nxxt/codex-auth
```

也支持子命令：

```bash
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
```

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

```bash
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`

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

执行顺序：

1. 刷新全部账号实例用量
2. 过滤不可用实例
3. 按 `1week` 剩余额度优先、其次 `5h` 剩余额度排序
4. 自动写回最佳实例到 `~/.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` 表示该账号实例最近一次被保存或刷新缓存的时间

```json
{
  "version": 2,
  "accounts": {
    "acct_1234567890ab": {
      "id": "acct_1234567890ab",
      "accountId": "account-id",
      "scopeId": "org_xxx",
      "scopeName": "Personal",
      "label": "主账号",
      "email": "user@example.com",
      "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` 都是立即覆盖行为，不做自动备份
- 工具会尽量把写出的配置文件权限收紧到私有权限