RealRelay.ai
Coding agents

Codex CLI

Connect OpenAI Codex CLI to RealRelay.ai through the OpenAI Responses endpoint: install it, add a custom model provider in config.toml, check the connection and choose models.

Create an API keyBrowse the catalog
Protocol
OpenAI Responses
Base URL
https://www.realrelay.ai/v1
Official docs
learn.chatgpt.com
Checked against the tool’s docs
2026-10
Experimental. Not yet run end to end against RealRelay.ai. The steps follow the tool’s own documentation; if one fails, contact support with the error.

Overview

Codex CLI is OpenAI's coding agent for the terminal. It works in your repository, edits files and runs commands within the permissions you give it. Codex only speaks the OpenAI Responses protocol, so it connects to RealRelay.ai's /v1/responses endpoint.

  • An API key from the API keys page of the console.

  • The base URL with /v1. Codex appends /responses to it.

  • A model ID that RealRelay.ai serves on Responses, for example openai/gpt-5.3-codex. Most models in the catalog are Chat Completions only and do not work in Codex.

This guide is experimental. RealRelay.ai does not serve a Codex model catalogue, so Codex runs every RealRelay.ai model with fallback metadata and prints a warning about it. You set the context window yourself, and features that depend on catalogue metadata may behave differently than with OpenAI's own service.

Install

Use one of OpenAI's install methods. On Windows, use npm; OpenAI's Codex page also lists a standalone PowerShell installer.

macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | shcodex --version
Homebrew
brew install --cask codexcodex --version
npm
npm install -g @openai/codexcodex --version

If codex --version prints a version number, the install worked. You do not need to sign in with ChatGPT to use a custom provider.

Configure

  1. 1

    Add the provider

    Open ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml) and merge in these lines. If the file already sets model or model_provider, replace those lines instead of adding a second copy.

    ~/.codex/config.toml
    1# Top-level keys first: anything below a [table] header belongs to that table.2model = "openai/gpt-5.3-codex"3model_provider = "realrelay"4web_search = "disabled"5# Codex has no built-in metadata for RealRelay.ai model IDs. Set these to the6# limits on the model's catalog page.7model_context_window = 4000008model_auto_compact_token_limit = 300000910[model_providers.realrelay]11name = "RealRelay.ai"12base_url = "https://www.realrelay.ai/v1"13wire_api = "responses"14env_key = "REALRELAY_API_KEY"
  2. 2

    Put the key in your environment

    Codex reads the key from the variable named in env_key. Replace sk-*** with your key.

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"

    Run source ~/.zshrc, or open a new terminal.

    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    Close and reopen the terminal afterwards.

  • model, model_provider and web_search must come before the first [table] header. A key placed after a header belongs to that table, and Codex ignores it without an error.

  • The provider needs its own ID. openai, ollama and lmstudio are reserved, so the example uses realrelay.

  • wire_api = "responses" is the only value current Codex accepts. Older guides that use "chat" no longer work.

  • web_search = "disabled" removes Codex's web search tool, which OpenAI recommends for a first gateway test.

  • Keep the key out of config.toml. The Codex desktop app does not see variables you only exported in a terminal.

Verify

  1. 1

    Call the endpoint directly

    Run this in the terminal where the key is set. A JSON reply with "object": "response" means the address, key and model work on Responses.

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/responses" \2  -H "Authorization: Bearer $REALRELAY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"model": "openai/gpt-5.3-codex", "input": "Reply with OK"}'
  2. 2

    Run the diagnostics

    codex doctor checks the config. The auth line should show your variable as (present), and the inference URL should be reachable. An HTTP 404 or 401 on the probe is normal; it means TLS and routing work.

    Terminal
    codex doctor | grep -E 'auth|reachab'
  3. 3

    Send a first message

    Start Codex in a project and run /status. It should show the realrelay provider and your model. Then send the test prompt; the reply should be gateway-ok. The request also appears in the console's usage logs.

    Codex CLI
    1cd /path/to/your/project2codex3/status4Reply with exactly: gateway-ok

Models

The /model picker lists models from Codex's own catalogue, so RealRelay.ai model IDs usually do not appear there. To switch, change model in config.toml, or start Codex with -m for one session:

Terminal
codex -m openai/gpt-5.3-codex

Only models served on /v1/responses work in Codex: openai/gpt-5.3-codex, the openai/*-pro models and the xai/grok-* text models. The current list is under Choosing a model. Plain openai/gpt-5.x, Claude, GLM, Kimi and the other families are Chat Completions only.

Because Codex has no metadata for these IDs, set model_context_window to the window on the model's catalog page and keep model_auto_compact_token_limit below it. The example values fit openai/gpt-5.3-codex (400,000 tokens).

Troubleshooting

  • "wire_api = "chat" is no longer supported". The config is from an older guide. Set wire_api = "responses".

  • codex doctor says the auth env var is missing. The terminal was opened before you added the key. Run source ~/.zshrc or open a new terminal. For the desktop app, set the variable where the app can see it and restart the app.

  • 401 "Invalid token". The key is wrong or was deleted. Copy it again from the console.

  • "Model metadata for … not found. Defaulting to fallback metadata". Expected with RealRelay.ai, which has no Codex catalogue. Requests still work; set the context window as shown under Models.

  • Errors naming the model on the first message. The model is not served on Responses, or the ID has a typo. Pick one from the list under Models and copy the ID exactly.

  • The provider or model you set is not active. /status shows something else. Check that the top-level keys sit above [model_providers.realrelay], and that no profile overrides them.

  • curl works but Codex reports "TLS handshake or certificate validation failed". This can happen when Codex's bundled certificate store does not yet include the root that signed the site's certificate. Point Codex at your system certificates, open a new terminal and run codex doctor again. Updating Codex may also fix it.

    ~/.zshrc (macOS)
    export SSL_CERT_FILE=/etc/ssl/cert.pem
    ~/.bashrc (Debian · Ubuntu)
    export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt