GitHub · 项目涌现

呵

lidge-jun/opencodex

二〇二六年八月二十六日·★ 4,876·⑂ 375·TypeScript·MIT ·最新发布 v2.7.40 · 2026-07-25 · GitHub 原仓库
摘要

opencodex 是一个轻量级本地代理，可将 OpenAI Codex 和 Claude Code 的 API 转换为任意 LLM 提供商（如 Anthropic、Google、xAI、DeepSeek、Ollama 等）的协议，支持流式传输、工具调用、推理 token 和图像功能。它通过 npm 安装（`npm install -g @bitkyc08/opencodex`），提供 Web 仪表盘（localhost:10100）管理 40 多个内置提供商和 ChatGPT 账户池，支持自动配额刷新、故障转移和亲和性路由。项目由社区维护，基于 MIT 许可证发布。

将 Claude、Gemini、Grok、GLM、DeepSeek、Kimi、Qwen、Ollama 或任何其他 LLM 与 Codex 以及 Claude Code 一起使用——无需等待任何人添加支持。

opencodex 是一个轻量级本地代理，它将 Codex 的 Responses API 转换为您的提供商所使用的协议。流式传输、工具调用、推理 token、图像——一切功能均可双向工作。

它还可以管理一个 ChatGPT 账户池，用于 Codex 认证。添加多个 ChatGPT / Codex 账户， 在仪表盘中刷新它们的 5 小时 / 每周 / 30 天配额，并让新会话自动路由到 使用率最低的健康账户。现有的 Codex 线程会固定到启动它们的账户上， 因此长时间的 SSH、tmux 或移动端连接会话不会在对话中途切换账户。

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

flowchart LR
  codex[Codex 会话<br/>CLI, App, SSH, 移动端] --> proxy[opencodex]
  proxy --> existing{已有线程?}
  existing -->|是| pinned[保持同一个<br/>ChatGPT 账户]
  existing -->|新会话| quota[刷新配额<br/>5h, 每周, 30d]
  quota --> pick[选择使用率最低<br/>的健康账户]
  pick --> upstream[ChatGPT / Codex 后端]
  pinned --> upstream
  upstream --> outcomes[配额 / 认证结果]
  outcomes -->|429| cooldown[冷却 + 故障转移]
  outcomes -->|401 / 403| reauth[标记需要重新认证]
  cooldown --> quota

支持的平台

操作系统 状态 服务管理器
macOS (arm64 / x64) 完全支持 launchd
Linux (x64 / arm64) 完全支持 systemd (用户单元)
Windows (x64) 完全支持 任务计划程序 (隐藏) / 可选原生服务 (--native, WinSW)

需要 Node 18+。Bun 运行时会自动捆绑在 npm install 中——无需单独安装 Bun。所有三个平台均可原生运行（Windows 上无需 WSL）。

快速开始

# 安装（自动捆绑 Bun 运行时——仅需 Node 18+）
# 建议使用用户拥有的 Node（nvm/fnm）——避免使用 `sudo npm install -g …`
npm install -g @bitkyc08/opencodex

# 交互式设置（写入配置，注入到 Codex，并提供自动启动 shim 安装选项）
ocx init

# 启动代理
ocx start

# 如果在初始化时跳过了，稍后安装按需自动启动 shim
ocx codex-shim install

# 正常使用 Codex——现在它通过 opencodex 路由
codex "用 Rust 写一个 hello world"

opencodex 将 Bun 运行时作为依赖项捆绑，并通过 Node 启动器运行它，因此您无需自行安装 Bun。如果您看到 "bundled Bun runtime is missing" 错误，说明安装跳过了生命周期脚本 （包括 npm 在 allowScripts 下阻止了 bun 的 postinstall）或可选 依赖项。请重新安装，不要使用那些标志，允许 bun 的安装脚本：

npm install -g --allow-scripts=bun @bitkyc08/opencodex   # 不要使用 --ignore-scripts，不要使用 --omit=optional

# 如果原始安装使用了 sudo，请继续使用 sudo：
sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex

npm 自身的警告建议使用一个省略包名的简化命令—— 那会重新安装当前目录，所以请始终显式传递 @bitkyc08/opencodex。

如果您使用 sudo 安装到了 root 拥有的前缀，上述 sudo 重新安装 会解除该前缀的阻塞——但建议在方便时迁移到用户拥有的 Node（nvm、fnm 或 用户 npm 前缀）。

添加提供商

添加提供商最快的方式是通过 Web 仪表盘：

ocx gui

这会在 http://localhost:10100 打开仪表盘。然后：

  1. 点击 "Add Provider"
  2. 从 40 多个内置提供商中选择——或输入自定义的 OpenAI 兼容端点
  3. 粘贴您的 API 密钥（或通过 OAuth 登录 Anthropic、xAI 和 Kimi）
  4. 模型会从提供商的 /v1/models 端点自动发现

您的新提供商立即可用。无需重启。

您也可以通过 ocx init（交互式 CLI）或直接编辑 ~/.opencodex/config.json 来添加提供商。

模型路由

使用 provider/model 语法定位任何已配置的提供商和模型：

自身模型 ID 包含 / 的提供商（zenmux、openrouter、nvidia 等）会以内部斜杠别名为 - 的形式暴露给 Codex（例如 zenmux/moonshotai-kimi-k3-free）；代理会透明地将它们路由回原生 ID，并且原始的完整斜杠形式也仍然有效。

# 通过 Anthropic 使用 Claude Opus
codex -m "anthropic/claude-opus-5" "解释这个堆栈跟踪"

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

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

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

当您省略 provider/ 前缀时，opencodex 会路由到默认提供商——或根据模型名称模式自动匹配（例如，claude-* 路由到 Anthropic，gpt-* 路由到 OpenAI）。

组合别名是精确的公共模型 ID，可以是裸名称或使用自定义命名空间。如果某个 组合别名与已配置的非 OpenAI provider/model 选择器完全匹配，则该组合 会在路由、/v1/models 和 Codex 目录中优先使用。重命名该 别名或删除该组合会立即恢复物理提供商选择器。

路由后的模型也会出现在 Codex App 的模型选择器中，并带有每个模型的推理努力控制：

当前的 Codex 构建可以在模型宣传支持时暴露 low、medium、high、xhigh、max 和 ultra 推理 控制。opencodex 保持 xhigh 和 max 的区分，除非提供商配置 显式地将一个映射到另一个。ultra 镜像上游 Codex 语义：它在客户端选择最大推理加上主动多代理委派，并在任何请求到达提供商之前转换为 max。路由后的模型仅在提供商配置通过 reasoningEfforts 选择加入时才宣传它。

GPT-5.6 Sol/Terra/Luna 作为可立即部署的目录条目被预置，适用于 OpenAI API 密钥和 OpenRouter 预设（gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna；OpenRouter 使用 openai/...）。它们仍然受上游可用性的预览限制；opencodex 仅为能够提供它们的账户和提供商准备路由和目录元数据。

OpenAI 提供商账户模式

提供商 ID 路由 凭证 行为
openai Codex 登录 主账户 + 添加的 Codex 账户 默认池模式；可选直连模式
openai-apikey OpenAI API API 密钥/密钥池 无 Codex 账户路由

对已配置的 openai 账户模式使用 gpt-5.6-sol，对 API 密钥使用 openai-apikey/gpt-5.6-sol。Codex 登录和 API 凭证永远不会互相回退。

池账户行为

在仪表盘中打开 Codex Auth 以添加账户并选择哪个账户应处理下一个 Codex 会话。opencodex 保持以下行为：

亮点

提供商和适配器

提供商 适配器 认证
OpenAI (ChatGPT 登录) openai-responses 转发 (无需密钥)
OpenAI (API 密钥) openai-responses 密钥
Umans AI Coding Plan anthropic 密钥
Anthropic Claude anthropic oauth / 密钥
xAI Grok openai-chat oauth / 密钥
Kimi (Moonshot) openai-chat oauth / 密钥
Google Gemini google 密钥
Azure OpenAI azure-openai 密钥
Cursor (实验性) cursor 仪表盘/本地配置；实时传输；不安全的原生本地执行是可选的
Ollama Cloud + 17 提供商目录 openai-chat 密钥
Ollama / vLLM / LM Studio (本地) openai-chat 密钥 (通常为空)
任何 OpenAI 兼容端点 openai-chat 密钥

此外还有 DeepSeek、Groq、OpenRouter、Together、Fireworks、Cerebras、Mistral、Hugging Face、NVIDIA NIM、MiniMax、Qwen Cloud、腾讯云 Coding Plan、SiliconFlow 等。使用 ocx init 或在提供商文档中查看完整列表。

Cursor 支持是一个分阶段的实验性桥接：它作为本地配置出现在 ocx init 和仪表盘 Add Provider 选择器中，带有 Cursor 的静态公共模型目录。当配置了 Cursor 访问 token 时，启用实时 HTTP/2 传输。Cursor 服务器驱动的原生读/写/删除/ls/grep/shell/fetch 执行默认禁用，因为它绕过了 Codex 的批准和沙箱路径。诸如 Codex danger-full-access 沙箱标记之类的请求文本永远不会授权原生本地执行；仅对受信任的本地实验设置 nativeLocalExec: "on"，其中每个数据平面调用者都是受信任的。nativeLocalExec: "codex-sandbox" 为了向后兼容而被接受，但像 off 一样安全关闭；遗留的 unsafeAllowNativeLocalExec: true 仍然是显式的操作员选择加入。 MCP、屏幕录制和计算机使用通过执行器钩子暴露；当没有配置本地执行器时，opencodex 返回类型化的无执行器结果，而不是策略阻止请求。 Cursor OAuth 和实时模型发现已为实验性 Cursor 适配器启用。

CLI

ocx init                       # 交互式设置
ocx start [--port 10100]       # 启动代理；如果端口繁忙，则回退到空闲端口
ocx stop                       # 停止 + 恢复原生 Codex
ocx restore                    # 恢复而不停止（别名：ocx eject）
ocx uninstall                  # 移除服务/shim/配置并恢复原生 Codex
ocx ensure                     # 如果需要则启动 + 刷新 Codex 配置/缓存
ocx sync                       # 刷新模型 + 重新注入到 Codex
ocx codex-shim install         # 每当启动 `codex` 时运行 `ocx ensure`
ocx status                     # 代理是否在运行？
ocx login <provider>          # OAuth 登录 (xai, anthropic, kimi, cursor, ...)
ocx logout <provider>          # 移除存储的登录
ocx account <list|current|use> # 列出/切换账户和 API 密钥池（掩码显示；也可刷新/自动切换/移除/添加密钥）
ocx gui                        # 打开 Web 仪表盘
ocx claude [args...]           # 启动连接到代理的 Claude Code（模型发现开启）
ocx service [install|start|stop|status|uninstall]   # 安装/更新/启动后台服务
ocx update [--tag preview]     # 更新 opencodex；预览安装保持在 @preview

自动启动：服务 vs shim

opencodex 有两种自动启动代理的方式：

ocx service / ocx service install ocx codex-shim install
方式 操作系统服务管理器 (launchd / systemd / schtasks) 包装 codex 的启动脚本；真正的 codex.exe 保持不变
何时 登录后始终运行 按需——当启动 codex 时运行 ocx ensure
重启 崩溃后自动重启 每次 codex 调用启动一次
Codex 更新 不受影响 完成的稳定启动器替换会在下一次普通 ocx 命令时修复
移除 ocx service uninstall ocx codex-shim uninstall

对于始终在线的代理，使用服务（推荐用于开发机器）。对于轻量级、按需的代理启动（无需后台守护进程），使用 shim。Shim 自动启动默认启用，可以从 GUI 仪表盘禁用。如果配置的代理端口已被占用，ocx start 会自动选择另一个空闲的本地端口并更新 Codex 以使用它。

如果外部的 Codex 更新覆盖了已安装的 shim，下一次普通 ocx 命令会备份新的稳定启动器并恢复 shim。仍在变化的启动器会保持不变并稍后重试。修复失败会发出警告，但不会使请求的命令失败；使用 ocx codex-shim install 作为手动回退。将 codexShimAutoRestore 设置为 false，或设置 OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0 以进行进程级选择退出。

卸载

在移除 npm 包之前，清理本地状态：

ocx uninstall
npm uninstall -g @bitkyc08/opencodex

ocx uninstall 会停止代理、移除任何已安装的服务、移除 Codex shim、恢复原生 Codex 配置/目录/历史记录，并删除 ~/.opencodex。

配置

配置位于 ~/.opencodex/config.json。如果文件无法解析（例如，JSON 被截断或手动损坏），opencodex 会将其备份到 config.json.invalid-<timestamp>，打印警告，并回退到默认值——因此您的原始文件永远不会被静默丢失。

以下是一个典型的多提供商设置：

{
  "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"
    }
  }
}

提供商条目还可以注释路由目录元数据和输出默认值。使用 contextWindow 设置提供商范围的 Codex 可见上下文上限，modelContextWindows 设置特定模型的上限，modelInputModalities 设置特定模型的目录输入提示，例如 ["text"] 或 ["text", "image"]。对于拒绝 Codex 推理摘要传递字段的 Responses 模型，将 modelSupportsReasoningSummaries.<model-id> 设置为 false；这会更新目录并在适配器边界剥离过时的摘要传递字段。对于上游默认响应预算太小的 OpenAI 兼容聊天提供商，设置 defaultMaxOutputTokens 或每个模型的 modelMaxOutputTokens；来自客户端的显式 max_output_tokens 仍然优先，未设置的配置仍然省略 max_tokens。上下文值限制实时 /models 元数据；它们永远不会提高较小的实时上下文窗口。捆绑的 GPT-5.6 Sol/Terra/Luna 回退元数据对 OpenAI API 密钥和 OpenRouter 目录条目使用 1,050,000 token 的上下文窗口；它不会绕过上游预览访问。有关完整字段列表，请参阅配置参考。

通过 Z.AI 的 GLM-5.2 1M 上下文： 通过 openai-chat 适配器，glm-5.2 和 glm-5.2[1m] 都有效——opencodex 在发送请求前会剥离尾部的 [1m] 后缀，因为 OpenAI 兼容端点拒绝带括号的 ID（Z.AI 400 代码 1211）。[1m] 后缀是 Claude-Code / Anthropic 端点的约定；要原生使用它，请将 anthropic 适配器指向 Z.AI 的编码基础（https://api.z.ai/api/coding/paas/v4）。通过模型目录（modelContextWindows）设置 1M 上下文窗口，而不是模型名称。

本地模型也可以工作。将 opencodex 指向您机器上运行的任何 OpenAI 兼容服务器：

{
  "port": 10100,
  "defaultProvider": "ollama",
  "providers": {
    "ollama": {
      "adapter": "openai-chat",
      "baseUrl": "http://localhost:11434/v1",
      "authMode": "key",
      "apiKey": "",
      "defaultModel": "llama3"
    },
    "vllm": {
      "adapter": "openai-chat",
      "baseUrl": "http://localhost:8000/v1",
      "authMode": "key",
      "apiKey": "",
      "defaultModel": "Qwen/Qwen3-32B"
    }
  }
}

WebSocket 传输默认关闭。仅当您希望 Codex 宣传并使用 Responses WebSocket 路径而不是 HTTP/SSE 时，才设置 "websockets": true。

远程访问

默认情况下，opencodex 绑定到 127.0.0.1（回环地址）并且不需要额外的认证。 如果您设置 "hostname": "0.0.0.0" 以在 LAN 上暴露代理，opencodex 需要一个 bearer token 来保护管理 API（/api/*）和数据平面（/v1/responses、 /v1/images/generations 和 /v1/images/edits）：

export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
ocx start

当绑定到回环地址之外时，如果没有此变量，代理会拒绝启动。如果您为 LAN 访问安装后台服务，请在 ocx service install 之前导出相同的变量，以便服务管理器接收它。 客户端（脚本、远程机器）必须在每个请求中包含 token：

x-opencodex-api-key: your-secret-token

Token 以恒定时间进行比较，以防止时序攻击。

opencodex 会自动重新映射 Codex 恢复历史记录，以便在代理活动时，旧的 OpenAI 聊天和 opencodex 创建的项目线程在 Codex App 中保持可见。opencodex 将原始提供商/源元数据记录在 ~/.opencodex/codex-history-backup.json 中。ocx stop / ocx restore 将备份的 OpenAI 行恢复到 OpenAI，并将任何剩余的 opencodex 用户线程也弹出到 OpenAI，这样原生 Codex 就不会尝试恢复其提供商在 config.toml 中不再存在的线程。

如果您测试过较旧的开发版本，其中 syncResumeHistory 在备份支持存在之前就已经重新映射了历史记录，您也可以运行显式恢复命令：

ocx recover-history --legacy-openai

有关每个字段，请参阅 配置参考。

文档

公共文档——安装、提供商、路由、sidecar、Codex 集成、Codex App 模型选择器以及 CLI/配置参考——从 docs-site/ 构建并发布到 opencodex.me。

维护者的真相来源笔记位于 structure/ 下。历史调查保留在 docs/ 下。 贡献者设置位于 CONTRIBUTING.md 中，安全报告指南 位于 SECURITY.md 中。

开发

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 dev 仍然是 bun run dev:proxy 的别名，以保持兼容性。在源代码检出中，代理 API 暴露 /healthz、/v1/responses、POST /v1/images/generations、POST /v1/images/edits 和 /api/*；GET / 仅在 bun run build:gui 生成 gui/dist 后才提供打包的仪表盘。在开发仪表盘时，请单独运行前端：

bun run dev:gui

请参阅 贡献指南。

免责声明

opencodex 是一个独立的、社区维护的项目，与 OpenAI、Anthropic 或任何其他提供商没有关联或背书。

某些提供商——特别是 Anthropic (Claude)——可能会暂停或限制通过第三方代理路由 API 流量的账户。使用风险自负 (UAYOR)。 在连接提供商之前，请查看其服务条款以确认允许基于代理的访问。opencodex 维护者对上游提供商采取的任何账户操作概不负责。

许可证

MIT

同时见于 gh-search:llm、OSSInsight 全局趋势
译自 GitHub · 项目涌现 · 录于 二〇二六年八月二十六日