用 Codex 统一团队配置并验证设置优先级

2026年10月4日

大约 40 分钟内，你可以为项目建立一份团队共用的 Codex 配置，测试设置的优先级，并记录同事如何复现结果。你需要 Codex CLI、一个测试仓库，以及修改该仓库文件的权限。最终应得到一份简短的配置文件、来自两台设备或两个账号的测试记录，以及处理个人设置覆盖团队默认值的方法。

多人使用 Codex 时，可能各自选择不同的模型和搜索模式。OpenAI 的 Config basics说明，Codex 会从多个位置读取配置。只有信任项目时，项目配置才会生效；管理员策略还可能限制用户可选择的值。本文聚焦于可复现的配置。文件访问、网络和命令审批的测试方法，请参阅我们的 Codex 权限检查指南。

准备工作

打开 Codex CLI 并登录。选择一个包含简单任务的测试仓库，例如修改按钮文案。记录 Codex 版本、操作系统、工作目录、workspace 和测试日期，以便比较两台设备。

修改之前，先区分以下四个位置：

~/.codex/config.toml 保存个人默认设置。如果设置了 CODEX_HOME，根目录会改为指定位置，而且该目录必须已经存在。
仓库中的 .codex/config.toml 保存项目设置。从项目根目录到当前工作目录可能有多个配置层。距离当前目录最近的一层优先。
$CODEX_HOME/[name].config.toml 是 profile 文件，用 --profile [name] 选择。
CLI 参数，包括 -c 或 --config，作用于当前运行，在配置值的优先级中最高。

增加新键之前，先查阅 Configuration Reference。项目配置不能覆盖 model_provider、model_providers、notify、profile、profiles 和 otel 等键。用自然语言描述的工作规则应放在 AGENTS.md，运行时设置则放在 config.toml。

分步操作

1. 只选择必要的团队共用值

请经常使用 Codex 的同事和安全负责人一起判断：哪些设置必须在不同设备上保持一致？只把这些共用值放进仓库。如果可用模型取决于个人订阅或账号权限，就不要为了让文件看起来一致而强行指定 model。

在测试仓库中创建 .codex/config.toml，先用一个最小示例：

web_search = "cached"
model_reasoning_effort = "medium"

这只是测试示例，并非适用于所有公司的标准。Config basics说明，cached 使用搜索索引。推理强度设置只有在所选模型支持时才有作用。保持文件简短，让审阅者能理解每一处修改。

如果要统一模型，请先确认相关账号都能使用该模型。Sample Configuration是参考材料，不应原样复制到仓库。

2. 为团队制作优先级表

建立三列表格：配置键、设置位置、预期值。OpenAI 公布的优先级从高到低依次是：CLI 参数、受信任项目从根目录到当前目录的配置、选中的 profile、用户配置、云端托管的 config.toml 默认值、系统配置、内置默认值。在项目内部，距离工作目录更近的配置层优先。

例如，仓库设为 web_search = "cached"，同事启动时却传入 -c web_search=live。由于 CLI 参数优先于仓库配置，这个会话使用 live。如果 profile 写了 disabled，而受信任仓库写了 cached，仓库配置优先。这是根据文档优先级得出的判断，仍应在测试会话中确认。

管理员强制执行的 requirements.toml 是约束条件，并非可以用 -c 覆盖的另一层默认值。策略可能禁止用户选择某些值。如果公司使用 MDM、Agent Security 或 Work Cloud，请管理员确认实际运行环境适用哪套策略。

3. 测试受信任和未受信任的项目

请两位同事在同一个测试仓库中分别启动新会话。如果界面的 /status 显示相关配置，就记录其显示值；否则记录可观察的测试结果。截图中不要包含 API 密钥、token 或登录文件。可以复制以下请求：

请告诉我你当前在哪个目录工作，并概述界面显示的会话设置。暂时不要修改文件。

请简要解释这个测试任务是否需要网页搜索，以及原因。不要修改文件，也不要运行安装命令。

如果项目被标记为 untrusted，Codex 会跳过项目的 .codex/ 配置层，包括配置、hooks 和 rules。用户配置及系统配置仍会加载。因此，在认定仓库文件写错之前，先检查信任状态。只在查看过来源后信任仓库。

4. 测试一次覆盖，然后恢复默认值

团队负责人应通过可逆的测试验证优先级表。在测试仓库中，用另一个值覆盖一个键，比较它与普通会话的结果：

codex -c web_search=disabled

记录命令、工作目录、预期值和观察结果。关闭测试会话，再不带 -c 启动新会话。如果只观察到行为变化，应明确记录这一点；它并不能证明所有配置层的加载路径。

当一个人需要两种工作方式时，例如快速检查和需要更多推理的任务，profile 很有用。把 profile 文件放在用户配置旁边，不要假定它定义在仓库里。通过 CLI 参数选择：

codex --profile [profile-name]

将 [profile-name] 替换为真实名称，并在代表性设备上测试。在受信任仓库中，项目配置仍优先于 profile。profile 只需保存与团队默认值不同的设置。

5. 区分环境变量和持久配置

OpenAI 的 Environment variables 文档指出，config.toml 用于持久设置。环境变量适用于当前 shell、自动化密钥和诊断。CODEX_HOME 会改变配置、身份验证、日志和会话的存储位置。如果同事设置了该变量，在修改 ~/.codex/config.toml 之前先确认实际路径。

不要把 CODEX_API_KEY 或 CODEX_ACCESS_TOKEN 放进仓库。OpenAI 将它们用于非交互进程或可信的自动化。请使用 CI 系统的密钥存储，并避免在日志中打印真实值。RUST_LOG 只控制诊断信息的过滤。

[shell_environment_policy] 限制传给子进程的环境变量。Config basics说明，ignore_default_excludes = false 会启用默认过滤，针对名称中包含 KEY、SECRET 或 TOKEN 的变量。请使用模拟变量测试，不要用真实密钥。这控制的是子进程的环境，与 Codex 读取哪个配置文件是两个不同问题。

6. 把配置修改纳入团队审查

每个修改 .codex/config.toml 的 pull request 都应说明原因、列出修改的键，并附上修改前后的测试结果。请一位同事从其他目录测试，看看是否有更近的配置层生效。团队使用 -c 或 profile 时，也应测试相应路径。任务说明写在 AGENTS.md；共享 skill 另有分发流程。

示例结果

一个三人团队在仓库中加入 web_search 和 model_reasoning_effort。两人记录了相同的预期值。第三人运行 -c web_search=disabled，观察到测试会话的不同，然后启动新会话恢复默认配置。记录还标明谁使用单独的 CODEX_HOME，以及 Work Cloud 策略仍需管理员确认。好的结果是能够解释某个值为何生效。