05 · Codex 为什么需要审批和沙箱

⏱️ 预计阅读 13 分钟 ｜ 🎯 目标：让 Codex「能动手」之前，先把"动手范围"框出来

上一篇讲了用 AGENTS.md 让 Codex 知道怎么干活。 这一篇讲一对互补又必需的安全控制：sandbox（沙箱，技术边界） 和 approval（审批，决策边界）。 这是 Codex 从"能跑"到"能放心跑"的最后一道工程门。

🎬 一个真实事故剧本

想象 Codex 没有边界，会发生什么？

⚠️ 这些不是 AI 故意作恶，是它没有"边界感"。 Agent 的能力越强，误操作的破坏力也越大。所以 Codex 不能只学会「干活」，必须学会「在边界里干活」。

🛡️ 拆开看：sandbox 管「能不能做」，approval 管「要不要问你」

新手常把这两个词混着用，其实它们各管一件事，缺一个都不行 ——

先看 Codex 想做一件事时的完整流程：

flowchart TD
    Start["🤖 Codex 想做某动作<br/>例如 rm -rf 文件 / 装新依赖"]
    Q1{"📦 Sandbox 检查<br/>这个动作在允许范围内吗"}
    Run["✅ 直接执行"]
    Q2{"✋ Approval 检查<br/>需要问你一下吗"}
    Ask["🛑 弹窗 — Codex 想做 X<br/>同意 / 拒绝"]
    Block["❌ 直接拒绝<br/>不打扰你"]
    Done["✅ 执行"]
    Cancel["⏸ 任务暂停<br/>等 Codex 换方案"]

    Start --> Q1
    Q1 -->|在范围内| Run
    Q1 -->|越界了| Q2
    Q2 -->|on-request 默认| Ask
    Q2 -->|never| Block
    Ask -->|你点允许| Done
    Ask -->|你点拒绝| Cancel

    style Q1 fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Q2 fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Run fill:#dcfce7,stroke:#22c55e
    style Done fill:#dcfce7,stroke:#22c55e
    style Block fill:#fee2e2,stroke:#ef4444
    style Cancel fill:#fee2e2,stroke:#ef4444

🎯 怎么读这张图：从上往下看 ——

• 🔵 蓝色菱形是 Sandbox 在检查（这事能不能做）
• 🟡 黄色菱形是 Approval 在检查（这事要不要问你）
• 🟢 绿色 = 允许通过；🔴 红色 = 被拦下

💡 核心区分：

• Sandbox 不在则失控，Approval 不在则烦人
• 二者互补不替代：Sandbox 定义"墙"，Approval 决定"门"什么时候开

📦 Sandbox 三档模式：技术边界

Codex 的 sandbox_mode 配置项有三档（在 config.toml 里设）：

📖 来源：OpenAI · Sandbox concepts、Configuration Reference

🔐 受保护路径：即使 workspace-write 也不能动

即使开了 workspace-write，下面的路径强制只读（防止 Codex 误改基础设施）：

`<工作区根>`/
├── .git/              ← 🔒 只读（git 历史不能被 Agent 直接改）
├── .agents/           ← 🔒 只读（Agent 配置不能被 Agent 改）
└── .codex/            ← 🔒 只读（Codex 自身配置不能被 Codex 改）

💡 设计巧思：这三个目录是 Agent 自己的"宿舍"。让 Agent 改自己的宿舍 = 让小偷管自己的家门钥匙。

✋ Approval 四种策略：决策边界

approval_policy 配置项决定越界时怎么办：

flowchart TD
    Action["🤖 Codex 想做某动作"]
    Sandbox{"📦 sandbox<br/>能直接做吗?"}
    Policy{"✋ approval_policy<br/>是哪种?"}

    Action --> Sandbox
    Sandbox -->|是| Direct["✅ 直接执行"]
    Sandbox -->|否| Policy

    Policy -->|"untrusted<br/>(凡事都问)"| AskAll["🛑 任何越界都问"]
    Policy -->|"on-request ⭐<br/>(默认)"| AskWhen["🛑 越界时问"]
    Policy -->|"never<br/>(从不问)"| Block["❌ 直接拒绝越界<br/>不打扰你"]
    Policy -->|"granular<br/>(细粒度)"| Custom["⚙️ 按动作类别决定<br/>有的问、有的拒"]

    style AskWhen fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Block fill:#fee2e2,stroke:#ef4444

📖 来源：Agent approvals & security

⭐ Auto preset（推荐组合）

官方推荐的"低摩擦默认"组合 = workspace-write + on-request：

# ~/.codex/config.toml 或项目 .codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

实际效果：

• ✅ workspace 内改文件 / 跑测试 / 跑构建 → 自动
• 🛑 改 workspace 外的文件 → 问你
• 🛑 联网（如 curl / npm install）→ 问你
• 🛑 跑高危命令（rm -rf / sudo）→ 问你

💡 新手就用这个组合。等熟悉 Codex 行为后再调整。

🌐 网络访问：默认关闭

flowchart LR
    A["🤖 Codex 想联网"]
    B{"📦 sandbox 允许吗?"}

    A --> B
    B -->|"workspace-write 默认: ❌"| Stop["🛑 拦下，等审批"]
    B -->|"显式开了网络"| C{"⚙️ 域名白名单?"}
    C -->|无白名单| All["🌐 任意域名"]
    C -->|有白名单| Allow["🟢 仅允许列表内域名"]
    C -->|命中拒绝列表| Deny["❌ 拒绝"]

    style Stop fill:#fef3c7,stroke:#f59e0b

关键事实：

• 🌐 默认 workspace-write 模式关闭网络（只能本机文件操作）
• 🌐 Codex Cloud 有两阶段：setup 阶段可联网装依赖 → agent 阶段默认离线
• 🌐 启用网络后可配 域名白名单 / 黑名单：

  [sandbox_workspace_write.network]
  "github.com" = "allow"
  "*.openai.com" = "allow"
  "*.tracker.com" = "deny"

• 🔍 Web search：默认走 OpenAI 维护的缓存索引，不直连任意网站 —— 减少 prompt injection（提示词注入攻击）暴露面

⚖️ 风险矩阵：哪些动作高危

并非所有"越界"都同等危险。给个风险矩阵帮你决策：

💡 判断口诀：

1. 可逆吗？ 不可逆 → 高风险（删除、强推、生产 migration）
2. 影响别人吗？ 影响多人 → 高风险（main 分支、共享资源）
3. 碰到钱 / 权限了吗？ → 永远不让 Codex 自动干

🎯 推荐配置：3 种典型场景

不同场景配不同档。直接抄配置：

场景 ① · 学习 / 探索陌生项目

目标：只让它读、不让它改

# ~/.codex/config.toml
sandbox_mode = "read-only"
approval_policy = "on-request"

➡️ Codex 只能读文件、跑只读命令；想改东西必须先来问你。

场景 ② · 日常开发（推荐 ⭐）

目标：Auto preset · 低摩擦 + 安全平衡

sandbox_mode = "workspace-write"
approval_policy = "on-request"

➡️ workspace 内自由动手，越界（改外部文件 / 联网 / 高危命令）才问。

场景 ③ · 自动化任务（CI / 后台批跑）

目标：别等审批弹窗，直接拒绝越界

sandbox_mode = "workspace-write"
approval_policy = "never"

[sandbox_workspace_write.network]
"npm.registry.com" = "allow"
"github.com" = "allow"

➡️ 越界直接拒（不会卡审批）；明确白名单允许必要的网络。

⚠️ never 一定要配明确的白名单，否则任务会因为缺权限直接失败。

🚫 常见误解 → ✅ 正确理解

🔍 想再深一层（点击展开）

# 部署到员工机器上的 requirements.toml（员工无权改）
[disallow]
approval_policy = ["never"]              # 禁止"从不询问"模式
sandbox_mode = ["danger-full-access"]    # 禁止全权限模式

# ~/.codex/config.toml 完整示例

# ============= 沙箱模式 =============
# read-only / workspace-write / danger-full-access
sandbox_mode = "workspace-write"

# ============= 审批策略 =============
# untrusted / on-request / never / granular
approval_policy = "on-request"

# ============= 工作区配置 =============
[sandbox_workspace_write]
# 允许写入的根目录（默认是项目根）
writable_roots = ["~/projects/my-app"]
# 是否允许跑常规本地命令（默认 true）
allow_local_commands = true

# ============= 网络配置 =============
[sandbox_workspace_write.network]
# 默认全部禁；按域名开
"github.com" = "allow"
"registry.npmjs.org" = "allow"
"*.openai.com" = "allow"
"*.tracker.com" = "deny"

# ============= 细粒度审批（高级）=============
[approval_policy.granular]
network_call = "ask"            # 联网每次问
high_risk_command = "ask"       # rm -rf 之类问
file_outside_workspace = "deny" # 工作区外的写直接拒

📝 本章自检

✅ 过关标准：能用一句话说清 —— "Sandbox 是墙，Approval 是门。墙定边界，门管什么时候开。"

📚 下一篇

• ➡️ 06 · App、IDE、CLI、Cloud 怎么选 —— 不同入口对应什么工作面
• 📖 设置审批和安全边界
• 📦 理解沙箱边界
• ⚙️ 配置 Codex 基础选项