Codex CLI 配置文件 config.toml 完整指南

配置参考 更新于 2026-05-28 约 10 分钟

Codex 的所有核心行为——用哪个模型、走哪个 provider、怎么接第三方 API——都通过一个 TOML 文件控制。本篇把每个关键字段讲清楚，附可直接复制的完整示例。

i

截至 2026：Chat Completions 协议已于 2026 年 2 月移除。所有 provider 必须使用 wire_api = "responses"（Responses API）。详见 wire_api 章节。

配置文件在哪

Codex 启动时会自动加载以下路径的配置文件：

系统路径
macOS / Linux~/.codex/config.toml
Windows%USERPROFILE%\.codex\config.toml

几点补充：

  • CLI 与 IDE 插件（如 VS Code Codex 扩展）共享同一套配置层，改一处全局生效。
  • 文件在每次 Codex 启动时加载一次；改完后需要退出并重新运行 codex。
  • 认证信息（OAuth token 或 API Key）单独存储在 ~/.codex/auth.json，与 config.toml 互不干扰。
✓

文件不存在时 Codex 会使用内置默认值正常启动，无需手动创建。有需要才编辑。

最常改的几个键

日常使用中，绝大多数人只需要关注以下三个顶级键：

键名类型说明
model 字符串 要使用的模型 ID，例如 "gpt-5.3-codex"。必须是所选 provider 支持的模型名。
model_provider 字符串 指定使用哪个 provider 定义。默认值为 "openai"（内置）。填自定义 provider 时需先在 [model_providers.<id>] 中定义。
model_context_window 整数 告知 Codex 当前模型可用的上下文 token 数量。通常无需手动设置，仅在接入上下文窗口与默认不符的模型时使用。
~/.codex/config.toml — 最简配置
# 指定模型
model = "gpt-5.3-codex"

# 使用内置 openai provider（默认值，可省略）
model_provider = "openai"
i

内置 provider "openai" 走的是 Responses API，无需额外配置。内置 provider "oss" 用于本地模型。openai、ollama、lmstudio 这三个 id 是保留名称，不可被自定义 provider 覆盖。

自定义模型提供商 [model_providers]

当你需要对接非内置端点——比如公司内部的模型网关、本地 Ollama 以外的推理服务——就需要在 [model_providers.<自定义id>] 段中定义一个 provider。每个 provider 定义包含以下字段：

字段说明
base_urlAPI 端点的根地址（大多数场景必填）。
env_keyCodex 运行时读取的环境变量名，把该变量的值作为 Bearer token 发送。密钥本身不写在配置文件里。
wire_api通信协议。截至 2026，只允许 "responses"（Responses API）。
~/.codex/config.toml — 自定义 provider 示例
# 顶级：使用哪个模型 + 哪个 provider
model          = "gpt-5.3-codex"
model_provider = "myrelay"

# 自定义 provider 定义
[model_providers.myrelay]
base_url = "https://your-relay.example.com/v1"
env_key  = "MYRELAY_API_KEY"
wire_api = "responses"

使用时，在终端里设置好对应的环境变量，Codex 启动时会自动读取：

终端 — 设置 API Key 环境变量
export MYRELAY_API_KEY="sk-..."
$ codex
!

不要把 API Key 的值直接写进 config.toml。env_key 只填环境变量的名字，真正的密钥通过环境变量传入，避免泄漏到版本控制。

接入第三方 API（示例）

如果你想通过中转服务或兼容 Responses API 的第三方端点来调用 Codex，步骤如下：

  1. 在 config.toml 中定义一个自定义 provider，base_url 指向中转端点，env_key 填存放该服务 API Key 的环境变量名。
  2. 在顶级将 model_provider 设为这个自定义 id。
  3. 启动前在终端里 export 好对应的环境变量。
~/.codex/config.toml — 第三方 API 示例
model          = "gpt-5.3-codex"
model_provider = "myrelay"

[model_providers.myrelay]
base_url = "https://your-relay.example.com/v1"
env_key  = "MYRELAY_API_KEY"
wire_api = "responses"
i

认证方式与具体 provider 相关；上面的示例使用最常见的 Bearer token 方式（由 env_key 驱动）。如果你的端点需要其他认证方式，请参考该服务的文档。

wire_api 与 2026 年的变更

wire_api 决定 Codex 与 provider 之间通信时使用哪套 API 协议。截至 2026 年 2 月，Codex 做了一项重要变更：

!

Chat Completions 支持已移除。此前 Codex 同时支持 wire_api = "chat"（Chat Completions）和 wire_api = "responses"（Responses API）。2026 年 2 月起，"chat" 选项被彻底移除。

现在所有 provider——包括内置的 openai、oss，以及任何自定义的第三方 provider 和本地模型 provider——都必须使用 wire_api = "responses"。

如果你的配置或第三方端点仍然使用旧的 "chat" 协议，升级后会立即报错。解决办法：

  • 将所有 wire_api = "chat" 改为 wire_api = "responses"。
  • 确认第三方端点本身支持 Responses API；不支持的端点暂时无法接入。

一份完整的 config.toml 示例

下面是一份带注释的完整示例，覆盖了日常使用中最常见的场景。按需取用，不需要的部分可以删掉或注释掉。

~/.codex/config.toml — 完整注释示例
# ============================================================
# Codex CLI — config.toml 完整示例（截至 2026）
# 文件位置：~/.codex/config.toml
# Windows：%USERPROFILE%\.codex\config.toml
# ============================================================

# 要使用的模型 ID
model = "gpt-5.3-codex"

# 使用哪个 provider 定义（默认 "openai"，接第三方时改为自定义 id）
model_provider = "openai"

# 可选：手动指定上下文窗口大小（token 数）
# 通常不需要；仅在接入上下文窗口与默认不符的模型时设置
# model_context_window = 128000

# ============================================================
# 自定义 provider 示例：中转 / 第三方 API
# 接入步骤：
#   1. 在下方填写端点 base_url 与存放 key 的环境变量名
#   2. 把顶部 model_provider 改为 "myrelay"
#   3. 启动前 export MYRELAY_API_KEY="sk-..."
# ============================================================

[model_providers.myrelay]
base_url = "https://your-relay.example.com/v1"
env_key  = "MYRELAY_API_KEY"
# wire_api 截至 2026 只支持 "responses"，"chat" 已于 2026-02 移除
wire_api = "responses"

常见问题

改了 model 不生效怎么办？

config.toml 在 Codex 启动时加载一次。改完文件后需要完全退出当前会话（Ctrl+C），再重新运行 codex，新的 model 才会生效。

如果只想临时切换，可以在会话内用 /model 斜杠指令切换，不会写回 config.toml。

第三方 API 报错说 wire_api 不对怎么处理？

从 2026 年 2 月起，wire_api = "chat" 已被移除。检查你的 [model_providers.<id>] 段，把所有 wire_api = "chat" 改成 wire_api = "responses"。

如果第三方端点本身不支持 Responses API，则目前无法直接接入，需要等待服务商更新。

Windows 上配置文件在哪里？

路径是 %USERPROFILE%\.codex\config.toml，通常展开为 C:\Users\你的用户名\.codex\config.toml。在文件资源管理器地址栏直接输入 %USERPROFILE%\.codex 可以快速跳转。

config.toml 改坏了怎么恢复默认？

把 config.toml 重命名（例如改为 config.toml.bak）或直接删除即可。Codex 下次启动时找不到文件会以内置默认值运行，等效于恢复出厂设置。

认证信息单独存储在 auth.json，改配置不会影响登录状态。