Run Codex CLI Against Your Own API Endpoint

1. Check compatibility before changing configuration

Codex CLI can use a custom model provider instead of its default service. This walkthrough uses CodeRelay Hub, a pay-as-you-go API hub with the API base https://api.coderelayhub.com. The important detail is not merely whether an endpoint accepts OpenAI-style requests: it must support the API behavior your installed Codex version expects.

For the configuration below, that means the Responses API, including streaming and the tool interactions needed for coding tasks. A gateway that supports only Chat Completions is not automatically compatible. Confirm Responses support for your chosen model before proceeding, and check whether the documented base URL requires a version suffix such as /v1. Do not add that suffix by habit.

2. Install Codex and record the version

If you use npm, install the CLI with:

npm install -g @openai/codex

After that, start the session with this command:

codex --version

Record the result when troubleshooting. Provider configuration and supported API modes can change across releases, so examples for an older version may not apply. If the installation fails, check the current package requirements and your Node.js environment before investigating the gateway.

3. Prepare credentials and a model identifier

Create an API key in your workspace and select a model enabled for your account. GPT-6 Astra is one available option, but use the exact API model identifier shown in the workspace rather than assuming its display name is accepted.

In a Bash-compatible shell, read the key without placing its literal value in shell history:

read -rsp 'API key: ' CODERELAY_API_KEY; export CODERELAY_API_KEY; printf '\n'

Set the model identifier separately:

export MODEL_ID='REPLACE_WITH_EXACT_API_MODEL_ID'

Keep the key out of repository files, screenshots, and shared terminal transcripts. Environment variables avoid embedding credentials in configuration, but they are not a complete secrets-management system. Use your organization's approved mechanism on shared machines or in automation.

4. Define the provider for a single run

Start with command-line overrides rather than editing your global configuration. This keeps the experiment isolated and makes it easy to return to your usual provider. The following command uses the supplied API base; replace that value if your workspace documents a different Responses API base.

codex -c 'model_providers.relay={name="Relay",base_url="https://api.coderelayhub.com",env_key="CODERELAY_API_KEY",wire_api="responses"}' -c 'model_provider="relay"' --model "$MODEL_ID"

The provider name, relay, connects the provider definition to model_provider. The env_key setting tells Codex which environment variable contains the credential. The wire_api setting selects Responses; it does not translate an incompatible upstream API into a compatible one.

5. Test inside a disposable repository

Create a small Git repository with one source file and launch the command there. Ask Codex to read the file and explain its behavior without changing anything. Next, request a tiny edit and a relevant test. Keep the normal approval and sandbox protections enabled.

These checks exercise different parts of the integration: authentication, model selection, streamed output, tool calls, and continuation after tool results. A successful text-only response does not establish that the entire coding workflow works.

Inspect the diff and test output yourself. Do not use a production checkout or sensitive repository as the first compatibility test.

6. Diagnose failures before making it permanent

• Authentication errors: Confirm the variable is exported in the shell running Codex and that the key is active.
• Not-found responses: Check the documented base path, Responses route, and exact model identifier.
• Streaming or tool errors: Verify support for the selected model and request features. Basic OpenAI compatibility is insufficient evidence.
• Unexpected usage: Compare workspace usage records with your test session, remembering that agent tasks can involve multiple requests.

Once the workflow passes, move the same settings into your Codex configuration file, usually ~/.codex/config.toml. Merge them carefully with existing settings, and leave credentials in the environment.

Open a free CodeRelay Hub workspace to try it.