Codex config.toml 配置指南

发布于 2026年7月17日更新于 2026年7月17日作者：Codex 中文指南

Codex 的主要配置文件使用 TOML 格式。个人机器的全局配置通常位于 ~/.codex/config.toml；受信任项目也可以使用 .codex/config.toml 添加项目级覆盖。两者用途不同，不应把账号和提供商设置混进仓库。

用户级与项目级配置

用户级配置适合保存只属于当前机器的选项，例如模型提供商、API 地址、通知和个人默认行为：

~/.codex/config.toml

项目级配置位于仓库中：

your-project/.codex/config.toml

Codex 只会在项目受信任时加载项目配置。根据官方配置参考，model_provider、model_providers 和 openai_base_url 等机器级提供商设置不能由项目配置覆盖，这能降低仓库悄悄把请求转发到其他服务的风险。

基础配置示例

下面示例只展示结构，不建议照搬所有选项：

model = "<model-id>"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "pragmatic"

• model 选择当前提供商支持的模型 ID。
• approval_policy 控制何时请求人工批准。
• sandbox_mode 控制文件系统和命令执行边界。
• web_search 控制搜索模式，是否可联网还受沙箱和环境策略影响。
• personality 调整支持该能力的模型的沟通风格。

不要因为某个示例使用了一个模型名，就假设你的账号或第三方提供商一定支持它。模型目录、权限和兼容性需要在实际服务中确认。

自定义模型提供商

自定义提供商必须写在用户级 ~/.codex/config.toml。一个典型结构是：

model = "<model-id>"
model_provider = "my_provider"

[model_providers.my_provider]
name = "My OpenAI-compatible provider"
base_url = "https://api.example.com/v1"
env_key = "MY_PROVIDER_API_KEY"
wire_api = "responses"

env_key 填的是环境变量名称，不是密钥本身。Codex 会从该环境变量读取令牌。wire_api = "responses" 表示上游需要兼容 Codex 使用的 Responses API 请求与流式事件；仅仅能处理普通聊天补全并不代表完整兼容。

APIBest 的完整示例和模型选择建议见 配置 APIBest API。

权限配置不要追求“一次不问”

开发时最方便的设置并不一定最安全。workspace-write 通常足以修改当前项目，同时避免默认写入项目外部。涉及网络、系统目录或高风险命令时，让 Codex 请求批准可以保留必要的检查点。

项目团队更适合把稳定的开发规则写进 AGENTS.md，而不是要求每位成员复制相同的个人权限设置。权限仍然应该由每台机器和执行环境决定。

使用配置档案

如果你需要在官方服务、APIBest 或不同安全策略之间切换，可以使用配置档案，而不是频繁手改主配置。配置档案文件与主配置放在同一目录，并通过 --profile 选择。具体文件命名和优先级应核对当前版本的官方文档。

这种方式特别适合区分：

• 日常交互开发与只读代码审查。
• 官方 OpenAI 提供商与第三方兼容提供商。
• 个人项目与公司受管环境。

保持配置可维护

每次只加入确实需要的字段，并用 codex --version 记录出现问题时的客户端版本。升级后如果配置报错，先对照 Codex 配置参考；不要盲目复制几年以前的博客字段。

对于 TOML 语法错误，可以先检查引号、表名和数组格式。提供商连接错误则应分开排查环境变量、base URL、模型 ID、协议兼容和网络连通性，详见 自定义 API 排错指南。