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.

The gateway supports Codex CLI against multiple provider types. Pick the tab that matches your setup.

Setup

Choose the provider the LLM Registry entry uses, and the mode you want to run in.

OpenAI

Direct — gateway-managed key

The gateway stores your OpenAI credential on the LLM Registry entry, so you don't send an API key from your machine — Codex CLI only sends its Agent Access Key.

In ~/.codex/config.toml:

model_provider = "aigw"

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

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 OpenAI credential on the outbound side, and forwards to OpenAI.

Via Agent Persona

Route Codex CLI through an Agent Persona so its LLM calls are governed by the same policies that gate the persona's tools.

In ~/.codex/config.toml:

model_provider = "aigw"
model = "~openai/gpt-latest"

[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>" }

Then:

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

The [mcp_servers.*] block wires the persona's tools into Codex CLI at the same time — one Agent Access Key covers both the LLM call and the MCP tool socket.

OpenRouter

Direct — gateway-managed key

The gateway stores your OpenRouter credential on the LLM Registry entry. Codex CLI only sends 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"

wire_api = "responses" tells Codex CLI to use OpenAI's Responses API shape, which OpenRouter exposes and which Codex prefers for tool use.

Then:

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

Via Agent Persona

In ~/.codex/config.toml:

model_provider = "aigw"
model = "~openai/gpt-latest"

[model_providers.aigw]
name = "AI Gateway"
base_url = "https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>/api/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>" }

note

For OpenRouter entries reached via a persona, base_url must end in /api/v1 (not /v1). The portal's Connect page does not yet show this variation — copy the URL manually until it does.

Then:

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

Where to find each value

Placeholder	Where to find it
<gateway-host>	The gateway host from the LLM Registry entry's Overview tab (e.g., gw.aigateway.example.com)
<url-prefix>	The URL prefix field on the LLM Registry entry
<persona-id>	The persona's ID on the Agent Persona page
<registry-entry-id>	The LLM Registry entry's ID on the entry's URL
<your-agent-access-key>	Generate on the Agent Access Keys step of the Connect flow; the plaintext is shown once

Tips

• One key, two uses. In the persona setup, the same Agent Access Key authenticates both the LLM call (Authorization: Bearer) and the MCP tool socket (X-Agent-Key). You don't need to mint two keys.
• Restart Codex CLI after any config change. Codex CLI reads ~/.codex/config.toml at startup only.
• Test the endpoint first. If Codex CLI reports a generic authentication error, run a plain curl against the same base_url with your Agent Access Key to confirm the endpoint and key are correct before debugging Codex's config file.