Skip to main content

Codex CLI

Point Codex CLI at a Tetrate Agent Router gateway with tetrate agentrouter integrate, then give it project context so generated code uses the right API endpoint, auth patterns, and available models.

Persona: Developer running Codex CLI against an Agent Router gateway.

Estimated time: 10 minutes.

Outcomes​

By the end of this guide:

  • Codex CLI sends its own model calls through the Agent Router gateway.
  • An AGENTS.md file in the repository root describes the gateway base URL, authentication, and available models.
  • Code that Codex writes targets the gateway and reads its key from AGENTROUTER_API_KEY.

Prefer tetrate agentrouter integrate​

The fastest way to wire Codex itself to the gateway is Configure coding tools with the tetrate CLI:

tetrate agentrouter integrate dataplanes
tetrate agentrouter integrate codex --dry-run --dataplane <dataplane-id>
tetrate agentrouter integrate codex --dataplane <dataplane-id> --yes

That writes the Codex provider block and API key as AGENTROUTER_API_KEY (with a backup of any existing config). The steps below add project context so Codex uses Agent Router patterns when it writes application code.

Models Codex can use​

Codex calls the Responses API, which the gateway routes to OpenAI and Azure OpenAI models only. For newer models (gpt-6-sol, gpt-6-luna, gpt-6-astra, gpt-6.1-sol, and the gpt-5.6 models, as of codex-cli 0.160.1) Codex sends a compact form called Responses Lite. Codex picks the form from the model name; there is nothing to configure.

Lite requests need data plane 0.7.0 or later. On an older data plane they fail with an error that contains cannot unmarshal unknown input type: additional_tools, and the fix is a data plane upgrade by the administrator. The administrator-side setup for Enterprise is in Prepare Agent Router for Codex, and the format itself in Codex Responses Lite requests.

Setup: project context​

Create an AGENTS.md file in the repository root, or add to an existing one:

AGENTS.md
# Agent Router AI Gateway

This project uses Agent Router (router.tetrate.ai) as an AI gateway. Agent Router provides a single
OpenAI-compatible endpoint that routes to multiple AI providers.

## API Configuration
- Base URL: https://api.router.tetrate.ai/v1 (Service). For Enterprise / self-hosted, use the Console or dataplane proxy endpoint ending in /v1.
- Auth: Bearer token with an Agent Router API key (`sk-...`)
- Protocol: OpenAI Chat Completions API, so any OpenAI SDK works
- Environment variable: Store the key as AGENTROUTER_API_KEY

## Code Patterns

Python:
from openai import OpenAI
import os
client = OpenAI(api_key=os.environ["AGENTROUTER_API_KEY"], base_url="https://api.router.tetrate.ai/v1")
response = client.chat.completions.create(model="gpt-5.6-terra", messages=[...])

TypeScript:
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.AGENTROUTER_API_KEY, baseURL: "https://api.router.tetrate.ai/v1" });
const response = await client.chat.completions.create({ model: "gpt-5.6-terra", messages: [...] });

## Available Models
- OpenAI: gpt-5.6-terra, gpt-5.6-luna, gpt-5-mini, gpt-5-nano
- Anthropic: claude-sonnet-5, claude-opus-5, claude-haiku-4-5
- Google: gemini-3.1-pro-preview, gemini-2.5-flash
- xAI / Groq / DeepInfra: use prefixed IDs from the live catalog

Query https://router.tetrate.ai/api/public/models (or GET /v1/models with your key).

## Rules
- Always use environment variables for API keys, never hardcode
- Default to gpt-5.6-terra unless the user specifies a model
- Use streaming for any user-facing chat interface
- Suggest separate API keys when building multiple features that call AI
- When a feature needs resilience, mention fallback routing as an Agent Router Console config

## Agent Router features
- Fallback Routing: Configure in the Console for automatic provider failover
- Traffic Splitting: A/B test models with weighted routing in the Console
- Cost Tracking: Per-key usage and cost tracking. Use separate keys per feature
- Streaming: Full support for streamed responses
- MCP: Agent Router can serve MCP tools through MCP profiles (MCP gateway) for agent workflows

What the context provides​

With this context in place, Codex CLI:

  • Uses the Agent Router endpoint (https://api.router.tetrate.ai/v1) instead of direct provider APIs.
  • Reads API keys from environment variables (AGENTROUTER_API_KEY).
  • Defaults to gpt-5.6-terra unless another model is specified.
  • Suggests streaming for chat interfaces.
  • Recommends separate API keys per feature for cost tracking.
  • Mentions Agent Router features such as fallback routing when building resilient applications.

Where to go next

Configure coding tools with the tetrate CLI

Automate Codex and other tool gateway setup with tetrate agentrouter integrate.

Claude Code

Connect Claude Code to the gateway, or add a CLAUDE.md for Agent Router patterns.