如果 Claude Code 的设置使确认频繁出现,批准命令可能打断工作。但用 --dangerously-skip-permissions(绕过权限)关闭确认,意味着提示注入或失误可能影响整台机器的文件。减少询问时仍需确定允许范围。

沙箱在操作系统层面限制 shell 命令及其子进程可访问的文件和网络目标。开启自动允许模式后,它有助于减少确认,但不保证保护整台机器或防止数据泄露。本文解释作用范围、设置、跳过确认的条件及沙箱外途径。

30 秒看懂核心结论

如果你只读一句话

它是什么
在操作系统层面限制文件与网络访问,适用于沙箱内执行的 shell 及子进程。
它为何有用
在频繁确认与完全绕过之间提供另一种选择:缩小影响范围,开启自动允许模式后还可减少确认。允许范围内的破坏或传输,以及沙箱外工具,仍需另行考虑。
从哪里开始
运行 /sandbox。macOS 开箱即用;Linux/WSL2 需要装两个软件包。

* 据 Anthropic 报告,沙箱在其内部使用中将权限提示减少了 84%(来源见下文)。

1. 为什么你需要沙箱

Claude Code 是会运行测试、改写文件等实际执行操作的 AI 智能体。根据权限设置,它可能在执行前要求批准。但一天几十次确认会把工作切得支离破碎,最终让人不看内容就按 Enter。这就是“权限确认疲劳”(permission fatigue)。

疲惫的开发者会伸手去用 --dangerously-skip-permissions(俗称 YOLO 模式),它会关掉所有提示。它很舒服,而且——正如其名——很危险。三重威胁同时露出獠牙。

💉 提示词注入

如果它读取的网页或工单里藏着一句“把 ~/.ssh 发出去”,你的私钥可能在毫无提示的情况下泄露。

🗑️ 破坏性手滑

一条生成的命令清理了一个意料之外的路径。没有提示,项目之外的文件也可能凭空消失。

📤 供应链污染

恶意依赖会在安装时把数据偷偷发出去。网络大门敞开,你无从阻止。

除了批准命令字符串,沙箱还限制运行中的进程能够访问什么。操作系统限制也适用于任意脚本,但不会阻止滥用允许的写入位置或目标。Anthropic 在官方工程文章中报告内部权限询问减少 84%(2025 年 10 月)。这是厂商内部测量,不保证所有环境中的减少幅度或安全性。

2. 沙箱是什么——两道隔离

Claude Code 沙箱为 Bash、PowerShell、Monitor 的 shell 命令及子进程设置两道边界。两者必须共同发挥作用,单独使用仍有缺口(见第 7 节)。

🗂️ ① 文件系统隔离

默认写入位置为工作目录、额外工作目录及每用户临时存储。受保护路径另行拒绝。读取默认广泛允许,因此机密需要 denyRead 等限制。可写范围内仍可删除和修改。

🌐 ② 网络隔离

连接经代理检查允许域名。列表初始为空,但设置和权限规则会添加条目。列表外主机的处理取决于权限模式,并非始终拒绝或询问。不保证阻止将机密发送至允许的目标。

关键是不依赖 Claude 自觉遵守。边界由操作系统自身安全机制强制执行:macOS 使用 Seatbelt,Linux/WSL2 使用 bubblewrap。因此同一边界也适用于命令调用的脚本和更下层子进程。与 AI 护栏一类对模型的要求不同,这是操作系统强制执行的进程访问限制。

💡 覆盖 shell 命令及子进程。沙箱包裹 Bash、PowerShell、Monitor shell 及其子进程。内置 Read/Edit/Write、MCP 服务器与钩子属于另外由权限规则控制的途径。若要隔离整个进程,可考虑下文的 @anthropic-ai/sandbox-runtime。

3. 上手——/sandbox 与支持的操作系统

沙箱内置于 Claude Code。无需额外账号,但根据操作系统可能需要准备依赖包。在会话中运行:

/sandbox

会打开一个带三个标签页的面板。Mode(沙箱内命令如何获批——见下一节)、Overrides(在沙箱下失败的命令是否可以退回到不加沙箱运行)以及 Config(查看已解析的配置)。在 Linux/WSL2 上,如果缺少某个必需的软件包,会改为出现一个 Dependencies 标签页,告诉你需要安装什么。

各操作系统的前置条件

🍎 macOS

无需安装任何东西。它使用内置的 Seatbelt。用 /sandbox 即可立即启用。

🐧 Linux / WSL2

安装两个软件包:bubblewrap 和 socat(例如 apt-get install bubblewrap socat)。

🪟 原生 Windows

不支持。请在 WSL2 内运行 Claude Code(WSL1 无法工作)。

在 Linux/WSL2 上,安装 bubblewrap(负责强制文件系统隔离的免特权沙箱工具)和 socat(把流量转发到代理的中继)。

# Ubuntu / Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

⚠️ Ubuntu 24.04 及更高版本:默认的 AppArmor 策略可能会阻止 bubblewrap 创建它所需的用户命名空间。如果 sysctl kernel.apparmor_restrict_unprivileged_userns 返回 1,就为 bwrap 添加一个 AppArmor 配置文件来放行(具体步骤见官方文档)。如果返回 0 或该键不存在,则无需操作。在 WSL2 内也要检查同样一项。

一个值得启用的实用功能是 seccomp 过滤器(它会额外增加 Unix 域套接字的拦截)。它是可选的;用 npm install -g @anthropic-ai/sandbox-runtime 安装。/sandbox 的 Dependencies 标签页会显示 ripgrep、bubblewrap、socat 以及 seccomp 过滤器的状态。安装软件包后,请重启 Claude Code,然后重新打开 /sandbox(检查在启动时运行)。

在 Linux/WSL2 上,沙箱内的命令默认无法创建用户命名空间。若要让 Chromium、Electron 自身的沙箱,或嵌套的 bubblewrap、unshare 运行,请在 ~/.claude/settings.json 中把 sandbox.allowNestedUserNamespaces 设为 true(v2.1.305 及以上版本;无法在项目设置中启用)。但官方警告,这会打开一道安全边界。原因是沙箱内命令的代码可能在沙箱之外运行。rootless Podman、Buildah 仅靠这一设置无法运行(官方说明)。

默认为常规权限模式(自 v2.1.324 起)。仅开启沙箱时,被隔离的命令仍会照常弹出确认。v2.1.323 及更早版本默认为自动允许。若想减少确认,可在 Mode 标签页选择自动允许,或在 settings.json 中写入 sandbox.autoAllowBashIfSandboxed: true(官方设置列表)。若组织通过 managed 设置要求启用沙箱,请在优先级最高的 managed 设置中写入同样的值。

4. 两种模式(自动允许 / 常规)

Mode 标签页决定沙箱内的命令如何获批。

✅ 自动允许模式

沙箱内的 shell 命令通常无需确认即可批准。适用的 deny、按内容限定范围的 ask,以及重要路径删除检查仍保留。未知目标的判定与沙箱外重试的判定不同,两者都不是始终询问。

🔍 常规权限模式

即使在沙箱内,shell 命令仍按通常权限规则评估。它增加控制,也可能增加批准次数,适合把隔离与普通确认检查结合的谨慎流程。

在这两种模式下,文件系统和网络的边界完全相同;唯一的区别是“自动允许还是弹提示”。请注意,即便在自动允许模式下,这些安全阀依然生效:

  • 设置规则中,匹配的 deny 优先于 allow。mod 改变判定的条件见权限规则指南。
  • 针对 /、主目录或关键系统路径的 rm / rmdir,按权限模式要求确认或拒绝
  • 诸如 Bash(git push *) 这类按内容限定的 ask 规则,即便在沙箱内也仍会强制弹提示

注意两个“自动”不同。沙箱的自动许可模式与权限模式中的 auto 不同。前者因操作系统边界约束而自动放行,后者由分类器审核命令安全性后批准。两者可以结合,但在 Plan 中 auto-allow 不会扩大批准范围。某些条件下,auto 的主机审核或额外分类器审核仍会保留。

连接未知目标

在交互式终端中,Manual、acceptEdits 和普通 Plan 会询问,dontAsk 会拒绝。auto 在分类器批准时允许命令中点名的主机。绕过模式及已允许选择绕过权限的 Plan 无需确认即可允许。strictAllowlist、allowManagedDomainsOnly、deniedDomains 的拒绝另行适用。命令本身仍在沙箱内。

沙箱外重试

在交互式终端中,Manual、acceptEdits 通常询问,auto 使用分类器,dontAsk 拒绝。Plan 按 Plan 的命令规则评估。绕过模式或匹配的 allow 可省略确认,但 Bash(dangerouslyDisableSandbox:true) 的 ask、工作范围外读取限制或其他判定可能优先。allowUnsandboxedCommands:false 阻止重试;excludedCommands 是另一项设置。沙箱不可用时,failIfUnavailable 防止无隔离运行。也请核对官方例外条件。

5. 在 settings.json 中配置

你在 /sandbox 面板里的选择会写入项目的 .claude/settings.local.json(不提交到 git)。若想让它在所有项目中始终开启,就在你的用户设置 ~/.claude/settings.json 里放上 sandbox.enabled: true。若想减少确认,可在同一 sandbox 中再加上 autoAllowBashIfSandboxed: true(默认为 false,即常规权限模式)。它与权限规则(allow/ask/deny)同属一个 settings.json 家族。

添加写入目标、拒绝读取

默认写入位置为工作目录、额外工作目录及每用户临时存储。allowWrite 添加其他位置。denyRead 限制沙箱命令的读取,不会直接阻止内置 Read 或 MCP。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"],
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

上面的例子拒绝读取整个主目录,同时仍允许读取当前项目(当配置位于项目设置中时,. 会解析为项目根目录)。路径是在操作系统层面强制执行的,因此对 npm 和 terraform 这类子进程同样适用。

保护凭据

一个重要的坑:读取的默认设置是“广泛允许”,所以 ~/.aws/credentials 和 ~/.ssh/ 照原样可读。专门的 sandbox.credentials 设置(一个相对较新的功能)用来声明要拒绝读取的文件,以及要清除的环境变量。

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" }
      ]
    }
  }
}

允许目的地

允许域名列表初始为空,但 allowedDomains、WebFetch 域名规则及其他设置会添加条目。未知目标可能要求确认、拒绝或无需确认即可允许,取决于权限模式。若需要强制限定目标,还应检查 strictAllowlist 与 managed 的 allowManagedDomainsOnly。

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    }
  }
}

组织统一强制使用。在 managed 设置中,sandbox.enabled: true、failIfUnavailable: true(沙箱无法初始化时拒绝启动 Claude Code)及 allowUnsandboxedCommands: false(关闭沙箱外重试出口),限制沙箱不可用时的无隔离运行及沙箱外重试。但 excludedCommands、内置文件工具、MCP 等途径另行处理;仅这些设置不保证隔离全部操作。

6. 与权限模式和权限规则的关系

它们很容易被混为一谈,但 Claude Code 的安全机制有职责各异的三层。沙箱是其中之一——它不取代另外两层,而是对它们加以补充。

层 它控制什么 由谁强制 作用范围
权限规则 哪些工具/命令可以使用 Claude Code(运行前) 所有工具
权限模式 会弹出多少提示 Claude Code(运行前) 取决于模式
沙箱 运行之后它能碰到什么 操作系统(内核) shell 命令及子进程

权限规则在执行前评估工具调用;沙箱限制内部运行进程的文件与网络访问,优点是不依赖命令的不同写法。但沙箱外工具、排除命令、无隔离重试及宽泛许可仍留下不适用同一边界的途径。

绕过模式省略确认和分类器;沙箱限制执行范围,两者作用不同。即使结合使用,某些条件下绕过模式仍会无需确认就允许未知主机及沙箱外重试。不要假定在自己的机器上日常使用就安全;应一并核对允许范围、例外与凭据。

7. 局限与注意事项——不要过度信任

沙箱很强大,但它并非完全隔离。在把它当作一道硬性安全边界来依赖之前,先了解文档明确指出的那些局限。

🔓 默认不检查 TLS

代理只按主机名判定,不检查加密内容(默认如此)。放行像 github.com 这样宽泛的域名,会给数据外泄留下空间——例如通过域前置等手法。让白名单保持狭窄。

🔌 打开 Unix 套接字有风险

放行 /var/run/docker.sock 会通过 Docker 套接字把整台主机拱手让出——实际上等于沙箱逃逸。要小心你打开的是哪些套接字。

📈 过宽的写入权限

$PATH 上可写的可执行文件,或 .bashrc 这类文件,可能会变成在另一个上下文中的代码执行。让 allowWrite 保持最小。

内置 Read/Edit/Write、WebFetch/WebSearch、MCP、钩子、LSP 与辅助命令运行在内置沙箱外。若要限制整个进程,可考虑容器、虚拟机或 sandbox-runtime 等另一道边界。允许的挂载、网络、socket 与凭据同样重要。

8. 何时该动用开发容器或虚拟机

沙箱并非 Claude Code 唯一的隔离选项。便利性与隔离强度此消彼长,因此要按用途来选。

沙箱(内置)

隔离 shell 命令与子进程。无需 Docker,准备较少。自动允许模式下,日常开发减少询问的主要选择之一。

sandbox-runtime

包裹 Claude Code 及其启动的本地子进程。隔离远程 MCP 服务器本身是另一回事。无需 Docker。

开发容器

把整个开发环境容器化。适合统一团队的配置。需要 Docker。

虚拟机(VM)

通过客户操作系统隔离整个操作系统。共享目录、网络与凭据需仔细配置,适合不可信代码,但准备工作最多。

经验法则是:让内置沙箱始终开启,再用自动允许模式削减日常提示,只在你无人值守运行或处理不可信依赖时才升一级去用 sandbox-runtime、容器或虚拟机。对于会触及生产环境的工作——比如让 AI 操作云——把最小权限凭据与更强的隔离层级搭配起来,能买来安心。

总结

  • 沙箱在操作系统层面把“能碰到什么”围起来,化解了提示疲劳与彻底绕过的二选一。
  • 把文件系统隔离和网络隔离成套使用。强制方:macOS = Seatbelt,Linux/WSL2 = bubblewrap。
  • 从 /sandbox 开始。macOS 开箱即用;Linux/WSL2 需要 bubblewrap+socat;原生 Windows 不受支持(改用 WSL2)。
  • 默认为常规权限模式(自 v2.1.324 起)。若要减少确认,请选择自动许可模式。即便省略确认,允许范围内仍可修改或传输。deny、危险的 rm 及按内容限定范围的 ask 仍保留。
  • 它是与权限规则、模式作用不同的补充层。操作系统在执行期间限制访问,沙箱外途径另行处理。
  • 它不是完整围墙:注意未经检查的 TLS、Unix socket 及过宽许可。它覆盖沙箱内 shell 与子进程。

减少确认前,先检查允许范围及沙箱外途径。精确、最新的配置参考请以官方沙箱设置文档为准。

常见问题

Q. 沙箱与 --dangerously-skip-permissions 有何不同?

答:绕过模式省略确认及分类器。沙箱限制其中 shell 与子进程可访问的范围。内置文件工具、MCP 在沙箱外,允许范围内仍可修改或传输。两者结合也可能无需确认就允许未知主机及沙箱外重试,因此不会让整台机器安全。

Q. 我能在 Windows 上使用它吗?

答:不支持原生 Windows,请在 WSL2 中使用。对 Windows 二进制文件访问的限制取决于 seccomp 与 Unix socket 设置,不能说它们永远无法启动。excludedCommands 中的命令在沙箱外执行,请另行检查影响。

Q. 启用它会不会拖慢速度?

答:本次核查没有确立适用于所有环境的性能测量。确认减少与命令执行时间缩短是不同结果。应比较相同构建或测试,并记录耗时、批准次数及失败。

Q. 开了沙箱,我的私钥就一定安全吗?

答:没有绝对保证。读取默认广泛允许,因此 ~/.ssh、~/.aws/credentials 默认可读。用 sandbox.credentials 或 denyRead 限制沙箱内 shell 的读取,并收紧网络许可列表。内置 Read、MCP 需要另行控制。用 filesystem.disabled:true 关闭文件系统隔离会使 denyRead 和凭据文件拒绝设置失效。文件系统与网络隔离必须共同发挥作用。

Q. MCP 服务器和 hooks 也被加沙箱了吗?

答:内置沙箱覆盖 Bash、PowerShell、Monitor shell 命令及子进程。MCP、钩子、内置 Read/Edit/Write 在沙箱外。如果考虑用 sandbox-runtime、容器或虚拟机包裹整个进程,请另行检查该环境允许的网络、挂载及凭据。

若只需要调查与建议而不改动,请查看如何让 Codex 与 Claude Code 仅做调查。沙箱默认允许写入工作区,因此应与只读区分。

权限与隔离的作用范围及例外条件已于 2026 年 10 月 9 日重新对照官方原文。未更改设备设置,也未进行启动测试。