配置基础

身份 非官方简体中文镜像

翻译状态 AI 翻译 / AI 审校

来源版本 官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

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 （~/.codex/profile-name.config.toml）
4. 用户配置： ~/.codex/config.toml
5. 系统配置（如果存在）： /etc/codex/config.toml 在 Unix 上
6. 内置默认值

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

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

有关通过 -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 时，请将原生沙箱模式设置为 elevated ，位置在 windows 表中。仅在你没有管理员权限或提权设置失败时使用 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 thread/turn 时按每个 APIs进行覆盖。

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

功能标志

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

常见功能标志

键	默认值	成熟度	说明
apps	true	稳定	启用应用（连接器）集成
goals	true	稳定	启用持久化目标和自动继续
hooks	true	稳定	启用来自以下位置的生命周期钩子： hooks.json 或内联 [hooks]。请参阅 钩子。
fast_mode	true	稳定	启用快速模式选择和 service_tier = "fast" 路径
memories	false	实验性	启用 记忆
multi_agent	true	稳定	启用子 Agent 协作工具
personality	true	稳定	启用个性选择控件
remote_plugin	true	稳定	启用远程插件目录
shell_snapshot	true	稳定	为你的 shell 环境创建快照，以加速重复命令
shell_tool	true	稳定	启用默认 shell 工具
unified_exec	true Windows 除外	稳定	使用统一的由 PTY支持的 exec 工具
web_search	true	已弃用	旧版开关；建议使用顶层 web_search 设置
web_search_cached	false	已弃用	旧版开关，会映射到 web_search = "cached" 未设置时
web_search_request	false	已弃用	旧版开关，会映射到 web_search = "live" 未设置时

此表列出常见的面向用户的标志，而不是每个内部或 开发中的功能。成熟度列使用诸如 实验性、Beta 和稳定等标签。请参阅 功能 成熟度 了解如何解读这些标签。

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

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

启用功能

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