Codex 的配置从 ~/.codex/config.toml（用户级）和 .codex/config.toml（项目级）读取，CLI flags 优先级最高。本文覆盖配置优先级规则、最常修改的几个选项（模型、审批策略、沙箱级别、联网模式、推理强度、通信风格），以及 Feature flags 完整列表——帮你快速知道"这个要改哪里"。

Codex 配置基础

配置文件位置

• 用户级配置：~/.codex/config.toml（个人默认值，所有项目共用）
• 项目级配置：仓库根目录下的 .codex/config.toml（覆盖用户级设置，仅在该项目生效）

CLI 和 IDE 扩展共享同一套配置层级。在 IDE 扩展里，点击右上角齿轮图标 → Codex Settings > Open config.toml 直接打开配置文件。

---

配置优先级

优先级从高到低：

1. CLI flags 和 --config 覆盖
2. Profile 值（用 --profile <name> 指定）
3. 项目配置文件：.codex/config.toml（从项目根到当前工作目录，就近优先；仅受信任项目）
4. 用户配置：~/.codex/config.toml
5. 系统配置（如存在）：Unix 上的 /etc/codex/config.toml
6. 内置默认值

如果项目被标记为不受信任，Codex 跳过所有 .codex/ 层，直接用用户和内置默认值。

在托管机器上，组织可能通过 requirements.toml 限制某些配置选项，例如禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access"。详见企业托管配置。

---

常用配置项

默认模型

model = "gpt-5.4"

审批策略

控制 Codex 在执行命令前是否暂停询问：

approval_policy = "on-request"
# 其他选项：untrusted（更严格）、never（完全自动）

不同策略的行为差异见审批与沙箱文档。

沙箱级别

控制 Codex 执行命令时对文件系统和网络的访问范围：

sandbox_mode = "workspace-write"
# 其他选项：read-only（更严格）、danger-full-access（完全开放）

Windows 沙箱模式

在 Windows 上原生运行时设置：

[windows]
sandbox = "elevated"   # 推荐，需要管理员权限
# sandbox = "unelevated" # 无管理员权限时的备选

联网模式

Codex 本地任务默认开启联网，从缓存索引提供搜索结果：

web_search = "cached"   # 默认：从 OpenAI 维护的缓存索引返回
# web_search = "live"   # 每次实时抓取最新数据（同 --search flag）
# web_search = "disabled"  # 完全关闭

使用 --yolo 或其他全访问沙箱设置时，默认切换为 live 模式。

推理强度

model_reasoning_effort = "high"
# 其他选项：medium、low

通信风格

personality = "friendly"   # 或 "pragmatic" 或 "none"

也可以在活跃会话里用 /personality 命令临时切换。

命令环境变量

控制 Codex 向子进程传递哪些环境变量：

[shell_environment_policy]
include_only = ["PATH", "HOME"]

日志目录

log_dir = "/absolute/path/to/codex-logs"

单次运行也可从 CLI 指定：

codex -c log_dir=./.codex-log

---

Feature Flags

在 config.toml 的 [features] 表里控制实验性和可选功能：

[features]
shell_snapshot = true

完整 Feature 列表

Key	默认值	成熟度	说明
apps	false	Experimental	启用 ChatGPT Apps/Connectors 支持
codex_hooks	false	Under development	从 hooks.json 启用生命周期 hooks
fast_mode	true	Stable	启用 Fast 模式和 service_tier = "fast" 路径
multi_agent	true	Stable	启用子代理协作工具
personality	true	Stable	启用通信风格选择控件
shell_snapshot	true	Stable	快照 shell 环境以加速重复命令
shell_tool	true	Stable	启用默认 shell 工具
smart_approvals	false	Experimental	将部分审批请求路由给 guardian reviewer 子代理处理
unified_exec	true（Windows 除外）	Stable	使用统一的 PTY-backed exec 工具
undo	false	Stable	通过每轮 git ghost 快照启用撤销功能
web_search	true	Deprecated	遗留开关，建议改用顶层 web_search 设置
web_search_cached	false	Deprecated	遗留开关，映射到 web_search = "cached"
web_search_request	false	Deprecated	遗留开关，映射到 web_search = "live"

省略某个 key 保持其默认值不变。

启用 Feature 的三种方式

1. 在 config.toml 的 [features] 下加 feature_name = true
2. 从 CLI 运行：codex --enable feature_name
3. 同时启用多个：codex --enable feature_a --enable feature_b

要禁用某个 feature，在 config.toml 里设置 feature_name = false。

---

常见问题

Q: 项目配置和用户配置冲突时以谁为准？

A: 项目配置优先级高于用户配置，但要求项目被标记为受信任。未受信任的项目的 .codex/config.toml 会被完全忽略，使用用户配置的默认值。

Q: 怎么临时覆盖某个配置项，又不影响 config.toml？

A: 用 CLI 的 -c / --config flag，例如 codex -c model='"gpt-4.1"'，只对当次运行生效。值使用 TOML 语法，字符串要加引号。

Q: Feature flag 里的 "Experimental" 是什么意思？

A: 表示该功能还在开发迭代中，接口或行为可能在未来版本里变动或被移除。生产环境建议谨慎启用。更多成熟度标签说明见 Feature Maturity 文档。