Codex 会从多个位置读取配置详情。您的个人默认设置位于 ~/.codex/config.toml，您也可以通过 .codex/config.toml 文件添加项目级覆盖。出于安全考虑，Codex 仅在您信任该项目时才会加载项目级的 .codex/ 层。
Codex 配置文件
Codex 将用户级配置存储在 ~/.codex/config.toml。若要针对特定项目或子文件夹设置作用域，请在代码仓库中添加一个 .codex/config.toml 文件。
要从 Codex IDE 扩展中打开配置文件，请点击右上角的齿轮图标，然后选择 Codex Settings > Open config.toml。
CLI 和 IDE 扩展共享相同的配置层。您可以使用它们来：
配置优先级
Codex 按以下顺序解析值（优先级从高到低）：
- CLI 参数和
--config覆盖项 - 配置文件 (Profile) 值（通过
--profile <name>） - 项目配置文件：
.codex/config.toml，从项目根目录向下到当前工作目录依次排序（越靠近当前目录优先级越高；仅限受信任项目） - 用户配置：
~/.codex/config.toml - 系统配置（如果存在）：Unix 系统上的
/etc/codex/config.toml - 内置默认值
利用这一优先级，您可以在顶层设置共享的默认值，并将配置文件的重点放在需要差异化的数值上。
如果您将项目标记为“不受信任”，Codex 将跳过项目范围内的 .codex/ 层，包括项目本地的配置、钩子 (hooks) 和规则。用户和系统配置仍会加载，包括用户/全局钩子和规则。
关于通过 -c/--config 进行的一次性覆盖（包括 TOML 引号规则），请参见 高级配置。
在受管计算机上，您的组织可能通过 requirements.toml 强制实施约束（例如，禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access"）。请参见 受管配置 和 管理员强制实施的要求。
常用配置选项
以下是人们最常更改的几个选项：
默认模型
选择 Codex 在 CLI 和 IDE 中默认使用的模型。
model = "gpt-5.5"审批提示
控制 Codex 在运行生成的命令前何时需要暂停询问。
approval_policy = "on-request"关于 untrusted（不受信任）、on-request（请求时）和 never（从不）之间的行为差异，请参见 无需审批提示运行 和 常见的沙盒与审批组合。
沙盒级别
调整 Codex 在执行命令时拥有的文件系统和网络访问权限大小。
sandbox_mode = "workspace-write"关于各模式的具体行为（包括受保护的 .git/.codex 路径和网络默认值），请参见 沙盒与审批、可写根目录下的受保护路径 和 网络访问。
权限配置文件
Codex 还支持为可复用的文件系统和网络策略配置命名权限文件。内置配置文件包括 :read-only、:workspace 和 :danger-full-access。自定义配置文件使用 [permissions.<name>] 表和匹配的 default_permissions 值。请参见 权限。
Windows 沙盒模式
在 Windows 上原生运行 Codex 时，请在 windows 表中将原生沙盒模式设置为 elevated（提升权限）。仅当您没有管理员权限或提升权限设置失败时，才使用 unelevated（不提升权限）。
[windows]
sandbox = "elevated" # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable网页搜索模式
Codex 默认开启本地任务的网页搜索，并提供来自网页搜索缓存的结果。该缓存是 OpenAI 维护的网页结果索引，因此“缓存模式”返回的是预索引结果，而非实时抓取页面。这减少了接触任意实时内容中提示注入攻击的风险，但您仍应将网页结果视为不受信任。如果您正在使用 --yolo 或其他 完全访问沙盒设置，网页搜索将默认为实时结果。请使用 web_search 选择模式：
"cached"（默认）：从网页搜索缓存中提供结果。"live"：从网页获取最新数据（与--search相同）。"disabled"：关闭网页搜索工具。
web_search = "cached" # default; serves results from the web search cache
# web_search = "live" # fetch the most recent data from the web (same as --search)
# web_search = "disabled"推理力度
在支持的情况下，调整模型执行推理的努力程度。
model_reasoning_effort = "high"沟通风格
为受支持的模型设置默认的沟通风格。
personality = "friendly" # or "pragmatic" or "none"您以后可以在活动会话中使用 /personality 进行覆盖，或在使用应用服务器 API 时按线程/轮次进行覆盖。
TUI 快捷键映射
在 tui.keymap 下自定义终端快捷键。特定上下文的绑定会覆盖 tui.keymap.global，留空则会取消该动作的绑定。
[tui.keymap.global]
open_transcript = "ctrl-t"
[tui.keymap.composer]
submit = ["enter", "ctrl-m"]命令环境
控制 Codex 将哪些环境变量转发给派生命令。
[shell_environment_policy]
include_only = ["PATH", "HOME"]日志目录
覆盖 Codex 写入本地日志文件（如 codex-tui.log）的位置。
log_dir = "/absolute/path/to/codex-logs"对于单次运行，您也可以从 CLI 设置它。
codex -c log_dir=./.codex-log功能标志
使用 config.toml 中的 [features] 表来切换可选和实验性功能。
[features]
shell_snapshot = true # Speed up repeated commands支持的功能
| 键 (Key) | 默认 | 成熟度 | 描述 |
|---|---|---|---|
apps | false | 实验版 | 启用 ChatGPT 应用/连接器支持 |
codex_git_commit | false | 实验版 | 启用 Codex 生成的 git 提交和提交归属尾注 |
hooks | true | 稳定版 | 启用来自 hooks.json 或内联 [hooks] 的生命周期钩子。请参见 钩子。 |
fast_mode | true | 稳定版 | 启用快速模式选择和 service_tier = "fast" 路径 |
memories | false | 稳定版 | 启用 记忆 (Memories) |
multi_agent | true | 稳定版 | 启用多智能体协作工具 |
personality | true | 稳定版 | 启用个性选择控件 |
shell_snapshot | true | 稳定版 | 快照您的 shell 环境以加速重复命令 |
shell_tool | true | 稳定版 | 启用默认的 shell 工具 |
unified_exec | 除 Windows 外均为 true | 稳定版 | 使用基于统一 PTY 的执行工具 |
undo | false | 稳定版 | 通过每轮 git 快照启用撤销功能 |
web_search | true | 已废弃 | 旧版切换；优先使用顶层的 web_search 设置 |
web_search_cached | false | 已废弃 | 旧版切换；未设置时映射为 web_search = "cached" |
web_search_request | false | 已废弃 | 旧版切换；未设置时映射为 web_search = "live" |
“成熟度”列使用了功能成熟度标签，例如实验性 (Experimental)、测试版 (Beta) 和稳定版 (Stable)。请参见 功能成熟度 以了解如何解读这些标签。
关于生命周期钩子配置，请参见 钩子。
启用功能
- 在
config.toml中，在[features]下添加feature_name = true。 - 从 CLI 运行
codex --enable feature_name。 - 要启用多个功能，请运行
codex --enable feature_a --enable feature_b。 - 要禁用某项功能，请在
config.toml中将该键设置为false。