A lightweight macOS menu bar proxy for connecting custom model providers to OpenAI Codex.
Intercepts Codex's Responses API calls and translates them to any upstream provider's Chat Completions API — works with DeepSeek, OpenRouter, local models, and more.
Install · Quickstart · Features · Configuration · Build from Source · Contributing
English · 中文
OpenAI Codex CLI connects to a fixed set of providers by default. If you want to use DeepSeek, OpenRouter, a local model, or any other OpenAI-compatible API, there's no built-in way to do it.
CodexAdaptor sits between Codex and your chosen provider, automatically translating the wire protocol so Codex "thinks" it's talking to OpenAI — while your requests actually go wherever you want.
Download the .dmg from Releases, drag CodexAdaptor to Applications, and launch it. The app lives in your menu bar — no terminal required.
Requires macOS 14+ and Swift 5.9+.
git clone https://github.com/panando/CodexAdaptor.git
cd codex-adapter
./build.shThe script builds the release binary, creates a .app bundle, and packages a .dmg in one step. Output appears in the project root.
- Launch CodexAdaptor — it appears as an icon in your menu bar
- Click the icon → Configure to open the settings window
- Go to Providers tab → click + to add a provider (name, base URL, API key)
- Add models to the provider (model slug must match the upstream API exactly)
- Go to Server tab → select your provider — this writes the config to
~/.codex/config.toml - Click "Start Service" — the proxy begins listening on
127.0.0.1:15721 - Launch Codex — it connects through the proxy automatically
Add as many providers as you need — DeepSeek, OpenRouter, SiliconFlow, local models, or any OpenAI-compatible API. Switch between them from the Server tab without editing config files manually.
Transparently converts between Codex's Responses API and the upstream provider's Chat Completions API. Supports both streaming and non-streaming responses.
Handles thinking/reasoning parameters across different providers with per-provider configuration:
- Thinking parameter:
thinking(DeepSeek/Kimi/GLM),enable_thinking(SiliconFlow/Qwen),reasoning_split(MiniMax), or auto-detect - Effort mapping: Maps Codex's effort levels to provider-specific values (e.g., DeepSeek's
max↔ OpenRouter'sxhigh) - Output normalization: Converts
reasoning_content,reasoning_details, orreasoningfields into a unified format for Codex
Via CDP (Chrome DevTools Protocol) injection into the Codex Electron app:
- Plugin Entry Unlock: Force the Plugins navigation button visible for all auth modes
- Plugin Marketplace Unlock: Expand marketplace plugin listings under API Key mode
- Force Plugin Install: Unblock disabled install buttons for restricted plugins
Built with SwiftUI — not Electron. Runs as a lightweight menu bar app with:
- Start/stop service with one click
- Configuration window with sidebar navigation
- Real-time log viewer with filtering and export
- Bilingual UI (English / Chinese)
- Writes
~/.codex/config.tomlwith the correctbase_url,model_provider,wire_api, and bearer token - Creates automatic backups before every config change (
config.toml.bak.codexadaptor) - Generates per-provider model catalog files that Codex reads to populate its model selector
All configuration is managed through the app's GUI. Files are stored under ~/.codex/:
| File | Purpose |
|---|---|
~/.codex/config.toml |
Codex main config — rewritten automatically when you switch providers |
~/.codex/providers.json |
CodexAdaptor metadata — upstream URLs, reasoning configs, model catalogs |
~/.codex/<provider-id>-model-catalog.json |
Per-provider model list for Codex's model selector |
~/.codex/config.toml.bak.codexadaptor |
Automatic backup before each config change |
~/.codex/logs/proxy.log |
Application logs |
Codex CLI
│
▼ (Responses API)
┌─────────────────────┐
│ CodexAdaptor │
│ 127.0.0.1:15721 │
│ │
│ ┌───────────────┐ │
│ │ Hummingbird │ │ ← HTTP proxy server
│ │ Server │ │
│ └───────┬───────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ SSE │ │ ← Protocol translation
│ │ Transformer │ │ (Responses ↔ Chat Completions)
│ └───────┬───────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ CDP │ │ ← Plugin injection into
│ │ Injector │ │ Codex Electron app
│ └───────────────┘ │
└─────────┬───────────┘
│
▼ (Chat Completions API)
Upstream Provider
(DeepSeek / OpenRouter / ...)
- macOS 14.0+ (Sonoma)
- Swift 5.9+
- Xcode Command Line Tools
./build.shProduces:
CodexAdaptor.app— macOS application bundleCodexAdaptor-<version>.dmg— disk image for distribution
swift build # Debug build
swift build -c release # Release build
swift test # Run testsContributions are welcome! Here's how to get started:
- Fork this repository
- Create a feature branch (
git checkout -b feature/my-feature) - Make your changes
- Build and test (
swift build && swift test) - Commit and push
- Open a Pull Request
Please open an issue first for large changes to discuss the approach.
This project builds on ideas and code from the following projects:
- cc-switch — The original local proxy approach for routing Codex to custom providers. CodexAdaptor's proxy architecture and config management are heavily inspired by cc-switch.
- EchoBird — Additional proxy patterns and provider abstraction techniques that informed CodexAdaptor's design.
- CodexPlusPlus — CDP-based plugin injection implementation for the Codex Electron app. CodexAdaptor's plugin entry unlock and force install features are ported from CodexPlusPlus's Rust/Tauri codebase.
APIBypass — A universal API proxy toolkit for bypassing provider restrictions. CodexAdaptor is planned to be integrated into APIBypass as a specialized module in the future. Follow the APIBypass project for updates.