Overview
Codex Tools 面向同时使用多个 Codex 账号的场景，提供桌面 GUI、命令行入口和本地 /v1 反代能力。你可以用它导入账号、查看用量、切换本机 Codex 登录态，也可以把账号池暴露成 OpenAI 兼容接口供 Cursor、ChatWise、CC Switch、本地脚本等工具调用。
Contents
Highlights
- 多账号管理：OAuth 登录导入、JSON 批量导入、账号备份回导入。
- 用量查看：展示
5h、1week 用量窗口、重置时间和账号计划类型；经典界面另显示按会话创建账号归属的本地 Token 用量、基于日志耗时估算的输出速度与 Credits 余额。
- 账号预热：可手动发送固定
hello 最小请求激活 5h 窗口，也可为选中账号配置每日自动预热时段（支持跨午夜）；会真实消耗少量额度。自动预热默认关闭并带持久化冷却；手动预热可绕过冷却，仍检查窗口是否已激活、周额度及授权状态。
- 账号优先级：支持调整账号组顺序，API 反代可按优先级使用账号，额度恢复后重新优先选择；也保留平均和逐个策略。
- 重置卡：在账号详情中选择可用卡片并确认使用，提交前重新读取卡片状态，重试同一张卡复用持久化请求 ID。
- 快速切换：切换
~/.codex/auth.json 和 config.toml，可联动启动新版 ChatGPT App，并兼容旧 Codex App 与 codex app 回退。
- CLI/TUI：通过
ctc 执行 list/switch/login/import/export/delete/usage/provider/doctor/report/tui。
- API 反代：本地提供 OpenAI 兼容
/v1 接口，支持运行中账号轮换。
- App/CLI 绑定：可一键把 Codex App/CLI 切到本机反代地址，也可一键恢复原配置。
- 公网访问：集成 cloudflared，支持快速隧道和命名隧道。
- 桌面能力：状态栏驻留、自动更新、多语言界面、编辑器联动；macOS 可独立启用文字额度栏与五种紧凑额度图标，Windows 可将额度显示在任务栏左侧、任务栏右侧或系统托盘。
Preview
桌面界面统一使用原版布局；精简布局及布局切换入口已移除，旧布局偏好不再影响启动。
Installation
CLI/TUI
推荐通过 npm 安装命令行入口：
npm i -g @170-carry/ctc
安装后使用：
ctc list --json
ctc switch --best --launch
ctc provider status --json
ctc tui
ctc ui
不想全局安装时，可以直接运行：
npx @170-carry/ctc list --json
ctc ui 会打开本机已安装的 Codex Tools 桌面应用；npm 包负责安装命令行入口和原生 CLI，不负责安装 .app 或 .exe 桌面包。
Desktop App
桌面应用从 GitHub Releases 下载：
安装桌面应用后，可以直接在 GUI 内完成账号导入、用量刷新、切换、API 反代和 cloudflared 配置。
Quick Start
Terminal
ctc login --label work
ctc list --refresh --json
ctc switch --best --launch
ctc provider sync
ctc doctor --json
常见流程：
- 用
ctc login 调用官方 codex login 并导入账号。
- 用
ctc list --refresh 查看账号和用量。
- 用
ctc switch 1 或 ctc switch --best 切换账号。
- 用
ctc provider sync 修复 Codex 历史 provider 元数据。
- 用
ctc doctor 检查本机环境和账号库状态。
Desktop
- 打开 Codex Tools。
- 导入一个或多个 Codex 账号。
- 刷新账号用量。
- 选择账号并切换，或启动本地 API 反代。
- 需要公网访问时，再开启 cloudflared。
macOS 首次运行新版时会显示额度展示引导。文字额度栏和紧凑额度图标可以独立启用、同时启用或同时关闭；之后可在“设置”中实时调整文字栏图标与五种额度图标样式。
Windows 首次运行新版时也会显示额度展示引导。任务栏组件和系统托盘额度图标至少启用一种，默认额度口径为“一周剩余”；之后可在“设置”中分别调整位置、图标样式和显示口径。如果左侧组件与 Windows 天气小组件冲突，可通过设置页或引导页打开 Windows 任务栏设置并关闭天气小组件。
CLI Reference
所有命令默认读取桌面应用相同的数据目录。需要隔离环境时，加 --data-dir <目录>。
| 命令 | 说明 |
|---|
ctc list --json | 列出已保存账号，输出 JSON |
ctc list --refresh --json | 刷新用量后列出账号 |
ctc switch 1 --json | 切换到第 1 个账号 |
ctc switch --best --launch | 按余量选择更合适的账号，并启动 codex app |
ctc login --label work | 调用官方 codex login，登录后自动导入账号 |
ctc import ./auth.json --json | 导入账号 JSON |
ctc import ./accounts-dir --json | 导入目录中的账号 JSON |
ctc import --current --json | 导入当前 ~/.codex/auth.json |
ctc export ./accounts.json --json | 导出账号库 |
ctc export --json | 直接把账号库 JSON 输出到终端 |
ctc delete 1 | 删除第 1 个账号（交互确认，--yes 跳过） |
ctc delete <id> --yes | 按 ctc list --json 中的内部 id 删除账号并跳过确认 |
ctc usage --cached --json | 查看本地缓存用量 |
ctc provider status --json | 查看当前 provider、rollout 和 state_5.sqlite provider 统计 |
ctc provider sync | 把本机 Codex 历史元数据同步到当前 provider |
ctc provider switch openai | 写入 model_provider = "openai" 并同步历史元数据 |
ctc provider restore | 恢复最近一次 provider 同步前备份 |
ctc doctor --json | 检查数据目录、Codex CLI、账号库和本机 auth 文件 |
ctc report --json | 输出完整诊断报告 |
ctc tui | 打开终端账号选择器 |
ctc ui | 打开已安装的 Codex Tools 桌面应用 |
ctc provider sync 会在 ~/.codex/backups_state/provider-sync/ 下生成备份；包含 encrypted_content 的历史会恢复列表可见性，但跨 provider 继续 resume 仍可能受 Codex 加密上下文限制。
API Proxy
Codex Tools 可以启动本地 OpenAI 兼容反代：
- 默认地址：
http://127.0.0.1:8787/v1
- 鉴权方式：应用内生成的
sk-... API Key
- 上游来源：已导入的 Codex 账号
- 账号选择：支持平均、逐个和账号优先级策略，可运行中切换
- 默认模型：
gpt-5.6-sol
- 默认推理：
xhigh + default（标准速度；客户端仍可显式请求 fast）
- GPT-6 Codex 账号代理模型：
gpt-6-astra、gpt-6.1-sol、gpt-6-sol、gpt-6-luna。代理使用 Codex CLI 0.159.0 标识及 Responses Lite 请求格式；模型能否调用仍由上游账号权限决定。
- GPT-5.6 模型：
gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna
CODEX_TOOLS_PROXY_SERVICE_TIER 可设置代理默认速度，支持 auto、default / standard、fast / priority、flex。显式请求值优先于环境变量；fast / priority 转为上游 priority。未设置或环境变量非法时使用 default，显式非法请求仍会被拒绝，Key 的速度权限继续生效。
Claude Code 的 output_config.effort 会在显式 reasoning_effort / reasoning.effort 之后读取，ultra 映射为 max。
更多链路说明见 docs/api-proxy.md。
Local Clients
本地脚本、curl、ChatWise 等本机直连客户端，可以直接使用本地 Base URL：
curl http://127.0.0.1:8787/v1/models \
-H "Authorization: Bearer sk-..."
Cursor
Cursor 可能由服务端代发请求，不建议填写 127.0.0.1、localhost、192.168.x.x、10.x.x.x 等本地或私网地址。
如果 Cursor 报 ssrf_blocked 或 connection to private IP is blocked，请改用：
- 应用内 cloudflared 生成的
Public URL
- 远程 Linux 反代地址
- 自己的公网域名反向代理地址
GPT-6 Astra、GPT-6.1 Sol、GPT-6 Sol、GPT-6 Luna 分别使用 gpt-6-astra、gpt-6.1-sol、gpt-6-sol、gpt-6-luna。Codex 账号代理支持 low、medium、high、xhigh、max 推理强度（ultra 映射为 max），拒绝 none / minimal。默认模型保持 gpt-5.6-sol。
GPT-6.1 Sol 也兼容 gpt6.1-sol、gpt-6-1-sol、gpt-6.1、gpt6.1、gpt-6-1 及带日期的模型名称。已有 Key 若设置了模型白名单，需要显式勾选 gpt-6.1-sol；升级不会扩大 Key 权限。其标准短上下文 API 费用估算使用每百万 Token 输入 $2、缓存输入 $0.10、输出 $10，详见 官方模型说明。
模型名称也可使用 gpt-5.6-sol。gpt-5.6、gpt5.6 和 gpt-5-6 会映射到 Sol，Terra/Luna 也兼容无点号和全连字符别名。
GPT-5.6 可用推理强度为 none、low、medium、high、xhigh、max；代理还保留 minimal 供旧模型兼容。可用速度为 auto、default、fast、flex，其中 fast 会按上游 wire 值 priority 发送。
CC Switch
在 CC Switch 的 Codex 自定义 provider 中填写：
Base URL：http://127.0.0.1:8787/v1API Key：应用内生成的 sk-...wire_api：responses
如果 Codex App/CLI 通过 wrapper、app bind、CC Switch 或自定义 provider 指向这个 Base URL，账号轮换会发生在本地反代层，不需要关闭 Codex App/CLI。
反代面板也提供“切到本机反代”和“恢复正常地址”按钮，会自动备份并恢复 ~/.codex/config.toml 与 ~/.codex/auth.json。
如果官方 Codex App/CLI 接入反代后看不到 GPT-6.1 Sol，可点击“切到本机反代”（已绑定时为“同步模型目录”），然后重启 Codex App/CLI。API Key 接入下，部分客户端使用内置模型目录，并不会读取反代的 /v1/models。绑定时本工具会通过 model_catalog_json 提供独立的 Codex 模型目录，按模型开关和当前 Key 白名单筛选；启动代理或修改这些权限时也会同步。原有 Key 的权限不会自动扩大。切换回普通账号或恢复配置后，Codex 继续使用原来的模型目录。
Anthropic Messages
兼容 Anthropic Messages 的客户端可以请求：
- 地址：
http://127.0.0.1:8787/v1/messages
- Key：
x-api-key: sk-...
- 版本：
anthropic-version: 2023-06-01
这里的 2023-06-01 是 Anthropic API version，不是模型版本日期。
Development
Requirements
- Node.js 20+
- Rust stable
- macOS 或 Windows
Run Locally
npm install
npm run tauri dev
Build CLI
cd src-tauri
cargo build --bin codex-tools-cli
Build Frontend
npm run build
Release
本仓库使用 GitHub Actions 自动发布桌面安装包和 npm CLI 包。
触发发布：
git tag v<version>
git push origin v<version>
仅发布桌面版本（跳过 npm）可在 main 推送完成后运行：
gh workflow run release.yml --ref main -f release_tag=v<version> -f publish_npm=false
该流程会创建对应版本标签，无需另外推送标签。
发布内容：
- macOS Apple Silicon 桌面安装包
- macOS Intel 桌面安装包
- Windows x64 桌面安装包
- npm wrapper：
@170-carry/ctc
- npm native packages：
@170-carry/ctc-darwin-arm64、@170-carry/ctc-darwin-x64、@170-carry/ctc-win32-x64
npm 发布需要在 GitHub repository secrets 中配置 NPM_TOKEN。
Documentation
Troubleshooting
npm 安装后缺少原生包
如果安装时禁用了 optional dependencies，可能会看到缺少平台包的提示。重新安装：
npm i -g @170-carry/ctc --include=optional
macOS 提示应用已损坏
如果 macOS 拦截未签名或隔离属性残留的应用，可以执行：
sudo spctl --master-disable
sudo xattr -r -d com.apple.quarantine /Applications/Codex\ Tools.app
Cursor 无法访问本地地址
如果 Cursor 返回 ssrf_blocked，说明它的请求侧无法访问本机私网地址。请使用 cloudflared、远程 Linux 反代或公网域名。
Project Layout
src/ React frontend
src-tauri/ Tauri and Rust backend
src-tauri/src/bin/ Native CLI binaries
npm/ npm wrapper and platform packages
docs/ Extra documentation
.github/workflows/ Release workflows
Star History
License
MIT，详见 LICENSE。
