opencodex 是一个本地代理服务，让 OpenAI Codex 和 Claude Code 能够接入任意第三方 LLM 提供商，同时支持 ChatGPT 账号池管理与负载均衡。
让 codex 开放！
OpenAI Codex 和 Claude Code 的通用提供商代理 — 在 Codex CLI、App、SDK 以及 Claude Code 中使用任何 LLM。
npm install -g @bitkyc08/opencodex · ocx start · localhost:10100
English · 한국어 · 简体中文 · 📖 完整文档 →
使用 Claude、Gemini、Grok、GLM、DeepSeek、Kimi、Qwen、Ollama 或任何其他 LLM 配合 Codex —— 以及配合 **Claude Code** —— 无需等待任何人添加支持。
opencodex 是一个轻量级的本地代理，可将 Codex 的 Responses API 转换为你的提供商所支持的任何格式。流式传输、工具调用、推理 token、图像 —— 所有功能都能双向正常工作。
Codex, running any model. Pick a provider and go — same Codex workflow, different brain.
它还可以管理用于 Codex 认证的 **ChatGPT 账号池**。添加多个 ChatGPT / Codex 账号，
在仪表板中刷新它们的 5 小时 / 每周 / 30 天配额，并让新会话自动路由到使用率最低的健康账号。现有的 Codex 线程会固定在启动它们的账号上，
因此长时间的 SSH、tmux 或移动连接的会话不会在对话中途跳转账号。
```
Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provider
│
Anthropic · Google · xAI · Kimi · Ollama Cloud · Groq
OpenRouter · Azure · DeepSeek · GLM · …and OpenAI itself
```
```
flowchart LR
codex[Codex session
CLI, App, SSH, mobile] --> proxy[opencodex]
proxy --> existing{Existing thread?}
existing -->|yes| pinned[Keep the same
ChatGPT account]
existing -->|new session| quota[Refresh quota
5h, weekly, 30d]
quota --> pick[Pick lowest-usage
healthy account]
pick --> upstream[ChatGPT / Codex backend]
pinned --> upstream
upstream --> outcomes[Quota / auth outcome]
outcomes -->|429| cooldown[Cooldown + failover]
outcomes -->|401 / 403| reauth[Mark reauth needed]
cooldown --> quota
```
## 支持的平台
| 操作系统 | 状态 | 服务管理器 |
|---|---|---|
| macOS (arm64 / x64) | 完全支持 | launchd |
| Linux (x64 / arm64) | 完全支持 | systemd (用户单元) |
| Windows (x64) | 完全支持 | Task Scheduler (隐藏) / 可选原生服务 (`--native`, WinSW) |
需要 [Node](https://nodejs.org) 18+。Bun runtime 会在 `npm install` 时自动打包 —— 无需单独安装 Bun。这三个平台均可原生运行（Windows 上不需要 WSL）。
## 快速开始
```
# 安装（自动打包 Bun 运行时 — 仅需 Node 18+）
# 推荐使用用户拥有的 Node (nvm/fnm) — 避免 `sudo npm install -g …`
npm install -g @bitkyc08/opencodex
# 交互式设置（写入 config，注入到 Codex，并提供 autostart shim 安装）
ocx init
# 启动 proxy
ocx start
# 如果在 init 期间跳过了，稍后安装按需的 autostart shim
ocx codex-shim install
# 正常使用 Codex — 它现在通过 opencodex 路由
codex "Write a hello world in Rust"
```
“缺少内置的 Bun runtime” / npm 屏蔽了 Bun 安装脚本？
opencodex 将 Bun runtime 作为依赖打包，并通过 Node
启动器运行它，因此你**不需要**自行安装 Bun。如果你看到
“缺少内置的 Bun runtime” 错误，说明安装过程跳过了生命周期脚本
（包括 npm 在 `allowScripts` 下屏蔽了 bun 的 postinstall）或可选
依赖项。请移除这些标志重新安装，以允许 bun 的安装脚本运行：
```
npm install -g --allow-scripts=bun @bitkyc08/opencodex # no --ignore-scripts, no --omit=optional
# 如果原始安装使用了 sudo，请继续使用 sudo：
sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex
```
npm 自身的警告会建议使用不带包名的缩写命令 —
这会重新安装当前目录，因此请务必显式传入
`@bitkyc08/opencodex`。
如果你使用 `sudo` 安装到了 root 拥有的 prefix 中，上面的 sudo 重新安装会
解锁该 prefix —— 但建议尽可能迁移到用户拥有的 Node（nvm、fnm 或
用户 npm prefix）。
## 添加提供商
添加提供商最快的方式是通过 Web 仪表板：
```
ocx gui
```
这会在 `http://localhost:10100` 打开仪表板。接下来：
1. 点击 **"Add Provider"**
2. 从 **40 多个内置提供商**中选择 —— 或者输入自定义的 OpenAI 兼容 endpoint
3. 粘贴你的 API key（或者通过 OAuth 登录 Anthropic、xAI 和 Kimi）
4. 模型会从提供商的 `/v1/models` endpoint **自动发现**
你的新提供商会立即可用。无需重启。
你也可以通过 `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-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）。
路由后的模型也会出现在 **Codex App** 的模型选择器中，并带有逐个模型的推理强度控制：
当前的 Codex 版本在模型支持时可以暴露 `low`、`medium`、`high`、`xhigh`、`max` 和 `ultra`
推理控制。除非提供商配置明确进行映射，否则 opencodex 会保持 `xhigh` 和 `max` 的独立性。`ultra` 反映了上游 Codex 的语义：它选择
最高推理加上客户端中的主动多代理委派，并且在任何请求到达提供商之前被转换为 `max`。只有当提供商配置通过 `reasoningEfforts`
选择启用时，路由的模型才会显示它。
GPT-5.6 Sol/Terra/Luna 作为 OpenAI API key 和 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 key/key 池 | 无 Codex 账号路由 |
- 池化包括主 Codex 登录和已添加的账号，具有亲和性、配额、冷却和故障转移。
- 直接模式会短路池状态，仅使用当前调用者/主登录的 bearer。
- 全新安装以及没有持久化模式的配置默认为池化。在
仪表板的 **Providers** 页面更改模式；无论哪种模式，模型 ID 均保持裸露状态。
- 旧的公共提供商 ID `chatgpt` 在迁移后会被隐藏。原始配置在
`~/.opencodex/config.json.pre-openai-tiers-v2.bak` 中保留一次；使用
`cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json` 恢复它。
- 当前配置使用 `openaiProviderTierVersion: 2`。早期的 v1 三提供商配置会自动
迁移到单一的 `openai` 行中。
- API 层级包括 Pro 虚拟模型（`gpt-5.6-sol-pro`、`gpt-5.6-terra-pro`、
`gpt-5.6-luna-pro`）。在通信层级别，每个都会重写为其基础模型，并带有
`reasoning.mode: "pro"`。
- 其目录固定为八个 ID：`gpt-5.5`、`gpt-5.6`、Sol/Terra/Luna 以及对应的三个
Pro 虚拟 ID。没有通用的 `gpt-5.6-pro` 别名。
- 精简请求会保留所选层级，但在发送基础模型时不带 reasoning 对象。
- 官方 API 元数据为 1,050,000 上下文 token 和 922,000 最大输入 token。
为配置的 `openai` 账号模式使用 `gpt-5.6-sol`，并为
API key 使用 `openai-apikey/gpt-5.6-sol`。Codex 登录和 API 凭证永远不会互相回退。
### 池化账号行为
在仪表板中打开 **Codex Auth** 添加账号，并选择哪个账号应该处理
下一个 Codex 会话。opencodex 保持以下行为：
- **现有会话保持亲和性。** 线程 ID 绑定到所选账号，并在
后续轮次中重用，因此长请求或移动/SSH 附加的会话会继续使用同一个账号。
- **新会话可以自动路由。** 启用自动切换后，opencodex 会比较 5 小时、每周和 30 天使用量中已知的最严苛的
配额窗口，然后在活跃账号超过阈值时为新会话选择一个使用率较低的合格账号。
- **内置配额查询。** 仪表板可以一键刷新所有账号配额，并且
请求日志使用非 PII 的账号序号标记池流量。
- **失败即安全关闭。** Token 失败会标记为需要重新认证，而不是静默回退到另一个
凭证；429 配额响应会使账号进入冷却期，并可以将未来的工作
故障转移到另一个合格的池账号。
## 亮点
- **在 Codex 中使用任何 LLM。** 5 种协议适配器涵盖 Anthropic Messages、Google Gemini、Azure、OpenAI Responses passthrough 以及每一个兼容 OpenAI 的 Chat Completions endpoint —— 开箱即用支持 40 多家提供商。
- **也可以在 Claude Code 中使用任何 LLM。** 同一个守护进程提供 Anthropic Messages API（`/v1/messages` + `count_tokens`）服务：`ocx claude` 启动完全连接好的 Claude Code，并且路由的模型通过网关模型发现（`claude-ocx-
--` 别名，Claude Code 2.1.129+）出现在其原生的 `/model` 选择器中。在仪表板的 Claude 页面配置槽位和模型映射。
- **安全地池化 ChatGPT 账号。** 将现有的 Codex 线程保留在一个账号上，而新会话
可以从池中自动选择使用率较低的账号，并提供配额刷新和非 PII 请求标签。
- **登录一次，跳过 API key。** 对 xAI、Anthropic 和 Kimi 的 OAuth 支持意味着你可以使用现有账号进行身份验证。Token 自动刷新。或者转发你的 `codex login`，粘贴 API key，或使用 `${ENV_VAR}` 引用 —— 由你决定。
- **在 Codex 能运行的任何地方运行。** 自动注入 Codex CLI、TUI、App 和 SDK。路由的模型就像原生模型一样出现在 Codex 的模型选择器中。
- **历史记录安全的注入。** 在本地安装时，代理通过单行 `openai_base_url` 将 Codex 自身内置的 `openai` 提供商指向自身 —— 新线程保留其原生提供商标签，因此正在进行的聊天历史永远不会被重映射，并且异常关闭也无法隐藏它。（在首次启动时，由旧版本重新打标签的线程会被迁移回去；远程/LAN 绑定使用专门的提供商条目，因为它们需要 API-key 标头。）
- **委派给合适的模型。** 从仪表板或配置中，在 Codex 的子代理选择器中特别展示多达五个路由或原生模型 —— 将复杂任务路由到推理模型，将快速任务路由到廉价模型。在 v2 多代理界面（GPT-5.6 Sol/Terra）上，代理会注入精简的委派指导：首选的子代理模型和强度（`injectionModel` / `injectionEffort`），带有各自支持的强度阶梯的展示模型列表，以及允许跨模型 `spawn_agent` 调用应用其覆盖配置的 `fork_turns` 规则。已知限制：当原生父级生成路由子级时，任务主体当前可能会以后端加密形式到达并丢失（[#92](https://github.com/lidge-jun/opencodex/issues/92）） —— 对于可靠的跨提供商委派，请使用 v1 界面。想要自定义措辞？设置包含 `{{model}}` / `{{effort}}` / `{{roster}}` 占位符的 `injectionPrompt`。
- **为预览受限的 OpenAI 版本发布做好准备。** GPT-5.6 Sol/Terra/Luna 条目保留了上游强度阶梯。Direct/Multi 使用 372k Codex 合约；OpenAI API 和 OpenRouter 在上游访问可用时使用 1.05M 元数据。
- **赋予任何模型超能力。** 非 OpenAI 模型通过你的 ChatGPT 登录的 `gpt-5.4-mini` sidecar 获得真正的网页和图像理解能力。
- **原生生成图像。** Codex 的独立 `image_gen` 工具使用 `POST /v1/images/generations` 进行生成，使用 `POST /v1/images/edits` 进行编辑；它与托管式 Responses 的 `image_generation` 工具是分开的。
- **查看正在发生的事情。** Web 仪表板显示提供商、OAuth 状态、模型选择和实时请求日志，包括在上游报告时的缓存/缓存写入 token 计数 —— 不再猜测请求失败的原因。
- **在后台运行。** 作为系统服务（launchd / systemd / Task Scheduler）安装，然后将其抛之脑后。在 macOS/Linux 上，代理在登录时启动；在 Windows 上，默认的 Task Scheduler 后端在登录时启动（无窗口），或者使用 `ocx service install --native` 来安装一个在开机时启动的真正 Windows 服务。
- **干净退出，零残留。** `ocx stop`（或仪表板的停止按钮）会关闭代理，如果安装了后台服务也会将其停止，并将 Codex 恢复到其原始配置。普通的 `codex` 会像以前一样正常运行 —— 没有残留配置，没有孤立进程。
## 提供商与适配器
| 提供商 | 适配器 | 认证 |
|---|---|---|
| OpenAI (ChatGPT 登录) | `openai-responses` | 转发 (无 key) |
| OpenAI (API key) | `openai-responses` | key |
| Umans AI Coding Plan | `anthropic` | key |
| Anthropic Claude | `anthropic` | oauth / key |
| xAI Grok | `openai-chat` | oauth / key |
| Kimi (Moonshot) | `openai-chat` | oauth / key |
| Google Gemini | `google` | key |
| Azure OpenAI | `azure-openai` | key |
| Cursor (实验性) | `cursor` | 仪表板/本地配置；实时传输；不安全的原生本地执行需主动开启 |
| Ollama Cloud + 17 提供商目录 | `openai-chat` | key |
| Ollama / vLLM / LM Studio (本地) | `openai-chat` | key (通常为空) |
| 任何兼容 OpenAI 的 endpoint | `openai-chat` | key |
此外还有 DeepSeek、Groq、OpenRouter、Together、Fireworks、Cerebras、Mistral、Hugging Face、NVIDIA NIM、MiniMax、Qwen Cloud 等。通过 `ocx init` 或在 [提供商文档](https://lidge-jun.github.io/opencodex/reference/configuration/) 中查看完整列表。
Cursor 支持是一个分阶段的实验性桥接：它在 `ocx init` 和仪表板的添加
提供商选择器中作为本地配置出现，带有 Cursor 的静态公共模型目录。当配置了
Cursor 访问 token 时，将启用实时
HTTP/2 传输。Cursor 服务器驱动的原生
读/写/删除/ls/grep/shell/fetch 执行默认禁用，因为它绕过了 Codex 的
审批和沙箱路径；仅在受信任的本地
实验中设置 `unsafeAllowNativeLocalExec: true`。
MCP、屏幕录制和 computer-use 通过执行器钩子暴露；当未配置本地执行器时，
opencodex 会返回类型化的无执行器结果，而不是策略阻止请求。
Cursor OAuth 和实时模型发现已为实验性 Cursor 适配器启用。
## CLI
```
ocx init # interactive setup
ocx start [--port 10100] # start the proxy; falls back to a free port if busy
ocx stop # stop + restore native Codex
ocx restore # restore without stopping (alias: ocx eject)
ocx uninstall # remove service/shim/config and restore native Codex
ocx ensure # start if needed + refresh Codex config/cache
ocx sync # refresh models + re-inject into Codex
ocx codex-shim install # run `ocx ensure` whenever `codex` is launched
ocx status # is the proxy running?
ocx login # OAuth login (xai, anthropic, kimi, cursor, ...)
ocx logout # remove a stored login
ocx gui # open the web dashboard
ocx claude [args...] # launch Claude Code wired to the proxy (model discovery on)
ocx service [install|start|stop|status|uninstall] # install/update/start background service
ocx update [--tag preview] # update opencodex; preview installs stay on @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 codex-shim install` 或 `ocx update` 时修复 |
| **移除** | `ocx service uninstall` | `ocx codex-shim uninstall` |
使用 **服务** 来实现常驻代理（推荐用于开发机器）。使用 **shim** 来实现
无需后台守护进程的轻量级、按需代理启动。Shim 自动启动默认启用，
并且可以从 GUI 仪表板禁用。如果配置的代理端口已被占用，`ocx start`
会自动选择另一个可用的本地端口并更新 Codex 以使用它。
### 卸载
在移除 npm 包之前，清理本地状态：
```
ocx uninstall
npm uninstall -g @bitkyc08/opencodex
```
`ocx uninstall` 会停止代理，移除任何已安装的服务，移除 Codex shim，恢复
原生的 Codex 配置/目录/历史记录，并删除 `~/.opencodex`。
## 配置
配置文件位于 `~/.opencodex/config.json`。如果文件无法解析（例如被截断或
手动破坏的 JSON），opencodex 会将其备份为 `config.json.invalid-`，打印警告，
并回退到默认值 —— 这样你的原始文件就永远不会被静默丢失。
这是一个典型的多提供商设置：
```
{
"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"]`。Context 值会限制实时的 `/models` 元数据；它们永远不会扩大较小的实时
上下文窗口。内置的 GPT-5.6 Sol/Terra/Luna 回退元数据为 OpenAI API key 和 OpenRouter 目录条目使用 1,050,000 token 的上下文
窗口；它不会绕过上游的预览
访问权限。有关完整的字段列表，请参见配置参考。
本地模型也可以使用。将 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` 之前 export 相同的变量，以便
服务管理器接收它。
客户端（脚本、远程机器）必须在每个请求中包含该 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
```
有关每个字段的说明，请参见 **[配置参考](https://lidge-jun.github.io/opencodex/reference/configuration/)**。
## 文档
公开文档 —— 包括安装、提供商、路由、sidecars、Codex 集成、Codex App 模型选择器和 CLI/配置参考 —— 均改编自 [`docs-site/`](./docs-site) 并发布至 **[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/)**。
维护者的事实来源（source-of-truth）说明位于 [`structure/`](./structure) 下。历史调查保留在 [`docs/`](./docs) 下。
贡献者设置位于 [`CONTRIBUTING.md`](./CONTRIBUTING.md)，安全报告指南
位于 [`SECURITY.md`](./SECURITY.md)。
## 开发
```
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy # start the proxy API in dev mode
bun run dev:gui # start the dashboard dev server in another terminal
bun x tsc --noEmit # typecheck
```
出于兼容性考虑，`bun run dev` 仍是 `bun run dev:proxy` 的别名。在源代码检出中，
代理 API 暴露了 `/healthz`、`/v1/responses`、`POST /v1/images/generations`、
`POST /v1/images/edits` 和 `/api/*`；只有在
`bun run build:gui` 生成了 `gui/dist` 之后，`GET /` 才会提供打包后的仪表板。在修改仪表板时，请单独运行前端：
```
bun run dev:gui
```
参见 **[贡献指南](./CONTRIBUTING.md)**。
## 免责声明
opencodex 是一个独立的、由社区维护的项目，**不隶属于 OpenAI、Anthropic 或任何其他提供商，也没有得到他们的认可**。
部分提供商 —— 尤其是 Anthropic (Claude) —— 可能会暂停或限制通过第三方代理路由 API 流量的账号。**使用风险自负 (UAYOR)。** 在连接提供商之前，请查阅其服务条款，确认是否允许基于代理的访问。opencodex 维护者不对上游提供商采取的任何账号措施负责。
## 许可证
MIT