Codex CLI Setup

Create a Gate.AI API Key

Open gate.ai → Dashboard → API Keys, create and copy a key starting with sk-v1-…
Confirm your account has sufficient balance

Network connectivity check

Replace GATEAI_API_KEY with your key:

bash

1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"

OpenAI-compatible endpoint (Codex / standard API):

bash

1curl -s -o /dev/null -w "%{http_code}" \2  -H "Authorization: Bearer $GATEAI_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"model":"openai/gpt-5.2","input":"hi","max_output_tokens":16}' \5  https://api.gate.ai/openai/v1/responses

Returns 200: gateway is reachable; proceed with install and configuration
Returns 401: invalid or expired key — check the dashboard
Connection timeout: check local network or DNS; do not use https://api.gate.ai/v1

Install Codex CLI

bash

1npm install -g @openai/codex

bash

1curl -fsSL https://chatgpt.com/codex/install.sh | sh

If you use Homebrew

bash

1brew install --cask codex

Verify: codex --version

If npm install fails

This is usually caused by registry.npmjs.org timeouts or instability — unrelated to the Gate.AI gateway. Try one of the following:

Option A: one-off install with a mirror (try first)

bash

1npm install -g @openai/codex --registry=https://registry.npmmirror.com2npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

Option B: set mirror globally

bash

1# Use npmmirror (common in China)2npm config set registry https://registry.npmmirror.com34# Verify registry5npm config get registry67# Reinstall8npm install -g @openai/codex9npm install -g @anthropic-ai/claude-code

Option C: current shell session only

bash

1export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com2npm install -g @openai/codex

Symptom	Fix
`ETIMEDOUT` / `ECONNRESET`	Switch mirror (Option A or B) and retry
`EACCES` permission error	Configure npm global prefix: `mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global`, and add `export PATH=~/.npm-global/bin:$PATH` to `~/.zshrc`
`command not found: claude` / `codex`	Installed but PATH not updated: restart the terminal, or confirm `bin` under `npm config get prefix` is on PATH

Configure model

Replace all sk-v1-your-key placeholders with your real key. No need to repeat unless you change the key or model.

bash

1mkdir -p ~/.codex23cat > ~/.codex/config.toml <<'EOF'4model_provider = "gateai"5model = "openai/gpt-5.2"67[model_providers.gateai]8name = "Gate.AI"9base_url = "https://api.gate.ai/openai/v1"10env_key = "GATEAI_API_KEY"11wire_api = "responses"12requires_openai_auth = false13EOF1415grep -q 'GATEAI_API_KEY=' ~/.zshrc 2>/dev/null || cat >> ~/.zshrc <<'EOF'1617# Gate.AI for Codex CLI18export GATEAI_API_KEY="sk-v1-your-key"19EOF2021source ~/.zshrc

Codex gateway settings must be in user-level ~/.codex/config.toml. Project-level .codex/config.toml cannot override these values.

Verify setup

In your project directory, start the CLI for AI-assisted coding in the terminal.

Run codex

bash

1codex

If you get a normal reply without 401 / 404, routing through Gate.AI succeeded.

Advanced configuration

Config reference

Field	Description	Example
`model_provider`	Provider name	`"gateai"`
`model`	Gate.AI model ID	`"openai/gpt-5.2"`
`base_url`	Gate OpenAI-compatible endpoint	`https://api.gate.ai/openai/v1`
`env_key`	API key environment variable	`"GATEAI_API_KEY"`
`wire_api`	Codex protocol type	`"responses"`
`requires_openai_auth`	When Gate key is not OpenAI official format	`false`
`model_reasoning_effort`	Reasoning effort (optional)	`"low"` / `"medium"` / `"high"`

Alternative configuration

Built-in OpenAI provider (try if Option A auth fails)

toml

1model = "openai/gpt-5.2"2openai_base_url = "https://api.gate.ai/openai/v1"

Environment variable: export OPENAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"

Temporary CLI override

bash

1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"2codex --config openai_base_url='"https://api.gate.ai/openai/v1"' --config model='"openai/gpt-5.2"'

Switch model

Edit model in ~/.codex/config.toml, or run: codex --model openai/gpt-5.2

Restore direct OpenAI (optional)

Remove Gate-related settings from ~/.codex/config.toml and unset GATEAI_API_KEY.

Troubleshooting

Common Base URL mistakes

bash

1# ❌ Wrong (missing /openai prefix, 404)2https://api.gate.ai/v13https://api.gate.ai/v1/chat/completions45# ❌ Wrong (do not use full API path in Codex config)6https://api.gate.ai/openai/v1/messages7https://api.gate.ai/openai/messages89# ✅ Correct10https://api.gate.ai/openai/v1          # Codex CLI11https://api.gate.ai/anthropic/v1/messages  # curl key check (Anthropic)12https://api.gate.ai/openai/v1/responses    # curl key check (Codex)

/openai/v1/chat/completions works, but Codex must use the Responses API. On 404 for /responses, check wire_api = "responses", not the URL.
/openai/v1/models does not validate keys (invalid keys may still return 200). Use the curl endpoints above to verify keys.

Quick reference

Symptom	Type	Suggestion
401 / auth failure	Auth error	Check the key is correct and not expired; for Codex confirm `requires_openai_auth = false`
404 on URL	Path error	Claude → `https://api.gate.ai/anthropic`; Codex → `https://api.gate.ai/openai/v1`. Do not use `https://api.gate.ai/v1/...`
404 on `/responses`	Protocol error	Base URL may be correct but Responses API not used. Check `~/.codex/config.toml`: `wire_api = "responses"`, `base_url = "https://api.gate.ai/openai/v1"`
curl `/models` returns 200 but CLI still 401	Wrong key check	`/openai/v1/models` does not validate keys. Use `/openai/v1/responses` or `/anthropic/v1/messages` instead
Model not found	Model ID error	Use `provider/model-name` format (e.g. `anthropic/claude-sonnet-4.6`, `openai/gpt-5.2`); see the model catalog
Still connecting to official domain	Config not applied	Use user-level config: Claude → `~/.claude/settings.json`; Codex → `~/.codex/config.toml` (project `.codex/config.toml` cannot override gateway settings)
402 / 429	Quota / rate limit	Top up or check key budget and rate limits
npm install fails	Network / permissions	See "If npm install fails"