AI Agent / 系统课时

管理环境变量与配置层级

管理环境变量与配置层级

Codex 的配置并不是只读一个文件:用户默认值、项目覆盖、Profile 与命令行可能同时生效。本篇把这些层级和环境变量拆开说明,并用一个可验证的命令演示“同一个键发生冲突时,最终到底采用谁的值”。

学习目标

  • 说清 Codex 配置的覆盖顺序,并判断同名配置最终值
  • 正确区分用户级、项目级、Profile、命令行与环境变量的职责
  • 用项目配置和一次性命令行覆盖完成安全、可验证的配置管理

配置到底从哪里生效

Codex 会把多个配置层合并,而不是简单选择某一个文件。对同一个配置键,优先级从高到低依次是:CLI flags 与 --config 覆盖、项目 .codex/config.toml、通过 --profile 选择的 Profile、用户 ~/.codex/config.toml、系统配置、内置默认值。

项目配置还存在两条重要规则。第一,Codex 只在项目被信任时加载项目级 .codex/ 配置;第二,从项目根目录到当前工作目录可以存在多层 .codex/config.toml,离当前目录越近的项目配置优先级越高。

Codex 配置层级与环境变量职责

环境变量要单独理解。Codex 用 config.toml 保存持久设置;环境变量主要承担 Shell 作用域的路径、认证、安装和诊断信息。例如 CODEX_HOME 会改变 Codex 状态与配置根目录,CODEX_API_KEY 可向非交互 codex exec 提供 API Key。它们并不是“所有配置键都能用同名环境变量覆盖”的通用层。

用户级与项目级配置

适合所有仓库的默认值放在 ~/.codex/config.toml。例如把日常默认模型和推理强度固定下来:

toml
model = "gpt-5.6"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

这段配置会成为本机用户默认值。验证时可启动 Codex,并用 /status 查看当前会话状态;如果项目或命令行没有覆盖这些键,应看到对应模型与运行设置生效。

项目特有的设置放在仓库内 .codex/config.toml。例如某个仓库希望默认降低推理强度:

toml
model_reasoning_effort = "low"

当 Codex 在这个可信项目中运行时,项目值会覆盖用户级的 medium。不要把 API Key、访问令牌等秘密写进项目配置;项目配置适合可共享的行为设置,认证秘密应通过受控登录或环境变量注入。

命令行覆盖与环境变量

命令行适合一次性实验,因为它只影响当前启动。下面的主示例同时演示环境变量认证、模型参数和 -c 配置覆盖;运行前把 <API_KEY> 替换为有效密钥。

bash
CODEX_API_KEY="<API_KEY>" codex exec \
  -m gpt-5.6-terra \
  -c 'model_reasoning_effort="high"' \
  "只回复 CONFIG_OK"

预期输出

text
CONFIG_OK

这里即使用户配置写了 model = "gpt-5.6",项目配置写了 model_reasoning_effort = "low",本次调用仍会使用命令行指定的模型,并把推理强度覆盖为 high。实际启动信息可能随 Codex 版本不同,但最终回答应为 CONFIG_OK。

-c 或 --config 的值按 TOML 解析,因此字符串通常需要保留引号;-m 或 --model 是模型选择的专用快捷参数。需要切换一整组个人配置时,则更适合用 --profile <NAME>,而不是堆很多 -c。

排查覆盖关系的顺序

遇到“我明明改了配置却没生效”,不要先反复编辑文件,而应从最高优先级向下检查:当前命令是否带 -m、-c 等覆盖;当前目录是否命中了更近的 .codex/config.toml;是否选择了 Profile;最后才检查用户级与系统级配置。

还要注意,项目级配置不能覆盖某些机器本地或安全敏感的设置,例如模型提供方、认证相关来源、Profile 选择和部分遥测配置。需要严格检查未知配置键时,可在运行命令上增加 --strict-config,让当前 Codex 版本对无法识别的字段直接报错,而不是带着错误假设继续排查。

把长期默认值放用户级,把仓库差异放项目级,把成组个人偏好放 Profile,把一次性实验留给 CLI;环境变量则负责路径、秘密和诊断。这样每一层的职责清楚,配置冲突也能按固定顺序定位。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理环境变量与配置层级

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通