文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

配置沙箱 Bash 工具

了解 Claude Code 的沙箱 Bash 工具如何提供文件系统和网络隔离，以实现更安全、更自主的智能体执行。

Bash 沙箱让 Claude 无需停下来请求许可即可运行大多数 shell 命令。你不需要批准每个命令，而是定义命令可以访问哪些文件和网络域名，操作系统为每个 Bash 命令及其子进程强制执行该边界。

本页面涵盖如何：

• 启用沙箱并选择沙箱命令的批准方式
• 配置命令可以访问的路径和网络域名
• 将沙箱与权限规则和权限模式结合
• 在组织中强制执行沙箱使用托管设置

快速开始

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

在 macOS 上，无需安装：沙箱使用内置的 Seatbelt 框架。在 Linux 和 WSL2 上，沙箱依赖两个包，在设置 Linux 和 WSL2 中介绍。即使你还没有安装它们，你也可以从 /sandbox 开始，因为它的面板会显示是否缺少任何东西。

1. 运行 /sandbox

   启动 Claude Code 会话并运行 /sandbox 命令：

   /sandbox
   

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

   • 模式：选择沙箱命令的批准方式，在下一步中介绍
   • 覆盖：选择在沙箱下失败的命令是否可以回退到非沙箱运行。这是 allowUnsandboxedCommands 设置
   • 配置：查看解析后的沙箱设置

   如果面板仅显示依赖标签页，则缺少必需的包。按照设置 Linux 和 WSL2 中的说明安装它，重启 Claude Code 并再次运行 /sandbox。

2. 选择模式

   在模式标签页上，选择自动允许或常规权限。自动允许无需提示即可运行沙箱命令，常规权限即使命令被沙箱化也保持常规权限提示。参见沙箱模式了解哪些命令在自动允许模式下仍会提示。

3. 运行 Bash 命令

   要求 Claude 运行命令，如构建或测试套件。默认情况下，沙箱内的命令只能写入工作目录。当命令首次需要新的网络域名时，Claude Code 会提示批准。

   无法在沙箱中运行的命令会回退到常规权限流程。要扩大或缩小这些边界，请参见配置沙箱。

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

设置 Linux 和 WSL2

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

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

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

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

安装后，/sandbox 中的依赖标签页会显示 ripgrep、bubblewrap、socat 和 seccomp 过滤器是否在你的平台上可用。Ripgrep 随原生 Claude Code 二进制文件捆绑。seccomp 过滤器是可选的，添加 Unix 域套接字阻止。如果缺失，使用 npm install -g @anthropic-ai/sandbox-runtime 安装。

当缺少必需的依赖时，依赖标签页是唯一显示的标签页，直到你安装它。依赖检查在启动时运行，因此安装包后重启 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 命令仍会触发权限提示
• 询问规则适用于回退到常规权限流程的命令

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

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

某些命令根本无法在沙箱内运行，如与沙箱不兼容的工具或需要你未允许的主机的工具。Claude Code 不会失败任务或要求你关闭沙箱，而是包含一个逃生通道：当命令因沙箱限制而失败时，Claude 分析失败原因并可能使用 dangerouslyDisableSandbox 参数重试命令。重试的命令在沙箱外运行，因此它经过常规权限流程并需要你的批准。

你可以通过在沙箱设置中设置 "allowUnsandboxedCommands": false 来禁用此逃生通道。禁用后（/sandbox 覆盖标签页显示为 Strict sandbox mode），dangerouslyDisableSandbox 参数被完全忽略，所有命令必须在沙箱中运行或明确列在 excludedCommands 中。

配置沙箱

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

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

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

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

当同一个文件系统数组在多个设置范围中定义时，数组会合并：来自每个范围的路径会被组合，而不是替换。

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

此语法不同于读取和编辑权限规则，后者使用 //path 表示绝对路径，/path 表示项目相对路径。沙箱文件系统路径使用标准约定：/tmp/build 是绝对路径。

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

以下示例阻止从整个主目录读取，同时仍允许从当前项目读取。将其放在项目的 .claude/settings.json 中，因为相对路径 . 仅在配置位于项目设置中时才解析为项目根目录：

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

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

沙箱工作原理

文件系统隔离

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

• 默认写入行为：对当前工作目录及其子目录的读写访问
• 默认读取行为：对整个计算机的读取访问，某些拒绝目录除外。注意此默认值仍允许读取凭据文件（如 ~/.aws/credentials 和 ~/.ssh/）。将它们添加到 denyRead 以阻止。
• 被阻止的访问：无法在没有显式许可的情况下修改当前工作目录外的文件，包括 shell 配置文件（如 ~/.bashrc）和 /bin/ 中的系统二进制文件
• Git 工作树：当工作目录是链接的 git 工作树时，沙箱还允许写入主仓库的共享 .git 目录，以便 git commit 等命令可以更新引用和索引。对该目录内 hooks/ 和 config 的写入仍然被拒绝。
• 可配置：通过设置定义自定义允许和拒绝路径

你可以使用设置中的 sandbox.filesystem.allowWrite 授予对其他路径的写入访问。这些限制在操作系统级别强制执行，因此它们适用于所有子进程命令，包括 kubectl、terraform 和 npm 等工具，而不仅仅是 Claude 的文件工具。

网络隔离

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

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

操作系统级强制执行

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

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

WSL1 不受支持，因为 bubblewrap 需要 WSL2 中才有的内核功能。这些操作系统级限制确保 Claude Code 命令生成的所有子进程继承相同的安全边界。

这些相同的原语作为独立的 @anthropic-ai/sandbox-runtime 包可用，沙箱环境页面将其作为包装整个 Claude Code 进程的单独方法进行介绍。

沙箱与权限和权限模式的关系

沙箱、权限规则和权限模式是互补的层。以下各节介绍沙箱如何与每个交互。

权限规则

权限规则和沙箱控制不同的东西：

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

两层在强制执行方式上也不同。Claude Code 在命令运行前评估权限决定，基于命令字符串和（在自动模式中）单独分类器关于命令是否安全的判断。操作系统在运行进程上强制执行沙箱边界，因此无论模型选择运行什么，甚至即使允许的命令做了超出其名称暗示的事情，它都有效。

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

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

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

权限模式

/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。为凭据目录（如 ~/.aws 和 ~/.ssh）添加 denyRead 条目，默认读取策略仍允许这些目录。

沙箱不在原生 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
    }
  }
}

故障排除

某些命令在沙箱内失败，即使它们在沙箱外工作。以下修复涵盖最常见的情况。

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

限制

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

安全限制

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

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

平台和工具兼容性

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

范围

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

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

另请参阅

• 沙箱环境：将内置沙箱与开发容器、容器和 VM 进行比较
• 安全：全面的安全功能和最佳实践
• 权限：权限配置和访问控制
• 设置：完整的配置参考
• CLI 参考：命令行选项