opencodex：让 Codex 和 Claude Code 用上任意 LLM 的通用代理

调研时间：2026 年 7 月 23 日 项目地址：https://github.com/lidge-jun/opencodex 文档站：https://lidge-jun.github.io/opencodex/ npm 包：@bitkyc08/opencodex 当前版本：v2.7.33

一、项目概述

opencodex（命令行工具简称 ocx）是一个轻量级本地代理，核心能力是将 OpenAI Codex 的 Responses API 翻译成任意 LLM Provider 所支持的协议。简言之：让 Codex CLI、Codex App、Codex SDK 以及 Anthropic Claude Code 能够使用任意大语言模型——无需等待官方添加支持。

核心定位

Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ 任意 Provider
                                              │
              Anthropic · Google · xAI · Kimi · Ollama Cloud · Groq
              OpenRouter · Azure · DeepSeek · GLM · …以及 OpenAI 本身

opencodex 不是一个编码 Agent 本身，而是一个协议翻译层 / 代理中间件。它让用户保持 Codex 原有的工作流不变，只替换后端的"大脑"——从 OpenAI 独占变成任意 Provider。同一个守护进程、同一个端口（localhost:10100），同时服务于 Codex 和 Claude Code 两大 AI 编程客户端。

核心价值主张

使用 Claude、Gemini、Grok、GLM、DeepSeek、Kimi、Qwen、Ollama 或任何其他 LLM 来驱动 Codex——同时还支持 Claude Code——无需等待任何人添加支持。

二、基本信息

三、核心功能详解

1. 用任意 LLM 驱动 Codex

opencodex 内置 5 种协议适配器，覆盖主流 LLM Provider 的全部 API 协议：

此外还有较新的适配器：kiro（AWS Kiro/Smithy 事件协议）、cursor（实验性 Cursor 桥接）、mimo-free。

开箱即用支持 40+ Provider，包括：DeepSeek、Groq、OpenRouter、Together、Fireworks、Cerebras、Mistral、Hugging Face、NVIDIA NIM、MiniMax、Qwen Cloud、Umans AI Coding Plan、Volcengine Ark Agent Plan、Alibaba（Qwen）、Z.AI（GLM）、Mimo、GitHub Copilot Transport 等。

2. 用任意 LLM 驱动 Claude Code

同一守护进程不仅服务于 Codex，还提供 Anthropic Messages API（/v1/messages + count_tokens）：

• ocx claude [args...] 一键启动已配置好的 Claude Code
• 路由后的模型会出现在 Claude Code 原生 /model 选择器中
• 模型别名为 claude-ocx-<provider>--<model> 格式
• 需 Claude Code 2.1.129+ 版本

一个守护进程，两大 AI 编程客户端，任意 Provider——这是 opencodex 的独特定位。

3. ChatGPT 账户池化管理

opencodex 可以管理多个 ChatGPT/Codex 账户，实现智能调度：

4. OAuth 免 API Key 登录

支持以下 Provider 的 OAuth 登录，令牌自动刷新：

登录一次即可，无需手动管理 API Key。也支持转发已有的 codex login、粘贴 API Key、或使用 ${ENV_VAR} 环境变量引用。

5. 模型路由语法

通过 provider/model 语法指定模型：

# 通过 Anthropic 使用 Claude Opus
codex -m "anthropic/claude-opus-4-8" "Explain this stack trace"

# 通过 Google 使用 Gemini
codex -m "google/gemini-3-pro" "Write unit tests for auth.ts"

# 通过 Ollama Cloud 使用 GLM
codex -m "ollama-cloud/glm-5.2" "Write a SQL migration"

# 通过本地 Ollama 使用
codex -m "ollama/llama3" "Refactor this function"

当省略 provider/ 前缀时，opencodex 会自动匹配：claude-* → Anthropic，gpt-* → OpenAI。内部分隔符为 / 的 Provider（如 openrouter、nvidia）会将内部斜杠别名为 -。

6. 智能模型委托（Subagent Delegation）

• 在 Codex 子代理选择器中展示最多 5 个路由/原生模型
• 复杂任务路由到推理模型，简单任务路由到快速模型
• 在 v2 多 Agent 表面（GPT-5.6 Sol/Terra）上注入委托指导
• 支持 injectionPrompt 自定义模板，含 {{model}}、{{effort}}、{{roster}} 占位符
• 推理等级支持：low、medium、high、xhigh、max、ultra

已知限制：原生父 Agent 生成路由子 Agent 时，任务体可能以加密形式到达后端导致丢失（Issue #92）。

7. 为非 OpenAI 模型赋予超能力

非 OpenAI 模型通过 gpt-5.4-mini 边车（sidecar）获得：

• 网页搜索：真实网络搜索能力
• 图像理解：图像识别与描述

8. 原生图像生成

支持独立的图像生成端点： - POST /v1/images/generations — 图像生成 - POST /v1/images/edits — 图像编辑

与 Responses hosted image_generation 工具分开运行。

9. Web 仪表盘

React 19 + Vite 构建的实时仪表盘（http://localhost:10100）：

• Provider 管理与添加
• OAuth 状态查看
• 模型选择与发现
• 实时请求日志（含缓存/缓存写入 token 计数）
• 每模型成本分解（Usage 标签页）
• Codex Auth 账户管理
• 模型组合（Combos）管理
• 调试日志（合并到 Logs 页面）

10. 后台服务运行

安装为系统服务，开机自启，崩溃自动重启：

11. 历史安全注入

opencodex 只通过一行 openai_base_url 将 Codex 内置的 openai Provider 指向自身：

• 新线程保留原生 Provider 标签
• 进行中的聊天历史不会被重新映射
• 异常关闭不会隐藏注入痕迹
• 旧版本重新映射的线程在首次启动时自动迁移回来
• 远程/LAN 绑定使用专用 Provider 条目（需要 API Key 头）

12. 干净退出，零残留

ocx stop        # 停止代理，恢复 Codex 原始配置
ocx uninstall   # 移除服务/shim/配置，恢复原生 Codex，删除 ~/.opencodex

无残留配置，无孤儿进程。

13. 预览门控的 OpenAI 模型支持

GPT-5.6 Sol/Terra/Luna 目录条目已就绪： - Direct/Multi 使用 372k Codex 合约 - OpenAI API 和 OpenRouter 使用 1,050,000 token 上下文窗口元数据 - Pro 虚拟模型（*-pro）映射到基础模型 + reasoning.mode: "pro"

14. 远程/局域网访问

默认绑定 127.0.0.1（仅本地）。设置 hostname: "0.0.0.0" 可暴露到局域网： - 需要 Bearer Token（环境变量 OPENCODEX_API_AUTH_TOKEN） - 客户端通过 x-opencodex-api-key 头发送 - 常量时间比较，防止时序攻击

15. 多国际化支持

README 翻译：英语、韩语、简体中文、俄语、日语 GUI 界面：中文、德语、俄语、日语

四、安装与快速开始

前置条件

• Node.js 18+（推荐使用 nvm/fnm 管理的用户级 Node，避免 sudo npm install -g）
• Bun 运行时在 npm install 时自动打包，无需单独安装
• 已安装 OpenAI Codex CLI（codex 命令可用）

安装

npm install -g @bitkyc08/opencodex

如果 npm 阻止了 Bun 安装脚本：

npm install -g --allow-scripts=bun @bitkyc08/opencodex

不要使用 --ignore-scripts 或 --omit=optional。

首次设置

ocx init          # 交互式设置（写入配置、注入 Codex、提供自启选项）
ocx start         # 启动代理 → localhost:10100
ocx gui           # 打开 Web 仪表盘 → http://localhost:10100

日常使用

# 使用默认 Provider
codex "Write a hello world in Rust"

# 指定 Provider 和模型
codex -m "anthropic/claude-opus-4-8" "Explain this stack trace"
codex -m "google/gemini-3-pro" "Write unit tests for auth.ts"
codex -m "ollama-cloud/glm-5.2" "Write a SQL migration"
codex -m "ollama/llama3" "Refactor this function"

# 启动 Claude Code（自动配置好代理）
ocx claude [args...]

通过仪表盘添加 Provider

1. 运行 ocx gui 打开仪表盘
2. 点击 "Add Provider"
3. 从 40+ 内置 Provider 中选择，或输入自定义 OpenAI 兼容端点
4. 粘贴 API Key 或通过 OAuth 登录
5. 模型从 Provider 的 /v1/models 端点自动发现

也可通过 ocx init 交互式添加，或直接编辑 ~/.opencodex/config.json。

五、完整 CLI 命令参考

自启动方式对比

卸载

ocx uninstall                      # 停止代理，移除服务/shim，恢复 Codex，删除 ~/.opencodex
npm uninstall -g @bitkyc08/opencodex

六、配置详解

配置文件路径：~/.opencodex/config.json

如果配置文件不可解析，会自动备份为 config.json.invalid-<timestamp> 并回退到默认配置。

典型多 Provider 配置

{
  "port": 10100,
  "defaultProvider": "anthropic",
  "providers": {
    "anthropic": {
      "adapter": "anthropic",
      "baseUrl": "https://api.anthropic.com",
      "authMode": "oauth",
      "defaultModel": "claude-sonnet-4-6"
    },
    "ollama-cloud": {
      "adapter": "openai-chat",
      "baseUrl": "https://ollama.com/v1",
      "apiKey": "${OLLAMA_API_KEY}",
      "defaultModel": "glm-5.2"
    }
  }
}

配置项说明

GLM-5.2 1M 上下文

通过 openai-chat 适配器，glm-5.2 和 glm-5.2[1m] 均可使用——opencodex 会在发送请求前剥离 [1m] 后缀。

本地模型配置

{
  "providers": {
    "ollama": {
      "adapter": "openai-chat",
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": ""
    },
    "vllm": {
      "adapter": "openai-chat",
      "baseUrl": "http://localhost:8000/v1",
      "apiKey": ""
    }
  }
}

七、支持的 Provider 与适配器

完整 Provider 列表

OpenAI Provider 账户模式

• Pool 模式：包含主 Codex 登录和已添加账户，具有亲和性、配额、冷却和故障转移
• Direct 模式：短路池状态，仅使用当前调用方的 bearer token
• 配置版本：openaiProviderTierVersion: 2
• Pro 虚拟模型（如 gpt-5.6-sol-pro）映射到基础模型 + reasoning.mode: "pro"

八、项目架构

顶层目录结构

opencodex/
├── bin/                CLI 启动器（ocx.mjs）
├── src/                代理运行时（TypeScript，Bun 原生）
│   ├── adapters/       协议翻译层（Provider 端）
│   ├── claude/         Claude Code 集成（Anthropic Messages API 翻译）
│   ├── cli/            ocx CLI 命令
│   ├── codex/          Codex CLI/App 注入与管理
│   ├── combos/         模型组合预设
│   ├── generated/      生成的 protobuf 代码
│   ├── lib/            共享工具
│   ├── oauth/          OAuth 流和令牌守护
│   ├── providers/      Provider 注册表与元数据
│   ├── responses/      OpenAI Responses API 解析
│   ├── server/         HTTP 服务器、管理 API、请求日志
│   ├── storage/        持久化状态
│   ├── update/         自更新
│   ├── usage/          使用量/定价追踪
│   ├── vision/         图像理解边车
│   ├── web-search/     网页搜索边车
│   ├── bridge.ts       核心代理桥接逻辑
│   ├── config.ts       配置加载/保存
│   ├── router.ts       请求路由到 Provider
│   ├── service.ts      后台服务安装/启动/停止
│   └── types.ts        共享 TypeScript 类型
├── gui/                React 19 + Vite Web 仪表盘
├── docs-site/          Astro + Starlight 文档站
├── docs/               历史调查记录、ADR
├── structure/          维护者架构笔记（9 个文件）
├── scripts/            发布和维护工具
├── tests/              Bun 测试套件
├── assets/             横幅图片、架构图、演示 GIF
├── AGENTS.md           AI Agent 贡献指南
├── CONTRIBUTING.md     贡献者指南
├── MAINTAINERS.md      维护者审查/合并策略
├── SECURITY.md         安全报告
└── README.md（+ 韩语/中文/俄语/日语版本）

核心源码文件

技术栈

九、与 OpenAI 官方 Codex CLI 对比

关键概念区别：OpenAI Codex 是编码 Agent 客户端，opencodex 是翻译代理——让你保持相同的 Codex 客户端工作流（CLI、App、SDK），但将后端大脑替换为任意 LLM Provider。它有意保留 Codex 的 UX：注入模型出现在 Codex 原生模型选择器中，配置注入是历史安全的，ocx stop 干净地恢复原生 Codex。

十、开发活跃度与社区

发布节奏

项目创建于 2026-06-18，仅 5 周已达到 v2.7.33，发布极为频繁——一天多次发布。采用 preview 预发布通道 + latest 正式发布模式。发布流程通过 scripts/release.ts 和 GitHub Actions 自动化。

近期版本时间线： - v2.7.33（2026-07-22） - v2.7.33-preview.20260722（2026-07-22） - v2.7.31（2026-07-21） - v2.7.30（2026-07-21）

分支策略

测试规模

3,571 个测试通过（截至 PR #304），3,513 个（PR #303）。CI 门包括 typecheck + lint:gui + test + privacy:scan。

主要贡献者

• lidge-jun（提交身份 bitkyc08-arch / [email protected]）— 主要开发者和所有者
• Wibias — 活跃外部贡献者
• str0203 — 多个 feature request 和 bug report
• jhste102lab — 韩语社区贡献者
• Ingwannu — 安全审查者
• 其他：mushikingh、diegocantarero、mihneaptu、Kling0012 等

社区国际化

Issues 使用中、英、韩三种语言提交，社区高度国际化。

近期开发重点（v2.7.33 周围）

1. Kiro（AWS）完整加固：完成、传输、OAuth、Smithy 事件验证、凭证导入文档
2. Antigravity（Google）effort 路由：effort 变体模型折叠为基础 ID，thinkingConfig 支持
3. 自定义模型管理：配置类型、管理 API、目录合并、GUI 芯片 UI、CLI 子命令
4. OpenRouter 可配置路由
5. GUI 改进：每模型成本分解、组合移到 Models 页、Debug 合并到 Logs
6. 新模型：Gemini 3.6 Flash 等级、qwen3.8-max-preview、gemini-3.5-flash-lite
7. 国际化：日语全面覆盖 GUI/文档/README、俄语覆盖
8. 池亲和性重构：语义终端状态

十一、常见 Issues 与注意事项

典型问题

注意事项

1. 使用风险自负（UAYOR）：opencodex 独立维护，与 OpenAI、Anthropic 或任何 Provider 无关联。某些 Provider（尤其是 Anthropic/Claude）可能限制或暂停通过第三方代理路由 API 流量的账户。
2. Bun 运行时：如 npm 阻止 Bun 安装脚本，使用 --allow-scripts=bun 参数。
3. 远程访问安全：开放局域网访问时务必设置 OPENCODEX_API_AUTH_TOKEN。
4. 多 Agent 限制：原生父 Agent 生成路由子 Agent 时，任务体可能丢失（#92）。

十二、文档与资源

十三、开发者指南

本地开发

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy    # 代理 API 开发模式
bun run dev:gui      # 仪表盘开发服务器（另开终端）
bun x tsc --noEmit   # 类型检查
bun run test         # 测试套件
bun run privacy:scan  # 隐私扫描（CI 门）
bun run prepush      # 完整 pre-push：typecheck + lint:gui + test + privacy:scan + doctor:gui

技术栈要点

• ESM 模块系统（"type": "module"）
• 严格 TypeScript（ESNext target，bundler moduleResolution，bun-types）
• 测试使用 Bun 内置 bun test
• GUI 使用 react-doctor 自动化 UI 健康检查
• CodeRabbit AI 代码审查（仅英文，按子系统路径指令）

十四、总结

opencodex 是一个极为活跃的开源项目（5 周内 3,600+ Stars，每日多次发布），解决了 AI 编程工具生态中的一个核心痛点：让 OpenAI Codex 和 Anthropic Claude Code 这两大 AI 编程客户端能够使用任意 LLM Provider。

核心价值

1. 通用性：5 种协议适配器覆盖 40+ Provider，几乎所有主流 LLM 均可接入
2. 双客户端支持：一个守护进程同时服务 Codex 和 Claude Code
3. 账户管理：ChatGPT 账户池化管理，智能调度、配额监控、故障转移
4. 开发体验：React 19 仪表盘、后台服务、历史安全注入、干净卸载
5. 安全意识：OAuth 免 Key 登录、远程访问 Bearer Token、常量时间比较

适用场景

• 想用 Claude、Gemini、DeepSeek、GLM 等非 OpenAI 模型驱动 Codex CLI
• 想用任意 Provider 驱动 Claude Code
• 需要管理多个 ChatGPT 账户的 Codex 配额
• 希望保持 Codex 原生 UX 但替换后端模型
• 需要在本地或局域网部署私有 LLM 代理

风险提示

opencodex 与 OpenAI、Anthropic 等任何 Provider 无官方关联。使用第三方代理路由 API 流量可能违反某些 Provider 的服务条款。请在使用前了解相关风险，使用风险自负（UAYOR）。

本文档由 Hermes Agent 自动调研并生成，数据截至 2026 年 7 月 23 日。 项目信息来源：GitHub API、项目 README、源码结构分析、官方文档站。