CodexSplit: a local gateway that adds third-party models to Codex Desktop without touching the native path

The rename from OpenCodex is still visible in the tree

CodexSplit is the renamed continuation of a project previously called OpenCodex, and the README flags the rename explicitly rather than quietly doing it. Product, source releases and the GitHub repository use CodexSplit, while historical commits, older tags, some internal directories and compatibility identifiers may still say OpenCodex. That is honest and useful to know, because searching the repository for the old name still turns up results.

The repository tree confirms it at the top level. Alongside `src/` and `src_v2/`, which suggests the v2 rewrite landed beside the original rather than replacing it in place, there is a `scripts/opencodex-codex` path referenced by the build script and a set of planning documents: `RELEASE_NOTES_v2.0.0-beta.1.md`, `SESSION_PROGRESS.md`, `TEST_FLOW.md`, `THIRD_PARTY_NOTICES.md` and `VOICE_GUIDE.md`. A `SESSION_PROGRESS.md` at the root of a released project is unusual, and it tells you something about how the work is being managed.

The declared language is TypeScript, but the tree is not pure TypeScript. There is `wake_word_listener.py` at the root for voice wake words and a `voice/` directory, so the speech side crosses into Python.

Four independent paths, and the table that separates them

The most valuable page in this README is the one that warns you not to conflate the gateway, the Desktop Bridge and the official account pool. A four row table maps each scenario to its actual path, and it is worth reproducing because the distinctions are the whole design.

An ordinary main session with an official GPT account goes through Codex's native OpenAI provider and native egress, without passing through any third party provider adapter. A GPT-Live conversation stays on Codex's native Live and Realtime path, with the account drawn from the configured official pool. A third party model main session goes through the CodexSplit local gateway, which listens on `127.0.0.1:8765` by default, and only models you added, imported and applied travel that way. And a `spawn_agent` or delegated task picks its model from the agent routing table while the parent session stays on its original path.

The consequences are spelled out. With the gateway switched off, third party models disappear but the official path is unaffected. With Live active, enabling the gateway does not turn the parent conversation into a third party model; only a subtask that Live explicitly delegates routes through agent selection.

For anyone evaluating this, that table is the whole product. A tool that merged these paths would be simpler and would also be harder to reason about when something routes wrong.

The four components, and what each one actually does

The README defines four things that are easy to confuse by name.

The gateway handles providers, API keys, the model catalogue, protocol adaptation and third party requests, and when started on its own it listens on `127.0.0.1:8765`. The Desktop Bridge is a process level switch inside Codex Desktop: turning it on lets Desktop see and use the pending third party models, and toggling it restarts Desktop. The CodexSplit app is the control centre and gateway management interface, and the README is explicit that opening the app does not restart Codex, that a first launch or ordinary launch should not quietly take over Desktop. The GPT account pool manages official ChatGPT and Codex login accounts only, and is not a third party API key pool.

The App distinction matters more than it sounds, because a tool that silently restarts your editor when you open its own window is a tool people uninstall. The README also separates restarting the gateway from toggling the Bridge: a plain gateway restart should not switch the Bridge off, and should not delete saved configuration.

One more detail is operationally useful. If the Bridge is on and you stop the gateway, the saved Bridge state stays on, so returning to native mode means using the Bridge switch or the restore native Codex action rather than assuming killing the process reverted it.

Provider setup, key pools and OAuth subscription import

Adding a provider follows a fixed sequence in the gateway screen. Pick a preset such as DeepSeek, MiniMax, Qwen, Z.ai, Kimi or OpenCode Go, fill in an API Key, or add an endpoint and base URL for a custom OpenAI compatible provider. Then fetch the available models, choose one, and select either the `Chat` or the `Responses` protocol according to upstream capability. Saving puts the model into a pending list rather than activating it. You test each model, and only then press the restart action that applies the model menu to Desktop.

That staging is deliberate. Saving never restarts Codex, which means a broken endpoint cannot take your working setup down at the moment you save it.

Namespacing is handled: a provider and model become a stable identifier such as `deepseek/model-name`, so two providers offering the same model name do not collide. The README is also careful about what the presets mean, stating they carry public endpoint and model metadata only and do not represent an official partnership, permission or availability guarantee. The preset catalogue is credited to the CC Switch project's `codexProviderPresets.ts` file, with a note that authentication, proxying, subscription and promotion code was not copied.

Multiple keys per provider get a credential pool with three scheduling modes: pin the current key, rotate in order, or skip a key that fails. Credentials live in the macOS Keychain with the frontend showing only a mask and a status. HTTP 401 and 403 mark a key invalid, 429 puts it in cooldown, and unavailable credentials are skipped during scheduling.

OAuth import is the path for local subscriptions. You add an OAuth provider, complete the official client login or capture the existing session, and then, importantly, click import models even after the login state is detected, because a discovered login file does not mean the model is available to Desktop.

Running from source, and what the build script reveals

Running from source is five commands, and they are stated plainly in the README:

git clone https://github.com/AITabby/codexsplit.git
cd codexsplit
npm install
npm run build
npm start

The management page then sits at a local dashboard URL on port 8765. The README notes that `npm start` from source defaults to the same port, and that the DMG manages its own local control service.

The `build` script in `package.json` is worth reading on its own, because it is a shell command that does several unusual things. It clears `dist`, runs `tsc`, renames the emitted `dist/server.js` to `dist/gateway-entry.js`, writes a new one line `server.js` that imports the renamed entry, copies `package.json` into `dist`, then copies the `scripts/voice` directory and two shell scripts into the output and marks them executable. The `postinstall` hook runs `tsc` as well, so a plain `npm install` already produces compiled output.

The dependency list explains the integration surface: `@modelcontextprotocol/sdk` for MCP, `node-pty` for spawning processes in a pseudo terminal, `ws` for the WebSocket and WebRTC signalling bridge, `undici` and `https-proxy-agent` for HTTP and proxied egress, `@bufbuild/protobuf` for protocol buffer handling, and `sql.js`, a SQLite compiled to WebAssembly, for local storage without a native module. Tests run with the Node built in test runner via `node --test test/*.test.mjs`.

The v2.0.0 release notes mention 42 of 42 targeted Live and bridging tests passing, plus DMG checksum and app signature verification, with the build being locally ad-hoc signed and not notarised by Apple.

Release cadence, platform coverage and the documentation language

Three releases are published, and they cluster. v2.0.0-beta.1 on 2026-08-09 was the first public beta under the CodexSplit name, deliberately shipped as both a source tag and a macOS Apple Silicon DMG so Windows development could continue from the same source. v2.0.0 landed later the same day on 2026-08-11 and fixed a real bug: third party models causing GPT-Live to produce no text, hang on stop and drag down other sessions. It also fixed the Live WebSocket and WebRTC signalling bridge, protocol negotiation, stop propagation and session release. v2.0.1 followed the same day, fixing slow session list loading, a list that did not refresh after deletion, repeated deletion, and reading an old API key index after a DMG upgrade.

Platform coverage is the caveat. The current release is v2.0.1 as a macOS Apple Silicon DMG with source. Windows is on v1.2.0 as an EXE with no Windows source, and Linux is not released. The beta notes state plainly that the macOS only features, namely local subscription import, the Voice Bar and CDP integration, do not represent equivalent Windows functionality.

The DMG bundles its own Node.js and a speech runtime, so an ordinary user needs no separate Node, npm, Homebrew or .NET SDK. It is also not signed or notarised by Apple, which means Gatekeeper may block the first launch and you have to allow it in system settings under privacy and security. That is the single most likely reason a first attempt appears to fail.

The repository is not archived and the last push was on 2026-09-07. The README is Chinese first with a linked English section, and the screenshots are annotated in Chinese, so an English-only reader will be translating while they set up. The `mobile/` directory and `wake_word_listener.py` suggest mobile and voice work in progress that the README barely covers.

Editorial conclusion

CodexSplit is worth evaluating if your problem is specifically that Codex Desktop will only talk to OpenAI and you want it to talk to something else, because the project's whole design is organised around keeping those two paths apart rather than merging them. The gateway, the Desktop Bridge switch, the API key pools and the agent router are all separate mechanisms with separate triggers, and the README spends more space explaining which is which than explaining any of them. Two constraints are worth knowing before you start. Documentation is Chinese first with an English section that is thinner, so expect to translate. Platform coverage is uneven: v2.0.1 ships a macOS Apple Silicon DMG, Windows is on v1.2.0 as an EXE with no Windows source, and Linux is not released. The last push was on 2026-09-07 and v2.0.1 was published on 2026-08-11.

Frequently asked questions

Official sources

1. AITabby/codexsplit on GitHub
2. Issues
3. README
4. Releases