配置官方原文

沙盒

了解 Claude Code 的沙盒 bash 工具如何提供文件系统和网络隔离，以实现更安全、更自主的代理执行。

了解 Claude Code 的沙盒 bash 工具如何提供文件系统和网络隔离，以实现更安全、更自主的代理执行。

概述

Claude Code 具有本机沙箱功能，可为代理执行提供更安全的环境，同时减少对持续权限提示的需求。沙箱无需为每个 bash 命令请求许可，而是预先创建定义的边界，使 Claude Code 可以在其中更自由地工作并降低风险。

沙盒 bash 工具使用操作系统级原语来强制文件系统和网络隔离。

为什么沙箱很重要

传统的基于权限的安全性需要用户不断批准 bash 命令。虽然这提供了控制，但可能会导致：

审批疲劳：重复点击“审批”可能会导致用户不太注意他们正在审批的内容
生产力降低：持续的中断会减慢开发工作流程
有限的自主权：Claude Code 在等待批准时无法高效工作

沙盒通过以下方式解决这些挑战：

定义明确的边界：准确指定 Claude Code 可以访问哪些目录和网络主机
减少权限提示：沙箱内的安全命令不需要批准
维护安全：尝试访问沙箱之外的资源会触发即时通知
实现自主性：Claude Code 可以在定义的限制内更独立地运行

警告

有效的沙箱需要**文件系统和网络隔离。如果没有网络隔离，受感染的代理可能会泄露 SSH 密钥等敏感文件。如果没有文件系统隔离，受感染的代理可能会为系统资源设置后门以获得网络访问权限。配置沙箱时，重要的是要确保您配置的设置不会在这些系统中创建绕过。

它是如何工作的

文件系统隔离

沙盒 bash 工具限制文件系统对特定目录的访问：

默认写入行为：对当前工作目录及其子目录的读写访问权限
默认读取行为：对整个计算机的读取访问权限，某些被拒绝的目录除外
阻止访问：未经明确许可，无法修改当前工作目录之外的文件
可配置：通过设置定义自定义允许和拒绝的路径

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

网络隔离

网络访问通过沙箱外部运行的代理服务器进行控制：* 域名限制：只有批准的域名才能访问

用户确认：新域请求会触发权限提示（除非启用 allowManagedDomainsOnly，这会自动阻止非允许的域）
自定义代理支持：高级用户可以对传出流量实施自定义规则
全面覆盖：限制适用于命令生成的所有脚本、程序和子进程

操作系统级强制执行

沙盒 bash 工具利用操作系统安全原语：

macOS：使用 Seatbelt 进行沙箱强制执行
Linux：使用 Bubblewrap 进行隔离
WSL2：使用气泡包装，与 Linux 相同

不支持 WSL1，因为 bubblewrap 需要仅在 WSL2 中提供的内核功能。

这些操作系统级别的限制可确保 Claude Code 命令生成的所有子进程继承相同的安全边界。

开始使用

先决条件

在 macOS 上，沙盒使用内置 Seatbelt 框架开箱即用。

在 Linux 和 WSL2 上，首先安装所需的软件包：

Ubuntu/Debian

sudo apt-get install bubblewrap socat

Fedora

sudo dnf install bubblewrap socat

启用沙箱

您可以通过运行 /sandbox 命令来启用沙箱：

/sandbox

这将打开一个菜单，您可以在其中选择沙盒模式。如果缺少所需的依赖项（例如 Linux 上的 bubblewrap 或 socat），菜单将显示适用于您的平台的安装说明。

沙盒模式

Claude Code 提供两种沙箱模式：

自动允许模式：Bash 命令将尝试在沙箱内运行，并且无需许可即可自动允许。无法沙箱化的命令（例如需要网络访问未经允许的主机的命令）将回退到常规权限流。您配置的显式询问/拒绝规则始终受到尊重。

常规权限模式：所有 bash 命令都会经过标准权限流程，即使在沙盒中也是如此。这提供了更多控制，但需要更多批准。

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

说明

自动允许模式的工作独立于您的权限模式设置。即使您未处于“接受编辑”模式，沙盒 bash 命令也会在启用自动允许时自动运行。这意味着修改沙箱边界内的文件的 bash 命令将在没有提示的情况下执行，即使文件编辑工具通常需要批准也是如此。

配置沙箱

通过 settings.json 文件自定义沙箱行为。请参阅设置以获取完整的配置参考。

授予子进程对特定路径的写访问权限

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

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "//tmp/build"]
    }
  }
}
```这些路径是在操作系统级别强制执行的，因此沙箱内运行的所有命令（包括其子进程）都会尊重它们。当工具需要对特定位置进行写访问时，这是推荐的方法，而不是使用 `excludedCommands` 将该工具完全从沙箱中排除。

当 `allowWrite`（或 `denyWrite`/`denyRead`/`allowRead`）在多个[设置范围](/docs/settings#settings-precedence) 中定义时，数组将被**合并**，这意味着来自每个范围的路径将被组合，而不是被替换。例如，如果托管设置允许写入 `//opt/company-tools`，并且用户在其个人设置中添加 `~/.kube`，则这两个路径都包含在最终沙箱配置中。这意味着用户和项目可以扩展列表，而无需复制或覆盖由更高优先级范围设置的路径。

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

|前缀 |意义|示例|
| :---------------- | :------------------------------------------ | :------------------------------------ |
| `//` |从文件系统根目录开始的绝对路径 | `//tmp/build` 变为 `/tmp/build` |
| `~/` |相对于主目录 | `~/.kube` 变为 `$HOME/.kube` |
| `/` |相对于设置文件的目录 | `/build` 变为 `$SETTINGS_DIR/build` |
| `./` 或无前缀 |相对路径（由沙箱运行时解析）| `./output` |

您还可以使用 `sandbox.filesystem.denyWrite` 和 `sandbox.filesystem.denyRead` 拒绝写入或读取访问。它们与 `Edit(...)` 和 `Read(...)` 权限规则中的任何路径合并。要重新允许读取被拒绝区域内的特定路径，请使用 `sandbox.filesystem.allowRead`，它优先于 `denyRead`。当在托管设置中启用 `allowManagedReadPathsOnly` 时，仅考虑托管 `allowRead` 条目；用户、项目和本地 `allowRead` 条目将被忽略。

例如，要阻止从整个主目录读取，同时仍允许从当前项目读取：

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

提示

并非所有命令都与开箱即用的沙箱兼容。一些可以帮助您充分利用沙箱的注意事项：

许多 CLI 工具需要访问某些主机。当您使用这些工具时，它们将请求访问某些主机的权限。授予权限将允许他们现在和将来访问这些主机，使他们能够在沙箱内安全地执行。
watchman 与沙箱中运行不兼容。如果您运行的是 jest，请考虑使用 jest --no-watchman
docker 与沙箱中运行不兼容。考虑在 excludedCommands 中指定 docker 以强制其在沙箱之外运行。

注意Claude Code 包括一个有意的逃生舱口机制，允许命令在必要时在沙箱外运行。当命令由于沙箱限制（例如网络连接问题或不兼容的工具）而失败时，系统会提示 Claude 分析故障，并可能使用 dangerouslyDisableSandbox 参数重试该命令。使用此参数的命令会经历正常的 Claude Code 权限流程，需要用户权限才能执行。这使得 Claude Code 能够处理某些工具或网络操作无法在沙箱限制内运行的边缘情况。

您可以通过在沙盒设置中设置 "allowUnsandboxedCommands": false 来禁用此逃生舱口。禁用后，dangerouslyDisableSandbox 参数将被完全忽略，所有命令都必须在沙盒中运行或在 excludedCommands 中显式列出。

安全优势

防止提示注入

即使攻击者通过提示注入成功操纵 Claude Code 的行为，沙箱也会确保您的系统保持安全：

文件系统保护：

无法修改关键配置文件，例如 ~/.bashrc
无法修改/bin/中的系统级文件
无法读取 Claude 权限设置中拒绝的文件

网络保护：

无法将数据泄露到攻击者控制的服务器
无法从未经授权的域下载恶意脚本
无法对未经批准的服务进行意外的 API 调用
无法联系任何未明确允许的域

监测和控制：

沙箱之外的所有访问尝试都会在操作系统级别被阻止
当边界被测试时您会立即收到通知
您可以选择拒绝、允许一次或永久更新您的配置

减少攻击面

沙箱限制了以下潜在损害：

恶意依赖项：NPM 包或其他包含有害代码的依赖项
受损脚本：构建具有安全漏洞的脚本或工具
社会工程：诱骗用户运行危险命令的攻击
提示注入：欺骗 Claude 运行危险命令的攻击

透明操作

当Claude Code尝试访问沙箱外的网络资源时：

操作在操作系统级别被阻止
您会立即收到通知
您可以选择：
- 拒绝请求
- 允许一次
- 更新您的沙箱配置以永久允许它

安全限制

网络沙盒限制：网络过滤系统通过限制允许进程连接的域来运行。它不会以其他方式检查通过代理的流量，用户负责确保他们在其策略中只允许受信任的域。

警告

用户应该意识到允许 github.com 等可能允许数据泄露的广泛域带来的潜在风险。此外，在某些情况下，可能可以通过域前置绕过网络过滤。* 通过 Unix 套接字进行权限升级：allowUnixSockets 配置可能会无意中授予对强大系统服务的访问权限，从而导致沙箱绕过。例如，如果它用于允许访问 /var/run/docker.sock，这将通过利用 docker 套接字有效地授予对主机系统的访问权限。我们鼓励用户仔细考虑允许通过沙箱的任何 UNIX 套接字。

文件系统权限升级：过于广泛的文件系统写入权限可能会导致权限升级攻击。允许写入 $PATH 中包含可执行文件的目录、系统配置目录或用户 shell 配置文件（.bashrc、.zshrc）可能会导致当其他用户或系统进程访问这些文件时在不同的安全上下文中执行代码。
Linux 沙箱强度：Linux 实现提供强大的文件系统和网络隔离，但包括 enableWeakerNestedSandbox 模式，使其能够在没有特权命名空间的 Docker 环境中工作。此选项会大大削弱安全性，并且仅应在以其他方式强制实施额外隔离的情况下使用。

沙箱与权限的关系

沙盒和权限是互补的安全层，可以协同工作：

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

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

使用 sandbox.filesystem.allowWrite 授予子进程对工作目录之外的路径的写访问权限
使用 sandbox.filesystem.denyWrite 和 sandbox.filesystem.denyRead 阻止子进程访问特定路径
使用 sandbox.filesystem.allowRead 重新允许读取 denyRead 区域内的特定路径
使用 Read 和 Edit 拒绝规则阻止对特定文件或目录的访问
使用WebFetch允许/拒绝规则来控制域访问
使用沙箱 allowedDomains 控制 Bash 命令可以到达哪些域

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

此存储库包含常见部署场景的入门设置配置，包括特定于沙箱的示例。使用这些作为起点并调整它们以满足您的需求。

高级用法

自定义代理配置

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

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

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

与现有安全工具集成

沙盒 bash 工具与以下工具一起工作：* 权限规则：结合【权限设置】(/docs/permissions)进行纵深防御

开发容器：与 devcontainers 一起使用以实现额外隔离
企业策略：通过托管设置强制执行沙箱配置

最佳实践

开始限制性：从最小权限开始，然后根据需要扩展
监控日志：查看沙盒违规尝试以了解 Claude Code 的需求
使用特定于环境的配置：开发环境与生产环境的不同沙箱规则
与权限结合：将沙盒与 IAM 策略结合使用以实现全面的安全性
测试配置：验证您的沙箱设置不会阻止合法的工作流程

开源

沙盒运行时可作为开源 npm 包在您自己的代理项目中使用。这使得更广泛的人工智能代理社区能够构建更安全、更可靠的自主系统。这也可以用于沙箱您可能希望运行的其他程序。例如，要将 MCP 服务器沙箱化，您可以运行：

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

有关实现细节和源代码，请访问 GitHub 存储库。

限制

性能开销：最小，但某些文件系统操作可能会稍微慢一些
兼容性：一些需要特定系统访问模式的工具可能需要配置调整，甚至可能需要在沙箱之外运行
平台支持：支持 macOS、Linux 和 WSL2。不支持 WSL1。计划提供本机 Windows 支持。

另请参阅

安全 - 全面的安全功能和最佳实践
权限 - 权限配置和访问控制
设置 - 完整配置参考
CLI 参考 - 命令行选项