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/responsesis 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/codexOpen 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
codexThe 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| Key | What it does |
|---|---|
model_provider | Selects the provider from model_providers. The default is openai. |
env_key | The environment variable that holds the provider API key |
requires_openai_auth | false means that Codex does not ask for an OpenAI login |
model_context_window | The context tokens of the active model. The command takes the value from your live catalog. |
model_auto_compact_token_limit | The token count that starts automatic history compaction. The command sets 90% of the context window. |
tool_output_token_limit | The 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-codexTo 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.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.
| Model | Free on | Context | Free limits (best offer) | Tools | Vision |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 req/min 1 req/min per model | Yes | No |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 req/min 40 RPM | Yes | Yes |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | Yes | Yes |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | Yes | No |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | Yes | Yes |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 req/min 20 req/day 250,000 tokens/min ~3M | Yes | Yes |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | Yes | Yes |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 req/min 50 req/day 50 req/day account-wide (1,000 after a $10 purchase) | Yes | Yes |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 req/min 50 req/day Shared rate limit | Yes | No |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 req/min 250 req/day 70,000 tokens/min ~6M | Yes | Yes |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 req/min 20 req/day 250,000 tokens/min ~3M | Yes | Yes |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | Yes | Yes |
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
| Problem | Cause | Fix |
|---|---|---|
| Codex asks you to sign in with ChatGPT | model_provider is not set, so Codex uses openai | Set model_provider = "freellmapi" |
401 "Invalid API key" | FREELLMAPI_API_KEY is not set in this shell | Export the variable, or use npx freellmapi launch-codex |
"Model metadata for auto not found" | Codex does not know the gateway model ids | Add model_catalog_url |
Errors with wire_api = "chat" | Codex supports only the Responses API | Set wire_api = "responses" |
| Profile settings are ignored | Codex 0.134.0 and later ignores [profiles.NAME] tables | Use the default provider setup, or a separate profile file |
| "All models rate-limited after N attempts" | All keys are at their limit | Add keys from more providers, or wait for the cooldowns |
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.
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.
Related guides
- How to use Claude Code for free
- Use OpenCode with a free LLM API
- Use Aider with a free LLM API
- Best free coding model APIs
- Is there a free GPT API?
Sources
- Codex docs: config reference (checked 20 November 2026)
- Codex docs: advanced config and profiles (checked 20 November 2026)
- Codex CLI repository (checked 20 November 2026)
- FreeLLMAPI docs: coding agents and Codex (checked 20 November 2026)
- FreeLLMAPI CLI generators (checked 20 November 2026)