codex-switch

中文说明

codex-switch is a tiny zero-dependency CLI for switching Codex between:

• API key mode
• OAI subscription login mode

It swaps these active Codex files:

• ~/.codex/config.toml
• ~/.codex/auth.json

with saved mode files:

• API mode: config.toml.api and auth.json.api
• OAI mode: config.toml.oai and auth.json.oai
• Compatibility files: config.toml.openai and auth.json.openai are also supported

Install

One-line install:

curl -fsSL https://raw.githubusercontent.com/Catherina0/codex-switch/main/install.sh | bash

If codex-switch is not found after installation, add this to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Then restart the terminal or run:

source ~/.zshrc

You can also install from a clone:

git clone https://github.com/Catherina0/codex-switch.git
cd codex-switch
make install

Quick Start

First, save the mode you are currently logged in with:

codex-switch init

The tool will ask:

Which mode are the current active Codex files using?
  1) oai - ChatGPT/OAI subscription login
  2) api    - API key login
Choose [1/oai, 2/api]:

Then log in with the other Codex mode and run the same command again:

codex-switch init

Check that both modes are ready:

codex-switch doctor

Daily switching:

codex-switch api
codex-switch oai

After a successful switch, codex-switch restarts Codex automatically so the new auth files are loaded.

Before switching, codex-switch tries to identify the current active mode and writes the current active config.toml and auth.json back to that mode's saved files. This keeps refreshed OAI/ChatGPT tokens from being overwritten by an old auth.json.oai snapshot on the next switch.

The automatic save preserves saved custom provider definitions, so OAI mode can still open conversations that were created with an API provider.

Skip the automatic save when needed:

codex-switch --no-auto-save api
CODEX_SWITCH_AUTO_SAVE_CURRENT=0 codex-switch oai

Skip the restart when needed:

codex-switch --no-restart api
CODEX_SWITCH_RESTART=0 codex-switch oai

Check current status:

codex-switch status

Non-Interactive Setup

For scripts or users who already know the current active mode:

codex-switch init api
codex-switch init oai

Overwrite an existing saved mode:

codex-switch init api --force
codex-switch init oai

The older openai command name remains an alias, but new usage should prefer oai.

Custom Codex Directory

By default, Codex files live in ~/.codex.

Use CODEX_HOME:

CODEX_HOME=/path/to/.codex codex-switch status

Or use --codex-home:

codex-switch --codex-home /path/to/.codex status
codex-switch --codex-home /path/to/.codex oai

Paths with spaces are supported.

Safety

Before switching modes, codex-switch backs up the active files with a timestamp:

config.toml.backup-YYYYMMDD-HHMMSS-before-api
auth.json.backup-YYYYMMDD-HHMMSS-before-api

It never prints the contents of config.toml or auth.json.

Commands

codex-switch status
codex-switch init
codex-switch init api
codex-switch init oai
codex-switch switch api
codex-switch switch oai
codex-switch --no-restart api
codex-switch --no-auto-save api
codex-switch api
codex-switch oai
codex-switch doctor
codex-switch --version
codex-switch --help

Test

make test

The test suite covers:

• interactive initialization
• non-interactive initialization
• switching both modes
• automatic Codex restart after switching
• timestamped backups
• .oai mode files and .openai compatibility files
• missing mode failure behavior
• paths with spaces
• CODEX_HOME
• --codex-home

Package

make dist

Release artifacts are written to dist/.

Uninstall

rm -f "$HOME/.local/bin/codex-switch"

Or, from a clone:

make uninstall