核心概念精讲：Prompting、Sandboxing 与 Approval

Codex 不是一个被动的代码补全工具——它是一个自主编码智能体。要驾驭这个智能体，你需要理解三个基石概念：Prompting（如何下达指令）、Sandboxing（智能体的技术边界在哪里）、Approval（何时需要人类确认）。三者协同构成了 Codex 的 "自主性-安全性" 平衡框架。

本篇核心收获：

• 掌握 Codex 提示词的结构化写法：目标、上下文、约束、输出格式
• 理解沙箱的三种模式及其平台原生实现机制
• 掌握审批策略的三档行为差异与运行时切换
• 理解 Rules 的命令级精细控制能力
• 建立「沙箱定义边界 + 审批控制暂停」的协同心智模型

一、Prompting：与 Codex 智能体对话的艺术

Codex 的工作模式是一个循环：接收提示词 → 调用模型 → 执行动作（读文件、编辑代码、运行命令）→ 观察结果 → 继续循环，直到任务完成或被取消。提示词的质量直接决定了这个循环的效率和准确性。

1.1 高质量提示词的结构

官方 Codex Prompting Guide（Cookbook）提炼了一个经过内部评估优化的提示词结构：

1.2 任务分解策略

Codex 处理复杂任务的能力远超简单补全，但仍然遵循 "小任务优于大任务" 的原则：

• 可验证性：包含复现步骤、验证方式、lint/pre-commit 检查指令，让 Codex 能自我验证
• 渐进式分解：不确定怎么拆？先问 Codex："分析这个需求，给我一个分步实现计划"
• 并行化思维：Codex 支持多线程并行工作（尤其是 Codex App），读密集型任务可以拆成多个独立线程

# ❌ 模糊的大任务
"重构整个认证模块"

# ✅ 分步的小任务
"Step 1: 将 AuthService 中的 JWT 生成逻辑抽取到 JwtTokenProvider 类
 Step 2: 添加 Token 刷新端点 POST /api/auth/refresh
 Step 3: 为新端点编写集成测试，覆盖过期 Token 和无效 Token 场景"

1.3 上下文管理

Codex 的所有信息必须装入模型的上下文窗口内。窗口大小因模型而异，Codex 会监控并报告剩余空间。

• 手动上下文：在提示词中引用相关文件和图片。IDE 扩展会自动包含打开的文件列表和选中的文本范围
• 自动上下文：Codex 在工作过程中会自动收集文件内容、工具输出，以及已完成/待完成事项的记录
• Compaction（上下文压缩）：长时间任务中，Codex 会自动通过摘要压缩上下文，丢弃不相关的细节。通过反复压缩，Codex 可以在多步骤复杂任务上持续工作数小时

1.4 图片输入：从截图到代码

Codex 支持多模态输入——你可以在提示词中附加截图、设计稿、UI 原型图，实现 "视觉到代码" 的工作流。

使用方式：

• CLI：codex -i screenshot.png "按照这个截图实现页面"
• IDE 扩展：在 Chat 面板中拖拽或粘贴图片
• Codex App：直接在输入框中粘贴图片

典型场景：

• 将 Figma 设计稿截图转换为前端组件代码
• 提供 Bug 截图，让 Codex 定位并修复 UI 问题
• 附加架构图，让 Codex 理解系统拓扑后生成代码

1.5 Web 搜索：cached vs live

Codex 内置了 Web 搜索工具，默认在本地任务中启用。搜索结果可以帮助 Codex 查阅 API 文档、了解框架用法、获取最新信息。

配置方式：

# config.toml
web_search = "cached"    # 默认值
# web_search = "live"    # 等同 --search
# web_search = "disabled"

二、Sandboxing：智能体的技术边界

沙箱是让 Codex 能够自主工作的前提——它定义了一个受约束的执行环境，Codex 可以在边界内自由行动，而不需要每一步都停下来请求确认。

2.1 沙箱的本质

沙箱作用于 Codex 派生的所有子进程，不仅限于 Codex 自身的文件操作。当 Codex 运行 git、包管理器、测试框架等工具时，这些命令都继承相同的沙箱边界。

核心思想：在明确的限制内给予智能体自主权。你不是在信任智能体的意图，而是在信任它运行在强制执行的限制之内。

2.2 三种沙箱模式

workspace-write 模式的保护路径：

即使在默认的 workspace-write 模式下，以下路径始终被保护为只读：

• <workspace>/.git（无论是目录还是 gitdir 指针文件，解析后的 Git 目录也受保护）
• <workspace>/.agents
• <workspace>/.codex
• 保护是递归的——上述路径下的所有内容都不可写

2.3 平台原生实现

Codex 在每个操作系统上使用原生的安全机制来强制执行沙箱策略，而不是简单的软件层模拟：

2.4 writable_roots：扩展可写范围

当 Codex 需要访问工作区之外的目录时（例如共享库路径、monorepo 的其他包），可以通过 writable_roots 扩展可写范围，而不需要移除整个沙箱：

[sandbox_workspace_write]
writable_roots = [
    "/home/user/shared-libs",
    "/opt/project/packages/common"
]

这比直接切换到 danger-full-access 安全得多——你精确控制了额外开放的路径。

2.5 network_access：网络访问控制

默认情况下，workspace-write 模式关闭网络访问。需要时（如 npm install、pip install），Codex 会通过审批流程请求网络权限。

如果你的工作流频繁需要网络（如持续安装依赖），可以在配置中显式开启：

[sandbox_workspace_write]
network_access = true

Codex Cloud 的网络模型不同：

云端环境使用两阶段模型——Setup 阶段可以访问网络（安装依赖），Agent 阶段默认离线。Secrets 仅在 Setup 阶段可用，Agent 阶段开始前被清除。

三、Approval Policy：何时暂停，何时放行

审批策略决定了 Codex 在遇到沙箱边界时的行为：是自动尝试、请求确认，还是直接失败。

3.1 三档审批策略

常见组合速查：

3.2 /permissions：运行时切换

你不需要重启 Codex 就能改变权限级别。在 CLI 会话中使用 /permissions 命令即可实时切换：

• Codex App 和 IDE 扩展中，权限选择器位于输入框下方
• CLI 中使用 /permissions 切换模式
• /status 可以查看当前工作区包含哪些目录

Codex 的智能推荐：

• 版本控制项目：启动时推荐 Auto（workspace-write + on-request）
• 非版本控制目录：启动时推荐 read-only
• 某些场景下，Codex 会以 read-only 启动，直到你通过 /permissions 显式信任工作目录

3.3 Granular Approval：精细化审批

除了三档全局策略，Codex 还支持颗粒化审批，让你对不同类型的审批分别控制：

approval_policy = { granular = {
    sandbox_approval = true,       # 沙箱越界：交互式审批
    rules = true,                  # Rules 匹配：交互式审批
    mcp_elicitations = true,       # MCP 工具调用：交互式审批
    request_permissions = false,   # 权限请求：自动拒绝
    skill_approval = false         # Skill 脚本：自动拒绝
}}

3.4 MCP 与 App 工具的审批

Codex 的审批不仅限于 Shell 命令。对于 MCP 服务器和 App 连接器的工具调用：

• 标记为有副作用的工具调用会触发审批
• 标记为 destructive 的工具调用始终需要审批，即使同时标记了 read-only

四、Rules：命令级的精细控制

当沙箱和审批策略的粒度不够时，Rules 提供了命令前缀级别的 allow / prompt / forbid 控制。

4.1 Rules 文件格式

Rules 使用 Starlark 语法（类 Python，但无副作用），文件位于 .codex/rules/ 目录下：

# ~/.codex/rules/default.rules
​
# 允许 git status 和 git diff 自动执行
prefix_rule(
    pattern = ["git", ["status", "diff"]],
    decision = "allow",
    justification = "Safe read-only git commands",
)
​
# 运行 npm publish 前必须确认
prefix_rule(
    pattern = ["npm", "publish"],
    decision = "prompt",
    justification = "Publishing to npm registry requires review",
)
​
# 禁止执行 rm -rf
prefix_rule(
    pattern = ["rm", "-rf"],
    decision = "forbidden",
    justification = "Dangerous: use git clean instead",
    match = ["rm -rf /tmp/build", "rm -rf node_modules"],
)

4.2 决策优先级

当多条 Rules 同时匹配一个命令时，Codex 采用最严格优先原则：

forbidden > prompt > allow

这意味着即使你 allow 了 git add，如果另一条 rule forbid 了出现在同一 bash -lc 调用中的 rm -rf /，整个调用仍会被拒绝。

4.3 Shell 复合命令的安全处理

Codex 对 bash -lc "git add . && rm -rf /" 这类复合命令有特殊处理：

• 可安全拆分时（仅包含纯文字、&&、||、;、|）：Codex 使用 tree-sitter 解析，拆分为独立命令分别评估
• 不可安全拆分时（包含重定向、变量替换、通配符、控制流）：整个调用作为一条命令评估

这防止了危险命令藏在安全命令后面偷偷执行。

4.4 Smart Approvals

当 Smart Approvals 启用时（默认开启），Codex 会在你遇到需要审批的命令时自动建议一条 prefix_rule。审查并接受后，该规则会写入 ~/.codex/rules/default.rules，后续同类命令自动放行。

4.5 测试 Rules

# 测试一条规则如何应用于特定命令
codex execpolicy check --pretty \\
    --rules ~/.codex/rules/default.rules \\
    -- gh pr view 7888 --json title,body,comments

输出 JSON 格式的匹配结果，包含最严格的决策和所有匹配规则的 justification。

五、三者协同：Codex 的自主性-安全性框架

理解了三个概念之后，最关键的是理解它们如何协同工作：

协同逻辑总结：

1. Sandboxing 定义技术边界——Codex 能触碰什么（文件、网络、目录）
2. Approval Policy 定义暂停时机——越界时是自动处理、请求确认还是直接失败
3. Rules 提供精细例外——在全局策略之上，对特定命令单独放行或禁止
4. Prompting 驱动整个循环——高质量的提示词减少越界需求，让智能体在沙箱内就能完成更多工作

参考文档

• Prompting — Codex 官方文档
• Sandboxing — Codex 官方文档
• Agent Approvals & Security — Codex 官方文档
• Rules — Codex 官方文档
• Codex Prompting Guide — Cookbook
• Config Basics — Codex 官方文档
• Advanced Configuration — Codex 官方文档