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, includingremote_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 replaceYOUR_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.429or Anthropic529: 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.