Connect Codex to Routescope

Point Codex to Routescope and run it with your Routescope API Key and quota.

This guide keeps only the most reliable setup paths. First-time users do not need to understand API protocols. Follow the steps and fill in the listed values.

Choose a Setup Method

Choose one of the two methods below. New users should use method 1.

If you are not comfortable with the command line, use CC Switch graphical setup.

Codex is an OpenAI coding tool. You can run it from a terminal with codex; since July 2026, it is also included in the ChatGPT desktop app. This page explains how to connect Codex to Routescope. It is not the same as normal ChatGPT web chat.

Before You Start

Both setup methods require the following items.

In Token Management, the record you create is the token: a key with permission settings. The sk- string inside it is the secret, or API Key. That is the value you copy into configuration.

1. Routescope Secret (API Key)

1. Sign in to the Routescope console.
2. Open Token Management.
3. Click Add Token.
4. Use a token name such as Codex.
5. Configure quota, allowed models, IP restrictions, and expiration if needed.
6. After saving, click Copy Access Code in the token list.

You will get a string that starts with sk-, for example:

sk-xxxxxxxxxxxxxxxx

Keep the entire string, including the sk- prefix.

2. An Available Model ID

1. Open Routescope Model Plaza.
2. Find a model that your token is allowed to use.
3. Copy the full model ID.

Do not copy only the display name, and do not blindly reuse model examples from other guides.

3. Install Codex

CC Switch and manual setup only change configuration. Codex itself must already be installed. Check it from a terminal first:

• Windows: search for and open PowerShell.
• macOS: open Applications -> Utilities -> Terminal.
• Linux: open your system terminal.

Run:

codex --version

If you see a version number, continue. If the command is not found, install Codex using either option below.

Option A: Install Codex CLI

The examples in this guide are based on the CLI.

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

macOS, Linux, or WSL:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

If Node.js is already installed, this also works on any system:

npm install -g @openai/codex

Option B: Install the ChatGPT Desktop App

Since July 9, 2026, OpenAI has merged Codex into the unified ChatGPT desktop app, with Chat, Work, and Codex in one app for Mac and Windows. If you already have the new ChatGPT desktop app, Codex is included and you do not need a separate CLI install.

After installing the CLI, close and reopen the terminal, then run codex --version. For desktop, open the app directly. If installation still fails, see the official Codex CLI setup guide.

Two reminders:

1. Chat and Work in the ChatGPT desktop app use the official OpenAI account path, not Routescope. Only Codex uses the Routescope setup described here.
2. The desktop app currently does not provide a UI to switch custom provider models. It uses the model line in config.toml, so set that line to your Routescope model ID.

Fixed Values You Will Use

Method 1: Use CC Switch (Recommended)

CC Switch is a graphical configuration tool. You do not need to create config.toml manually.

For the full flow, see the "Configure Codex" section in Connect CC Switch to Routescope.

Summary:

1. Install and open CC Switch.
2. Select Codex at the top.
3. Click the + button in the upper-right corner.
4. Choose Application-specific provider.
5. Choose Custom configuration under preset providers.
6. Enter the full secret (sk-...).
7. Set API endpoint to https://api.routescope.ai/v1. Codex must include /v1.
8. Expand Advanced Options and set Upstream format to Responses (native).
9. In the config.toml editor, replace the model name on the model = line with your model ID.
10. Save, then click Enable on the Routescope provider card.

After this, skip to How to Confirm It Works.

Method 2: Manual config.toml Setup

This method requires opening a terminal and creating two configuration files. If that feels hard, switch to method 1.

Before starting, confirm codex --version shows a version number. If not, return to "Before You Start -> Install Codex".

Step 1: Open config.toml

Codex configuration lives in the .codex folder in your user directory. The main configuration file is config.toml.

Windows

Run these in PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"

If Notepad asks whether to create a new file, choose yes.

macOS

Run these in Terminal:

mkdir -p ~/.codex
touch ~/.codex/config.toml
open -e ~/.codex/config.toml

The file opens in TextEdit.

Linux

Run:

mkdir -p ~/.codex
nano ~/.codex/config.toml

After pasting, press Ctrl + O to save, press Enter to confirm, then press Ctrl + X to exit.

Step 2: Paste the config.toml Configuration

If this is a new file, paste the full content below:

model_provider = "OpenAI"
model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.routescope.ai/v1"
wire_api = "responses"
requires_openai_auth = true

Replace only one kind of value: change gpt-5.4 in both the model and review_model lines to your real model ID. Use the same model in both places for first-time setup.

Do not change these lines:

base_url = "https://api.routescope.ai/v1"
wire_api = "responses"
requires_openai_auth = true

The OpenAI label is just a configuration name. Copy it as is.

Check:

• base_url is https://api.routescope.ai/v1, includes /v1, and has no extra trailing /.
• model and review_model have both been changed to your real model ID.
• Quotes, equals signs, and square brackets are still present.

Save and close the file.

Step 3: Create auth.json for the Secret

The secret does not go into config.toml. It goes into a separate auth.json file in the same .codex folder.

Windows PowerShell:

notepad "$env:USERPROFILE\.codex\auth.json"

macOS:

touch ~/.codex/auth.json
open -e ~/.codex/auth.json

Linux:

nano ~/.codex/auth.json

Paste this into auth.json:

{
  "OPENAI_API_KEY": "sk-your-full-secret"
}

Replace sk-your-full-secret with the full secret you copied earlier, keeping the sk- prefix.

The field name must be OPENAI_API_KEY. Do not change it. This is only where Codex reads the secret from; the value inside is your Routescope secret.

Check:

• The file is named auth.json, not auth.json.txt.
• The secret keeps the sk- prefix.
• Quotes and braces are still present.

Save and close the file.

Step 4: Start Codex

Close the previous terminal, open a new one, and run:

codex

Normally, this opens the Codex chat interface.

How to Confirm It Works

Asking the AI to say "I am connected to Routescope" is not enough. It may only repeat your words.

Confirm it this way:

1. Send a normal question in Codex, for example:

   Describe yourself in one sentence.

2. After receiving a response, open the Routescope console.

3. Go to Operation Records or Call Records.

4. Find a new record from the same time.

5. Confirm the call status is successful.

6. Confirm the model, token usage, and billing look normal.

Codex is truly connected only when Codex replies normally and Routescope shows the corresponding successful request.

Optional quick check: if you only want to test whether the endpoint and secret work, run this in a terminal after replacing your-full-sk-secret:

curl https://api.routescope.ai/v1/models -H "Authorization: Bearer your-full-sk-secret"

If it returns a model list, the endpoint and secret are valid. This does not prove Codex chat works; the Operation Records check above is still the source of truth.

Troubleshooting

401 or 403

This is usually a secret or token permission issue. Check:

1. The secret is complete.
2. The sk- prefix is present.
3. The token is not disabled, expired, or out of quota.
4. The model is allowed by the token.
5. IP restrictions are not blocking the request.
6. OPENAI_API_KEY in auth.json contains the Routescope secret, not an OpenAI key from somewhere else.

After changes, close the terminal and restart Codex.

404

This is usually an endpoint typo. Confirm config.toml contains:

base_url = "https://api.routescope.ai/v1"

Do not omit /v1, and do not add an extra trailing /.

model not found or Model Unavailable

The model / review_model value does not exist, or your token is not allowed to use it.

1. Return to Routescope Model Plaza.
2. Copy the full model ID allowed by your token.
3. Replace model and review_model in config.toml.
4. Save, close the terminal, and restart Codex.

Codex Replies, but Routescope Has No Operation Record

This usually means the current request did not use Routescope, or old local settings pointed it elsewhere.

1. Confirm base_url in config.toml is https://api.routescope.ai/v1.

2. Confirm you reopened the terminal after changing configuration.

3. If you previously set Codex environment variables, clear them:

   unset OPENAI_BASE_URL OPENAI_API_KEY

   On Windows, run this in Git Bash.

4. Send another request and refresh Operation Records.

Authentication Still Fails (Advanced)

In rare cases, you may need to change requires_openai_auth in config.toml to false. This is advanced troubleshooting; contact Routescope support before changing it.

Still Stuck

Do not keep guessing. Send support a screenshot of the step where you are stuck, with the secret masked. You can also switch to CC Switch graphical setup.

Advanced (Optional)

Most users can skip this section after setup succeeds.

Use an Environment Variable Instead of auth.json

If you know how to configure system environment variables, you can add this line under [model_providers.OpenAI]:

env_key = "OPENAI_API_KEY"

Then set your secret in a system environment variable named OPENAI_API_KEY. Codex will read it from there, so auth.json is not needed. New users do not need this.

config.toml Field Meanings

Only set different model and review_model values after confirming your token can access multiple models.

References

• Codex CLI setup guide
• Routescope: Get Base URL and API Key
• Routescope: Operation Records
• Routescope: CC Switch