Running Codex with Ollama

Who this is for and what you will be able to do

This guide is for developers who want Codex CLI to run on models served by Ollama, rather than only on cloud models. After reading it you should be able to install Codex CLI, start it with ollama launch codex, switch models inside a session, and keep a configuration in a profile file so it applies every time.^[1]

Install Codex CLI first

Codex CLI is installed with npm:^[1]

npm install -g @openai/codex

Quick start with ollama launch codex

The simplest route is to run the launch command:^[1]

ollama launch codex

When Codex is started this way, Ollama refreshes the model catalog and uses a dedicated Codex profile for that session.^[1]

Inside Codex, type /model to switch between your installed Ollama models that support tools, without restarting. The model you started with stays selected. Each model keeps its own context window, vision and thinking settings.^[1]

To add a model to the picker, pull it with ollama pull <model> before you launch.^[1]

To configure Codex without starting it, run ollama launch codex --config. To remove the launch profile and the model catalog that Ollama generated, run ollama launch codex --restore.^[1] The two commands work as a pair: --config sets things up, and --restore removes what Ollama generated for that setup.^[1]

Manual setup with codex --oss

Without ollama launch, add the --oss flag to codex to send it to Ollama:^[1]

codex --oss

To pick a model, pass the -m flag:^[1]

codex --oss -m gpt-oss:120b

For a cloud model, use the name with the -cloud suffix:^[1]

codex --oss -m gpt-oss:120b-cloud

Keep the setup in a profile file

To make the configuration persist, create ~/.codex/ollama-launch.config.toml with the content below. Replace the model_catalog_json path with your own; the example uses /Users/you/.codex/model.json.^[1]

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"

In that configuration, model_provider points to a provider named ollama-launch. Its base_url is http://localhost:11434/v1/, an address on your own machine, and wire_api is set to responses.^[1]

After saving the file, run codex --profile ollama-launch.^[1]

A profile is a named set of settings. When --profile selects it, Codex uses the model, provider and interface settings stored in it, so you do not have to type them on the command line each time.^[1] The model catalog path in the example is a local file, so it is specific to the machine where it is created.

Web search

Web-search requests that Codex sends through the Ollama profile are executed by Ollama, for both local and cloud models. To use the web-search service, sign in with ollama signin first.^[1]

To turn off web search for one Codex session, run:^[1]

codex --profile ollama-launch -c 'web_search="disabled"'

Things to watch

The page recommends a context window of at least 64k tokens for Codex. The context window is the amount of text a model can handle at once. If it is too small, there is less room for the project files Codex reads and for the conversation history.^[1]

Each model keeps its own context window setting, so when you switch models, check that each one has enough room.^[1]

The two startup routes suit different needs. To try things out, ollama launch codex is the least work. To keep one set of settings in effect every time, the profile file is the steadier choice. If you switch to another model, pull it with ollama pull before you start Codex.^[1]

Next steps

For the full details of Codex CLI, read OpenAI's Codex CLI documentation. For Ollama's models and commands, read Ollama's own documentation. The official pages are the reference for both.^[1]

Adapted from Ollama's documentation page on Codex CLI integration^[1], released under the MIT License.