Local large model API for Codex usage tutorial: Ollama, LM Studio and vLLM

If you want Codex to use local large models, don’t plug any OpenAI compatible addresses directly into the project configuration. Currently Codex has a more reliable local model path: OSS mode. It natively supports selecting Ollama or LM Studio as a local provider.

The shortest command is:

1

codex --oss --local-provider ollama

or:

1

codex --oss --local-provider lmstudio

If you deploy a vLLM, LiteLLM, or other OpenAI-compatible gateway yourself, you can explore the advanced configuration of openai_base_url. However, this path requires the service to be truly compatible with the API behavior required by Codex, and the troubleshooting cost is higher. It should not be confused with the built-in OSS mode.

Choose the right route first

Ordinary individual users are recommended to run through Ollama or LM Studio first. Codex’s --oss will use the specified local OSS provider; if --local-provider is not passed and no default value is set, the interactive CLI will prompt you to choose, but codex exec will directly report an error.

Solution 1: Use Ollama to connect to Codex

1. Confirm that Ollama and models are available

First check if Ollama is available:

1
2

ollama -v
ollama ls

When there is no model, first download a code or general model suitable for the local video memory, for example:

1

ollama pull qwen3:8b

Test separately:

1

ollama run qwen3:8b

If the model cannot run in Ollama, first solve the problem of video memory, driver, model download or Ollama service; do not directly go to Codex for troubleshooting.

2. Single-use local model

Execute in the project directory:

1

codex --oss --local-provider ollama

Then enter the task as usual, for example:

1

阅读这个仓库的 README，列出本地启动步骤，不要修改文件。

This only affects the current session. If you want to temporarily switch back to the regular Codex, just start it without --oss.

3. Set Ollama as the default local provider

If you frequently use local models, put the following content in the user-level Codex configuration file:

1

oss_provider = "ollama"

You can then run directly:

1

codex --oss

User-level configuration of Codex is usually located under CODEX_HOME, and the default is ~/.codex/config.toml; common Windows paths are:

1

C:\Users\你的用户名\.codex\config.toml

Reopen the Codex after modification. If there is a complex configuration, back up config.toml first and add only this line. Do not overwrite the original sandbox, MCP, skills and other settings.

Option 2: Use LM Studio to connect to Codex

LM Studio is suitable for people who have downloaded the GGUF model and want to use the graphical interface to adjust the context and GPU offload.

1. Start the local service in LM Studio and load the model

Enter the Developer page of LM Studio, start the server, and confirm that a chat/instruct model has been loaded. LM Studio’s local API defaults to listening at:

1

http://localhost:1234

You can verify the model service first:

1

curl http://localhost:1234/v1/models

What is returned here is the LM Studio side model status; it helps confirm that both the service and the model are ready.

2. Start in Codex OSS mode

1

codex --oss --local-provider lmstudio

Long term default configuration:

1

oss_provider = "lmstudio"

Then use:

1

codex --oss

LM Studio’s model context length, GPU offload, and inference parameters are still managed by LM Studio. If the Codex response is slow, first check whether the model size exceeds the video memory, whether the context is set too long, and whether other local inference services occupy the GPU at the same time.

Option 3: Advanced connection method for OpenAI compatible APIs such as vLLM

vLLM, LiteLLM, enterprise gateways, and some agents provide an OpenAI-compatible /v1 interface. Codex’s official configuration reference provides openai_base_url, which overrides the base address of the built-in openai provider.

Schematic configuration:

1

openai_base_url = "http://127.0.0.1:8000/v1"

If the service is on a LAN host:

1

openai_base_url = "http://192.168.1.20:8000/v1"

There are four boundaries to pay attention to on this road:

1. **Written only at user level ~/.codex/config.toml. ** Codex will ignore openai_base_url, model_provider and model_providers in project .codex/config.toml to prevent the repository from secretly changing the machine’s model provider.
2. A service is not just “/v1/chat/completions” that is enough. Codex specific workflows may require models, streaming responses, tool calls, or other compatible behaviors.
3. Authentication is determined by your gateway. If the gateway requires a Bearer token, it should be set correctly according to the current authentication configuration of the gateway and Codex; do not write the token into the warehouse file.
4. This is not an official Codex listed local provider for OSS. When encountering an exception, first use Ollama or LM Studio to verify the Codex OSS mode, and then check the gateway compatibility.

The vLLM service can be independently verified first:

1

curl http://127.0.0.1:8000/v1/models

Only after the command returns a stable list of models does the codex continue to be checked for user-level openai_base_url.

How to choose a model

Whether a local model can “use” and whether it can be “as reliable as the official Codex model” are two different things. Code Agents typically require long context, stable tool calls, strong code understanding, and sufficiently fast generation speeds.

When selecting, look at at least:

• Whether the video memory can accommodate model weights and common context;
• Whether the model is an instruct/chat or specialized code model;
• Whether it can stably comply with file modification, testing and command execution requirements;
• Whether it supports the tool calls or JSON output you need;
• Is it easy to go off track, forget constraints, or produce incomplete modifications under long tasks?

The local 7B/8B model is suitable for warehouse browsing, simple scripts, document organization and local modifications. Multi-file refactoring, complex test repairs, and long-term Agent tasks require higher model and hardware requirements; don’t assume that just because the local API can be connected, it is suitable for high-risk automatic changes.

A safe way to get started

When using a local model to drive Codex for the first time, it is recommended to restrict permissions first:

1

codex --oss --local-provider ollama --sandbox read-only

Let the model complete the read-only task first:

1

分析当前仓库的目录结构，指出启动命令和测试命令。不要修改文件。

After confirming that the model understands the warehouse and the output is stable, gradually allow workspace writing and test execution. Do not enable sandbox-less or approval-skipping mode directly to save the confirmation step.

FAQ

1. codex exec --oss reports an error directly

Usually no local provider is specified. use:

1

codex exec --oss --local-provider ollama "只分析当前仓库，不修改文件"

Or set oss_provider in user-level configuration.

2. Codex cannot connect to Ollama or LM Studio

First verify the services separately:

1
2

ollama ls
curl http://localhost:1234/v1/models

Then check whether the service is started, whether the model is loaded, and whether the local port is affected by a firewall or other processes.

3. Local models always break code

Reduce the task first: make it read-only for analysis, change only one file, and give the plan first before executing it. And use Git branches or commit points to save revertable state. When the model capability is insufficient, increasing the complexity of prompt words usually cannot solve the fundamental problem.

4. The configuration is written but does not take effect.

Check whether the project .codex/config.toml was written by mistake. The provider-related key needs to be written in user-level ~/.codex/config.toml; restart Codex after modification.

Summarize

To allow local large models to be used by Codex, the order of priority should be:

1
2
3
4
5

Ollama / LM Studio 跑通模型
-> codex --oss --local-provider ollama|lmstudio
-> 只读任务验证
-> 设置 oss_provider 作为默认
-> 再考虑 vLLM 等 OpenAI 兼容网关

For most users, --oss is the shortest and most controllable entry. openai_base_url is suitable for advanced scenarios that already have compatible gateways and operation and maintenance requirements, but should be configured at the user level and interface compatibility verified first.

refer to:

• Codex OSS mode local providers
• Codex configuration reference
• Codex developer commands
• LM Studio OpenAI compatible interface tutorial
• vLLM KV Cache insufficient memory troubleshooting