How to point the Codex CLI at a custom base URL

What you need before you start

The Codex CLI reads plain environment variables, so the setup is short: install the CLI, create a gateway key, then choose between an environment variable and a config file.

• A QuickRouter account with an active plan and an API key from the console.
• The OpenAI-style base URL, /v1 included: https://api.quickrouter.homes/v1.
• Node.js 18+ with npm, or a package manager that can install a global CLI.
• A shell profile you can edit if you want the setting to survive a reboot.

Option 1: environment variables

The fastest route. Export the two variables, then start the CLI from the same shell - Codex reads them at startup.

1. 01

   Export the base URL and key

   Run both lines in the terminal you use for Codex.

   export OPENAI_BASE_URL="https://api.quickrouter.homes/v1"
   export OPENAI_API_KEY="sk-qr-your-key"

2. 02

   Run a first task

   Start with something small and read-only so you can confirm the wiring before it edits files.

   codex "list the files in this repository and summarise the build"

Option 2: a persistent provider in config.toml

Declare the gateway once in ~/.codex/config.toml and select it as the default provider. The file survives new shells, which is what you want on a work machine.

1. 01

   Add the provider block

   Use the chat wire API for an OpenAI-compatible endpoint and keep the key in an environment variable rather than in the file.

   [model_providers.quickrouter]
   name = "QuickRouter"
   base_url = "https://api.quickrouter.homes/v1"
   env_key = "OPENAI_API_KEY"
   wire_api = "chat"
   
   [profiles.quickrouter]
   model_provider = "quickrouter"
   model = "gpt-5"

2. 02

   Select the profile

   Start Codex with the profile so the gateway becomes the active provider for that session.

   codex --profile quickrouter "summarise the open issues"

Errors you are most likely to hit

Configuration mistakes in Codex surface as connection errors during startup, before any model call happens.

Which model should Codex use?

Codex spends most of its tokens re-reading context, so the input price dominates the bill. A cheap input model with a long context window is usually the better default than the flagship.