Codex CLI + Ollama in 2026: Three Ways to Run OpenAI's Terminal Agent on a Local Model

By AICoderScope Team · 11 min read
codexollamalocal-llmsetup-guidegpt-ossopenaiprivacyai

TL;DR: Codex CLI has shipped a first-class local-model path since 2025, and in 2026 it’s genuinely good: ollama launch codex wires everything in one command, codex --oss gets you running on gpt-oss:20b in one flag, and a five-line config.toml profile makes it permanent. The catch is context — Codex wants 64K tokens and Ollama’s default gives you a fraction of that.

  • What you’ll be able to do after this guide: run Codex CLI entirely against Ollama — agentic edits, shell commands, and approvals — with zero API spend, no ChatGPT sign-in, and no code leaving your machine.
  • What you’ll need: a current Ollama release (v0.32.1 as of July 16, 2026), Codex CLI (v0.144.6, July 18, 2026), and 16 GB of VRAM or unified memory for the default gpt-oss:20b.
  • What you’ll avoid: the three documented failure modes — silent context truncation, the /model picker that can’t see local models, and the --oss flag that ignores your remote Ollama host.

Honest take: If you have an active ChatGPT plan, cloud Codex on GPT-5.5-class models will out-code any 20B local model and you should keep using it. Local Codex is for the other cases — air-gapped repos, unlimited experimentation, and having a fallback that no billing change or outage can take away. For those, ollama launch codex is the fastest working setup we’ve tested this year.

Codex CLI was the last major terminal agent missing from our local-setup series — we’ve covered Claude Code, OpenCode, and the editor-side tools already. It’s an ironic gap, because OpenAI’s agent has arguably the most official local-model support of the lot: the --oss flag is built into the CLI, Ollama documents a dedicated integration, and the two projects even ship a joint auto-configuration path. Here’s what actually works, verified July 21, 2026.

The three setup paths, and which one you want

ollama launch codexcodex --ossManual config.toml profile
Best forFirst run, zero configQuick sessions on defaultsDaily driver, custom models, remote hosts
EffortOne commandOne flag~10 lines of TOML, once
Model pickingInteractive, from your local libraryDefaults to gpt-oss:20bAnything Ollama serves, persisted
The catchNewer Ollama required (launch shipped in v0.15)Auto-downloads ~12 GB if the default model is missing; localhost onlyYou own the context-window math

All three end in the same place: Codex talking to Ollama’s OpenAI-compatible endpoint at http://localhost:11434/v1. They differ in who writes the config.

Path 1: one command, no config

Ollama’s launch command — the same mechanism the tool uses for Claude Code, OpenCode, VS Code, and Droid — configures and starts Codex in one step:

$ ollama launch codex
# interactive model picker → writes ~/.codex/ollama-launch.config.toml → starts Codex

Two flags matter. ollama launch codex --config writes the configuration without starting a session, and ollama launch codex --restore undoes everything back to stock Codex if you want your cloud setup back. That restore path is worth knowing about: launch works by dropping a profile into ~/.codex/, and if you later see Codex behaving oddly with cloud models, a stale launch profile is the first thing to check.

Under the hood, the generated file looks like this (from Ollama’s official Codex integration doc):

model = "gpt-oss:120b"
model_provider = "ollama-launch"
model_catalog_json = "/Users/you/.codex/model.json"

[model_providers.ollama-launch]
name = "Ollama"
base_url = "http://localhost:11434/v1/"
wire_api = "responses"

Note wire_api = "responses" — Ollama now speaks OpenAI’s Responses API, not just Chat Completions, which is what lets current Codex builds run against it without translation glue. The model_catalog_json line solves a real problem we’ll come back to: without it, Codex’s /model picker has no idea your local models exist.

Path 2: the built-in --oss flag

No Ollama-side setup at all — the flag ships in Codex:

codex --oss                      # runs gpt-oss:20b
codex --oss -m gpt-oss:120b      # if you have the VRAM

When you pass --oss, Codex reads the oss_provider key from ~/.codex/config.toml to decide which local backend to talk to (ollama or lmstudio); if it’s not set, current builds ask you to pick one. Then it checks whether the model is present and pulls it if not.

That auto-pull is the first-run surprise. gpt-oss:20b is a ~12 GB download (OpenAI post-trained it with MXFP4 quantization so it “runs within 16GB of memory,” per the official model repo), and Codex starts pulling it without much ceremony if it’s missing — a documented complaint in the project’s issue tracker. If you’re on metered internet or already know you want a different model, run ollama pull yourself first, or go straight to a profile.

--oss is the right tool for a quick isolated session. It’s the wrong tool for two specific situations, both covered in “Where it breaks” below: remote Ollama hosts and per-model context tuning.

Path 3: a permanent profile you control

For a daily setup, write the provider and profile into ~/.codex/config.toml yourself:

oss_provider = "ollama"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "responses"

[profiles.local]
model_provider = "ollama"
model = "qwen3-coder"

Then codex --profile local starts every session on your terms. This is also the only reliable route to a remote Ollama box (a homelab GPU server, say): set base_url to the machine’s address in the provider block and use the profile — do not rely on --oss, which is hard-wired to localhost (issue #8240, closed as not-planned in Codex 0.73.x).

The profile approach is what every other tool in this series converges on too, and the same guidance applies: if Codex connects but nothing generates, work through the connection-refused checklist — it’s the same Ollama server whether Cline or Codex is calling it.

The 64K context floor

Ollama’s integration doc is unusually blunt here: “Codex requires a larger context window. It is recommended to use a context window of at least 64k tokens.”

Now line that up against Ollama’s defaults. The FAQ still documents a 4,096-token baseline, and recent releases scale the default with available VRAM — under 24 GiB you’re still in the low thousands. Codex’s system prompt, tool schemas, and AGENTS.md alone can swallow that before the model reads a single source file, and Ollama truncates from the top of the prompt silently. The symptoms are the classic ones: the agent forgets its instructions mid-session, re-reads the same file repeatedly, or proposes edits against code it can no longer see.

Fix it server-wide before blaming the model:

OLLAMA_CONTEXT_LENGTH=65536 ollama serve

The KV-cache VRAM cost is real — a 64K window on a 20B-class model wants a 24 GB card, which is why the used RTX 3090 keeps showing up as the price-performance pick for this workload. The full diagnosis, including per-tool overrides and the Modelfile route, is in our num_ctx deep dive; everything there applies to Codex unchanged.

There’s a Codex-side wrinkle the other tools don’t have: for models it doesn’t recognize, Codex has been observed assuming an enormous default window (272K in the April 2026 issue-tracker report) instead of asking the server. The result is the mirror-image failure — Codex happily builds a prompt far bigger than Ollama’s actual window, and you get overflow errors or truncation instead of the compaction Codex would normally trigger. Until per-model context configuration lands properly, the practical rule is: set OLLAMA_CONTEXT_LENGTH as high as your VRAM allows, and keep sessions on a local model shorter than you would with cloud Codex.

Which model to run

HardwareModelWhat you actually get
16 GB VRAM or unified memorygpt-oss:20b (default)The model --oss was built around; solid tool calling, runs within 16 GB per OpenAI
24 GB VRAM (RTX 3090/4090 class)gpt-oss:20b at 64K context, or qwen3-coderThe realistic sweet spot: the context window this agent needs
80 GB (H100 class, Mac Studio, multi-GPU)gpt-oss:120bBig quality step up; MXFP4 fits it on a single 80 GB GPU
Anything, with an Ollama accountgpt-oss:120b-cloudOllama-hosted — no download, no VRAM limit, but it’s not local anymore

Two honesty notes. First, gpt-oss:120b-cloud appears in Ollama’s own Codex doc and it’s a fine escape hatch, but be clear-eyed: your prompts are going to Ollama’s servers, so the privacy argument for this whole setup evaporates — you’ve swapped one cloud for another. Second, gpt-oss:20b is a good local agent model and the path of least resistance here, but it is not GPT-5.5. On multi-file refactors you will feel the gap. Our Codex CLI review covers what the cloud version does well; the local version keeps the harness and trades away the top-tier model.

If you’re below 16 GB, the VRAM-tier model guide on our sister site maps what’s realistic, and their GPU buying guide covers the hardware side. No GPU at all? A rented one on RunPod running Ollama gives you the same wiring with the privacy dial set to “trusted cloud” instead of “none.”

Where it breaks

The /model picker can’t see your local models. Out of the box, /model inside a Codex session lists OpenAI’s static cloud catalog — your Ollama library isn’t in it. This is the documented gap behind issue #17261 (April 2026), and it’s why the model_catalog_json line in the ollama launch config exists: the launch path generates a catalog file so the picker works. If you configured manually and want to switch models, do it with -m at launch or separate profiles, not /model.

--oss ignores your remote host. Point base_url at http://192.168.1.50:11434/v1, pass --oss, and Codex will still call localhost — the maintainers closed the report as not-planned. The workaround is structural: remote hosts go in a named provider + profile (Path 3), and --oss stays reserved for same-machine setups.

Model choice doesn’t persist across --oss sessions. The flag re-resolves its default each time rather than remembering what you last ran. Again: profiles fix this, flags don’t.

None of these are dealbreakers once you know the shape of the fix — they’re all the same fix. The moment your setup outgrows one machine and one default model, stop using the convenience flag and write the ten-line profile.

FAQ

Do I need a ChatGPT account or API key for this? No. The whole point of the --oss/Ollama path is that requests go to localhost:11434, not OpenAI. You skip codex sign-in entirely. (Cloud Codex, by contrast, authenticates through your ChatGPT plan.)

Is this free? The software is: Codex CLI is open source (Apache-2.0, github.com/openai/codex), Ollama is free, and the gpt-oss weights are freely downloadable. Your costs are hardware and electricity. Ollama’s -cloud model variants are the exception — those run on Ollama’s infrastructure under their account terms.

Can I use LM Studio instead of Ollama? Yes — set oss_provider = "lmstudio" and Codex targets LM Studio’s local server instead. The context-window warning applies identically; set the window in LM Studio’s server settings before loading the model.

How does this compare to Claude Code + Ollama? The wiring is nearly identical in 2026 — both have an ollama launch one-liner and both need the 64K context fix. Codex has the more mature built-in local flag (--oss); Claude Code needs env vars or the launch path. Model-quality trade-offs are the same class of downgrade in both. Side-by-side cloud comparison: Claude Code vs Codex CLI.

Which is better for local: Codex CLI or OpenCode? OpenCode remains the most local-first of the terminal agents (its --local flag and model-agnostic design were built for this), but Codex’s harness — approvals, sandboxing, AGENTS.md — is more polished. If local is your primary mode, try OpenCode first; if local is your fallback mode, stay with the agent you already use.

  • RTX 3090 (24 GB) — the used-market sweet spot: runs gpt-oss:20b with the 64K context window this agent actually needs

Sources

Last updated July 21, 2026. Setup flows and defaults change frequently — verify against the official docs before relying on them.

Was this article helpful?