MIT-licensed, Apple-notarized macOS app (universal binary) that switches Codex between Official OpenAI and custom / third-party APIs in one click — DeepSeek and other Chinese LLM quick presets, a local Chat-Completions→Responses adapter, and conversations never lost.
DSH integration
Ecosystem-related
Author-claimed
Safety audit
Unaudited
Last verified
2026-08-28
License
MIT
01What can it help you accomplish?
Switch Codex between Official OpenAI and your own custom / third-party API in one click
A saved configuration where both provider routes stay in `~/.codex/auth.json` and `config.toml`; the default route changes on save and saved conversations keep their provider/model attribution
Codex desktop & CLI users who want a reliable one-click way to route Codex to DeepSeek / other Chinese LLM providers while keeping official OpenAI login
Bridge Chat-Completions-only endpoints into the Responses protocol Codex speaks
A local adapter (documented at `127.0.0.1:17638`) that auto-translates Codex's Responses requests into Chat Completions; endpoints natively supporting `/responses` connect directly
Users of DeepSeek / Kimi / Qwen and other providers whose APIs only expose `/chat/completions`
02How to install into DeepSeek Harness
Prerequisites
- macOS — the app is a universal binary (Intel + Apple Silicon)
- Download `Codex-Switch-vX.Y.Z.dmg` from GitHub Releases
Installation steps
- 01
Download `Codex-Switch-vX.Y.Z.dmg` from GitHub Releases
- 02
Double-click the DMG, drag `Codex Switch.app` into Applications, then launch it from Applications (do not run it straight from the DMG window or Downloads)
- 03
In the app, pick the API provider (Official OpenAI or custom / third-party), paste the API key, and save — the built-in probe validates the endpoint first
Verify the integration
- The app launches from Applications without an 'untrusted developer' prompt — it is Developer ID signed and Apple-notarized
03DSH integration and capability boundaries
Ecosystem-level: the README documents no DeepSeek Harness interface. This standalone macOS utility edits Codex's `~/.codex/auth.json` and `config.toml` to switch between Official OpenAI and custom / third-party providers — one-click presets for Chinese LLM providers (including DeepSeek) plus a local Chat-Completions→Responses adapter.
Parallel provider switching (Official / custom)
choose the API provider in the app and save→top-level `model_provider` flips between `custom` and `openai`; both provider blocks and CLI profiles stay in `config.toml`
only rewrites `~/.codex/auth.json` and `config.toml`; never retags saved conversationsChat adapter (Responses → Chat Completions bridge)
provider endpoints that only support `/chat/completions` (e.g. DeepSeek / Kimi / Qwen)→a local proxy translating Codex's Responses requests into Chat Completions; native `/responses` endpoints connect directly
starts a local proxy service on the machineQuick presets for Chinese LLM providers
one of the built-in presets — DeepSeek, Kimi, Zhipu GLM, Qwen, Doubao (Volcano Engine), Baidu Wenxin, MiniMax, StepFun, or a manually-filled third-party / relay API→base URL and model auto-filled; you only paste the API key
Proxy repair for official OpenAI mode
HTTP/mixed proxy URL (e.g. `http://127.0.0.1:7897`)→writes the proxy into Codex's shell env, the current macOS `launchd` env, and a login-restore LaunchAgent; fixes new-task Reconnecting in official mode
proxy only applies in official OpenAI mode — auto-off when switched to custom API, auto-restore per your settings when switching back
04Who is it for? When not to use it?
Good for
- Codex desktop & CLI users who want a reliable one-click way to route Codex to DeepSeek / other Chinese LLM providers while keeping official OpenAI login
- Users of DeepSeek / Kimi / Qwen and other providers whose APIs only expose `/chat/completions`
Not for
- Launch the app from Applications only — running it from the DMG window or the Downloads folder triggers macOS App Translocation, which breaks the built-in proxy helper.
05Compatibility, maintenance and safety notes
- Codex Switch is a macOS app — the README describes a universal binary (Intel + Apple Silicon).
- Launch the app from Applications only — running it from the DMG window or the Downloads folder triggers macOS App Translocation, which breaks the built-in proxy helper.
- Don't ask Codex itself to edit its provider config in chat — the README warns it's unreliable; use this app to switch instead.
- The desktop model picker is driven by Codex itself; custom-provider models show under a 'custom' label — a Codex limitation. Requests still route to the selected provider correctly, and the CLI allows full model-ID control.
MIT · actively maintained (latest release v0.7.21, 2026-08-27)
06Frequently asked questions
Is Codex Switch a native DeepSeek Harness plugin?
The README documents no DeepSeek Harness (dsh) interface. Codex Switch is a standalone macOS utility that edits Codex's `~/.codex/auth.json` and `config.toml`. Its relevance to the DeepSeek ecosystem is via one-click presets for DeepSeek and other Chinese LLM providers, so Codex can be routed to them reliably.
How do I point Codex at DeepSeek's API?
Pick the DeepSeek quick preset (presets also cover Kimi, Zhipu GLM, Qwen, Doubao, Baidu Wenxin, MiniMax, StepFun) — it auto-fills the base URL and model, so you only paste your API key. On save the app probes `/responses` then `/chat/completions` and errors immediately if the endpoint is unreachable.
Will switching providers lose my conversation history?
No. Normal switching only rewrites `~/.codex/auth.json` and `config.toml` and never retags saved conversations. If an old adapter left an illegal message ID, it backs up first, then fixes the `item_...` → `msg_...` prefix once, keeping history and session ownership intact.
My provider only supports Chat Completions, not the Responses protocol — will Codex still work?
Yes. Turn on the chat adapter and Codex Switch starts a local proxy (the CLI notes document `127.0.0.1:17638`) that bridges Codex's Responses requests to Chat Completions; endpoints that natively support `/responses` are connected directly. `NO_PROXY` keeps `localhost,127.0.0.1,::1` so the local adapter is not pushed through your proxy.
Does using this tool affect my official OpenAI login?
No. Official OpenAI and your custom provider stay configured in parallel — switching only changes the default route. You can optionally skip ChatGPT OAuth and use API-key mode instead.
07Related DSH workflows
deepwiki-rs
by sopaco
Turn code into clarity. Generate accurate technical docs and AI-ready context in minutes—perfectly structured for human teams and intelligent agents.
dsh-purge
by yujunzhixue
A jailbreak layer for DeepSeek Harness that unlocks every model and lets you swap custom prompts per model (default tuned for the domestic "XiaoMaJiang" model).
dsh-plugin-radar
by adamplatin123
An ecosystem radar for the DeepSeek Harness (dsh) plugin community that auto-discovers thousands of candidate plugins and runs continuous k8s-level validation, publishing the results as a browsable plugin catalog.
picgo-core
by picgo
:zap:The ultimate image uploading engine. Both CLI & API supports.
08Data and sources
It turns hand‑editing `~/.codex/auth.json` and `config.toml` into one save: Official OpenAI and your custom provider bot…
It ships quick presets for popular Chinese LLM providers and can run a local adapter that bridges Chat‑Completions‑only…
This page is generated from the project’s public documentation, repository metadata and a structured parse of DSH Plugins; last verified on 2026-08-28. Found an error? Submit a correction.
Best DeepSeek Harness Plugins
Twelve plugins worth installing first — picked from the whole catalog, across every category.