沙箱隔离

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

为什么需要沙箱？

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

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

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

1. 定义明确边界：指定 Claude Code 可以访问的目录和网络主机
2. 减少权限提示：沙箱内的安全命令不需要审批
3. 维护安全性：尝试访问沙箱外的资源会立即通知用户
4. 启用自主性：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：

sudo apt-get install bubblewrap socat

Fedora：

sudo dnf install bubblewrap socat

启用沙箱

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

/sandbox

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

沙箱模式

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

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

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

配置文件系统权限

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

允许子进程写入特定路径

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

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

路径前缀规则：

前缀	含义	示例
/	从文件系统根的绝对路径	/tmp/build 保持不变
~/	相对于 home 目录	~/.kube → $HOME/.kube
./ 或无前缀	相对于项目根目录	./output → <project-root>/output

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

限制读写访问

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

这个示例：拒绝读取 home 目录，但允许读取当前项目（. 解析到项目根目录）。

配置项说明：

配置项	说明
allowWrite	允许写入的额外路径
denyWrite	禁止写入的路径
denyRead	禁止读取的路径
allowRead	在 denyRead 范围内例外允许读取的路径

自定义代理配置

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

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

安全防护

防护 Prompt 注入

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

文件系统保护：

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

网络保护：

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

降低攻击面

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

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

透明操作

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

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

安全限制

网络过滤局限性：网络过滤系统通过限制可访问域名工作，不检查通过代理的流量内容。允许宽泛域名（如 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 项目中使用：

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

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

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

限制

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

沙箱不覆盖的范围

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

相关资源

• 安全：完整安全特性和最佳实践
• 权限配置：权限配置和访问控制
• 设置参考：完整配置参考
• CLI 参考：命令行选项