# Codex

Source: https://aiand-docs-staging.pages.dev/integrations/codex/

[Codex](https://developers.openai.com/codex) talks to the OpenAI Responses API. ai& exposes an OpenAI-compatible `/v1/responses` endpoint, so any tool-calling model in our [catalog](/models/catalog/) can drive the agent loop.

<Aside type="note">
  Codex 0.141+ speaks the **Responses API only** — the older chat-completions wire was removed — so `wire_api = "responses"` is required in the config below.
</Aside>

## 1. Install Codex

Prerequisite: [Node.js 18 or newer](https://nodejs.org/).

<Tabs syncKey="os">
<TabItem label="macOS / Linux">

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

Confirm the install — `codex --version` should print a version number:

```bash
codex --version
```

</TabItem>
<TabItem label="Windows (PowerShell)">

```powershell
npm install -g @openai/codex
```

Confirm the install — `codex --version` should print a version number:

```powershell
codex --version
```

</TabItem>
</Tabs>

## 2. Set your API key

The config below reads your key from the `AIAND_API_KEY` environment variable, so Codex never stores it on disk.

<Tabs syncKey="os">
<TabItem label="macOS / Linux">

```bash
export AIAND_API_KEY="sk-your-aiand-api-key"
```

Add that line to your `~/.zshrc` or `~/.bashrc` to persist it across terminals.

</TabItem>
<TabItem label="Windows (PowerShell)">

```powershell
$env:AIAND_API_KEY = "sk-your-aiand-api-key"
```

To persist it across sessions: `setx AIAND_API_KEY "sk-your-aiand-api-key"` (reopen the terminal afterward).

</TabItem>
</Tabs>

## 3. Add an ai& profile

Codex 0.141+ keeps each profile in its own file, `~/.codex/<name>.config.toml`. Create `~/.codex/aiand.config.toml`:

```toml
model = "moonshotai/kimi-k3"
model_reasoning_effort = "high"
model_provider = "aiand"
web_search = "disabled"

[model_providers.aiand]
name = "ai&"
base_url = "https://api.aiand.com/v1"
wire_api = "responses"

[model_providers.aiand.auth]
command = "sh"
args = ["-c", "echo $AIAND_API_KEY"]

[tools]
view_image = false

[features]
unified_exec = false
apps = false
browser_use = false
browser_use_external = false
computer_use = false
image_generation = false
multi_agent = false
in_app_browser = false
```

The `model_reasoning_effort` line matters. Codex's built-in default is `medium`, but supported reasoning levels vary by model, and a level a model does not list in its `reasoning_efforts` is rejected. `moonshotai/kimi-k3` accepts `high`, which makes it a safe, deliberate choice here; check `reasoning_efforts` in [`GET /v1/models`](/api/models/) before switching models.

The `[model_providers.aiand.auth]` block is what makes Codex fetch ai&'s model catalog. Codex 0.157 and later only ask a custom provider for its model list when the provider is authenticated through a command; with a plain `env_key = "AIAND_API_KEY"` the request still works, but Codex falls back to its bundled metadata, `/model` shows an "Unknown model" warning, and the reasoning levels each ai& model supports are not offered. The command just prints the key from the environment variable you set in step 2.

The `[features]` block matters too. ai& serves standard **function tools** — which is all the coding agent loop needs — but not Codex's hosted/built-in tools (web search, image generation, browser & computer control) or its grouped-tool wrapper. Left on, Codex can send tool types the API rejects (`tool type … not supported`), so the profile turns them off.

Save it in one step:

<Tabs syncKey="os">
<TabItem label="macOS / Linux">

```bash
mkdir -p ~/.codex && cat > ~/.codex/aiand.config.toml <<'EOF'
model = "moonshotai/kimi-k3"
model_reasoning_effort = "high"
model_provider = "aiand"
web_search = "disabled"

[model_providers.aiand]
name = "ai&"
base_url = "https://api.aiand.com/v1"
wire_api = "responses"

[model_providers.aiand.auth]
command = "sh"
args = ["-c", "echo $AIAND_API_KEY"]

[tools]
view_image = false

[features]
unified_exec = false
apps = false
browser_use = false
browser_use_external = false
computer_use = false
image_generation = false
multi_agent = false
in_app_browser = false
EOF
```

</TabItem>
<TabItem label="Windows (PowerShell)">

```powershell
New-Item -ItemType Directory -Force -Path $HOME\.codex | Out-Null
@'
model = "moonshotai/kimi-k3"
model_reasoning_effort = "high"
model_provider = "aiand"
web_search = "disabled"

[model_providers.aiand]
name = "ai&"
base_url = "https://api.aiand.com/v1"
wire_api = "responses"

[model_providers.aiand.auth]
command = "cmd"
args = ["/c", "echo %AIAND_API_KEY%"]

[tools]
view_image = false

[features]
unified_exec = false
apps = false
browser_use = false
browser_use_external = false
computer_use = false
image_generation = false
multi_agent = false
in_app_browser = false
'@ | Set-Content -Encoding utf8 $HOME\.codex\aiand.config.toml
```

</TabItem>
</Tabs>

<Aside type="tip">
  Any model with the `tool_calling` capability in the [catalog](/models/catalog/) works — swap the `model` line to switch, and set `model_reasoning_effort` to a level listed in that model's `reasoning_efforts`.
</Aside>

## 4. Run Codex

```bash
codex --profile aiand
```

Or non-interactively — `--sandbox workspace-write` lets the agent edit files in the workspace:

```bash
codex exec --profile aiand --sandbox workspace-write "Fix the failing test in src/math.js"
```

## Verify

Probe the wire-level path from the shell — a match means the key authenticates and the model is on your org:

<Tabs syncKey="os">
<TabItem label="macOS / Linux">

```bash
curl -sS https://api.aiand.com/v1/models \
  -H "Authorization: Bearer $AIAND_API_KEY" \
  | grep -o 'moonshotai/kimi-k3'
```

</TabItem>
<TabItem label="Windows (PowerShell)">

```powershell
(Invoke-RestMethod https://api.aiand.com/v1/models `
  -Headers @{ Authorization = "Bearer $env:AIAND_API_KEY" }).data.id `
  | Select-String "moonshotai/kimi-k3"
```

</TabItem>
</Tabs>

<Aside type="caution">
  A few things to expect:

  - **`ERROR: Reconnecting…` five times, then `We're currently experiencing high demand`** — usually not load. This is how Codex surfaces a model rejecting the request, most often a `model_reasoning_effort` the model doesn't support (Codex defaults to `medium` when the line is missing). Set it to a level the model supports — `high` works for every model recommended here.
  - **`tool type … not supported`** — a built-in tool is still enabled. Make sure the `[features]` block and `web_search = "disabled"` are present in your profile.
  - **`warning: Model metadata for '…' not found`**, or **"Unknown model"** in `/model` — Codex did not fetch the model list from ai&. On Codex older than 0.144, upgrade. On 0.157 and later, make sure the profile authenticates through `[model_providers.aiand.auth]` as above rather than `env_key`: since [openai/codex#46561](https://github.com/openai/codex/pull/46561) an `env_key` provider only fetches a catalog when `model_catalog_url` is set and the `api_key_model_discovery` feature is on. With the command-auth profile Codex receives real model metadata (context windows, reasoning levels, tool capabilities), so `/model` shows correct values with no local `model_catalog_json` file needed.
  - **``Automatic approval review failed: … The model `codex-auto-review` does not exist``** — Codex's automatic approval review runs on the model the ai& model list names for it, so it only works once Codex has fetched that list. Use the command-auth profile above, or have Codex ask you instead: pick that reviewer in `/permissions`, or set `approvals_reviewer = "user"` in the profile.
  - **`unsupported call: apply_patch` in the logs** — harmless. Codex falls back to shell commands to edit files when the host doesn't expose its patch tool.
</Aside>