aivokey

Codex

Run OpenAI's Codex CLI with any model on AivoKey.

Use OpenAI's Codex CLI with any model on AivoKey.

Before you start

  • Codex CLI is installed (codex --version works).
  • You have an AivoKey API key and some credit (Quickstart).
  • You picked a model id with the tools badge on Models.

Step 1 — Save your key in an environment variable

macOS / Linux (add the line to ~/.bashrc or ~/.zshrc to keep it):

export AIVOKEY_API_KEY="sk-aivo_..."

Windows PowerShell (permanent; open a new terminal afterwards):

setx AIVOKEY_API_KEY "sk-aivo_..."

Step 2 — Add AivoKey to the Codex config

Open (or create) ~/.codex/config.toml — on Windows %USERPROFILE%\.codex\config.toml — and add:

model = "deepseek-v4-pro"
model_provider = "aivokey"

[model_providers.aivokey]
name = "AivoKey"
base_url = "https://api.aivokey.dev/v1"
env_key = "AIVOKEY_API_KEY"
wire_api = "responses"
  • base_url includes /v1.
  • env_key is the name of the variable from step 1, not the key itself.
  • wire_api = "responses" is required: Codex talks the Responses format.

Step 3 — Run Codex

codex

Ask something small first; the request shows up in Console → Usage.

Switching models

Change model in the config, or start Codex with another model for one session:

codex -m deepseek-v4-pro

Web search

To let Codex search the web (served by AivoKey for every model), add this line at the top level of config.toml:

web_search = "live"

See Web search & fetch for pricing.

Common problems

  • "Missing environment variable: AIVOKEY_API_KEY" — the variable is not set in this terminal. On Windows, open a new terminal after setx.
  • 401 — the key is wrong or revoked.
  • 404 — base_url is missing /v1.
  • Codex still asks you to sign in to OpenAI — model_provider is not set to "aivokey", or it sits below the [model_providers.aivokey] section. Keep model and model_provider at the very top of the file.

More fixes: Troubleshooting.