lidge-jun/opencodex · 上手攻略

  • 仓库：lidge-jun/opencodex
  • 链接：https://github.com/lidge-jun/opencodex
  • 分类：AI 编程 · 模型路由与代理
  • 作者：Tom
  • 更新：2026-07-23

是什么

opencodex 是一个轻量级本地代理服务，它的核心职责是把 OpenAI Codex 的 Responses API 请求"翻译"成任意 LLM 提供商能理解的协议，并在请求路径上支持 ChatGPT 账户池化管理。装好之后，你在 Codex CLI/App/SDK 或 Claude Code 里选什么模型，实际上都在走 opencodex 转发到 Anthropic、Google、xAI、DeepSeek、Ollama 等 40+ 提供商——无需等待官方适配，也无需换工具链。

简单说：opencodex 让 Codex 和 Claude Code 变成一个模型无关的终端，你可以在里面跑任何 LLM。

解决什么问题

  • 模型选择受限：Codex 原生只支持 OpenAI 系模型，想用 Claude Opus 或 Gemini 得换工具。
  • 多账户配额管理：有多个 ChatGPT Plus 账号，想在新会话间自动分配压力。
  • API 成本控制：有 Claude API key 但没有 OpenAI 订阅，想直接走 Claude 侧 API。
  • 本地模型集成：有 Ollama 或 LM Studio 在本地跑量化模型，想在 Codex 里直接用。
  • Provider 锁定：不想被绑定在单一提供商的 API 上，希望随时切换。

快速安装

前置：Node 18+（Bun 运行时随 npm install 自动打包，无需单独安装）。

# 推荐用用户级 Node（nvm/fnm），不要 sudo
npm install -g @bitkyc08/opencodex

# 交互式初始化（写入配置 + 注入 Codex）
ocx init

# 启动代理
ocx start

# 启动 GUI 仪表盘（http://localhost:10100）
ocx gui

# 若跳过了 shim 安装，之后补上
ocx codex-shim install

# 正常使用 Codex——请求已自动路由到 opencodex
codex "Write a hello world in Rust"

遇到 bundled Bun runtime is missing 报错：

npm install -g --allow-scripts=bun @bitkyc08/opencodex
# 用了 sudo 安装的话保留 sudo

核心用法

添加 Provider（通过 GUI 最快）

ocx gui   # 打开 http://localhost:10100
# 1. 点击 "Add Provider"
# 2. 从 40+ 内置 provider 中选，或填自定义 OpenAI 兼容端点
# 3. 粘贴 API key（Anthropic/xAI/Kimi 支持 OAuth）
# 4. 模型自动从 /v1/models 发现，无需重启

通过 provider/model 指定路由模型

# 通过 Anthropic 用 Claude Opus
codex -m "anthropic/claude-opus-4-8" "解释这个 stack trace"

# 通过 Google 用 Gemini
codex -m "google/gemini-3-pro" "为 auth.ts 写单元测试"

# 通过 Ollama Cloud 用 GLM
codex -m "ollama-cloud/glm-5.2" "写一个 SQL migration"

# 通过 Ollama 用本地模型
codex -m "ollama/llama3" "重构这个函数"

省略 provider/ 前缀时，opencodex 按模型名自动匹配： claude-* → Anthropic，gpt-* → OpenAI。

Claude Code 中使用（需 Claude Code ≥ 2.1.129）

ocx claude [args...]   # 启动已接入代理的 Claude Code

路由模型会以 claude-ocx--- 别名出现在 Claude Code 原生模型选择器中。

ChatGPT 账户池（Pool 模式）

opencodex 的 openai provider 支持多账户轮询：

  • Pool 模式（默认）：新会话自动选配额最空闲的账户；已有线程绑定原账户不断开。
  • Direct 模式：绕过池，直接用主登录凭证。
  • 仪表盘可一键刷新所有账户 5h/每周/30d 配额。

其他常用命令

ocx status           # 查看代理是否在运行
ocx stop             # 停止代理并恢复原生 Codex 配置
ocx update           # 更新 opencodex
ocx service install   # 安装后台服务（launchd/systemd/Task Scheduler）

典型适用场景

场景 推荐配置
用 Claude Opus 写代码但没有 OpenAI 订阅 anthropic provider + API key
同时跑 Claude 和 Gemini 做模型对比 双 provider + codex -m "google/gemini-3-pro"
有多个 ChatGPT Plus 账户共享团队 openai Pool 模式 + 多账户注入
本地跑量化模型（Ollama/vLLM） ollama provider + 本地 endpoint
用 Claude Code 但想路由到 Claude API ocx claude 启动
规避 OpenAI API 限速做高并发任务 openai-apikey Direct 模式 + key pool

坑与注意

  1. --allow-scripts=bun：npm 默认可能拦截 bun 的 postinstall 脚本导致 Bun runtime 缺失，必须加此 flag 重装。
  2. sudo 安装前缀问题：用 sudo 装到 root 前缀时 token 刷新会失败，优先迁移到用户级 Node。
  3. Claude Code 版本：路由模型出现在原生选择器需要 Claude Code ≥ 2.1.129，旧版需手动指定 -m。
  4. Provider 的 / 冲突：部分 provider ID 含斜杠（如 zenmux/moonshotai-k3-free），opencodex 会将其别名为 -，路由时透明还原。
  5. Pool 与 Direct 混用：两种模式的凭证互不 fallback，openai-apikey/gpt-5.6-sol 不会路由到 Codex 登录凭证。
  6. GPT-5.6 Sol/Terra/Luna：README 中提及这些型号，但受上游 preview gate 限制，opencodex 只准备好路由元数据，实际可用性取决于你的账号权限。

与同类对比

工具 定位 支持的模型层 账户池 GUI
opencodex Codex/Claude Code 的 provider 代理 40+ provider，含 Claude/Gemini/Ollama ✅ Pool + Direct ✅ Web 仪表盘
OpenRouter 统一 API 网关 通用，支持模型多 ❌ ❌
LiteLLM 多模型 LLM 调用库 100+ provider ❌（需自行封装） ❌
ollama 本地模型服务 本地 ❌ ❌
Codex 内置 OpenAI 官方 仅 OpenAI 系 ❌ ❌

opencodex 的差异化在于深度集成 Codex 生态（CLI/App/SDK 全链路注入）+ ChatGPT 账户池，而 LiteLLM 更偏向纯 API 聚合，opencodex 更像给 Codex 用户打造的"模型自由"方案。

一句话推荐结论

如果你已经在用 Codex 或 Claude Code，想摆脱 OpenAI 模型锁定、灵活切换 Claude/Gemini/本地模型，同时管理多个 ChatGPT 账户配额，opencodex 是目前最顺滑的一站式解法。