# opencodex: a local proxy that lets Codex and Claude Code run any LLM > opencodex translates the Codex Responses API into whatever your provider speaks, so Claude Code, Codex, Claude Desktop and Grok Build can drive Claude, Gemini, Grok, DeepSeek, Ollama or any OpenAI-compatible endpoint. It is a routing layer with a web dashboard, an account pool for Codex auth, and a policy note about provider terms that is worth reading before you set it up. **lidge-jun/opencodex** — Universal provider proxy for OpenAI Codex & Claude Code, use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code. - Repository: https://github.com/lidge-jun/opencodex - Website: https://opencodex.me/ - Stars: 16,448 · Forks: 1,239 - Language: TypeScript - License: MIT - Published: 2026-08-08 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/lidge-jun-opencodex ## What opencodex actually routes, and who it is for Codex and Claude Code each expect a particular API shape. Codex speaks the Responses API; Claude Code expects Anthropic-style messages. If you want either client to talk to DeepSeek, Gemini, Grok, GLM, Kimi, Qwen, or a local Ollama server, something has to sit in the middle and translate. That is the whole job of opencodex, and the README describes it as "a lightweight local proxy that translates Codex's Responses API into whatever your provider speaks, streaming, tool calls, reasoning tokens, images, in both directions." The audience is narrow but real. You are already committed to Codex CLI, the Codex App, the Codex SDK, Claude Code, Claude Desktop, or Grok Build, and you want the model behind the picker to be something other than the default. The README lists 40+ built-in providers plus any OpenAI-compatible endpoint. If you are happy with the vendor's own models and have no reason to switch, this project adds a process, a config file, and a dashboard for no benefit. The value only appears when the model choice matters more than the client choice. ## How the proxy translates requests in both directions The mechanism is a local HTTP service. `ocx start` launches the proxy and a dashboard on localhost:10100, and the client points at that address instead of the vendor endpoint. Requests arriving in Codex's Responses format are rewritten into the target provider's format; the response stream is rewritten back, including tool calls, reasoning tokens, and images. The README says this works "in both directions," which matters because tool-call round trips are where naive proxies break. The second mechanism is a ChatGPT account pool for Codex auth. Accounts are added in the dashboard, and their 5h, weekly, and 30d quotas can be refreshed there. Under quota routing, new sessions can be sent to the lowest-usage healthy account; round-robin and fill-first use their own policies. Existing threads normally stay pinned to the account that started them, so long SSH, tmux, or mobile sessions do not jump accounts mid-conversation. The README is explicit that this affinity is not absolute: quota re-evaluation, failover, account exclusion, affinity expiry, or 401/403 and 429 recovery can rebind a thread. Accounts can also be given a selection order, so one account (the README names a Codex Desktop login as the usual case) is only reached once the others are drained. A third layer is combos: one virtual model id that fails over or round-robins across providers by weight. There is also a sub-agent surface, which lets routed models appear in Codex's sub-agent picker with v1/v2 surface control and fallback chains. ## Installing opencodex and running your first routed session The README's quick start is two commands. The npm package is `@bitkyc08/opencodex`, Node 18 or newer is required, and the Bun runtime is bundled automatically on install, so you do not need a separate Bun install. ```bash npm install -g @bitkyc08/opencodex ocx start ``` `ocx start` brings up the proxy and the dashboard. The README says to open http://localhost:10100 and configure providers, models, and accounts in the web dashboard. `ocx gui` re-opens the dashboard at any time without restarting the proxy. To run it detached, the README gives `ocx service` as the background variant. If you want the setup to write your config and wire Codex for you, there is an interactive path: ```bash ocx init ``` The README states that `ocx init` writes `~/.opencodex/config.json` and wires Codex, and that it never starts the proxy. Order does not matter for starting, but headless commands such as `ocx provider add` and `ocx combo set` talk to the live proxy and exit nonzero when it is unreachable. `ocx status`, `ocx doctor`, and `ocx health` report running state, so those are the commands to run when a provider add fails silently. There is a Docker path as well, with a `compose.yaml` that publishes `${OPENCODEX_BIND_ADDRESS:-127.0.0.1}:${OPENCODEX_PORT:-10100}:10100` and persists two named volumes, `ocx-state` and `codex-state`, mounted at `/home/bun/.opencodex` and `/home/bun/.codex`. The container runs read-only with `cap_drop: ALL` and `no-new-privileges:true`. Note the comment in that file: a custom `CODEX_HOME` also requires a matching writable volume target, and the Dockerfile notes that the two homes have incompatible `auth.json` formats and are deliberately not combined. For agent-driven installs, the README points at `AGENTS_INSTALL.md` and states that an interactive `ocx start` may ask once whether to star the repository, that the CLI suppresses this prompt for agent-driven runs, and that the API refuses them with `403 agent_consent_required`. ## Where opencodex is the wrong tool The account-pool feature carries a warning the README puts in its own block. It says account pooling is "for routing and operational resilience only," that it does not guarantee protection from provider rate limits, enforcement, suspension, or other account actions, and that opencodex does not endorse using additional accounts to circumvent provider limits or sharing credentials between people. Users are responsible for complying with each provider's terms. If your reason for installing this is to spread load across accounts to avoid a rate limit, the project itself tells you it will not protect you from the consequence. That is a policy boundary as much as a technical one. Thread affinity is the second limitation, and it is subtler because it is presented as a feature. The README says existing threads "normally" retain affinity but lists five events that can rebind them: quota re-evaluation, failover, account exclusion, affinity expiry, and 401/403 or 429 recovery. A long-running session that depends on a specific account's context can therefore move underneath you. The word "normally" is doing real work in that sentence. Platform support is broad (macOS with launchd, Linux with a systemd user unit, Windows with Task Scheduler or an opt-in native service via `--native` and WinSW), so this is less a limitation than a maintenance surface: three service managers means three sets of failure modes, and the README does not document rollback for any of them. ## How opencodex differs from a client-side model switcher Tools like Ccswitch change which account or endpoint a client points at; they operate on the client's configuration. opencodex sits between the client and the provider and rewrites the protocol. That difference decides which one you want. If your target provider already speaks the API your client expects, a switcher is enough and you avoid running a local service. If it does not, a switcher cannot help, because the request body itself is the wrong shape. The other comparison point is a plain OpenAI-compatible gateway. Those generally assume OpenAI's chat completions format on both sides. opencodex's stated purpose is the Responses API and Anthropic-style clients, plus the pieces that come with that: reasoning tokens, images, tool calls, and the account pool. The cost of that specificity is that the proxy is in the request path for every call, so a proxy bug looks like a model bug. The README's `ocx doctor` and `ocx health` commands exist for exactly that reason. ## Licence, maintenance, and what an upgrade costs you The repository is MIT licensed, which permits commercial and private use, modification, and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence, but it says nothing about the providers you route to; their terms are separate agreements, and the README's own policy note puts that responsibility on the operator. On maintenance: the repository is not archived, and the last push was on 2026-08-28. The release list shows v2.34.0 on 2026-08-27, v2.35.0 on 2026-08-28, and a preview build, v2.36.0-preview.20260829, on 2026-08-28. The cadence visible in those three entries is days, not months. Upgrade cost is mostly configuration drift. The README's source-install section states that running from source tracks the latest `dev` branch and that memory ownership patches, runtime GC improvements, and unreleased fixes land there before the npm package. That means the source path and the npm path are not the same software, and a bug you cannot reproduce on npm may be fixed or introduced only on `dev`. The Dockerfile pins its base image by digest, so a container rebuild is reproducible until you change that pin. The repository also ships `compose.yaml` with named volumes for state, which means an upgrade that changes config shape has persistent state to migrate, not just a binary to swap. ## Conclusion Adopt opencodex if you already use Codex or Claude Code and want to point it at a local Ollama model, a cheaper provider, or a pooled set of accounts without changing your editor workflow. Do not adopt it to work around a provider's rate limits: the README's own provider-policy note says account pooling is for routing and operational resilience only and does not guarantee protection from enforcement or suspension. Before you commit, verify two things on your own machine: that Node 18 or newer is available so the bundled Bun runtime installs, and that the dashboard at localhost:10100 reaches the provider you actually intend to use. ## FAQ ### What is opencodex? It is a local proxy that translates Codex's Responses API into whatever provider you point it at, so Codex CLI, the Codex App, the Codex SDK, Claude Code, Claude Desktop, and Grok Build can run Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama, or any other LLM. It ships with a web dashboard on localhost:10100 and can also pool ChatGPT accounts for Codex auth. ### Is Codex a part of ChatGPT? The repository does not describe Codex's relationship to ChatGPT. It treats Codex as a client that speaks the Responses API and can be pointed at opencodex, and it separately offers a ChatGPT account pool for Codex auth, which implies ChatGPT and Codex accounts are related but does not explain how. ### Can I use OpenAI Codex for free? The repository does not state whether Codex itself is free. What it does document is that you can route Codex to a local Ollama server or another provider, and that accounts added to the pool have 5h, weekly, and 30d quotas you can refresh in the dashboard. ### What can you do with OpenAI Codex? The README does not enumerate Codex's own capabilities. It describes opencodex as the layer that changes which model answers inside Codex, including routing to sub-agents on other models and defining combos that fail over across providers. ### Is Codex better than ChatGPT? The repository makes no comparison between Codex and ChatGPT. It documents opencodex as a proxy that sits in front of Codex and other clients, and it notes that account pooling does not guarantee protection from provider rate limits or enforcement. ## Sources - [Official documentation](https://opencodex.me/) - [Official README](https://github.com/lidge-jun/opencodex#readme) - [Project repository](https://github.com/lidge-jun/opencodex) - [Release notes](https://github.com/lidge-jun/opencodex/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lidge-jun-opencodex