Sandboxing（沙箱隔离）

Claude Code 内置的沙箱化 Bash 工具，用操作系统级原语在文件系统和网络两个维度隔离每条 Bash 命令及其子进程，让 Claude 无需逐条审批即可自主运行命令。

为什么你尤其该看这节

你全局 defaultMode: bypassPermissions——权限弹窗全跳过。这意味着 Claude 跑命令、读写文件几乎不受权限拦截。Sandboxing 是 OS 级的第二道闸：即使权限放行，沙箱也能从操作系统层面限制文件读写范围和网络访问。bypassPermissions + sandbox 是更安全的组合：你享受"不弹窗的顺"，又有 OS 兜底。

怎么开 / 体验

settings.json 里配 sandbox（按需）：

json

{
  "sandbox": {
    "enabled": true,
    "network": { "allowedDomains": ["registry.npmmirror.com", "gitee.com", "127.0.0.1"] },
    "filesystem": { "denyRead": ["~/.ssh/**", "**/.env"], "denyWrite": ["/etc/**"] }
  }
}

沙箱内 Bash 默认即使有 ask 规则也不弹（autoAllowBashIfSandboxed），但 deny 和 rm -rf 关键路径仍拦——和你 bypass 习惯不冲突。
网络白名单贴你的实际：npmmirror 镜像、gitee、本地 127.0.0.1（你 Nacos/Gateway 都在本地）。

对你的实际意义

你跑前端 pnpm、后端构建、各种脚本——沙箱能挡住意外的对外连接和越界文件写入，尤其在 bypassPermissions 下值得开。
它和权限是互补两层：权限管"哪个工具/命令"，沙箱管"OS 层能碰哪些文件/域名"。

官方文档要点

以下为按官方文档整理的系统性参考。

是什么

Bash sandbox 让 Claude 运行大多数 shell 命令时不必停下来逐条征求权限：你定义命令能触碰哪些文件和网络域名，由操作系统对每条 Bash 命令及其子进程强制执行这个边界。它内置于 Claude Code，运行于 macOS、Linux 和 WSL2（不支持原生 Windows）。它只作用于 Bash 命令及其子进程，是与 permission rules（权限规则）、permission modes（权限模式）互补的一层 OS 级强制隔离。注意它本身不是 permission mode，也不是完整的隔离边界。

怎么工作

文件系统隔离：默认对当前工作目录（及其子目录）可读可写；默认对整台机器可读（除被 deny 的目录外）——注意默认仍允许读取 ~/.aws/credentials 和 ~/.ssh/ 等凭据文件，需手动加入 denyRead 才会阻止；默认禁止修改工作目录以外的文件，包括 ~/.bashrc 等 shell 配置和 /bin/ 中的系统二进制。可通过 sandbox.filesystem.allowWrite 授予额外写路径。
OS 级强制：macOS 用内置 Seatbelt 框架；Linux 用 bubblewrap；WSL2 同 Linux 用 bubblewrap。所有限制在 OS 层强制，因此命令派生的所有子进程（kubectl/terraform/npm 等）都继承同一安全边界，不依赖模型选择运行什么，即便某个命令做的事超出其名字暗示也照样受限。
网络隔离：通过运行在沙箱外的 proxy server 控制。默认不预先放行任何域名；命令首次需要某个新域名时 Claude Code 弹窗征求批准。可用 allowedDomains 预放行避免弹窗，用 deniedDomains 阻止特定域名。Linux/WSL2 上由 socat 把网络流量中继到 sandbox proxy。
内置 proxy 仅基于请求的 hostname 做 allowlist 判断，不终止也不检查 TLS 流量（不解密加密内容），因此存在 domain fronting 等绕过风险。
git worktree 特例：当工作目录是 linked git worktree 时，沙箱额外允许写主仓库共享的 .git 目录（让 git commit 能更新 refs 和 index），但该目录下的 hooks/ 和 config 仍禁止写。
两种 sandbox mode：auto-allow（沙箱内命令自动放行不弹窗）；regular permissions（即使沙箱化仍走常规权限流程）。两种模式下文件系统和网络限制相同，区别只在是否自动批准。
逃生舱机制：某些命令无法在沙箱内运行时，Claude 分析失败原因后可能带 dangerouslyDisableSandbox 参数重试，该命令在沙箱外运行并走常规权限流程需你批准；设 allowUnsandboxedCommands: false 可彻底禁用（即 Strict sandbox mode）。
默认行为：若沙箱因依赖缺失或平台不支持而无法启动，默认只警告并以非沙箱方式运行命令；设 failIfUnavailable: true 可改为硬失败（用于把沙箱当安全门的托管部署）。
settings 文件保护：沙箱自动拒绝对每个 scope 的 settings.json 及 managed settings 目录的写访问，使沙箱内命令无法修改自身策略。
依赖检测在启动时运行，装完包需重启 Claude Code 才能被 /sandbox 检测到。

怎么配置 / 用法

交互入口：会话内运行 /sandbox 打开面板，有 Mode / Overrides / Config 三个标签（依赖缺失时只显示 Dependencies 标签）。在面板选 Mode 会写入项目本地设置 .claude/settings.local.json（仅当前项目、不入 git）。全局开启在用户设置 ~/.claude/settings.json 设 sandbox.enabled=true；组织级用 managed settings。

授予额外写路径（.claude/settings.json）： { "sandbox": { "enabled": true, "filesystem": { "allowWrite": ["~/.kube", "/tmp/build"] } } }

阻止读 home 但放行项目（需放在项目 .claude/settings.json，因为 "." 解析为项目根）： { "sandbox": { "enabled": true, "filesystem": { "denyRead": ["~/"], "allowRead": ["."] } } }

路径前缀规则：/ 绝对路径（/tmp/build 保持原样）；~/ 相对 home（~/.kube → $HOME/.kube）；./ 或无前缀相对项目根（项目设置中）或相对 ~/.claude（用户设置中）。注意：此语法不同于 Read/Edit 权限规则（后者用 //path 表绝对、/path 表项目相对）。

组织强制（managed settings）： { "sandbox": { "enabled": true, "failIfUnavailable": true, "allowUnsandboxedCommands": false } }

自定义 proxy 端口（sandbox settings）： { "sandbox": { "network": { "httpProxyPort": 8080, "socksProxyPort": 8081 } } }

Linux/WSL2 安装依赖：Ubuntu/Debian 用 sudo apt-get install bubblewrap socat；Fedora 用 sudo dnf install bubblewrap socat；可选 seccomp filter 用 npm install -g @anthropic-ai/sandbox-runtime。

什么时候用

想让 Claude 自主跑大量 build/test 等命令又不想逐条审批时：开 auto-allow 模式，由沙箱边界兜底
需要在文件系统和网络两个维度对 Bash 子进程做 OS 级硬隔离时（permission rules 是运行前判断，沙箱是运行中强制）
组织要对所有开发者强制沙箱、不让他们放宽策略、把流量走公司 proxy 时——用 managed settings
需要更可控、愿意多审批时用 regular permissions 模式
别用/慎用：威胁模型需要 TLS 检查时不要依赖内置 proxy（它不解密 TLS），改用 custom proxy 终止并检查 TLS；不要把它当完整隔离边界（见 limits）；native Windows 不支持，需在 WSL2 或容器内跑
对 Read/Edit/Write 等内置文件工具无效（它们直接走权限系统而非沙箱），computer use、子进程环境变量等也在不同边界下

限制 / 坑

不是完整隔离边界，只降低风险，不能当硬安全控制单独依赖
网络过滤：内置 proxy 不终止/不做 TLS 检查，只按 client 提供的 hostname 判断，放行 github.com 等宽泛域名可被 domain fronting 等技术绕过、形成数据外泄通道
默认读策略仍允许读 ~/.aws/credentials 和 ~/.ssh/，必须手动加 denyRead（如 ~/.aws、~/.ssh）才阻止
allowUnixSockets 可能误授强力系统服务访问，例如放行 /var/run/docker.sock 等于通过 Docker socket 拿到宿主机访问
文件系统写权限过宽会导致提权：对 $PATH 中含可执行文件的目录、系统配置目录、.bashrc/.zshrc 等授写可在不同安全上下文执行代码
enableWeakerNestedSandbox 会显著削弱安全性，仅当外层容器已提供隔离时才用
平台：仅支持 macOS / Linux / WSL2；WSL1 与原生 Windows 不支持（bubblewrap 需 WSL2 内核特性）
WSL2 下沙箱命令无法启动 Windows 二进制（cmd.exe / powershell.exe / /mnt/c/ 下的程序），因为 WSL 经 Unix socket 转交宿主被沙箱阻断；需加入 excludedCommands
watchman 与沙箱不兼容，jest 会 hang/fail，需用 jest --no-watchman
docker 与沙箱不兼容，需把 docker * 加入 excludedCommands
macOS 上 Go 系 CLI（gh / gcloud / terraform）在 Seatbelt 下可能 TLS 校验失败，需放入 excludedCommands，或用 MITM proxy+自定义 CA 时改设 enableWeakerNetworkIsolation=true
Ubuntu 24.04+ 默认 AppArmor 策略阻止 bubblewrap 创建 user namespaces，需加 /etc/apparmor.d/bwrap 配置文件并 reload
无特权容器内 bubblewrap 无法挂载新 /proc，需 enableWeakerNestedSandbox=true（会暴露进程信息）
excludedCommands 没有 managed-only 锁定，开发者总能追加条目让命令在沙箱外运行，托管列表要保持精简
性能开销很小，但部分文件系统操作可能略慢
环境变量：沙箱 Bash 默认继承父进程环境（含其中凭据），需设 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 才能剥离 Anthropic 和云厂商凭据
auto-allow 下即便不在 accept edits 模式，沙箱边界内改文件的 Bash 命令也会无提示执行，而文件编辑工具通常需批准

硬事实速查（36 条）

命令：/sandbox（打开面板，三标签 Mode/Overrides/Config；依赖缺失时只显示 Dependencies）
Mode 选择写入 .claude/settings.local.json（当前项目、不入 git）
全局开启：~/.claude/settings.json 中 sandbox.enabled=true
OS 原语：macOS 用 Seatbelt；Linux 用 bubblewrap；WSL2 同 Linux 用 bubblewrap；WSL1 不支持；原生 Windows 不支持
Linux/WSL2 依赖：bubblewrap（文件系统隔离）、socat（网络流量中继到 proxy）
安装：Ubuntu/Debian sudo apt-get install bubblewrap socat；Fedora sudo dnf install bubblewrap socat
ripgrep 随 native Claude Code 二进制自带；seccomp filter 可选（加 Unix domain socket 阻断），用 npm install -g @anthropic-ai/sandbox-runtime 安装
Dependencies 标签检查项：ripgrep、bubblewrap、socat、seccomp filter
依赖检测在启动时运行，装完需重启 Claude Code
默认写：当前工作目录及子目录可读写
默认读：整机可读（denyRead 除外），仍含 ~/.aws/credentials 和 ~/.ssh/
默认阻止：修改工作目录外文件，含 ~/.bashrc 和 /bin/
配置字段：sandbox.enabled、sandbox.failIfUnavailable、sandbox.allowUnsandboxedCommands
文件系统字段：sandbox.filesystem.allowWrite / denyWrite / denyRead / allowRead
网络字段：sandbox.network.httpProxyPort、sandbox.network.socksProxyPort；域名 allowedDomains / deniedDomains
managed-only 锁定字段：allowManagedDomainsOnly、allowManagedReadPathsOnly（设 true 后仅 managed settings 的对应条目生效）
其它字段：excludedCommands、enableWeakerNetworkIsolation、enableWeakerNestedSandbox、allowUnixSockets
路径前缀：/ 绝对；~/ 相对 home（~/.kube→$HOME/.kube）；./ 或无前缀相对项目根（项目设置）或相对 ~/.claude（用户设置）
沙箱路径语法 != Read/Edit 规则语法（后者 //path 绝对、/path 项目相对）
同名 filesystem 数组在多个 settings scope 下是合并（merge）而非替换
逃生舱参数：dangerouslyDisableSandbox（命令在沙箱外重试、走常规权限流程）；allowUnsandboxedCommands=false 即 Strict sandbox mode，完全忽略该参数
两种 mode：auto-allow（自动放行）、regular permissions（仍走权限流程）；两者文件/网络限制相同
auto-allow 下仍生效：显式 deny 规则；rm/rmdir 针对 /、home 或关键系统路径仍弹窗；ask 规则对回退到常规流程的命令生效
网络默认不预放行任何域名，首次新域名弹窗批准
allowManagedDomainsOnly 在 managed settings 设置后：非放行域名自动阻止（不弹窗），且只认 managed 的 allowedDomains
boolean 键（enabled、failIfUnavailable）：托管值生效、忽略本地；array 键（excludedCommands、allowRead）：各 scope 合并、可被开发者追加放宽
git worktree：允许写主仓库共享 .git，但 hooks/ 和 config 仍禁写
环境变量：CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 用于剥离子进程凭据
标准包：@anthropic-ai/sandbox-runtime（也是可独立包裹整个 Claude Code 进程的同套原语）
故障：jest 用 --no-watchman；docker * 加 excludedCommands；macOS Go CLI（gh/gcloud/terraform）加 excludedCommands 或设 enableWeakerNetworkIsolation=true
Ubuntu 24.04+：检查 sysctl kernel.apparmor_restrict_unprivileged_userns，返回 1 则需加 /etc/apparmor.d/bwrap profile（profile bwrap /usr/bin/bwrap flags=(unconfined) 带 userns）再 sudo systemctl reload apparmor
WSL 版本检查 wsl -l -v；'Sandboxing requires WSL2' 表示在跑 WSL1
--dangerously-skip-permissions 作为 root 或 sudo 运行时在 Linux/macOS 被阻止；在识别到的沙箱内自动跳过该检查
settings.json 文件在每个 scope 及 managed settings 目录均被沙箱自动拒绝写
subagents 与父会话同进程、共用同一沙箱配置
内置文件工具 Read/Edit/Write 走权限系统而非沙箱

官方出处：https://code.claude.com/docs/en/sandboxing

Sandboxing（沙箱隔离） ​

为什么你尤其该看这节 ​

怎么开 / 体验 ​

对你的实际意义 ​

官方文档要点 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​

硬事实速查（36 条） ​