Codex 配置教程：config.toml、审批模式与沙箱怎么设
装好 Codex CLI 以后，多数人第一次打开 ~/.codex/config.toml 是因为它又停下来问「能不能跑这条命令」，或者反过来，担心它一声不吭就把仓库改了。这两件事归同一组开关管：沙箱决定 Codex 技术上能碰什么，审批策略决定它什么时候要先问你。下面按 OpenAI 官方 Codex 文档（2026-10-31 北京时间查阅；npm 上 @openai/codex 当前版本 0.166.0）把配置文件放哪、谁覆盖谁、几种常用组合和容易踩的坑理一遍。
前置条件
- 已安装 Codex CLI 并登录（
npm i -g @openai/codex）。CLI、IDE 扩展和 ChatGPT 桌面端共用同一套配置层，改一处三个地方都生效。 - 项目最好在 git 里。官方建议先切功能分支、保持
git status干净再派活，出了问题好回滚。 - 公司电脑可能装了管理员下发的
requirements.toml，它可以直接禁掉approval_policy = "never"或danger-full-access。你本地怎么写都绕不过去。
第一步：搞清配置文件放哪、谁覆盖谁
个人默认值写在 ~/.codex/config.toml。只对某个仓库生效的设置放进仓库里的 .codex/config.toml，但这一层只在你信任该项目时才加载，不受信任的项目连项目级的 hooks 和 rules 都会跳过。
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1（最高） | 命令行参数和 -c / --config | 单次覆盖，适合临时试 |
| 2 | 项目 .codex/config.toml | 从项目根往当前目录逐层找，离得最近的赢；仅受信任项目 |
| 3 | --profile 名字 选中的 profile 文件 | 文件是 ~/.codex/名字.config.toml |
| 4 | ~/.codex/config.toml | 你的个人默认值 |
| 5 | 云端下发的工作区默认值 | 登录了企业工作区才有 |
| 6 | /etc/codex/config.toml | Unix 系统级，存在才读 |
| 7 | 内置默认值 | 什么都不写时的行为 |
官方建议这么分：公共默认值写进 config.toml，profile 文件只放和默认不同的那几项。IDE 扩展里点右上角齿轮，选 Codex Settings → Open config.toml，打开的是同一个文件。
第二步：沙箱和审批是两个开关
sandbox_mode 是硬边界，由操作系统强制执行：macOS 用 Seatbelt，Linux 默认用 bwrap 加 seccomp，Windows 优先用 MXC。可选值有三个：read-only、workspace-write、danger-full-access。approval_policy 决定越界时要不要先停下来问你，常用 on-request 和 never。
沙箱管「能不能做」，审批管「做之前问不问」。把审批关掉，沙箱照样拦着；把沙箱拆了，审批也救不回来。
官方给的四种常用组合：
| 用途 | 命令行写法 | 效果 |
|---|---|---|
| Auto（默认预设） | --sandbox workspace-write --ask-for-approval on-request | 工作区内读写、跑命令不用问；改工作区外文件或要联网时请求批准 |
| 只读浏览 | --sandbox read-only --ask-for-approval on-request | 只读，越界动作需要批准 |
| 只读 CI | --sandbox read-only --ask-for-approval never | 只读，从不询问，适合流水线 |
| 完全放开 | --yolo（即 --dangerously-bypass-approvals-and-sandbox） | 没有沙箱也没有审批，官方不推荐 |
写进配置文件，核心是中间两行：
# ~/.codex/config.toml
model = "gpt-6.1-sol"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
model_reasoning_effort = "medium"启动时 Codex 会看目录在不在版本控制里：在的话推荐 Auto，不在的话推荐 read-only。会话里用 /permissions 切模式，用 /status 看当前工作区包含哪些目录（当前目录和 /tmp 这类临时目录都算）。
就算在 workspace-write 下，可写目录里的 .git、.agents、.codex、.aws 仍然是只读的，而且递归生效。所以 Codex 能改代码，但改不了你的 git 元数据和它自己的配置。
第三步：常用组合存成 profile
不想每次敲一长串参数，就把组合存成 profile 文件，用 codex --profile 名字 调出来：
# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode = "read-only"想要介于 on-request 和 never 之间的行为，可以用 granular 写法，按类别决定哪些审批照常弹出、哪些直接拒绝。类别包括沙箱越界、execpolicy 规则、MCP 请求、request_permissions 和 Skill 脚本：
approval_policy = { granular = {
sandbox_approval = true,
rules = true,
mcp_elicitations = true,
request_permissions = false,
skill_approval = false
} }还有一个选项 approvals_reviewer = "auto_review"，把需要审批的请求先交给一个审查 Agent 判断。它会多花模型调用，计入用量。
第四步：只放开网络，再用白名单收紧
workspace-write 默认不让命令联网。装依赖、调接口时要单独打开：
[sandbox_workspace_write]
network_access = true这样放开后，去哪个域名都不拦。想只允许几个域名，再打开 network_proxy，光写域名规则不开代理是不起作用的：
[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }- 规则以白名单为先：
*.example.com只配子域名，**.example.com连主域一起配；deny永远压过allow。 - 默认
allow_local_binding = false，回环和内网地址都会被挡。要访问本机服务，单独加一条localhost或具体 IP 的 allow 规则。 - 这个代理只过滤沙箱里命令发出的流量，管不到 web search、MCP 连接和浏览器工具。
联网搜索另有开关 web_search，默认 "cached"，读的是 OpenAI 维护的预索引结果，不现抓网页，被提示词注入的面更小。要实时结果写 "live"（等同 --search），完全不要就写 "disabled"。用 --yolo 时默认会变成 live。
第五步：在 config.toml 里挂 MCP 服务器
最快的方式是命令行：codex mcp add context7 -- npx -y @upstash/context7-mcp，再用 codex mcp list 查看。它写进的也是 config.toml，想细调就直接编辑对应的表：
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45启动超时默认 10 秒，单次工具调用默认 60 秒。default_tools_approval_mode 可以是 auto、prompt、writes、approve，其中 writes 只对没标只读的工具弹审批。服务器带破坏性标注的工具，不管怎么配都要审批。MCP 本身是什么、和 Skill 怎么分工，见 MCP 入门。
常见坑
- 老配置里有
approval_policy = "untrusted"：这个值已退役，留着可能让 Codex 和 ChatGPT Work 都起不来。用户配置、项目配置、profile、启动脚本里都要删掉。想保留「每条命令都要批」的严格度，改成在用户配置里给项目标[projects."/path/to/project"] trust_level = "untrusted"，同时不要显式写approval_policy。 - 项目配置不生效：多半是项目没被信任，
.codex/整层被跳过。 - Docker 里沙箱报错：容器禁止命名空间、setuid
bwrap或seccomp时，Linux 沙箱建不起来。官方做法是让容器当隔离边界，在容器里用danger-full-access，只对可信仓库这么做。 - 环境变量里的密钥被带进命令：
[shell_environment_policy]的ignore_default_excludes默认是true，名字里含 KEY、SECRET、TOKEN 的变量不会被自动过滤。想自动过滤要设成false。 - WSL1：0.115 起 Linux 沙箱改用
bwrap，WSL1 不再支持，要用 WSL2。
想自己看某条命令在沙箱里会怎样，用 codex sandbox linux 命令（macOS 换成 macos，Windows 换成 windows）单独跑一次。
完成标准
- 打开
codex后/status显示的沙箱模式和审批策略，和你在config.toml里写的一致。 - 工作区内改文件不再弹窗，改工作区外文件或联网时会先问你。
- 配置里没有
untrusted审批值；需要联网的项目只放行了用得到的域名。 codex mcp list能看到你挂的服务器。
最后
先用默认的 Auto 跑一周，把真正被拦下来的动作记下来，再针对这几项放开，比一上来就 --yolo 稳得多。多个 Codex 并行干活时，上下文怎么分，可以接着看 子 Agent 该不该继承上下文。
