This guide is for local Codex tasks. The “OpenAI API key” field on the ChatGPT sign-in screen is for the official service and has no XiuRouter Base URL field. Configure XiuRouter outside the app before opening ChatGPT.
Before you start
- Select an available key and exact model ID in XiuRouter console → Agent integrations. Copying a key command there inserts the selected key. Replace
YOUR_XIUROUTER_API_KEYandYOUR_MODEL_IDin this document yourself. - Choose your operating system below. Desktop setup requires ChatGPT; IDE setup requires the Codex extension published by OpenAI. Only CLI setup requires
codex --versionto print a version. - Back up existing configuration and keep other providers. Keep keys out of
config.toml, project repositories, and agent conversations.
macOS desktop
Skip this if ChatGPT is already installed. Otherwise, open the official link below and follow the installation instructions for your operating system. Continue with the configuration below before entering any XiuRouter key.
Press Command + Space, type Terminal, and press Return. Paste each command into that window and press Return.
1. Quit ChatGPT completely (macOS)
Choose ChatGPT → Quit ChatGPT in the menu bar, or press Command + Q. Closing the window is not enough.
2. Back up and open the config file (macOS)
Return to the command window and run the entire block below. It creates the folder and config file if needed, makes a timestamped backup, then opens the file in a text editor without overwriting the existing configuration.
mkdir -p "$HOME/.codex"
touch "$HOME/.codex/config.toml"
cp "$HOME/.codex/config.toml" "$HOME/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)"
open -e "$HOME/.codex/config.toml"The opened file is ~/.codex/config.toml. Its backup is in the same folder with a name starting with config.toml.backup-.
3. Set the model and provider (macOS)
Put the three lines below at the top of the opened file, before any section starting with [. If model, model_provider, or web_search already exists, update its value instead of adding a duplicate. Keep other settings.
model = "YOUR_MODEL_ID"
model_provider = "xiurouter"
web_search = "disabled"Replace YOUR_MODEL_ID with the exact model ID. The XiuRouter console fills its generated configuration after you select a model there. web_search disables OpenAI-hosted search for the initial test.
4. Add the XiuRouter configuration and save (macOS)
Put the entire block below at the end of the file. If [model_providers.xiurouter] already exists, replace it and its xiurouter.auth subtable if present, without adding duplicates. Keep other providers.
[model_providers.xiurouter]
name = "XiuRouter"
base_url = "https://router-api.xiu.ai/v1"
env_key = "XIUROUTER_API_KEY"
wire_api = "responses"Press Command + S in TextEdit, then close the file. If it uses rich text, choose Format → Make Plain Text first. Keep the filename config.toml.
5. Save the XiuRouter key (macOS)
Return to the command window, copy the entire block below, and run it. Copying in the XiuRouter console inserts the selected key. Replace YOUR_XIUROUTER_API_KEY in this document with your key.
launchctl setenv XIUROUTER_API_KEY "YOUR_XIUROUTER_API_KEY"Returning to the prompt with no output means the command finished. This lasts for the current sign-in session. After signing out or restarting the computer, repeat this step before opening ChatGPT.
6. Reopen ChatGPT (macOS)
Open ChatGPT from Applications or the Dock. Complete the first-use setup if shown, switch to Codex, and create a new local task. Existing tasks keep their previous connection.
7. Verify in a new local task (macOS)
Open a local folder in Codex, create a new task, and send the test message below. After the reply, return to XiuRouter console → Agent integrations → Check a real request and refresh usage. Confirm the selected model, /v1/responses, and a succeeded status.
Tell me the current folder name without changing any files.Opening ChatGPT alone does not prove the connection. Confirm the request in XiuRouter.
Windows desktop
Skip this if ChatGPT is already installed. Otherwise, open the official link below and follow the installation instructions for your operating system. Continue with the configuration below before entering any XiuRouter key.
Official Windows installation guide
Press the Windows key, search for PowerShell, and open Windows PowerShell as a regular user. Paste each command there and press Enter. Do not use Command Prompt, Git Bash, or WSL for these Windows desktop steps.
1. Quit ChatGPT completely (Windows)
Choose Quit in ChatGPT. If its icon remains in the system tray, right-click it and quit there too. Closing the window is not enough.
2. Back up and open the config file (Windows)
Return to the command window and run the entire block below. It creates the folder and config file if needed, makes a timestamped backup, then opens the file in a text editor without overwriting the existing configuration.
$xiuConfigDir = Join-Path $env:USERPROFILE ".codex"
New-Item -ItemType Directory -Force $xiuConfigDir | Out-Null
$xiuConfigFile = Join-Path $xiuConfigDir "config.toml"
if (-not (Test-Path $xiuConfigFile)) { New-Item -ItemType File $xiuConfigFile | Out-Null }
Copy-Item $xiuConfigFile "$xiuConfigFile.backup-$(Get-Date -Format yyyyMMdd-HHmmss)"
notepad $xiuConfigFileThe opened file is %USERPROFILE%.codex\config.toml. Its backup is in the same folder with a name starting with config.toml.backup-.
3. Set the model and provider (Windows)
Put the three lines below at the top of the opened file, before any section starting with [. If model, model_provider, or web_search already exists, update its value instead of adding a duplicate. Keep other settings.
model = "YOUR_MODEL_ID"
model_provider = "xiurouter"
web_search = "disabled"Replace YOUR_MODEL_ID with the exact model ID. The XiuRouter console fills its generated configuration after you select a model there. web_search disables OpenAI-hosted search for the initial test.
4. Add the XiuRouter configuration and save (Windows)
Put the entire block below at the end of the file. If [model_providers.xiurouter] already exists, replace it and its xiurouter.auth subtable if present, without adding duplicates. Keep other providers.
[model_providers.xiurouter]
name = "XiuRouter"
base_url = "https://router-api.xiu.ai/v1"
env_key = "XIUROUTER_API_KEY"
wire_api = "responses"Press Ctrl + S in Notepad, then close it. Keep the filename config.toml, not config.toml.txt.
5. Save the XiuRouter key (Windows)
Return to the command window, copy the entire block below, and run it. Copying in the XiuRouter console inserts the selected key. Replace YOUR_XIUROUTER_API_KEY in this document with your key.
$env:XIUROUTER_API_KEY = "YOUR_XIUROUTER_API_KEY"
[Environment]::SetEnvironmentVariable("XIUROUTER_API_KEY", $env:XIUROUTER_API_KEY, "User")Returning to the prompt with no output means the command finished. The key is set in this PowerShell window and saved in your Windows user environment. Keep using this window in the next step so ChatGPT receives the key immediately.
6. Open ChatGPT from the same PowerShell window (Windows)
Return to the PowerShell window where you saved the key and run the entire block below. It finds and opens ChatGPT installed from Microsoft Store. Make sure you have quit ChatGPT completely as described above; an existing process keeps its old environment.
$xiuChatGptPackage = Get-AppxPackage -Name OpenAI.Codex | Select-Object -First 1
if (-not $xiuChatGptPackage) { throw "ChatGPT was not found. Install it from Microsoft Store first." }
$xiuChatGptExe = Join-Path $xiuChatGptPackage.InstallLocation "app\ChatGPT.exe"
Start-Process -FilePath $xiuChatGptExeNo computer restart is needed for this setup. Complete the first-use setup if shown, switch to Codex, and create a new local task. You can use Start for later launches. If the app does not receive a new key, repeat the key and launch steps, or save your other work and restart the computer.
7. Verify in a new local task (Windows)
Open a local folder in Codex, create a new task, and send the test message below. After the reply, return to XiuRouter console → Agent integrations → Check a real request and refresh usage. Confirm the selected model, /v1/responses, and a succeeded status.
Tell me the current folder name without changing any files.Opening ChatGPT alone does not prove the connection. Confirm the request in XiuRouter.
Linux desktop
Skip this if ChatGPT is already installed. Otherwise, open the official link below and follow the installation instructions for your operating system. Continue with the configuration below before entering any XiuRouter key.
Official Linux installation guide
Open Terminal from the applications menu. Paste each command there and press Enter. The Linux desktop app is in preview; install the package for your distribution using OpenAI’s Linux installation guide.
1. Quit ChatGPT completely (Linux)
Choose Quit in ChatGPT and quit its tray icon if present. Closing the window is not enough.
2. Back up and open the config file (Linux)
Return to the command window and run the entire block below. It creates the folder and config file if needed, makes a timestamped backup, then opens the file in a text editor without overwriting the existing configuration.
mkdir -p "$HOME/.codex"
touch "$HOME/.codex/config.toml"
cp "$HOME/.codex/config.toml" "$HOME/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)"
nano "$HOME/.codex/config.toml"The opened file is ~/.codex/config.toml. Its backup is in the same folder with a name starting with config.toml.backup-.
3. Set the model and provider (Linux)
Put the three lines below at the top of the opened file, before any section starting with [. If model, model_provider, or web_search already exists, update its value instead of adding a duplicate. Keep other settings.
model = "YOUR_MODEL_ID"
model_provider = "xiurouter"
web_search = "disabled"Replace YOUR_MODEL_ID with the exact model ID. The XiuRouter console fills its generated configuration after you select a model there. web_search disables OpenAI-hosted search for the initial test.
4. Add the XiuRouter configuration and save (Linux)
Put the entire block below at the end of the file. If [model_providers.xiurouter] already exists, replace it and its xiurouter.auth subtable if present, without adding duplicates. Keep other providers.
[model_providers.xiurouter]
name = "XiuRouter"
base_url = "https://router-api.xiu.ai/v1"
wire_api = "responses"
[model_providers.xiurouter.auth]
command = "/bin/sh"
args = ['-c', 'cat "$HOME/.codex/xiurouter-api-key"']In nano, press Ctrl + O, then Enter to confirm the filename, then Ctrl + X to exit.
5. Save the XiuRouter key (Linux)
Return to the command window, copy the entire block below, and run it. Copying in the XiuRouter console inserts the selected key. Replace YOUR_XIUROUTER_API_KEY in this document with your key.
(
set -e
umask 077
mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/xiurouter-api-key" ]; then
cp "$HOME/.codex/xiurouter-api-key" "$HOME/.codex/xiurouter-api-key.backup-$(date +%Y%m%d-%H%M%S)"
fi
touch "$HOME/.codex/xiurouter-api-key"
chmod 600 "$HOME/.codex/xiurouter-api-key"
printf '%s' "YOUR_XIUROUTER_API_KEY" > "$HOME/.codex/xiurouter-api-key"
)Returning to the prompt with no output means the command finished. The key is stored in your own .codex folder with access restricted to your user. An existing key is backed up there as xiurouter-api-key.backup-. The key stays outside config.toml and works when launching the app from the applications menu.
6. Reopen ChatGPT (Linux)
Open ChatGPT from the applications menu. Complete the first-use setup if shown, switch to Codex, and create a new local task. Existing tasks keep their previous connection.
7. Verify in a new local task (Linux)
Open a local folder in Codex, create a new task, and send the test message below. After the reply, return to XiuRouter console → Agent integrations → Check a real request and refresh usage. Confirm the selected model, /v1/responses, and a succeeded status.
Tell me the current folder name without changing any files.Opening ChatGPT alone does not prove the connection. Confirm the request in XiuRouter.
Codex CLI or IDE extension
The config file is ~/.codex/config.toml on macOS/Linux and %USERPROFILE%\.codex\config.toml for native Windows. The Windows desktop app and WSL do not automatically share a user directory.
Quit all IDE windows completely, then set the key in a terminal:
export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"Windows PowerShell:
$env:XIUROUTER_API_KEY = "YOUR_XIUROUTER_API_KEY"Put the first three lines below before the first TOML table, then place the provider table at the end. Update existing keys and provider tables without duplicates. Remove an existing xiurouter.auth subtable when switching from the Linux desktop key-file method to this environment-variable method.
model = "YOUR_MODEL_ID"
model_provider = "xiurouter"
web_search = "disabled"
[model_providers.xiurouter]
name = "XiuRouter"
base_url = "https://router-api.xiu.ai/v1"
env_key = "XIUROUTER_API_KEY"
wire_api = "responses"CLI: run this from the terminal where you set the key:
codex exec --model YOUR_MODEL_ID --sandbox read-only "Run pwd without changing files, then tell me the directory."IDE: launch the editor from that terminal (code . for VS Code), create a new local task in the Codex panel, and send “Run pwd without changing files, then tell me the current directory.” Reloading a window alone may retain the old environment. A separate CLI is not required to verify the IDE.
Confirm the connection
After the client responds, refresh Check a real request in the XiuRouter console. Confirm the same key, model, /v1/responses, and a succeeded status. Opening the app, editing a file, or passing a key check does not replace a real request. After basic connectivity works, test the tools your project needs; a text reply does not prove editing, file, hosted-search, or long-context support.
Troubleshooting and support
| Symptom | Action |
|---|---|
| The official sign-in screen remains | Quit completely and reopen; put the root model_provider = "xiurouter" before the first table; keep the Windows filename config.toml, not config.toml.txt |
duplicate key or a config parsing error |
Keep one copy of root settings and the provider; save plain text on macOS, and do not combine Linux auth with env_key |
401 |
Repeat the key and launch steps for your OS, checking key status and env_key; on macOS, repeat key setup after signing out or restarting |
| Model missing from the picker | Set its exact ID in config.toml and create a new local task |
Linux reports nano: command not found |
Show hidden files in the file manager and open .codex/config.toml with an installed text editor |
If it still fails, contact XiuRouter in-page support with your OS, ChatGPT/Codex version, client surface, model ID, time and timezone, exact error, request ID if present, and steps already tried. Hide keys, tokens, cookies, email addresses, and unrelated conversations in screenshots. Do not send a complete config.toml or auth.json.
Roll back
Replace config.toml with its config.toml.backup- copy from before setup, then quit the client completely and reopen it. On Linux, restore a replaced key from xiurouter-api-key.backup- too. Revoke a new key when no longer needed. Check whether other clients use the configuration before removing it.
Sources and review date
Reviewed on 2026-10-09. On macOS, a signed-out instance loaded the provider and entered onboarding. Windows ChatGPT 26.1002.6548.0 produced a local reply with a matching XiuRouter request. Linux configuration and key-file reading were executed; its native desktop UI has not been tested.