Codex CLI 切换模型 / 接入第三方 API 完全指南：DeepSeek、Ollama、config.toml 多 Provider 配置（2026）
(updated )
codex-cliai-codingapi-setupconfigdeepseekollama

Codex CLI 切换模型 / 接入第三方 API 完全指南：DeepSeek、Ollama、config.toml 多 Provider 配置（2026）

本文定位：Codex CLI 进阶配置，覆盖 config.toml、多 Provider 切换、接入 DeepSeek / Ollama / 自定义第三方 API、推理强度与沙箱。如果你是第一次装 Codex CLI、还没跑通基础环境变量，建议先看 Codex CLI 入门教程（5 分钟零基础版）。

为什么需要 config.toml

如果你还没装好 Codex CLI 或者卡在国内访问问题上，先看Codex 官网国内访问 + 完整安装教程把 macOS / Windows / Linux 三平台跑通再回来。

如果你已经用环境变量跑通了 Codex CLI 的基本配置（OPENAI_BASE_URL + OPENAI_API_KEY），日常用没问题。但碰到这些场景就不够了：

  • 手头有多个 API Key（比如 OfoxAI 用来做日常开发，OpenAI 官方 Key 用来跑基准测试），想快速切换
  • 项目 A 用 GPT-5.4-mini-codex 追求速度，项目 B 用 Codex-Max 做复杂重构
  • 需要控制沙箱权限、推理强度、上下文窗口这些细粒度参数

这些都指向同一个东西：~/.codex/config.toml。

config.toml 基本结构

Codex CLI 启动时按这个顺序加载配置：

  1. ~/.codex/config.toml — 用户级，全局生效
  2. 项目根目录 .codex/config.toml — 项目级，优先级更高（需信任项目）
  3. 命令行参数 — 最高优先级

一个完整的配置文件长这样：

# 当前使用的模型
model = "openai/gpt-5.4-mini-codex"

# 当前使用的 Provider
model_provider = "ofoxai"

# 上下文窗口（token 数）
model_context_window = 200000

# 推理强度：minimal | low | medium | high | xhigh
model_reasoning_effort = "medium"

# 沙箱模式：read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"

# 审批策略
approval_policy = "on-request"

# ──────── Provider 定义 ────────

[model_providers.ofoxai]
name = "OfoxAI"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOXAI_API_KEY"

[model_providers.openai]
name = "OpenAI Official"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"

配置自定义 API 提供商

核心操作就是在 [model_providers.<id>] 下面加 Provider。每个 Provider 需要三个字段：

字段说明示例
base_urlAPI 端点地址https://api.ofox.ai/v1
env_keyAPI Key 对应的环境变量名OFOXAI_API_KEY
name显示名称OfoxAI

OfoxAI 配置示例

[model_providers.ofoxai]
name = "OfoxAI Gateway"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOXAI_API_KEY"

环境变量照常设置：

# ~/.zshrc
export OFOXAI_API_KEY=<你的 OfoxAI Key>

然后在顶层指定使用这个 Provider：

model_provider = "ofoxai"
model = "openai/gpt-5.4-mini-codex"

接入 DeepSeek（第三方 API）

DeepSeek API 完全兼容 OpenAI 协议，只需要一个 Provider 块：

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

环境变量里放好 Key：

# ~/.zshrc
export DEEPSEEK_API_KEY=<你的 DeepSeek Key>

然后命令行用 --provider deepseek --model deepseek-chat 或者 deepseek-coder 即可。任何兼容 OpenAI 协议的第三方 API（Moonshot、智谱、Together 等）都是同一套写法，把 base_url 改成对应端点就行。

接入 Ollama 本地模型

完全离线场景，Codex CLI 直接连本地 Ollama：

[model_providers.local]
name = "Local Ollama"
base_url = "http://localhost:11434/v1"
env_key = "OLLAMA_API_KEY"

本地 Ollama 不验证 Key，但 env_key 字段不能省，随便给个值占位：

export OLLAMA_API_KEY=dummy

命令行：codex --provider local --model llama3.3 "..."。LM Studio 也同样支持。

多 Provider 同时注册

实际开发里最实用的配置是把上面几种都写进去，按需切换：

model_provider = "ofoxai"   # 默认用 OfoxAI

[model_providers.ofoxai]
name = "OfoxAI"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOXAI_API_KEY"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

[model_providers.openai-direct]
name = "OpenAI Direct"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"

[model_providers.local]
name = "Local Ollama"
base_url = "http://localhost:11434/v1"
env_key = "OLLAMA_API_KEY"

命令行临时切换：

# 用 OfoxAI（默认）
codex "写一个快排"

# 临时切到 DeepSeek
codex --provider deepseek --model deepseek-coder "写一个快排"

# 切到 OpenAI 官方
codex --provider openai-direct "写一个快排"

# 切到本地 Ollama
codex --provider local --model llama3.3 "写一个快排"

不用改配置文件，一个 --provider 参数搞定。

Codex CLI 怎么切换模型

切换 Codex CLI 用的模型有三种方式，按生效粒度从低到高：

  1. 改全局默认：编辑 ~/.codex/config.toml 顶层 model = "..."，全局生效，下一次运行 codex 就用新模型。
  2. 项目级覆盖：在项目根目录建 .codex/config.toml，只在这个项目里生效（需信任项目）。适合不同项目要用不同模型的场景。
  3. 命令行临时切换：codex --model openai/gpt-5.1-codex-max "..."，单次运行生效，最灵活，不动配置文件。

三种方式可以叠加用：日常默认走 gpt-5.4-mini-codex，遇到复杂重构临时 --model openai/gpt-5.1-codex-max 切到大模型即可。切换前确认目标模型在你配置的 Provider 里能跑：OfoxAI 覆盖 GPT-5.4-mini-codex / GPT-5.1-codex-max / GPT-5.5 等 OpenAI 系列；DeepSeek 走 deepseek-chat / deepseek-coder；Ollama 走本地模型名。

Codex CLI 怎么修改默认模型

修改默认模型只需要改 ~/.codex/config.toml 顶层一行：

# 改成你想要的默认模型
model = "openai/gpt-5.1-codex-max"

保存后下次运行 codex 立即用新模型，不需要重启终端。两个坑：

  • 项目目录里如果存在 .codex/config.toml 且也设了 model，会盖掉全局默认（项目级优先）。临时想用全局默认可以加 --model。
  • 模型名前缀必须带 Provider 命名空间。OpenAI 系列写 openai/gpt-5.4-mini-codex，DeepSeek 直接写 deepseek-coder。前缀写错会被静默忽略再走 fallback。

Codex CLI 怎么使用其他模型（非 OpenAI 官方）

Codex CLI 不止能跑 OpenAI 官方模型，任何兼容 OpenAI 协议的 API 都能接：

  • 国产模型：DeepSeek、Kimi（Moonshot）、智谱 GLM、Qwen，base_url 改成对应端点即可
  • 本地模型：Ollama、LM Studio 启用 OpenAI 兼容端点（默认 http://localhost:11434/v1）
  • 聚合网关：OfoxAI 一个 Key 接 GPT / Claude / Gemini / DeepSeek / Kimi 等所有主流模型，不用维护多个 Provider 和环境变量

接入只要三行 toml（具体看上面配置自定义 API 提供商段），然后命令行 codex --provider <id> --model <model_name> 即可。典型场景：默认走 OfoxAI 聚合 Key 省心，跑评测时临时 --provider openai-direct 切到官方对照，离线临时 --provider local 走 Ollama，三套同时存在不冲突。

进阶参数详解

推理强度 (model_reasoning_effort)

控制模型在回答前「想多久」。支持五个级别：

级别适用场景Token 消耗
minimal补全变量名、简单格式化最低
low常规代码生成、小修改低
medium日常开发（默认推荐）中
high复杂逻辑、多文件重构高
xhigh架构设计、疑难 Bug 排查最高
# 日常用 medium
model_reasoning_effort = "medium"

# Plan 模式可以单独设更高
plan_mode_reasoning_effort = "high"

沙箱模式 (sandbox_mode)

决定 Codex 能对你的文件系统做什么：

  • read-only — 只读，最安全，适合代码审查
  • workspace-write — 可以写当前工作目录（默认）
  • danger-full-access — 完全访问，谨慎使用
sandbox_mode = "workspace-write"

上下文窗口 (model_context_window)

手动指定模型的上下文长度。通过 OfoxAI 使用时，大部分模型会自动协商，但如果你用的是本地模型或者想限制 token 消耗，可以手动设：

model_context_window = 128000  # 128K

功能开关 (features)

Codex CLI 有一组实验性功能，通过 [features] 块控制：

[features]
multi_agent = true          # 多 Agent 协作
web_search = true           # 允许搜索
fast_mode = true            # 快速模式（降低质量换速度）
prevent_idle_sleep = true   # 防止系统休眠

项目级配置

团队协作时，可以在项目根目录放一个 .codex/config.toml，覆盖用户级配置。典型用途：

# .codex/config.toml（项目级）
model = "openai/gpt-5.1-codex-max"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

[features]
multi_agent = true

提交到 Git，团队成员拉下来就能用统一配置。

注意：项目级配置文件只有在你信任该项目后才会被加载。首次打开项目时 Codex CLI 会提示确认。

完整配置模板

把上面的内容整合到一起，这是一个生产可用的 config.toml：

# ~/.codex/config.toml

# ──── 模型设置 ────
model = "openai/gpt-5.4-mini-codex"
model_provider = "ofoxai"
model_context_window = 200000
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

# ──── 安全设置 ────
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# ──── 功能开关 ────
[features]
multi_agent = true
web_search = true
fast_mode = false
prevent_idle_sleep = true

# ──── API Provider ────

[model_providers.ofoxai]
name = "OfoxAI Gateway"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOXAI_API_KEY"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

[model_providers.openai]
name = "OpenAI Direct"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"

常见问题排查

Provider 配置了但 Codex 还是走 OpenAI 官方

检查这几项：

  1. model_provider 是否写对了 Provider ID（区分大小写）
  2. 对应的环境变量是否已设置并 source 生效
  3. 有没有项目级配置覆盖了用户级设置

用 codex --version 确认版本 ≥ 0.118.0，老版本不支持 model_providers 语法。

切换 Provider 后报 401

大概率是 env_key 指向的环境变量里装的是另一个 Provider 的 Key。401 之外的报错（429、Sandbox、网络超时等）按报错原文对照 Codex CLI 常见错误排查手册 里的小节查。每个 Provider 用不同的环境变量名：

# OfoxAI 用 OFOXAI_API_KEY
[model_providers.ofoxai]
env_key = "OFOXAI_API_KEY"

# OpenAI 用 OPENAI_API_KEY
[model_providers.openai]
env_key = "OPENAI_API_KEY"

model_reasoning_effort 不生效

只有支持推理控制的模型才响应这个参数。GPT-5.4-mini-codex 和 Codex-Max 都支持。如果用的是其他模型，这个参数会被静默忽略。

本地模型连不上

确认 Ollama 或 LM Studio 已启动，端口正确。本地服务通常不需要 API Key，但 env_key 字段不能省，设个空变量就行：

export OLLAMA_API_KEY=dummy

小结

环境变量够用就别折腾 config.toml。但如果你有多 Provider 切换、项目差异化配置、推理强度调优这些需求，config.toml 就是必经之路。核心就三步：定义 Provider → 指定默认 → 按需切换。

如果你在纠结 Codex CLI 和 Claude Code、Cursor 3、DeepSeek TUI 之间怎么选，AI 编程代理 2026 横评 把这四款工具的价格、上下文窗口、并行能力放到同一张表上做了对比，可以一次看清差异。

相关文章

Codex CLI 怎么用？零基础 5 分钟从 npm 安装到跑通第一条命令（OfoxAI 接入，2026）

Codex CLI 省 Token 真功夫：把那条火爆的"三招"扒到底（2026）

Codex Chrome 扩展 + Codex App 国内教程：5/7 新功能怎么用、用不了又该怎么办（2026）

← 返回文章列表