> ## Documentation Index
> Fetch the complete documentation index at: https://gateway.consus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> Use OpenAI Codex CLI with ITAR restricted data

<Warning>
  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.
</Warning>

## Before you start

You need:

* **Codex CLI installed.** v0.128.0 or newer. See the [Codex docs](https://developers.openai.com/codex) 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 profile

If you use Codex for anything else (personal OpenAI account or another organization) we recommend setting up an isolated Consus Gateway profile. This keeps your Consus credentials and settings fully isolated.

Add this alias to your shell profile (`~/.zshrc` or `~/.bashrc`):

```bash theme={null}
alias codex-gateway='CODEX_HOME=~/.codex-gateway codex'
```

Then `source ~/.zshrc` (or `source ~/.bashrc`) to pick up the alias.

Create the profile directory (Codex requires it to exist before launch):

```bash theme={null}
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`):

```bash theme={null}
export CONSUS_API_KEY="<CONSUS_API_KEY>"
```

Replace `<CONSUS_API_KEY>` with your actual key, then `source ~/.zshrc`.

Create `~/.codex-gateway/config.toml` with:

```toml theme={null}
model = "gpt-5.4:itar"
model_provider = "consus"
model_reasoning_effort = "medium"

[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" }

[profiles.gpt41]
model = "gpt-4.1:il5+itar"
model_reasoning_effort = "none"

[profiles.mini]
model = "gpt-4.1-mini:il5+itar"
model_reasoning_effort = "none"
```

`codex-gateway` launches with gpt-5.4 by default. To use a different model: `codex-gateway --profile gpt41` or `codex-gateway --profile mini`.

## Step 3: Start your session

```bash theme={null}
cd /path/to/your/project
codex-gateway
```

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

## Step 4: Verify

The Codex header should show `gpt-5.4` 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.

## What gets served

Every request from Codex CLI — coding turns, reasoning, tool use — is served by **GPT-5.4 on AWS GovCloud (Bedrock) with ITAR authorization**. 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`](/endpoints/responses).

## 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_reasoning_effort`
: Default reasoning effort for gpt-5.4's extended thinking. One of `none`, `low`, `medium`, `high`, or `xhigh`. `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](/rate-limits#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](/integrations/claude-code) for Claude models, or [OpenCode](/integrations/opencode) for the multi-provider Chat API.

**`Model metadata for gpt-5.4:itar not found. Defaulting to fallback metadata`** — Cosmetic. Codex's local model registry doesn't recognize Consus's composite IDs and falls back to defaults. Safe to ignore.