最近在使用 Codex 时遇到一个比较麻烦的问题：中转 API Key 偶尔会过期、额度耗尽或者触发限流，每次都要手动修改配置、重启 Codex。
所以做了一个桌面小工具 Codex Key Manager，在本机启动一个 OpenAI 兼容代理，Codex 只连接本地代理，真实 API Key 由工具统一管理。
目前是 V1 版本，主要目标是先把 Key 管理、健康检测和自动切换 做稳定。
支持 macOS，Windows 版本可使用同一套代码打包。
- 管理多个 OpenAI / 中转 API Key
- 设置 Key 优先级
- 一键测试 Key 是否可用
- 401 / 403 时自动切换备用 Key
- 429 限流或额度不足时自动进入冷却并切换
- 5xx 或临时网络错误自动重试，失败后切换
- 支持 Codex 使用的
/v1/responses - 兼容只提供
/v1/chat/completions的中转服务 - 支持 SSE 流式输出和长任务
- 自动修改 Codex 配置，停止服务时恢复原配置
- 查看请求状态、使用的 Key 和响应耗时
- 菜单栏 / 系统托盘后台运行
工作方式大致如下：
Codex App / Codex CLI
|
| http://127.0.0.1:17890/v1
v
Codex Key Manager 本地代理
|
+---- Key A（优先级 1）
+---- Key B（优先级 2）
+---- Key C（优先级 3）
代理默认只监听 127.0.0.1，不会开放到局域网。
- Node.js 22 或更高版本
- npm 10 或更高版本
- Git
- macOS 12+，或 Windows 10/11
项目使用了 Electron 原生依赖 better-sqlite3，建议在准备运行应用的目标系统上安装依赖并完成打包。
git clone https://github.com/Superbrain1/Codex-Key-Manager.git
cd Codex-Key-Manager
npm installnpm install 完成后会自动为当前 Electron 版本重建 SQLite 原生模块。
npm run dev该命令会启动 Vite、TypeScript 监听编译和 Electron。开发时修改前端代码后可以直接查看效果，不需要先制作安装包。
正式打包前建议先执行：
npm run typecheck
npm test请在 macOS 上执行：
npm run dist:mac构建完成后，.dmg 和 .zip 会生成在：
release/
构建架构默认跟随当前 Mac。Apple Silicon 设备通常生成 arm64 版本，Intel Mac 通常生成 x64 版本。
项目目前没有配置 Developer ID 签名和公证。分发自己构建的应用时，macOS 可能提示无法验证开发者。
建议在 Windows 10/11 或 Windows CI 环境中执行：
npm install
npm run dist:win构建完成后，NSIS 安装版和 Portable .exe 会生成在：
release\
由于项目包含 SQLite 原生模块，在目标操作系统上构建比跨平台打包更稳定。
如果只需要检查生产构建，不需要生成安装程序：
npm run build更多开发说明可查看仓库中的 DEVELOPMENT.md。
打开软件，进入 API Keys 页面，点击右上角的 添加 Key。
需要填写：
名称：给这个 Key 起一个容易识别的名字
API Key：真实的上游 API Key
Base URL：API 服务地址
优先级：数字越小越优先
备注：可选
标准 OpenAI 兼容地址可以这样填写：
https://api.example.com
或者：
https://api.example.com/v1
如果中转只提供 Chat Completions，也可以直接填写完整接口：
https://api.example.com/v1/chat/completions
工具会把 Codex 的 Responses 请求自动转换为 Chat Completions，并将流式响应转换回 Codex 可以识别的格式。
Base URL 末尾不要复制多余的引号、空格或反斜杠。
添加完成后，点击 Key 右侧的 测试。
测试成功后会显示：
- Key 状态正常
- 响应时间
- 获取到的模型数量
建议先确保至少有一个 Key 测试成功，再启动本地代理。
需要自动切换时，可以继续添加多个 Key，并设置不同优先级。
例如：
| Key | 优先级 | 用途 |
|---|---|---|
| Key A | 1 | 默认使用 |
| Key B | 2 | 第一备用 |
| Key C | 3 | 第二备用 |
进入 设置 页面。
默认配置：
监听地址：127.0.0.1
监听端口：17890
本地访问 Key：local-key
建议保留：
启动时自动配置 Codex，停止时恢复原配置
然后点击 启动服务。
代理地址为：
http://127.0.0.1:17890/v1
代理启动成功后，需要：
- 完全退出已经打开的 Codex App / Codex CLI。
- 重新打开 Codex。
- 新建一个任务或对话。
已经打开的 Codex 任务会继续使用启动时读取的旧配置，因此仅仅关闭当前对话通常不够。
在 Codex 中发送一条测试消息，例如：
只回复 OK
然后回到 Codex Key Manager：
- 概览页面会显示当前使用的 Key。
- 请求日志中应出现
/v1/responses。 - HTTP 状态为
200表示请求成功。
自动配置模式默认识别：
macOS：~/.codex/config.toml
Windows：%USERPROFILE%\.codex\config.toml
如果你的配置文件在其他位置，可以在设置页面手动填写 config.toml 的绝对路径。
启动服务时，工具会临时加入一个本地 provider：
model_provider = "codex_key_manager_local_proxy"
[model_providers.codex_key_manager_local_proxy]
name = "Codex Key Manager Local Proxy"
base_url = "http://127.0.0.1:17890/v1"
wire_api = "responses"
experimental_bearer_token = "local-key"停止服务或退出工具时会恢复原配置。
如果不希望工具修改配置，也可以关闭自动配置，手动设置环境变量。
macOS / Linux：
export OPENAI_BASE_URL=http://127.0.0.1:17890/v1
export OPENAI_API_KEY=local-keyWindows PowerShell：
$env:OPENAI_BASE_URL = "http://127.0.0.1:17890/v1"
$env:OPENAI_API_KEY = "local-key"这里的 local-key 只是访问本机代理的凭据，不是真实的上游 API Key。
| 上游状态 | 处理方式 |
|---|---|
| 2xx | 正常返回 |
| 400 / 404 | 原样返回，不切换 Key |
| 401 / 403 | 当前 Key 标记失败，切换下一个 |
| 429 | 当前 Key 进入冷却，切换下一个 |
| 5xx | 当前 Key 重试一次，仍失败则切换 |
| 连接超时、连接重置 | 重试一次，仍失败则切换 |
自动切换发生在代理把响应发送给 Codex 之前。
如果上游已经开始输出 SSE 内容后突然断开，由于部分内容已经发送给 Codex，这次请求无法安全地换 Key 后从头重放。这属于当前版本的限制。
依次检查：
- 设置页面是否显示“代理运行中”。
- API Key 状态是否正常。
- Base URL 是否填写正确。
- 是否完全退出并重新打开 Codex。
- 请求日志里是否出现
/v1/responses。 - Codex 配置文件路径是否指向实际使用的
config.toml。
如果中转只支持 /chat/completions，请填写完整接口地址，工具会自动进行协议转换。
说明当前没有处于可用状态的 Key。
可以在 API Keys 页面点击 测试，查看 Key 是否因为以下原因失败：
- Key 已过期
- 额度不足
- 上游返回 401 / 403
- 上游限流
- Base URL 填写错误
正常情况下，点击 停止服务 或退出工具都会恢复原配置。
如果工具异常退出，可以重新打开工具后再次启动、停止服务，让恢复流程重新执行。重要配置建议自行保留一份备份。
可能是上游模型冷启动、模型列表刷新或中转服务响应较慢。可以在请求日志中查看每次请求的耗时。
- 真实 API Key 保存在本机 SQLite 数据库中。
- 在系统支持时，API Key 会通过 Electron
safeStorage加密保存。 - 代理只监听
127.0.0.1。 - 请求日志不保存请求正文和响应正文。
- 日志不会显示完整真实 API Key。
- 界面中的用户目录会显示为
~或%USERPROFILE%，避免截图暴露设备账户名。 - 没有云同步、账号系统或远程后台。
建议在设置中把默认的 local-key 改成自己生成的随机字符串。
Codex Key Manager 0.1.0
当前还是 V1 MVP，优先保证本地代理、Responses 兼容、SSE 流式传输和 Key 自动切换稳定。
目前已知限制：
- macOS 和 Windows 安装包暂未进行商业代码签名。
- 已经开始输出的流式请求无法在中途无损切换 Key。
- Token 统计取决于上游是否返回 usage 信息。
如果遇到问题，反馈时建议附上：
操作系统版本：
Codex 版本：
Base URL 类型（不要提供真实 Key）：
请求日志中的状态码：
是否为流式请求：
请不要在帖子或截图中公开真实 API Key、完整数据库文件以及未脱敏的配置文件内容。