Verdict: You can run OpenAI's Codex CLI — the open-source terminal coding agent — entirely for free by swapping its paid model for a free one in your config.toml. The cheapest reliable path is OpenRouter, which gives you a single API key in front of dozens of free models (including z-ai/glm-4.5-air:free and openai/gpt-oss-120b). The most private path is a local Ollama install running Qwen2.5-Coder on your own hardware. Neither trick is a hack — both use a builder setting Codex ships and documents.
Last verified: 2026-07-29
- Free cloud path: OpenRouter free-tier models — one key, ~20+ free models (OpenRouter Free Models).
- Free local path: Ollama + Qwen2.5-Coder — no internet, no rate limits, runs on a laptop with 16 GB RAM minimum (Ollama, Qwen2.5-Coder).
- The swap: one
[model_providers.<id>]block in~/.codex/config.toml. No code change required (OpenAI Codex config docs).- Caveat:
wire_api = "responses"is required since Codex removed thechatvalue in February 2026 (OpenRouter Codex guide).
What is Codex CLI, and which part actually costs money?
Codex CLI is the terminal coding agent from OpenAI. It is open-source under the Apache-2.0 license, hosted at github.com/openai/codex, and installs in under a minute. You give it a prompt like "build a landing page for my indie SaaS," and it plans the job, opens files, writes code, runs shell commands, and checks its own work in a loop. That loop — the "hands" — is free and always was. The cost is the brain: by default Codex talks to an OpenAI hosted model (like gpt-5-codex) and you pay per token every time it thinks.
The clean way to think about it:
| Part | What it is | What it costs |
|---|---|---|
| The hands (Codex) | Plan + write files + run commands + self-check | Free, open-source (Apache-2.0) |
| The brain (model) | Whatever model answers each reasoning step | Paid by default (OpenAI API); free if you swap in a free model |
Swapping the brain is a first-class, documented feature — not a workaround. Codex supports custom [model_providers.<id>] blocks in your user-level ~/.codex/config.toml, so you can point it at any OpenAI-compatible endpoint: OpenRouter, Ollama, LM Studio, or a self-hosted inference server (OpenAI Codex — Advanced Configuration).
How do you install Codex CLI before configuring it?
Install with one of three paths (all official):
# macOS / Linux (one-line installer)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# npm (cross-platform, needs Node.js)
npm install -g @openai/codex
# Homebrew (macOS)
brew install --cask codex
These commands come straight from the openai/codex README. After install, run codex once — it walks you through a login. Even if you skip login, you can still configure a custom provider (which is the whole trick here). It is also the same agent you get inside the IDE extension and the desktop codex app.
If you want the free path, you do not need to pay for ChatGPT Plus, log in, or grant OAuth. You point Codex at your own endpoint and go. See how this compares with our wider How to Run Claude Code for Free in 2026 guide — the same OpenRouter lane that powers free Claude Code powers free Codex.
How do you run Codex CLI for free through OpenRouter?
OpenRouter is an API gateway in front of ~300+ models. A growing subset of those models are free ($0/M input, $0/M output), and every free model is reachable with one key starting with sk-or-.... The setup is five steps.
Step 1 — Get an OpenRouter key
Sign up at openrouter.ai, then open openrouter.ai/keys and create a key. Free models work on free accounts; there is a default 50 requests/day limit you can raise to 1,000/day by adding ≥$10 in credits (you do not have to spend them on free models — credits unlock the higher rate-limit tier only, per the OpenRouter free models gist).
Step 2 — Edit ~/.codex/config.toml
Open (or create) your user-level config file and add the [model_providers.openrouter] block:
# ~/.codex/config.toml
model = "z-ai/glm-4.5-air:free"
model_provider = "openrouter"
[model_providers.openrouter]
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"
Three things to get right:
modelmust be an exact OpenRouter slug with the provider prefix, e.g.z-ai/glm-4.5-air:free— not the bareglm-4.5-air. A bare slug is the most common cause ofmodel_not_found(OpenRouter Codex tutorial).wire_api = "responses"is mandatory. Codex removed the olderchat/completionswire protocol in February 2026, so any custom provider missingwire_api(or set to"chat") now errors on startup (OpenAI Codex Discussions #7782).model_providersonly works in your user-level~/.codex/config.toml. Codex ignores it in a project-local.codex/config.tomland prints a startup warning (OpenAI Codex — Advanced Configuration).
Step 3 — Export the key
# bash / zsh — add to ~/.zshrc or ~/.bashrc
export OPENROUTER_API_KEY="sk-or-..."
Step 4 — Run Codex
cd /path/to/your/project
codex
The agent now thinks through your free model and acts through Codex's harness — file edits, command runs, self-checks — at zero cost per token.
Step 5 — Verify
Open the OpenRouter Activity dashboard and confirm the request shows up with the right model name and a token count (OpenRouter Codex CLI docs).
Which free models actually work with Codex CLI?
Not every free model is agent-quality. Codex's agentic loop needs a model that reliably emits tool calls in the exact schema the harness expects. Older free models would freeze halfway through a job when they formatted a tool request wrong. The 2025–2026 generation fixed that. The three families worth your time today:
Models you can reach for free via OpenRouter
| Model (OpenRouter slug) | Context | Notable property | Source |
|---|---|---|---|
z-ai/glm-4.5-air:free |
131K | MoE with hybrid "thinking mode"; trained for agent-centric use | OpenRouter — GLM 4.5 Air free |
openai/gpt-oss-120b:free |
131K | 117B-param MoE, native tool use, OpenAI's first open-weight model | OpenRouter — gpt-oss-120b free |
minimax/minimax-text-01:free |
197K | Very long context, trained on planning/agent loops | OpenRouter Free Models |
Local models that pair well with Codex (free, offline)
| Model | Sizes | Why it fits Codex | Source |
|---|---|---|---|
| Qwen2.5-Coder | 0.5B, 1.5B, 3B, 7B, 14B, 32B | Code-specific; 32B beats GPT-4o on the Aider code-repair benchmark (73.7); handles tool calls | Ollama library, Alibaba Qwen blog |
| DeepSeek-Coder-V2-Lite | 16B (2.4B active) | MoE, only 2.4B active params per token so it runs on modest hardware; 338-language code support | DeepSeek-Coder-V2 on GitHub |
For a typical developer laptop (8 GB GPU or Apple Silicon with unified memory), qwen2.5-coder:7b (~4.7 GB on disk, Q4_K_M) is the sweet spot. On a 24 GB GPU you can stretch to qwen2.5-coder:14b (~9 GB) or qwen2.5-coder:32b (~20 GB) for noticeably better reasoning (Ollama — qwen2.5-coder).
Can you run Codex CLI completely offline with Ollama?
Yes. If your machine has the RAM (16 GB minimum for a 7B model, per the Ollama/Ollama hardware guide), local inference turns the brain into something you own outright — no meter, no rate limit, nothing leaving the machine.
Step 1 — Install Ollama and pull a model
# macOS
brew install ollama
# Linux
curl -fsSL https://ollama.com/install.sh | sh
# Pull a code-tuned model
ollama pull qwen2.5-coder:7b
That is a ~4.7 GB download — the model sits on your disk and runs on your CPU/GPU (Ollama library — qwen2.5-coder).
Step 2 — Start the Ollama server
ollama serve runs by default after install, listening on http://localhost:11434. It exposes an OpenAI-compatible endpoint at http://localhost:11434/v1 (Ollama — qwen2.5-coder).
Step 3 — Point Codex at the local endpoint
# ~/.codex/config.toml — local Ollama path
model = "qwen2.5-coder:7b"
model_provider = "ollama-local"
[model_providers.ollama-local]
name = "Ollama local"
base_url = "http://localhost:11434/v1"
# Ollama ignores the key — set any non-empty string
env_key = "OLLAMA_API_KEY"
wire_api = "responses"
Set the env var (export OLLAMA_API_KEY="dummy"), then codex in any repo. Codex now thinks on hardware you already own.
LM Studio is the same trick on port 1234
Prefer a GUI model manager? LM Studio exposes the same OpenAI-compatible server at http://localhost:1234/v1 by default. Just swap the base_url in the provider block above to http://localhost:1234/v1 and change the model to the exact ID shown in the LM Studio UI (LM Studio — local OpenAI-compatible endpoint). This local-inference pattern is identical to the one in our Ollama Gemma 4 Tool Calling in 2026: How the Reliability Fix Actually Works write-up — it is the reason local models are suddenly viable for agents at all.
How do you switch back to paid models when you need them?
The whole point of the swap is that nothing breaks. Your normal OpenAI login is untouched; the free provider is just a config entry. To use the paid brain for a big job, either change the two lines in config.toml (model + model_provider) or use a profile:
# ~/.codex/config.toml — free by default, paid on demand
model = "qwen2.5-coder:7b"
model_provider = "ollama-local"
[model_providers.ollama-local]
base_url = "http://localhost:11434/v1"
env_key = "OLLAMA_API_KEY"
wire_api = "responses"
# Flip to the big brain for hard jobs
[profiles.cloud]
model_provider = "openai"
model = "gpt-5-codex"
Then on the command line:
# Free, everyday tasks
codex "explain this function"
# Paid, hard refactors
codex --profile cloud "migrate this module to dependency injection"
Profiles have been independent ~/.codex/<profile-name>.config.toml files since Codex 0.134.0 — Codex no longer reads [profiles.xxx] tables from the main config.toml(KnightLi — Codex OSS mode). The full provider table (fields, types, rules) lives in the Advanced Configuration docs.
What makes the free path viable now when it wasn't before?
The blocker was never model intelligence — it was tool-call reliability. Codex's agentic loop depends on the model emitting structured "tool calls" (open this file, run this command, read this folder) in the exact JSON shape the harness expects. Older open models would get halfway through a job, format the request slightly wrong, and freeze. The job died with a half-built website sitting on disk.
That has changed in the current generation:
- Qwen2.5-Coder is code-specific, trained on tool-use traces, and the 32B variant now scores 73.7 on Aider — competitive with GPT-4o on code repair (Alibaba Qwen blog).
- GLM-4.5-Air (Z-AI) was purpose-built for agent-centric applications, with a "thinking mode" for agentic tool use (OpenRouter — GLM 4.5 Air).
- gpt-oss-120b is OpenAI's first open-weight model in years, with native function-calling, browsing, and structured output (OpenRouter — gpt-oss-120b).
Pair any of those with Codex's working harness — planning, file writes, command runs, self-checks — and you get something that actually finishes real jobs. The hands were always good; the brains finally caught up. The harness-vs-brain split is the same mental model behind our How to Build an AI Agent OS in 2026 guide: the harness (Codex, Hermes Agent, Claude Code) is a reusable commodity once you can pick the brain freely.
What does a free Codex setup actually let you build overnight?
Because there is no meter, you stop babysitting the agent. The practical shift is in how much you delegate, not how much you prompt:
- Land it in one prompt. Tell Codex "build a clean SaaS landing page with an email capture and an FAQ section." Go make coffee. Come back to HTML that builds.
- Run long goal loops. With a paid token budget, a long job dies at 3am when the meter hits zero. With a free brain, the loop just keeps going. You wake up to a finished scaffold, not a broken half-site (the same unlocked-by-free-tokens story we traced in How to Run an AI Agent Loop in 2026).
- Switch brains per job. One model is great at scaffolding; another is faster at bug fixes. With Codex CLI you switch by changing one
modelline — no reinstall, no new key. Different brains for different jobs, at zero switching cost.
The sensible pattern is hybrid: use the free local/cloud model for everyday work (drafting, commenting, simple edits, bug fixes), and reserve the paid model for a hard multi-file refactor or a complex migration where frontier reasoning matters. The profile-system makes that a single flag.
A fuller architecture for gluing Codex into memory, workspace state, and other tools lives in our Agent OS Architecture Guide — the free "brain" is what makes 24/7 agent runs affordable in the first place.
What this means for you
- If you are a solo builder or small team: start with OpenRouter's free tier. It is the fastest lane — one key, no install, ~20+ free models. Once a free model gets rate-limited, swap in another by changing one
modelline. - If privacy matters (client code, regulated industries): go local. Ollama + Qwen2.5-Coder:7b fits on a mid-range laptop with 16 GB RAM;
ollama pulland you are done. Nothing leaves the machine. - If you have a strong workstation: run the 14B or 32B Qwen2.5-Coder. The bigger model is noticeable on refactors and deeper reasoning.
- If your hardware is older or you don't want to manage models: stick with the OpenRouter cloud lane and let their servers do the inference.
The trick is the same in every case: Codex's hands are free and always were. You swap the brain in one config file, and a free model is enough brain for the bulk of everyday coding work.
FAQ
Q: Is running Codex CLI with a third-party model actually allowed?
A: Yes. Custom [model_providers.<id>] blocks are a documented, first-class Codex feature — not a hack or a jailbreak. You configure them in your user-level ~/.codex/config.toml, and OpenAI ships and documents the Advanced Configuration reference that covers every supported field.
Q: Do I need an OpenAI subscription or ChatGPT Plus to use Codex CLI? A: No. Once you configure a custom provider and export its key, Codex routes requests and bills (or doesn't bill, for free models) through that provider. An OpenAI plan is only needed if you fall back to OpenAI's hosted models (OpenRouter Codex FAQ).
Q: What is wire_api and why does it matter?
A: wire_api controls which API protocol Codex uses to talk to a provider. As of February 2026, Codex removed support for the older chat value, so any custom provider (OpenRouter, Ollama, LM Studio) must set wire_api = "responses" — otherwise Codex errors on startup (OpenAI Codex Discussions #7782).
Q: Which free model should I pick first?
A: For a zero-install cloud path, z-ai/glm-4.5-air:free or openai/gpt-oss-120b:free on OpenRouter. For an offline path, qwen2.5-coder:7b via Ollama is the most-tested code-specific option and fits on a typical laptop (OpenRouter Free Models, Ollama — qwen2.5-coder).
Q: How many free OpenRouter requests can I make per day? A: The default is 50 requests/day on a free account. You can raise that to 1,000/day by adding at least $10 in credits — the credits unlock the higher rate-limit tier and do not have to be spent on free models (OpenRouter free models gist).
Q: Can I switch between a free model and a paid model without reinstalling?
A: Yes. Change the two lines model and model_provider in your config.toml, or set up a [profiles.cloud] block and use codex --profile cloud on demand. Switching is a one-line change — no new key, no reinstall (OpenRouter Codex tutorial).
Discussion
0 comments