Agent 沙箱（Agent Sandbox）

什么是 Agent 沙箱

Agent 沙箱是给 智能体编程 Agent 划定的执行边界：用操作系统级能力限制它能读写哪些路径、能访问哪些域名，超出边界的操作直接被拦下而不是弹窗征求同意。

它和「权限系统」解决的是两件事，别混为一谈：

「审批疲劳」是沙箱存在的真正理由。传统做法下，Agent 每跑一条 bash 都要问一次，人点了二十次同意之后就不会再看了——这时的许可已经不提供任何安全收益，只剩打断。沙箱换个思路：边界一次性划好，边界内的命令自动放行，把人的注意力留给真正越界的那几次。

它到底隔离了什么

一个能用的 Agent 沙箱必须同时做到文件系统与网络两层隔离，缺一层就等于没隔离：

• 缺网络隔离：被注入的 Agent 可以读走你的 SSH key，然后发到任意服务器；
• 缺文件系统隔离：被注入的 Agent 可以改写系统配置或后门脚本，自己开出一条网络通路。

文件系统隔离

以 Claude Code 的实现为典型：

• 默认写权限：当前工作目录及其子目录（可写可读）；
• 默认读权限：整机可读，但排除显式 deny 的目录；
• 越界写：未显式授权则不能改工作目录之外的文件；
• 可扩展：通过 sandbox.filesystem.allowWrite 追加可写路径，通过 sandbox.filesystem.denyRead 收紧可读路径。

关键一点：这些限制是在操作系统层强制的，所以所有子进程都继承同一套边界——不只是 Agent 自己的文件工具，npm install 里的 postinstall 脚本也一样被关着。

网络隔离

网络不走「禁用」而走沙箱外的代理：

• Agent 的对外请求全部经过运行在沙箱外的代理服务器；
• 代理按域名白名单放行，遇到白名单外的新域名触发权限提示（开启 allowManagedDomainsOnly 后则直接拒绝，不再问）；
• 限制覆盖命令派生的所有脚本、程序与子进程。

这个架构有个很实用的性质：即使 Agent 被提示注入完全控制，它也只能跟代理说话——只要代理不转发，数据就出不去。

各家怎么实现

沙箱在哪一侧是 2026 年选型时必须问出口的问题。托管沙箱（如 Agents API 的 hosted sandbox）省事，但执行环境、审计日志与故障模式都由供应商定义；自托管沙箱（客户网络内执行）麻烦，但源码、密钥与内部服务不出自己的机器——Cursor Self-Hosted Machines 与 Coder Agents 走的都是后一条路。

怎么开（以 Claude Code 为例）

沙箱默认是关闭的，需要显式开启：

// ~/.claude/settings.json（全局）或 .claude/settings.json（项目级）
{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "allowWrite": ["//tmp/build"],
      "denyRead": ["~/.ssh", "~/.aws"]
    },
    "network": {
      "allowedDomains": ["registry.npmjs.org", "github.com"],
      "allowManagedDomainsOnly": true
    }
  }
}

三个字段值得单独说：

• failIfUnavailable: true——依赖缺失或平台不支持时直接失败，而不是「警告一声然后裸跑」。做托管部署/安全门禁的团队应该开着。
• allowUnsandboxedCommands: false——关掉逃逸口（见下节）。
• allowManagedDomainsOnly: true——白名单外的域名自动拒绝，不再弹窗问人。

会话内也可以直接用 /sandbox 打开面板切换（VS Code 侧在 v2.1.280 起有专门的 Sandbox 对话框，显示沙箱模式、非沙箱回退与排除命令）。

四个必须知道的坑

1. 有一个「故意留的逃逸口」

当命令因沙箱限制失败（比如需要访问白名单外的网络，或工具本身不兼容），Claude 会分析失败原因，并可能带 dangerouslyDisableSandbox 参数重试一次——即「跳出沙箱再跑一次」。这次重试仍走正常权限流程，需要你批准。

这是为了兼容现实（很多工具在沙箱里就是跑不起来）而做的设计，但它也是整条链路上最容易被人一路同意的地方。要彻底关掉，设 allowUnsandboxedCommands: false。

2. 有些工具在沙箱里跑不了

官方点名的两个：

• watchman 与沙箱不兼容——跑 jest 时用 jest --no-watchman；
• docker 与沙箱不兼容——把 docker 写进 excludedCommands，强制它在沙箱外执行。

碰到「升级后某条命令突然失败」，先怀疑这一类，而不是先关沙箱。

3. 共享宿主内核 = 理论上的逃逸面

沙箱（Seatbelt / bubblewrap / 普通容器）与宿主共享同一个内核：内核一旦有漏洞，理论上就能逃逸。对多数个人开发与 CI 场景这层防护已经「显著提高门槛」，但如果你的威胁模型要求内核级隔离，答案是 gVisor 或独立 VM——gVisor 在用户态拦截系统调用，恶意代码得先攻破 gVisor 的实现。

4. 代理不做 TLS 检查，域名白名单可被绕过

沙箱代理依据客户端提供的 hostname 做白名单，不终止也不检查加密流量。因此沙箱内的代码有可能通过 domain fronting 一类技术触达白名单外的主机。需要更强保证时，配一个 TLS 终止代理。

还有一条配套的：如果 Agent 对某个已放行域名持有高权限凭证，它仍可能借该域名发起其他请求或外泄数据——白名单域名不等于安全域名。

沙箱的两个新方向：可搬运的执行环境、可 diff 的权限（2026-09 更新）

2026 年 9 月，Docker 把沙箱这条线往前推了两步，值得单独记一笔，因为它改变的是沙箱的形态而不只是强度。

方向一：执行环境可以在本地与云之间搬

Docker Cloud Sandboxes（2026-09-24 发布） 把原本只能跑在开发机上的 microVM 沙箱延伸到 Docker 托管的云算力，且本地与云端共用同一套 sbx CLI——sbx move 会抓取沙箱文件系统并在另一端重建。

它解决的是一个很具体的痛点：长任务 Agent 的「开始比结束容易」。你在本机起一个跨几十个文件的重构，跑到一半要合上笔记本，过去的选项只有「切小块牺牲连贯性」或「专门为它开一台云主机」。现在变成一次搬迁：本地调好上下文 → 搬到云上跑完 → 搬回来继续。

计费也按这个模型设计：按秒计费，暂停不收费（官方公布区间 $0.07/小时 起，到 16 vCPU / 32 GiB 的 $1.12/小时），模型推理费另算、可用自己的 API key。也就是说它卖的是算力而不是订阅席位——别拿 token 账单的思路去估它。

方向二：权限变成可 review 的制品

Sandbox Kit 规范 v3（同期开源，Apache-2.0，Docker 宣布拟提交 CNCF 中立治理）用普通 OCI 镜像承载一个 Agent 的「权限申请单」：清单注解里写它要访问哪些主机、凭证、卷与端口，镜像层里装 Agent 本体与工具。

• workload / mixin 两角色：workload 给根文件系统与启动命令，mixin 叠加 CLI、凭证绑定、网络规则或 Agent 上下文；组合顺序由 provides / requires 依赖图决定，不是按 flag 顺序。
• 锁 digest = 同时锁内容与权限：所以放宽权限的改动必然表现为 manifest 里新增的行，人可以拒绝，runtime 也可以对归一化授权集做门禁，让静默的权限爬升 fail closed。
• Kit 是「申请」，不是「围栏」：官方措辞明确——Kit asks，conforming runtime grants or refuses。换到不合规的 runtime 上，descriptor 里的 deny 未必有人执行。 选型时该问的是「你实际用的 runtime 怎么执行网络、凭证与文件系统策略」。
• 状态：官方 README 标 experimental，最终版目标 Q4 2026；Sandbox API 与 TypeScript SDK 亦为实验性；v3 不能与 v1/v2 混用（内置 agent 名选中 v2 kit，加 v3 mixin 会失败）。

对已有 Agent 编排 的团队，这条更直接：子 agent 的权限边界随镜像版本走，「这个 subagent 能碰什么」变成一条可 review 的配置行，而不是启动脚本里的一堆环境变量。

自建容器时的加固基线

不走现成沙箱、自己封容器时，下面这组参数是常见的起点：

docker run \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --security-opt seccomp=/path/to/seccomp-profile.json \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --network none \
  --memory 2g --cpus 2 --pids-limit 100 \
  --user 1000:1000 \
  -v /path/to/code:/workspace:ro \
  -v /var/run/proxy.sock:/var/run/proxy.sock:ro \
  agent-image

几个要点：--network none 让容器完全没有网卡，对外只能通过挂载的 Unix socket 走宿主代理（域控、注入凭证、全量日志都在代理上做）；--read-only 让根文件系统不可变；不要把 ~/.ssh、~/.aws、~/.config 挂进去。可再加 --userns-remap（把容器 root 映射为宿主非特权用户）与 --ipc private。

与相邻概念的区别

FAQ

开了沙箱还需要权限提示吗？ 需要，但数量会大幅下降。Claude Code 提供两种模式：auto-allow（沙箱内的 bash 自动放行）与 regular permissions（即便在沙箱内也逐条走权限流程）。前者省事，后者可控，团队按风险偏好选。

沙箱能防提示注入吗？ 严格说：防不住注入，防得住注入之后的破坏。注入仍可能发生，但被注入的 Agent 无法读写边界外的文件、也无法把数据发到白名单外的地址。所以官方把「权限 + 沙箱 + 对未审计文件保持警惕」称为防御三角。

Windows / WSL1 能用吗？ WSL1 不支持（bubblewrap 需要 WSL2 才有的内核特性）。WSL2 与原生 Linux 一样需要装 bubblewrap + socat。

CI 里要不要开？ 要，而且建议配 failIfUnavailable: true——CI 是「无人值守 + 有凭证 + 跑不审计的第三方代码」三者叠加，正是沙箱收益最大的场景。

延伸阅读

• 工具：Claude Code · GitHub Copilot · OpenCode · OpenAI Agents API · Cursor
• 概念：智能体编程 · MCP · 智能体编排 · 上下文工程 · 长上下文
• 实践：终端 Agent 技术栈 2026 · 从零搭 MCP
• 资讯：Docker Cloud Sandboxes 与 Sandbox Kit v3（2026-09-24） · 微软新版 Copilot 的 Code 跑在沙盒中、Autopilot 带独立计算机实例（2026-09-25） · Cursor 上线 Rollouts 与 Security Review（2026-09-23）

来源

• Claude Code Sandboxing 官方文档（Seatbelt / bubblewrap、文件系统与网络隔离、逃逸口与 excludedCommands）
• Securely deploying AI agents — Anthropic Agent SDK 文档（共享内核限制、无 TLS 检查、容器加固参数、gVisor）
• Introducing the Agents API（OpenAI，2026-09-10，托管 / 自托管沙箱 public beta）
• GitHub Changelog：Copilot for JetBrains 企业托管沙箱策略（2026-09-08）
• Docker Launches Cloud Sandboxes（Docker 官方新闻稿，2026-09-24） — Cloud Sandboxes 发布、Kit 权限模型、CNCF 意向
• Docker Sandboxes release notes（0.45.1 2026-09-22 / 0.45.0 2026-09-21） — v3 kits、sbx --cloud、v1/v2 不兼容与实验性标注

本条目由 AI 之家 编辑部根据公开资料整理，非厂商付费内容。沙箱的具体字段与默认值随版本变化较快，落地前请以所用工具的官方文档为准；涉及威胁模型的判断（是否需要 gVisor / VM）请结合自身场景评估。欢迎在 反馈邮箱 反馈更新。