Skip to main content

Codex CLI

Codex CLI is OpenAI's terminal-based coding assistant. It reads its provider configuration from ~/.codex/config.toml, which lets you point it at the Cequence AI Gateway instead of calling the provider directly. It can also send custom headers, which is how the Agent Access Key travels when a route needs one alongside a provider key.

Which setup do you need?​

What you getUse it when
LLM Registry entryThe model, governedYou only need model access
Agent PersonaThe model and the persona's MCP tools, from one config fileYou want Codex to use tools as well

Which credentials you send depends on the entry's credential mode. If you haven't read which credentials your entry needs, start there.

note

OpenRouter entries take a different base URL suffix. Use /api/v1 where the examples below use /v1. Everything else on this page is identical for OpenAI and OpenRouter entries; only the model identifiers differ, and those come from the entry's Allowed Models list. The portal's Connect page does not yet show this variation, so adjust the URL manually.

Connect to an LLM Registry entry​

Pick the credential mode on the entry's Provider Credential panel.

The gateway stores your provider credential, so no provider key leaves your machine. Codex CLI sends only its Agent Access Key.

In ~/.codex/config.toml:

model_provider = "aigw"
model = "<model-id>"

[model_providers.aigw]
name = "AI Gateway"
base_url = "https://<gateway-host>/llm/<url-prefix>/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Then:

export OPENAI_API_KEY="<your-agent-access-key>"

Codex CLI sends the Agent Access Key on Authorization: Bearer. The gateway authenticates the call, attaches the stored provider credential on the outbound side, and forwards it upstream.

Connect through an Agent Persona​

An Agent Persona bundles a set of MCP tools and, optionally, LLM access under one endpoint. Codex CLI wires both from the same config file:

  • The model route, at https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>/v1, on the [model_providers.aigw] block.
  • The tools socket, at https://<gateway-host>/p/<persona-id>, on an [mcp_servers.*] block.

One Agent Access Key covers both. The same key authenticates the model route and the tools socket, whichever Inbound Authentication method the persona uses.

note

Two separate settings are in play here, and only one of them changes the code below.

  • The entry's credential mode — API Key or Passthrough — decides which credentials you send. This is what the tabs below switch between, exactly as on the route above.
  • The persona's own Inbound Authentication method — Interactive or Passthrough — decides how the persona identifies you. Either way an Agent Access Key is issued, and neither changes the configuration below.

Because a persona always identifies you by an Agent Access Key, the entry's third mode — Passthrough (No Agent Access Key) — has no tab here. It applies to the LLM Registry entry route only.

model_provider = "aigw"
model = "<model-id>"

[model_providers.aigw]
name = "AI Gateway"
base_url = "https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[mcp_servers."<persona-name>"]
url = "https://<gateway-host>/p/<persona-id>"
http_headers = { "X-Agent-Key" = "<your-agent-access-key>" }
export OPENAI_API_KEY="<your-agent-access-key>"

The same Agent Access Key appears twice on purpose: once in the environment variable for the model route, once as an MCP header for the tools socket.

Where to find each value​

PlaceholderWhere to find it
<gateway-host>Host from the entry's Overview tab
<url-prefix>The URL prefix field on the entry's Overview tab
<persona-id>The persona's ID on the Agent Persona page
<persona-name>Any short name you want Codex CLI to use for this MCP server locally
<registry-entry-id>The LLM Registry entry's ID in the entry's URL
<model-id>A model identifier from the entry's Allowed Models list
<your-agent-access-key>Generate from the entry's Agent Access Keys step, or the persona's Connect flow. Plaintext is shown once.
<your-provider-api-key>Your own OpenAI or OpenRouter key, needed only in the passthrough modes

Tips​

  • Use a named provider block. [model_providers.aigw] with an explicit base_url is the configuration that works. A bare openai_base_url or a plain OPENAI_BASE_URL environment variable does not.
  • Keep wire_api = "responses". Codex CLI talks to the gateway over the Responses API shape; omitting this line changes the wire format it sends.
  • Restart Codex CLI after any config change. It reads ~/.codex/config.toml at startup only.
  • Check the endpoint first. If Codex CLI reports a generic authentication error, compare the base_url and Agent Access Key in your config against the values shown in the Connect flow before debugging the config file. A mismatched URL prefix looks identical to a bad key from the CLI's error message.
Last updated on