codex-tools

代理,快速切换codex账号,监控codex使用量的工具,以及对codex进行api反代,支持多种语言

Overview

Codex Tools 面向同时使用多个 Codex 账号的场景，提供桌面 GUI、命令行入口和本地 /v1 反代能力。你可以用它导入账号、查看用量、切换本机 Codex 登录态，也可以把账号池暴露成 OpenAI 兼容接口供 Cursor、ChatWise、CC Switch、本地脚本等工具调用。

Highlights
Installation
Quick Start
CLI Reference
API Proxy
Development
Release
Documentation
Troubleshooting

Highlights

多账号管理：OAuth 登录导入、JSON 批量导入、账号备份回导入。
用量查看：展示 5h、1week 用量窗口和账号计划类型。
账号预热：可手动发送固定 hello 最小请求激活 5h 窗口，也可在设置中为选中账号开启自动预热；该功能会真实消耗少量额度，默认关闭并带持久化防重复冷却。
快速切换：切换 ~/.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 下载：

Latest Release
macOS Apple Silicon / Intel
Windows x64

安装桌面应用后，可以直接在 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 --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 模型：gpt-6-astra（兼容 gpt6、gpt-6、gpt6-astra 别名）
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-astra，支持 low、medium、high、xhigh、max 推理强度（ultra 映射为 max），不支持 none / minimal。代理采用 Codex CLI 0.153.4 的客户端标识与 Responses Lite 转换；已有默认模型保持 gpt-5.6-sol。

模型名称也可使用 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/v1
API 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。

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
git push origin v

发布内容：

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。

codex-tools

工具介绍

Overview

Contents

Highlights

Preview

Installation

CLI/TUI

Desktop App

Quick Start

Terminal

Desktop

CLI Reference

API Proxy

Local Clients

Cursor

CC Switch

Anthropic Messages

Development

Requirements

Run Locally

Build CLI

Build Frontend

Release

Documentation

Troubleshooting

npm 安装后缺少原生包

macOS 提示应用已损坏

Cursor 无法访问本地地址

Project Layout

Star History

License

Issues· 0 开放

> 标签

> 工具信息

> 相关工具

codex-tools

工具介绍

Overview

Contents

Highlights

Preview

Installation

CLI/TUI

Desktop App

Quick Start

Terminal

Desktop

CLI Reference

API Proxy

Local Clients

Cursor

CC Switch

Anthropic Messages

Development

Requirements

Run Locally

Build CLI

Build Frontend

Release

Documentation

Troubleshooting

npm 安装后缺少原生包

macOS 提示应用已损坏

Cursor 无法访问本地地址

Project Layout

Star History

License

Issues· 0 开放

> 标签

> 讨论区

> 工具信息

> 相关工具