Codex Desktop接入本地Ollama模型的五条路径全解析实用指南

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Codex Desktop接入本地Ollama模型的五条路径全解析”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

结合项目来看，Codex Desktop 是 OpenAI 推出的本地终端编程 Agent，2026 年 6 月 OpenAI Codex 团队成员 @thsottiaux 在 X 上提醒：Codex App、CLI 和 SDK 均可指向任意 OpenAI 兼容 API，不限于 GPT 系列模型；Ollama 同日随即响应，补全了 ollama launch codex 和 ollama launch codex-app 两条快捷入口，兼容 GLM-5.2、Kimi-K2.7-Code、gpt-oss:120b 等开源模型，无需 OpenAI API Key 即可完整采用 Codex 的 Agent 循环、工具执行和 AGENTS.md 项目记忆；核心设置文件为 ~/.codex/config.toml（用户级，不可用项目级覆盖），关键字段是 wire_api = "responses"（Codex 采用 Responses API 而非 Chat Completions，漏配这一行是最常用的 404 错误来源），上下文窗口建议 64k Token 以上；本文梳理从零起步到多 Profile 切换的五条接入路径，以及 Desktop 模型选择器不显示外部 Provider 等已知问题的修正方案。

接入前的三项前置条件

不管选哪条路径，以下三项必须先确认：

Ollama 0.30 以上版本

ollama launch codex 的 Profile v2 兼容需 Ollama 0.30+。用 ollama --version 确认，旧版 ollama launch codex 写入的是已废弃的 [profiles.*] 格式，Codex 0.134+ 不再接受。

# 检查版本
ollama --version
# 升级（macOS Homebrew）
brew upgrade ollama

上下文窗口 64k Token 以上

理解这一步时，Codex 的 Agent 循环会在每轮累积工具输出、diff、代码片段，上下文消耗速度远快于普通对话。Ollama 官方建议至少 32k Token，社区实测建议 64k+。选模型时优先确认上下文规格，不够长的模型在复杂任务中途截断会导致工具调用混乱。

设置文件位置

Codex 的 Provider 认证必须写在用户级设置，项目级 .codex/config.toml 无法覆盖 model_provider 和 model_providers 字段：

五条接入路径

路径 A：ollama launch codex（最快，建议新手）

在这个场景下，Ollama 托管整个 Profile 设置、模型目录和 Provider 注册，一条命令搞定：

# 安装 Codex CLI（如未安装）
npm install -g @openai/codex

# 拉取一个编程能力强的开源模型
ollama pull glm-5.2          # 推理强，适合 Fable 5 替代场景
ollama pull kimi-k2.7-code   # 专攻 Agentic 编程，SWE-bench 数据好
ollama pull gpt-oss:120b     # OpenAI 开源权重，官方 OSS 栈首选

# 启动 Codex CLI
ollama launch codex
# 启动 Codex Desktop App
ollama launch codex-app

ollama launch codex 在后台做了三件事：

1. 刷新 Codex 可见的模型目录（model_catalog_json）
2. 在 ~/.codex/config.toml 写入 [model_providers.ollama-launch]
3. 生成 ~/.codex/ollama-launch.config.toml Profile 文件，以 --profile ollama-launch 启动 Codex

只设置不启动（便于检查生成了什么）：

ollama launch codex --config

恢复到 Ollama 接入前的原始设置：

ollama launch codex --restore

路径 B：--oss标志（临时会话）

不想持久化设置，只想临时跑一次本地模型：

# 使用默认 OSS Provider（config.toml 里的 oss_provider 字段）
codex --oss

# 指定具体模型
codex --oss -m gpt-oss:120b
codex --oss -m glm-5.2

# Ollama Cloud 托管变体
codex --oss -m gpt-oss:120b-cloud

在 ~/.codex/config.toml 设置默认 OSS Provider：

# 默认本地 Provider，--oss 时生效
oss_provider = "ollama"   # 或 "lmstudio"

运行前确保 ollama serve 已在后台运行，且目标模型已 pull。

路径 C：手动写 config.toml（Power Users）

最灵活，适合需在 GPT 和本地模型之间更快切换的开发者。

第一步：在 ~/.codex/config.toml 注册 Provider

[model_providers.ollama-launch]
name     = "Ollama"
base_url = "http://localhost:11434/v1/"
wire_api = "responses"

wire_api = "responses" 是必填项，不是可选项。 在这个场景下，Codex 采用 OpenAI 的 Responses API（/v1/responses），而大多数兼容服务默认只暴露 Chat Completions（/v1/ch@t/completions）。漏配这一行会收到 404 错误。

第二步：新建 Ollama Profile 文件 ~/.codex/ollama-launch.config.toml

model              = "glm-5.2"
model_provider     = "ollama-launch"
model_catalog_json = "/Users/your-name/.codex/ollama-launch-models.json"

第三步：新建 GPT Profile 文件 ~/.codex/gpt.config.toml（可选）

model                  = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy        = "on-request"

切换采用：

codex --profile ollama-launch   # 本地 Ollama 模型
codex --profile gpt             # OpenAI GPT
codex exec --profile ollama-launch "修复 src/auth 里的测试"

Profile v2 格式说明（Codex 0.134+）： Profile 是独立的 .config.toml 文件（~/.codex/<profile-name>.config.toml），顶层 key，不再嵌套在 [profiles.name] 下。如果看到 --profile xxx cannot be used while config.toml contains legacy [profiles.xxx] 的报错，说明设置是旧格式，运行 ollama launch codex --restore 后重新设置。

路径 D：LM Studio

Codex 内置了 lmstudio Provider ID。在 LM Studio 里启动本地服务器后：

oss_provider = "lmstudio"

codex --oss

上下文要求和 wire_api = "responses" 限制与 Ollama 路径完全一致。如果 LM Studio 只暴露 Chat Completions 端点，同样需代理转换（见下方路径 E）。

路径 E：自定义 Provider（vLLM / 任意 OpenAI 兼容端点）

在这个场景下，适合自建 vLLM、Unh 推理服务，或借助七牛云 AI 等聚合平台统一接入多个开源模型：

model          = "your-model-id"
model_provider = "local_vllm"

[model_providers.local_vllm]
name                 = "Local vLLM"
base_url             = "http://localhost:8000/v1"
wire_api             = "responses"
requires_openai_auth = false
env_key              = "LOCAL_API_KEY"   # 无鉴权时填 dummy 字符串即可

# 启动
codex --oss --profile local_vllm

# 或单次覆盖
codex --config model_provider='"local_vllm"' --config model='"your-model-id"'

查看端点兼容的模型 ID：

curl http://localhost:8000/v1/models

注意： openai、ollama、lmstudio 是 Codex 保留 ID，自定义 Provider 不能用这三个名字，选 local_vllm、my_api 等唯一名称。

建议模型与硬件参考

硬件原则：Agent 任务的上下文窗口比模型参数量更影响实际体验。显存够放模型但不够跑长上下文时，任务中途截断比跑慢更致命——换更小量化版，保留足够 KV Cache 空间。

已知问题与修正方案

问题一：Desktop 模型选择器不显示外部 Provider

实际处理时，Codex Desktop App 的 UI 模型选择器目前不展示自定义 Provider 里的模型，即使 config.toml 设置完全正确。临时解法：借助 ollama launch codex-app 或命令行 --profile 参数绕过 UI 选择器启动。OpenAI 官方 GitHub issue 已记录，修复尚未发布。

问题二：404 /v1/responses 错误

从实现思路看，最常用的报错。原因是目标端点只有 Chat Completions API，没有 Responses API。解法有两种：

• 检查 Ollama 版本是否 0.30+（旧版 Ollama 不兼容 Responses 转换层）
• 采用社区工具 CC Switch 做协议转换代理（在 Responses 和 Chat Completions 之间转换）

问题三：Profile 格式旧版报错

--profile ollama-launch cannot be used while config.toml contains legacy [profiles.ollama-launch]

运行 ollama launch codex --restore 清除旧格式，更新 Ollama 到 0.30+，再重新 ollama launch codex。

问题四：Computer Use / 浏览器自动化不可用

这些功能是 GPT 独占特性，OSS 模式下不可用，与模型能力无关。

OSS 模式实际能跑什么

结合项目来看，接入 Ollama 后，以下 Codex 功能在 OSS 模式下完整保留：

• Agent 循环 + 工具执行（读取/修改代码、运行命令、提交 PR）
• 斜线命令：/init（自动生成 AGENTS.md）、/plan、/goal、/review、/diff、/context
• 项目记忆（AGENTS.md 和 .codex/ 目录）
• Skills 兼容（模型工具调用稳定性决定效果上限）
• 并行任务和多 Profile 切换

在这个场景下，降级的部分主要是工具调用可靠性（与模型质量强相关）和需 GPT 独占能力的功能。实际建议：OSS 模型适合做垂直切片任务（“修这个文件里的 bug”），复杂跨库重构优先用 GPT Profile。

工具调用与多模型统一接入

实际处理时，对于需把 Ollama 和多个云端模型（DeepSeek、Kimi、GLM 等）统一管理的团队，在路径 E 里设置聚合推理平台的接入端点是一种省事的方案——单一 API Key 覆盖多个模型，免维护多账号，配合 Codex 的 Profile 机制能够做到按任务性质自动切换推理来源。七牛云 AI 模型广场兼容 OpenAI 兼容格式，设置方式与自定义 Provider 路径完全一致，对已有 Codex 设置的团队迁移成本极低。

在这个场景下，以上就是Codex Desktop接入本地Ollama模型的五条路径全解析的详细内容，更多关于Codex Desktop接入Ollama模型的资料请关注脚本之家其它相关文章！