How to Connect Codex to an OpenAI-Compatible Gateway

Codex speaks the OpenAI protocol, which means connecting it to Zivv takes two settings: replace the OpenAI base URL with Zivv's endpoint and use a Zivv API key. The mechanics take five minutes. What actually deserves attention is everything around those two settings — picking the right model per task, distributing keys across a team, and knowing how to debug the handful of errors you might hit. This guide walks through all of it.

Who This Is For

• Codex users who want lower API costs without changing how they work
• Teams running both Claude Code and Codex who are tired of juggling separate accounts
• Any tool that only speaks the OpenAI protocol but needs access to Claude or Gemini models

Zivv is a unified gateway: one key, 100+ models, three protocols. Codex connects through the OpenAI-compatible endpoint, Claude Code through the Anthropic one, and both bill against the same balance.

Know Your Endpoints

The single most common mistake is using the wrong path for the protocol. Keep this table nearby:

Codex needs the /v1 path. If you copy the Claude Code setup (root domain, no path), requests will fail even though the key is valid.

Step-by-Step Setup

Step 1: Create a key

Register at Zivv, top up (the rate is a flat 1 CNY = 1 USD), and create an API key from the console.

Step 2: Set the environment variables

macOS / Linux:

export OPENAI_BASE_URL=https://zivv.pro/v1
export OPENAI_API_KEY=sk-your-key-here
codex

Windows PowerShell:

$env:OPENAI_BASE_URL="https://zivv.pro/v1"
$env:OPENAI_API_KEY="sk-your-key-here"
codex

Add the export lines to your shell profile once you have confirmed they work, so new terminals start configured. Codex also supports a persistent provider entry in its own config file if you prefer not to use environment variables — the Codex guide shows both approaches.

Step 3: Verify the route before starting work

A ten-second curl check tells you whether the gateway, key, and model name are all correct:

curl https://zivv.pro/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"ping"}]}'

A JSON completion back means you are done. An error here saves you from debugging inside Codex later.

Step 4: Pick a model deliberately

Do not default every task to the most expensive model. Route by task:

• Small edits and code explanation: a lower-cost general model such as gpt-5.4
• Multi-file refactors: a stronger coding model such as gpt-5.5 or claude-sonnet-5
• Tests and documentation: mid-tier models are usually enough
• Architecture decisions: temporarily upgrade to a top model such as claude-opus-4-8

Because Zivv exposes Claude and Gemini models through the same OpenAI-compatible endpoint, "switching providers" in Codex is just changing a model string. Browse what is available in the Model Hub.

Team Key Distribution

The worst setup is one shared key pasted into every laptop and CI job. A better pattern:

1. Create a team and invite members
2. Issue each member an independent key
3. Create separate keys for automation and CI pipelines
4. Set daily or monthly budget caps per key
5. Review the usage breakdown weekly

With Teams, all keys draw from one owner-funded balance while usage stays attributable per member, per key, and per model. When a script misbehaves, you disable one automation key instead of rotating everyone.

Troubleshooting

401 unauthorized. The key is wrong, has trailing whitespace from a copy-paste, or has been disabled. Compare against the error reference.

404 model not found. The model name is not available to your key's group, or it is misspelled. Check the exact identifier in the Model Hub.

Requests still hit OpenAI. OPENAI_BASE_URL is not set in the terminal that actually launches Codex. Run an echo of the variable in that same terminal to confirm.

Garbled characters in output. Almost always the terminal or log viewer, not the API. Re-test with a plain English prompt before blaming the gateway.

Running Codex Alongside Claude Code

Many developers use both tools daily: Claude Code for long-context agent sessions, Codex for OpenAI-ecosystem tooling and automation. Through Zivv they share one key and one bill, which beats maintaining separate official accounts per tool. If rate limits are what pushed you here, the Claude Code stability guide covers that side of the setup.

FAQ

Does Codex need a plugin or patch to work with Zivv? No. Codex already speaks the OpenAI protocol; Zivv implements the same protocol, so the base URL and key are the only changes.

Can I use Claude models from inside Codex? Yes. Models like claude-sonnet-5 are served through the OpenAI-compatible endpoint, so any OpenAI-protocol client can call them by name.

Does streaming work? Yes. The OpenAI-compatible endpoint supports streaming responses the same way the official API does.

How do I keep personal and CI usage separate? Use different keys. Member keys for laptops, automation keys with stricter caps for CI. The usage dashboard then attributes every token correctly.

Wrap-Up

Codex integration comes down to OPENAI_BASE_URL set to https://zivv.pro/v1 plus a Zivv key — verify with curl, choose models per task, and split keys before the team grows. Create your key and Codex is running on the gateway in the time it takes to read this section.