config.toml 常用配置与 Profiles
Codex 配置文件的位置与优先级、最常改的配置项、用 profile 文件切换不同工作模式，以及命令行临时覆盖。
Codex CLI 和 IDE 扩展共用一套配置。个人默认配置写在 ~/.codex/config.toml，没有这个文件就新建一个。
在 IDE 扩展里，点右上角齿轮，选择 Codex Settings > Open config.toml，可以直接打开这个文件。
配置优先级
同一个配置项出现在多个地方时，按下面的顺序生效（越靠前优先级越高）：
- 命令行参数和
-c/--config覆盖 - 项目里的
.codex/config.toml（从项目根目录到当前目录，越近越优先；只在你信任这个项目时才加载） - 用
--profile选中的 profile 文件 - 用户配置
~/.codex/config.toml - 工作区下发的云端配置（如有）
- 系统配置
/etc/codex/config.toml（Unix，如有） - 内置默认值
排查"配置为什么没生效"时，在 Codex 里输入 /debug-config，可以看到每一层的情况。
常用配置项
# ~/.codex/config.toml
# 默认模型（换成你账号可用的模型）
model = "gpt-6.1-sol"
# 推理强度，可选值取决于模型
model_reasoning_effort = "medium"
# 审批与沙箱
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# 网页搜索：cached（默认，读缓存索引）/ live（实时）/ indexed / disabled
web_search = "cached"
# 凭据存到系统钥匙串
cli_auth_credentials_store = "keyring"
# 让回复里的文件引用变成可点击链接：vscode / cursor / windsurf / vscode-insiders / none
file_opener = "vscode"
# 单独指定 /review 使用的模型
# review_model = "gpt-6.1-sol"
# 允许 workspace-write 模式下联网
[sandbox_workspace_write]
network_access = false
# 本地历史记录：不想保存可设为 "none"
[history]
persistence = "save-all"不需要改的项不用写，Codex 会用内置默认值。比如 history.persistence 默认就是 "save-all"，只有想关闭本地历史记录时才需要设成 "none"。
Profiles：一键切换工作模式
Profile 是一份叠加在基础配置之上的配置文件，只需要写和基础配置不一样的项。
写法已经改变
从 Codex 0.134.0 起，profile 不再写在 config.toml 的 [profiles.名字] 小节里，顶层的 profile = "名字" 也不再支持。每个 profile 现在是一个单独的文件：~/.codex/<名字>.config.toml。网上很多老教程还是旧写法，请注意区分。
示例：深度审查模式
新建 ~/.codex/deep-review.config.toml，直接写顶层配置项，不要再套 [profiles.xxx]：
# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"使用：
codex --profile deep-review
codex exec --profile deep-review "审查这次改动"profile 名只能包含字母、数字、连字符和下划线。
从旧写法迁移
如果你的 config.toml 里还有这样的内容：
# 旧写法，已失效
profile = "fast"
[profiles.fast]
model_reasoning_effort = "low"把 [profiles.fast] 里的配置挪到 ~/.codex/fast.config.toml（去掉小节标题），再删掉 config.toml 里的 profile = ... 和 [profiles.fast]。
命令行临时覆盖
只想对这一次运行改配置时：
# 有专门参数的，优先用参数
codex --model gpt-6.1-sol
# 任意配置项：值按 TOML 解析
codex --config model='"gpt-6.1-sol"'
codex -c sandbox_workspace_write.network_access=true
codex -c 'shell_environment_policy.include_only=["PATH","HOME"]'- 用点号设置嵌套项，比如
mcp_servers.context7.enabled=false； - 值按 TOML 解析，解析失败就当字符串处理；
- 值里有空格时加引号，避免被 shell 拆开。
项目级配置
在仓库里放 .codex/config.toml，可以给这个项目单独设置（只在你信任该项目时加载）。出于安全考虑，项目配置不能修改下面这些项，Codex 会忽略并给出警告：openai_base_url、chatgpt_base_url、model_provider、model_providers、notify、profile、profiles、otel 等。这些只能写在用户级 ~/.codex/config.toml 里。
本地文件都在哪
Codex 的本地状态都放在 CODEX_HOME（默认 ~/.codex）下：
| 文件 / 目录 | 内容 |
|---|---|
config.toml | 你的配置 |
<名字>.config.toml | profile 文件 |
AGENTS.md | 全局说明 |
auth.json | 登录凭据（使用文件存储时） |
sessions/ | 会话记录 |
archived_sessions/ | 已归档的会话 |