本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/config-basic

配置基础

了解配置本地 Codex 客户端的基础知识

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 扩展共享相同的配置层。你可以用它们来：

设置默认模型和提供方。
配置审批策略和沙箱设置。
配置 MCP 服务器。

配置优先级

Codex 按以下顺序解析值（优先级从高到低）：

CLI 标志和 --config 覆盖
Profile 值（来自 --profile ）
项目配置文件：.codex/config.toml，按从项目根目录到当前工作目录的顺序排列（越近者优先；仅限受信任项目）
用户配置：~/.codex/config.toml
系统配置（如果存在）：Unix 上的 /etc/codex/config.toml
内置默认值

使用这一优先级，在顶层设置共享默认值，并让 profile 只关注那些不同的值。

如果你将某个项目标记为不受信任，Codex 会跳过项目范围的 .codex/ 层，包括项目本地配置、hooks 和 rules。用户和系统配置仍会加载，包括用户/全局 hooks 和 rules。

有关通过 -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 路径和默认网络设置），请参阅沙箱与审批、可写根中的受保护路径和网络访问。

权限 profiles

Codex 还支持命名的权限 profile，用于复用文件系统和网络策略。内置 profile 有 :read-only、:workspace 和 :danger-full-access。自定义 profile 使用 [permissions.] 表以及匹配的 default_permissions 值。请参阅Permissions。

Windows 沙箱模式

当在 Windows 上原生运行 Codex 时，请在 windows 表中将原生沙箱模式设置为 elevated。只有在你没有管理员权限或提升设置失败时，才使用 unelevated。

[windows]
sandbox = "elevated"   # 推荐
# sandbox = "unelevated" # 当管理员权限/设置不可用时作为回退

Web 搜索模式

Codex 默认会为本地任务启用 Web 搜索，并从 Web 搜索缓存提供结果。该缓存是由 OpenAI 维护的 Web 结果索引，因此缓存模式会返回预先编入索引的结果，而不是抓取实时页面。这会减少来自任意实时内容的提示注入暴露，但你仍应将 Web 结果视为不受信任。如果你正在使用 --yolo 或其他完全访问沙箱设置，Web 搜索默认会返回实时结果。使用 web_search 选择模式：

"cached"（默认）从 Web 搜索缓存提供结果。
"live" 从 Web 获取最新数据（与 --search 相同）。
"disabled" 关闭 Web 搜索工具。

web_search = "cached"  # 默认；从 Web 搜索缓存提供结果
# web_search = "live"  # 从 Web 获取最新数据（与 --search 相同）
# web_search = "disabled"

推理强度

在支持时，调整模型应用的推理强度。

model_reasoning_effort = "high"

沟通风格

为受支持的模型设置默认沟通风格。

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

你之后可以在活动会话中通过 /personality 覆盖它，或者在使用 app-server 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           # 加速重复命令

支持的功能

Key	Default	Maturity	Description
`apps`	false	Experimental	启用 ChatGPT Apps/connectors 支持
`codex_git_commit`	false	Experimental	启用由 Codex 生成的 git commit 和 commit attribution trailers
`hooks`	true	Stable	启用来自 `hooks.json` 或内联 `[hooks]` 的生命周期 hooks。参见 Hooks。
`plugin_hooks`	false	Under development	选择启用随插件打包的生命周期 hooks。参见 Hooks。
`fast_mode`	true	Stable	启用 Fast 模式选择和 `service_tier = "fast"` 路径
`memories`	false	Stable	启用 Memories
`multi_agent`	true	Stable	启用 subagent 协作工具
`personality`	true	Stable	启用 personality 选择控件
`shell_snapshot`	true	Stable	对你的 shell 环境做快照以加速重复命令
`shell_tool`	true	Stable	启用默认 `shell` 工具
`unified_exec`	`true` except Windows	Stable	使用统一的 PTY 支持 exec 工具
`undo`	false	Stable	启用通过按轮次的 git ghost snapshots 实现的撤销
`web_search`	true	Deprecated	旧版切换项；更推荐使用顶层 `web_search` 设置
`web_search_cached`	false	Deprecated	旧版切换项；在未设置时映射到 `web_search = "cached"`
`web_search_request`	false	Deprecated	旧版切换项；在未设置时映射到 `web_search = "live"`

Maturity 列使用功能成熟度标签，例如 Experimental、Beta 和 Stable。有关如何解读这些标签，请参阅 Feature Maturity。

省略功能键可保持其默认值。

有关生命周期钩子配置，请参阅 Hooks。

启用功能

在 config.toml 中，于 [features] 下添加 feature_name = true。
在 CLI 中，运行 codex --enable feature_name。
要启用多个功能，运行 codex --enable feature_a --enable feature_b。
要禁用某个功能，请在 config.toml 中将该键设为 false。

Codex 配置文件​

配置优先级​

常见配置选项​

默认模型​

审批提示​

沙箱级别​

权限 profiles​

Windows 沙箱模式​

Web 搜索模式​

推理强度​

沟通风格​

TUI 键位映射​

命令环境​

日志目录​

功能标志​

支持的功能​

启用功能​