Codex 模型配置与切换实战指南：从 ChatGPT 内置模型到自定义提供商

Codex CLI 的强大之处不仅在于它能在终端里帮你写代码，更在于它允许你灵活选择和切换后端模型。无论你是使用 ChatGPT Plus/Pro 订阅附带的内置模型，还是想接自己的 API Key 使用最新模型，甚至连接到第三方模型提供商（如 AWS Bedrock、本地 Ollama 等），Codex 都提供了完整的配置体系来满足你的需求。

本文将深入讲解 Codex 的模型配置体系，从登录认证到模型参数调优，帮你全面掌控 AI 编程助手的"大脑"。

一、Codex 支持的两大认证方式

在配置模型之前，首先要搞定认证。Codex 支持两种登录方式：

1.1 使用 ChatGPT 账号登录（推荐）

运行 codex 后选择 Sign in with ChatGPT 即可使用 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 计划中附带的模型额度。这是最简单的方式，模型选择会由你的订阅计划决定，开箱即用。

codex
# 在 TUI 中选择 "Sign in with ChatGPT"
# 浏览器会自动打开，完成登录后回到终端即可

1.2 使用 API Key 登录

如果你拥有 OpenAI API Key，也可以用 API 方式登录。这种方式可以让你使用 API 侧开放的模型，但需要额外的配置步骤。

codex login --api-key
# 输入你的 OpenAI API Key 即可完成认证

你还可以通过环境变量设置 API Key：

export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

需要注意的是，API 方式登录虽然灵活性更高，但你的请求将直接走 API 计费，不会消耗 ChatGPT 订阅的模型额度。

二、配置文件基础：config.toml

Codex 的核心配置存储在 ~/.codex/config.toml 文件中。关于模型的所有设置都集中在这里的 [profile] 和 [model_providers] 两个区域。

首次使用时，Codex 会自动生成一个默认的配置文件。你也可以手动创建：

mkdir -p ~/.codex
codex config init

2.1 通过命令行临时覆盖配置

除了配置文件，Codex 还支持通过 -c 参数动态设置任意配置项，非常适合临时测试不同的模型：

codex -c model=gpt-5
codex -c model_reasoning_effort=high
codex -c model=o4-mini -c model_reasoning_effort=medium

-c 参数的优先级高于配置文件，而且支持多次使用——每项设置一个 -c key=value 即可。

三、模型选择：指定你想用的"大脑"

3.1 基础模型切换

在 ~/.codex/config.toml 中，model 字段控制 Codex 默认使用哪个模型：

[profile]
model = "gpt-5"

Codex 支持 OpenAI 生态下的多种模型，常见的包括：

| 模型名称 | 适用场景 |
|---------|---------|
| gpt-5 | 全能型，适合复杂编程任务 |
| gpt-5-mini | 轻量快速，适合简单任务 |
| o4-mini | 推理增强，逻辑密集型任务 |
| codex-oss | 面向开源代码的场景 |

你可以在 Codex 运行时通过 /model 命令实时查看和切换可用模型。配置文件中设置的只是默认值。

3.2 设置模型推理强度

Codex 允许你控制模型的推理深度，通过 model_reasoning_effort 字段：

[profile]
model_reasoning_effort = "high"

可选值：

• "low" —— 快速响应，适合简单问题
• "medium" —— 平衡速度与深度（默认）
• "high" —— 深度推理，适合复杂架构决策

这个设置直接影响模型在给出答案前的"思考"时间。对于日常的代码补全和小修复，low 或 medium 足够了；对于架构设计、大型重构，建议用 high。

3.3 模型输出详细程度

model_verbosity 控制模型回答的啰嗦程度：

[profile]
model_verbosity = "high"

可选值包括 "low"、"medium"、"high"。"high" 会让模型输出更多解释和上下文，适合学习场景；"low" 则更简洁，适合你只想快速拿到代码的场景。

3.4 推理摘要

当你使用了推理后，model_reasoning_summary 控制推理过程的摘要方式：

[profile]
model_reasoning_summary = "detailed"

可选值为 "auto" 和 "detailed"。如果你关心模型的推理过程（例如调试时），设为 "detailed" 可以看到更完整的思考链。

3.5 服务层级

service_tier 用于控制请求的优先级：

[profile]
service_tier = "priority"

可选值："default"、"priority"、"flex"。如果你在使用 API Key 方式登录，"priority" 层级可以获得更低的延迟，但费用更高。ChatGPT 订阅用户的层级由计划决定。

四、自定义模型提供商：连接第三方模型

除了 OpenAI 官方模型，Codex 还支持连接自定义模型提供商——无论是 AWS Bedrock、Azure OpenAI，还是你自己部署的兼容 OpenAI API 的服务。

4.1 注册自定义提供商

在 ~/.codex/config.toml 中添加 [model_providers] 小节：

[model_providers.my_provider]
base_url = "https://api.example.com/v1"

[model_providers.my_provider.auth.command]
command = "aws"
args = ["--profile", "my-profile", "codex-get-credentials"]
refresh_interval_ms = 300000
timeout_ms = 5000

配置说明：

• base_url：提供商 API 的基础 URL，需兼容 OpenAI API 格式
• auth.command：用于获取 Bearer Token 的命令，命令的 stdout 输出会被用作 Authentication Header
• refresh_interval_ms：Token 刷新间隔（默认 5 分钟）
• timeout_ms：获取 Token 的超时时间

4.2 切换到自定义提供商

注册完成后，通过 model_provider 和 model 字段选择提供商和具体模型：

[profile]
model_provider = "my_provider"
model = "my-custom-model"

你也可以通过 -c 参数快速切换：

codex -c model_provider=my_provider -c model=claude-sonnet-4

4.3 开源模型提供商

Codex 原生支持通过 Ollama 等工具运行本地开源模型。配置 oss_provider：

[profile]
oss_provider = "ollama"
model = "llama3.1:70b"

这需要你提前在本地启动 Ollama 并拉取对应模型。Codex 会通过 Ollama 的本地 API 与模型通信。

4.4 AWS Bedrock 集成

如果你在 AWS 环境中工作，可以直接配置 AWS SigV4 认证：

[model_providers.bedrock]
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"

[model_providers.bedrock.auth.aws]
profile = "my-aws-profile"
region = "us-east-1"

Codex 会自动使用 AWS SDK 的标准凭证链，包括 IAM 角色、环境变量、配置文件等。

五、多配置文件（Profiles）与高级切换

Codex 支持定义多个 Profile，让你在不同场景间快速切换——比如日常工作用一个轻量模型，大型重构时切到最强模型。

5.1 定义多 Profile

在 config.toml 中，你可以覆盖 [profile] 的默认值：

[profile]
model = "gpt-5-mini"
model_reasoning_effort = "low"

# 定义一个"深度工作"Profile
[profile.deep_work]
model = "gpt-5"
model_reasoning_effort = "high"
model_verbosity = "high"
service_tier = "priority"

# 定义一个"轻量快速"Profile
[profile.quick]
model = "gpt-5-mini"
model_reasoning_effort = "low"
model_verbosity = "low"

5.2 在运行时切换 Profile

通过 -c 指定 Profile 名称——Codex 会加载该 Profile 中定义的所有设置：

# 使用深度工作模式
codex -c profile=deep_work

# 使用快速轻量模式
codex -c profile=quick

你还可以基于 Profile 做局部覆盖：

codex -c profile=quick -c model_reasoning_effort=medium

这种方式让你既有预设的便利，又有临时微调的灵活性。

六、实战场景与最佳实践

场景 1：日常开发，速度优先

[profile]
model = "gpt-5-mini"
model_reasoning_effort = "low"
model_verbosity = "low"

适合代码补全、简单 bug 修复、格式化等高频小任务。响应快，消耗少。

场景 2：复杂重构，质量优先

[profile.refactor]
model = "gpt-5"
model_reasoning_effort = "high"
model_verbosity = "high"
model_reasoning_summary = "detailed"

使用 codex -c profile=refactor 启动。模型会进行更深度的思考，输出也会包含更多解释，方便你理解和审查。

场景 3：离线或隐私敏感环境

[profile]
oss_provider = "ollama"
model = "llama3.1:70b"

配合本地运行的 Ollama，所有计算都在本地完成，数据不会离开你的机器。

场景 4：混合使用

你可以用 ChatGPT Plan 登录享受免费额度，但在特定项目上用 API Key 连接自己的模型提供商：

# 全局默认：ChatGPT 登录使用的模型
codex

# 特定项目：使用 API Key + 自定义模型
cd my-enterprise-project
codex -c model_provider=my_provider -c model=gpt-5

也可以在项目根目录创建 config.toml，让 Codex 自动读取项目级配置（项目级优先于用户级）。

七、总结

Codex 的模型配置体系可以用一句话概括：灵活且层次分明。

• 认证层：ChatGPT 订阅或 API Key，决定了你能用什么模型
• 提供商层：原生 OpenAI、自定义 API、AWS Bedrock、本地 Ollama
• 模型层：选择具体的模型名称
• 调优层：推理强度、输出详细度、推理摘要、服务层级
• Profile 层：组合以上所有设置，一键切换场景

掌握这套配置体系后，你可以在"快速完成一个 CRUD"和"深度重构核心模块"之间无缝切换，充分榨干 Codex 的潜力。

如果你还没试过多模型切换，不妨现在打开 ~/.codex/config.toml，根据你的场景做一个定制化的 Profile——让 AI 编程助手真正适配你的工作节奏，而不是反过来。