> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/integrations/coding/codex.md).

# Codex CLI

## Codex CLI Integration Guide

This document explains how to integrate [Codex CLI](https://github.com/openai/codex) — OpenAI's official terminal coding agent — with the AVIS OpenAI-compatible API.

### What is Codex CLI

Codex CLI is an open-source coding agent that runs in your terminal, reads/edits files, and executes shell commands. It speaks OpenAI's Responses API (and Chat Completions), so it works against AVIS through the OpenAI-compatible surface — AVIS's `/responses` endpoint is specifically the Codex CLI/Desktop-style surface.

### 1) Install Codex CLI

```bash
# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

# macOS / Linux (curl)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

Verify:

```bash
which codex
```

### 2) Get an AVIS API key

See Authentication — sign in at [avis.xyz](https://avis.xyz), go to **Settings → API Keys**, and create one.

### 3) Configure AVIS as a model provider

Set the key in your shell:

```bash
export AVIS_API_KEY="<your-avis-api-key>"
```

Edit `~/.codex/config.toml`:

```toml
model_provider = "avis"
model = "claude-sonnet-5"

[model_providers.avis]
name = "AVIS"
base_url = "https://api.avis.xyz/api/openai/v1"
env_key = "AVIS_API_KEY"
wire_api = "responses"
```

Notes:

* `env_key` names the environment variable Codex reads the key from — Codex sends it as `Authorization: Bearer <value>`, which AVIS accepts as an alternative to `x-api-key` (see Authentication).
* `wire_api = "responses"` targets AVIS's `/responses` endpoint — the Codex CLI/Desktop-native shape. Use `wire_api = "chat"` instead to target `/chat/completions` if you specifically need Chat Completions semantics; for Codex CLI itself, `"responses"` is the one to use.
* `model_provider` must match the table name under `[model_providers.*]` (`avis` here) — Codex routes every call through whichever provider that top-level key names.
* You cannot name a custom provider `openai`, `ollama`, or `lmstudio` — those ids are reserved for Codex's built-ins.

### 4) Pick a model

Query the live catalog for exact current IDs — this surface uses AVIS's flat canonical id (no `anthropic/`/`openai/` prefix):

```bash
curl https://api.avis.xyz/api/openai/v1/models \
  -H "x-api-key: $AVIS_API_KEY" | jq '.data[].id'
```

Set `model` (top-level, §3) to one of these, e.g. `claude-sonnet-5`, `claude-opus-5`, `gpt-5.5`.

### 5) Run Codex CLI

```bash
cd your-project
codex
```

On first run in a new folder, Codex asks whether to trust the project — accept it to let Codex read/edit/execute in that directory. To pre-approve a project non-interactively, add it to `config.toml`:

```toml
[projects."/absolute/path/to/your/project"]
trust_level = "trusted"
```

### 6) Troubleshooting

* `warning: Model metadata for '<model>' not found. Defaulting to fallback metadata; this can degrade performance and cause issues.` (and a matching `failed to refresh available models` error in logs)
  * Codex tries to fetch a model catalog from the provider to learn context window/reasoning support for the configured model, and expects a `{"models": [...]}` shape. AVIS's `GET /models` returns the OpenAI-standard `{"object": "list", "data": [...]}` shape instead, so Codex falls back to generic metadata.
  * **This does not block requests** — text generation still works (see the Minimal E2E Checklist below) — but reasoning-effort/context-limit behavior may be less accurate than with a provider Codex has full metadata for.
* `401 Unauthorized`
  * `AVIS_API_KEY` isn't exported in the shell Codex was launched from — `env_key` resolves empty if the var isn't set there.
  * AVIS key is invalid or revoked — verify directly: `curl -H "x-api-key: $AVIS_API_KEY" https://api.avis.xyz/api/openai/v1/models`.
* `400` / request rejected immediately
  * `wire_api` doesn't match what you intended — `"responses"` and `"chat"` hit different AVIS endpoints (`/responses` vs `/chat/completions`) with different request shapes; mismatching `wire_api` against the endpoint you meant fails at the request-shape level, not auth.
* `404` / model not found
  * The `model` value doesn't match AVIS's catalog exactly (flat id, no prefix) — re-check against `GET /api/openai/v1/models` (§4).
* `403` with a valid key
  * Account balance is depleted — see Errors.
* Codex still calls the real OpenAI API instead of AVIS
  * `model_provider` at the top level of `config.toml` must equal the table name under `[model_providers.*]` — a typo here silently falls back to Codex's built-in `openai` provider instead of erroring.

### 7) Minimal End-to-End Checklist

1. AVIS API key created (§2) and exported as `AVIS_API_KEY`.
2. `~/.codex/config.toml` has `model_provider = "avis"`, a matching `[model_providers.avis]` block with `base_url`/`env_key`/`wire_api`, and a `model` confirmed against AVIS's catalog (§3–4).
3. Project trusted (§5).
4. `codex` starts and a message returns model output from the AVIS-backed model.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avis.xyz/integrations/coding/codex.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.