Use Codex CLI with the Gateway¶

Codex CLI is OpenAI's open-source terminal coding agent. Connect it to the Gateway to route requests through your regional endpoint with full budget controls and data residency.

Prerequisites¶

Codex CLI installed (installation guide)
An LLM API key

Connect Codex CLI to the Gateway¶

Step 1 — Configure the provider¶

Create or edit ~/.codex/config.toml:

model_provider = "amazeeai"
model = "claude-4-5-sonnet"
web_search = "disabled"

[model_providers.amazeeai]
name = "Gateway"
base_url = "https://llm.[your-region].amazee.ai/v1"
env_key = "AMAZEEAI_API_KEY"

Replace [your-region] with your region code (e.g. ch103, us103).

Don't name the provider openai

Codex reserves openai for its built-in provider and won't load a config that redefines it. Use any other name, like amazeeai.

Why web search is disabled

With GPT models, Codex adds a built-in web search tool that the Gateway can't pass through. Without this line, GPT models fail with 'search_content_types' field is not supported. Claude models work either way.

Step 2 — Set your API key¶

Add to your shell profile (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish):

export AMAZEEAI_API_KEY="your-api-key-here"

Then reload your shell:

source ~/.zshrc   # or ~/.bashrc

Step 3 — Check it works¶

codex exec "Reply with the word pong"

You should see provider: amazeeai in the header and pong at the end. You may also see Model metadata for ... not found. Defaulting to fallback metadata. That's expected for non-OpenAI models and safe to ignore.

Codex only runs inside a git repo. If you're testing from an empty folder, add --skip-git-repo-check.

Step 4 — Start Codex¶

cd /path/to/your/project
codex

Switching models¶

Change model in config.toml, or pass -m <model-id>. Use the exact ID from Available Models or /v1/models, for example claude-4-5-sonnet or claude-5-sonnet. Not every region serves every model: GPT models, for example, aren't on every region.

Troubleshooting¶

"model_providers contains reserved built-in provider IDs: openai": Rename [model_providers.openai] to another name and update model_provider to match.
"403 team not allowed to access model" (after several "Reconnecting..." lines): The model ID doesn't exist on the Gateway or isn't on your key. Gateway IDs look like claude-4-5-sonnet, not claude-sonnet-4-5.
"'search_content_types' field is not supported for web search tools": Add web_search = "disabled" to config.toml.
"Not inside a trusted directory and --skip-git-repo-check was not specified": Run Codex inside a git repo, or add --skip-git-repo-check.
Auth errors: Make sure AMAZEEAI_API_KEY is set in the shell you start Codex from. Run [ -n "$AMAZEEAI_API_KEY" ] && echo set to check without printing the key.
Connection errors: Verify your base URL is correct and includes /v1.