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

# Codex setup

> Run the Codex CLI with a Pearl model through the Responses API.

## Before you start

Complete organization setup, make sure your account has inference credit, and create a key on the [API Keys page](https://platform.pearlresearch.ai/api-keys). Most coding agents need a tool-capable chat model; Aider's basic edit workflow does not require native tool calling. Image input and reasoning support depend on the model. These terminal examples use Bash or Zsh on macOS, Linux, or Windows through WSL.

Install the Codex CLI using its official guide. Use version 0.134.0 or later, which loads profile files and supports custom provider capabilities, including `remote_compaction = "unsupported"`. [Installation instructions](https://learn.chatgpt.com/docs/codex/cli).

```bash theme={null}
codex --version
```

## Get your connection settings

Open [Integrations](https://platform.pearlresearch.ai/integrations), select a model, then choose Codex. The screen uses your organization's region. The examples below use the public global endpoint; replace it with your regional endpoint and replace `YOUR_MODEL_ID` with the full model ID shown there. Choose one of the models listed for this integration.

Set your Pearl API key in the terminal where you run Codex:

```bash theme={null}
export PEARL_API_KEY="YOUR_PEARL_API_KEY"
```

## Configure Codex

Save the Pearl provider and settings as the profile file \~/.codex/pearl.config.toml. Codex applies it on top of \~/.codex/config.toml only when you start with `--profile pearl`, so your usual provider selection stays intact. The key is read from PEARL\_API\_KEY; do not paste it into the configuration file.

```toml ~/.codex/pearl.config.toml (create this profile file) theme={null}
model_provider = "pearl"
model = "YOUR_MODEL_ID"
web_search = "disabled"
model_reasoning_summary = "none"

[model_providers.pearl]
name = "Pearl"
base_url = "https://inference.pearlresearch.ai/v1"
env_key = "PEARL_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

[model_providers.pearl.capabilities]
remote_compaction = "unsupported"
external_web_access = false
```

```bash Start Codex with the Pearl profile theme={null}
codex --profile pearl
```

## Start using Codex

Start Codex in your project with the Pearl profile. Ask it to explain a file, then make a small change and approve the operations you want to allow. The configuration uses HTTP Responses, disables hosted web search, and uses local compaction.

## Troubleshooting

Choose a Pearl chat model with tool calling. Pearl chat models support all three API formats; Codex uses OpenAI Responses. Keep WebSockets disabled and remote compaction unsupported. Stored-response continuation and OpenAI-hosted tools are not part of this setup. Codex 0.134.0 and later reject a \[profiles.pearl] table in config.toml; move it into pearl.config.toml. The profile file belongs in \~/.codex, not in the project config.

* `401`: check the key and allow time for a newly created key to reach the inference gateway.
* `404`: copy the endpoint and exact model ID from Integrations. OpenAI base URLs end in `/v1`; the Anthropic SDK and Claude Code use the URL without that suffix.
* `402`: check your organization's credit and billing status.
* `429` or Anthropic `529`: respect retry instructions and reduce concurrency.
* For truncated output, check the output limit and reasoning budget. Increase limits only within the model's maximum output length.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.