Codex Desktop接入本地Ollama模怎么理解-相关要点和注意事项

更直接地说，先把使用场景分清楚，再按功能选择做法，能少走不少弯路。很多人使用skt时只停留在基础操作，真正影响效率的往往是接入前的三项前置条件、五条接入路径、路径 A：ollama launch codex（最快，推荐新手）这些细节。

接入前的三项前置条件容易忽略的点

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

① Ollama 0.30 以上版本

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

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

② 上下文窗口 64k Token 以上

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

③ 配置文件位置

换到实际使用里，项目级 .codex/config.toml 无法覆盖 model_provider 和 model_providers 字段：Codex 的 Provider 认证必须写在用户级配置

五条接入路径容易忽略的点

路径 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 CLIollama launch codex# 启动 Codex Desktop Appollama 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:120bcodex --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"

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

第二步：创建 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 GPTcodex exec --profile ollama-launch "修复 src/auth 里的测试"

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

路径 D：LM Studio

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

oss_provider = "lmstudio"

codex --oss

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

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

适合自建 vLLM、Unsloth 推理服务，或通过七牛云 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 = falseenv_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

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

问题二：404 /v1/responses 错误

原因是目标端点只有 Chat Completions API，没有 Responses API。解法有两种：最常见的报错。

1. 检查 Ollama 版本是否 0.30+（旧版 Ollama 不支持 Responses 转换层）
2. 使用社区工具 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 模式下完整保留：

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

更直接地说，降级的部分主要是工具调用可靠性（与模型质量强对应）和需要 GPT 独占能力的功能。从操作角度看，实际建议：OSS 模型适合做垂直切片任务（“修这个文件里的 bug”），复杂跨库重构优先用 GPT Profile。

工具调用与多模型统一接入要先看什么

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