Codex Sandbox 模式实战指南：让 AI 自动执行代码也能安全可控

引言

在日常使用 AI 编程助手时，一个绕不开的痛点就是安全性——当 AI 建议执行一段 Shell 命令或脚本时，你永远不知道它会不会意外删除重要文件、修改系统配置，甚至访问不该访问的网络资源。Codex CLI 提供的 Sandbox（沙箱）模式正是为了解决这个问题而设计的，它能让 AI 生成的代码在一个隔离的环境中运行，既保护了你的开发环境，又不会限制 AI 的能力发挥。

本文将深入讲解 Codex Sandbox 模式的配置方法、不同隔离级别的适用场景，以及如何将沙箱模式融入日常开发工作流。

什么是 Sandbox 模式

Sandbox 模式的核心理念很简单：让 AI 代码在一个受限的容器内执行，隔离文件系统、网络和进程空间。Codex 通过 Docker 容器来实现这套隔离机制，当沙箱启用时，所有 AI 自动执行的命令都会被限制在容器的边界内。

Codex 提供了三个层级的沙箱隔离：

| 级别 | 说明 | 适用场景 |
|------|------|----------|
| workspace | 仅隔离到工作目录，可访问本地文件系统 | 日常开发、代码重构 |
| container | 使用 Docker 容器完全隔离 | 运行第三方脚本、测试未知代码 |
| strict | 最严格的隔离，无网络无持久化 | 运行不受信任的代码 |

配置 Sandbox 模式

全局配置（codex.json）

在项目根目录的 codex.json 中配置沙箱行为：

{
  "sandbox": {
    "mode": "container",
    "image": "node:20-alpine",
    "workspace_mount": true,
    "network": "none",
    "read_only": false,
    "tmpfs": true
  }
}

各配置项的含义：

• mode：沙箱模式，可选 workspace、container、strict
• image：Docker 镜像，仅在 container 模式下有效
• workspace_mount：是否将项目目录挂载进容器（true 时 AI 可读写项目文件，false 时完全隔离）
• network：网络策略，none 为完全断网，host 为共享主机网络
• read_only：是否以只读方式挂载，防止 AI 修改源码
• tmpfs：是否使用内存文件系统，容器销毁后数据不保留

通过 AGENTS.md 按任务配置

你也可以在 AGENTS.md 中针对特定任务指定沙箱规则：

# 沙箱安全策略

## 执行外部脚本时
- sandbox: container
- image: python:3.12-slim
- network: none

## 日常开发命令（npm、git 等）
- sandbox: workspace

Codex 在执行命令前会读取 AGENTS.md 中的沙箱策略，然后根据当前任务的上下文选择合适的隔离级别。

命令行临时覆盖

如果你临时想改变沙箱行为，可以通过 CLI 参数直接指定：

# 临时禁用沙箱（不推荐）
codex exec --sandbox=none "运行单元测试"

# 临时启用严格沙箱
codex exec --sandbox=strict "分析这个可疑的 shell 脚本"

实战场景

场景一：安全审查开源项目

当你在 GitHub 上发现一个有意思的项目，想快速看看它的运行效果，但又担心代码有问题：

codex exec --sandbox=strict "克隆 https://github.com/example/unknown-repo，阅读 README 并执行安装步骤"

设置为 strict 后：

• 代码在临时容器中执行
• 无法访问你的本地文件
• 无法联网发送数据
• 容器销毁后所有痕迹消失

场景二：日常开发保持文件安全

在日常开发中，你希望 AI 能正常读写项目文件，但不想它随意修改系统配置：

{
  "sandbox": {
    "mode": "container",
    "image": "node:20-alpine",
    "workspace_mount": true,
    "read_only": false,
    "network": "host",
    "mounts": ["./src", "./package.json", "./tsconfig.json"]
  }
}

这个配置的关键在于：

• workspace_mount: true 允许 AI 修改项目代码
• mounts 显式指定了只挂载必要文件，避免容器访问敏感目录
• network: host 允许 AI 执行 npm install 等需要网络的操作

场景三：运行 AI 生成的数据库迁移脚本

数据库迁移是一个高风险操作，配置时应该格外谨慎：

{
  "sandbox": {
    "mode": "container",
    "image": "postgres:16-alpine",
    "workspace_mount": false,
    "network": "host",
    "env_file": ".env.test",
    "read_only": true
  }
}

这里的关键设计：

• workspace_mount: false 且 read_only: true 双重保护项目文件
• 指定了 .env.test 作为环境变量来源，避免生产环境密钥泄露给 AI
• 使用独立的 PostgreSQL 镜像，不依赖本地数据库版本

场景四：沙箱与 Hooks 联动

Codex 支持在执行命令前后插入 Hooks，结合沙箱可以实现强大的自动化安全检查：

{
  "sandbox": {
    "mode": "container",
    "image": "ubuntu:22.04"
  },
  "hooks": {
    "pre_exec": [
      "echo '[SANDBOX] 开始执行，模式: {sandbox_mode}'",
      "docker run --rm aquasec/trivy image {sandbox_image} || true"
    ],
    "post_exec": [
      "echo '[SANDBOX] 执行完毕，容器即将销毁'"
    ]
  }
}

使用 pre_exec Hook 在每次进入沙箱前对镜像做安全扫描，post_exec Hook 记录执行日志。

Sandbox 模式的选择策略

选择合适的沙箱模式需要权衡安全性和可用性：

graph TD
    A[AI 需要执行的命令] --> B{是否需要访问项目文件?}
    B -->|是| C{是否信任命令来源?}
    C -->|是| D[workspace 模式]
    C -->|否| E{是否需要网络?}
    E -->|是| F[container 模式 + 网络]
    E -->|否| G[container 模式 + 无网络]
    B -->|否| H{命令来源是否可信?}
    H -->|是| I[container 模式]
    H -->|否| J[strict 模式]

一个实用的经验法则：

npm install / pip install / go mod tidy → container 模式 + 网络 + 挂载依赖文件

代码重构 / 格式化 → workspace 模式

执行外部脚本 / 分析未知代码 → strict 模式

数据库操作 → container 模式 + 环境变量注入

常见问题与最佳实践

Q: 沙箱模式下 npm install 太慢怎么办？

可以通过挂载本地缓存目录加速：

{
  "sandbox": {
    "mode": "container",
    "image": "node:20-alpine",
    "volumes": [
      "~/.npm:/root/.npm",
      "node_modules:/app/node_modules"
    ]
  }
}

Q: 如何在沙箱中调试？

添加 --keep-alive 参数可以让容器在执行完后不立即销毁：

codex exec --sandbox=container --keep-alive "运行测试并排查错误"
# 容器保持运行，你可以 docker exec 进去检查
docker exec -it codex-sandbox-xxxx /bin/sh

Q: 沙箱模式对性能有影响吗？

启动 Docker 容器通常需要 1-3 秒的冷启动时间。如果频繁执行短命令，建议对这些命令使用 workspace 模式并设置合理的文件白名单，减少不必要的容器创建。

总结

Codex 的 Sandbox 模式是 AI 编程安全实践中的关键一环。它用简单清晰的配置层级（代码配置、文档配置、命令行参数）覆盖了从严格隔离到灵活开放的多种场景。建议每个使用 Codex 的开发者都至少配置基本的沙箱策略——哪怕只是最简单的 workspace 模式加文件白名单，也比让 AI 裸奔在你的系统上要安全得多。

记住一个核心原则：永远在知道 AI 在做什么的前提下，给它刚好够用的权限。Sandbox 模式就是实现这一原则的最好工具。