codex-provider-switcher

英文 | Chinese simplified

A small local operations script for switching Codex Desktop App / Codex CLI between the default OpenAI provider and configurable third-party providers/models. The built-in default supports DeepSeek through Moon Bridge.

This is not an official OpenAI, DeepSeek, or Moon Bridge project. It only switches local Codex configuration files and manages local helper processes such as Moon Bridge.

Why

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

codex-toggle automates that workflow.

Features

• Switch Codex back to OpenAI / GPT.
• Switch Codex to third-party models through a local provider registry.
• Built-in DeepSeek through Moon Bridge defaults when no registry file exists.
• Explicitly select deepseek-v4-pro or deepseek-v4-flash.
• Add more providers/models by editing ~/.codex/codex-providers.yml.
• 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 provider config back to its baseline file.

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.

Additional third-party providers/models can be registered in:

~/.codex/codex-providers.yml

Requirements

• macOS
• Codex Desktop App and/or Codex CLI
• Node.js 18+
• Go 1.25+
• Moon Bridge cloned locally
• DeepSeek API key
• yq v4 when using a custom provider registry

Default expected Moon Bridge location:

~/Documents/ai_tools/moon-bridge

You can override it with:

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

Install yq if you want to use ~/.codex/codex-providers.yml:

brew install yq

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 baseline Codex configs:

~/.codex/config.openai.toml
~/.codex/config.deepseek.toml
~/.codex/codex-providers.yml

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"

codex-providers.yml is optional. If it does not exist, codex-toggle uses built-in defaults for OpenAI, Moon Bridge, deepseek-v4-pro, and deepseek-v4-flash.

Create an editable registry from the built-in defaults:

codex-toggle init-config

You can also start from:

examples/codex-providers.example.yml

Commands

codex-toggle status
codex-toggle doctor
codex-toggle list
codex-toggle init-config
codex-toggle use deepseek-pro
codex-toggle provider openai
codex-toggle openai
codex-toggle deepseek
codex-toggle deepseek-pro
codex-toggle deepseek-flash
codex-toggle logs 50
codex-toggle sync-deepseek
codex-toggle sync moonbridge
codex-toggle start
codex-toggle start moonbridge
codex-toggle stop
codex-toggle stop moonbridge
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

Or use the generic model/alias command:

codex-toggle use deepseek-flash
codex-toggle use deepseek-v4-pro

List configured providers and models:

codex-toggle list

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