How to Configure Different Codex API Base URLs with the OpenAI Codex Plugin

Yes, the OpenAI Codex plugin supports configurable API base URLs through environment variables or persisted session files, allowing seamless switching between self-hosted instances, staging environments, and regional endpoints without modifying source code.

The openai/codex-plugin-cc repository implements a dynamic endpoint resolution system that decouples the plugin from hardcoded API addresses. By leveraging the Codex App Server client architecture, the plugin can route all requests to alternative Codex instances by reading configuration from environment variables or local session persistence files.

Understanding the Endpoint Resolution Architecture

The plugin determines which Codex API to target through a hierarchical resolution process implemented in plugins/codex/scripts/lib/state.mjs. The getSessionRuntimeStatus function (lines 6‑15) first checks for the BROKER_ENDPOINT_ENV environment variable (exposed as CODX_ENDPOINT to users), then falls back to endpoint data stored in the broker session file via loadBrokerSession.

All network communication flows through the CodexAppServerClient class, which receives endpoint configuration during initialization. When CodexAppServerClient.connect is invoked, it accepts an optional env object containing a custom CODX_ENDPOINT value, which it then uses for all subsequent client.request calls.

Configuring Endpoints via Environment Variables

The simplest method to redirect the plugin involves setting the CODX_ENDPOINT environment variable before launching Claude Code. This approach overrides any persisted session configuration and immediately directs traffic to your specified URL.

# Point to a self-hosted Codex instance

export CODX_ENDPOINT="https://my-self-hosted-codex.example.com"

# Reload plugins to pick up the new environment variable

/reload-plugins

# Verify connectivity to the custom endpoint

/codex:setup

The plugin reads this value through the BROKER_ENDPOINT_ENV constant defined in the source code. If the variable is present, getSessionRuntimeStatus extracts it from process.env[BROKER_ENDPOINT_ENV] and passes it to the client initialization logic.

Using Persisted Broker Session Files

For persistent configuration across sessions, the plugin stores endpoint metadata in a JSON file located at <repository-root>/.codex/broker-session.json. The plugins/codex/scripts/lib/broker-endpoint.mjs module handles reading and writing these persisted endpoints, enabling shared runtime states between different Claude Code windows.

To manually configure a different API base URL, modify the endpoint field in the broker session file:

{
  "endpoint": "https://internal-codex.mycompany.com",
  "pid": 12345,
  "startedAt": "2024-11-01T12:34:56Z"
}

When CODX_ENDPOINT is undefined, the plugin automatically loads this file and uses the stored URL for reconnection attempts.

Programmatic Endpoint Configuration

Developers building custom Claude Code extensions can programmatically specify endpoints by passing configuration objects directly to the client constructor. The CodexAppServerClient.connect method accepts an env parameter that bypasses both environment variables and session files.

// Programmatic use inside a Claude Code extension
import { CodexAppServerClient } from "plugins/codex/scripts/lib/app-server.mjs";

const client = await CodexAppServerClient.connect(process.cwd(), {
  env: { CODX_ENDPOINT: "https://staging.codex.openai.com" },
  reuseExistingBroker: false,
});

await client.request("review/start", { /* request payload */ });
await client.close();

This approach is particularly useful for testing environments where you need to temporarily override the default endpoint without affecting global environment variables.

CLI Verification and Runtime Status

The /codex:setup command (implemented in plugins/codex/scripts/codex-companion.mjs) validates endpoint connectivity during initialization. When executed, this command reports the currently detected endpoint and attempts to start a new shared runtime at that URL if none is running, providing immediate feedback on whether your custom configuration is reachable.

Summary

• The Codex plugin uses CodexAppServerClient to manage API connections dynamically rather than hardcoding endpoints.
• Set the CODX_ENDPOINT environment variable to override the default URL for the current session.
• Persisted configuration stores the endpoint in <repo>/.codex/broker-session.json via the broker-endpoint.mjs helper.
• Programmatic users can pass custom environments directly to CodexAppServerClient.connect in plugins/codex/scripts/lib/codex.mjs.
• Use /codex:setup to verify connectivity against your configured base URL before executing Codex operations.

Frequently Asked Questions

Can the Codex plugin connect to self-hosted Codex instances?

Yes. By exporting CODX_ENDPOINT="https://your-instance.example.com" before launching Claude Code, or by editing the broker session file, you can direct the plugin to communicate with any Codex-compatible API server, including self-hosted deployments or enterprise internal instances.

What happens if I don't specify a custom endpoint?

If CODX_ENDPOINT is undefined and no broker session file exists, the plugin falls back to its default endpoint resolution logic. The getSessionRuntimeStatus function in plugins/codex/scripts/lib/state.mjs handles this gracefully by checking both sources sequentially before establishing connections.

How do I verify which API endpoint the plugin is currently using?

Execute the /codex:setup command in Claude Code. This CLI tool (located in plugins/codex/scripts/codex-companion.mjs) displays the resolved endpoint URL and attempts to validate connectivity, showing whether the plugin will communicate with the default OpenAI servers or your custom-configured base URL.

Can I change the endpoint without restarting Claude Code?

Yes. After modifying the CODX_ENDPOINT environment variable, run /reload-plugins to force the plugin to reinitialize and pick up the new configuration. Alternatively, updating the broker session file will affect the next connection attempt without requiring a full application restart.

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