Connect Codex to UniRoute: API Key and Setup Tutorial

Connect the official Codex CLI to your UniRoute account, then verify the result in the UniRoute console. This tutorial walks through creating a key, choosing a compatible model, configuring authentication, checking one request, and restoring your previous setup.

You can use either a manually managed environment key or the UniRoute setup tool. Choose one authentication method before editing; the two configurations below use different credential sources.

1. Create a key in your UniRoute account

Install the official Codex CLI if needed (or follow our step-by-step guide to install Codex CLI on macOS, Linux, and Windows), then record its version:

npm install -g @openai/codex
codex --version

Create a UniRoute API key. ChatGPT subscription access, OpenAI API billing, and UniRoute balance and keys are separate. A ChatGPT subscription or OpenAI platform key does not fund a UniRoute request. Check current UniRoute pricing, review the OpenAI API price guide for GPT token rates, prompt caching, and model-specific context-tier pricing, and inspect your own account before making a paid request.

In UniRoute, open API keys from the console navigation, choose Create key, and give this connection a recognizable name such as codex-laptop. Copy the complete key when it is first displayed and store it privately; you cannot view it again after closing that dialog. Review the key's spending, channel, and model restrictions so the intended model is allowed. The key allowance is separate from your wallet balance.

Keep keys out of chat, command arguments, source control, screenshots, and shared logs. Before changing anything, quit Codex and privately back up the active config.toml and any existing auth.json. Record which files existed for rollback. Do not run codex logout or delete authentication as a setup step.

2. Choose a Responses-compatible UniRoute model

The setup tool needs Node.js 22+. In a terminal, run:

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup models

It reads UNIROUTE_API_KEY if set; otherwise it asks for your key with hidden input. It queries https://api.uniroute.app/v1/models. Copy the exact ID of a model with openai-responses support and replace MODEL_ID below. If the protocol is unknown, confirm support before selecting it; a name alone does not establish compatibility.

A successful catalog response establishes discovery, not successful inference, available credit, or support for every Codex feature. Current access also depends on account permissions and route availability.

3A. Manual config.toml with an environment key

Edit the user configuration at $CODEX_HOME/config.toml, or ~/.codex/config.toml when CODEX_HOME is unset. Provider settings belong at user level, not in the project's .codex directory. See OpenAI's configuration guide for configuration locations and provider scope.

This is a complete minimal UniRoute configuration. Merge these fields into your existing file, preserving unrelated settings. Keep the top-level fields before any table header; update an existing [model_providers.uniroute] instead of creating a duplicate.

model = "MODEL_ID"
model_provider = "uniroute"

[model_providers.uniroute]
name = "UniRoute"
base_url = "https://api.uniroute.app/v1"
wire_api = "responses"
env_key = "UNIROUTE_API_KEY"
requires_openai_auth = false

env_key names an environment variable, not the key itself. requires_openai_auth = false keeps this provider on environment authentication. Setting it to true makes Codex ignore env_key. These are separate methods in OpenAI's authentication documentation.

For Bash or Zsh, enter the key without displaying it or storing its value in shell history:

printf 'UniRoute API key (hidden): '
read -r -s UNIROUTE_API_KEY
printf '\n'
export UNIROUTE_API_KEY
codex

In PowerShell:

$env:UNIROUTE_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host 'UniRoute API key' -AsSecureString)).Password
codex

The variable must reach the process that starts Codex. Set it again in a new terminal or use your own secret manager. A desktop app opened from the Dock or Start menu may not inherit terminal variables; see the desktop guide before choosing this method there. This option does not require changing auth.json or logging out of ChatGPT. Remove conflicting command-backed auth or inline bearer tokens from this provider's table when switching methods.

Keep /v1 in the base URL; do not append /responses or /chat/completions. Codex selects the Responses endpoint using wire_api. See OpenAI's field reference and OpenAI Responses API vs. Chat Completions: Migration Guide for protocol differences.

3B. Setup tool with file-based authentication

Choose this option to let the tool manage the active Codex credentials. Version 0.1.2 targets the operating system's home directory plus .codex; it does not follow CODEX_HOME. If you use a custom CODEX_HOME, use Option A at that location instead. --home means an alternate home root, beneath which the tool creates .codex; it is not a Codex configuration-directory argument.

Preview the changes, then run the write command only if you want this authentication switch:

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure codex --model MODEL_ID --dry-run
npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure codex --model MODEL_ID

The preview lists affected files; it does not print full file contents or write them. The tool preserves unrelated settings and creates private backups of existing changed files, reporting their names. The resulting provider configuration is:

model = "MODEL_ID"
model_provider = "uniroute"
cli_auth_credentials_store = "file"

[model_providers.uniroute]
name = "UniRoute"
base_url = "https://api.uniroute.app/v1"
wire_api = "responses"
requires_openai_auth = true

The tool writes your UniRoute key into auth.json as OPENAI_API_KEY, with auth_mode set to apikey. That field name does not turn it into an OpenAI-issued key. It removes existing tokens and last_refresh from active authentication, and removes env_key, inline bearer tokens, and command-backed auth from this provider. Any ChatGPT tokens in the original auth.json are retained in its backup rather than the active file; this does not remove credentials from an OS keychain. Do not mix in Option A's environment-key fields.

Although the tool can read UNIROUTE_API_KEY as input, the generated Codex configuration uses the credential file. Protect auth.json and its backups like passwords. See the credential-store reference for cli_auth_credentials_store.

Check local files without making a model request:

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup doctor codex

local config ready is a local check for the tool's file-based setup, not proof of inference. It is not a validator for Option A. The UniRoute configuration Skill can assist with this same tool flow.

4. Verify the connection in UniRoute usage records

Start codex and check that the active provider is uniroute and the model matches your chosen ID. If you decide to test, send one short, nonsensitive message. A real request can incur charges; retries or agent activity can create multiple requests. Stop after an error and inspect it before retrying.

Then open your own UniRoute usage records. Match the time, model, outcome, token usage, and actual charge. Resolve billing questions through authenticated account records; catalog results and client token totals alone cannot establish the wallet debit. Open the matching request detail. If you need support, use Copy diagnostic summary and review it before sharing through private support. Missing fields remain unknown, and the summary does not confirm wallet settlement. Never publish your account ledger or someone else's records.

5. Resolve a failed connection

An HTTP/SOCKS network proxy transports traffic. An API provider selects the service endpoint and authentication. Changing base_url does not configure a network proxy, and a network proxy does not select UniRoute. Do not send your key to an unknown proxy endpoint. See API endpoints and connectivity.

For support, share the Codex version, model, timestamp and timezone, status, and a redacted error. Exclude keys, authorization headers, cookies, auth.json, private prompts, and account balances.

6. Restore your previous setup

Quit Codex first. For Option A, restore the saved configuration and remove UNIROUTE_API_KEY from the terminal with unset UNIROUTE_API_KEY in Bash/Zsh or Remove-Item Env:UNIROUTE_API_KEY in PowerShell. Remove any secret-manager launch setting you added too.

For Option B, restore the matching pre-change config.toml and auth.json backups together. If a file did not exist before, undo only the file or settings introduced by this setup, preserving subsequent changes. Keep credentials private and verify the intended provider after reopening Codex. Do not delete an existing authentication file or log out as a general troubleshooting shortcut.