AI Agent / 系统课时
管理环境变量与配置层级
管理环境变量与配置层级
Codex 的配置并不是只读一个文件:用户默认值、项目覆盖、Profile 与命令行可能同时生效。本篇把这些层级和环境变量拆开说明,并用一个可验证的命令演示“同一个键发生冲突时,最终到底采用谁的值”。
学习目标
- 说清 Codex 配置的覆盖顺序,并判断同名配置最终值
- 正确区分用户级、项目级、Profile、命令行与环境变量的职责
- 用项目配置和一次性命令行覆盖完成安全、可验证的配置管理
配置到底从哪里生效
Codex 会把多个配置层合并,而不是简单选择某一个文件。对同一个配置键,优先级从高到低依次是:CLI flags 与 --config 覆盖、项目 .codex/config.toml、通过 --profile 选择的 Profile、用户 ~/.codex/config.toml、系统配置、内置默认值。
项目配置还存在两条重要规则。第一,Codex 只在项目被信任时加载项目级 .codex/ 配置;第二,从项目根目录到当前工作目录可以存在多层 .codex/config.toml,离当前目录越近的项目配置优先级越高。

环境变量要单独理解。Codex 用 config.toml 保存持久设置;环境变量主要承担 Shell 作用域的路径、认证、安装和诊断信息。例如 CODEX_HOME 会改变 Codex 状态与配置根目录,CODEX_API_KEY 可向非交互 codex exec 提供 API Key。它们并不是“所有配置键都能用同名环境变量覆盖”的通用层。
用户级与项目级配置
适合所有仓库的默认值放在 ~/.codex/config.toml。例如把日常默认模型和推理强度固定下来:
model = "gpt-5.6"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"这段配置会成为本机用户默认值。验证时可启动 Codex,并用 /status 查看当前会话状态;如果项目或命令行没有覆盖这些键,应看到对应模型与运行设置生效。
项目特有的设置放在仓库内 .codex/config.toml。例如某个仓库希望默认降低推理强度:
model_reasoning_effort = "low"当 Codex 在这个可信项目中运行时,项目值会覆盖用户级的 medium。不要把 API Key、访问令牌等秘密写进项目配置;项目配置适合可共享的行为设置,认证秘密应通过受控登录或环境变量注入。
命令行覆盖与环境变量
命令行适合一次性实验,因为它只影响当前启动。下面的主示例同时演示环境变量认证、模型参数和 -c 配置覆盖;运行前把 <API_KEY> 替换为有效密钥。
CODEX_API_KEY="<API_KEY>" codex exec \
-m gpt-5.6-terra \
-c 'model_reasoning_effort="high"' \
"只回复 CONFIG_OK"预期输出
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;环境变量则负责路径、秘密和诊断。这样每一层的职责清楚,配置冲突也能按固定顺序定位。