配置沙箱化 Bash 工具

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

​

入门

/sandbox

​

设置 Linux 和 WSL2

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

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

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

​

沙箱模式

• 显式 deny rules 始终被尊重
• 针对 /、你的主目录或其他关键系统路径的 rm 或 rmdir 命令仍会触发权限提示
• Ask rules 适用于回退到常规权限流程的命令

​

配置沙箱

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

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

​

沙箱如何工作

​

文件系统隔离

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

​

网络隔离

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

​

操作系统级强制执行

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

​

沙箱如何与权限和权限模式相关

​

权限规则

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

​

权限模式

​

为你的组织配置沙箱

​

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

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

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

​

防止开发者扩大策略

​

自定义代理配置

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

{
  "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 访问加上没有权限提示可以修改系统上的任何文件或服务。检查在识别的沙箱内自动跳过。要在容器中自主运行，请使用 dev container 配置，它以非 root 用户身份运行 Claude Code。

​

限制

​

安全限制

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

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

​

平台和工具兼容性

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

​

范围

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

​

另请参阅

• Sandbox environments：比较内置沙箱与开发容器、容器和虚拟机
• Security：全面的安全功能和最佳实践
• Permissions：权限配置和访问控制
• Settings：完整的配置参考
• CLI reference：命令行选项