深色模式
Codex 配置
概述
Codex 的配置不只是一份 config.toml。真正会影响行为的，至少有三层：
~/.codex/config.toml和项目内的.codex/config.tomlAGENTS.md指令链- MCP、profile、审批与沙箱这些附加配置
如果把这些东西全塞进一个文件，很快就会乱。比较稳的做法是先分清职责：哪些属于客户端行为，哪些属于项目指令，哪些属于工具接入。
本文基于 2026 年 4 月 2 日查阅的 OpenAI 官方 Codex 文档整理，重点放在本地 CLI 和 IDE 共用的配置链，不展开 Codex cloud 环境配置。
先分清两类配置
客户端配置：config.toml
Codex 的用户级配置文件默认在：
text
~/.codex/config.toml项目级配置文件则放在仓库里的：
text
.codex/config.tomlOpenAI 官方文档明确说明，CLI 和 IDE extension 共用这套配置层。也就是说，模型、审批、沙箱、MCP 这些设置，不需要在两个客户端里各写一遍。
项目指令：AGENTS.md
AGENTS.md 不属于客户端参数配置，而是给 Codex 的长期项目说明。
更适合放进去的内容通常是：
- 仓库结构
- 测试命令
- 哪些目录不要碰
- 团队约束
- 提交和评审习惯
一句话区分：
config.toml控制 Codex 怎么运行AGENTS.md控制 Codex 在这个项目里该怎么做事
配置是怎么叠加生效的
官方文档当前给出的优先级，从高到低是：
- CLI flags 和
--config临时覆盖 --profile <name>选中的 profile- 项目内
.codex/config.toml - 用户级
~/.codex/config.toml - 系统级配置
- 内置默认值
这条顺序很重要，因为它决定了两个实际结论：
- 团队共享默认值，应该尽量放到项目内
.codex/config.toml - 一次性实验，不要回去改全局文件，直接用命令行覆盖更干净
另一个容易忽略的点是：项目级 .codex/config.toml 只会在受信任项目中加载。项目被标记为 untrusted 时，Codex 会跳过项目作用域配置，回退到用户级和默认值。
常改的几个配置项
默认模型
官方 sample config 里的推荐示例当前是：
toml
model = "gpt-5.4"
model_provider = "openai"如果团队已经接了代理或自定义提供方，也可以继续改 model_provider，但大多数个人使用场景里，先保持 openai 就够了。
审批策略：approval_policy
最常见的值有三个：
untrustedon-requestnever
官方文档里最常见的推荐示例是：
toml
approval_policy = "on-request"这个值比较均衡。能自动做一部分事，但碰到越界动作时还会停下来问你。
沙箱级别：sandbox_mode
这个配置决定 Codex 执行命令时的技术边界。常见值有：
read-onlyworkspace-writedanger-full-access
例如：
toml
sandbox_mode = "workspace-write"如果只是做审阅、解释和方案整理，read-only 更稳。如果需要在工作区里改文件并跑命令，workspace-write 才是日常主力。danger-full-access 留给你非常确定的场景，不适合默认开着。
workspace-write 的附加设置
当 sandbox_mode = "workspace-write" 时，还可以继续细化：
toml
[sandbox_workspace_write]
writable_roots = []
network_access = false这两个字段最关键：
writable_roots：额外可写目录network_access：是否允许联网
官方安全文档当前明确写到，本地 Codex 默认网络关闭。只要不是明确需要联网，先维持 false 更省事。
Web 搜索模式
Codex 当前支持：
cachedlivedisabled
例如：
toml
web_search = "cached"官方文档把 cached 作为默认值。它走的是 OpenAI 维护的缓存索引，而不是直接抓取实时网页。安全面上会稳一些，也更适合默认配置。
推理强度和风格
如果你想把表达风格和推理强度固定下来，也可以放进配置：
toml
model_reasoning_effort = "high"
# personality = "pragmatic"官方 sample config 当前把 personality 的可选值写成：
nonefriendlypragmatic
对 coding agent 来说，pragmatic 通常比较贴近日常开发心智。
Profiles 适合存“工作模式”
如果你经常在“轻量改动”和“深度审查”之间切换，profile 很有用。
官方 advanced config 文档当前给出的思路是，在 config.toml 里定义：
toml
[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"然后这样调用：
sh
codex --profile deep-review需要注意两点：
- profiles 目前还是 experimental
- 官方文档当前说明 profiles 还不支持 Codex IDE extension
所以它更适合 CLI 重度用户。
AGENTS.md 怎么组织更稳
OpenAI 官方文档当前说明，Codex 在开工前会先读 AGENTS.md。它的发现顺序大致是：
- 先看
~/.codex/AGENTS.override.md或~/.codex/AGENTS.md - 再从项目根往当前目录一路向下找
AGENTS.md - 越靠近当前目录的文件，越能覆盖前面的指导
一个更稳的用法是这样分层：
- 全局
~/.codex/AGENTS.md：个人习惯 - 仓库根
AGENTS.md：团队规则 - 子目录
AGENTS.md：模块级补充约束
别把模型参数塞进 AGENTS.md，也别把测试命令塞进 config.toml。分层清楚以后，排查“为什么 Codex 这么做”会轻松很多。
MCP 配置也走 config.toml
Codex 的 MCP 配置也是 config.toml 的一部分，而且 CLI 和 IDE extension 共享。
用 CLI 添加
官方 MCP 文档当前给出的通用形式是：
sh
codex mcp add <server-name> --env VAR1=VALUE1 -- <stdio server-command>例如：
sh
codex mcp add context7 -- npx -y @upstash/context7-mcp直接写配置文件
如果需要更细控制，可以直接写：
toml
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"MCP server 常见字段包括：
command、args、envurlbearer_token_env_varenabled_tools、disabled_toolsstartup_timeout_sec、tool_timeout_sec
如果你既用 CLI 又用 IDE，这种共用配置的好处很直接：接一次就够了。
一份够用的本地起步配置
如果只是先把本地工作流跑顺，通常不需要一份很长的 config.toml。下面这种就够了：
toml
model = "gpt-5.4"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
# personality = "pragmatic"
[sandbox_workspace_write]
network_access = false
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"然后把项目约束写进仓库根目录的 AGENTS.md。这两层分开，后面不管是加 MCP、加 profiles，还是切模型，都比较顺。