Claude Code 深度学习手册

主题

选择隔离环境 ​

对比 Bash 沙箱、sandbox runtime、dev container、VM、web 五类隔离方案，按威胁模型选型。

是什么 ​

隔离 Claude Code 限制一个会话能读、写、访问网络的范围。当你想减少权限提示、让 Claude 无人值守运行、或让它处理你不完全信任的代码时，隔离最为重要。

Claude Code 可在多种隔离环境中运行，从轻量的逐命令沙箱到完全独立的虚拟机。隔离能降低被攻破后的影响，但不能消除风险：任何允许网络出站的方案仍可能泄露 agent 能读到的数据，任何把项目目录以可写方式挂载的方案仍可能修改代码。隔离也不改变发送给模型的内容。

怎么工作 ​

  • 前两种方案（Sandboxed Bash tool 与 Sandbox runtime）直接运行在宿主操作系统上、不用容器；其余方案把 Claude Code 放进容器或虚拟机。
  • Sandboxed Bash tool 内置于 Claude Code，仅限制 Bash 命令；built-in file tools、MCP servers、hooks 仍直接在宿主上运行。
  • Sandbox runtime、dev container、custom container 把整个 Claude Code 进程放入隔离边界，因此 file tools、MCP servers、hooks 也一并受限。
  • 隔离与权限模式协同：权限模式决定一次工具调用是否运行、是否先提示你；隔离限制命令运行后能访问什么。
  • --dangerously-skip-permissions 移除逐操作审查，此时隔离边界是唯一约束，必须在容器、VM 或 sandbox runtime 内运行。
  • Auto mode 用分类器替代提示来拦截越权操作，这是逐操作控制而非隔离边界；隔离边界仍能为无人值守运行提供纵深防御。
  • 可叠加方案：在容器或 VM 内再运行 sandboxed Bash tool，可在外层环境边界之上再加一层 OS 级命令限制。

怎么配置 / 用法 ​

各方案启用方式：

  • Sandboxed Bash tool：内置，用 /sandbox 命令启用。默认允许写工作目录，命令首次需要新网络域时提示。不支持原生 Windows，Windows 宿主用 WSL2 或容器/VM。Linux/WSL2 用 bubblewrap，macOS 用内置 Seatbelt。

  • Sandbox runtime（beta 研究预览）：用 @anthropic-ai/sandbox-runtime 包把整个进程裹进与 Bash 沙箱相同的 Seatbelt/bubblewrap 隔离。默认拒绝所有写和网络访问，需先在 ~/.srt-settings.json 放行至少项目目录、~/.claude、~/.claude.json 的写权限及所需网络域（含 api.anthropic.com 或你的 provider 端点）。然后启动：

bash
npx @anthropic-ai/sandbox-runtime claude

  • Dev container：在仓库放 .devcontainer/ 目录，由 VS Code 管理的 Docker 容器运行、挂载项目。官方示例 dev container 带 default-deny iptables 防火墙，支持用 --dangerously-skip-permissions 无人值守运行。

  • Custom container：可在任意 Docker/OCI 镜像中运行，自定义网络策略、挂载卷、seccomp profile；容器内可叠加 built-in Bash 沙箱（非特权容器需 nested-sandbox 设置）。

  • Virtual machine：独立 VM 提供最强隔离（独立内核）；选项含云实例、本地 hypervisor、Firecracker 等 microVM；Docker Desktop 的 sandboxes 功能提供带独立 daemon 的 microVM。

  • Claude Code on the web：每个会话运行在 Anthropic 托管的隔离 VM 中；网络代理强制默认 allowlist，另一个代理把你的 GitHub token 留在沙箱外。需要 Claude 订阅和已连接的 GitHub 账户。

什么时候用 ​

  • 日常在自己机器上工作、想减少权限提示：用 /sandbox 启用 sandboxed Bash tool。
  • 想让 Claude 用 --dangerously-skip-permissions 或 auto mode 无人值守运行：用预配置 dev container、任意容器/VM，或 sandbox runtime。
  • 想在不用 Docker 的前提下同时隔离 MCP servers 和 hooks（不只是 Bash）：用 sandbox runtime。
  • 处理不信任的仓库：用专用 VM，或在有 Claude 订阅和连接的 GitHub 账户时用 Claude Code on the web。
  • 想跨团队标准化沙箱环境：把预配置 dev container 复制进仓库。

限制 / 坑 ​

  • 隔离降低被攻破影响但不消除风险：允许网络出站仍可能泄露数据，可写挂载项目目录仍可能被改代码。
  • 隔离不改变发送给模型的内容：prompt 与 Claude 读取的文件无论是否沙箱都会传给 API/provider。
  • Sandboxed Bash tool 仅约束 Bash，单独使用不足以支撑任一模式下的完全无人值守运行。
  • Sandboxed Bash tool 不支持原生 Windows，需用 WSL2 或容器/VM。
  • Sandbox runtime 是 beta 研究预览，配置格式可能随包演进而变化。

硬事实速查（11 条） ​

  • Sandboxed Bash tool：隔离 Bash 命令及其子进程；不需 Docker；内置用 /sandbox 启用，适合日常减少权限提示。
  • Sandbox runtime：隔离整个 Claude Code 进程含 file tools、MCP servers、hooks；不需 Docker；适合不用 Docker 也要隔离 MCP/hooks 或支撑无人值守运行。
  • Dev container：隔离完整开发环境；需要 Docker；带 default-deny 防火墙，适合团队标准化和 --dangerously-skip-permissions 无人值守运行。
  • Custom container：隔离完整开发环境；需要 Docker；适合已有容器基础设施或 CI runner 的组织，可自定义网络/挂载/seccomp。
  • Virtual machine：隔离完整操作系统（独立内核）；不需 Docker；隔离最强，适合评估不信任代码或需内核级分离的合规要求。
  • Claude Code on the web：隔离完整操作系统、由 Anthropic 托管；无需设置但需 Claude 订阅和 GitHub；适合无本地环境的设备。
  • 只有 built-in Bash sandbox 是 Claude Code 自身能强制的方案，可通过 managed settings 或 server-managed settings 下发。
  • Dev container 是约定而非强制边界，因为 Claude Code 并不要求必须在容器内运行；如需强制要靠组织的设备管理或软件白名单。
  • 原生 Windows 宿主：用容器/VM，或在 WSL2 内跑 Bash 沙箱。
  • Auto mode 的分类器是逐操作控制而非隔离边界，不像 --dangerously-skip-permissions 那样强制要求隔离边界。
  • 处理不信任仓库或要求内核级分离时，VM 提供最强分离；microVM 选项含 Firecracker 和 Docker Desktop sandboxes。

官方出处：https://code.claude.com/docs/en/sandbox-environments