{/* TRANSLATED — 已翻译为中文 */}

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

# 配置沙箱 Bash 工具

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

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

本页面涵盖如何：

* [启用沙箱](#get-started)并选择沙箱命令的批准方式
* [配置](#configure-sandboxing)命令可以访问的路径和网络域名
* [将沙箱与权限规则和权限模式结合](#how-sandboxing-relates-to-permissions-and-permission-modes)
* [在组织中强制执行沙箱](#configure-the-sandbox-for-your-organization)使用托管设置

<Note>
  要比较其他隔离方法（如开发容器、自定义容器和虚拟机），请参见[沙箱环境](/en/sandbox-environments)。要减少 Bash 以外工具的权限提示，请参见[权限模式](/en/permission-modes)。
</Note>

## 快速开始

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

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

<Steps>
  <Step title="运行 /sandbox">
    启动 Claude Code 会话并运行 `/sandbox` 命令：

    ```text theme={null}
    /sandbox
    ```

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

    * **模式**：选择沙箱命令的批准方式，在下一步中介绍
    * **覆盖**：选择在沙箱下失败的命令是否可以回退到非沙箱运行。这是 [`allowUnsandboxedCommands`](/en/settings#sandbox-settings) 设置
    * **配置**：查看解析后的沙箱设置

    如果面板仅显示依赖标签页，则缺少必需的包。按照[设置 Linux 和 WSL2](#set-up-linux-and-wsl2) 中的说明安装它，重启 Claude Code 并再次运行 `/sandbox`。
  </Step>

  <Step title="选择模式">
    在模式标签页上，选择自动允许或常规权限。自动允许无需提示即可运行沙箱命令，常规权限即使命令被沙箱化也保持常规权限提示。参见[沙箱模式](#sandbox-modes)了解哪些命令在自动允许模式下仍会提示。
  </Step>

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

    无法在沙箱中运行的命令会回退到常规权限流程。要扩大或缩小这些边界，请参见[配置沙箱](#configure-sandboxing)。
  </Step>
</Steps>

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

<Warning>
  默认情况下，如果沙箱因缺少依赖或平台不支持而无法启动，Claude Code 会显示警告并在没有沙箱的情况下运行命令。要使其成为硬性失败，将 [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) 设置为 `true`。这适用于需要沙箱作为安全门控的托管部署。
</Warning>

### 设置 Linux 和 WSL2

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

* [`bubblewrap`](https://github.com/containers/bubblewrap)：强制执行文件系统隔离的非特权沙箱工具
* [`socat`](http://www.dest-unreach.org/socat/)：用于通过沙箱代理路由网络流量的中继

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

<Tabs>
  <Tab title="Ubuntu/Debian">
    ```bash theme={null}
    sudo apt-get install bubblewrap socat
    ```
  </Tab>

  <Tab title="Fedora">
    ```bash theme={null}
    sudo dnf install bubblewrap socat
    ```
  </Tab>
</Tabs>

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

当缺少必需的依赖时，依赖标签页是唯一显示的标签页，直到你安装它。依赖检查在启动时运行，因此安装包后重启 Claude Code 以便 `/sandbox` 检测它们。

<AccordionGroup>
  <Accordion title="Ubuntu 24.04 及更高版本：允许 bubblewrap 创建用户命名空间">
    在 Ubuntu 24.04 及更高版本上，默认的 AppArmor 策略阻止 bubblewrap 创建隔离所需的用户命名空间。

    要检查你的环境是否强制执行此限制（包括在 WSL2 内），运行 `sysctl kernel.apparmor_restrict_unprivileged_userns`。如果键不存在或返回 `0`，跳过此步骤。如果返回 `1`，添加一个授予 `bwrap` 此功能的 AppArmor 配置文件：

    ```bash theme={null}
    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
    ```

    配置文件仅适用于 `bwrap` 本身，不适用于它在沙箱内运行的命令。重新加载 AppArmor 以应用它：

    ```bash theme={null}
    sudo systemctl reload apparmor
    ```
  </Accordion>

  <Accordion title="WSL2 注意事项">
    从 PowerShell 使用 `wsl -l -v` 检查你的 WSL 版本。如果你看到 `Sandboxing requires WSL2`，你的发行版正在运行 WSL1。将其升级到 WSL2 或在没有沙箱的情况下运行 Claude Code。

    在 WSL2 上，沙箱命令无法启动 Windows 二进制文件（如 `cmd.exe`、`powershell.exe` 或 `/mnt/c/` 下的任何内容）。WSL 通过 Unix 套接字将这些传递给 Windows 主机，沙箱会阻止。如果命令需要调用 Windows 二进制文件，将其添加到 [`excludedCommands`](/en/settings#sandbox-settings) 以便在沙箱外运行。
  </Accordion>
</AccordionGroup>

### 沙箱模式

Claude Code 提供两种沙箱模式：

**自动允许模式**：Bash 命令将尝试在沙箱内运行，并自动允许，无需请求许可。无法被沙箱化的命令（如需要访问未允许主机的网络）会回退到常规权限流程，Claude Code 检查你的[权限规则](/en/permissions)并提示你任何这些规则尚未允许的命令。

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

* 显式的[拒绝规则](/en/permissions)始终被遵守
* 针对 `/`、你的主目录或其他关键系统路径的 `rm` 或 `rmdir` 命令仍会触发权限提示
* [询问规则](/en/permissions)适用于回退到常规权限流程的命令

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

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

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

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

<Info>
  自动允许模式独立于你的权限模式设置。即使你不在 "accept edits" 模式中，启用自动允许后沙箱化的 Bash 命令也会自动运行。这意味着修改沙箱边界内文件的 Bash 命令将无需提示即可执行，即使文件编辑工具通常需要批准。
</Info>

## 配置沙箱

通过你的 `settings.json` 文件自定义沙箱行为。参见[设置](/en/settings#sandbox-settings)了解完整的配置参考。

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

```json theme={null}
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}
```

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

当同一个文件系统数组在多个[设置范围](/en/settings#settings-precedence)中定义时，数组会合并：来自每个范围的路径会被组合，而不是替换。

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

| 前缀 | 含义 | 示例 |
| :--- | :--- | :--- |
| `/` | 文件系统根目录的绝对路径 | `/tmp/build` 保持 `/tmp/build` |
| `~/` | 相对于主目录 | `~/.kube` 变为 `$HOME/.kube` |
| `./` 或无前缀 | 项目设置相对于项目根目录，用户设置相对于 `~/.claude` | `.claude/settings.json` 中的 `./output` 解析为 `<project-root>/output` |

此语法不同于[读取和编辑权限规则](/en/permissions#read-and-edit)，后者使用 `//path` 表示绝对路径，`/path` 表示项目相对路径。沙箱文件系统路径使用标准约定：`/tmp/build` 是绝对路径。

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

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

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

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

## 沙箱工作原理

### 文件系统隔离

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

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

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

### 网络隔离

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

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

<Note>
  内置代理基于请求的主机名强制执行白名单，不会终止或检查 TLS 流量。参见[安全限制](#security-limitations)了解此设计的影响，如果你的威胁模型需要 TLS 检查，请参见[自定义代理配置](#custom-proxy-configuration)。
</Note>

### 操作系统级强制执行

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

* **macOS**：使用 Seatbelt 进行沙箱强制执行
* **Linux**：使用 [bubblewrap](https://github.com/containers/bubblewrap) 进行隔离
* **WSL2**：使用 bubblewrap，与 Linux 相同

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

这些相同的原语作为独立的 [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) 包可用，[沙箱环境](/en/sandbox-environments#sandbox-runtime)页面将其作为包装整个 Claude Code 进程的单独方法进行介绍。

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

沙箱、[权限规则](/en/permissions)和[权限模式](/en/permission-modes)是互补的层。以下各节介绍沙箱如何与每个交互。

### 权限规则

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

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

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

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

| 设置或规则 | 作用 |
| :--- | :--- |
| `sandbox.filesystem.allowWrite` | 授予子进程对工作目录外路径的写入访问 |
| `sandbox.filesystem.denyWrite` 和 `sandbox.filesystem.denyRead` | 阻止子进程对特定路径的访问 |
| `sandbox.filesystem.allowRead` | 在 `denyRead` 区域内重新允许读取特定路径 |
| `Edit` 允许规则 | 授予对特定路径的写入访问，与 `sandbox.filesystem.allowWrite` 相同 |
| `Read` 和 `Edit` 拒绝规则 | 阻止对特定文件或目录的访问 |
| `WebFetch` 允许和拒绝规则 | 控制域名访问 |
| 沙箱 `allowedDomains` | 控制 Bash 命令可以访问哪些域名 |
| 沙箱 `deniedDomains` | 阻止特定域名，即使更宽泛的 `allowedDomains` 通配符会允许它们 |

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

[claude-code 仓库的示例目录](https://github.com/anthropics/claude-code/tree/main/examples/settings)包含常见部署场景的入门设置配置，包括沙箱特定的示例。将这些作为起点并调整以适应你的需求。

### 权限模式

`/sandbox` 不是[权限模式](/en/permission-modes)。权限模式决定工具调用是否运行以及是否先提示你，而沙箱限制 Bash 命令运行后可以访问的内容。它们在控制内容和替代每次操作提示的内容方面不同：

| | 控制内容 | 替代提示的内容 |
| :--- | :--- | :--- |
| `/sandbox` | Bash 命令运行后可以访问的内容 | 沙箱边界本身，在[自动允许模式](#sandbox-modes)中 |
| [自动模式](/en/permission-modes#eliminate-prompts-with-auto-mode) | 每个工具调用是否运行 | 审查操作的分类器 |
| `--dangerously-skip-permissions` | 每个工具调用是否运行 | 无。[受保护路径](/en/permission-modes#protected-paths)检查也被跳过；仅删除 `/` 或你的主目录仍会提示 |

沙箱的[自动允许模式](#sandbox-modes)与[自动模式](/en/permission-modes#eliminate-prompts-with-auto-mode)是分开的：自动允许批准 Bash 命令是因为沙箱边界包含它们，而自动模式使用分类器审查操作。两者独立工作，可以组合。要为无人值守运行选择隔离边界，请参见[沙箱环境](/en/sandbox-environments#how-isolation-relates-to-permission-modes)。

## 为你的组织配置沙箱

管理员可以为每个用户要求沙箱，防止开发者扩大策略，并通过企业代理路由沙箱流量。

### 使用托管设置强制执行沙箱

要为每个开发者要求沙箱，通过[托管设置](/en/settings#settings-files)传递 `sandbox` 键，可以是 MDM 管理的文件或通过 Claude.ai 上的[服务器托管设置](/en/server-managed-settings)。

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

```json theme={null}
{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}
```

`enabled` 之外的两个键控制沙箱无法运行命令时发生什么：

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

有两个补充项值得考虑。为任何组织批准的必须在没有隔离的情况下运行的工具添加 `excludedCommands`。为凭据目录（如 `~/.aws` 和 `~/.ssh`）添加 [`denyRead`](#filesystem-isolation) 条目，默认读取策略仍允许这些目录。

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

### 防止开发者扩大策略

对于布尔键（如 `enabled` 和 `failIfUnavailable`），Claude Code 使用托管值并忽略开发者在本地设置的任何内容。对于数组键（如 `excludedCommands` 和 `allowRead`），Claude Code 合并来自每个范围的条目，因此开发者可以追加扩大策略的条目。

在托管设置中将 `allowManagedReadPathsOnly` 设置为 `true`，以便只遵守来自托管设置的 `allowRead` 条目。用户、项目和本地的 `allowRead` 条目被忽略。这可以防止开发者将读取访问扩大到超出组织批准的路径。要以相同方式将网络域名锁定到托管值，设置 [`allowManagedDomainsOnly`](/en/settings#sandbox-settings)。

`excludedCommands` 没有等效的仅托管锁定，因此开发者总是可以追加在沙箱外运行额外命令的条目。保持托管列表窄范围。

### 自定义代理配置

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

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

要将 Claude Code 指向你的代理，在[沙箱设置](/en/settings#sandbox-settings)中设置代理端口：

```json theme={null}
{
  "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`](/en/settings#sandbox-settings) 设置为 `true`。
* **`docker` 命令失败**：`docker` 与沙箱不兼容。将 `docker *` 添加到 `excludedCommands` 以在沙箱外运行。
* **Bubblewrap 在容器内启动失败**：在非特权容器中，bubblewrap 无法挂载新的 `/proc` 文件系统。将 [`enableWeakerNestedSandbox`](/en/settings#sandbox-settings) 设置为 `true`，使内部沙箱绑定挂载容器现有的 `/proc`。仅在外部容器已提供你所需的隔离边界时使用此设置，因为它会向沙箱命令暴露新 `/proc` 挂载会隐藏的进程信息。
* **Linux 上的 seccomp 过滤器**：seccomp 过滤器是阻止 Unix 域套接字所必需的。`/sandbox` 中的依赖标签页显示它是否可用。如果缺失，运行 `npm install -g @anthropic-ai/sandbox-runtime` 安装助手。
* **`--dangerously-skip-permissions` 以 root 失败**：此标志在 Linux 和 macOS 上以 root 或通过 sudo 运行时被阻止，因为 root 访问加上无权限提示可以修改系统上的任何文件或服务。在识别的沙箱内自动跳过检查。要在容器中自主运行，请使用[开发容器](/en/devcontainer)配置，它以非 root 用户运行 Claude Code。

## 限制

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

### 安全限制

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

<Warning>
  允许像 `github.com` 这样的宽泛域名可以为数据泄露创建路径。因为代理根据客户端提供的主机名做出允许决定而不检查 TLS，沙箱内运行的代码可能使用[域前置](https://en.wikipedia.org/wiki/Domain_fronting)或类似技术访问白名单外的主机。如果你的威胁模型需要更强的保证，请配置[自定义代理](#custom-proxy-configuration)以终止 TLS 并检查流量，并在沙箱内安装其 CA 证书。更强的 TLS 感知网络隔离是正在积极开发的领域。
</Warning>

* **通过 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 直接使用权限系统，而不是通过沙箱运行。参见[权限](/en/permissions)。
* **计算机使用**：当 Claude 打开应用并控制你的屏幕时，它在你的实际桌面上运行，而不是在隔离环境中。每个应用的权限提示门控每个应用程序。参见[CLI 中的计算机使用](/en/computer-use)或[桌面应用中的计算机使用](/en/desktop#let-claude-use-your-computer)。
* **环境变量**：沙箱 Bash 命令默认继承父进程环境，包括其中设置的任何凭据。要从子进程中剥离 Anthropic 和云提供商凭据，设置 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/en/env-vars)。
* **子智能体**：[子智能体](/en/sub-agents)在与父会话相同的进程中运行，使用相同的沙箱配置。当父会话中启用沙箱时，子智能体内的 Bash 命令被沙箱化。

<Warning>
  有效的沙箱需要文件系统和网络隔离。没有网络隔离，被入侵的智能体可以泄露 SSH 密钥等敏感文件。没有文件系统隔离，被入侵的智能体可以给系统资源植入后门以获得网络访问。当你扩大默认值时，检查 `allowWrite` 路径、宽泛的 `allowedDomains` 条目或 `excludedCommands` 例外是否不会取消另一侧的限制。
</Warning>

## 另请参阅

* [沙箱环境](/en/sandbox-environments)：将内置沙箱与开发容器、容器和 VM 进行比较
* [安全](/en/security)：全面的安全功能和最佳实践
* [权限](/en/permissions)：权限配置和访问控制
* [设置](/en/settings)：完整的配置参考
* [CLI 参考](/en/cli-reference)：命令行选项