本地大模型 API 给 Codex 使用教程：Ollama、LM Studio 和 vLLM

想让 Codex 使用本地大模型，先不要把任何 OpenAI 兼容地址直接塞进项目配置。当前 Codex 有一条更稳妥的本地模型路径：OSS 模式。它原生支持选择 Ollama 或 LM Studio 作为本地提供方。

最短命令是：

1

codex --oss --local-provider ollama

或者：

1

codex --oss --local-provider lmstudio

如果你自己部署的是 vLLM、LiteLLM 或其他 OpenAI 兼容网关，则可以研究 openai_base_url 的高级配置。但这条路径要求服务真正兼容 Codex 所需的 API 行为，排障成本也更高，不应和内置 OSS 模式混为一谈。

先选对路线

你的本地服务	推荐接法	适合谁
Ollama	`codex --oss --local-provider ollama`	想最快跑通本地模型
LM Studio	`codex --oss --local-provider lmstudio`	已在 LM Studio 下载和管理模型
vLLM / 自建 OpenAI 兼容服务	用户级 `openai_base_url`	已了解 API 兼容性、鉴权与模型路由的高级用户

普通个人用户建议先跑通 Ollama 或 LM Studio。Codex 的 --oss 会使用指定的本地 OSS 提供方；如果没有传 --local-provider，也没有设置默认值，交互式 CLI 会提示你选择，但 codex exec 会直接报错。

方案一：用 Ollama 接入 Codex

1. 确认 Ollama 和模型可用

先检查 Ollama 是否可用：

1
2


ollama -v
ollama ls

没有模型时，先下载一个适合本机显存的代码或通用模型，例如：

1

ollama pull qwen3:8b

再单独测试：

1

ollama run qwen3:8b

模型在 Ollama 里都跑不通时，先解决显存、驱动、模型下载或 Ollama 服务问题；不要直接转到 Codex 排查。

2. 单次使用本地模型

在项目目录执行：

1

codex --oss --local-provider ollama

随后像平时一样输入任务，例如：

1

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

这只影响当前会话。想临时切回常规 Codex，不带 --oss 启动即可。

3. 把 Ollama 设为默认本地提供方

如果经常使用本地模型，把下面内容放到用户级 Codex 配置文件：

1

oss_provider = "ollama"

之后可直接运行：

1

codex --oss

Codex 的用户级配置通常位于 CODEX_HOME 下，默认是 ~/.codex/config.toml；Windows 常见路径是：

1

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

修改后重开 Codex。若已有复杂配置，先备份 config.toml，只添加这一行，不要覆盖原有 sandbox、MCP、技能等设置。

方案二：用 LM Studio 接入 Codex

LM Studio 适合已经下载了 GGUF 模型、希望用图形界面调上下文和 GPU 卸载的人。

1. 在 LM Studio 启动本地服务并加载模型

进入 LM Studio 的 Developer 页面，启动 server，并确认一个 chat/instruct 模型已经加载。LM Studio 的本地 API 默认监听在：

1

http://localhost:1234

可以先验证模型服务：

1

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

这里返回的是 LM Studio 侧模型状态；它有助于确认服务和模型都已就绪。

2. 用 Codex OSS 模式启动

1

codex --oss --local-provider lmstudio

长期默认配置：

1

oss_provider = "lmstudio"

然后使用：

1

codex --oss

LM Studio 的模型上下文长度、GPU offload 和推理参数仍由 LM Studio 管理。若 Codex 反应慢，优先检查模型大小是否超过显存、上下文是否设得过长，以及是否同时有其他本地推理服务占用 GPU。

方案三：vLLM 等 OpenAI 兼容 API 的高级接法

vLLM、LiteLLM、企业网关和一些代理会提供 OpenAI 兼容的 /v1 接口。Codex 的官方配置参考提供了 openai_base_url，用于覆盖内置 openai 提供方的基础地址。

示意配置：

1

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

如果服务在局域网主机：

1

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

这条路要注意四个边界：

只写在用户级 ~/.codex/config.toml。 Codex 会忽略项目 .codex/config.toml 里的 openai_base_url、model_provider 和 model_providers，以避免仓库偷偷改变机器的模型提供方。
服务不只是“有 /v1/chat/completions”就一定够用。Codex 的具体工作流可能需要模型、流式响应、工具调用或其他兼容行为。
鉴权由你的网关决定。若网关要求 Bearer token，应按网关和 Codex 当前认证配置正确设置；不要把 token 写进仓库文件。
这不是 Codex 官方列出的 OSS 本地提供方。遇到异常时，先用 Ollama 或 LM Studio 验证 Codex OSS 模式，再排查网关兼容性。

vLLM 服务可先单独验证：

1

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

只有该命令稳定返回模型列表后，才继续检查 Codex 的用户级 openai_base_url。

怎么选模型

本地模型能否“用”与能否“像 Codex 官方模型一样可靠”是两件事。代码 Agent 通常需要长上下文、稳定工具调用、较强的代码理解和足够快的生成速度。

选型时至少看：

显存能否容纳模型权重和常用上下文；
模型是否是 instruct/chat 或专门的代码模型；
是否能稳定遵循文件修改、测试和命令执行要求；
是否支持你需要的工具调用或 JSON 输出；
长任务下是否容易跑偏、忘记约束或产生不完整修改。

本地 7B/8B 模型适合仓库浏览、简单脚本、文档整理和局部修改。多文件重构、复杂测试修复和长时间 Agent 任务，对模型和硬件要求更高；不要因为本地 API 能连通，就默认它适合承担高风险自动改动。

一套安全的起步方式

第一次用本地模型驱动 Codex，建议先限制权限：

1

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

先让模型完成只读任务：

1

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

确认模型理解仓库、输出稳定后，再逐步允许 workspace 写入和测试执行。不要为了省确认步骤直接启用无沙箱或跳过审批的模式。

常见问题

1. `codex exec --oss` 直接报错

通常是没有指定本地提供方。使用：

1

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

或在用户级配置中设置 oss_provider。

2. Codex 连不上 Ollama 或 LM Studio

先分别验证服务：

1
2


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

再检查服务是否启动、模型是否加载、本机端口是否被防火墙或其他进程影响。

3. 本地模型总是改坏代码

先缩小任务：让它只读分析、只改一个文件、先给方案再执行。并使用 Git 分支或提交点保存可回退状态。模型能力不足时，提升提示词复杂度通常解决不了根本问题。

4. 配置写了却没有生效

检查是否误写进项目 .codex/config.toml。提供方相关键需要写在用户级 ~/.codex/config.toml；修改后重新启动 Codex。

总结

让本地大模型给 Codex 使用，优先顺序应是：

1
2
3
4
5


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

对绝大多数用户，--oss 是最短、最可控的入口。openai_base_url 适合已有兼容网关和运维需求的高级场景，但应放在用户级配置并先做接口兼容性验证。

参考：