本地大模型 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 或 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"

这条路要注意四个边界：

1. 只写在用户级 ~/.codex/config.toml。 Codex 会忽略项目 .codex/config.toml 里的 openai_base_url、model_provider 和 model_providers，以避免仓库偷偷改变机器的模型提供方。
2. 服务不只是“有 /v1/chat/completions”就一定够用。Codex 的具体工作流可能需要模型、流式响应、工具调用或其他兼容行为。
3. 鉴权由你的网关决定。若网关要求 Bearer token，应按网关和 Codex 当前认证配置正确设置；不要把 token 写进仓库文件。
4. 这不是 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。

LM Studio OpenAI 兼容本地 API 详解

LM Studio 可以把本地加载的模型变成 OpenAI 兼容接口。对现有项目来说，通常不需要重写调用逻辑：把 OpenAI 客户端的 base_url 改成 LM Studio 本地地址，再把 model 换成 LM Studio 里的模型标识即可。

最常用的地址是：

1

http://localhost:1234/v1

它适合接入已有的 Python、JavaScript、C# 或其他 OpenAI 客户端代码。下面按“先跑通，再接进项目”的顺序说明。

先说结论

要使用 LM Studio 的 OpenAI 兼容接口，只需要完成四步：

1. 在 LM Studio 的 Developer 页面启动本地服务器。
2. 加载一个聊天模型。
3. 请求 http://localhost:1234/v1/models，确认模型 ID。
4. 将客户端 base_url 改为 http://localhost:1234/v1。

最小 Python 写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

response = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 KV cache。"}
    ],
)

print(response.choices[0].message.content)

api_key="lm-studio" 在未开启鉴权时只是给 OpenAI SDK 的占位值；如果你在 LM Studio 服务设置中启用了 API token，则应改成真正的 token。

第一步：启动 LM Studio 本地服务器

打开 LM Studio，进入 Developer 页面，打开 Start server 开关。默认服务会监听：

1

http://localhost:1234

也可以使用 LM Studio 的命令行工具启动：

1

lms server start

如果电脑上还没有 lms，可以按 LM Studio 官方文档安装 CLI：

1

npx lmstudio install-cli

服务启动只代表 API 端口已监听，不代表已经有可推理的模型。继续在 Chat 或 Developer 页面加载一个模型，或者用 lms load 载入。

第二步：先获取模型 ID

不要凭文件名猜 model 参数。最稳的办法是请求模型列表：

1

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

Windows PowerShell 可以用：

1

Invoke-RestMethod http://localhost:1234/v1/models

返回的 data 列表里会有模型标识。之后在请求中把 model 填为实际返回的 ID。

这一步能避免两个常见问题：模型虽然下载了但还没加载，或者代码里写的名称与 LM Studio 当前暴露的模型 ID 不一致。

第三步：用 curl 测试 Chat Completions

先用最直观的 OpenAI 兼容端点测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的 LM Studio 模型 ID",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "解释什么是向量数据库。"}
    ],
    "temperature": 0.7
  }'

成功后，回答通常在：

1

choices[0].message.content

Chat Completions 会自动应用聊天模型的 prompt template。只要模型本身是 chat/instruct 类型，通常不需要在客户端手动拼接特殊控制 token。

Python 项目怎么替换 OpenAI

如果项目原本就使用 OpenAI Python SDK，重点通常只有两处：base_url 和 model。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

completion = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "system", "content": "你是一名 Python 助手。"},
        {"role": "user", "content": "写一个读取 JSON 文件的最小示例。"},
    ],
    temperature=0.2,
    max_tokens=500,
)

print(completion.choices[0].message.content)

这样做的好处是：应用层仍然使用 OpenAI SDK 的对象和返回格式，后端可在云端 OpenAI API 与本地 LM Studio 之间切换。

但“兼容”不等于每个云端模型特性都能原样复制。工具调用、结构化输出、视觉输入、推理内容和 Responses API 是否可用，仍取决于 LM Studio 版本、当前模型能力和对应端点支持情况。

流式输出

在 Chat Completions 中设置 stream=True：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

stream = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[{"role": "user", "content": "写一首四行小诗。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

流式输出适合聊天界面、终端工具和长回答。它改善的是用户等待体验，不会让本地模型本身生成得更快。

Embeddings、Responses 与原生 REST API 怎么选

LM Studio 的 OpenAI 兼容层包含常用端点：

LM Studio 也有自己的原生接口，当前推荐路径是 /api/v1/*，例如 /api/v1/chat 和 /api/v1/models。原生 API 更适合需要模型加载/卸载、状态化聊天、MCP 或 LM Studio 专属能力的项目。

简单判断：已有 OpenAI SDK 项目，优先用 /v1；新项目要深度管理本地模型或使用 LM Studio 专属能力，再考虑 /api/v1。

结构化输出和工具调用

LM Studio 的 OpenAI 兼容层支持在相应端点中使用工具调用与结构化输出，但先确认两件事：

1. 你加载的模型本身要有较可靠的工具调用或 JSON 输出能力。
2. LM Studio 和客户端 SDK 的版本要足够新。

不要只因为请求没有报错，就假设模型能稳定生成符合 schema 的结果。上线前应使用真实参数、异常分支和多轮请求做测试。

常见报错排查

1. 连接被拒绝或 Connection refused

先确认 Developer 页面里的服务器已启动，再测试：

1

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

如果这里都连不上，优先检查端口、LM Studio 是否仍在运行，或本机安全软件是否拦截本地端口。

2. 404 Not Found

最常见原因是路径写错。OpenAI 兼容聊天端点是：

1

/v1/chat/completions

不是 /api/v1/chat/completions。后者属于另一套原生 API 路径。

3. 模型不存在或返回空列表

先在 LM Studio 中加载模型，再检查 /v1/models 的返回。代码里的 model 必须使用实际返回的标识，不要照抄别人的模型名。

4. 能回答但格式很奇怪

检查是否加载了 base 模型而不是 instruct/chat 模型；同时检查聊天模板是否由 LM Studio 自动应用。对于工具调用和 JSON 输出，还要确认模型是否真正支持该能力。

5. 局域网设备访问不到

LM Studio 可以在 Developer 页面配置服务到本地网络。开启网络访问后，还需要确认防火墙、监听地址和 API token 设置。不要把无鉴权的本地模型服务直接暴露到公网。

一套最小接入清单

1
2
3
4
5
6
7

1. LM Studio Developer -> Start server
2. 加载一个 instruct/chat 模型
3. curl http://localhost:1234/v1/models
4. 客户端 base_url 改为 http://localhost:1234/v1
5. model 填实际返回的 ID
6. 用 chat/completions 跑通单轮请求
7. 再测试流式、工具调用、Embeddings 或结构化输出

先跑通最小请求，再接 RAG、Agent 或编辑器插件，排障会简单很多。

总结

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

1
2
3
4
5

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

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

参考：

• Codex OSS mode local providers
• Codex configuration reference
• Codex developer commands
• LM Studio OpenAI 兼容接口教程
• vLLM KV Cache 内存不足排查