Codex Custom Provider Setup in config.toml

Codex supports defining model providers through configuration files. When connecting to a third-party compatible API, the key point is base_url, authentication environment variables, model ID, and wire_api. The official configuration reference specifies wire_api as responses, so the compliant service must actually support the Responses API; simply supporting Chat Completions is not enough to cover the Codex's agent tasks.

Quick conclusion

A Codex custom provider must support the Responses API. Use the configuration below and a dedicated environment variable, then verify file creation and tool calls in a temporary Git repository. A successful chat response alone does not verify agent workflows.

Check before you start

First confirm that the target model and API support the Responses API. Don't infer that just because the normal chat API is available, file operations, tool calls, and continuous agent tasks are also available.

Prepare independent environment variables:

export AIFAST_LINK_API_KEY="YOUR_LINK_API_KEY"

Configuration steps

Use the user-level configuration file ~/.codex/config.toml to add a custom provider. The project-level file .codex/config.toml cannot overwrite model_provider、model_providers or provider authentication. Example:

[model_providers.aifast_link]
name = "AIFast Link"
base_url = "https://www.aifast.link/v1"
env_key = "AIFAST_LINK_API_KEY"
wire_api = "responses"

Keep your existing default model and provider. This guide requires stable Codex CLI 0.134.0 or later and uses a separate profile file: put the following two settings in ~/.codex/aifast_link.config.toml and select Link only when launching. Do not overwrite your full user configuration.

Check codex --version first. Older releases use a different profile configuration structure; follow the official migration guide before continuing. The startup check below rejects old or unrecognized versions without upgrading software or changing configuration.

model = "YOUR_MODEL_ID"
model_provider = "aifast_link"

These paths assume the default CODEX_HOME. If you customized it, use the actual directory for both user configuration and the profile. Review existing same-name provider or profile settings before editing; do not overwrite them.

Note:

• YOUR_MODEL_ID must be replaced with a model ID currently available to your account.
• If the service only supports Chat Completions, don't assume that changing one field will fully support Codex.
• Keep the API key in an environment variable, not in config.toml.
• Do not use the reserved provider ID openai、ollama or lmstudio.
• The regular Responses address corresponding to the above Base URL is https://www.aifast.link/v1/responses, not /v1/v1/responses.

Minimal verification task

Create a temporary Git repository without sensitive files, then start Codex with strict configuration checking:

(
  set -e
  : "${AIFAST_LINK_API_KEY:?Set AIFAST_LINK_API_KEY locally before running}"
  codex_version="$(codex --version)"
  node -e 'const m = /^codex-cli (\d+)\.(\d+)\.(\d+)(?:\s|$)/.exec(process.argv[1]); if (!m || !(Number(m[1]) > 0 || Number(m[2]) >= 134)) { console.error("Codex CLI 0.134.0+ stable required; review the migration guide first."); process.exit(1); }' "$codex_version"
  mkdir codex-link-check
  cd codex-link-check
  git init
  codex --strict-config --profile aifast_link
)

After confirming that there are no unknown field errors on startup, run in the Codex:

Create hello.txt containing exactly connection ok followed by a newline.
Read the file and show git status --short --untracked-files=all.
Do not stage, commit, or modify any other files.

A new untracked file may not appear in git diff. Check its contents and the ?? hello.txt entry in git status. These are verification steps, not evidence that a Link model has already passed the test.

Download configuration and verify file output

The separate Link GitHub repository provides provider, profile and matching file-task templates. Downloading them does not install settings, read keys or send requests. Starting a Codex task may incur charges; use a separate limited key.

Download Link Codex configuration and verification templates

After exiting the test session, enter the newly created codex-link-check directory and run:

(
  set -e
  node <<'NODE'
const assert = require("node:assert/strict");
const fs = require("node:fs");
const path = require("node:path");
const { execFileSync } = require("node:child_process");
const git = (...args) => execFileSync("git", args, { encoding: "utf8" });
const cwd = fs.realpathSync(".");
assert.equal(path.basename(cwd), "codex-link-check");
assert.equal(fs.realpathSync(git("rev-parse", "--show-toplevel").trim()), cwd);
assert.deepEqual(fs.readdirSync(".").sort(), [".git", "hello.txt"]);
assert.ok(fs.lstatSync(".git").isDirectory());
assert.ok(fs.lstatSync("hello.txt").isFile());
assert.equal(git("status", "--porcelain=v1", "--untracked-files=all", "--ignored", "-z"), "?? hello.txt\0");
git("diff", "--exit-code");
git("diff", "--cached", "--exit-code");
assert.equal(fs.readFileSync("hello.txt", "utf8"), "connection ok\n");
console.log("CODEX_FILE_CHECK_OK");
NODE
)

Requires local Node.js 22 or later. Run the complete block only at the root of codex-link-check: it permits only .git and an untracked regular hello.txt file with the exact content and trailing newline. Any failure exits nonzero; only a complete pass prints CODEX_FILE_CHECK_OK. This verifies local output, not model identity, API routing or charges; those require corresponding request records.

Verify four things:

1. Codex recognizes models.
2. The request fell to the expected /v1/responses, did not become /v1/v1/responses.
3. Tool calls can return normally.
4. The scope of file modification is consistent with the task.

FAQ

Unsupported parameter or response field is missing

This usually means that the compatibility layer does not fully implement the Responses API, rather than a prompt word issue. Save the error text and check the API protocol.

Ordinary Q&A is successful, but tool execution fails.

Codex agent tasks rely on tool invocation events and continuous responses. Successful text generation can only prove that the basic request is available, but not that the complete proxy link is available.

Environment variable not found

From the same terminal where Codex was launched, execute:

test -n "$AIFAST_LINK_API_KEY" && echo "Key Loaded"

Do not output the complete Key.

Still getting 401 or requests going to the old provider

Check that --profile aifast_link, provider ID aifast_link and environment variable AIFAST_LINK_API_KEY agree. Do not put another gateway's key in the Link variable or treat ChatGPT sign-in as Link API authentication. Verify the final host using redacted request records, not just the displayed model name.

Responses returns 404 or HTML

Set the Base URL to https://www.aifast.link/v1 and let the client append /responses. Do not use the Docs host, the full /v1/responses path or a duplicated /v1/v1 as the Base URL. If the path is correct but requests fail, check Responses support for the current model and group. Do not retry indefinitely.

Next step

Link account and billing checks

Use a distinct provider ID and environment variable to select the intended gateway. GPT monthly plans provide a daily allowance for their eligible group. Read Link billing guide and confirm that the target model belongs to the eligible group.

A reproducible run should include the client version, test date, model ID, final request path, redacted tool events and task output. This guide provides configuration instructions; it does not claim a successful Link run without that evidence.

After setup, follow the Codex gateway API acceptance and troubleshooting checklist to verify the active provider, Responses path, streaming, tool calls, context compaction and session recovery. A plain text answer does not verify a coding-agent workflow.

Before using a production repository, test read-only analysis, single-file edits, multi-file edits, and test commands. Keep the previous provider configuration ready for rollback.

• Check current models and prices: View AIFast model prices, confirm that the target model currently supports the Responses API.
• Create a standalone test key: Register AIFast, first limit the quota and start with read-only tasks.