Codex

OpenAI Codex CLI via GUARD API.

Model protocol

Codex CLI: setup from scratch

Before you start

Get a gd-… key from the Guard bot: open the bot, obtain access and copy your key. Usage is charged to your Guard balance, shown in your Guard account. You will enter the full key at the hidden prompt in a later step.

The Codex family includes gpt-6-astra, gpt-6.1-sol, gpt-6-sol, gpt-6-luna, gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna. The primary example selects Astra; you may use any of the seven exact IDs. The table shows values supported by Guard. For Astra, GPT-6.1 Sol, GPT-6 Sol, GPT-5.6 Sol, and GPT-5.6 Terra the Codex client additionally offers the ultra level. It works through Guard: the client itself turns it into a supported level (xhigh or max, depending on the model) and may hand parts of the task to sub-agents, so it uses more tokens. A direct API request with ultra is rejected. GPT-6.1 Sol defaults to low; none and minimal are unsupported. The API supports none for GPT-6 Sol and GPT-6 Luna, although the native dropdown does not show it.

Model ID	Guard-supported reasoning effort
`gpt-6-astra`	low, medium, high, xhigh, max
`gpt-6.1-sol`	low, medium, high, xhigh, max
`gpt-6-sol`	none, low, medium, high, xhigh, max
`gpt-6-luna`	none, low, medium, high, xhigh, max
`gpt-5.6-sol`	low, medium, high, xhigh, max
`gpt-5.6-terra`	low, medium, high, xhigh, max
`gpt-5.6-luna`	low, medium, high, xhigh, max

Install Codex CLI

Open the official Codex CLI installation page and select your OS. If Node.js and npm are already installed, you can install the client with this command.

bash

npm install -g @openai/codex
codex --version

If npm is not found, use your OS installer from the official page. Open a new terminal after installation. codex --version should print the client version.

Open the configuration file

Provider settings go in your user config.toml, shared by Codex CLI and the extension. If the file already contains settings, save a copy. Update the settings below rather than replacing the entire file.

macOS: open Terminal using Spotlight and run the commands below. They create the folder and an empty file if needed.

bash

mkdir -p ~/.codex
touch ~/.codex/config.toml
open -e ~/.codex/config.toml

Windows: open PowerShell from Start. These commands open the file in Notepad.

powershell

$codexConfig = Join-Path $env:USERPROFILE ".codex\config.toml"
New-Item -ItemType Directory -Force (Split-Path $codexConfig) | Out-Null
if (-not (Test-Path $codexConfig)) { New-Item -ItemType File $codexConfig | Out-Null }
notepad $codexConfig

Linux: open a terminal and edit the file with a text editor such as nano. In nano, save with Ctrl+O, Enter, then exit with Ctrl+X.

bash

mkdir -p ~/.codex
touch ~/.codex/config.toml
nano ~/.codex/config.toml

Add the Guard provider

Add the settings below. Put the first four lines at the top of the file, before the first [section] heading. If model, model_provider, model_reasoning_effort or model_context_window already exist, update their existing lines. Add [model_providers.guard-codex] once, or update its fields if it exists. Save the file.

toml

model = "gpt-6-astra"
model_provider = "guard-codex"
model_reasoning_effort = "medium"
model_context_window = 872000

[model_providers.guard-codex]
name = "GUARD API · Codex"
base_url = "https://api.guardrelay.ai/codex/v1"
env_key = "GUARD_API_KEY"
wire_api = "responses"

Model ID	model_context_window
`gpt-6-astra`	872000
`gpt-6.1-sol`	872000
`gpt-6-sol`	872000
`gpt-6-luna`	872000
`gpt-5.6-sol`	872000
`gpt-5.6-terra`	872000
`gpt-5.6-luna`	872000

model_context_window sets the client history budget. The table uses the declared maximum from the latest saved Codex catalog dated September 13, 2026; it is not a guarantee of the API input hard limit. History compaction may start earlier; this setup does not set a per-response output cap.

Setting	Meaning
model	Exact model ID; GPT-5.6 Sol here.
model_provider	Provider section name below: guard-codex.
model_reasoning_effort	Reasoning effort. This example uses `medium`; choose only a supported value from the table above.
base_url	Guard address for this family. Do not append /responses manually.
env_key	Name of the environment variable containing your key, not the key itself.
wire_api	Responses

If you previously used model_catalog_json with a Claude model catalog, remove that setting when switching to the Codex family. The Claude catalog does not contain GPT models. Do not infer a response limit from model_context_window: if the client sends max_output_tokens, Guard accepts and preserves it, but managed Codex does not guarantee hard truncation; billing follows actual tokens and the key's money rules.

Provide your key to the application

macOS / Linux: run these commands, paste your key at the Guard API key prompt, and press Enter. Input is hidden and is not stored as part of a shell command in history. The variable applies to that terminal and programs launched from it.

bash

unset GUARD_API_KEY; until [ -n "${GUARD_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_API_KEY || break; printf "\n"; done; export GUARD_API_KEY

Windows / PowerShell: run these commands in the window you will use to start the client; paste the key into the hidden prompt and press Enter. Set the variable again when opening a new terminal.

powershell

$guardKey = Read-Host "Guard API key" -AsSecureString
$env:GUARD_API_KEY = [System.Net.NetworkCredential]::new("", $guardKey).Password

Start in your project folder

Open a terminal in your project folder. On Windows, right-click the folder and choose Open in Terminal; on macOS, type cd followed by a space and drag the folder into Terminal.
Set GUARD_API_KEY in that window and run codex. If asked to trust a folder, check its path and approve the intended folder.
For your first task, ask: “Read the file list and explain what is in this folder.” Wait for the answer.
Continue in the same conversation: “Now tell me more about one of those files.” This continues the existing task.

bash

codex

Choose another model and effort

For one run, pass the model with -m; for a persistent choice, edit model in your configuration. Check the reasoning levels for the chosen model.

bash

codex -m gpt-6-astra -c model_reasoning_effort="max"

See Models for all reasoning levels and prices. Changing models does not require a new key.

Subagents

To let Codex delegate parts of a task to subagents, add the settings below to the matching config.toml sections. If a section exists, add its fields there rather than duplicating it. Restart Codex.

toml

[features]
multi_agent = true

[agents]
enabled = true

Example task: “Ask a subagent to review three test scenarios and wait for its result.” Subagents use the same Guard provider; their requests count toward the key’s usage.

If connection fails

What you see	What to check
GUARD_API_KEY / missing environment variable	The process did not receive the key. Close the client and launch it from the terminal where you set the variable.
401 / invalid_api_key	The variable contains your full actual gd-key rather than a placeholder; the key is active in your Guard account.
model_not_found	The ID exactly matches the model list. Remove the old Claude catalog and check the /codex/v1 address.
TOML / duplicate key	No duplicated settings or sections. Top-level options appear before [model_providers.guard-codex].
insufficient_balance	Your Guard account has available balance.

If the error repeats, send Guard support the client name and version, model, error text and request time. Do not send your key or entire configuration file.

Codex connects to Guard through your user config.toml. It also needs a local model catalog for a reliable cold start: without it, the first request can be built before Codex finishes fetching /v1/models, leaving some tools disabled.

1. Download the model catalog

Mac / Linux:

bash

mkdir -p ~/.codex
curl -fsSL https://docs.guardrelay.ai/assets/guard-codex-models.json \
  -o ~/.codex/guard-codex-models.json

Windows (PowerShell):

powershell

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
Invoke-WebRequest https://docs.guardrelay.ai/assets/guard-codex-models.json `
  -OutFile "$HOME\.codex\guard-codex-models.json"

2. Add the provider to config.toml

Open (or create) the file ~/.codex/config.toml — on Windows that's %USERPROFILE%\.codex\config.toml — and paste:

toml

model = "claude-sonnet-5-5"
model_provider = "guard"
model_catalog_json = "~/.codex/guard-codex-models.json"

[model_providers.guard]
name = "Guard AI"
base_url = "https://api.guardrelay.ai/v1"
env_key = "GUARD_API_KEY"
wire_api = "responses"

The Codex catalog contains nine Claude models: claude-sonnet-5-5, claude-sonnet-5, claude-opus-5-5, claude-opus-5, claude-opus-4-8, claude-haiku-5-5, claude-haiku-4-5, claude-fable-5-1 and claude-fable-5. Put the desired ID in model; Sonnet 5.5 is the default. The server prompt does not work on every model; those it works on are marked UNLOCK in Guard Code, and the other Claude models of a prompted key work without it.

3. Set the key and run

Windows (PowerShell): run these commands, paste your key at the Guard API key prompt, and press Enter. Input is hidden and is not stored as part of a shell command in history.

powershell

$guardKey = Read-Host "Guard API key" -AsSecureString
$env:GUARD_API_KEY = [System.Net.NetworkCredential]::new("", $guardKey).Password
codex

Mac / Linux: run these commands, paste your key at the Guard API key prompt, and press Enter. Input is hidden and is not stored as part of a shell command in history.

{
unset GUARD_API_KEY
until [ -n "${GUARD_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_API_KEY || break; printf "\n"; done
export GUARD_API_KEY
codex
}

A one-off run without interactive mode:

bash

codex exec "check connection: reply 'ok'"

Kimi, Composer and Grok in Codex

The configuration above uses wire_api = "responses", that is POST /v1/responses.

Family	On `/v1/responses`
Kimi	available: it accepts `model`, `input`, `instructions`, `stream`, `tools`, `tool_choice`, `parallel_tool_calls`, `max_output_tokens`, `reasoning`, `text`, `temperature`, `top_p`, `prompt_cache_key`, `include`, `store`, `truncation` and `metadata`
Composer, Grok	Currently incompatible in Codex 0.155: the client adds unsupported `id` and declares `web_search`/`namespace`; direct `/v1/responses` remains a separate API surface

Codex on a Kimi model

Codex calls the Responses surface, and Kimi serves it. The configuration is the Claude one with two differences: an exact Kimi id in model, and no model catalog. The downloaded guard-codex-models.json describes Claude models only, so leave the model_catalog_json line out for Kimi: with a foreign catalog Codex treats the model as unknown.

toml

model = "k3"
model_provider = "guard"

[model_providers.guard]
name = "Guard AI"
base_url = "https://api.guardrelay.ai/v1"
env_key = "GUARD_API_KEY"
wire_api = "responses"

The key is passed through the GUARD_API_KEY variable. Mac / Linux:

Environment variables

bash · macOS / Linux

export GUARD_API_KEY="gd-your-key-from-bot"
codex

PowerShell · Windows

$env:GUARD_API_KEY = "gd-your-key-from-bot"
codex

Windows (PowerShell):

powershell

$env:GUARD_API_KEY = "gd-your-key-from-bot"
codex

A one-off connection check without interactive mode:

bash

codex exec "check connection: reply 'ok'"

Composer and Grok: current Codex incompatibility

Composer and Grok are currently incompatible with real Codex 0.155. Do not configure them from the API examples in these docs, and do not treat a successful direct /v1/responses call as proof that the IDE works. No separate Codex-path fix has been released.

Separately: the direct Responses API contract

GLM 5.3 in Codex

Install Codex CLI

Follow the official Codex CLI guide. With Node.js installed, use npm and check the version.

bash

npm install -g @openai/codex
codex --version

Get a Guard key

Get a universal gd-… key from the direct API link in @guardapi and choose an API package. Do not put the key in a project, repository, task prompt, or screenshot. Balance and usage are available in your Guard account.

Add a separate provider

Open the user ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml). Put the top-level fields before the first [section], and add the provider table once. Do not add model_context_window, effort, or another family's model catalog.

toml

model = "glm-5.3"
model_provider = "guard-glm"

[model_providers.guard-glm]
name = "GUARD API · GLM"
base_url = "https://api.guardrelay.ai/glm/v1"
env_key = "GUARD_GLM_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

macOS / Linux: enter the key at the hidden prompt. The variable applies only to this terminal and the client started from it.

{
unset GUARD_GLM_API_KEY
until [ -n "${GUARD_GLM_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_GLM_API_KEY || break; printf "\n"; done
export GUARD_GLM_API_KEY

codex -m glm-5.3
}

Windows PowerShell: run these commands in the same window that starts the client. Set the key again after opening a new PowerShell window.

powershell

$guardKey = Read-Host "Guard API key" -AsSecureString
$env:GUARD_GLM_API_KEY = [System.Net.NetworkCredential]::new("", $guardKey).Password

codex -m glm-5.3

Quick check and continuation

Run codex -m glm-5.3 in a test folder.
Send: Read README.md and reply with exactly GUARD_GLM_OK. Change nothing.
Continue in the same conversation by asking for the line without rereading. After exit, use Codex's built-in continue flow for the last task in this folder.
For Flash, start a new task with codex -m glm-5.3-flash.

Models and confirmed capabilities

Model ID	When to use it
`glm-5.3`	Default model; text and coding tasks.
`glm-5.3-flash`	Fast model; at API level it accepts PNG and PDF through all three protocols, and MP4 through Chat Completions only.

Responses streaming, local shell/file tools, and resuming the same session are confirmed.
The client itself executes file, edit, and terminal tools. This profile does not connect Z.AI tools or MCP automatically.
This version was checked with text tasks; its attachment button was not checked. Flash capability at API level does not prove that this particular UI can send a file.
The profile uses OpenAI Responses. The GLM server prompt is off by default for ordinary API access; client setup does not enable it.
Native TXT, DOCX, and XLSX are outside the confirmed GLM contract. Use PDF for documents, or PNG with glm-5.3-flash for images.

If the connection fails

Symptom	What to check
`401 invalid_api_key`	The client received the complete active `gd-…` key; the variable is set in the same process that starts the client.
`404 model_not_found`	The model ID is exactly `glm-5.3` or `glm-5.3-flash`; old GLM IDs, aliases, Turbo, and FlashX are unsupported.
`404` or incorrect path	Base URL is `https://api.guardrelay.ai/glm/v1`. The client appends `/responses`; do not add it twice.
`400 invalid_request`	The documented API format is selected; reasoning, temperature, MCP, or other unconfirmed fields were not copied from an older profile.
`402 insufficient_balance`	Check available balance and unfinished reservations in your Guard account.
Codex asks for OpenAI login	Check `model_provider = "guard-glm"`, `requires_openai_auth = false`, and the `GUARD_GLM_API_KEY` variable.

Gemini in Codex

Install Codex CLI

Follow the official Codex CLI guide. With Node.js installed, use npm and check the version.

bash

npm install -g @openai/codex
codex --version

Get a Guard key

Add a separate provider

toml

model = "gemini-4-argon"
model_provider = "guard-gemini"

[model_providers.guard-gemini]
name = "GUARD API · Gemini"
base_url = "https://api.guardrelay.ai/v1"
env_key = "GUARD_GEMINI_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

macOS / Linux: enter the key at the hidden prompt. The variable applies only to this terminal and the client started from it.

{
unset GUARD_GEMINI_API_KEY
until [ -n "${GUARD_GEMINI_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_GEMINI_API_KEY || break; printf "\n"; done
export GUARD_GEMINI_API_KEY
codex -m gemini-4-argon
}

Windows PowerShell: run these commands in the same window that starts the client. Set the key again after opening a new PowerShell window.

powershell

$guardKey = Read-Host "Guard API key" -AsSecureString
$env:GUARD_GEMINI_API_KEY = [System.Net.NetworkCredential]::new("", $guardKey).Password
codex -m gemini-4-argon

Quick check and continuation

Run codex -m gemini-4-argon in a test folder.
Send: Read README.md and reply with exactly GUARD_GEMINI_OK. Change nothing.
Continue in the same conversation by asking for the line without rereading. After exit, use Codex's built-in continue flow for the last task in this folder.
For another model, start a new task, for example with codex -m gemini-3.8-flash.

Gemini models and capabilities

Model ID	Input and window
`gemini-4-argon`	Text, images, PDF; 1,048,576-token window, shared by input and answer.
`gemini-3.8-flash`	Text, images, PDF; 1,048,576-token window for input.

Codex itself executes the local file and shell tools; it sends the task history with every request.
The Guard catalog takes text, images, and PDF as input and returns text. How to send a file or an image depends on the client's interface; this guide does not describe attachments.
The profile uses OpenAI Responses. The server prompt is a separate setting of the Gemini family: it applies only when the key has the entitlement and the option is on; client setup does not enable it.

If the connection fails

Symptom	What to check
`401 invalid_api_key`	The client received the complete active `gd-…` key; the variable is set in the same process that starts the client.
`404 model_not_found`	The model ID is an exact ID from the table above or the short name `gemini`; other spellings are unsupported.
`404` or incorrect path	Base URL is `https://api.guardrelay.ai/v1`. The client appends `/responses`; do not add it twice.
`400 invalid_request`	The documented API format is selected; extra settings from an older profile were not copied: reasoning, temperature, MCP, and others.
`402 insufficient_credit`	Check available balance and unfinished reservations in your Guard account.
Codex asks for OpenAI login	Check `model_provider = "guard-gemini"`, `requires_openai_auth = false`, and the `GUARD_GEMINI_API_KEY` variable.

Muse in Codex

Install Codex CLI

Follow the official Codex CLI guide. With Node.js installed, use npm and check the version.

bash

npm install -g @openai/codex
codex --version

Get a Guard key

Add a separate provider

toml

model = "muse-wonder-1.0"
model_provider = "guard-muse"

[model_providers.guard-muse]
name = "GUARD API · Muse"
base_url = "https://api.guardrelay.ai/v1"
env_key = "GUARD_MUSE_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

macOS / Linux: enter the key at the hidden prompt. The variable applies only to this terminal and the client started from it.

{
unset GUARD_MUSE_API_KEY
until [ -n "${GUARD_MUSE_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_MUSE_API_KEY || break; printf "\n"; done
export GUARD_MUSE_API_KEY
codex -m muse-wonder-1.0
}

Windows PowerShell: run these commands in the same window that starts the client. Set the key again after opening a new PowerShell window.

powershell

$guardKey = Read-Host "Guard API key" -AsSecureString
$env:GUARD_MUSE_API_KEY = [System.Net.NetworkCredential]::new("", $guardKey).Password
codex -m muse-wonder-1.0

Quick check and continuation

Run codex -m muse-wonder-1.0 in a test folder.
Send: Read README.md and reply with exactly GUARD_MUSE_OK. Change nothing.
Continue in the same conversation by asking for the line without rereading. After exit, use Codex's built-in continue flow for the last task in this folder.
For another model, start a new task, for example with codex -m muse-spark-1.3.

Muse models and capabilities

Model ID	Input and window
`muse-wonder-1.0`	Text, images, PDF; 1,048,576-token window.
`muse-spark-1.3`	Text, images, PDF; 1,048,576-token window.
`muse-spark-1.2`	Text, images, PDF; 1,048,576-token window.

Codex itself executes the local file and shell tools; it sends the task history with every request.
The Guard catalog takes text, images, and PDF as input and returns text. How to send a file or an image depends on the client's interface; this guide does not describe attachments.
The profile uses OpenAI Responses. The server prompt is a separate setting of the Muse family: it applies only when the key has the entitlement and the option is on; client setup does not enable it.

If the connection fails

Symptom	What to check
`401 invalid_api_key`	The client received the complete active `gd-…` key; the variable is set in the same process that starts the client.
`404 model_not_found`	The model ID is an exact ID from the table above or the short name `muse`; other spellings are unsupported.
`404` or incorrect path	Base URL is `https://api.guardrelay.ai/v1`. The client appends `/responses`; do not add it twice.
`400 invalid_request`	The documented API format is selected; extra settings from an older profile were not copied: reasoning, temperature, MCP, and others.
`402 insufficient_credit`	Check available balance and unfinished reservations in your Guard account.
Codex asks for OpenAI login	Check `model_provider = "guard-muse"`, `requires_openai_auth = false`, and the `GUARD_MUSE_API_KEY` variable.