Skip to content

README_EN.md

Latest commit

 

History

History
152 lines (116 loc) · 5.97 KB

README_EN.md

File metadata and controls

152 lines (116 loc) · 5.97 KB

Codex Model Switcher

License Python macOS GitHub Release

中文 | English

A macOS menubar tool for switching OpenRouter models in Codex Desktop with one click.

Why

When Codex Desktop uses a custom provider (e.g. OpenRouter), its main UI does not show a model selector. Switching models requires manually editing ~/.codex/config.toml and restarting the app. This tool wraps that workflow into a single menubar click.

Screenshots

Menubar Switch to GPT-4o Switch to Sonnet 4.6

Quick Start

Option A: Download pre-built app (Recommended)

No Python environment required — download and run:

  1. Go to the Releases page and download the latest Codex.Switcher.app.zip
  2. Unzip and drag Codex Switcher.app into /Applications
  3. Set the environment variable (if not already configured): 
    export OPENROUTER_API_KEY="sk-or-..."
  4. Double-click the app — the model switcher appears in the menubar

Tip: On first launch macOS may show "cannot verify the developer". Go to System Settings → Privacy & Security and click "Open Anyway".

Option B: Run from source

1. Clone & install

git clone https://github.com/GitBiao/codex-switcher.git
cd codex-switcher
pip3 install -r requirements.txt

2. Set environment variable

export OPENROUTER_API_KEY="sk-or-..."

3. Run

# Run the module directly
python3 -m codex_switcher.app

# Or use the launcher script (auto-installs deps)
./run.sh

4. Build macOS .app (optional)

make app
# Output: dist/Codex Switcher.app

Features

  • One-click model switching -- pick a model from the menubar, config is updated and Codex restarts automatically
  • Reasoning Effort control -- choose from low / medium / high / xhigh
  • Dashboard -- native pywebview window for visual management of models, provider, and default parameters
  • Model enable/disable -- disabled models are hidden from the menubar; toggle anytime in the Dashboard
  • macOS .app bundle -- build a standalone app via py2app, double-click to run
  • Quick edit -- open config.toml directly to edit the Codex configuration
  • Auto-start -- supports macOS LaunchAgent for login startup

Project Structure

codex-switcher/
├── codex_switcher/              # Core Python package
│   ├── __init__.py              # Version (__version__)
│   ├── app.py                   # Menubar app entry point
│   ├── config_manager.py        # config.toml read/write
│   ├── dashboard.py             # Dashboard panel (pywebview)
│   ├── models.py                # Model preset management
│   ├── process_manager.py       # Codex process lifecycle
│   └── switcher_config.json     # Model preset config
├── docs/                        # Documentation
│   ├── installation.md / installation_en.md
│   ├── usage.md / usage_en.md
│   ├── configuration.md / configuration_en.md
│   └── autostart.md / autostart_en.md
├── public/                      # Screenshots
│   ├── desc_gpt4o.png
│   ├── desc_sonnet4.6.png
│   └── switcher_main.png
├── resources/                   # App resources
│   ├── icon.icns                # macOS app icon
│   └── icon_1024.png            # Hi-res icon source
├── main.py                      # py2app entry point
├── setup.py                     # py2app build config
├── Makefile                     # Build commands (make app / make clean)
├── LICENSE                      # Apache License 2.0
├── README.md                    # Documentation (Chinese)
├── README_EN.md                 # Documentation (English)
├── requirements.txt             # Python dependencies
└── run.sh                       # Launcher script

Documentation

Document Description
Installation Direct download, source install, environment variables, .app build
Usage Launch methods, menu operations, Dashboard, model switching
Configuration switcher_config.json & config.toml reference
Auto-start macOS LaunchAgent setup

Prerequisites

  1. macOS
  2. Codex Desktop installed at /Applications/Codex.app
  3. OPENROUTER_API_KEY environment variable set (Get API Key)
  4. Python 3.10+ only needed when running from source (the pre-built .app requires no Python)

Related Links

Star History

Star History Chart

License

This project is licensed under the Apache License 2.0.