Codex
Connect Codex CLI to Etage: prepare your key, write the configuration and start on Windows or macOS/Linux.
On this page
Before you start
You need Codex CLI installed, an Etage API key and available credits. Create a key and allow a model compatible with Responses. This guide configures the terminal client, not Codex Desktop.
1. Open the configuration folder
Codex must already be installed. Fully quit it before editing. If configuration exists, make a backup first. The examples below are for a new setup; in an existing file merge only the required Etage fields without removing other connections, security settings or sign-in data.
Windows: press Win + R and open %USERPROFILE%\.codex. If the folder is missing, create it with the PowerShell command below (not CMD), then edit the file in Notepad. On macOS open Terminal; on Linux use your terminal. The second tab creates the folder and opens the file in nano; another text editor also works. Examples use the standard home directory; if you changed the client configuration location, use your own path.
New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
notepad "$HOME\.codex\config.toml"2. Write config.toml
Paste the TOML below. Etage uses Responses with the base URL https://api.etage.one/v1. The model and review_model values select gpt-6.1-sol; to switch, update both to an allowed Model ID compatible with Responses. This minimal example needs only config.toml and auth.json, not a separate model catalogue. Do not add /v1 twice.
In an existing TOML add or update only the required fields and model_providers.etage table. Do not duplicate tables. Preserve your approval, sandbox and network restrictions; connecting does not require weakening them. If you used another authentication method, back it up and check conflicting settings first.
model = "gpt-6.1-sol"
review_model = "gpt-6.1-sol"
model_provider = "etage"
[model_providers.etage]
name = "Etage"
base_url = "https://api.etage.one/v1"
wire_api = "responses"
requires_openai_auth = true
3. Create auth.json in the same folder
Open the second file in the same .codex folder, not in your project folder. On Windows use PowerShell and Notepad; on macOS/Linux open it in nano. If auth.json already exists, back it up first: previous sign-in data must not be lost when switching to an API key.
notepad "$HOME\.codex\auth.json"4. Write your key in auth.json
For a new setup paste the JSON below and replace YOUR_API_KEY with your Etage key. Do not put the key in config.toml. auth.json is a regular local secret-containing file, not encrypted storage: never send it to chat, support or a repository. Check that old environment variables or credential helpers do not override the connection.
{
"OPENAI_API_KEY": "YOUR_API_KEY"
}5. Save the files
Save as plain UTF-8 text. In Notepad choose All files, press Ctrl + S and check that .txt was not added to the filename. In nano: Ctrl + O → Enter → Ctrl + X. On macOS/Linux restrict access to key-containing files with the command below; do not publish them or their backups.
Fully quit Codex before starting again: an existing session may keep old settings. Preserve your approval rules, sandbox and network restrictions.
chmod 600 "$HOME/.codex/auth.json"6. Start Codex
Open a terminal in your project folder and run the command. In the client check the selected model and Etage connection.
codexVerify the connection
Test with a short request without secrets; it spends credits. After a response, check Usage for a retained record. A missing record does not establish zero spending. Configuration does not guarantee compatibility with every model.
Troubleshooting
Never publish auth.json or disable sandbox or approvals to fix a connection. Check the following settings.
- 401/403: check the auth.json key, expiry, model access and credits.
- Model not found: check the exact Model ID in model and review_model and Responses support.
- Configuration error: check TOML/JSON, UTF-8, duplicate tables and unexpected .txt extensions.
- Stale settings: fully restart Codex; check model_provider, the .codex path and conflicting authentication variables.