DocsAPI ReferenceSDKsCookbookChangelog

For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://modelgates.ai/docs/_mcp/server.

Codex CLI

What is Codex CLI?

Codex CLI is OpenAI's open-source local coding agent that runs in your terminal. It supports multiple model providers, including ModelGates, so you can use ModelGates's unified API, provider failover, and organizational controls with Codex's agentic coding workflows.

Quick Start

Step 1: Install Codex CLI

Follow the Codex CLI installation instructions to install the CLI on your system.

Step 2: Get Your ModelGates API Key

  1. Sign up or log in at ModelGates
  2. Navigate to your API Keys page
  3. Create a new API key
  4. Copy your key (starts with sk-mg-...)

Step 3: Configure Codex for ModelGates

Codex uses a config.toml file, typically located at ~/.codex/config.toml. Create or edit this file with the following configuration:

toml
model_provider = "modelgates"model_reasoning_effort = "high"model="openai/gpt-5.3-codex" [model_providers.modelgates]name = "modelgates" base_url="https://modelgates.ai/api/v1"env_key="MODELGATES_API_KEY"

Step 4: Set Your API Key

Export your ModelGates API key in your shell profile:

bash
# Add to ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fishexport MODELGATES_API_KEY="sk-mg-..."

Codex reads the API key from the environment variable specified in env_key (default: MODELGATES_API_KEY). Ensure this is set before starting Codex.

Step 5: Start Codex

Navigate to your project directory and run:

bash
cd /path/to/your/projectcodex

Your requests will now be routed through ModelGates.

Configuration Reference

Core Settings

SettingDescriptionExample
model_providerProvider to use for model requests"modelgates"
modelModelGates model ID"openai/gpt-5.3-codex"
model_reasoning_effortReasoning effort level for Codex models"low", "medium", "high", "xhigh"
show_raw_agent_reasoningWhether to display reasoning tokens in the UItrue or false
personalityAgent personality preset"pragmatic", "helpful", etc.

ModelGates Provider Block

toml
[model_providers.modelgates]name = "modelgates"base_url = "https://modelgates.ai/api/v1"env_key = "MODELGATES_API_KEY"
  • base_url: ModelGates API endpoint. Use https://modelgates.ai/api/v1 for production.
  • env_key: Environment variable name for your API key.

Project Trust Levels

Codex supports per-project trust levels. Add project paths to control what the agent can access:

toml
[projects."/path/to/trusted/project"]trust_level = "trusted" [projects."/path/to/untrusted/project"]trust_level = "untrusted"
  • trusted: Agent has full access (e.g., run commands, edit files).
  • untrusted: Agent has restricted access for safety.

Why Use ModelGates with Codex CLI?

Provider Failover

ModelGates routes requests across multiple providers. If one provider is unavailable or rate-limited, ModelGates can fail over to another, keeping your coding sessions uninterrupted.

Organizational Controls

For teams, ModelGates provides centralized budget management. Set spending limits, allocate credits, and prevent unexpected cost overruns across developers using Codex.

Usage Visibility

Track Codex usage in real-time via the ModelGates Activity Dashboard. Monitor costs, token usage, and request patterns.

Model Flexibility

Switch between Codex models (e.g., gpt-5.2-codex, gpt-5.3-codex) or try other ModelGates models without changing your Codex installation—just update config.toml.

Troubleshooting

  • Auth Errors: Ensure MODELGATES_API_KEY is set and valid. Check at modelgates.ai/keys.
  • Model Not Found: Verify the model ID on modelgates.ai/models. Use the exact format (e.g., openai/gpt-5.3-codex).
  • Privacy: ModelGates does not log your source code prompts unless you opt-in to prompt logging. See our Privacy Policy for details.

Resources