Guide

Use Codex CLI with free models

Codex CLI is OpenAI's open-source coding agent for the terminal. It can use a custom model provider. This guide connects Codex CLI to free models from other providers through FreeLLMAPI. Codex speaks the Responses API, and FreeLLMAPI serves it on /v1/responses.

How it works

Codex CLI sends requests in the OpenAI Responses format. The Codex docs say that responses is the only supported wire_api value. So a provider for Codex must serve /v1/responses. FreeLLMAPI serves this endpoint. It translates each request and sends it to a free model, for example Gemini, GPT-OSS, Qwen or GLM.

  • You get: the Codex CLI agent, its tools and its edit loop, on free models.
  • You do not get: OpenAI's own GPT models through your ChatGPT plan. Requests go to the free providers in your FreeLLMAPI pool.
  • Limit: image input on /v1/responses is not supported yet. Use text prompts.

Step 1: Install FreeLLMAPI and Codex CLI

Install both

curl -fsSL https://freellmapi.co/install.sh | bash
npm install -g @openai/codex

Open http://localhost:3001. Add at least two free provider keys on the Keys page. Copy your unified key from the same page. On macOS, you can also install Codex with brew install --cask codex.

Step 2: Connect Codex CLI

The setup command adds a provider to ~/.codex/config.toml. It makes a backup first and merges the new block, so your other settings stay.

One command

export FREELLMAPI_API_KEY=<unified-key>
npx freellmapi setup-codex --url http://localhost:3001 --dry-run
npx freellmapi setup-codex --url http://localhost:3001
codex

The command writes these settings, with values from your live catalog. The key is not in the file. Codex reads it from the FREELLMAPI_API_KEY environment variable, so export the variable in each shell where you run Codex.

~/.codex/config.toml

model = "auto"
model_provider = "freellmapi"
model_context_window = 128000
model_auto_compact_token_limit = 115200
tool_output_token_limit = 20000

[model_providers.freellmapi]
name = "FreeLLMAPI"
base_url = "http://localhost:3001/v1"
wire_api = "responses"
env_key = "FREELLMAPI_API_KEY"
requires_openai_auth = false
KeyWhat it does
model_providerSelects the provider from model_providers. The default is openai.
env_keyThe environment variable that holds the provider API key
requires_openai_authfalse means that Codex does not ask for an OpenAI login
model_context_windowThe context tokens of the active model. The command takes the value from your live catalog.
model_auto_compact_token_limitThe token count that starts automatic history compaction. The command sets 90% of the context window.
tool_output_token_limitThe token budget for each tool output that Codex keeps in history

To keep the key out of files and out of your shell profile, use the launcher. It starts Codex with the key in its environment only:

Zero-persistence launcher

npx freellmapi launch-codex

To make sure that the requests go to the gateway, run npx freellmapi doctor. It checks the routed Authorization header, the catalog and a live probe. The dashboard request log then shows each Codex call. The X-Routed-Via response header names the provider and model that answered. If a request failed over, X-Fallback-Trail names each failed hop and the reason.

Profiles: the Codex docs say that Codex 0.134.0 and later no longer reads [profiles.NAME] tables from config.toml. Profiles are now separate files, for example ~/.codex/NAME.config.toml. Use the default setup above with a current Codex version.

Remove the model metadata warning

Codex prints "Model metadata for auto not found" on every run. Codex does not know the gateway's model ids. To give it real metadata, such as the context window and image support, add a model catalog URL to the provider:

Add to [model_providers.freellmapi]

model_catalog_url = "http://localhost:3001/v1/codex/models"

The catalog keeps Codex's own default system prompt and tool settings. Only the warning and the context window change.

Choose models for Codex CLI

Codex is an agent. It runs shell commands and edits files through tool calls. Use models with tool calling and a large context window. The table shows free models that meet both rules today.

Free models for Codex CLI: tool calling and 128K+ context
ModelFree onContextFree limits (best offer)ToolsVision
GLM 5.3UnoRouter1M1 req/min
1 req/min per model
YesNo
GLM 5.3 FlashNVIDIA NIM, UnoRouter1M40 req/min
40 RPM
YesYes
Gemini 3.8 FlashGoogle AI Studio1MRecurring provider quotaYesYes
Qwen3.8 Flash NextAMD Radeon Cloud262KRecurring daily account allowanceYesNo
Qwen3.8 FlashElectronHub1M$0.25/week shared recurring creditYesYes
Gemini 3.7 FlashGoogle AI Studio1M10 req/min
20 req/day
250,000 tokens/min
~3M
YesYes
GPT-5.6 LunaElectronHub1M$0.25/week shared recurring creditYesYes
Dots3 Note PreviewKilo Gateway, OpenRouter512K20 req/min
50 req/day
50 req/day account-wide (1,000 after a $10 purchase)
YesYes
DeepSeek V4 FlashAMD Radeon Cloud, BazaarLink, ElectronHub1M10 req/min
50 req/day
Shared rate limit
YesNo
Qwen3.8 27BElectronHub, Groq, OVH AI Endpoints262K30 req/min
250 req/day
70,000 tokens/min
~6M
YesYes
Gemini 3.6 FlashGoogle AI Studio1M10 req/min
20 req/day
250,000 tokens/min
~3M
YesYes
Qwen 3.8 27BCloudflare Workers AI262KShared 10k neurons/dayYesYes

Showing 12 of 109 matching free models. See all models.

Live data from the FreeLLMAPI catalog (version 2026.11.19, checked 19 November 2026). Free limits change often. The catalog is checked every day.

Keep model = "auto" to let the router select a model for each request. To pin one model, run npx freellmapi setup-codex --url http://localhost:3001 --model <id>. You can also set model = "auto:smart" or model = "auto:fast" in config.toml.

Free tiers have limits per minute and per day. When a provider sends a 429 error, FreeLLMAPI sends the request to the next model in the chain. Add keys from four or more providers for long Codex sessions. Codex compacts its history when it reaches model_auto_compact_token_limit. A lower value sends smaller requests, which helps on free tiers with low tokens-per-minute limits.

Troubleshooting

ProblemCauseFix
Codex asks you to sign in with ChatGPTmodel_provider is not set, so Codex uses openaiSet model_provider = "freellmapi"
401 "Invalid API key"FREELLMAPI_API_KEY is not set in this shellExport the variable, or use npx freellmapi launch-codex
"Model metadata for auto not found"Codex does not know the gateway model idsAdd model_catalog_url
Errors with wire_api = "chat"Codex supports only the Responses APISet wire_api = "responses"
Profile settings are ignoredCodex 0.134.0 and later ignores [profiles.NAME] tablesUse the default provider setup, or a separate profile file
"All models rate-limited after N attempts"All keys are at their limitAdd keys from more providers, or wait for the cooldowns
Use every one of these through one key. FreeLLMAPI is an open-source, self-hosted router that puts all these free tiers behind a single OpenAI-compatible endpoint and fails over when one is rate-limited. Browse the catalog or go live.

Frequently asked questions

Can I use Codex CLI for free?

Yes. Codex CLI is open source. Add FreeLLMAPI as a custom model provider in config.toml. The gateway sends each request to free provider tiers, so inference costs $0.

Can Codex CLI use models from other providers?

Yes. Add a [model_providers.] block with base_url, env_key and wire_api = "responses", then set model_provider. The provider must serve the Responses API.

Does Codex CLI support the Chat Completions API?

No. The Codex config reference says that responses is the only supported wire_api value. FreeLLMAPI serves /v1/responses, so it works as a Codex provider.

Which free model is best for Codex CLI?

Use a model with tool calling and at least 128K context. The table on this page shows the strongest free models that meet both rules today.

How do I fix 'Model metadata for auto not found'?

Add model_catalog_url = "http://localhost:3001/v1/codex/models" to the provider block in ~/.codex/config.toml. Codex then reads real metadata for the gateway models.

Sources

All guides · Browse all free models

Keep reading

All posts →
Guide

Best free LLM APIs 2026

Ten genuinely free LLM APIs worth using — ranked, with real limits.

Guide

Unlimited free AI tokens?

No free AI API is unlimited. The closest real thing: 10.1 billion free tokens a month behind one key.

Guide

How to get a free LLM API key

Get a working key in minutes — no credit card required.