沙箱与 Devcontainer

沙箱与 Devcontainer

Claude Code 会写文件、会跑 bash 命令、会联网——这些能力强大，但强大本身就是风险。万一它写错地方、跑错命令、连错网络，后果可能很重。企业部署尤其在意这个：开发者本机的 ~/.ssh、生产凭证、其他项目的代码，都可能被一次失控的命令搞砸。

沙箱就是把 Claude 关进一个无菌操作台——只让它碰该碰的东西，越界的全拦下。这一篇讲清楚 Claude Code 的 /sandbox 命令、文件系统隔离、网络隔离、settings.json 各字段、以及 Devcontainer 这种更彻底的隔离方式。

一句话开启沙箱

在 Claude Code 里输入：

/sandbox

沙箱就开了。开了之后，Claude 跑 bash、写文件、联网，都受沙箱规则约束。

文件系统隔离：默认只写当前目录

沙箱对文件系统的规则是：

操作	默认行为
读	全机可读，除了一小撮敏感路径（denied）
写	只能写当前目录及子目录

也就是说，Claude 想读你机器上的文件，默认能读——这合理，因为读代码、读配置都要全机读。但写被严格限制在当前目录及子目录，越界一律拦下。

写越界的例子：

# Claude 想干这个，沙箱拦下
echo "evil" >> ~/.bashrc

# Claude 想干这个，沙箱拦下
rm -rf /tmp/something_outside

# Claude 想干这个（在当前目录内），沙箱放行
mkdir -p ./src/components

这种「读开放、写收紧」的设计，是沙箱的核心理念：让 Claude 充分获取信息，同时把破坏面收窄到当前项目目录内。

网络隔离：proxy server

沙箱对网络的隔离是：所有出向流量走一个本地 proxy server。proxy 可以按规则放行/拦截，让 Claude 的网络行为可控。

比如：

• 允许 npm install 拉包。
• 拦截对陌生 IP 的 curl。
• 拦截对内网管理端口的访问。

proxy 的具体端口、是否允许 Unix sockets、是否允许本地绑定，都在 settings.json 里配（见下文）。

OS 级隔离：bubblewrap 与 Seatbelt

沙箱不是 Claude Code 自己实现的一个软件层——它复用了操作系统自带的隔离机制：

操作系统	底层机制
Linux	bubblewrap（bwrap）
macOS	Seatbelt（sandbox-exec）

这两个都是各自系统级的隔离原语，做进程级沙箱用了很多年，靠谱。Claude Code 在它们之上封装了一层，开发者只用 /sandbox，不用关心底层。

sandbox settings.json 全字段

沙箱的行为可以在 settings.json 里精细调。下面是官方 sandboxing 文档列的字段：

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git"],
    "allowUnsandboxedCommands": ["git status"],
    "network": {
      "allowUnixSockets": false,
      "allowLocalBinding": false,
      "httpProxyPort": 0,
      "socksProxyPort": 0,
      "enableWeakerNestedSandbox": false
    }
  }
}

逐个看：

字段	作用
enabled	开关沙箱
autoAllowBashIfSandboxed	沙箱开启时，bash 命令自动放行（因为在沙箱里跑，破坏面有限）
excludedCommands	这些命令不在沙箱里跑（比如 git，因为 git 写 .git/ 在当前目录内是安全的）
allowUnsandboxedCommands	显式允许某些命令脱离沙箱执行
network.allowUnixSockets	是否允许 Unix socket
network.allowLocalBinding	是否允许绑定本地端口
network.httpProxyPort	HTTP 代理端口
network.socksProxyPort	SOCKS 代理端口
network.enableWeakerNestedSandbox	嵌套沙箱场景下用更弱的隔离（兼容性优先）

字段不少，但用得最多的是前三个：开沙箱、autoAllow、把 git 排除掉（让 git 命令不进沙箱，因为 git 本来就只动当前目录）。

Devcontainer：更彻底的隔离

沙箱是「进程级」隔离——Claude 还在你机器上跑，只是被沙箱规则约束。Devcontainer 是「容器级」隔离——Claude 跑在一个完全独立的容器里，连文件系统都是另一套。

怎么用

在项目根目录建一个 .devcontainer/ 目录，里面写 devcontainer.json 和 Dockerfile。VS Code 等 IDE 原生支持 Devcontainer，Claude Code 也兼容。

官方提供了一个参考实现，照着抄最快：

参考实现：github.com/anthropics/claude-code/tree/main/.devcontainer

照着这个仓库的 .devcontainer/ 抄一份到你项目，改改 Dockerfile 就能跑。

sandbox-runtime 工具

如果不想自己写 Docker 配置，可以用官方提供的沙箱运行时：

npx @anthropic-ai/sandbox-runtime

它会帮你拉起一个隔离的运行环境，Claude Code 在里面跑，外部完全隔离。

沙箱 vs Devcontainer：怎么选

维度	沙箱	Devcontainer
隔离级别	进程级	容器级
启动速度	快（几乎零成本）	慢（要起容器）
配置成本	settings.json 几行	Dockerfile + devcontainer.json
文件访问	默认读全机、写当前目录	容器内，外部完全隔离
网络隔离	proxy server	容器网络命名空间
适合	开发者日常	CI、不信任的代码、强隔离需求
跨平台	Linux/macOS 各有底层	任何能跑 Docker 的系统

简单说：日常开发用沙箱就够——零成本开个开关；CI 或跑不信任代码用 Devcontainer——彻底关进容器。

沙箱的常见搭配

想做的事	配置
日常开发，开沙箱省心	enabled: true + autoAllowBashIfSandboxed: true
让 git 不进沙箱（性能更好）	excludedCommands: ["git"]
允许 Claude 起本地服务调试	network.allowLocalBinding: true
不允许 Claude 联 Unix socket	network.allowUnixSockets: false
嵌套沙箱场景（在容器里再开沙箱）	enableWeakerNestedSandbox: true

沙箱和企业策略的配合

企业部署里，沙箱的开关通常不能让员工自己关——managed-settings.json 里写死 sandbox.enabled: true，员工级 settings.json 改不动这条。这样确保全公司默认开沙箱，没人能裸跑。

再配 disableBypassPermissionsMode: "disable"（IAM 文档），就没人能绕过权限模式跑危险操作了。沙箱 + 权限锁 + 网关，三层关卡叠起来，企业部署的安全性才有底。

常见踩坑

• macOS 上 sandbox-exec 没装：极少见，但如果系统被改过，可能要重装。
• Linux 上 bwrap 权限不够：在某些受限环境（如某些 CI runner）里 bubblewrap 起不来，要 enableWeakerNestedSandbox: true 或换 Devcontainer。
• Claude 想写 ~/.cache：被沙箱拦下，要看是不是真的需要；不需要就让它别写，需要就走 Devcontainer 或显式 allow。
• Claude 起的本地服务连不上：默认 allowLocalBinding: false，要本地调试就开 true。

沙箱是 Claude Code 安全体系的最内层防线——权限管的是「Claude 能干啥」，沙箱管的是「Claude 干的时候能碰啥」。两层叠起来，企业部署才敢放开手用。