Codex 审批与安全
本文是对 OpenAI 官方文档 Agent approvals & security 的中文整理版，目标是用更短的路径讲清三件事：
- Codex 的安全模型是什么
- 文档里提到的可配置项有哪些
- 日常怎么选更合适的组合
先看结论
这篇文档的核心只有两层：
sandbox_mode决定技术上能做什么approval_policy决定什么时候必须先问人
一句话记忆：
sandbox_mode管边界approval_policy管是否弹审批
安全模型
Codex 的安全控制由两部分组成：
| 维度 | 作用 | 典型影响 |
|---|---|---|
sandbox_mode | 限制进程能访问的文件、目录和网络 | 能不能写工作区外、能不能联网、有没有系统级隔离 |
approval_policy | 控制哪些动作必须暂停并请求人工批准 | 是否对越界操作、网络访问、不受信任命令弹审批 |
补充两点：
- App/MCP 工具即使不是 shell 命令，只要带副作用或 destructive annotation，也可能触发审批
- 本地 CLI / IDE extension 使用的是操作系统级沙箱能力，不是单纯靠应用层自觉限制
运行环境差异
Codex Cloud
- 运行在 OpenAI 托管的隔离容器里
setup阶段可以联网安装依赖agent阶段默认离线，除非显式开启互联网访问- secrets 只在
setup阶段可用，进入agent阶段前会被移除
Codex CLI / IDE Extension
- 依赖操作系统级沙箱
- 默认语义接近“工作区内可写、默认不联网”
- 可以通过配置或启动参数调整沙箱、审批和网络策略
默认行为
文档对本地运行的推荐是：
- 版本控制目录：推荐
Auto - 非版本控制目录：推荐
read-only - 某些环境下，未显式信任的目录会先以
read-only启动 - 工作区可能不只当前目录，也可能包括
/tmp
常见启动方式：
codex
codex --sandbox workspace-write --ask-for-approval on-request
codex --sandbox read-only --ask-for-approval on-request
其中：
Auto本质上接近workspace-write + on-request--ask-for-approval on-failure已被标记为 deprecated
先理解两个核心值
sandbox_mode
| 值 | 含义 | 适合什么场景 |
|---|---|---|
"read-only" | 只读，不能改 | 浏览、问答、只读检查 |
"workspace-write" | 可在工作区内写，网络默认关闭 | 本地日常开发 |
"danger-full-access" | 不再使用 Codex 的沙箱限制 | 只适合已做额外隔离的高风险环境 |
注意：
danger-full-access只表示“无沙箱”- 它不自动等于“无审批”
approval_policy
| 值 | 原文语义 | 直白理解 |
|---|---|---|
"untrusted" | 已知安全的读操作自动放行，不受信任命令需要审批 | 尽量自动读，危险命令先问 |
"on-request" | 先在当前沙箱内自动工作，越出沙箱、联网或需要额外权限时审批 | 默认先执行，越界再问 |
"never" | 不弹审批，只在当前配置允许的边界内尽力执行 | 不问你，但仍受沙箱限制 |
再强调一次：
read-only + never仍然是只读- 更接近“完全放开”的组合是
danger-full-access + never
--yolo / --dangerously-bypass-approvals-and-sandbox
这是 CLI 的高风险快捷参数，含义是：
- 无沙箱
- 无审批
它和 danger-full-access 不是一回事：
danger-full-access：无沙箱--yolo/--dangerously-bypass-approvals-and-sandbox：无沙箱 + 无审批
配置索引
下面按类别汇总文档中提到的配置项，尽量不遗漏。
1. 核心配置
| 属性/参数 | 可选值/示例 | 位置 | 说明 |
|---|---|---|---|
sandbox_mode | "read-only" / "workspace-write" / "danger-full-access" | config.toml | 定义沙箱级别 |
approval_policy | "untrusted" / "on-request" / "never" / { granular = { ... } } | config.toml | 定义审批策略 |
allow_login_shell | false | config.toml | 可选加固项，禁止 shell 类工具使用 login shell |
--sandbox, -s | read-only / workspace-write / danger-full-access | CLI | 覆盖本次运行的沙箱策略 |
--ask-for-approval, -a | untrusted / on-request / never | CLI | 覆盖本次运行的审批策略 |
--full-auto | 布尔参数 | CLI | 等价于 workspace-write + on-request |
--dangerously-bypass-approvals-and-sandbox | 布尔参数 | CLI | 关闭沙箱并关闭审批 |
--yolo | 布尔参数 | CLI | 上一个参数的别名 |
2. 颗粒化审批
approval_policy = { granular = {
sandbox_approval = true,
rules = true,
mcp_elicitations = true,
request_permissions = false,
skill_approval = false
} }
| 属性 | 可选值 | 说明 |
|---|---|---|
approval_policy.granular.sandbox_approval | true / false | 是否对越出沙箱类动作继续审批 |
approval_policy.granular.rules | true / false | 是否对规则触发类审批继续交互 |
approval_policy.granular.mcp_elicitations | true / false | 是否对 MCP elicitations 继续交互 |
approval_policy.granular.request_permissions | true / false | 是否对 request_permissions 继续交互 |
approval_policy.granular.skill_approval | true / false | 是否对 skill 脚本审批继续交互 |
原文意思可以概括成：
- 保留你想要的审批类型
- 其他审批类型可以自动拒绝或不再交互
3. 网络与 Web Search
| 属性/参数 | 可选值/示例 | 位置 | 说明 |
|---|---|---|---|
[sandbox_workspace_write].network_access | true / false | config.toml | 控制 workspace-write 模式下是否允许网络访问 |
web_search | "cached" / "disabled" / "live" | config.toml | 控制 Web Search 模式 |
--search | 布尔参数 | CLI | 把 web_search 切到 "live" |
要点：
- 网络默认关闭
web_search = "cached"是默认值cached风险低于live，但结果仍应视为不可信输入- 只启用 Web Search，不一定等于给 shell 命令完整网络权限
4. Profile
| 属性/参数 | 可选值/示例 | 位置 | 说明 |
|---|---|---|---|
[profiles.<name>] | 如 full_auto、readonly_quiet | config.toml | 定义命名配置档 |
[profiles.<name>].approval_policy | 同上 | config.toml | 该 profile 的审批策略 |
[profiles.<name>].sandbox_mode | 同上 | config.toml | 该 profile 的沙箱模式 |
--profile <name> | 如 --profile full_auto | CLI | 选择某个 profile |
文档示例：
[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[profiles.readonly_quiet]
approval_policy = "never"
sandbox_mode = "read-only"
常见组合
| 场景 | 推荐参数 | 含义 |
|---|---|---|
Auto | 默认启动或 --full-auto | 工作区可读写，越界写入或联网时审批 |
| 安全只读浏览 | --sandbox read-only --ask-for-approval on-request | 能读文件，改文件/运行命令/联网都要审批 |
| 只读非交互 | --sandbox read-only --ask-for-approval never | 只能读，不会弹审批 |
| 自动编辑但保守 | --sandbox workspace-write --ask-for-approval untrusted | 可读写，但不受信任命令先审批 |
| 高风险完全放开 | --dangerously-bypass-approvals-and-sandbox | 无沙箱、无审批，不建议 |
最高权限示例
如果你就是要“无沙箱、无审批”，可以用下面两种方式。
CLI 启动方式：
codex --dangerously-bypass-approvals-and-sandbox
或：
codex --yolo
配置文件方式：
approval_policy = "never"
sandbox_mode = "danger-full-access"
这两种写法表达的目标一致：
- 不再弹审批
- 不再使用 Codex 的沙箱限制
区别是：
- CLI 参数只对当前启动生效
config.toml会作为默认行为持续生效
这属于文档里的最高风险模式，只适合你已经通过外部环境自行做过额外隔离的场景。
受保护路径
即使是 workspace-write，下面这些路径也仍然是只读：
<writable_root>/.git- 若
.git是指针文件，则其解析后的真实 Git 目录 <writable_root>/.agents<writable_root>/.codex
这些保护是递归生效的。
平台实现
| 平台 | 实现方式 |
|---|---|
| macOS | sandbox-exec + Seatbelt policy |
| Linux | bubblewrap + seccomp |
| Windows | WSL 下复用 Linux；原生 Windows 用独立实现 |
补充：
- Linux 某些环境下可启用
use_legacy_landlock - 托管代理模式下，默认通过 proxy-only bridge 出网
- 如果 Docker 环境不支持所需的
Landlock或seccomp，官方建议由容器自身提供隔离，再在容器内用--sandbox danger-full-access
本地测试沙箱
# macOS
codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--full-auto] [COMMAND]...
补充命令：
codex sandbox也可写成codex debug- 还有别名
codex sandbox seatbelt与codex sandbox landlock
版本控制建议
文档建议把 Codex 放进正常 Git 工作流里：
- 使用 feature branch
- 委托任务前尽量保持
git status干净 - 优先用
git diff/git apply一类 patch 工作流 - 小步提交，方便回滚
- 把 Codex 产出当普通 PR 一样审查
安全建议
- 默认不要开网络，除非确实需要
- 即使是 Web Search 缓存结果，也不要当成可信输入
log_user_prompt优先保持false- 工具参数和工具输出都应视为敏感数据
- 遥测最好只导出到你自己控制的 collector
- 定期审查审批策略、沙箱变更和异常工具执行
推荐起步配置
如果你只是想要一套“本地好用、又不算太冒险”的起步配置，可以从下面开始：
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
[sandbox_workspace_write]
network_access = false
[otel]
environment = "staging"
exporter = "none"
log_user_prompt = false
这套配置的含义是：
- 默认允许在工作区内自动工作
- 越界、联网或高风险动作时再审批
- 网络默认关闭
- 搜索默认走缓存
- 遥测默认不外发，prompt 默认不记录