Codex 配置参考中文指南：读懂 config.toml、Profile 与权限设置

配图来源：OpenAI Codex Ambassadors。

Codex 的 config.toml 可以决定默认模型、推理强度、文件访问范围、联网方式，以及接入哪些外部工具。配置项很多，但实际使用时，可以从一份小配置开始，再根据任务逐项增加。

本文以 OpenAI 官方 Configuration Reference 为主线，按使用场景整理关键字段的中文含义，并补充独立编写的示例。适合先通读，再按字段名查找；完整字段表可回到原文检索。

从一份基础配置开始

如果已经完成登录，可以先在用户级 config.toml 中合并下面几项，模型沿用当前默认设置：

# 需要额外权限时请求审批
approval_policy = "on-request"

# 允许在工作区内写入
sandbox_mode = "workspace-write"

# 使用缓存网页搜索
web_search = "cached"

[sandbox_workspace_write]
network_access = false

这组设置适合“阅读项目、修改文件、运行本地检查”的工作流。命令默认无法联网，但网页搜索有自己的访问设置；需要下载依赖时，再调整命令网络权限。相关行为见审批与沙盒说明。

合并 TOML 时，把 model、web_search 等顶层字段放在 [表名] 之前。同一张表也不要重复声明。例如，写在 [sandbox_workspace_write] 后面的 model = "..." 会属于这张表，失去顶层模型配置的含义。官方示例配置

配置放在哪里，谁覆盖谁

同一个字段的优先级从高到低是：

1. 命令行参数和 --config。
2. 已信任项目中的 .codex/config.toml，越接近当前目录越优先。
3. 通过 --profile 选中的配置文件。
4. 用户级 ~/.codex/config.toml。
5. 系统配置，Unix 上通常为 /etc/codex/config.toml。
6. 内置默认值。

项目被标记为不可信时，项目级 .codex/ 配置、Hooks 和规则会被跳过；用户与系统层仍会加载。CLI 与 IDE 扩展共用这些配置层。配置基础与优先级

如果设置了 CODEX_HOME，配置和状态根目录随之改变，默认值才是 ~/.codex。自定义目录需要预先存在。环境变量参考

Provider 等机器级设置要放在用户配置中。 当前文档明确列出：项目配置中的 model_provider、model_providers、openai_base_url、chatgpt_base_url、notify、otel 等字段会被忽略。排查“项目里改了接口却没生效”时，先检查这一点。项目配置限制

模型、推理强度和上下文

这组字段分别影响模型选择、思考投入和输出表现：

例如，model_reasoning_summary = "none" 关闭的是摘要展示；需要调整推理投入，应修改 model_reasoning_effort。计划模式也有单独的字段，不能假定它总会继承普通模式的强度。模型配置字段

可以先只调整下面几项，观察回答长度与任务效果，再决定是否修改其他参数：

model_reasoning_effort = "high"
plan_mode_reasoning_effort = "high"
model_reasoning_summary = "none"
model_verbosity = "low"

这段配置要求所选模型支持对应选项。上下文大小和压缩阈值可先保持默认；手动填写一个更大的窗口数值，并不会扩大服务端模型实际支持的容量。

Profile：为不同任务保存差异配置

当前配置 Profile 使用独立文件。例如，把下面内容保存为 ~/.codex/review.config.toml：

model_reasoning_effort = "high"
model_verbosity = "low"

启动时选择它：

codex --profile review

Profile 只需写与用户默认值不同的字段。从 Codex 0.134.0 起，旧的 [profiles.review] 表和顶层 profile = "review" 选择器已不再受支持，应迁移到独立文件。Profile 配置与迁移

单次调整也可以直接使用命令行。-c 的值按 TOML 解析，下面是 Bash / Zsh 示例：

codex -c 'model_reasoning_effort="high"' -c 'web_search="live"'

适合临时验证的参数，先通过命令行试用，确认合适后再写入文件。命令行临时覆盖

Provider：连接模型接口

model_provider 选择提供商，[model_providers.<id>] 定义其连接方式。下面是用户配置中的网关示例，使用前需要替换接口地址，并在启动 Codex 的环境中设置 TEAM_MODEL_API_KEY：

model_provider = "team_gateway"

[model_providers.team_gateway]
name = "Team Model Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
env_key = "TEAM_MODEL_API_KEY"

name 是显示名称，base_url 是接口基础地址，env_key 填写保存密钥的环境变量名称。模型 ID 还需要与网关实际提供的模型匹配。上面的地址是占位示例。Provider 示例、Provider 环境变量

当前参考页中，wire_api 仅支持 responses。自定义 Provider ID 也不能占用内置的 openai、ollama、lmstudio。Provider 字段约束

需要附加请求头时，可使用 http_headers 或从环境变量取值的 env_http_headers。企业凭据助手可使用 [model_providers.<id>.auth] 获取令牌，这种方式不能与 env_key、experimental_bearer_token、requires_openai_auth 混用。自定义 Provider 与认证

审批策略和沙盒分别控制什么

审批策略决定何时请求授权，沙盒决定本地命令的文件与网络访问范围。

例如，read-only 配合 never 可以用于不弹审批的只读任务。never 本身不会解除沙盒。workspace-write 也不代表项目内所有路径都可随意写入，.git、.codex 等目录可能保持只读。常见审批与沙盒组合

approvals_reviewer = "auto_review" 会让符合条件的交互式审批交给自动审查；它改变审批者，现有沙盒边界仍然适用。自动审批审查

新版权限 Profile：集中管理文件和网络规则

default_permissions 与 [permissions.<name>] 属于 Beta 权限配置。它和 --profile review 选择的配置 Profile 是两个概念：前者描述访问规则，后者叠加一组通用配置。

下面是一份替代本文开头传统沙盒设置的示例：

approval_policy = "on-request"
default_permissions = "docs_edit"

[permissions.docs_edit]
extends = ":workspace"
description = "编辑工作区文档，命令不联网"

[permissions.docs_edit.network]
enabled = false

内置权限 Profile 包括 :read-only、:workspace 和 :danger-full-access。使用这套配置时，应移除已加载配置中的 sandbox_mode、[sandbox_workspace_write]，并避免同时传入 --sandbox；两套设置不组合叠加。权限 Profile 说明

自定义规则可以细化到路径、Glob 和域名。特别注意：network.enabled = true 只允许命令联网。要让域名规则生效，还需要启用网络代理，例如 [features.network_proxy] 中的 enabled = true，或由管理员启用相应代理要求。网络权限及代理条件

网页搜索、命令联网和环境变量

web_search 有四种模式：

完整访问模式下，网页搜索默认会切到 live。搜索工具与命令网络权限独立，tools.web_search.allowed_domains 也只作用于搜索，不限制 Shell、Apps 或 MCP。自定义 Provider 能否搜索，还取决于接口、模型和运行时的支持。网页搜索配置

另一个容易混淆的设置是 shell_environment_policy：它控制传给子进程的环境变量。例如，在有自动过滤需求时，可以设置：

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"DEPLOY_*" = "exclude"

ignore_default_excludes 当前默认是 true；改为 false 才会启用针对变量名中 KEY、SECRET、TOKEN 的自动排除。这里控制的是命令环境，Provider 的认证配置仍有自己的用途。命令环境配置

MCP：接入外部工具

MCP 配置以 [mcp_servers.<名称>] 为单位。先分清两种连接：

远程服务的占位示例：

[mcp_servers.team_docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "TEAM_DOCS_TOKEN"
startup_timeout_sec = 15
tool_timeout_sec = 90

替换为实际服务和凭据后再使用。若服务使用 OAuth，可按服务要求运行 codex mcp login team_docs；终端会话中的 /mcp 用于查看活动服务。MCP 连接与配置

管理工具时，常用 enabled 暂时关闭服务，enabled_tools 限定可用工具，disabled_tools 再排除工具。required = true 表示该服务初始化失败时阻止启动。超时字段默认分别为启动 10 秒、工具调用 60 秒。MCP 可选配置

功能开关、指令和子代理

功能开关放在 [features] 下。当前文档中，apps、goals、hooks、multi_agent、remote_plugin 等已是稳定且默认开启的功能；memories 仍标为实验性、默认关闭。省略字段会保留默认值，复制旧教程时应重新核对功能状态。功能开关表

项目的工作约定适合写入 AGENTS.md。与之相关的配置有 project_doc_fallback_filenames，用于增加后备文件名，以及 project_doc_max_bytes，用于限制汇总的项目指令大小。官方说明当前默认上限为 32 KiB。AGENTS.md 的发现与加载

子代理全局设置仍写在 [agents] 中，例如限制同时打开的子代理线程数：

[agents]
max_concurrent_threads_per_session = 3

这里的数量不包含主代理。需要专门角色时，可在 ~/.codex/agents/ 或项目 .codex/agents/ 下创建独立 TOML 文件，并填写 name、description、developer_instructions。当前本地客户端通常在用户明确要求，或适用的 AGENTS.md / Skill 指令要求时开展委派。子代理配置

Skills、Apps 和 Plugins 也各有配置入口。选择时先看目标：复用工作方法用 Skill，连接外部服务用工具连接，把相关能力一起分发则用 Plugin。插件可以同时包含技能与工具。Skills 与 Plugins

Hooks、历史和终端体验

Hooks 可以在会话开始、工具执行前后、上下文压缩前后等时机运行脚本或 MCP 工具。配置可以写入 hooks.json，也可以内联到 config.toml 的 [hooks] 中。

Hooks 的合并规则需要单独理解：多个来源中匹配的 Hook 会一起执行，高优先级配置不会简单替换低优先级 Hook。普通 Hook 新增或修改后，需要通过 /hooks 审查并信任其定义才会运行。Hooks 配置与信任

日常终端使用还可以调整下面几项：

file_opener = "vscode"

[history]
max_bytes = 52428800

[tui]
notifications = ["agent-turn-complete"]

这个示例选择 VS Code 打开文件引用，将历史文件上限设为 50 MiB，并启用任务结束通知。它们分别属于文件链接、历史持久化与终端界面设置。官方示例中的界面与历史配置

需要排查日志时，可以显式设置 log_dir；这也会开启该目录中的明文 codex-tui.log。诊断输出的详细程度由 RUST_LOG 控制。诊断与日志

requirements.toml：管理员约束可选范围

config.toml 保存使用偏好，requirements.toml 定义管理员强制实施的限制。命令行覆盖也不能突破这些要求；出现冲突时，客户端会按要求处理并提示。受管理配置

权限 Profile 允许列表需要 Codex 0.138.0 或更高版本。该列表一旦存在，未列入或设为 false 的 Profile 都不可选；MCP 允许列表还会核对服务身份，不只核对名称。管理员要求与版本条件

配置不生效时，按这个顺序检查

1. 确认运行环境和文件位置。 核对 CODEX_HOME、用户配置路径及当前工作目录。
2. 检查 TOML 层级。 顶层字段有没有误写到上一张表中，同一张表是否重复声明。
3. 查找覆盖来源。 当前命令参数、项目配置和选中的 Profile 是否设置了相同字段。
4. 核对版本与可用能力。 模型选项、Beta 功能和第三方接口是否支持当前写法。
5. 查看管理限制。 用户配置正确时，也可能受到 requirements.toml 约束。

排查时保留一份配置副本，每次只调整与问题相关的一组字段。需要继续扩展时，可按名称查询完整配置参考，再对照官方示例确认 TOML 的放置层级。