Codex + Ollama: run OpenAI Codex CLI on a local model
12 min read
Run OpenAI Codex CLI on a local model with Ollama: ollama launch codex, the --oss flag, the config.toml provider block, context length, models and limits.
OpenAI's Codex CLI can run against a model that Ollama serves on your own machine. ollama launch codex sets it up in one command, and Codex has its own switch for the same thing: codex --oss, which uses a built-in ollama provider at http://localhost:11434/v1.
You need Ollama 0.15 or later for the launch command, a context length of 64K tokens, and a model that supports tool calling. Codex's default local model is gpt-oss:20b, which runs on 16 GB of memory. This guide gives the one-command path, the --oss path, the manual config.toml provider, how to check that requests stay local, the known limits, and how to roll the same setup out to a team with Aventail™ Connect.
What you need
Minimum | Comfortable | |
|---|---|---|
Ollama | 0.13.4 for | Latest release: 0.40.16, published 9 November 2026 |
Codex CLI | Any current version | Latest release: 0.169.0, published 13 November 2026 |
Context length | 64K tokens. Ollama's Codex page says to use at least 64K | The model's full window, if it fits in memory |
Memory (unified or VRAM) | 16 GB for gpt-oss:20b | An 80 GB GPU for gpt-oss:120b |
Disk | 14 GB for gpt-oss:20b | 65 GB for gpt-oss:120b |
Two figures are in circulation for the context length. Ollama's blog post of 15 January 2026 recommended at least 32K. Ollama's current Codex page says at least 64K. Use 64K.
Ollama sets a default context length from your GPU memory: 4K below 24 GiB, 32K from 24 to 48 GiB, 256K at 48 GiB and above. With less than 24 GiB that is 4K, so you raise it by hand in step 1.
Step 1: install Ollama and set the context length
macOS and Linux:
curl -fsSL https://ollama.com/install.sh | sh
Windows PowerShell:
irm https://ollama.com/install.ps1 | iex
Set the context length before you serve a model. The quickest way is the slider in the Ollama app settings. From a terminal:
OLLAMA_CONTEXT_LENGTH=64000 ollama serve
Check what is loaded, how much context it has, and whether it sits on the GPU or the CPU:
ollama ps
Step 2: pull a model that supports tools
Codex edits files and runs commands through tool calls. Every model below carries the tools tag in the Ollama library on 15 November 2026.
Model | Size on disk | Context window | Memory guidance from Ollama | Tags |
|---|---|---|---|---|
gpt-oss:20b | 14 GB | 128K | Runs on systems with as little as 16 GB | tools, thinking |
gpt-oss:120b | 65 GB | 128K | Fits on a single 80 GB GPU | tools, thinking |
qwen3-coder:30b | 19 GB | 256K | Not published for the 30B size | tools |
glm-4.7-flash | 19 GB | 198K | About 23 GB of VRAM at 64K context | tools, thinking |
devstral-small-2:24b | 15 GB | 384K | Not published | tools, vision |
qwen3.5:27b | 17 to 20 GB | 256K | Not published | tools, thinking, vision |
gpt-oss is the model family Codex's local mode is built around: it is the default for --oss, and Ollama's examples use it. Where Ollama publishes no memory figure, use the file size as the floor, because the weights and the 64K context both have to fit in memory.
ollama pull gpt-oss:20b
Step 3: install Codex CLI
macOS and Linux:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Windows, from a new PowerShell window:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Or with npm, which is the command Ollama's page uses:
npm install -g @openai/codex
Step 4: launch Codex on Ollama with one command
ollama launch codex
Ollama refreshes the model catalogue and uses a dedicated Codex profile for that session. Inside Codex, type /model to switch between your installed, tool-capable Ollama models without restarting. Each model keeps its own context window, vision and thinking settings. Pull extra models with ollama pull before you launch so they appear in the picker.
To configure without launching:
ollama launch codex --config
To remove the Ollama launch profile and the generated model catalogue:
ollama launch codex --restore
Step 5: or use Codex's own --oss flag
Use this when you want Codex to start from its own command.
codex --oss
With no -m, Codex uses gpt-oss:20b and pulls it if it is missing. To name a model:
codex --oss -m gpt-oss:120b
--oss supports two local providers, Ollama and LM Studio. Codex picks one in this order: the --local-provider flag, the oss_provider key in your config, then a prompt that asks you to choose. codex exec exits with an error if neither is set. To make Ollama the default, add this to ~/.codex/config.toml:
# Default local provider used with `--oss`oss_provider = "ollama" # or "lmstudio"
For one run:
codex --oss --local-provider ollama -m gpt-oss:20b
Step 6: or define the provider in config.toml
Use this when you want a named, persistent setup, or when Ollama runs on another host.
Ollama documents a profile file. Create ~/.codex/ollama-launch.config.toml:
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"
Then run:
codex --profile ollama-launch
--profile layers ~/.codex/ollama-launch.config.toml on top of your base config, so your normal Codex setup stays untouched. model_catalog_json points at a model catalogue file; ollama launch codex generates one. Replace /Users/you with your home directory.
To put the provider in your main ~/.codex/config.toml, use the keys from the Codex configuration docs:
model = "gpt-oss:20b"model_provider = "local_ollama"model_context_window = 64000[model_providers.local_ollama]name = "Ollama"base_url = "http://localhost:11434/v1"wire_api = "responses"
Four things to know about these files:
responsesis the only wire API. Codex removedwire_api = "chat". A guide that tells you to set it is out of date, and Codex returns an error that names the fix. The oldollama-chatprovider ID is gone as well.Pick your own provider ID. Codex reserves
openai,ollama,lmstudio,amazon-bedrock,amazon-bedrock-runtimeandgcpfor built-in providers, and you cannot override them.Provider keys belong in the user config. Codex ignores
model_provider,model_providersandprofilein a project's.codex/config.tomland prints a warning.Tell Codex the real window.
model_context_windowis the number of context tokens available to the active model. Set it to the length you gave Ollama.model_auto_compact_token_limitsets the token count at which Codex compacts the history.
Step 7: check it is running locally
Run
ollama pswhile Codex is answering. The model should be listed with the context length you set.In Codex, run
/status. It shows the session configuration, the active model and the remaining context capacity.Turn off the traffic that goes to OpenAI by default. Codex periodically sends anonymous usage and health data to OpenAI unless you add this to
~/.codex/config.toml:[analytics]enabled = false[feedback]enabled = falsecheck_for_update_on_startup = falsestops the update check.Turn off web search if nothing may leave the machine. Through the Ollama profile, Codex web-search requests are executed by Ollama's web-search service, which needs
ollama signin:codex --profile ollama-launch -c 'web_search="disabled"'Unplug the network and ask Codex to explain a file. If it answers, the model is local.
What works and what does not on a local model
Works: Ollama says Codex can read, modify and execute code in your working directory with open models, and /model switching works when you start with ollama launch codex. Codex's sandbox, approval prompts and AGENTS.md are features of the client and do not depend on the model provider.
Known limits:
Stateless Responses only. Ollama supports the Responses API without the stateful parts: no
previous_response_id, noconversation, notruncation. Each request therefore carries the conversation so far.No prompt caching to rely on. Ollama's OpenAI-compatible API documents no cache settings. On a local model the cost of a long conversation is time.
Tool reliability depends on the model. gpt-oss is OpenAI's open-weight family, described as designed for agentic tasks, and it is Codex's default local model. Reliability with other open models varies, so test a real edit before you settle on one.
Reasoning display. OpenAI's docs note that some models and providers, gpt-oss among them, do not emit raw reasoning, so the setting that shows it has no visible effect.
OpenAI account features are out of scope. Codex cloud tasks and ChatGPT sign-in features run on OpenAI's service. The built-in local providers are defined in the Codex source with
requires_openai_authset to false. OpenAI's docs do not say whether a first run with--ossasks you to sign in.The context default is too small. Below 24 GiB of VRAM Ollama allocates 4K unless you change it. Ollama says coding tools need at least 64000 tokens.
Speed. Neither vendor publishes tokens per second for this pairing. Ollama's guidance is to avoid CPU offload; check the PROCESSOR column in
ollama ps.
Codex in the ChatGPT desktop app is a separate integration. Ollama 0.34.0 and later can add local and cloud models to Codex's model picker from the Ollama app, under Apps.
Ollama cloud models are not your own models
Ollama's Codex page also shows codex --oss -m gpt-oss:120b-cloud. Cloud models run on Ollama's servers. Ollama states that prompt and response data is never logged or trained on, and that it hosts models primarily in the United States with routing to Europe for extra capacity. If your code must stay on your machines, do not pass a -cloud or :cloud model name.
The same setup for a team with Aventail™ Connect
The steps above suit one developer who manages their own machine. They give an IT or security lead no record of which machine sent which request where, and no rule that a developer cannot edit back in config.toml.
Aventail™ Connect configures supported apps to send their model requests through Aventail™ Link, the inference engine and gateway that runs on each machine. Routing rules are set in Aventail™ Control and evaluated on the device. Codex, Claude Code, Claude Desktop and OpenCode are supported. In this setup Link serves the model itself, in place of Ollama.
Sign in to Control at control.aventail.co.uk and choose Connect a device.
Install Link on each machine: desktop installers for macOS (Apple silicon), Windows x64 and Linux x64, or unattended:
curl -fsSL https://get.aventail.co.uk/install.sh | AVENTAIL_REGISTRATION_KEY='YOUR_REG_KEY' shServe a model. In Models, download a coding model and choose Start serving.
Connect Codex. In Connected apps, choose Connect next to Codex. The Codex CLI, the editor extension and Codex in the ChatGPT desktop app share one user configuration, so one connection covers all three. Sessions that are already open keep their model.
Check where it ran. Send a harmless prompt, then open Requests in Control.
Write the routing rule. The first matching enabled rule wins. For a local-only team, permit only On device; if local serving is unavailable, the request fails with an error.
Two limits from Aventail™'s docs: the Codex connection uses the Responses API, and the reviewed route supports local models, peers and OpenAI. Other cloud providers are not supported for Codex on this path.
Disconnect restores the settings Link changed. The Free plan covers three connected devices, including business use. Starter is £50 a month excluding VAT and includes ten devices. Routing policies need Control for Enterprise.
Which path to take
Codex + Ollama by hand | Codex with Aventail™ Connect | |
|---|---|---|
Who it suits | One developer on their own machine | A team whose code must stay on approved models |
Setup |
| Connect button in Link, rules in Control |
Who picks the model | The developer, with | The developer in Link, within the routing rule |
Where requests go | Wherever | Where the routing rule says, evaluated on the device |
Record of requests | None | Requests view in Control |
If the local model is down | Developer switches provider | Fails with an error, or falls back to an approved destination |
Cost | Free | Free for three devices; £50 a month for ten |
Frequently asked questions
Can Codex CLI run on a local model?
Yes. codex --oss runs Codex against a local provider, Ollama or LM Studio. ollama launch codex does the same setup from the Ollama side.
Which Ollama model does Codex use by default?
gpt-oss:20b. Codex pulls it if it is not on the machine. Pass -m to use another model, for example codex --oss -m gpt-oss:120b.
Which Ollama version does Codex need?
Codex checks the server version and refuses anything older than 0.13.4, because it needs the Responses API. ollama launch needs 0.15 or later.
Why does my config with wire_api = "chat" fail? Codex no longer supports the Chat Completions wire API. Set wire_api = "responses" in the provider block, or remove the line, since responses is the default.
How do I set the context length for Codex with Ollama?
Set it in Ollama first, with the app slider or OLLAMA_CONTEXT_LENGTH=64000 ollama serve. Then set model_context_window = 64000 in ~/.codex/config.toml so Codex compacts at the right point.
Can Codex use Ollama on another machine?
Yes. Define a provider in ~/.codex/config.toml with base_url set to that server's address ending in /v1, and point model_provider at it.
Is my code sent to OpenAI when I use Codex with Ollama?
Model requests go to the base_url you set. Codex still sends anonymous usage and health data to OpenAI by default; [analytics] enabled = false turns that off. For how Codex handles data on OpenAI's own service, see Is Codex safe for work?.
Related guides
Sources
Ollama, Codex CLI integration: https://docs.ollama.com/integrations/codex
Ollama, ChatGPT Desktop integration: https://docs.ollama.com/integrations/chatgpt
Ollama, Context length: https://docs.ollama.com/context-length
Ollama, OpenAI compatibility (Responses API): https://docs.ollama.com/api/openai-compatibility
Ollama blog, OpenAI Codex with Ollama (15 January 2026): https://ollama.com/blog/codex
Ollama blog, ollama launch (23 January 2026): https://ollama.com/blog/launch
Ollama download page and releases (v0.40.16): https://ollama.com/download and https://github.com/ollama/ollama/releases/latest
Ollama library: gpt-oss, qwen3-coder, glm-4.7-flash, devstral-small-2, qwen3.5 at https://ollama.com/library
Ollama cloud: https://ollama.com/cloud
OpenAI, Codex CLI: https://developers.openai.com/codex/cli
OpenAI, Codex command line options: https://developers.openai.com/codex/cli/reference
OpenAI, Codex advanced configuration: https://developers.openai.com/codex/config-advanced
OpenAI, Codex configuration reference: https://developers.openai.com/codex/config-reference
Codex GitHub repository, README and release 0.169.0: https://github.com/openai/codex
Codex source, built-in local providers: https://github.com/openai/codex/blob/main/codex-rs/model-provider-info/src/lib.rs and https://github.com/openai/codex/blob/main/codex-rs/ollama/src/lib.rs
Aventail™, Connect overview: https://docs.aventail.co.uk/docs/connect/overview
Aventail™, Initial setup: https://docs.aventail.co.uk/docs/getting-started/initial-setup
Aventail™, Routing: https://docs.aventail.co.uk/docs/fleet/routing
Aventail™, Pricing: https://aventail.co.uk/#pricing
All sources were read on 15 November 2026. The developers.openai.com/codex pages redirect to learn.chatgpt.com/docs.