Claude Code 沙箱通过 OS 级隔离（macOS 用 Seatbelt，Linux 用 bubblewrap）限制 AI Agent 的文件系统和网络访问范围，在减少频繁权限提示的同时防范 Prompt 注入攻击。沙箱允许读取项目目录和必要系统路径，禁止写入敏感区域，可配置网络策略。通过 --sandbox 标志或 settings.json 启用，支持按项目定制允许/拒绝规则。适合团队和企业场景下对 AI 自主操作的安全管控。

沙箱隔离

Claude Code 的沙箱功能通过 OS 级隔离为 Agent 执行提供更安全的环境，同时减少频繁的权限提示。

为什么需要沙箱？

传统的权限安全模式需要用户对每个 Bash 命令逐一审批。虽然提供了控制，但会导致：

审批疲劳：反复点击"确认"会让用户不再仔细审查内容
降低效率：频繁中断拖慢开发节奏
限制自主性：Claude Code 需要等待审批，无法高效工作

沙箱通过以下方式解决这些问题：

定义明确边界：指定 Claude Code 可以访问的目录和网络主机
减少权限提示：沙箱内的安全命令不需要审批
维护安全性：尝试访问沙箱外的资源会立即通知用户
启用自主性：Claude Code 可以在定义的边界内独立工作

重要警告：有效的沙箱需要同时启用文件系统和网络隔离。只有网络隔离时，被攻击的 Agent 可能通过读取 SSH 密钥等文件泄露数据；只有文件系统隔离时，被攻击的 Agent 可能篡改系统资源获取网络访问权限。

工作原理

文件系统隔离

沙箱限制文件系统访问：

默认写入：读写当前工作目录及其子目录
默认读取：读取整台电脑的文件，但特定目录除外
阻止：无法修改工作目录外的文件（除非明确授权）

可以通过 sandbox.filesystem.allowWrite 设置添加额外的写权限路径。这些限制在 OS 级别强制执行，对所有子进程有效，包括 kubectl、terraform、npm 等工具。

网络隔离

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

域名限制：只允许访问批准的域名
用户确认：新域名请求触发权限提示（除非启用 allowManagedDomainsOnly）
自定义代理：支持实现自定义出口流量规则
全面覆盖：限制适用于所有脚本、程序和子进程

OS 级强制执行

平台	技术
macOS	Seatbelt 沙箱框架
Linux	bubblewrap
WSL2	bubblewrap（与 Linux 相同）

WSL1 不支持：bubblewrap 需要 WSL2 才有的内核特性。

所有由 Claude Code 命令衍生的子进程都继承相同的安全边界。

快速开始

前提条件

macOS：开箱即用，使用内置 Seatbelt 框架。

Linux / WSL2：需要先安装必要包：

Ubuntu/Debian：

bash

sudo apt-get install bubblewrap socat

Fedora：

bash

sudo dnf install bubblewrap socat

启用沙箱

运行 /sandbox 命令打开配置菜单：

/sandbox

如果缺少依赖（如 Linux 上的 bubblewrap 或 socat），菜单会显示安装说明。

默认情况下，如果沙箱无法启动（缺少依赖、平台不支持），Claude Code 会显示警告并在无沙箱状态下运行命令。如果需要强制要求沙箱（管理部署的安全门控），可以将 sandbox.failIfUnavailable 设为 true，届时沙箱不可用会直接报错退出。

沙箱模式

自动允许模式：Bash 命令在沙箱中自动允许执行，无需权限确认。无法沙箱化的命令（如需要访问非允许主机）回退到正常权限流程。你配置的显式 ask/deny 规则始终有效。

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

自动允许模式独立于你的权限模式设置。即使不在"accept edits"模式，沙箱中的 Bash 命令也会自动执行——包括在沙箱边界内修改文件的命令。

配置文件系统权限

通过 settings.json 自定义沙箱行为：

允许子进程写入特定路径

默认情况下，沙箱命令只能写入工作目录。如果 kubectl、terraform 或 npm 需要写入项目目录外的路径：

json

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

路径前缀规则：

前缀	含义	示例
`/`	从文件系统根的绝对路径	`/tmp/build` 保持不变
`~/`	相对于 home 目录	`~/.kube` → `$HOME/.kube`
`./` 或无前缀	在项目设置（`.claude/settings.json`）中：相对于项目根目录；在用户设置（`~/.claude/settings.json`）中：相对于 `~/.claude`	`./output` 在项目设置中 → `<project-root>/output`

旧版 //path 前缀（绝对路径）仍然兼容。注意这与 Read/Edit 权限规则的路径语法不同：权限规则中 //path 是绝对路径，/path 是项目相对路径；沙箱设置使用标准惯例（/tmp/build 就是绝对路径）。

多个设置范围中的 allowWrite 数组会合并，不会互相覆盖。

限制读写访问

json

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

这个示例：拒绝读取 home 目录，但允许读取当前项目（. 在项目设置中解析到项目根目录；如果放在用户设置 ~/.claude/settings.json 中，. 会解析到 ~/.claude，此时项目文件仍被 denyRead 阻止）。

配置项说明：

配置项	说明
`allowWrite`	允许写入的额外路径
`denyWrite`	禁止写入的路径
`denyRead`	禁止读取的路径（与权限规则的 `denyRead` 合并）
`allowRead`	在 `denyRead` 范围内例外允许读取的路径

allowManagedReadPathsOnly（managed settings 专用）：开启后，只有 managed settings 中的 allowRead 条目生效；user、project 和 local 级别的 allowRead 会被忽略。denyRead 仍然从所有来源合并。适用于需要严格锁定读取白名单的管理部署场景。

自定义代理配置

企业用户可以实现自定义代理：

json

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

安全防护

防护 Prompt 注入

即使攻击者通过 Prompt 注入操控了 Claude Code 的行为，沙箱也能保护系统：

文件系统保护：

无法修改关键配置文件（如 ~/.bashrc）
无法修改系统文件（如 /bin/）
无法读取权限设置中被拒绝的文件

网络保护：

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

降低攻击面

沙箱限制以下场景的潜在危害：

恶意依赖：含有有害代码的 NPM 包等
被篡改的脚本：有安全漏洞的构建脚本
社会工程：诱骗用户运行危险命令
Prompt 注入：诱骗 Claude 运行危险命令

透明操作

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

操作在 OS 层面被阻止
你收到立即通知
可以选择：
- 拒绝请求
- 本次允许
- 永久更新沙箱配置

安全限制

网络过滤局限性：网络过滤系统通过限制可访问域名工作，不检查通过代理的流量内容。允许宽泛域名（如 github.com）可能允许数据外泄，且某些情况下可能通过域前置绕过。

Unix Socket 权限升级：allowUnixSockets 配置可能意外授权对强大系统服务的访问。例如允许访问 /var/run/docker.sock 实际上会通过 Docker Socket 授权访问主机系统。

文件系统权限升级：过于宽泛的写权限可能导致权限升级攻击，尤其是允许写入 $PATH 中的可执行目录、系统配置目录或用户 shell 配置文件（.bashrc、.zshrc）。

Linux 沙箱强度：Linux 实现在 Docker 等无权限命名空间的环境中有 enableWeakerNestedSandbox 模式，这会显著降低安全性，仅在有其他隔离措施时使用。

沙箱与权限的关系

沙箱和权限是互补的安全层：

权限：控制 Claude Code 可以使用哪些工具，在工具运行前评估
沙箱：提供 OS 级强制执行，限制 Bash 命令对文件系统和网络的访问

配置建议：

用 sandbox.filesystem.allowWrite 授权子进程写入工作目录外的路径
用 Read 和 Edit deny 规则阻止特定文件或目录访问
用 WebFetch allow/deny 规则控制域名访问
用沙箱 allowedDomains 控制 Bash 命令可以访问的域名

工具兼容性提示

watchman 与沙箱不兼容。运行 Jest 时考虑使用 jest --no-watchman
docker 与沙箱不兼容，考虑在 excludedCommands 中指定 docker 让其在沙箱外运行
许多 CLI 工具需要访问特定主机，第一次使用时会请求权限，授权后在沙箱内可以安全使用

开源沙箱运行时

沙箱运行时作为开源 npm 包提供，可在自己的 Agent 项目中使用：

bash

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

例如沙箱化一个 MCP 服务器：

bash

npx @anthropic-ai/sandbox-runtime npx @modelcontextprotocol/server-sqlite

限制

性能开销：极小，但某些文件系统操作可能稍慢
兼容性：某些需要特定系统访问模式的工具可能需要调整配置
平台支持：支持 macOS、Linux、WSL2，不支持 WSL1，Windows 原生支持计划中

沙箱不覆盖的范围

内置文件工具（Read、Edit、Write）：使用权限系统而非沙箱
桌面应用的计算机使用：在实际桌面上运行，不在隔离环境中

常见问题

Q: 沙箱会不会影响 Claude 运行项目命令（如 npm run dev）？

A: 沙箱默认允许访问项目目录和常用工具路径，大多数构建/运行命令可正常执行。如果发现某个命令被拒绝，可以在 settings.json 的 sandbox.allowExec 中添加允许的命令或路径。

Q: macOS 和 Linux 的沙箱实现有什么区别？

A: macOS 使用系统内置的 Seatbelt（sandbox-exec），Linux 使用 bubblewrap（bwrap）。两者提供相似的隔离能力，但配置语法略有不同。Windows 目前不支持沙箱模式。

Q: 沙箱能防止 Claude 删除我的文件吗？

A: 沙箱限制写入范围，超出项目目录和允许路径的写操作会被阻止。但项目目录内的文件仍可被修改。配合 Checkpointing 使用，可以在发生意外修改时快速回滚。

沙箱隔离 ​

为什么需要沙箱？ ​

工作原理 ​

文件系统隔离 ​

网络隔离 ​

OS 级强制执行 ​

快速开始 ​

前提条件 ​

启用沙箱 ​

沙箱模式 ​

配置文件系统权限 ​

允许子进程写入特定路径 ​

限制读写访问 ​

自定义代理配置 ​

安全防护 ​

防护 Prompt 注入 ​

降低攻击面 ​

透明操作 ​

安全限制 ​

沙箱与权限的关系 ​

工具兼容性提示 ​

开源沙箱运行时 ​

限制 ​

沙箱不覆盖的范围 ​

相关资源 ​

常见问题 ​

沙箱隔离

为什么需要沙箱？

工作原理

文件系统隔离

网络隔离

OS 级强制执行

快速开始

前提条件

启用沙箱

沙箱模式

配置文件系统权限

允许子进程写入特定路径

限制读写访问

自定义代理配置

安全防护

防护 Prompt 注入

降低攻击面

透明操作

安全限制

沙箱与权限的关系

工具兼容性提示

开源沙箱运行时

限制

沙箱不覆盖的范围

相关资源

常见问题