原生沙盒机制

Claude Code 内置原生沙盒（v2.1.0+），使用操作系统级原语隔离 bash 命令。本指南涵盖 OS 底层机制、配置选项、安全局限和进程级沙盒的最佳实践。

概览

方面	详情
macOS	Seatbelt（内置，开箱即用）
Linux/WSL2	bubblewrap + socat（需安装）
文件系统	可读全部（可配置），仅可写工作区
网络	SOCKS5 代理，域名允许/拒绝列表
模式	自动允许（bash 自动批准）vs 常规权限
逃逸舱	`dangerouslyDisableSandbox` 用于不兼容的工具
平台支持	macOS、Linux、WSL2（不支持 WSL1，Windows 原生计划中）

快速开始：

# 启用沙盒
/sandbox

# Linux/WSL2 先决条件
sudo apt-get install bubblewrap socat  # Ubuntu/Debian
sudo dnf install bubblewrap socat      # Fedora

为什么需要原生沙盒？

自主性与安全性的矛盾

Claude Code 的权限系统产生了一个根本性矛盾：

--dangerously-skip-permissions 移除所有防护——快速、自主，但在裸机上很危险
交互式权限——安全，但缓慢，对大规模重构不切实际

原生沙盒解决了这个问题：让 Claude 在操作系统强制的边界内自由运行。沙盒成为安全边界，而非权限系统。

优势

减少审批疲劳

安全命令在沙盒边界内自动批准。

自主工作流

大规模重构和 CI 流水线无需频繁确认。

注入防护

恶意提示无法逃逸沙盒边界。

依赖安全

被入侵的 npm 包被限制在工作区内。

操作系统原语

macOS：Seatbelt

内置，开箱即用——无需安装。

机制：macOS 沙盒框架（TrustedBSD 强制访问控制）
执行：内核级系统调用过滤
范围：每进程的文件系统、网络、IPC 限制
性能：开销极小（典型工作负载约 1-2% CPU）

Claude Code 进程
       |
       +-- 启动 bash 命令
       |
       v
应用 Seatbelt 策略
       |
       +-- 文件系统规则：可读全部，仅可写 CWD
       +-- 网络规则：所有连接经过代理
       +-- IPC 规则：限制进程间通信
       |
       v
内核强制限制
       |
       +-- 允许：边界内的操作
       +-- 阻止：边界外的操作
       +-- 通知：用户收到警报

Linux/WSL2：bubblewrap

需要安装——必须安装 bubblewrap 和 socat 包。

机制：Linux 命名空间 + seccomp-bpf 系统调用过滤
执行：内核命名空间隔离（mount、network、PID、IPC）
范围：为每个命令创建类容器的隔离环境
性能：开销极小（约 2-3% CPU，每命令启动 <10ms）

先决条件：

# Ubuntu/Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

# Arch Linux
sudo pacman -S bubblewrap socat

Claude Code 进程（宿主命名空间）
       |
       +-- 启动 bash 命令
       |
       v
bubblewrap 创建隔离命名空间
       |
       +-- Mount 命名空间：自定义文件系统视图
       +-- Network 命名空间：通过 socat 代理
       +-- PID 命名空间：隔离的进程树
       +-- IPC 命名空间：无共享内存访问
       |
       v
命令在隔离环境中执行
       |
       +-- 文件系统：仅看到允许的路径
       +-- 网络：所有连接经过代理
       +-- 进程：看不到宿主进程

WSL2 vs WSL1

WSL2：支持（使用 bubblewrap，与 Linux 相同）
WSL1：不支持——bubblewrap 需要 WSL1 转换层中不可用的内核功能（命名空间、cgroups）

文件系统隔离

默认行为

读权限：整台计算机（除了显式拒绝的目录）
写权限：仅当前工作目录（CWD）及其子目录
阻止：未经许可修改 CWD 之外的内容

为什么”全部可读，仅可写 CWD”？

这种非对称策略平衡了可用性和安全性：

全部可读：Claude 需要搜索/分析整个代码库、读取系统配置、检查依赖
仅可写 CWD：大部分开发工作在项目目录内进行；限制写入防止意外/恶意的系统修改

配置文件系统限制

{
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(~/.kube/**)",
      "Edit(~/.ssh/**)",
      "Edit(~/.aws/**)",
      "Edit(~/.kube/**)"
    ]
  }
}

网络隔离

代理架构

沙盒命令的所有网络连接都通过运行在沙盒外部的 SOCKS5 代理路由。代理限制进程可以连接的域名，但不检查通过它的流量内容。

沙盒化的 bash 命令
       |
       +-- 尝试连接 api.anthropic.com:443
       |
       v
SOCKS5 代理（沙盒外部）
       |
       +-- 检查域名允许/拒绝列表
       |
       +-- 允许？ -> 转发连接
       +-- 拒绝？ -> 拒绝 + 通知用户
       |
       v
外部网络（如果允许）

阻止所有流量，仅允许指定目标：

{
  "sandbox": {
    "network": {
      "policy": "deny",
      "allowedDomains": [
        "api.anthropic.com",
        "*.npmjs.org",
        "*.pypi.org",
        "github.com",
        "registry.yarnpkg.com"
      ]
    }
  }
}

允许大部分流量，阻止特定目标：

{
  "sandbox": {
    "network": {
      "policy": "allow",
      "blockedDomains": [
        "*.malicious-domain.com"
      ]
    }
  }
}

模式匹配：

精确：example.com（完全匹配）
端口指定：example.com:443（仅 HTTPS）
通配符：*.example.com（匹配 sub.example.com，不匹配 example.com 本身）

默认阻止范围：私有 CIDR（10.0.0.0/8、127.0.0.0/8、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16）

自定义代理

用于高级场景（HTTPS 检查、企业代理）：

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

沙盒模式

自动允许模式

Bash 命令在沙盒内运行时自动批准
与沙盒不兼容的命令回退到常规权限流程
显式的 ask/deny 规则始终生效
内置阻止列表：curl 和 wget 默认被阻止

适用场景：日常开发、自主重构、CI/CD 流水线

常规权限模式

所有 bash 命令都需要显式批准，即使在沙盒内
沙盒仍然执行文件系统/网络限制
更多控制，但工作流更慢

适用场景：高安全环境、不可信代码库、学习 Claude Code 行为

切换模式

# 交互菜单
/sandbox

# 或编辑 settings.json
{
  "sandbox": {
    "autoAllowMode": true  // 或 false 用于常规权限
  }
}

逃逸舱

dangerouslyDisableSandbox 参数

某些工具与沙盒不兼容（如 docker、watchman）。Claude Code 包含一个逃逸舱：

命令因沙盒限制失败
Claude 分析失败原因
Claude 使用 dangerouslyDisableSandbox 参数重试
用户收到权限提示（正常的 Claude Code 流程）
如果批准，命令在沙盒外部运行

不兼容工具：docker（需要 /var/run/docker.sock）、watchman（需要文件系统监视 API）、带 watchman 的 jest（改用 jest --no-watchman）。

禁用逃逸舱

要获得最高安全性，完全禁用逃逸舱：

{
  "sandbox": {
    "allowUnsandboxedCommands": false
  }
}

禁用后，dangerouslyDisableSandbox 参数完全被忽略。所有命令必须在沙盒内运行，或者在 excludedCommands 中明确列出。

excludedCommands

对于永远无法在沙盒中工作的工具，永久排除它们：

{
  "sandbox": {
    "excludedCommands": ["docker", "kubectl", "vagrant"]
  }
}

被排除的命令始终在沙盒外运行（使用正常权限提示）。

安全局限

域名前置

缓解措施：

避免宽泛的 CDN 域名：*.cloudflare.com、*.akamai.net、*.fastly.net
白名单指定子域名：my-app.pages.dev、my-workers.workers.dev
在不可信环境中使用拒绝列表模式

Unix 套接字权限提升

风险：allowUnixSockets 配置可能授予对强大系统服务的访问。

常见易受攻击的套接字：

/var/run/docker.sock（Docker 守护进程——完整宿主访问）
/run/containerd/containerd.sock（containerd——容器控制）
/tmp/supervisor.sock（supervisord——进程管理）

缓解措施：

绝不允许宽泛模式：/tmp/*.sock、/var/run/*.sock
审计后白名单特定套接字
默认：Unix 套接字被阻止，除非明确允许

文件系统权限提升

风险：过于宽泛的写权限导致权限提升。

易受攻击的目录：

$PATH 目录（/usr/local/bin、~/bin）
Shell 配置文件（~/.bashrc、~/.zshrc、~/.profile）
系统目录（/etc、/opt、/Library）
Cron 目录（/etc/cron.d、/var/spool/cron）

缓解措施：仅限制写入项目目录（沙盒默认行为）。使用权限拒绝规则阻止敏感读取。

Linux：嵌套沙盒弱化

enableWeakerNestedSandbox 模式在没有特权命名空间的 Docker 容器内运行 Claude Code 时会弱化隔离。仅在有额外隔离保障时使用（Docker Sandboxes、云沙盒）。绝不在裸机上与不可信代码一起使用。

平台支持

平台	支持情况	备注
macOS	完全支持	Seatbelt 内置，开箱即用
Linux	完全支持	需安装 `bubblewrap` + `socat`
WSL2	完全支持	与 Linux 相同（使用 bubblewrap）
WSL1	不支持	bubblewrap 需要 WSL1 中不可用的内核功能
Windows（原生）	计划中	暂不可用

配置示例

{
  "sandbox": {
    "autoAllowMode": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "policy": "deny",
      "allowedDomains": [
        "api.anthropic.com",
        "registry.npmjs.com",
        "registry.yarnpkg.com",
        "files.pythonhosted.org",
        "github.com"
      ]
    },
    "excludedCommands": []
  },
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)", "Read(~/.aws/**)",
      "Read(~/.kube/**)", "Read(~/.gnupg/**)",
      "Edit(~/.ssh/**)", "Edit(~/.aws/**)"
    ]
  }
}

{
  "sandbox": {
    "autoAllowMode": true,
    "allowUnsandboxedCommands": true,
    "network": {
      "policy": "allow",
      "blockedDomains": [
        "*.malicious-domain.com"
      ]
    },
    "excludedCommands": ["docker", "kubectl"]
  },
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)", "Read(~/.aws/**)",
      "Edit(~/.ssh/**)", "Edit(~/.aws/**)"
    ]
  }
}

{
  "sandbox": {
    "autoAllowMode": true,
    "allowUnsandboxedCommands": true,
    "network": {
      "policy": "allow"
    },
    "excludedCommands": ["docker", "podman", "kubectl", "vagrant"]
  }
}

最佳实践

从严格开始，按需放宽 — 以拒绝列表模式开始，逐步白名单域名/路径
监控沙盒违规 — 审查日志以了解 Claude 的访问模式
审计权限拒绝规则 — 阻止对敏感目录的访问（~/.ssh、~/.aws、~/.kube）
避免宽泛的 CDN 域名 — 白名单特定子域名而非 *.cloudflare.com
在生产环境禁用逃逸舱 — CI/CD 中设置 allowUnsandboxedCommands: false
结合 IAM 策略 — 将沙盒与权限设置结合实现纵深防御
测试配置 — 部署前验证沙盒不会阻止合法工作流
记录允许的域名 — 注释每个域名被白名单的原因

故障排除

沙盒未激活

症状：/sandbox 显示”沙盒不可用”

原因：Linux/WSL2 缺少 bubblewrap 或 socat、WSL1（不支持）、Windows 原生（暂不支持）。

解决方案：

# Linux/WSL2
sudo apt-get install bubblewrap socat

# 验证
which bubblewrap socat

命令因”网络错误”失败

症状：npm install 连接超时

原因：域名未在白名单中

解决方案：检查沙盒日志并添加域名到 allowedDomains：

{
  "sandbox": {
    "network": {
      "allowedDomains": [
        "registry.npmjs.com",
        "registry.yarnpkg.com"
      ]
    }
  }
}

Docker 命令总是需要权限

症状：docker ps 每次都触发权限提示

原因：Docker 与沙盒不兼容

解决方案：添加到 excludedCommands：

{
  "sandbox": {
    "excludedCommands": ["docker"]
  }
}

jest 因 watchman 错误失败

症状：jest 报”watchman 不可用”

原因：watchman 与沙盒不兼容

解决方案：使用 jest --no-watchman

原生沙盒 vs Docker 沙盒

方面	原生沙盒	Docker 沙盒
隔离级别	进程（Seatbelt/bubblewrap）	微虚拟机（Hypervisor）
内核隔离	否（共享内核）	是（每沙盒独立内核）
开销	最小（~1-3% CPU）	中等（~5-10% CPU，+200MB RAM）
配置	0 依赖（macOS），2 个包（Linux）	Docker Desktop 4.58+
适用场景	日常开发，可信代码	不可信代码，最高安全
平台	macOS、Linux、WSL2	macOS、Windows

经验法则：

日常开发，可信团队 — 原生沙盒（轻量，安全性足够）
运行不可信代码、AI 生成的脚本 — Docker 沙盒（最高隔离）
多代理编排 — 云端沙盒（并行、可扩展）