Codex 通过内置的 ollama provider ID 原生支持本地模型接入，配置核心只有三行：在 ~/.codex/config.toml 中指定 model_provider = "ollama"、model = "模型名"，再确保 Ollama 服务在本地跑起来，codex --oss 启动即可。但实际落地有几个细节容易踩坑：ollama 是系统保留 ID 不能自定义覆盖、沙箱模式默认关闭本地网络导致连不上 localhost:11434、WSL 环境下地址要换成 host.docker.internal、多数本地小模型不支持推理参数需手动关闭。本文基于 Codex 官方配置文档（developers.openai.com/codex/config-reference），整理最小化配置、扩展配置、Profile 多场景切换和逐项排查清单。

 

第一步：确认环境

接入前先确认 Ollama 和 Codex 都已正确安装并能运行。

 

# 检查 Ollama 版本和服务状态
ollama --version
ollama list                         # 查看本地已有模型
 
# 如果服务没启动，手动启动
ollama serve                        # 默认监听 http://localhost:11434
 
# 检查 Codex 版本
codex --version
 
# 拉取推荐的代码模型（如果还没有的话）
ollama pull qwen2.5-coder:32b       # 代码能力强，Apple Silicon 可流畅跑量化版
# 或者
ollama pull codellama:34b           # Meta 代码专项模型
# 或者轻量选项
ollama pull qwen2.5-coder:7b        # 7B 版，任何 Mac 都能跑

确认 Ollama API 可访问：

 

curl http://localhost:11434/v1/models
# 返回 JSON 表示服务正常

 

第二步：写配置文件

Codex 的配置文件位于 ~/.codex/config.toml（全局）。model_provider 和 oss_provider 只能放在全局配置，写在项目级 .codex/config.toml 里会被忽略。

最小化配置（三行搞定）

 

# ~/.codex/config.toml
 
model = "qwen2.5-coder:32b"    # 替换为 ollama list 里看到的模型名
model_provider = "ollama"
oss_provider = "ollama"

完整推荐配置

 

# ~/.codex/config.toml
 
model = "qwen2.5-coder:32b"
model_provider = "ollama"
oss_provider = "ollama"
 
# 本地模型通常不支持 reasoning，关闭避免报错
model_reasoning_effort = "low"
 
# 审批策略：本地用，可以相对宽松
approval_policy = "on-request"
 
# 沙箱需要允许本地网络，否则连不上 localhost:11434
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true             # ⚠️ 关键：必须开启，否则 Codex 连不上 Ollama
 
[tui]
file_opener = "cursor"

如果用自定义 Provider（更灵活）

ollama 是内置保留 ID，不能用来自定义。如果需要自定义 base_url（例如 Ollama 跑在非标准端口），改用自定义 ID：

 

model = "qwen2.5-coder:32b"
model_provider = "local-ollama"   # 注意：不能用 "ollama"，那是保留 ID
 
[model_providers.local-ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "responses"

 

第三步：启动 Codex

 

# 方式一：--oss 参数，自动使用 oss_provider 指定的本地 provider
codex --oss
 
# 方式二：直接指定模型（临时覆盖配置文件）
codex -m qwen2.5-coder:32b --model-provider ollama
 
# 方式三：用 Profile 区分本地和云端场景
codex --profile local

Profile 方式适合同时使用本地模型和云端模型的开发者，无需每次改主配置：

 

# 创建本地模型 profile
cat > ~/.codex/local.config.toml << 'EOF'
model = "qwen2.5-coder:32b"
model_provider = "ollama"
oss_provider = "ollama"
approval_policy = "on-request"
 
[sandbox_workspace_write]
network_access = true
EOF
 
# 使用本地模型
codex --profile local
 
# 使用默认（云端模型）
codex

 

常见坑和排查

坑一：连接被拒（connection refused）

现象： Codex 启动后报 connection refused 或 failed to connect to localhost:11434。

原因： Codex 的沙箱模式默认关闭出站网络。

修复：

 

[sandbox_workspace_write]
network_access = true

如果已有该配置仍然报错，检查 Ollama 服务是否在运行：

 

ps aux | grep ollama
# 没有输出说明服务没启动，运行 ollama serve

坑二：WSL 环境下连不上

现象： Windows WSL 里跑 Codex，localhost:11434 连接失败，而 Ollama 在 Windows 侧运行。

修复： 把 base_url 换成 Docker 网关地址：

 

model_provider = "wsl-ollama"
 
[model_providers.wsl-ollama]
name = "Ollama (WSL)"
base_url = "http://host.docker.internal:11434/v1"
wire_api = "responses"

坑三：模型名写错导致 404

Codex 的 model 字段填写的是 Ollama 里的完整模型 tag，不是别名。

 

# 先确认本地模型的完整名称
ollama list
 
# 输出示例：
# NAME                        ID              SIZE    MODIFIED
# qwen2.5-coder:32b           abc123...       18 GB   2 days ago
# codellama:34b               def456...       19 GB   1 week ago

config.toml 里的 model 字段要和 NAME 列完全一致：

 

model = "qwen2.5-coder:32b"   # 正确：带 :32b 后缀
# model = "qwen2.5-coder"     # 错误：缺少 tag，Ollama 可能找不到

坑四：推理参数报错

现象： 配置了 model_reasoning_effort = "high" 后报错或模型响应异常。

原因： 推理参数只对支持 Extended Thinking 的模型有效（如 Claude Opus 4.8），本地小模型不支持。

修复：

 

model_reasoning_effort = "low"     # 或直接删掉这行

坑五：ollama 作为自定义 ID 被拒绝

现象： 配置 [model_providers.ollama] 后 Codex 报错说 ID 是保留字。

原因： openai、ollama、lmstudio 是系统内置保留 ID，不能重定义。

修复： 换一个自定义 ID：

 

[model_providers.my-ollama]   # 或 local-ollama、ollama-local 等
base_url = "http://localhost:11434/v1"

 

推荐的本地代码模型

Ollama 支持数百个模型，以下是在 Codex 编程任务中表现较好的选项：

模型

参数量

适用硬件

代码能力

qwen2.5-coder:32b

32B

M3 Max / M4 Pro+

★★★★★ 当前开源代码最强之一

qwen2.5-coder:7b

7B

任何 Mac

★★★★ 轻量高性价比

codellama:34b

34B

M3 Max / M4 Pro+

★★★★ Meta 专项代码模型

deepseek-coder-v2:16b

16B

M2 Pro+

★★★★ 中文代码注释友好

llama3.1:8b

8B

任何 Mac

★★★ 通用，代码能力中等

 

# 拉取推荐模型
ollama pull qwen2.5-coder:32b
 
# 量化版本（减小内存占用，速度更快）
ollama pull qwen2.5-coder:32b-instruct-q4_K_M

 

本地模型 vs 云端模型：什么时候用哪个

场景

选择

原因

涉及保密代码、内网数据

本地 Ollama

数据完全不出本机

无网络环境、出差

本地 Ollama

零依赖外部服务

预算有限、高频调用

本地 Ollama

运行后无 API 费用

复杂多文件重构

云端（gpt-5.5 / Claude）

本地模型全局推理能力有限

CI/CD 流水线

云端

无稳定 GPU 资源，本地服务不可靠

日常补全、单文件修改

均可

7B-32B 本地模型已够用

Codex 的 Profile 机制让两种模式无缝切换——日常用 codex --profile local 跑本地，遇到复杂任务 codex 切回云端，不需要改任何配置文件。

 

常见问题 FAQ

Q1：用 Ollama 接 Codex，效果能媲美 gpt-5.5 吗？

在补全、单文件修改、写单测等任务上，qwen2.5-coder:32b 已接近中等云端模型水平。多文件依赖分析、复杂架构设计等需要大量全局推理的任务，32B 本地模型明显落后于 gpt-5.5 或 Claude Sonnet 4.6。适合"不出网的日常任务"，不适合"最高精度的大型重构"。

Q2：Ollama 运行中 Codex 可以直接用吗，还是要每次 ollama serve？

macOS 安装 Ollama 桌面版后，Ollama 服务会随系统启动自动运行，无需手动 ollama serve。命令行安装的版本需要手动启动或配置 launchd/systemd 开机自启。检查方式：curl http://localhost:11434/ 如果返回 "Ollama is running" 表示服务已在运行。

Q3：本地模型占用多少内存？会影响 Codex 的其他任务吗？

以 qwen2.5-coder:32b-instruct-q4_K_M 为例，加载到内存后占约 18-22 GB（因量化级别不同而异）。M4 Pro（48GB）以上可流畅运行，M3 Pro（36GB）会比较紧张。运行期间其他 Codex 操作（文件读写、命令执行）不受影响，只有新的模型推理请求需要等待 GPU 可用。

Q4：Codex 的 approval_policy 对本地模型有影响吗？

approval_policy 控制 Codex 执行工具时是否暂停请求确认，与模型无关。本地模型场景建议用 "on-request"——高风险操作（写文件、执行命令）前确认，避免推理能力较弱的模型产生意外操作。

Q5：能同时在 Claude Code 和 Codex 里用同一个 Ollama 实例吗？

完全可以。Ollama 默认监听 localhost:11434，多个工具同时请求时按顺序处理（Ollama 单并发）。Claude Code 通过 ANTHROPIC_BASE_URL 或 --model-provider 指向 Ollama，Codex 通过 config.toml 配置，两者互不干扰，共用同一个 Ollama 服务实例。

 

小结

Ollama 接 Codex 的核心路径：ollama serve 启动服务 → ollama pull 模型名 拉取代码模型 → ~/.codex/config.toml 写入三行配置（model、model_provider = "ollama"、sandbox_workspace_write.network_access = true）→ codex --oss 启动。最容易踩的两个坑是沙箱关闭本地网络（加 network_access = true 解决）和把 ollama 当自定义 ID 使用（它是系统保留字，改用其他名称）。代码任务推荐 qwen2.5-coder:32b，轻量场景用 7B 版。用 Profile 分离本地和云端配置，复杂任务随时切回云端。本文数据来源：Codex 官方配置文档（developers.openai.com/codex/config-reference），2026-06。

 

参考来源：

● Ollama 官方（ollama.com）

● 七牛云：AI 编程工具配置大全