Codex Custom Provider: API Key and config.toml Setup

Codex custom provider: quick reference

This guide configures a Superfastcode gateway key. Use the official OpenAI configuration documentation for other provider configurations. For supported clients and feature limits, see Codex integration compatibility.

1. Get the right client and key

You need an installed Codex CLI, a Superfastcode account with available usage, and an active Codex/OpenAI-platform key from Console → API Keys. If the CLI is missing, follow the official Codex CLI installation guide first. Select the Codex preset for that key. A Claude Code key or an OpenAI-issued key is not a substitute for a Superfastcode Codex key.

codex --version

Record the version when reporting a problem. Supported models and channel rules are listed on the Codex pricing page. The sample model is the current Console default; use the model returned by your own current preset if it differs.

2. Merge the custom provider configuration

Open your user configuration: ~/.codex/config.toml on macOS/Linux, or %USERPROFILE%\.codex\config.toml on Windows. If you intentionally set CODEX_HOME, use that directory instead. Create the directory when missing and back up existing configuration and credentials before editing.

mkdir -p ~/.codex

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"

# Merge into your USER configuration, normally ~/.codex/config.toml.
# Back up the existing file; do not overwrite auth.json.
model_provider = "superfastcode"
model = "gpt-6.1-sol"
review_model = "gpt-6.1-sol"

[model_providers.superfastcode]
name = "Superfastcode"
base_url = "https://api.superfastcode.com/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "REPLACE_WITH_SUPERFASTCODE_KEY"

Download the config.toml template. Set top-level keys before any TOML table headers, merge an existing provider table rather than declaring it twice, and leave unrelated settings intact. Keep auth.json unchanged. This preset stores the gateway bearer key in your local config, so keep the file private and out of source control.

The current Console offers separate login and API Key Mode presets, including image-tool setup. Use the full generated preset for those modes; this text-only example does not configure every Codex feature. Do not mix authentication modes or change your sandbox permissions just to make an API connection work.

3. Run one small smoke test

Quit and restart the CLI after saving. Run this from a directory without private project files:

codex exec --skip-git-repo-check --sandbox read-only "Reply with exactly: superfastcode-ok"

Expected result: a completed assistant response containing superfastcode-ok, a successful process exit, and a corresponding request in Console usage history. A model list, a login screen, an HTTP 200 alone or a partially streamed response does not establish working inference. The request can incur metered usage.

If it fails, check for a TOML parse error first, then the selected provider, key platform, model and balance. See the error guide for authentication, rate-limit and timeout failures.

Recorded verification: Codex CLI 0.161.0 with gpt-6.1-sol completed 5 of 5 fixed-marker requests on October 16, 2026. See the dated results, test conditions and limitations and sanitized observation data. This verifies basic text completion in that window, not every tool or future availability.

Client scope and restoring your setup

The Codex channel is intended for Codex App and Codex CLI. A Responses-shaped URL does not mean arbitrary SDKs or other agents are entitled to the channel. Model and tool access depends on the selected channel and client; test the tools you need before relying on them.

For Codex App, use the Console’s App-compatible preset and restart the App, then start a new task. WebSocket transport has its own preset. Do not assume a CLI smoke test verifies App-only features, live audio, image tools, cloud sessions or every extension.

To restore your earlier provider, restore the backed-up configuration, or remove this provider table and restore your previous top-level model_provider, model and review_model. Restart the client. Rotate the gateway key if it was accidentally committed or shared.

Sources checked October 16, 2026: Official OpenAI custom provider configuration; Superfastcode Console’s current Codex preset and compatibility scope.