Codex CLI 完全指南：第五章·沙箱安全模式

沙箱模式是 Codex CLI 最重要的安全特性之一。它通过容器技术将 AI 代码执行隔离在受控环境中，让你的主机免受误操作或恶意代码的影响。

为什么需要沙箱

当 Codex 执行命令时，它拥有你赋予的权限。一个错误的 rm -rf、一次权限越界的文件写入、一个未预期的系统配置修改——在没有隔离的情况下，这些操作的破坏是不可逆的。

沙箱模式本质上是在主机和 AI 执行环境之间加了一层"安全气囊"。

沙箱类型

none（无沙箱）

execution:
  sandbox: none

命令直接在主机上运行。仅在你 100% 信任 AI 操作且项目有备份时使用。

Docker 沙箱

execution:
  sandbox: docker
  sandbox_config:
    image: ubuntu:22.04
    workdir: /workspace
    network: bridge

Codex 会在 Docker 容器中执行命令。前提是主机安装了 Docker。

Podman 沙箱

execution:
  sandbox: podman
  sandbox_config:
    image: fedora:39

与 Docker 类似，使用 Podman（Red Hat 的容器引擎）。

配置 Docker 沙箱

安装 Docker

# macOS
brew install --cask docker

# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install docker.io
sudo usermod -aG docker $USER  # 免 sudo

# Windows
# 安装 Docker Desktop 并启用 WSL2 集成

验证：

docker run --rm hello-world

基础沙箱配置

execution:
  policy: ask
  sandbox: docker
  sandbox_config:
    image: node:20-alpine     # 预装 Node.js 的环境
    workdir: /workspace        # 项目挂载点
    mount: true                # 自动挂载当前项目目录
    network: bridge            # 允许网络访问
    env:
      - NODE_ENV=development
      - API_BASE_URL=https://api.example.com

项目文件挂载

mount: true 会自动将项目目录挂载到容器的 /workspace：

主机: /home/user/my-project/
  └── 挂载到
容器: /workspace/

这样 AI 在容器内生成的代码会直接写入项目文件。

语言特定的镜像

# Python 项目
sandbox_config:
  image: python:3.12-slim

# Go 项目
sandbox_config:
  image: golang:1.22-alpine

# Rust 项目
sandbox_config:
  image: rust:1.78-slim

# 多语言项目
sandbox_config:
  image: ubuntu:22.04
  setup_commands:
    - apt-get update && apt-get install -y nodejs npm python3 pip golang

自定义 Dockerfile

对于有特殊需求的场景，可以指定自定义 Dockerfile：

sandbox_config:
  dockerfile: .codex/Dockerfile

.codex/Dockerfile 示例：

FROM node:20-alpine

RUN apk add --no-cache git openssh curl python3

ENV NODE_ENV=development

WORKDIR /workspace

预构建镜像策略

每次启动容器都会重新构建镜像可能很慢。Codex 支持预构建：

codex sandbox build   # 预先构建沙箱镜像

这会根据 sandbox_config 的配置提前构建好镜像，后续启动容器时直接使用缓存。

网络隔离

沙箱的网络策略控制容器内 AI 是否可以访问网络：

sandbox_config:
  network: none        # 完全断网，最低风险
  # network: bridge    # 默认，允许访问主机网络
  # network: host      # 共享主机网络栈

none：适合只需文件操作的场景，如代码重构
bridge：适合需要 npm install 等联网操作
host：适合需要访问 localhost 服务的场景

端口映射

sandbox_config:
  network: bridge
  ports:
    - "3000:3000"   # Next.js 开发服务器
    - "5432:5432"   # 访问主机 PostgreSQL

安全加固配置

execution:
  sandbox: docker
  sandbox_config:
    image: node:20-alpine
    read_only: false          # 是否只读挂载
    no_new_privileges: true   # 禁止提权
    cap_drop:                 # 移除的 Linux capabilities
      - ALL
    cap_add:                  # 保留的必要能力
      - NET_BIND_SERVICE
    memory_limit: 2g          # 内存限制
    cpu_limit: 2.0            # CPU 限制
    timeout: 300              # 命令超时秒数
    tmpfs:                    # 临时文件系统
      /tmp: size=512m

风险场景与策略

| 场景 | 推荐配置 |
|------|----------|
| 学习/试用 AI | policy: ask + sandbox: docker + network: bridge |
| 开源项目开发 | policy: ask + sandbox: docker + mount: true |
| 代码审查 | policy: never + sandbox: none |
| CI/CD 自动化 | policy: always + sandbox: docker + network: none |
| 生产环境操作 | policy: ask + sandbox: docker + read_only: true |

沙箱中的文件持久化

默认情况下挂载是双向的（读写）。如果你需要 AI 只能读不能改：

sandbox_config:
  mount: true
  read_only: true
  output_dir: /host/user/output   # AI 输出文件的唯一写入路径

这样 AI 可以读取项目代码，但写入结果只能放在指定的输出目录。

实战：安全地测试未知代码

# 拉取一个陌生仓库，在沙箱中运行
git clone https://github.com/unknown/some-tool.git
cd some-tool

codex --sandbox docker --network none \
  "阅读 README，安装依赖，运行测试，告诉我结果"

即便这个仓库有恶意安装脚本，破坏也只限于容器内。

故障排查

容器启动失败

# 检查 Docker 是否运行
docker ps

# 手动测试镜像
docker run --rm node:20-alpine node -e "console.log('ok')"

文件挂载权限问题

在 Linux 上，容器内的文件操作默认以 root 身份执行，生成的文件属于 root。修正：

sandbox_config:
  user: "${UID}:${GID}"   # 以当前用户身份运行

或使用 --user 参数：

codex exec --sandbox docker --sandbox-user "$(id -u):$(id -g)" "..."

macOS 性能问题

macOS 的 Docker 通过虚拟机运行，文件 I/O 有性能损耗。优化建议：

使用 VirtioFS 文件共享（Docker Desktop 设置中启用）
将 node_modules 等频繁 I/O 的目录放入容器内而非挂载

小结

沙箱模式不是可选项，而是 AI 编程的安全基础设施。核心原则：在容器中运行 AI 比你想象的重要得多。适配好沙箱后，你可以放心地让 AI 执行任意操作。

下一章将学习生命周期 Hooks——在 Codex 执行的每个关键节点插入自定义逻辑。