Use Codex with SeedRouter via CC Switch

About this document

This document explains how to use CC Switch's Universal Provider feature to connect the OpenAI Codex command-line tool to a specified API gateway and make the configuration take effect.

Supported versions: CC Switch v3.16.x and later.

Sources: the user manual and source code of the CC Switch official repository. The software is updated frequently; if the product interface does not match this document, follow what the app actually shows.

Terminology

Term	Description
Codex	A command-line AI coding assistant from OpenAI. After installation, start it by running the `codex` command in a terminal.
CC Switch	A cross-platform desktop configuration management tool for the service endpoints and credentials of tools such as Codex, Claude Code, and Gemini CLI. CC Switch itself does not provide AI capabilities; it only generates and switches configuration files.
Provider	The party that provides model inference. It can be an official service from a model vendor, or a self-hosted or purchased API gateway.
API Key	A secret string used for authentication, usually starting with `sk-`.
Universal Provider	A CC Switch feature. One configuration can be synced to Claude Code, Codex, and Gemini CLI at the same time. It applies to gateways that support multiple API protocols (for example, NewAPI).
Application-specific provider	A provider configuration that applies only to a single tool, as opposed to a Universal Provider.

Before you begin

System requirements

Operating system	Minimum version	Architecture
Windows	Windows 10	x64
macOS	macOS 12 (Monterey)	Intel (x64) / Apple Silicon (arm64)
Linux	Ubuntu 22.04 / Debian 11 / Fedora 34 and equivalent versions	x64 / ARM64

You also need Node.js 18 or later. See "Task 1" for the installation steps.

Information to obtain in advance

Before you start configuring, obtain the following four items from your API service provider. The configuration cannot be completed if any item is missing.

Item	Description	Example
API address (Base URL)	The gateway's service address	`https://seedrouter.net`
API Key	Authentication key	`sk-xxxxxxxxxxxx`
Model name	The model identifier used on the Codex side	`gpt-5.6-sol`
Protocol support	Whether the gateway supports the OpenAI Responses protocol	Supported / Not supported

Key point: The fourth item determines whether this document applies. In the configuration that the unified provider generates for Codex, the communication protocol is fixed as wire_api = "responses" and cannot be changed. If the gateway does not support the Responses protocol and only supports the Chat Completions protocol, you cannot use the unified provider. Use Solution F in the "Troubleshooting" section instead.

Open a terminal

Several parts of this document require you to run commands in a terminal. Open a terminal as follows:

Windows: Press Win + R, type powershell, and press the Enter key.
macOS: Press Command + Space, type terminal, and press the Enter key.
Linux: Use the terminal application included with your distribution.

Task 1: Install Node.js

About this task

Codex is distributed through npm, the Node.js package manager. Even if you use CC Switch's one-click installation method, you still need a Node.js runtime first.

Procedure

Visit the Node.js official website.
Download the installation package labeled LTS (Long Term Support). Do not download the Current version.
Run the installer and complete the installation with the default options. You do not need to change any configuration options.

If you are on macOS and already have Homebrew installed, you can also run brew install node in a terminal.
Close all current terminal windows, then open a new terminal window.
Run the following commands in order to verify the installation:
```
node --version
      npm --version
```

Results

Both commands output a version number (for example, v22.14.0 and 10.9.2), and the Node.js version is v18 or later. This indicates that the installation succeeded.

Note: If you see "is not recognized as an internal or external command" or "command not found", it is usually because you did not reopen the terminal window. Newly installed commands take effect only in a newly opened terminal session.

Task 2: Install CC Switch

About this task

CC Switch is free, open-source software and is distributed only through the following two channels:

Official website: ccswitch.io
GitHub releases page: farion1231/cc-switch Releases

Warning: Any "CC Switch" website or client that requires payment, a top-up, or account login credentials is not an official channel. Do not download or use it.

Procedure

Windows

Open the GitHub releases page and, in the Assets section under the latest release, find CC-Switch-v3.16.x-Windows.msi.
Download it and double-click to run the installer. Follow the prompts to complete the installation.

If nothing happens when you double-click it, the file is locked by a system security policy. Right-click the file, select Properties, and on the General tab, in the Security section at the bottom, check Unblock. Click OK, then run it again.

If you do not want to install it on the system, you can also download the no-install version, CC-Switch-v3.16.x-Windows-Portable.zip. Extract it and run CC-Switch.exe directly.

macOS

Use either of the following methods:

Method 1 (recommended if Homebrew is already installed): In a terminal, run
```
brew install --cask cc-switch
```
Method 2: Download CC-Switch-v3.16.x-macOS.dmg, double-click to open it, and drag the CC Switch icon into the "Applications" folder.

Note: The macOS version is code-signed and notarized by Apple. You can install and open it directly. The "developer cannot be verified" prompt does not appear, and no extra step to remove the quarantine is required.

Linux

Choose according to your distribution:

Debian / Ubuntu: Download the .deb package, then run

sudo dpkg -i CC-Switch-v3.16.x-Linux-*.deb
      sudo apt-get install -f

Arch Linux: paru -S cc-switch-bin
Other distributions: Download the .AppImage, run chmod +x to add execute permission, then run it directly.

Results

After you start CC Switch, the main window displays normally, and the CC Switch icon appears in the system tray area (bottom-right on Windows, right side of the menu bar on macOS). This means the installation succeeded.

On first launch, if you are prompted to import existing CLI tool configuration, importing is recommended. This saves the current configuration as a default provider and does not cause any configuration to be lost.

Task 3: Install Codex

About this task

You can install through the CC Switch graphical interface, or from the command line. Method A is recommended for first-time users.

Procedure

Method A: Install through CC Switch (recommended)

Start CC Switch.
Go to Settings > About.
In the Local Environment Check area, check the status of the Codex row.
If it shows not detected, click the Install button on the right side of that row.

Installation runs silently in the background. The button shows progress, and the version number refreshes automatically when it finishes.

Note: Later upgrades are also done in this interface. When a new version is detected, you can upgrade it individually, or click Upgrade All to process them in a batch.

Method B: Install from the command line

Open a terminal.
Run the following command:
```
npm install -g @openai/codex
```
If the download is too slow, you can use a mirror registry instead:
```
npm install -g @openai/codex --registry=https://registry.npmmirror.com
```
If you need to use the mirror registry long term, you can first run the following command once to set it globally:
```
npm config set registry https://registry.npmmirror.com
```

Results

After you close and reopen the terminal, run the following command:

codex --version

A version number in the output means the installation succeeded.

Note: Provider configuration is not complete yet. Running codex directly reports an error because valid credentials are missing. This is expected. Configuration is completed in Task 4.

Task 4: Create a unified provider

About this task

This task creates a unified provider configuration in CC Switch and syncs it to Codex’s provider list.

Procedure

Start CC Switch.
In the application switcher at the top, switch to Codex.

Switching to the Claude or Gemini panel also reaches the unified provider entry. The three share the same configuration.
Click the ＋ button in the upper-right corner to open the Add Provider panel.
At the top of the panel, select the Unified Provider tab.

Restriction: The OpenCode, OpenClaw, Hermes, and Claude Desktop panels do not support unified providers, and this tab is not shown on those panels. If you do not see the tab, switch to the Claude, Codex, or Gemini panel first.
Click Add Unified Provider.

Fill in the form fields as shown in the table below:

Field	How to fill in
Select preset type	When the gateway is NewAPI, select NewAPI. Otherwise, or if you are unsure, select Custom Gateway. The two have exactly the same fields; only the default values differ.
Name	A custom identifier, for example `NewAPI Gateway`. This name is shown on the Codex provider card.
API address	Enter the Base URL obtained in advance. For how to fill it in, see "API address handling rules" below.
API Key	Enter the key obtained in advance. You can click the eye icon on the right to toggle plain-text display.
Official website address	Optional. After you fill it in, you can jump to it directly from the provider card.
Remarks	Optional. It is recommended to record information such as the key source and validity period.
Enabled applications	Includes three switches: Claude Code, OpenAI Codex, and Gemini. You must turn on OpenAI Codex. If this gateway is also used by the other two tools, you can turn those on as well.
Model configuration > Codex > Model	Enter the model name obtained in advance, for example `gpt-5.6-sol`.
Model configuration > Codex > Reasoning Effort	Reasoning effort. The value is `low`, `medium`, or `high`. If you have no special requirements, enter `high`.

Note: The Unified Provider form does not provide a "Fetch Models" button. The model name must be entered manually and is case-sensitive.

Click Add.

Result

The interface shows "Unified Provider added and synced". At this point, CC Switch has created a provider card with the same name in Codex's provider list. If other apps were checked, cards are also created in the corresponding lists.

Key point: Syncing is not enabling. At this point the configuration has not yet been written to Codex's runtime configuration file. You must continue with Task 5.

API address handling rules

When CC Switch generates the configuration for Codex, it handles the API address you enter as follows:

Form of the address entered	Result
Bare domain with no path, for example `https://seedrouter.net`	Automatically completed to `https://seedrouter.net/v1`
Already ends with `/v1`, for example `https://seedrouter.net/v1`	Used as is
Contains another path, for example `https://api.example.com/openai`	Used as is; `/v1` is not appended

The criterion is: after /responses is appended to the processed address, the result must be an endpoint path the gateway can actually serve. Before entering it, confirm the full endpoint address with the service provider, then use the table above to determine what to enter. An incorrect address will cause requests to return 404.

Task 5: Enable the provider and make the configuration take effect

About this task

After the provider card is created, you must enable it manually before the configuration is written to Codex's configuration file. Codex does not support hot reloading of configuration. After you enable it, you must restart the terminal.

Procedure

Close the Add Provider panel.
In the app switcher at the top, switch to Codex.
In the provider list, find the card with the same name created in Task 4.
Click the Enable button on the card.

The card shows a blue border and a "Currently enabled" label, which means the configuration has been written.

Fully close the current terminal window, then open a new terminal window.

Key point: This means closing the entire terminal window, not exiting the codex process and then running the codex command again. How the change takes effect differs by tool:

Tool	How it takes effect after switching providers
Claude Code	Takes effect immediately; hot reload is supported
Gemini CLI	Takes effect immediately; the configuration is reread on each request
Codex	Close and reopen the terminal
OpenCode / OpenClaw	Close and reopen the terminal

In the new terminal, run:
```
codex
```
After it starts, enter a test sentence, for example "Hello, please briefly introduce yourself".

Result

The model returns a response normally, which means configuration is complete and Codex is connected to the specified gateway.

Reference: Generated configuration files

CC Switch follows the principle of minimal intrusion. After you enable a provider, the configuration is written directly to Codex's own configuration files. Even if CC Switch is uninstalled, Codex can continue to work normally.

The files involved are as follows. In these paths, ~ means the current user's directory: C:\Users\<username>\ on Windows, and /Users/<username>/ or /home/<username>/ on macOS and Linux.

~/.codex/auth.json — stores credentials:

{
        "OPENAI_API_KEY": "<API Key>"
      }

~/.codex/config.toml — stores the model and endpoint configuration:

model_provider = "cliproxyapi"
      model = "gpt-5.6-sol"
      model_reasoning_effort = "max"
      sandbox_mode = "workspace-write"
      model_context_window = 372000
      model_auto_compact_token_limit = 334800
      model_auto_compact_token_limit_scope = "total"
      service_tier = "priority"
      
      [model_providers.cliproxyapi]
      name = "SeedRouter"
      base_url = "https://seedrouter.net/v1"
      wire_api = "responses"
      requires_openai_auth = true
      experimental_bearer_token = "sk-xxxxxxxxxx"

CC Switch stores its own data in the ~/.cc-switch/ directory. The database file is cc-switch.db, automatic backups are in the backups/ subdirectory, and the 10 most recent copies are kept.

Maintenance operations

Modify configuration

When changing the API Key, model name, or service address:

Click the ＋ button and switch to the Unified Provider tab.
Click the edit icon on the target card.
Change the corresponding fields.

In edit mode, the bottom of the form provides a Configuration JSON Preview area, where you can confirm the actual content that will be written to each app before syncing.
Click Save and Sync.
Confirm the action in the confirmation dialog. This action overwrites the associated provider configurations in Claude, Codex, and Gemini.
Close and reopen the terminal.

Provider card actions

Action	Description
Sync	Manually push the current configuration to each associated app again, to fix inconsistent configurations
Copy	Create a copy from the current configuration, so you can set up a backup key
Edit	Modify the configuration content
Delete	Delete the unified provider, and also delete the associated provider cards it generated in Claude, Codex, and Gemini

Quick switch

Right-click the CC Switch icon in the system tray and click the target provider name directly in the Codex submenu to switch, without opening the main interface. After switching, you also need to restart the terminal.

Troubleshooting

A. Returns 401 or 403 authentication failure

Possible cause	Solution
Extra spaces or line breaks were included when copying the API Key	Copy and paste it again, and pay attention to the selection
The API Key has expired or the quota is exhausted	Confirm the key status with the service provider
The API Key does not match the API address	Check whether the two come from the same service

B. Returns 404 or says the endpoint does not exist

In most cases, the API address is incorrect after processing. Recheck it against "Task 4 > API address processing rules", and confirm the full endpoint address with the service provider.

C. No change after modifying the configuration

The terminal was not restarted. Fully close the terminal window and open it again. This is the most common problem when using Codex.

D. An environment variable conflict warning is shown at the top of the interface

The system has environment variables such as OPENAI_API_KEY. Environment variables take priority over configuration files and override the configuration written by CC Switch, causing requests to be sent to the wrong endpoint or to use the wrong key.

Handling steps:

Click Expand on the warning banner to view the conflicting variable’s name, value, and source.
Check the variables to delete, or click Select All.
Click Delete Selected and confirm.

CC Switch automatically backs up to ~/.cc-switch/env-backups/ before deletion. To restore, manually restore from the JSON files in that directory.

E. The terminal reports that the codex command does not exist

Possible cause	Solution
The terminal was not reopened after installation	Close all terminal windows and open them again
Node.js is not installed correctly	Return to Task 1 and verify whether `npm --version` outputs normally
The npm global directory is not on PATH	Reinstall using CC Switch’s Settings > About > Local Environment Check

F. The gateway only supports the Chat Completions protocol

The unified provider’s communication protocol is fixed to Responses, which does not apply in this scenario. You must use an app-specific provider instead.

In CC Switch, switch to the Codex panel and click the ＋ button.
Stay on the Codex Provider tab on the left. Do not switch to Unified Provider.
In the preset dropdown, select the corresponding service provider. DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Bailian, ModelScope, SiliconFlow, Doubao Seed, Xiaomi MiMo, Novita AI, and others are all Chat Completions-type presets.
After you select this type of preset, CC Switch automatically turns on the "Requires local route mapping" switch and configures the model mapping table. The local proxy performs the protocol conversion, and no manual setup is needed.
Enter the API Key, click Add, then enable this provider and restart the terminal.

G. Need to restore official account login

On the Codex panel, add a provider that uses the "OpenAI Official" preset.
Enable this provider and restart the terminal.
Complete authentication by following Codex’s own login flow.

Once this is done, you can switch freely between official login and third-party providers.

Selection reference: unified provider and app-specific provider

Use case	Recommended approach
A single gateway serves Claude Code, Codex, and Gemini CLI at the same time and supports the Responses protocol	Unified provider
Using only the Codex tool	Both work; the app-specific provider has a shorter configuration path
The gateway supports only the Chat Completions protocol	App-specific provider, used with a built-in preset
Each tool connects to a different service provider	App-specific provider, configured separately
You need to configure OpenCode, OpenClaw, or Hermes	App-specific provider; these three tools do not support the unified provider

Security notes

An API Key is as sensitive as account credentials. Do not send it in instant messaging tools, share screenshots of it, or submit it to a code repository.
Get the CC Switch installation package only from the CC Switch official website or the official GitHub repository.
If the device changes or you suspect the key has leaked, replace the key immediately.
CC Switch’s configuration export feature writes all provider information in plaintext to a .sql backup file. Keep exported files with care and avoid storing them in a shared directory.

Quick reference

1. Install Node.js                  nodejs.org, choose the LTS version
      2. Install CC Switch          ccswitch.io or GitHub Releases
      3. Install Codex              CC Switch > Settings > About > Local Environment Check > Install
      4. Create a unified provider  Switch to the Codex panel > ＋ > Unified provider > Add unified provider
                                    Fill in the name, API URL, and API Key
                                    Turn on the OpenAI Codex switch and fill in the model name
      5. Enable the provider        Codex panel > target card > Enable
      6. Restart the terminal       Close the terminal window completely, then open it again
      7. Verify                     Run the codex command and send a test message

When submitting problem feedback, please also provide a screenshot of the complete error message and the API URL entered in task 4 (redact the key portion) to shorten the troubleshooting cycle.

Configure Codex with a CC Switch Universal Provider

About this document

Terminology

Before you begin

System requirements

Information to obtain in advance

Open a terminal

Task 1: Install Node.js

About this task

Procedure

Results

Task 2: Install CC Switch

About this task

Procedure

Windows

macOS

Linux

Results

Task 3: Install Codex

About this task

Procedure

Method A: Install through CC Switch (recommended)

Method B: Install from the command line

Results

Task 4: Create a unified provider

About this task

Procedure

Result

API address handling rules

Task 5: Enable the provider and make the configuration take effect

About this task

Procedure

Result

Reference: Generated configuration files

Maintenance operations

Modify configuration

Provider card actions

Quick switch

Troubleshooting

A. Returns 401 or 403 authentication failure

B. Returns 404 or says the endpoint does not exist

C. No change after modifying the configuration

D. An environment variable conflict warning is shown at the top of the interface

E. The terminal reports that the codex command does not exist

F. The gateway only supports the Chat Completions protocol

G. Need to restore official account login

Selection reference: unified provider and app-specific provider

Security notes

Quick reference