Codex CLI 多配置使用指南

01

默认配置文件

默认的用户配置文件位于：

~/.codex/config.toml

直接启动时，Codex 会读取基础配置，并按规则叠加其他配置层：

codex

基础配置适合保存各个使用场景共用的设置。其他配置层只需补充或覆盖有差异的字段。

02

用 Profile 保存常用设置

Profile 是叠加在基础配置上的命名配置文件，适合为开发、代码审查等场景分别保存设置。

文件结构

~/.codex/
├── config.toml
├── work.config.toml
└── review.config.toml

基础配置

文件：~/.codex/config.toml

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

以上仅为示例；已有配置文件时，合并所需字段即可。

开发配置

文件：~/.codex/work.config.toml

model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

审查配置

文件：~/.codex/review.config.toml

model_reasoning_effort = "high"
sandbox_mode = "read-only"

Profile 只需填写与基础配置不同的字段，其他字段继续继承基础配置。开发示例保留了两个常用字段，也可以省略与基础配置相同的值。

示例未指定模型，会沿用已有的模型配置；推理强度需要所选模型支持。

启动命令

# 使用开发配置
codex --profile work

# 使用审查配置
codex --profile review

# 简写
codex -p review

# 非交互运行
codex exec -p review "审查当前代码改动"

--profile review 对应 review.config.toml，参数中不包含文件扩展名。

03

用 CODEX_HOME 切换环境

CODEX_HOME 决定 Codex 的本地配置与状态目录，默认是 ~/.codex。可以为工作和个人使用维护不同目录：

~/.codex-work/
├── config.toml
└── review.config.toml

~/.codex-personal/
└── config.toml

先创建目录，再分别添加配置文件：

mkdir -p "$HOME/.codex-work"
mkdir -p "$HOME/.codex-personal"

启动时选择目录：

CODEX_HOME="$HOME/.codex-work" codex

CODEX_HOME="$HOME/.codex-personal" codex

两条命令分别读取：

~/.codex-work/config.toml
~/.codex-personal/config.toml

与 Profile 组合使用

CODEX_HOME="$HOME/.codex-work" codex -p review

这条命令读取工作环境的基础配置，再叠加 ~/.codex-work/review.config.toml。

对登录状态的影响

切换 CODEX_HOME 也会改变历史记录、日志和缓存等本地状态的存储位置。

使用文件存储凭据时，auth.json 位于该目录；使用系统钥匙串时，登录状态还取决于凭据存储配置。因此，切换目录后可能需要重新登录：

CODEX_HOME="$HOME/.codex-work" codex login

这种内联环境变量写法只影响当前命令，不会永久修改环境变量。Profile 本身不会自动切换账号。

04

用命令行临时覆盖

使用 -c 或 --config 覆盖本次运行的设置：

codex -c 'model_reasoning_effort="high"'

可以重复使用 -c：

codex \
    -c 'model_reasoning_effort="high"' \
    -c 'sandbox_mode="read-only"'

也可以在 Profile 上继续覆盖：

codex -p review -c 'model_reasoning_effort="medium"'

即使 review.config.toml 中设置为 high，这次运行也会使用命令行指定的 medium。

这些设置不会自动写回配置文件。值按 TOML 解析，嵌套字段可以使用点号。

05

配置覆盖顺序

常用配置层的优先级从低到高如下。同一个字段出现在多层时，后面的设置覆盖前面的设置。

用户 config.toml
    ↓
Profile 文件
    ↓
项目 .codex/config.toml
    ↓
命令行参数与 -c 覆盖

例如，同一个字段分别设置为：

最终使用命令行指定的 medium。如果没有命令行覆盖，则会使用项目配置中的 low。

项目配置只在项目受信任时加载；同一项目中，越靠近当前工作目录的配置优先级越高。部分提供方、凭据及 Profile 相关字段不能由项目配置覆盖。

以上省略了更低优先级的内置、系统和云管理默认值。组织强制策略还会约束可用设置，配置优先级不能绕过这些要求。

06

如何选择与检查

• 需要保存开发、审查等常用设置：使用 Profile。
• 需要不同的本地配置和状态目录：使用 CODEX_HOME。
• 只想临时改动一两个字段：使用 -c。

三种方式可以组合使用。排查设置没有生效时，先确认当前 CODEX_HOME 和 Profile 名称，再检查项目配置与命令行是否覆盖了同一字段。

查看本机版本与支持的参数：

codex --version
codex --help

官方参考

• 高级配置：Profile、命令行覆盖与 CODEX_HOME
• 配置基础与优先级
• CLI 参数说明