Skip to main content

Before you start

Complete organization setup, make sure your account has inference credit, and create a key on the API Keys page. 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.

Get your connection settings

Open 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:

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.
~/.codex/pearl.config.toml (create this profile file)
Start Codex with the Pearl profile

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.