配置基础

学习 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 按以下顺序解析配置值（优先级从高到低）：

1. CLI 标志和 --config 覆盖
2. 项目配置文件：.codex/config.toml，按从项目根目录向下到当前工作目录的顺序排列（最近的优先；仅限受信任的项目）
3. 使用 --profile profile-name 选择的配置文件（~/.codex/profile-name.config.toml）
4. 用户配置：~/.codex/config.toml
5. 系统配置（如果存在）：Unix 上为 /etc/codex/config.toml
6. 内置默认值

使用该优先级在 config.toml 中设置共享默认值，并让 profile 文件只关注那些不同的值。

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

关于通过 -c/--config 进行一次性覆盖（包括 TOML 引号规则），请参阅高级配置。

Note

在托管机器上，你的组织可能还会通过 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。仅当你没有管理员权限或 elevated 设置失败时，才使用 unelevated。

[windows]
sandbox = "elevated"   # 推荐
# sandbox = "unelevated" # 当管理员权限/设置不可用时的备选方案

网页搜索模式

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

• "cached"（默认）：从网页搜索缓存提供结果。
• "live"：从网页获取最新数据（等同于 --search）。
• "disabled"：关闭网页搜索工具。

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

推理力度

在模型支持的情况下，调整其推理力度。

model_reasoning_effort = "high"

沟通风格

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

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

你可以在活跃会话中稍后通过 /personality 覆盖此设置，或在使用 app-server API 时按线程/轮次覆盖。

TUI 键盘映射

在 tui.keymap 下自定义终端快捷键。选定的 composer 操作会回退到匹配的 tui.keymap.global 绑定；在支持时，特定上下文的绑定优先。空列表会解除该操作的绑定。

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

命令环境变量

控制 Codex 将哪些环境变量转发给生成的命令。

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

日志目录

覆盖 Codex 写入本地日志文件的位置。显式设置 log_dir 还会在该目录中启用可选择加入的明文 TUI 日志 codex-tui.log。

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

对于一次性运行，你也可以从 CLI 设置：

codex -c log_dir=./.codex-log

功能标志

在 config.toml 中使用 [features] 表来切换可选和实验性功能。

[features]
shell_snapshot = true           # 加快重复命令的速度

支持的功能

键	默认值	成熟度	描述
apps	false	实验性	启用 ChatGPT Apps/connectors 支持
codex_git_commit	false	实验性	启用 Codex 生成的 git 提交和提交归因 trailers
hooks	true	稳定	启用来自 hooks.json 或内联 [hooks] 的生命周期 hooks。参见 Hooks。
fast_mode	true	稳定	启用 Fast 模式选择和 service_tier = "fast" 路径
memories	false	稳定	启用 Memories
multi_agent	true	稳定	启用 subagent 协作工具
personality	true	稳定	启用 personality 选择控制
shell_snapshot	true	稳定	对你的 shell 环境进行快照，以加快重复命令
shell_tool	true	稳定	启用默认 shell 工具
unified_exec	true，Windows 除外	稳定	使用统一的基于 PTY 的 exec 工具
undo	false	稳定	通过每轮 git ghost snapshots 启用 undo
web_search	true	已弃用	旧版开关；优先使用顶层 web_search 设置
web_search_cached	false	已弃用	旧版开关，未设置时映射到 web_search = "cached"
web_search_request	false	已弃用	旧版开关，未设置时映射到 web_search = "live"

Note

成熟度列使用实验性、测试版和稳定版等功能成熟度标签。请参阅 功能成熟度 了解如何解读这些标签。

Note

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

关于生命周期 hook 配置，请参阅 Hooks。

启用功能

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