Codex CLI 进阶配置：自定义 API、多模型切换与 config.toml 完全指南（2026）

为什么需要 config.toml

如果你已经用环境变量跑通了 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 需要三个字段：

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"

多 Provider 切换

实际开发中最实用的配置是同时注册多个 Provider：

model_provider = "ofoxai"   # 默认用 OfoxAI

[model_providers.ofoxai]
name = "OfoxAI"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOXAI_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 "写一个快排"

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

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

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

进阶参数详解

推理强度 (model_reasoning_effort)

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

# 日常用 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.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。每个 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 → 指定默认 → 按需切换。