# CodexUsage

**Repository Path**: vpen/codex-usage

## Basic Information

- **Project Name**: CodexUsage
- **Description**: codex 账号管理，快速切换账号
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodexUsage

CodexUsage 是一个基于 `SwiftUI` 的 `macOS` 桌面应用，用来在本地管理 OpenAI 账号、Token 文件和额度快照，并支持把选中的账号 Token 写回 `~/.codex/auth.json`，方便快速切换当前 Codex 使用的身份。

当前工程是一个 `macOS app`，不是 iOS App。构建和运行目标应选择 `My Mac`，而不是 iPhone Simulator。

## 主要功能

- 本地管理 OpenAI 账号列表，支持新增、编辑、删除账号。
- 读取 `~/.codex/tokens` 下的本地 Token 文件，并自动补充本地账号列表。
- 一键切换当前 Codex 账号，直接覆盖 `~/.codex/auth.json`。
- 支持按账号查看最近 Token、保存时间、过期时间和 Token 摘要。
- 拉取并展示额度快照，包含常见的 `5 小时` 与 `7 天` 窗口。
- 支持 `邮箱密码`、`Google`、`Apple` 三种登录方式。
- 邮箱密码登录支持手动输入 OTP 验证码。
- 第三方登录支持应用内嵌 OAuth 浏览器和本地回调处理。
- 支持批量执行 `refresh_token` 刷新。
- 支持导入本地 Token 文件，以及打包导出全部 Token。

## 当前运行模式

mac 客户端当前只保留一种模式：

- `本地原生模式`
  直接读取本地 Token、额度缓存和 Codex 配置文件，不依赖 Python 服务启动。

虽然代码里保留了服务抽象层，但当前 UI 和配置只启用 `native_local`。

## 默认目录

应用默认会使用下面这些路径：

- Codex 目录：`~/.codex`
- 当前 Codex 登录文件：`~/.codex/auth.json`
- 本地 Token 目录：`~/.codex/tokens`
- 本地应用数据目录：`~/.codex/macos-app-data`
- 本地账号文件：`~/.codex/macos-app-data/accounts.json`
- 本地 OAuth 回调存储：`~/.codex/macos-app-data/oauth-callbacks.json`
- 本地登录日志：`~/.codex/macos-app-data/local-auth.log`

这些路径都可以在应用的“设置”页里调整。

## 登录与账号来源

当前支持的账号类型包括：

- `email_password`
  需要 OpenAI 邮箱、OpenAI 密码，必要时配合 Gmail App Password 和 OTP 验证码。
- `google`
  通过应用内嵌浏览器完成 Google OAuth 登录。
- `apple`
  通过应用内嵌浏览器完成 Apple OAuth 登录。
- `local_token`
  从本地 Token 文件自动识别并生成的只读账号来源，适合直接切换使用。

第三方登录时，应用会启动本地回调服务并监听：

- `http://127.0.0.1:1455/auth/callback`

用于接收 OpenAI 登录完成后的回调参数。

## 典型使用流程

1. 打开应用后先进入“设置”，确认 `Codex 目录`、`本地 tokens 目录`、`本地数据目录` 是否正确。
2. 如果你已经有现成 Token，可以在“本地”页点击“手动新增Token”导入。
3. 如果需要新建账号，可以在“总览”页新增账号，并选择邮箱密码、Google 或 Apple 登录方式。
4. 对邮箱密码账号执行登录时，如果需要验证码，会弹出 OTP 窗口继续流程。
5. 对 Google / Apple 账号执行登录时，会打开内嵌 OAuth 浏览器窗口完成授权。
6. 登录成功或 Token 导入成功后，可以在账号列表或本地 Token 列表中执行“切换”，将当前身份写入 `~/.codex/auth.json`。
7. 需要查看额度时，可在总览页或账号详情页刷新额度快照。

## 开发环境

- macOS `15.6` 或更高版本
- Xcode `26+` 推荐
- Swift `5`

如果你是第一次在自己的机器上打开工程，可能需要先在 Xcode 里调整：

- `Signing & Capabilities` 中的开发团队
- 本地运行所需的自动签名配置

## 构建与运行

### 使用 Xcode

1. 打开 `CodexUsage.xcodeproj`
2. 选择 Scheme：`CodexUsage`
3. 选择运行目标：`My Mac`
4. 执行 Build / Run

### 使用命令行构建

```bash
xcodebuild -project CodexUsage.xcodeproj -scheme CodexUsage -configuration Debug -destination 'platform=macOS' build
```

### 运行测试

```bash
xcodebuild -project CodexUsage.xcodeproj -scheme CodexUsage -destination 'platform=macOS' test
```

说明：

- 当前测试目标已经创建，但测试内容仍以模板为主，需要后续补充实际断言。
- 如果直接克隆到新机器，命令行构建前也可能需要先解决本地签名团队设置。

## 项目结构

```text
CodexUsage/
├── App/          # 应用入口、全局状态、导航与窗口调度
├── Models/       # 账号、Token、额度、配置等数据模型
├── Services/     # 本地文件、OAuth 回调、账号操作、额度拉取等服务层
├── Views/        # SwiftUI 页面与弹窗
├── Assets.xcassets/
└── ...

scripts/
└── generate_token_app_icon.swift   # 生成 App Icon 的辅助脚本

CodexUsageTests/
CodexUsageUITests/
```

## 关键模块说明

- `CodexUsage/App/AppModel.swift`
  应用核心状态容器，负责刷新数据、切换账号、触发登录流程、打开窗口和同步 UI。
- `CodexUsage/Services/BackendClient.swift`
  定义服务协议与本地原生模式实现，负责账号 CRUD、Token 下载、额度拉取、刷新 Token 等逻辑。
- `CodexUsage/Services/FileSaveService.swift`
  负责本地文件读写，包括账号文件、Token 文件、额度缓存和日志文件。
- `CodexUsage/Services/LocalOAuthCallbackServer.swift`
  本地 OAuth 回调服务，监听 `127.0.0.1:1455` 并落盘回调结果。
- `CodexUsage/Services/NativeLocalAuthManager.swift`
  管理邮箱密码登录、OTP、第三方 OAuth 等本地认证流程。

## 已知限制

- 当前只支持 `macOS`，不能直接在 iPhone Simulator 中运行。
- 当前只启用 `本地原生模式`，没有在 UI 中开放 Python 服务模式。
- 本地原生模式下暂不支持批量登录，但支持批量 `refresh_token` 刷新。
- 测试目标已创建，但自动化覆盖率还比较有限。

## 维护建议

- 修改本地文件结构时，优先同步更新 `BackendConfiguration` 和 `FileSaveService`。
- 修改登录流程时，重点关注 `NativeLocalAuthManager`、`LocalOAuthCallbackServer` 和各个弹窗状态同步。
- 如果调整 Token 文件格式，记得同时检查账号自动补全、额度刷新和切换 Codex 账号这三条链路。

## 效果图
![输入图片说明](image.png)