How to Configure the Codex Plugin for Custom OpenAI‑compatible API Endpoints

Yes — the Codex plugin can use custom base URLs by setting openai_base_url in the Codex CLI's config.toml file, which the plugin automatically inherits.

The Codex plugin does not implement its own OpenAI client. Instead, it delegates all requests to the locally installed Codex CLI and its app-server. This architectural choice means every configuration option available to the CLI — including custom API endpoints — flows directly to the plugin without additional setup.

How the Plugin Inherits Custom Endpoints

Architecture Overview

The plugin communicates with the Codex app-server through the library at plugins/codex/scripts/lib/codex.mjs. The app-server reads configuration from standard TOML files at either the user level (~/.codex/config.toml) or project level (.codex/config.toml).

When you specify openai_base_url in either location, you override the default https://api.openai.com/v1 endpoint used by the built-in OpenAI provider. The plugin requires no code changes — it simply routes through the already-configured CLI.

Configuration Sources

Scope	Path	Best For
Project-level	.codex/config.toml	Repository-specific endpoints
User-level	~/.codex/config.toml	Global default across all projects

Setting Up Custom OpenAI-compatible Endpoints

Project-Level Configuration (Recommended for Single Repositories)

Create a .codex directory in your repository root and add the endpoint:

mkdir -p .codex
cat > .codex/config.toml <<'EOF'
openai_base_url = "https://my-custom-openai-proxy.example.com/v1"
openai_api_key = "sk-*****"
EOF

Any /codex:* command executed in this repository now targets your custom endpoint.

User-Level Configuration (Global Default)

Apply the setting across your entire machine:

mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
openai_base_url = "https://my-custom-openai-proxy.example.com/v1"
EOF

Verifying Your Configuration

Confirm the plugin will use your custom endpoint:

codex config show | grep openai_base_url

The output displays your configured value, proving the setting is active before the plugin invokes the CLI.

Evidence from the Source Code

The repository's documentation explicitly supports this approach. As stated in README.md (lines 316-322):

"Point the built-in OpenAI provider at a different endpoint, set openai_base_url in your Codex config."

The core library at plugins/codex/scripts/lib/codex.mjs launches the app-server without hardcoding any API URLs — it relies entirely on the CLI's configuration resolution. This design guarantees that custom OpenAI-compatible API endpoints configured in TOML files propagate automatically to plugin operations.

Compatible Endpoint Requirements

Your custom endpoint must implement the OpenAI API specification. Most providers advertising "OpenAI-compatible" support — including Azure OpenAI Service, local inference servers like llama.cpp, and proxies like litellm — work without modification. The openai_base_url value should point to the base path preceding /chat/completions, /models, and other standard endpoints.

Summary

• The Codex plugin delegates all API calls to the local Codex CLI app-server configured in plugins/codex/scripts/lib/codex.mjs.
• Set openai_base_url in ~/.codex/config.toml or .codex/config.toml to override the default OpenAI endpoint.
• No plugin code changes or special flags are required — configuration flows automatically from CLI to plugin.
• Use codex config show to verify your custom endpoint is recognized before running plugin commands.

Frequently Asked Questions

Where does the Codex plugin store its API configuration?

The plugin does not store API configuration independently. It reads from the same TOML files used by the Codex CLI: either ~/.codex/config.toml for user-level settings or .codex/config.toml for project-specific overrides. Set openai_base_url in either file to control where requests are sent.

Can I use Azure OpenAI Service with the Codex plugin?

Yes — any OpenAI-compatible API endpoint works, including Azure OpenAI Service. Configure openai_base_url to your Azure endpoint (e.g., https://your-resource.openai.azure.com/openai/deployments/your-deployment) and ensure openai_api_key contains your Azure API key. The plugin routes requests exactly as the CLI would.

Do I need to restart my editor after changing the configuration?

No. The Codex plugin launches a fresh app-server process for each operation through plugins/codex/scripts/lib/codex.mjs, which reads the current configuration file. Changes to config.toml take effect on the next /codex:* command without requiring an editor restart.

What happens if openai_base_url is not set?

When openai_base_url is absent, the built-in OpenAI provider defaults to https://api.openai.com/v1. The plugin continues to function normally, sending all requests to the standard OpenAI API endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}