配置基础

身份 非官方简体中文镜像

翻译状态 AI 翻译 / AI 审校

来源版本 官方未提供

同步日期 2026-07-26

官方原文 learn.chatgpt.com

Codex 会从多个位置读取配置详细信息。个人默认配置位于 ~/.codex/config.toml，你可以通过 .codex/config.toml 文件添加项目覆盖配置。出于安全考虑，Codex 仅在你信任项目时加载项目的 .codex/ 配置层。

Codex 配置文件

Codex 将用户级配置存储在 ~/.codex/config.toml 中。若要将设置限定到特定项目或子文件夹，请在仓库中添加 .codex/config.toml 文件。

要从 Codex IDE extension 打开配置文件，请选择右上角的齿轮图标，然后选择 Codex Settings > Open config.toml。

CLI 和 IDE extension 共享相同的配置层。你可以使用它们来：

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

配置优先级

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

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

利用这一优先级顺序在 config.toml 中设置共享默认值，并让 profile 文件 专注于存储差异化的值。

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

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

在受管控的计算机上，你的组织还可能通过 requirements.toml 强制实施限制（例如禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access"）。请参阅受管控配置和管理员强制要求。

常见配置选项

以下是用户最常修改的几个选项：

默认模型

选择 Codex 在 CLI 和 IDE 中默认使用的模型。

model = "gpt-5.6"

批准提示

控制 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

Web 搜索模式

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

• "cached"（默认）从 Web 搜索缓存提供结果。
• "indexed" 仅当搜索索引允许请求时，才允许外部 Web 访问。
• "live" 从 Web 获取最新数据（与 --search 相同）。
• "disabled" 关闭 Web 搜索工具。

web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# 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 覆盖此设置；使用 app-server API 时，也可以针对线程或回合覆盖此设置。

TUI 键位映射

在 tui.keymap 下自定义终端快捷键。选定的编辑器操作会回退到匹配的 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] 表格切换可选和实验性功能。

常见功能标志

键	默认值	成熟度	描述
apps	true	Stable	启用应用（连接器）集成
goals	true	Stable	启用持久化目标和自动继续
hooks	true	Stable	启用来自 hooks.json 或内联 [hooks] 的生命周期钩子。请参阅 Hooks。
fast_mode	true	Stable	启用 Fast 模式选择和 service_tier = "fast" 路径
memories	false	Experimental	启用 Memories
multi_agent	true	Stable	启用子代理协作工具
personality	true	Stable	启用个性选择控件
remote_plugin	true	Stable	启用远程插件目录
shell_snapshot	true	Stable	对 shell 环境创建快照，以加快重复命令的执行
shell_tool	true	Stable	启用默认的 shell 工具
unified_exec	Windows 除外为 true	Stable	使用统一的基于 PTY 的 exec 工具
web_search	true	Deprecated	旧版开关；建议使用顶层 web_search 设置
web_search_cached	false	Deprecated	未设置时映射为 web_search = "cached" 的旧版开关
web_search_request	false	Deprecated	未设置时映射为 web_search = "live" 的旧版开关

此表列出了常见的面向用户的标志，并非所有内部或仍在开发中的功能。成熟度列使用 Experimental、Beta 和 Stable 等标签。有关如何理解这些标签，请参阅功能成熟度。

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

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

启用功能

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