Codex CLI

Use of Codex CLI with the Consus Gateway is appropriate when handling ITAR data. However, the gateway does not control client-side behavior including local tool execution, file access, outbound destinations, etc. Client-side behavior is the customer’s responsibility.

Before you start

You need:

Codex CLI installed. v0.146.0 or newer (this guide was verified on 0.147; 0.154 is current). See the Codex docs if you don’t have it yet.
A Consus API key. Get one from your Consus admin.

Step 1 (recommended): Set up an isolated Consus home

If you use Codex for anything else (personal OpenAI account or another organization) we recommend giving the gateway its own Codex home directory. This keeps your Consus credentials, catalog, and settings fully isolated from any other Codex use. Add this alias to your shell profile (~/.zshrc or ~/.bashrc):

alias codex-gateway='CODEX_HOME=~/.codex-gateway codex'

Then source ~/.zshrc (or source ~/.bashrc) to pick up the alias. Create the directory (Codex requires it to exist before launch):

mkdir -p ~/.codex-gateway

The rest of this guide uses codex-gateway and ~/.codex-gateway/ throughout. If you skip this step, substitute codex and ~/.codex/.

Step 2: Configure your gateway settings

Export your Consus API key in your shell profile (~/.zshrc or ~/.bashrc):

export CONSUS_API_KEY="<CONSUS_API_KEY>"

Replace <CONSUS_API_KEY> with your actual key, then source ~/.zshrc. Create ~/.codex-gateway/config.toml with:

model = "gpt-5.4:itar"
model_provider = "consus"
model_reasoning_effort = "medium"
web_search = "disabled"

[model_providers.consus]
name = "Consus Gateway"
base_url = "https://api.consus.io/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "CONSUS_API_KEY" }

Step 3 (optional): Generate the model catalog

This step is optional. Codex works against the gateway without it: the config in Step 2 is enough, and you can pick a model at launch with codex-gateway -m <id> or a profile (Step 4). The catalog adds two things: the /model picker lists Consus models so you can switch mid-session, and Codex knows each model’s real context window instead of a conservative fallback, which matters for the 1M-context GPT-5.6 models. Skip it and nothing else in this guide changes.

Codex only lets you switch models with /model if the model is in its catalog, and it uses catalog metadata for context-window sizing and the reasoning-effort picker. Consus’s composite IDs are not in the built-in catalog, so generate one. Save the script below as ~/.codex-gateway/make-catalog.py and run it once:

python3 ~/.codex-gateway/make-catalog.py

import json, subprocess, copy, sys, os

# Consus composite ID -> (bundled template slug, display name, context window, allowed efforts)
MODELS = {
    "gpt-5.6-sol:itar":       ("gpt-5.6-sol",   "GPT-5.6 Sol (ITAR)",        922000,  ["low", "medium", "high", "xhigh"]),
    "gpt-5.6-terra:itar":     ("gpt-5.6-terra", "GPT-5.6 Terra (ITAR)",      1000000, ["low", "medium", "high", "xhigh"]),
    "gpt-5.6-luna:itar":      ("gpt-5.6-luna",  "GPT-5.6 Luna (ITAR)",       1000000, ["low", "medium", "high", "xhigh"]),
    "gpt-5.4:itar":           ("gpt-5.4",       "GPT-5.4 (ITAR)",            272000,  ["low", "medium", "high", "xhigh"]),
    "gpt-5.1:itar":           ("gpt-5.4",       "GPT-5.1 (ITAR)",            272000,  ["low", "medium", "high"]),
    "gpt-4.1:il5+itar":       ("gpt-5.4-mini",  "GPT-4.1 (IL5 + ITAR)",      300000,  []),
    "gpt-4.1-mini:il5+itar":  ("gpt-5.4-mini",  "GPT-4.1 mini (IL5 + ITAR)", 300000,  []),
}

bundled = json.loads(subprocess.check_output(["codex", "debug", "models", "--bundled"]))
by_slug = {m["slug"]: m for m in bundled["models"]}
out = []
for i, (cid, (tmpl, name, ctx, efforts)) in enumerate(MODELS.items()):
    m = copy.deepcopy(by_slug[tmpl])
    m.update({
        "slug": cid, "display_name": name, "description": "Consus Gateway",
        "priority": i + 1, "visibility": "list",
        "context_window": ctx, "max_context_window": ctx,
        "supported_reasoning_levels": [l for l in m["supported_reasoning_levels"] if l["effort"] in efforts],
        "default_reasoning_level": "medium" if efforts else "none",
        "additional_speed_tiers": [], "service_tiers": [], "availability_nux": None, "upgrade": None,
        "supports_search_tool": False,
    })
    out.append(m)

path = os.path.expanduser(sys.argv[1] if len(sys.argv) > 1 else "~/.codex-gateway/consus-models.json")
with open(path, "w") as f:
    json.dump({"models": out}, f, indent=2)
print(f"wrote {len(out)} models to {path}")

The script clones the built-in entries from your installed Codex (which is why it is a script rather than a static file: the entries carry version-specific Codex instructions) and rewrites them as the Consus IDs with the gateway’s context windows and supported efforts. Re-run it after updating Codex. Trim the MODELS table to the models your authorization allows. Confirm the catalog loaded:

codex-gateway -c 'model_catalog_json="~/.codex-gateway/consus-models.json"' debug models \
  | python3 -c "import sys,json; print([m['slug'] for m in json.load(sys.stdin)['models']])"

You should see only the Consus IDs. Then point config.toml at the file by adding this line at the top level:

model_catalog_json = "~/.codex-gateway/consus-models.json"

Add this line only after the file exists: Codex refuses to start when model_catalog_json points at a missing file.

Step 4 (optional): Profiles for launch defaults

/model switches models within a session. If you also want to launch on a different model, use a profile file: Codex loads config.toml, then overlays <name>.config.toml from the same directory when you pass --profile <name>. For example, ~/.codex-gateway/sol.config.toml:

model = "gpt-5.6-sol:itar"
model_reasoning_effort = "high"

Then codex-gateway --profile sol. Any Consus ID from the catalog works the same way.

Older guides put profiles inline as [profiles.NAME] tables inside config.toml. Codex 0.146+ treats those as legacy and warns that they “can no longer be written”; the file-per-profile layout above is the supported form.

Step 5: Start your session

cd /path/to/your/project
codex-gateway

That’s it. Every request now routes through Consus Gateway with ITAR authorization.

Step 6: Verify

The Codex header should show gpt-5.4:itar and your working directory. Send a simple message:

> hi

You should get a normal response within a few seconds. If you see unexpected status errors instead, check the troubleshooting section below. Then type /model. The picker should list the Consus models from your catalog (GPT-5.6 Sol, Terra, Luna, GPT-5.4, GPT-5.1, GPT-4.1, GPT-4.1 mini) with their reasoning-effort options. Pick one to switch mid-session; the header updates to the new composite ID.

What gets served

Every request from Codex CLI — coding turns, reasoning, tool use — is served by the model shown in the header, at the compliance level in its ID. With the default config that is GPT-5.4 on AWS GovCloud (Bedrock) with ITAR authorization; GPT-5.1 and GPT-5.6 Sol route to Azure Government OpenAI, and the other GPT-5.6 models to Bedrock. The compliance boundary is enforced at the gateway architecture level. For the full Responses API surface (multimodal input, streaming behavior, governance flags, tool-use shape), see POST /v1/responses.

Web search is not available

Codex 0.146 and newer declares OpenAI’s hosted web_search tool on every request unless told otherwise (the setting defaults to "cached", and to "live" under full-access sandboxes). That tool is server-executed outside the compliance boundary, so the gateway removes it from every request before dispatch — Codex works normally, but the model has no web access and may tell you so when asked about live information. Treat any “current” facts it produces without a tool as unverified. The web_search = "disabled" line in the config above stops Codex declaring the tool at all. The accepted values are disabled, cached, indexed, and live; the older [tools]-table boolean web_search = false parses but is ignored by Codex 0.146+.

What each setting does

model : The composite model ID Codex sends to the gateway. gpt-5.4:itar resolves to GPT-5.4 on AWS GovCloud (Bedrock) with ITAR enforcement. Use /v1/models to list other available composite IDs. model_provider : Selects which [model_providers.X] block Codex uses. Must match the block name below. model_catalog_json : Path to the catalog generated in Step 3. It is what makes /model list Consus IDs, and it supplies each model’s context window and reasoning-effort options. Without it Codex falls back to conservative metadata and compacts history far earlier than the 1M-context models need. web_search = "disabled" : Stops Codex declaring the hosted web search tool (see below). model_reasoning_effort : Default reasoning effort for the model’s extended thinking. One of none, low, medium, high, or xhigh (Codex also accepts minimal, which the gateway forwards as-is). medium is the recommended default — it handles typical coding turns (file edits, multi-step tool plans, integration writing) in a few seconds. Bump to high or xhigh for genuinely hard problems (architecture exploration, tricky debugging); expect multi-minute latency there. Requests are capped at 5 minutes — turns that exceed it return a 504 (see Request Timeout). Can be overridden per request. base_url : Routes Codex’s requests to the gateway. The Responses API lives at /v1/responses. wire_api = "responses" : Tells Codex to use OpenAI’s Responses API wire format env_http_headers : Reads CONSUS_API_KEY from your shell environment and sends it as the x-api-key header on every request. The gateway authenticates with x-api-key, not Authorization: Bearer, so the alternative env_key setting will not work.

Troubleshooting

unexpected status 404 Not Found, url: ...v1/responses — Your Codex version predates v0.128.0, or the gateway you’re hitting predates the /v1/responses endpoint. Confirm with codex --version. unexpected status 401 — x-api-key is missing or wrong. Verify echo $CONSUS_API_KEY returns your key in the same shell session you launched codex-gateway from, and that the env_http_headers line in config.toml is present (not env_key). unexpected status 400 ... not available on /v1/responses — You picked a non-GPT model in /model (e.g., Claude). The Responses endpoint is GPT-only. Use Claude Code for Claude models, or OpenCode for the multi-provider Chat API. unexpected status 400 on every gpt-5.4 turn with Codex ≥0.146 — Gateway versions before 2026-08 rejected the hosted web_search tool Codex now sends by default. Current gateways strip the tool automatically; if you’re pinned to an older gateway, set web_search = "disabled" in config.toml (see above). stream disconnected before completion: failed to parse ResponseCompleted on gpt-5.1/gpt-4.1 with Codex ≥0.146 — The model answers, then the turn errors at the end of the stream. Azure reports a null cache-write counter in the terminal usage frame, which new Codex versions reject; gateways from 2026-08 onward normalize it. Fixed by a gateway upgrade — there is no client-side workaround. Model metadata for gpt-5.4:itar not found. Defaulting to fallback metadata — The catalog from Step 3 is missing or model_catalog_json points at the wrong path. Codex still works, but with a small default context window and no /model entries for Consus. Re-run the generator and check the path. /model shows only OpenAI’s stock models — Same cause: the catalog did not load. Run the debug models check from Step 3. Error loading configuration: No such file or directory (os error 2) — model_catalog_json points at a file that does not exist. Run the generator from Step 3, or remove the line. failed to parse model_catalog_json ... missing field — The catalog was written for a different Codex version. Re-run the generator with the Codex you have installed. profiles contains legacy config profile tables — Your config.toml still has inline [profiles.NAME] tables. Move each one into ~/.codex-gateway/NAME.config.toml as shown in Step 4.

Product

Getting Started

API Reference

Integrations

Before you start

Step 1 (recommended): Set up an isolated Consus home

Step 2: Configure your gateway settings

Step 3 (optional): Generate the model catalog

Step 4 (optional): Profiles for launch defaults

Step 5: Start your session

Step 6: Verify

What gets served

Web search is not available

What each setting does

Troubleshooting

​Before you start

​Step 1 (recommended): Set up an isolated Consus home

​Step 2: Configure your gateway settings

​Step 3 (optional): Generate the model catalog

​Step 4 (optional): Profiles for launch defaults

​Step 5: Start your session

​Step 6: Verify

​What gets served

​Web search is not available

​What each setting does

​Troubleshooting

Before you start

Step 1 (recommended): Set up an isolated Consus home

Step 2: Configure your gateway settings

Step 3 (optional): Generate the model catalog

Step 4 (optional): Profiles for launch defaults

Step 5: Start your session

Step 6: Verify

What gets served

Web search is not available

What each setting does

Troubleshooting