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 对某个已放行域名持有高权限凭证，它仍可能借该域名发起其他请求或外泄数据——白名单域名不等于安全域名。

自建容器时的加固基线

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

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

来源

• 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）

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