OpenCodex 是一款轻量级本地代理,能将 Codex 的 Responses API 请求转换为各个 LLM 提供商自己的协议。它让 Codex CLI、App、SDK 以及 Claude Code 都能使用 Anthropic、Google、xAI、Kimi、DeepSeek、GLM、Qwen、Ollama 等模型。流式响应、工具调用、推理 token、图像输入都会双向转换。
1. 快速上手
环境要求
- Node.js 18 及以上
- Bun 运行时作为 npm 依赖被打包,通过 Node 启动器执行,无需单独安装
- 注意:如果
npm配置为阻止生命周期脚本运行,安装时会出现 "bundled Bun runtime is missing" 错误。此时需要允许脚本后重新安装,或者直接安装 Bun - 建议使用 nvm/fnm 等用户自有的 Node 环境,而不是
sudo npm install -g
安装与运行
# 1. 全局安装(自动打包 Bun 运行时)
npm install -g @bitkyc08/opencodex
# 2. 交互式初始化(写入配置文件 + 注入 Codex 配置 + 引导安装自动启动 shim)
ocx init
# 3. 启动代理
ocx start
之后照常使用 Codex,请求会自动经过 opencodex。
codex "Write a hello world in Rust"
仪表盘可通过 http://localhost:10100 访问。
卸载与还原
ocx stop # 停止代理、停止后台服务、还原 Codex 配置
ocx uninstall # 清理残留配置(建议在卸载 npm 包之前执行)
npm uninstall -g @bitkyc08/opencodex
支持平台
| 系统 | 状态 | 服务管理器 |
|---|---|---|
| macOS(arm64/x64) | 支持 | launchd |
| Linux(x64/arm64) | 支持 | systemd |
| Windows(x64) | 支持(无需 WSL) | 任务计划程序 |
2. 优点
| # | 项目 | 说明 |
|---|---|---|
| 1 | 模型自由度 | 支持 40 多个内置提供商,包括 Anthropic、Google、xAI、Kimi、Ollama Cloud、Groq、OpenRouter、Azure、DeepSeek、GLM 以及 OpenAI 本身。可以在同一个 Codex 工作流中切换模型 |
| 2 | 基于适配器的转换 | 通过 Anthropic Messages、Google Gemini、Azure、OpenAI Responses 透传、OpenAI 兼容 Chat Completions 这 5 种适配器,覆盖大部分端点 |
| 3 | 简化安装配置 | 不需要自己搭建代理链,通过 ocx init 的交互式设置即可完成。xAI、Anthropic、Kimi 支持 OAuth 登录,无需 API Key 即可连接 |
| 4 | 不修改二进制文件 | 不是修改 Codex 应用的二进制文件,而是将 provider 注入到 Codex 的配置文件和模型目录中。执行 ocx stop 即可恢复原始配置 |
| 5 | 统一仪表盘 | 提供商、API Key、模型别名(alias)、日志、账号管理都可以在网页仪表盘中处理 |
| 6 | 模型路由规则 | 可以用 provider/model 格式显式指定,若省略 prefix,则按模型名称模式自动匹配(claude-* → Anthropic,gpt-* → OpenAI) |
| 7 | Codex App 集成 | 路由后的模型会与原生模型一起出现在 Codex App 的模型选择器中,并可按模型调整 reasoning effort |
| 8 | ChatGPT 账号池 | 可注册多个 ChatGPT/Codex 账号,轮转刷新 5 小时、每周、30 天的配额,并将新会话路由到用量最低的账号。已有的会话线程则固定使用当初创建它的账号 |
| 9 | 后台服务 | 注册为系统服务,开机自动运行,设计上停止时不会留下残留配置或僵尸进程 |
3. 缺点与风险
| # | 项目 | 说明 |
|---|---|---|
| 1 | 服务条款风险 | 技术上能够接入 OAuth/订阅账号,并不意味着相应提供商允许通过第三方代理使用该账号。项目自身的文档也警告存在账号受限或被封的可能性,尤其是账号池功能,有可能被解读为绕过使用量限制的手段 |
| 2 | 增加了一层复杂度 | 在 Codex 之上多了一层代理,意味着更多的配置决策点和调试环节 |
| 3 | 功能兼容存在延迟 | 由于是自建的 API 转换层,Codex 或 Claude Code 的最新功能可能无法立即得到支持 |
| 4 | 项目成熟度 | 相比官方工具,生态规模较小,发布节奏非常快(存在大量按周发布的 preview 标签),其稳定性和长期维护能力还需进一步观察 |
| 5 | 依赖持续运行 | 前提是 Node 环境和 ocx 守护进程始终在运行,相比单独使用 Codex 会占用更多资源 |
| 6 | 本地凭据集中存放 | 多个提供商的 API Key 和 OAuth Token 都会集中存放在本地配置文件(~/.opencodex/config.json)中,一旦终端被攻破,受影响范围会扩大 |
4. 名称相似的其他独立项目
有多个项目使用了"OpenCodex"这个名字,需要加以区分,以免混淆各自的功能。
| 项目 | 定位 | 与本文所述项目的关系 |
|---|---|---|
| lidge-jun/opencodex | 本文所述的项目。面向 Codex/Claude Code 的通用提供商代理 | — |
| AITabby/opencodex | 面向 Codex Desktop 的本地网关,具备 Vision Bridge、Computer Use 引擎、语音助手(OpenCodexBar) | 完全不同的项目。Vision Bridge、语音功能属于该项目,而非 lidge-jun 的版本 |
| RyensX/OpenCodex | Codex Desktop 中间件,专注于浏览器远程访问 | 完全不同的项目,远程访问功能属于该项目 |
| Open Codex(codingmoh) | 完全本地运行的 CLI 助手,无需 API Key,支持 phi-4-mini 等本地模型 | 完全不同的项目 |
5. 竞品与替代工具
| 工具 | 说明 | 区别 |
|---|---|---|
| OpenCode(SST) | 开源终端 AI 编码代理 | 是独立代理,而非中转代理。原生支持多个提供商,对 OpenCode 用户来说 opencodex 的实际价值有限 |
| Claude Code | Anthropic 的终端编码助手 | 专注于 Claude 生态,opencodex 也可作为 Claude Code 侧的代理运行 |
| Cursor | AI 原生代码编辑器 | 以 IDE 内置体验为核心 |
| GitHub Copilot | IDE 插件式编码助手 | 提供商选择范围有限 |
| Aider / Cline / Windsurf | 各有不同方式的编码代理 | 工作流和专长领域各不相同 |
6. 与单独使用 Codex 的对比
| 项目 | 单独使用 Codex | Codex + OpenCodex |
|---|---|---|
| 可用模型 | 仅 OpenAI 系列 | 40 多个提供商 |
| 配置难度 | 低 | 中等 |
| 成本优化 | 有限 | 借助低价模型路由更具优势 |
| 定制化 | 有限 | 高 |
| 运维风险 | 低 | 新增代理故障点、提供商服务条款风险 |
| 适合人群 | 想立即上手使用的普通用户 | 重视模型实验和成本优化的高级用户 |
7. 综合评价
其技术设计是合理的。选择配置注入而不是修改二进制文件,并且能通过一句 ocx stop 完全还原,这是这类工具中最重要的安全保障。将适配器抽象为 5 种类型,也降低了扩展新提供商的成本。
不过,在决定是否采用它时,比技术便利性更重要的变量是服务条款风险。基于 API Key 的接入方式,与基于订阅账号(OAuth)的接入方式性质完全不同,尤其是多个 ChatGPT 账号池化,从提供商的角度可能被判定为规避使用量政策的行为。在工作环境中,更安全的配置是只注册基于 API Key 的提供商,而不使用账号池功能。
按周发布 preview 版本的开发节奏,在功能扩展方面是积极信号,但作为生产环境依赖来说还为时过早。目前更适合在个人开发环境中进行实验性尝试。