面向 OpenAI Codex 与 Claude Code 的通用代理：可在这些应用中使用任意 LLM

面向 OpenAI Codex 与 Claude Code 的通用提供商代理——在 Codex CLI、App、SDK 以及 Claude Code 中使用任意 LLM。

npm install -g @bitkyc08/opencodex · ocx start · localhost:10100

English · 한국어 · 简体中文 · Русский · 日本語 · 📖 完整文档 →

无需等待任何人添加支持，即可在 Codex——以及 Claude Code——中使用 Claude、Gemini、Grok、GLM、DeepSeek、Kimi、Qwen、Ollama 或任何其他 LLM。

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

让 Codex 运行任意模型。 选择一个提供商即可开始——保持相同的 Codex 工作流，换一个不同的“大脑”。

它还可为 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<br/>CLI, App, SSH, mobile] --> proxy[opencodex]
  proxy --> existing{Existing thread?}
  existing -->|yes| pinned[Keep the same<br/>ChatGPT account]
  existing -->|new session| quota[Refresh quota<br/>5h, weekly, 30d]
  quota --> pick[Pick lowest-usage<br/>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 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

# 如果你在 init 期间跳过此步骤，可稍后安装按需自动启动 shim
ocx codex-shim install

# 正常使用 Codex——现在请求将通过 opencodex 路由
codex "Write a hello world in Rust"

出现“bundled Bun runtime is missing”错误，或 npm 阻止了 Bun 安装脚本？

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 控制台：

这会在 http://localhost:10100 打开控制台。之后：

1. 点击 “Add Provider”
2. 从 40+ 个内置提供商中选择，或输入自定义的 OpenAI 兼容端点
3. 粘贴 API key（或通过 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-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）。

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

已路由模型也会出现在 Codex App 的模型选择器中，并提供逐模型推理强度控制：

当前 Codex 版本可在模型声明支持时展示 low、medium、high、xhigh、max 和 ultra 推理控制项。除非提供商配置明确将两者映射，opencodex 会将 xhigh 和 max 视为不同选项。ultra 遵循上游 Codex 语义：它会在客户端选择最高推理强度并启用主动多 Agent 委派，在请求到达任何提供商前会被转换为 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 账户	默认使用账户池；可选 Direct 模式
openai-apikey	OpenAI API	API key/key 池	不进行 Codex 账户路由

• 账户池包含主 Codex 登录和新增账户，并支持亲和性、配额、冷却和故障转移。
• Direct 会绕过账户池状态，仅使用当前调用方/主登录的 bearer。
• 全新安装和未持久化模式的配置默认使用 Pool。可在控制台的 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" 重写为其基础模型。
• 其目录固定为 8 个 ID：gpt-5.5、gpt-5.6、Sol/Terra/Luna，以及对应的三个 Pro 虚拟 ID。不存在通用的 gpt-5.6-pro 别名。
• Compact 请求会保留所选层级，但会发送不含推理对象的基础模型。
• 官方 API 元数据显示，其上下文窗口为 1,050,000 tokens，最大输入为 922,000 tokens。

对于已配置的 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 透传，以及所有 OpenAI 兼容的 Chat Completions 端点——开箱即用支持 40+ 家提供商。

• 也可在 Claude Code 中使用任意 LLM。 同一守护进程提供 Anthropic Messages API（/v1/messages + count_tokens）：ocx claude 可启动已完整配置的 Claude Code，已路由模型可通过网关模型发现出现在其原生 /model 选择器中（claude-ocx-<provider>--<model> 别名，Claude Code 2.1.129+）。可在控制台的 Claude 页面配置插槽和模型映射。

• 也可在 GitHub Copilot App 中使用任意 LLM。 将 Copilot 的 Model providers 指向 http://127.0.0.1:10100/v1——OpenCodex 提供 OpenAI 兼容的 GET /v1/models 和 POST /v1/chat/completions，因此已路由模型会同步至应用。参见 docs/github-copilot-app.md。

• 安全地管理 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 header。）

• 向正确的模型委派任务。 可通过控制台在 Codex 的子 Agent 选择器中展示最多五个已路由或原生模型

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI, App, SDK, and Claude Code.

npm install -g @bitkyc08/opencodex · ocx start · localhost:10100

English · 한국어 · 简体中文 · Русский · 日本語 · 📖 Full documentation →

Use Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama, or any other LLM with Codex — and with Claude Code — without waiting for anyone to add support.

opencodex is a lightweight local proxy that translates Codex's Responses API into whatever your provider speaks. Streaming, tool calls, reasoning tokens, images — everything works, in both directions.

Codex, running any model. Pick a provider and go — same Codex workflow, different brain.

It can also manage a ChatGPT account pool for Codex auth. Add multiple ChatGPT / Codex accounts, refresh their 5h / weekly / 30d quota in the dashboard, and let new sessions auto-route to the lowest-usage healthy account. Existing Codex threads stay pinned to the account that started them, so long SSH, tmux, or mobile-connected sessions do not jump accounts mid-conversation.

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<br/>CLI, App, SSH, mobile] --> proxy[opencodex]
  proxy --> existing{Existing thread?}
  existing -->|yes| pinned[Keep the same<br/>ChatGPT account]
  existing -->|new session| quota[Refresh quota<br/>5h, weekly, 30d]
  quota --> pick[Pick lowest-usage<br/>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

Loading OS	Status	Service manager
macOS (arm64 / x64)	Fully supported	launchd
Linux (x64 / arm64)	Fully supported	systemd (user unit)
Windows (x64)	Fully supported	Task Scheduler (hidden) / opt-in native service (--native, WinSW)

Requires Node 18+. The Bun runtime is bundled automatically on npm install — no separate Bun install needed. All three platforms work natively (no WSL needed on Windows).

# Install (bundles the Bun runtime automatically — only Node 18+ required)
# Prefer a user-owned Node (nvm/fnm) — avoid `sudo npm install -g …`
npm install -g @bitkyc08/opencodex

# Interactive setup (writes config, injects into Codex, and offers autostart shim install)
ocx init

# Start the proxy
ocx start

# If you skipped it during init, install the on-demand autostart shim later
ocx codex-shim install

# Use Codex normally — it now routes through opencodex
codex "Write a hello world in Rust"

"bundled Bun runtime is missing" / npm blocked Bun install scripts?

opencodex bundles the Bun runtime as a dependency and runs it via a Node launcher, so you do not need to install Bun yourself. If you see a "bundled Bun runtime is missing" error, the install skipped lifecycle scripts (including npm blocking bun's postinstall under allowScripts) or optional dependencies. Reinstall without those flags, allowing bun's install script:

npm install -g --allow-scripts=bun @bitkyc08/opencodex   # no --ignore-scripts, no --omit=optional

# if the original install used sudo, keep using sudo:
sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex

npm's own warning suggests an abbreviated command without the package name — that would reinstall the current directory, so always pass @bitkyc08/opencodex explicitly.

If you installed with sudo into a root-owned prefix, the sudo reinstall above unblocks that prefix — but prefer migrating to a user-owned Node (nvm, fnm, or a user npm prefix) when you can.

The fastest way to add a provider is through the web dashboard:

This opens the dashboard at http://localhost:10100. From there:

1. Click "Add Provider"
2. Pick from 40+ built-in providers — or enter a custom OpenAI-compatible endpoint
3. Paste your API key (or log in via OAuth for Anthropic, xAI, and Kimi)
4. Models are auto-discovered from the provider's /v1/models endpoint

Your new provider is ready to use immediately. No restart needed.

You can also add providers through ocx init (interactive CLI) or by editing ~/.opencodex/config.json directly.

Target any configured provider and model using the provider/model syntax:

Providers whose own model ids contain / (zenmux, openrouter, nvidia, …) are exposed to Codex with inner slashes aliased to - (e.g. zenmux/moonshotai-kimi-k3-free); the proxy transparently routes them back to the native id, and the raw full-slash form keeps working too.

# Use Claude Opus through Anthropic
codex -m "anthropic/claude-opus-4-8" "Explain this stack trace"

# Use Gemini through Google
codex -m "google/gemini-3-pro" "Write unit tests for auth.ts"

# Use GLM through Ollama Cloud
codex -m "ollama-cloud/glm-5.2" "Write a SQL migration"

# Use a local model through Ollama
codex -m "ollama/llama3" "Refactor this function"

When you omit the provider/ prefix, opencodex routes to the default provider — or auto-matches based on the model name pattern (e.g., claude-* routes to Anthropic, gpt-* routes to OpenAI).

Combo aliases are exact public model ids and may be bare names or use a custom namespace. If a combo alias exactly matches a configured non-OpenAI provider/model selector, the combo intentionally takes precedence in routing, /v1/models, and the Codex catalog. Renaming that alias or deleting the combo immediately restores the physical provider selector.

Routed models also appear in the Codex App model picker with per-model reasoning effort controls:

Current Codex builds can expose low, medium, high, xhigh, max, and ultra reasoning controls when a model advertises them. opencodex keeps xhigh and max distinct unless a provider config explicitly maps one to the other. ultra mirrors upstream Codex semantics: it selects maximum reasoning plus proactive multi-agent delegation in the client, and is converted to max before any request reaches a provider. Routed models advertise it only when a provider config opts in via reasoningEfforts.

GPT-5.6 Sol/Terra/Luna are seeded as rollout-ready catalog entries for the OpenAI API key and OpenRouter presets (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna; OpenRouter uses openai/...). They remain preview-gated by upstream availability; opencodex only prepares the routing and catalog metadata for accounts and providers that can serve them.

OpenAI provider account modes

Provider ID	Route	Credential	Behavior
openai	Codex login	Main + added Codex accounts	Pool by default; optional Direct mode
openai-apikey	OpenAI API	API key/key pool	No Codex account routing

• Pool includes the main Codex login and added accounts, with affinity, quota, cooldown, and failover.
• Direct short-circuits pool state and uses only the current caller/main-login bearer.
• Fresh installs and configs with no persisted mode default to Pool. Change the mode on the dashboard's Providers page; model ids stay bare in either mode.
• The legacy public provider id chatgpt is hidden after migration. The original config is retained once at ~/.opencodex/config.json.pre-openai-tiers-v2.bak; restore it with cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json.
• Current configs use openaiProviderTierVersion: 2. Earlier v1 three-provider configs migrate automatically into the single openai row.
• The API tier includes Pro virtual models (gpt-5.6-sol-pro, gpt-5.6-terra-pro, gpt-5.6-luna-pro). At the wire level, each rewrites to its base model with reasoning.mode: "pro".
• Its catalog is fixed to eight ids: gpt-5.5, gpt-5.6, Sol/Terra/Luna, and the three corresponding Pro virtual ids. There is no generic gpt-5.6-pro alias.
• Compact requests keep the selected tier but send the base model without a reasoning object.
• Official API metadata is 1,050,000 context tokens and 922,000 max input tokens.

Use gpt-5.6-sol for the configured openai account mode and openai-apikey/gpt-5.6-sol for the API key. Codex-login and API credentials never fall through to one another.

Open Codex Auth in the dashboard to add accounts and choose which account should handle the next Codex session. opencodex keeps these behaviors:

• Existing sessions keep affinity. A thread id is bound to the selected account and reused on later turns, so a long request or a mobile/SSH-attached session keeps using the same account.

• New sessions can auto-route. When auto-switch is enabled, opencodex compares the hottest known quota window across 5h, weekly, and 30d usage, then picks a lower-usage eligible account for new sessions once the active account crosses the threshold.

• Quota lookup is built in. The dashboard can refresh all account quotas in one click, and the request log labels pool traffic with non-PII account ordinals.

• Failures fail closed. Token failures mark reauthentication instead of falling back to another credential silently; 429 quota responses put the account in cooldown and can fail over future work to another eligible pool account.

• Use any LLM with Codex. 5 protocol adapters cover Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough, and every OpenAI-compatible Chat Completions endpoint — that's 40+ providers out of the box.

• Use any LLM with Claude Code too. The same daemon serves the Anthropic Messages API (/v1/messages + count_tokens): ocx claude launches Claude Code fully wired, and routed models appear in its native /model picker via gateway model discovery (claude-ocx-<provider>--<model> aliases, Claude Code 2.1.129+). Configure slots and model maps on the dashboard's Claude page.

• Use any LLM with GitHub Copilot App too. Point Copilot's Model providers at http://127.0.0.1:10100/v1 — OpenCodex serves OpenAI-compatible GET /v1/models and POST /v1/chat/completions so routed models sync into the app. See docs/github-copilot-app.md.

• Pool ChatGPT accounts safely. Keep existing Codex threads on one account while new sessions can auto-pick a lower-usage account from the pool, with quota refresh and non-PII request labels.

• Log in once, skip the API key. OAuth support for xAI, Anthropic, and Kimi means you can authenticate with your existing account. Tokens auto-refresh. Or forward your codex login, paste an API key, or use ${ENV_VAR} references — your call.

• Works everywhere Codex does. Injects into Codex CLI, TUI, App, and SDK automatically. Routed models show up in Codex's model picker just like native ones.

• History-safe injection. On local installs the proxy points Codex's own built-in openai provider at itself via a single openai_base_url line — new threads keep their native provider tag, so ongoing chat history is never remapped and an unclean shutdown can't hide it. (Threads re-tagged by older versions are migrated back once on the first start; remote/LAN binds use a dedicated provider entry instead, since they need an API-key header.)

• Delegate to the right model. Feature up to five routed or native models in Codex's subagent picker from the dashboard or config — route complex tasks to a reasoning model, fast tasks to a cheap one. On the v2 multi-agent surface (GPT-5.6 Sol/Terra) the proxy injects compact, schema-agnostic delegation guidance: an eligible preferred sub-agent model and effort (injectionModel / injectionEffort), the configured intersection of Codex's picker-visible, v2-compatible, priority-sorted first five with available effort ladders, and the fork_turns rules that let cross-model spawn_agent calls apply their overrides. Known limitation: when a native parent spawns a routed child, the task body can currently arrive backend-encrypted and be lost (#92) — use the v1 surface for reliable cross-provider delegation. Want your own wording? Set injectionPrompt with {{model}} / {{effort}} / {{roster}} placeholders.

• Prepare for preview-gated OpenAI rollouts. GPT-5.6 Sol/Terra/Luna entries preserve the upstream effort ladders. Direct/Multi use the 372k Codex contract; OpenAI API and OpenRouter use 1.05M metadata when upstream access is available.

• Give any model superpowers. Non-OpenAI models get real web search and image understanding via a gpt-5.4-mini sidecar over your ChatGPT login.

• Generate images natively. Codex's standalone image_gen tool uses POST /v1/images/generations for generation and POST /v1/images/edits for edits; it is separate from the hosted Responses image_generation tool.

• See what's happening. The web dashboard shows providers, OAuth status, model selection, and a live request log, including cached/cache-write token counts when upstream reports them — no more guessing why a request failed.

• Runs in the background. Install as a system service (launchd / systemd / Task Scheduler) and forget about it. On macOS/Linux the proxy starts at login; on Windows the default Task Scheduler backend starts at logon (windowless), or use ocx service install --native for a real Windows service that starts at boot.

• Clean exit, zero residue. ocx stop (or the dashboard's Stop button) shuts down the proxy, stops the background service if one is installed, and restores Codex to its original configuration. Plain codex works exactly as it did before — no leftover config, no orphaned processes.

Provider	Adapter	Auth
OpenAI (ChatGPT login)	openai-responses	forward (no 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 (experimental)	cursor	dashboard/local config; live transport; unsafe native local exec is opt-in
Ollama Cloud + 17-provider catalog	openai-chat	key
Ollama / vLLM / LM Studio (local)	openai-chat	key (usually blank)
Any OpenAI-compatible endpoint	openai-chat	key

Plus DeepSeek, Groq, OpenRouter, Together, Fireworks, Cerebras, Mistral, Hugging Face, NVIDIA NIM, MiniMax, Qwen Cloud, Tencent Cloud Coding Plan, SiliconFlow, and more. See the full list with ocx init or in the provider docs.

Cursor support is a staged experimental bridge: it appears in ocx init and the dashboard Add Provider picker as a local config with Cursor's static public model catalog. Live HTTP/2 transport is enabled when a Cursor access token is configured. Cursor server-driven native read/write/delete/ls/grep/shell/fetch execution is disabled by default because it bypasses Codex's approval and sandbox path. Request text such as a Codex danger-full-access sandbox marker never authorizes native local exec; set nativeLocalExec: "on" only for trusted local experiments where every data-plane caller is trusted. nativeLocalExec: "codex-sandbox" is accepted for backwards compatibility but fails closed like off; legacy unsafeAllowNativeLocalExec: true remains an explicit operator opt-in. MCP, screen recording, and computer-use are exposed through executor hooks; when no local executor is configured, opencodex returns typed no-executor results instead of policy-blocking the request. Cursor OAuth and live model discovery are enabled for the experimental Cursor adapter.

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 <provider>          # OAuth login (xai, anthropic, kimi, cursor, ...)
ocx logout <provider>          # remove a stored login
ocx account <list|current|use> # list/switch accounts & API-key pools (masked; also refresh/auto-switch/remove/add-key)
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

Autostart: service vs shim

opencodex has two ways to auto-start the proxy:

| ocx service / ocx service install | ocx codex-shim install
---|---|---
How | OS service manager (launchd / systemd / schtasks) | Wraps script launchers for codex; real codex.exe is left untouched
When | Always running after login | On-demand — runs ocx ensure when codex is launched
Restart | Auto-restarts on crash | Starts once per codex invocation
Codex updates | Unaffected | Repairs on next ocx codex-shim install or ocx update
Remove | ocx service uninstall | ocx codex-shim uninstall

Use the service for always-on proxy (recommended for development machines). Use the shim for lightweight, on-demand proxy startup without a background daemon. Shim autostart is enabled by default and can be disabled from the GUI dashboard. If the configured proxy port is already busy, ocx start automatically picks another free local port and updates Codex to use it.

Before removing the npm package, clean up local state:

ocx uninstall
npm uninstall -g @bitkyc08/opencodex

ocx uninstall stops the proxy, removes any installed service, removes the Codex shim, restores native Codex config/catalog/history, and deletes ~/.opencodex.

Config lives at ~/.opencodex/config.json. If the file cannot be parsed (e.g. truncated or manually broken JSON), opencodex backs it up to config.json.invalid-<timestamp>, prints a warning, and falls back to defaults — so your original file is never silently lost.

Here's a typical multi-provider setup:

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

Provider entries can also annotate routed catalog metadata and output defaults. Use contextWindow for a provider-wide Codex-visible context cap, modelContextWindows for model-specific caps, and modelInputModalities for model-specific catalog input hints such as ["text"] or ["text", "image"]. For OpenAI-compatible chat providers whose upstream default response budget is too small, set defaultMaxOutputTokens or per-model modelMaxOutputTokens; explicit max_output_tokens from the client still wins, and unset configs still omit max_tokens. Context values cap live /models metadata; they never raise a smaller live context window. The bundled GPT-5.6 Sol/Terra/Luna fallback metadata uses a 1,050,000-token context window for OpenAI API key and OpenRouter catalog entries; it does not bypass upstream preview access. See the configuration reference for the full field list.

GLM-5.2 1M context via Z.AI: through the openai-chat adapter, both glm-5.2 and glm-5.2[1m] work — opencodex strips the trailing [1m] suffix before sending the request, since OpenAI-compatible endpoints reject the bracketed id (Z.AI 400 code 1211). The [1m] suffix is a Claude-Code / Anthropic-endpoint convention; to use it natively, point the anthropic adapter at Z.AI's coding base (https://api.z.ai/api/coding/paas/v4). Set the 1M context window via the model catalog (modelContextWindows), not the model name.

Local models work too. Point opencodex at any OpenAI-compatible server running on your machine:

{
  "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 transport is off by default. Set "websockets": true only if you want Codex to advertise and use the Responses WebSocket path instead of HTTP/SSE.

By default opencodex binds to 127.0.0.1 (loopback) and requires no extra authentication. If you set "hostname": "0.0.0.0" to expose the proxy on the LAN, opencodex requires a bearer token to protect both the management API (/api/*) and the data-plane (/v1/responses, /v1/images/generations, and /v1/images/edits):

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

The proxy refuses to start without this variable when binding beyond loopback. If you install a background service for LAN access, export the same variable before ocx service install so the service manager receives it. Clients (scripts, remote machines) must include the token in every request:

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

The token is compared in constant time to prevent timing attacks.

opencodex automatically remaps Codex resume history so old OpenAI chats and opencodex-created project threads stay visible in Codex App while the proxy is active. opencodex records the original provider/source metadata in ~/.opencodex/codex-history-backup.json. ocx stop / ocx restore restores backed-up OpenAI rows to OpenAI, and ejects any remaining opencodex user threads to OpenAI as well so native Codex does not try to resume a thread whose provider no longer exists in config.toml.

If you tested an older development build where syncResumeHistory already remapped history before backup support existed, you can also run the explicit recovery command:

ocx recover-history --legacy-openai

See the Configuration reference for every field.

The public docs — install, providers, routing, sidecars, Codex integration, Codex App model picker, and CLI/config reference — are built from docs-site/ and published to lidge-jun.github.io/opencodex.

Maintainer source-of-truth notes live under structure/. Historical investigations remain under docs/. Contributor setup lives in CONTRIBUTING.md, and security reporting guidance lives in 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 remains an alias for bun run dev:proxy for compatibility. In a source checkout, the proxy API exposes /healthz, /v1/responses, POST /v1/images/generations, POST /v1/images/edits, and /api/*; GET / serves the packaged dashboard only after bun run build:gui has produced gui/dist. While hacking on the dashboard, run the frontend separately:

See Contributing.

opencodex is an independent, community-maintained project and is not affiliated with or endorsed by OpenAI, Anthropic, or any other provider.

Some providers — notably Anthropic (Claude) — may suspend or restrict accounts that route API traffic through third-party proxies. Use at your own risk (UAYOR). Before connecting a provider, review its Terms of Service to confirm that proxy-based access is permitted. The opencodex maintainers are not responsible for any account actions taken by upstream providers.

MIT