--- title: "Codex" description: "Point Codex CLI at pirouter: add a provider to ~/.codex/config.toml with base_url https://api.pirouter.ai/v1 and wire_api responses, and read the key from PIROUTER_API_KEY; only models served on the Responses endpoint work." canonical: "https://pirouter.ai/docs/integrations/codex" last-updated: "2026-10-18" lang: "en" source: "content/docs/en/integrations/codex.mdx" --- # Codex Point Codex CLI at pirouter: add a provider to ~/.codex/config.toml with base_url https://api.pirouter.ai/v1 and wire_api responses, and read the key from PIROUTER_API_KEY; only models served on the Responses endpoint work. [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) runs on pirouter without a plugin. Define a provider that points at pirouter in `~/.codex/config.toml` and let Codex read the key from an environment variable. Codex uses only the OpenAI Responses endpoint and sends its requests to `POST /v1/responses`, so it works only with models served on that endpoint. ## Prerequisites - A pirouter API key. If you do not have one, create it with the [quickstart](https://pirouter.ai/docs/quickstart.md) and store it in an environment variable. Put it in a shell profile such as `~/.zshrc` so every terminal can read it: `~/.zshrc`: ```bash export PIROUTER_API_KEY="sk-pi-..." ``` - Codex CLI. This page was verified on v0.162.1. If it is not installed yet, run this on macOS or Linux: ```bash curl -fsSL https://chatgpt.com/codex/install.sh | sh ``` You can also use `npm install -g @openai/codex` or `brew install --cask codex`. For Windows, see the [Codex CLI install guide](https://learn.chatgpt.com/docs/codex/cli). ## Configure Put this in `~/.codex/config.toml`. If the file already has content, keep the first three lines at the very top, before the first `[...]` table header; otherwise Codex reads them as keys of the table above them: `~/.codex/config.toml`: ```toml model = "openai/gpt-6.1-sol" model_provider = "pirouter" web_search = "disabled" [model_providers.pirouter] name = "pirouter" base_url = "https://api.pirouter.ai/v1" wire_api = "responses" env_key = "PIROUTER_API_KEY" ``` What each entry does: - `model` is the full model ID. - `model_provider` points at the `pirouter` provider defined below. - `web_search = "disabled"` turns off Codex's built-in web search tool. By default it searches an index maintained by OpenAI, and pirouter does not provide that tool. - `base_url` is `https://api.pirouter.ai/v1`, with `/v1`. Codex appends `/responses` to it. - `wire_api` is `responses`, the only value Codex supports. - `env_key` is the name of the environment variable that holds the key, not the key itself. Codex sends the variable's value in the `Authorization: Bearer` header, which is where the gateway reads it. This configuration only works in your user-level `~/.codex/config.toml`. A project's `.codex/config.toml` ignores `model_provider` and `model_providers`. ### Which models you can use Codex calls only `POST /v1/responses`; it uses neither Chat Completions nor the Anthropic protocol. For the models you can use, see the protocol table in [Models & protocols](https://pirouter.ai/docs/models.md#which-protocols-each-model-accepts): pick a model with OpenAI support that is served on the Responses endpoint. `openai/gpt-6.1-sol` and `openai/gpt-5.5` both work in testing, tool calls included. To switch models for one run, add `-m`: ```bash codex -m openai/gpt-5.5 ``` ## Verify In a terminal, run: ```bash codex exec --skip-git-repo-check "Reply with the single word: ok" ``` You should see Codex finish with `ok`. `--skip-git-repo-check` lets it run in a directory that is not a git repository. The request shows up in [Logs](https://pirouter.ai/docs/guides/logs.md) in the console, with `/v1/responses` under **Endpoint**. ## Troubleshooting ### wire\_api = "chat" is no longer supported If Codex stops at startup with `` `wire_api = "chat"` is no longer supported ``, the configuration came from an old guide. Codex no longer supports Chat Completions: set `wire_api` to `"responses"` and keep `base_url` at `https://api.pirouter.ai/v1`. ### Web search left on Without `web_search = "disabled"`, the default is `"cached"`: Codex gives the model a web search tool that searches an index maintained by OpenAI. pirouter does not provide that tool. Add `web_search = "disabled"` at the top of the configuration file. ### codex exec hangs in a script When a script, a CI job or another program calls `codex exec`, standard input is not a terminal, and Codex waits to read it, which looks like a hang. When you have nothing to pass in, redirect standard input from `/dev/null`: ```bash codex exec --skip-git-repo-check "Reply with the single word: ok" < /dev/null ``` ### 422 validation\_failed A `422` with the error code `validation_failed` and a `message` starting "This model is not served on the endpoint you called." means the model is not served on the Responses endpoint. The rest of the `message` lists the endpoints it is served on. Pick a model in the protocol table that is served on the Responses endpoint. ### 401 invalid\_api\_key A `401` with the error code `invalid_api_key` means the request carried no key, or carried something other than a pirouter key starting with `sk-pi-`. Check that `PIROUTER_API_KEY` is set in the terminal that starts Codex. The Codex desktop app may not see variables exported in a terminal. For other authentication failures, see [Authentication & API keys](https://pirouter.ai/docs/authentication.md#when-authentication-fails). ## Not verified yet - Non-OpenAI models have not been tested with Codex. Some are served on the Responses endpoint, but Codex's prompts and tools are written for OpenAI models. - Putting the provider in a separate profile file (`~/.codex/pirouter.config.toml`, started with `codex --profile pirouter`) has not been tested. - What happens with web search on (`web_search` set to `"cached"` or `"live"`) has not been tested. ## Related links - [Codex](https://github.com/openai/codex) on GitHub - [Codex CLI install guide](https://learn.chatgpt.com/docs/codex/cli) - [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway): the official guide to custom providers in Codex - [Configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference): every `config.toml` setting