# Codex CLI (/docs/integrations/codex-cli)

Point OpenAI Codex CLI at codai through a custom model provider on the Responses API, plus the codai MCP server.

Codex CLI talks to codai through a **custom model provider** in `~/.codex/config.toml`: base URL `https://ai.codai.ro/v1`, wire API `responses`, your key from an environment variable and the model `codai`.

<Callout type="warn" title="Not yet verified end to end">
This setup follows Codex's configuration schema and codai's [Responses API](../gateway/wire-formats.mdx#openai-responses-api) support, but we have not yet run a full Codex agent session against codai. Codex edits files with a **freeform** `apply_patch` tool; codai's Responses layer forwards only **function** tools, so file edits may fail or fall back to shell commands. If something breaks, tell us at [hub.codai.ro](https://hub.codai.ro) support and use a [tested tool](./index.mdx) in the meantime.
</Callout>

## Before you start [#before-you-start]

- A codai key from [hub.codai.ro](https://hub.codai.ro) → **Keys → Create key** (details in the [quickstart](../gateway/index.mdx)).
- Codex CLI installed. Recent versions accept only `wire_api = "responses"` for custom providers; `"chat"` is rejected.

Set the key in the shell that starts Codex:

```powershell tab="PowerShell"
$env:CODAI_API_KEY = 'codai_xxxxxxxx'
```

```bash tab="bash"
export CODAI_API_KEY='codai_xxxxxxxx'
```

## Configure the provider [#configure-the-provider]

```toml title="~/.codex/config.toml"
model = "codai"
model_provider = "codai"

[model_providers.codai]
name = "codai"
base_url = "https://ai.codai.ro/v1"
env_key = "CODAI_API_KEY"
wire_api = "responses"
```

- `env_key` names the variable Codex reads; the key itself never goes into the file.
- Codex appends `/responses` to `base_url`, so keep `/v1` and nothing after it.
- To keep your OpenAI setup as the default, put `model` and `model_provider` in a profile (`[profiles.codai]`) and start with `codex --profile codai`.
- Codex has no built-in metadata for the name `codai` and prints a "fallback metadata" warning. It is harmless.

## MCP [#mcp]

```toml title="~/.codex/config.toml"
[mcp_servers.codai]
url = "https://ai.codai.ro/mcp"
bearer_token_env_var = "CODAI_API_KEY"
```

The same key authenticates the codai MCP server; tools are listed on [clients](../gateway/clients.mdx#mcp-server).

## What works and what does not [#what-works-and-what-does-not]

| Feature | With codai |
| --- | --- |
| Chat, function tools, streaming | Expected to work — Responses requests are translated to Chat Completions inside the gateway |
| `reasoning.effort` | Mapped onto codai effort tiers (`xhigh` → `max`) |
| `apply_patch` (freeform tool) | Not forwarded — see the warning above |
| `previous_response_id`, background mode, built-in `web_search` | Rejected with `400 bad_request` |
| Reasoning summaries | Not returned |

## Troubleshooting [#troubleshooting]

- **`404`** — `base_url` lacks `/v1` or has `/responses` on it.
- **`401 invalid_api_key`** — `CODAI_API_KEY` is not set in the environment Codex started from.
- **`400 bad_request` mentioning `previous_response_id`** — this Codex build chains responses; codai needs the full input on every request.
- **`429`** — read `error.code`; see [limits and pricing](../gateway/limits-pricing.mdx).

## Sources [#sources]

Checked 2026-10-18 against the Codex source (`codex-rs` config and provider types).

- [OpenAI Codex — repository](https://github.com/openai/codex)
- [Codex — removal of `wire_api = "chat"`](https://github.com/openai/codex/discussions/7782)