codex-provider-switcher

英文 | Chinese simplified

A small local operations script for switching Codex Desktop App / Codex CLI between the default OpenAI provider and a Moon Bridge based DeepSeek provider.

This is not an official OpenAI or DeepSeek project. It only switches local Codex configuration files and manages a local Moon Bridge process.

Why

Codex users may want to keep OpenAI models as the primary path and use DeepSeek as a fallback when quota, cost, or availability becomes a constraint. Manual switching is error-prone because it usually involves editing ~/.codex/config.toml, starting or stopping Moon Bridge, and restarting Codex Desktop App.

codex-toggle automates that workflow.

Features

• Switch Codex back to OpenAI / GPT.
• Switch Codex to DeepSeek through Moon Bridge.
• Explicitly select deepseek-v4-pro or deepseek-v4-flash.
• Start and stop Moon Bridge automatically.
• Restart Codex Desktop App after config changes.
• Provide status, doctor, and logs commands for troubleshooting.
• Sync the currently validated DeepSeek config back to ~/.codex/config.deepseek.toml.

Architecture

Codex Desktop App / Codex CLI
  -> ~/.codex/config.toml
  -> Moon Bridge at http://127.0.0.1:38440/v1
  -> DeepSeek API

OpenAI mode uses the normal Codex config. DeepSeek mode uses a custom provider named moonbridge.

Requirements

• macOS
• Codex Desktop App and/or Codex CLI
• Node.js 18+
• Go 1.25+
• Moon Bridge cloned locally
• DeepSeek API key

Default expected Moon Bridge location:

~/Documents/ai_tools/moon-bridge

You can override it with:

export MOON_BRIDGE_DIR="/path/to/moon-bridge"

Installation

Clone this project or copy the script:

mkdir -p ~/.local/bin
cp scripts/codex-toggle ~/.local/bin/codex-toggle
chmod +x ~/.local/bin/codex-toggle

Ensure ~/.local/bin is in your shell path:

grep -q 'export PATH="$HOME/.local/bin:$PATH"' ~/.zshrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Prepare Config Files

You need two baseline Codex configs:

~/.codex/config.openai.toml
~/.codex/config.deepseek.toml

config.openai.toml should be your normal OpenAI / GPT Codex configuration.

config.deepseek.toml should be generated by Moon Bridge and should include:

model = "moonbridge"
model_provider = "moonbridge"
model_catalog_json = "/Users/<you>/.codex/models_catalog.json"

[model_providers.moonbridge]
name = "Moon Bridge"
base_url = "http://127.0.0.1:38440/v1"
wire_api = "responses"

Commands

codex-toggle status
codex-toggle doctor
codex-toggle openai
codex-toggle deepseek
codex-toggle deepseek-pro
codex-toggle deepseek-flash
codex-toggle logs 50
codex-toggle sync-deepseek
codex-toggle start
codex-toggle stop
codex-toggle restart-app

Recommended Usage

Use OpenAI as the default path:

codex-toggle openai

Use DeepSeek Flash for daily fallback tasks:

codex-toggle deepseek-flash

Use DeepSeek Pro for heavier reasoning or long-context coding tasks:

codex-toggle deepseek-pro

Check actual routing:

codex-toggle logs 50

Look for:

actual_model=deepseek-v4-pro
actual_model=deepseek-v4-flash

Known Codex Desktop Limitation

Codex Desktop App may recognize the custom provider but fail to show all third-party models from model_catalog_json in the model picker. In that case, the reliable workaround is to set the model name directly in ~/.codex/config.toml.

codex-toggle deepseek-pro writes:

model = "deepseek-v4-pro"

codex-toggle deepseek-flash writes:

model = "deepseek-v4-flash"

Mobile Remote Codex

When using ChatGPT mobile app to operate Codex running on a Mac, the actual execution still happens on the Mac host. If the Mac host is currently switched to DeepSeek / Moon Bridge, mobile-triggered tasks are expected to follow that local provider configuration. This combination should be treated as a compatibility scenario to verify before production use.

Suggested verification:

codex-toggle deepseek-flash
codex-toggle logs 50

Then trigger a small task from mobile and verify Moon Bridge logs show actual_model=deepseek-v4-flash.

Safety Notes

• Do not commit API keys.
• Keep config.yml with your DeepSeek API key out of public repositories.
• This script restarts Codex Desktop App and may interrupt unsaved work.
• Always verify with codex-toggle status and codex-toggle logs after switching.

License

MIT