Claude Code 内置沙箱通过操作系统级隔离（macOS 使用 Seatbelt，Linux 使用 bubblewrap）限制 Bash 命令的文件系统和网络访问，从而在减少权限提示的同时防范 Prompt 注入。默认只允许写入当前工作目录，弹出新网络域名时提示授权；可通过 settings.json 自定义允许/拒绝路径和域名，或在托管部署中用 managed settings 强制锁定。不支持原生 Windows，需在 WSL2 下运行。

Claude Code 沙箱配置 - OS 级 Bash 隔离与网络边界设置 #

Bash 沙箱让 Claude 可以直接运行大多数 shell 命令，不需要每步都停下来请求许可。你不必逐个审批每条命令，而是定义哪些文件和网络域名命令可以触及，操作系统会为每个 Bash 命令及其子进程强制执行这个边界。

本页涵盖：

• 启用沙箱并选择沙箱命令的审批方式
• 配置命令可以访问的路径和网络域名
• 理解沙箱与权限规则、权限模式的关系
• 在组织范围内强制执行沙箱

若要对比其他隔离方式（开发容器、自定义容器、虚拟机），参见沙箱环境。若要减少 Bash 以外的工具权限提示，参见权限模式。

启用沙箱 #

沙箱内置于 Claude Code，在 macOS、Linux 和 WSL2 上运行。不支持原生 Windows。在 Windows 上，请在 WSL2 发行版内运行 Claude Code。

macOS 无需额外安装：沙箱使用内置 Seatbelt 框架。Linux 和 WSL2 依赖两个包，详见配置 Linux 和 WSL2。即使还没安装，也可以先用 /sandbox 命令，因为它的面板会显示缺少什么。

1. 启动 Claude Code 会话，运行 /sandbox 命令：

   /sandbox

   这会打开沙箱面板，有三个标签页：

   • Mode：选择沙箱命令的审批方式，见下一步
   • Overrides：选择沙箱内命令失败时是否可以回退到非沙箱运行。对应 allowUnsandboxedCommands 设置
   • Config：查看已解析的沙箱设置

   如果面板只显示 Dependencies 标签页，说明缺少必要的包。按配置 Linux 和 WSL2 安装后重启 Claude Code，再运行 /sandbox。

2. 在 Mode 标签页选择自动允许（auto-allow）或常规权限（regular permissions）。自动允许模式下沙箱命令无需提示直接运行；常规权限模式即使命令沙箱化也保留常规权限提示。哪些命令在自动允许模式下仍会提示，见沙箱模式。

3. 要求 Claude 运行一条命令，比如构建或测试套件。默认情况下沙箱内的命令只能写入工作目录。第一次命令需要新网络域名时，Claude Code 会弹出审批提示。

   无法沙箱化的命令会回退到常规权限流程。要放宽或收紧这些边界，见配置文件系统权限。

在面板中选择模式会写入项目本地设置文件 .claude/settings.local.json，这个文件仅适用于当前项目，不进 Git 版本控制。要在所有项目中启用沙箱，请在用户设置 ~/.claude/settings.json 中将 sandbox.enabled 设为 true。要为组织中的每个开发者强制执行沙箱，使用托管设置。

默认情况下，如果沙箱因为依赖缺失或平台不支持而无法启动，Claude Code 会显示警告并在无沙箱状态下运行命令。要将此行为改为硬性失败，将 sandbox.failIfUnavailable 设为 true。这个选项适用于需要将沙箱作为安全门控的托管部署。

配置 Linux 和 WSL2 #

在 Linux 和 WSL2 上，沙箱依赖两个包：

• bubblewrap：无特权的沙箱工具，执行文件系统隔离
• socat：中继，用于通过网络沙箱代理路由流量

用你的发行版包管理器安装：

# Debian / Ubuntu
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

安装后，/sandbox 的 Dependencies 标签页会显示 ripgrep、bubblewrap、socat 以及 seccomp 过滤器在你的平台上是否可用。Ripgrep 随 Claude Code 原生二进制自带。seccomp 过滤器是可选的，用于阻止 Unix 域套接字。如果缺少，运行 npm install -g @anthropic-ai/sandbox-runtime 安装。

当缺少某依赖时，Dependencies 标签页是唯一显示的标签页，直到你安装完成。依赖检查在启动时运行，因此安装包后需要重启 Claude Code 才能让 /sandbox 检测到它们。

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

沙箱模式 #

Claude Code 提供两种沙箱模式：

自动允许模式：Bash 命令会尝试在沙箱内运行并自动允许，无需权限确认。无法沙箱化的命令（例如需要访问未允许主机的网络访问）会回退到常规权限流程，此时 Claude Code 会检查你的权限规则，并对未明确允许的命令弹出提示。

即使在自动允许模式下，以下规则仍然适用：

• 显式的拒绝规则始终有效
• rm 或 rmdir 命令以 /、你的 home 目录或其他关键系统路径为目标时，仍然会触发权限提示
• 询问规则 适用于回退到常规权限流程的命令

常规权限模式：所有 Bash 命令即使沙箱化也要经过常规权限流程。这提供更多控制，但需要更多审批。

两种模式下，沙箱都强制执行相同的文件系统和网络限制。区别仅在于沙箱命令是自动批准还是需要显式权限。

有些命令完全无法在沙箱内运行，比如与沙箱不兼容的工具或需要访问未允许主机。为了避免任务失败或要求你关闭沙箱，Claude Code 提供一个逃生门：当命令因沙箱限制失败时，Claude 会分析失败原因并可能使用 dangerouslyDisableSandbox 参数重试该命令。重试的命令在沙箱外运行，因此会经过常规权限流程并需要你批准。

你可以通过将 allowUnsandboxedCommands 设为 false 来禁用此逃生门。禁用后，/sandbox 的 Overrides 标签页会显示为 Strict sandbox mode，dangerouslyDisableSandbox 参数会被完全忽略，所有命令要么在沙箱内运行，要么被显式列入 excludedCommands。

自动允许模式独立于你的权限模式设置。即使你没有处于"接受编辑"模式，启用自动允许后，沙箱内的 Bash 命令也会自动执行。这意味着在沙箱边界内修改文件的 Bash 命令会在没有提示的情况下执行，即使文件编辑工具通常需要批准。

配置文件系统权限 #

通过 settings.json 文件自定义沙箱行为。完整配置参考见设置。

默认情况下，沙箱命令只能写入当前工作目录。如果 kubectl、terraform 或 npm 等子进程命令需要写入项目目录以外的路径，使用 sandbox.filesystem.allowWrite 授予对特定路径的访问权限：

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

这些路径在 OS 级别强制执行，因此沙箱内运行的所有命令（包括其子进程）都会遵守。这是推荐的方式，当某个工具需要写入特定位置时，而不是用 excludedCommands 将工具完全排除在沙箱外。

当相同的 filesystem 数组在多个设置作用域中定义时，这些数组会合并：来自每个作用域的路径会组合起来，而不是互相替换。

路径前缀控制路径解析方式：

此语法与 Read/Edit 权限规则不同，后者使用 //path 表示绝对路径、/path 表示项目相对路径。沙箱文件系统路径使用标准惯例：/tmp/build 是绝对路径。

你还可以使用 sandbox.filesystem.denyWrite 和 sandbox.filesystem.denyRead 拒绝写入或读取访问，并使用 sandbox.filesystem.allowRead 在拒绝区域内重新允许特定路径。

下面的示例阻止读取整个 home 目录，同时仍然允许读取当前项目。请将它放在项目的 .claude/settings.json 中，因为相对路径 . 只有在配置位于项目设置时才解析为项目根目录：

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

allowRead 中的 . 解析为项目根目录，因为此配置位于项目设置中。如果你将同样的配置放在 ~/.claude/settings.json 中，. 将解析为 ~/.claude，项目文件仍会被 denyRead 规则阻止。

沙箱工作原理 #

文件系统隔离 #

沙箱 Bash 工具将文件系统访问限制到特定目录：

• 默认写入行为：对当前工作目录及其子目录具有读写访问权限
• 默认读取行为：对整个计算机具有读取访问权限，但某些拒绝目录除外。注意此默认值仍然允许读取凭证文件，如 ~/.aws/credentials 和 ~/.ssh/。将它们添加到 denyRead 以阻止。
• 阻止的访问：未经明确许可，无法修改当前工作目录之外的文件，包括 shell 配置文件（如 ~/.bashrc）和 /bin/ 中的系统二进制文件。
• 可配置：通过设置定义自定义的允许和拒绝路径。

你可以使用 sandbox.filesystem.allowWrite 授予对额外路径的写入访问权限。这些限制在 OS 级别强制执行，因此适用于所有子进程命令，包括 kubectl、terraform 和 npm，而不仅仅是 Claude 的文件工具。

网络隔离 #

网络访问通过沙箱外运行的代理服务器控制：

• 域名限制：没有预先允许的域名。第一次命令需要新域名时，Claude Code 会弹出批准提示。使用 allowedDomains 预先允许域名以避免提示。
• 托管锁定：如果在托管设置中设置了 allowManagedDomainsOnly，非允许域名会被自动阻止而不是提示，并且只采纳托管设置中的 allowedDomains。
• 自定义代理支持：高级用户可以实现对出站流量的自定义规则。
• 全面覆盖：限制适用于命令生成的所有脚本、程序和子进程。

内置代理根据请求的主机名强制执行允许列表，不终止也不检测 TLS 流量。关于此设计的影响，请参阅安全限制；如果你的威胁模型需要 TLS 检测，请参阅自定义代理配置。

OS 级强制执行 #

沙箱 Bash 工具利用操作系统的安全原语：

• macOS：使用 Seatbelt 进行沙箱强制执行
• Linux：使用 bubblewrap 进行隔离
• WSL2：使用 bubblewrap，与 Linux 相同

WSL1 不受支持，因为 bubblewrap 需要 WSL2 才有的内核特性。这些 OS 级限制确保 Claude Code 命令衍生的所有子进程继承相同的安全边界。

相同的原语也可作为独立的 @anthropic-ai/sandbox-runtime 包使用，沙箱环境 页面将其作为另一种隔离方式（包装整个 Claude Code 进程）进行介绍。

沙箱与权限规则、权限模式的关系 #

沙箱、权限规则和权限模式是互补的安全层。以下部分介绍沙箱如何与它们交互。

权限规则 #

权限规则和沙箱控制不同的内容：

• 权限规则控制 Claude Code 可以使用哪些工具，在每个工具运行前评估。它们适用于所有工具：Bash、Read、Edit、WebFetch、MCP 等。
• 沙箱提供 OS 级强制执行，限制 Bash 命令在文件系统和网络级别可以访问的内容。它仅适用于 Bash 命令及其子进程。

这两层在强制执行方式上也有不同。Claude Code 在命令运行前根据命令字符串以及（在自动模式下）分类器对命令安全性的判断来评估权限决策。操作系统在运行进程上强制执行沙箱边界，因此无论模型选择运行什么，即使允许的命令做了超出其名称暗示的操作，沙箱也会强制执行。

文件系统和网络限制通过沙箱设置和权限规则共同配置：

来自 sandbox.filesystem 设置和权限规则的路径会合并到最终的沙箱配置中。

claude-code 仓库的 examples 目录 包含常见部署场景的入门设置配置，包括沙箱特定的示例。以此作为起点并根据你的需求调整。

权限模式 #

/sandbox 不是一个权限模式。权限模式决定工具调用是否运行以及是否先提示你，而沙箱限制 Bash 命令运行后可以访问的内容。它们在控制内容以及替换单个提示的方式上有所不同：

沙箱的自动允许模式与自动模式是分开的：自动允许批准 Bash 命令是因为沙箱边界约束了它们，而自动模式使用分类器审查动作。两者独立工作，可以组合使用。要为无人值守运行选择隔离边界，请参阅沙箱环境。

为组织配置沙箱 #

管理员可以要求每个用户使用沙箱，阻止开发者放宽策略，以及通过企业代理路由沙箱流量。

通过托管设置强制执行沙箱 #

要要求每个开发者使用沙箱，通过托管设置交付 sandbox 键，可以是 MDM 管理的文件，也可以通过 Claude.ai 上的服务器托管设置。

以下托管设置配置启用沙箱，如果沙箱无法初始化则拒绝启动 Claude Code，并阻止模型在沙箱外重试命令：

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

除 enabled 之外的两个键控制沙箱无法运行命令时的行为：

• failIfUnavailable：如果缺少依赖（如 Linux 上的 bubblewrap），Claude Code 会阻塞启动，而不是显示警告并回退到无沙箱执行。
• allowUnsandboxedCommands: false：dangerouslyDisableSandbox 逃生门被忽略，因此沙箱内失败的命令无法在沙箱外重试。

另外两个设置值得一并考虑。为组织认可的需要无隔离运行的工具添加 excludedCommands。添加 denyRead 条目以阻止凭证目录（如 ~/.aws 和 ~/.ssh），因为默认读取策略仍然允许它们。

沙箱不在原生 Windows 上运行，因此如果你的机群包含 Windows 主机，请将此配置限定在 macOS 和 Linux 上，或让这些用户在 WSL2 或容器中运行 Claude Code。

阻止开发者放宽策略 #

对于布尔键（如 enabled 和 failIfUnavailable），Claude Code 使用托管值并忽略开发者设置的任何值。对于数组键（如 excludedCommands 和 allowRead），Claude Code 会合并每个作用域的条目，因此开发者可以添加条目来放宽策略。

在托管设置中将 allowManagedReadPathsOnly 设为 true，这样只采纳托管设置中的 allowRead 条目。用户、项目和本地 allowRead 条目会被忽略。这可以防止开发者将读取访问放宽到组织批准的路径之外。要以相同方式将网络域名锁定为托管值，设置 allowManagedDomainsOnly。

excludedCommands 没有等效的仅托管锁定，因此开发者始终可以添加条目以在沙箱外运行更多命令。请保持托管列表狭窄。

自定义代理配置 #

对于需要高级网络安全性的组织，可以实现自定义代理来：

• 解密和检测 HTTPS 流量
• 应用自定义过滤规则
• 记录所有网络请求
• 与现有安全基础设施集成

要将 Claude Code 指向你的代理，在沙箱设置中设置代理端口：

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

故障排除 #

某些命令在沙箱内会失败，尽管在沙箱外可以正常工作。以下修复涵盖最常见的场景。

• 命令因主机不允许错误失败：许多 CLI 工具需要访问特定主机。当提示时授予权限，即可将该主机添加到你的允许列表中，以后该工具就能在沙箱内运行。
• jest 挂起或失败：watchman 与沙箱不兼容。运行 jest --no-watchman 代替。
• 基于 Go 的 CLI 在 macOS 上 TLS 验证失败：工具如 gh、gcloud 和 terraform 可能在 Seatbelt 下 TLS 验证失败。将这些工具列入 excludedCommands 以在沙箱外运行。如果你正在使用 httpProxyPort 配合 MITM 代理和自定义 CA，可以将 enableWeakerNetworkIsolation 设为 true 作为替代方案。
• docker 命令失败：docker 与沙箱不兼容。将 docker * 添加到 excludedCommands 以在沙箱外运行。
• Bubblewrap 在容器内启动失败：在非特权容器中，bubblewrap 无法挂载全新的 /proc 文件系统。将 enableWeakerNestedSandbox 设为 true，这样内部沙箱会绑定挂载容器的现有 /proc。仅当外层容器已经提供了你所需的隔离边界时才使用此设置，因为这会向沙箱命令暴露进程信息，而全新的 /proc 挂载会隐藏这些信息。
• Linux 上的 seccomp 过滤器：seccomp 过滤器需要阻止 Unix 域套接字。/sandbox 中的 Dependencies 标签页会显示它是否可用。如果缺失，运行 npm install -g @anthropic-ai/sandbox-runtime 来安装辅助程序。
• --dangerously-skip-permissions 以 root 身份运行失败：此标志在 Linux 和 macOS 上以 root 身份或通过 sudo 运行时会被阻止，因为 root 权限加上无权限提示可以修改系统上的任何文件或服务。在已识别的沙箱内，此检查会自动跳过。要在容器中自主运行，请使用开发容器配置，该配置以非 root 用户运行 Claude Code。

限制 #

沙箱降低了风险，但不是完全的隔离边界。在依赖它作为硬性安全控制之前，请审阅以下限制。

安全限制 #

• 网络过滤：网络过滤系统通过限制进程可以连接到的域来工作。内置代理不对出站流量进行 TLS 终止或检测，因此加密连接的内容不会被检查。你负责确保策略中只允许受信任的域。

允许宽泛的域（如 github.com）可能会为数据外泄创造途径。由于代理只根据客户端提供的主机名做出允许决定而不检测 TLS，沙箱内运行的代码可能利用域前置或类似技术到达允许列表之外的主机。如果你的威胁模型需要更强的保证，请配置一个自定义代理来终止 TLS 并检测流量，并在沙箱内安装其 CA 证书。更强的 TLS 感知网络隔离是正在积极开发的领域。

• 通过 Unix 套接字的权限升级：allowUnixSockets 配置可能不经意地授予对强大系统服务的访问权限，这可能导致沙箱绕过。例如，允许访问 /var/run/docker.sock 实际上通过 Docker 套接字授予了对主机系统的访问权限。请仔细考虑你通过沙箱允许的任何 Unix 套接字。
• 文件系统权限升级：过于宽泛的文件系统写入权限可能导致权限升级攻击。允许写入包含 $PATH 中可执行文件的目录、系统配置目录或用户 shell 配置文件（如 .bashrc / .zshrc）可能会在其他用户或系统进程访问这些文件时导致不同安全上下文中的代码执行。
• Linux 沙箱强度：Linux 实现提供了强大的文件系统和网络隔离，但包含一个 enableWeakerNestedSandbox 模式，使其可以在没有特权命名空间的 Docker 环境中运行，或者在 Linux 主机上（其中非特权用户命名空间已通过 sysctl 禁用）。此选项大大削弱了安全性，只应在有其他隔离措施强制的情况下使用。
• 设置文件受保护：沙箱自动拒绝写入 Claude Code 的 settings.json 文件（每个作用域）和托管设置目录，因此沙箱命令无法修改自己的策略。

平台和工具兼容性 #

• 平台支持：支持 macOS、Linux 和 WSL2。WSL1 和原生 Windows 不受支持。
• 性能开销：极小，但某些文件系统操作可能稍慢。
• 工具兼容性：某些需要特定系统访问模式的工具可能需要配置调整，或者需要在沙箱外运行。

范围 #

沙箱隔离 Bash 子进程。其他工具在不同的边界下运行：

• 内置文件工具：Read、Edit 和 Write 直接使用权限系统，而不是通过沙箱运行。见权限。
• 计算机使用：当 Claude 打开应用并控制屏幕时，它在你的实际桌面上运行，而不是在隔离环境中。每个应用的权限提示控制应用访问。见 CLI 中的计算机使用 或 Desktop 中的计算机使用。
• 环境变量：沙箱 Bash 命令默认继承父进程的环境，包括其中设置的所有凭证。要从子进程中剥离 Anthropic 和云提供商凭证，设置 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB。
• 子代理：子代理在父会话的同一进程中运行，并使用相同的沙箱配置。当父会话启用了沙箱时，子代理内的 Bash 命令也会被沙箱化。

有效的沙箱需要同时具备文件系统和网络隔离。没有网络隔离，被攻破的 Agent 可以外泄敏感文件（如 SSH 密钥）。没有文件系统隔离，被攻破的 Agent 可以篡改系统资源以获取网络访问。当你放宽默认值时，请检查一个 allowWrite 路径、一个宽泛的 allowedDomains 条目或 excludedCommands 异常是否撤销了另一方的限制。

参见 #

• 沙箱环境：对比内置沙箱与开发容器、容器和虚拟机
• 安全：全面的安全特性和最佳实践
• 权限：权限配置和访问控制
• 设置：完整配置参考
• CLI 参考：命令行选项

常见问题 #

沙箱在 Windows 上能用吗？ #

不能。Claude Code 沙箱不支持原生 Windows，但可以在 WSL2 发行版内使用。WSL1 也不支持（bubblewrap 需要 WSL2 的内核特性）。在 WSL2 上，沙箱命令不能启动 Windows 二进制文件（如 cmd.exe），这些命令需要列入 excludedCommands 才能在沙箱外运行。

沙箱和 --dangerously-skip-permissions 有什么区别？ #

沙箱通过 OS 级边界限制命令可以访问的文件和网络，而 --dangerously-skip-permissions 会绕过所有权限提示，让工具调用直接运行。两者可以结合使用，但 --dangerously-skip-permissions 在 root 或 sudo 下会被阻止，因为无提示的 root 访问可以修改系统任何部分。沙箱的自动允许模式只适用于 Bash 命令，且由 OS 绑定保护。

为什么我的 kubectl 或 npm 在沙箱里写入失败？ #

默认情况下，沙箱内的命令只能写入当前工作目录。如果 kubectl 需要写 ~/.kube，或 npm 需要写 /tmp，请使用 sandbox.filesystem.allowWrite 添加这些路径。不要将整个工具排除沙箱（excludedCommands），除非必要，因为那样会失去所有沙箱保护。路径配置在 OS 级别生效，对所有子进程均有效。