Independent setup guide

NanoGPT with Codex CLI: use the Responses configuration.

Current Codex CLI releases need wire_api = "responses" for a custom NanoGPT provider. This guide gives you the minimal user-level config, a secret-safe check, focused error diagnosis and a clean rollback.

Referral links on this page give you 5% off qualifying NanoGPT website queries (no API discount claimed) and may earn this independent site credit.

Fact-checked 9 August 2026Config parsed with Python 3.11 TOMLNo paid inference claimed

The stale-setting trap

NanoGPT’s current Codex guide explicitly says older examples using wire_api = "chat" fail with recent Codex CLI versions. Use responses. This setting selects the API protocol; it is not a model name.

Step 1

Back up first, then install.

Codex stores user configuration in ~/.codex/config.toml. Preserve an existing file rather than replacing custom profiles, sandbox settings or MCP servers blindly.

mkdir -p ~/.codex
if [ -f ~/.codex/config.toml ]; then
  cp ~/.codex/config.toml ~/.codex/config.toml.before-nanogpt
fi
npm install -g @openai/codex
codex --version

NanoGPT currently specifies Node.js 22 or newer for this integration. Prefer a Node version manager or a user-writable npm prefix over sudo npm install.

Step 2

Add a named NanoGPT provider.

Merge these top-level values and provider table into ~/.codex/config.toml. If those keys already exist, update them once; duplicate TOML keys are invalid.

model_provider = "nanogpt"
model = "openai/gpt-5.2"

[model_providers.nanogpt]
name = "NanoGPT"
base_url = "https://nano-gpt.com/api/v1"
env_key = "NANOGPT_API_KEY"
wire_api = "responses"

openai/gpt-5.2 is a current documented example, not a permanent recommendation. Check the live model catalogue before choosing a model.

Set the key outside the TOML file

Use an environment variable; do not paste a reusable key into a project file, command example, screenshot or repository.

# Current shell only; leading space may avoid history where HISTCONTROL supports it
 export NANOGPT_API_KEY="paste-your-key-locally"
codex

For persistence, add the export to the appropriate private shell profile and restrict that file’s permissions. Open a new terminal afterwards. The official NanoGPT installer also supports browser login, but manual setup makes each file change visible.

Step 3

Check structure and presence, not the secret itself.

Python 3.11 can parse the configuration without printing it. The second command reports only whether the variable exists.

python3 -c 'import pathlib,tomllib; tomllib.loads(pathlib.Path.home().joinpath(".codex/config.toml").read_text()); print("TOML is valid")'
python3 -c 'import os; print("NANOGPT_API_KEY is set" if os.getenv("NANOGPT_API_KEY") else "NANOGPT_API_KEY is missing")'
codex --version

Then launch codex in a disposable test repository and use a small prompt. A real model request is billable; inspect NanoGPT’s usage page and exact request cost rather than assuming the referral discount applies.

Model choice

Use a callable ID from the live catalogue.

NanoGPT says availability changes frequently and identifies GET /api/v1/models as the authoritative source for callable text-model IDs. Listing models does not require a key:

curl -fsS https://nano-gpt.com/api/v1/models

Copy an exact data[].id value into the top-level model setting, or override it for one launch:

codex --model MODEL_ID_FROM_THE_LIVE_CATALOGUE

Do not infer feature parity from a model appearing in the list. Codex relies on Responses API behaviour and tool calling, so a listed chat model may still be a poor fit for an agent workflow.

Diagnostic path

Fix the category, not the symptom.

Config or protocol error

Parse the TOML. Confirm the table is exactly [model_providers.nanogpt], the selected provider is nanogpt, and wire_api is responses, not chat.

401 authentication

The key is missing or invalid. Check variable presence without printing its value, open a fresh terminal after profile changes, and rotate any key that was exposed.

402 payment required

The authenticated account has insufficient balance. Add funds only if you choose to; do not keep retrying. A referral click alone does not provide prepaid API credit.

404 or model not found

Refresh /api/v1/models and use an exact current ID. Do not rely on a copied model list.

429 rate limit

Wait and respect Retry-After when supplied. NanoGPT says this can represent throughput or a per-key daily limit.

500, 503 or timeout

Retry a small number of times with backoff. If persistent, try another compatible model and retain the X-Request-ID for support.

Reversible by design

Restore your previous setup.

If you made the backup above, restore it and remove the key from the current shell. This does not revoke the key at NanoGPT.

if [ -f ~/.codex/config.toml.before-nanogpt ]; then
  mv ~/.codex/config.toml.before-nanogpt ~/.codex/config.toml
else
  rm -f ~/.codex/config.toml
fi
unset NANOGPT_API_KEY

Also remove any persistent export you added to a shell profile. Revoke the key in NanoGPT’s API-key page if it was disclosed or is no longer needed.

Optional next step

Keep the setup guide free of gates.

You can create a NanoGPT account through the clean official API page. If the separate website-query discount is useful, the disclosed invitation is below.

Accept the qualifying 5% web-query invitation

Method and limits

Primary sources, with a clear test boundary.

This page was checked against NanoGPT’s current Codex CLI guide, model endpoint documentation, error reference, and OpenAI’s Codex configuration reference on 9 August 2026.

The published TOML fixture was parsed successfully. No paid inference request was made for this page, so this guide does not claim an end-to-end model benchmark or personal product experience. Interfaces, model IDs and requirements can change; the linked first-party pages remain authoritative.