如何设置 Codex config.toml：自定义 API、代理和常见错误

Codex 将设置保存在一个文件 config.toml 中：使用哪个模型、调用哪个 API，以及代理无需询问即可执行多少操作。该格式在 2026 年多次变更，年初的许多指南所列的设置如今会导致 Codex 无法启动。

本指南先提供一份可用配置，然后介绍大多数人会修改的部分：配置档案、项目设置、沙盒和代理。最后列出你可能遇到的错误及其含义。内容已对照 OpenAI 文档核验，并于 2026 年 10 月 19 日在 Codex CLI 0.162.1 上运行测试。示例使用 AIHubMix 作为服务提供商；任何支持 OpenAI Responses API 的网关都可以采用相同方法。

简要说明

配置文件位于 ~/.codex/config.toml；Windows 上则是 C:\Users\<you>\.codex\config.toml。
自定义服务提供商需要设置 base_url、wire_api = "responses" 和 env_key。API 密钥应放在环境变量中。
配置档案现在是单独的文件 ~/.codex/<name>.config.toml，通过 --profile <name> 选择。
仓库中的 .codex/config.toml 仅在受信任的项目中生效，而且不能更改服务提供商。
每次编辑后都要重启 Codex；它只会在启动时读取该文件。

config.toml 文件的位置

主要设置保存在 ~/.codex/config.toml 中。CLI 和 IDE 扩展都会读取该文件。如果文件尚不存在，请创建一个。

另外还有两个位置可以叠加设置：

配置档案文件 ~/.codex/<name>.config.toml，仅当使用 --profile <name> 启动 Codex 时才会使用。
项目文件 .codex/config.toml，位于仓库中，用于共享团队希望共用的设置。

如果你在 Windows 上的 WSL2 中运行 Codex，它会读取 Linux 主目录中的文件（/home/<you>/.codex/config.toml），而不是 Windows 中的文件。如果设置了 CODEX_HOME，Codex 会使用该文件夹，而不是 ~/.codex。

最简可用配置

这份完整的 ~/.codex/config.toml 会将 Codex 的请求发送到 AIHubMix：

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

model 是要调用的模型 ID，model_reasoning_effort 是默认推理级别。
model_provider 必须与 [model_providers.<name>] 中的名称一致。不要使用 openai、ollama 或 lmstudio；这些名称已被 Codex 内置服务提供商占用。
base_url 是服务提供商的 API 地址。现在 Codex 只接受 wire_api = "responses" 这一值。
env_key 是环境变量的名称，不是密钥本身。

接着，使用AIHubMix 控制台中的密钥设置该变量：

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

在新的终端中运行 codex，然后随便问它一个问题。如果它能回答，说明服务提供商可以正常工作。是否已登录 Codex 与此无关：codex login 使用的密钥不会发送给自定义服务提供商。

配置档案：每种配置一个文件

配置档案只保存与主配置不同的设置，例如更深入的推理，以及用于代码审查的只读沙盒。每个配置档案都是与 config.toml 同级的独立文件，键直接写在顶层：

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

这一点在 Codex 0.134.0 中发生了变化。较早的指南会在 config.toml 中用 [profiles.review] 表格定义配置档案，并通过 profile = "review" 选择。现在 Codex 遇到这个选择器会拒绝启动。单独遗留的 [profiles.review] 表格会被静默忽略，因此其中的设置会悄然失效。要迁移，请将每个表格中的键移至 ~/.codex/<name>.config.toml，然后删除该表格和 profile = ... 这一行。更多详情请参阅 OpenAI 的高级配置指南。

项目配置：.codex/config.toml

仓库中的 .codex/config.toml 可让团队共享默认模型、推理级别或沙盒模式。Codex 只会在你自己的 ~/.codex/config.toml 中标记为受信任的项目里读取它：

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

项目文件不能更改请求的发送位置。Codex 会忽略其中的 model_provider、model_providers、openai_base_url、profile、notify 以及其他少数几个键，并在忽略时打印警告。请将服务提供商配置保留在 ~/.codex/config.toml 中。项目仍然可以选择模型；请求会发送到你自己的服务提供商。

哪个设置优先生效

如果同一个键在多个位置都有设置，OpenAI 的配置基础知识列出了以下优先级，顺序从高到低：

命令行标志，包括 -c 覆盖项
项目的 .codex/config.toml
通过 --profile 选择的配置档案
你的 ~/.codex/config.toml
系统配置 /etc/codex/config.toml
Codex 内置默认值

请注意，项目文件的优先级高于配置档案。如果配置档案中的某项设置似乎没有生效，请检查仓库的 .codex/config.toml 是否设置了相同的键。

若只想在单次运行中更改某项设置，请使用 -c：

codex -c model_reasoning_effort=high

沙盒与审批

两个键控制 Codex 自主执行操作的方式。sandbox_mode 用于设置命令可以访问哪些内容，approval_policy 用于设置 Codex 何时会停下来征求你的同意。

sandbox_mode	命令可以执行哪些操作
read-only	读取文件；其他操作都需要审批
workspace-write	可在项目文件夹和临时文件夹中写入
danger-full-access	不受沙盒限制，可执行任何操作

approval_policy	Codex 何时征求同意
on-request	需要超出沙盒限制时
never	从不征求同意；被阻止的命令会直接失败

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

两者彼此独立：never 会停止征求同意，但不会放宽沙盒限制。在 workspace-write 模式下，除非设置 network_access = true，否则命令无法访问网络。

通过代理连接

Codex 没有在 config.toml 中设置代理的选项。它使用标准环境变量：

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

OpenAI 文档没有提到这些变量，因此我们在 Codex 0.162.1 上进行了测试：包括发送到自定义服务提供商的请求在内，所有请求都会通过 HTTPS_PROXY（或 ALL_PROXY）转发，而 NO_PROXY 中列出的主机则会直接连接。不支持 PAC 文件，因此请填写代理地址本身。如果公司的代理使用自己的根证书，请按照环境变量参考中的说明，将 CODEX_CA_CERTIFICATE 指向该证书。

在 /model 中添加更多模型

/model 选择器只列出 OpenAI 的模型。若要从中选择 GLM、Claude、Gemini 或 DeepSeek 模型，请添加模型目录：使用顶层键 model_catalog_json 指定一个 JSON 文件。请将该键放在第一条 [table] 之前，否则 TOML 会将它视为该表格的一部分，Codex 也就会忽略它。

模型目录会取代内置列表，而且每个条目都需要填写大量字段，因此最好通过脚本生成，而不是手动编写。AIHubMix Codex CLI 指南提供了一个脚本，可根据 AIHubMix 上排名前 30 的模型生成目录。桌面应用可能仍会在选择器中隐藏自定义模型（openai/codex#19694），因此请在终端中切换模型。

常见错误及其含义

以下是 Codex 0.162.1 在出现相应错误时打印的消息。

legacy profile = "..." config is no longer supported
你的 config.toml 中仍有旧版 profile = "..." 行。请按照上文所述，将配置档案移至单独的文件中。如果仍存在旧版 [profiles.x] 表格时运行 --profile x，也会出现类似错误：--profile x cannot be used while ... contains legacy ... config。

wire_api = "chat" is no longer supported
Codex 不再支持 Chat Completions API。请将其改为 wire_api = "responses"。如果某个服务提供商只支持 Chat Completions API，则必须使用转换代理才能正常工作。

model_providers contains reserved built-in provider IDs
你将服务提供商命名为 openai、ollama 或 lmstudio 了。请将表格名称和 model_provider 改为其他名称。

approval_policy = "untrusted" is no longer supported
请删除该行，或改用 on-request。

Missing environment variable: AIHUBMIX_API_KEY
env_key 中指定的变量未在启动 Codex 的终端中设置。请打开一个新终端，或运行 source ~/.zshrc，然后重新启动 Codex。

出现几行“Reconnecting...”后报 401 Unauthorized
请求发送时未携带密钥。请检查服务提供商表格中是否设置了 env_key。保存在 auth.json 中的登录信息不适用于自定义服务提供商。

Model metadata for ... not found. Defaulting to fallback metadata
Codex 没有该模型的内置设置；对于非 OpenAI 模型，这属于正常情况。请求仍可正常运行。如果想使用适当的设置，并在 /model 中看到该模型，请添加模型目录。

Ignored unsupported project-local config keys
仓库的 .codex/config.toml 设置了一个仅在你自己的配置中生效的键，通常是 model_provider。请将其移至 ~/.codex/config.toml。

missing field base_instructions
模型目录中的某个条目缺少必需字段，因此 Codex 会拒绝整个文件。请使用脚本重新生成目录，而不是手动编辑。

设置未生效时的排查方法

编辑后重启 Codex。
确保顶层键位于第一条 [table] 之前。
检查仓库的 .codex/config.toml；它会覆盖你的配置档案。
检查是否遗留了 [profiles.x] 表格。
运行 codex doctor，检查安装、配置和登录状态。

如果你想用一个密钥在 Codex 中调用 OpenAI、Anthropic、Google、智谱、DeepSeek 等模型，AIHubMix 会通过 Responses API 在 https://aihubmix.com/v1 提供这些模型。先使用上面的最简配置；如果想通过 /model 切换模型，再添加模型目录。

常见问题

Codex 的 config.toml 文件在哪里？
macOS 和 Linux 上位于 ~/.codex/config.toml，Windows 上位于 C:\Users<you>.codex\config.toml。如果设置了 CODEX_HOME，则文件位于该文件夹中。

更改 config.toml 后需要重启 Codex 吗？
需要。Codex 会在启动时读取该文件，因此请退出并重新打开终端会话或应用。

为什么 Codex 提示“已不再支持旧版配置文件中的配置档案”？
Codex 0.134.0 移除了在 config.toml 中定义的配置档案。请将每个配置档案移至 ~/.codex/name.config.toml，删除旧配置行，然后使用 --profile name 启动 Codex。

我还能使用 wire_api = "chat" 吗？
不能。Codex 仅接受 wire_api = "responses"。仅支持 Chat Completions 的提供商需要通过代理转换为 Responses API。

为什么我已登录 Codex，自定义提供商却返回 401？
auth.json 中的登录密钥不会发送给自定义提供商。请在提供商表格中添加 env_key，并在终端中设置该变量。

Codex 会使用 HTTPS_PROXY 吗？
会。在 Codex 0.162.1 的测试中，请求通过 HTTPS_PROXY 发送，并跳过了 NO_PROXY 中列出的主机。不支持 PAC 文件。

为什么项目的 .codex/config.toml 中的 model_provider 会被忽略？
项目文件无法更改请求的发送位置，因此代码仓库无法重定向你的流量。请将提供商配置放在 ~/.codex/config.toml 中；项目文件仍可设置模型。

来源

配置基础，OpenAI
高级配置，OpenAI
配置参考，OpenAI
Codex CLI 集成指南，AIHubMix
Codex CLI 代理配置：SOCKS、HTTP 和企业网络，Daniel Vaughan