太长不看
- /sandbox 命令打开一个三标签面板：Mode、Overrides、Config。自动放行（auto-allow）模式下沙箱内 bash 命令直接执行不弹窗；常规权限模式则保留每一条确认。
- 边界由内核强制执行，不靠弹窗：macOS 用 Seatbelt，Linux 和 WSL2 用 bubblewrap。原生 Windows 和 WSL1 不受支持。
- 沙箱内命令只能写入工作目录、每用户临时目录和 --add-dir 指定的路径；网络流量全部经过一个代理，默认不放行任何域名。
- 读取默认不设防——配置 sandbox.credentials 之前，~/.ssh 和 ~/.aws 一直可读。VS Code 的 Sandbox 对话框随 v2.1.280 上线。
Claude Code Sandbox Explained
频道:The Art of Vibe Coding4:29
How auto mode works with Claude Code
频道:Claude5:42
Configure the sandboxed Bash tool (official docs)
文档:code.claude.com
第一部视频是动效讲解片——本页引用的帧是风格化插画而非真实截图，它的个别说法在下文步骤里已纠正（凭据文件默认可读；片中示例的设置键名与真实键名不符）。第二部是 Anthropic 官方录像，只取用其中真实的终端与设置界面。
事实核对自 code.claude.com/docs/en/sandboxing 与 anthropics/claude-code 的 CHANGELOG（v2.1.280–2.1.283）。截图为对录像的简短引用，用于解说。
12 步配好 Claude Code 沙箱
先搞懂边界
- 1
认清「审批疲劳」这道老毛病
没有沙箱时，每条建议执行的命令都要停下来按一次 y/n：npm install、git status，然后是下一条。Anthropic 自己统计过，97% 的 Claude Code 权限请求都会被批准——这正是沙箱存在的理由：把检查从每条命令挪到一个一次配好的边界上。
视频复原的逐命令 y/n 循环——连按 47 次 Enter 之后，你就再也不看了。看原视频 0:22 处 - 2
在受支持的平台上启动 Claude Code
在项目里打开会话。macOS 的沙箱是内置能力，Seatbelt 随系统自带、无需安装任何东西；Linux 和 WSL2 需要先用包管理器装好 bubblewrap 和 socat。原生 Windows 和 WSL1 不受支持——Windows 用户请在 WSL2 发行版里运行 Claude Code。
一个位于 ~/Documents/code/acme 的会话——这个工作目录就是沙箱稍后认定的可写范围。看原视频 0:35 处 - 3
运行 /sandbox，读懂面板
在会话里输入 /sandbox。面板有三个标签：Mode（沙箱内命令如何审批）、Overrides（失败的命令能否退到沙箱外重试，对应 allowUnsandboxedCommands 设置）和 Config（最终生效的完整沙箱配置）。Linux 上还会多一个 Dependencies 标签，列出缺失的依赖，比如 bubblewrap、socat 或可选的 seccomp 过滤器。v2.1.281 起可用方向键切换标签；VS Code 则在 v2.1.280 拿到了配置同样设置的 Sandbox 对话框。
打开沙箱
- 4
选自动放行还是常规权限
Mode 标签里，自动放行让沙箱内命令直接执行不弹窗；常规权限则对沙箱内命令也保留确认。选择会写入项目的 .claude/settings.local.json（Claude Code 会自动帮你加 gitignore）。想覆盖所有项目，就在 ~/.claude/settings.json 里设 "sandbox": undefined；只想试一次会话，用 --settings 传入即可。
两步快速上手：/sandbox 定模式，settings.json 放长期生效的配置。看原视频 4:00 处 - 5
知道自动放行仍会问什么
自动放行不是静音键。显式 deny 规则永远生效；对关键路径的 rm、rmdir 仍然弹窗；内容级 ask 规则（比如 Bash(git push *)）照样强制确认。无法在沙箱内运行的命令会退回常规流程，弹窗标题会写成「Bash command (unsandboxed)」。另外自动放行独立于权限模式——即使停在 Manual 模式，沙箱内 bash 也照样免提示执行。
shift+tab 循环切换权限模式——它和沙箱的自动放行是两个独立开关。看原视频 0:28 处 - 6
看操作系统怎么画这条边界
这些限制由内核强制执行，不是客气话：macOS 用 Seatbelt，Linux 和 WSL2 用 bubblewrap。即使一条被提示注入的命令试图去读 ~/.ssh 或向外部回连，撞上的也是同一堵墙——规则绑定在运行中的进程及其所有子进程上，模型没法靠嘴皮子说服内核。
应用层的权限检查可能被绕过；内核层不会。看原视频 2:07 处
文件系统、凭据与网络
- 7
理解文件系统默认值——以及读取的坑
沙箱内命令可以写入工作目录及其子目录、每用户临时目录，以及用 --add-dir 或 permissions.additionalDirectories 添加的目录。读取默认全开：整块磁盘都可读，包括 ~/.aws/credentials 和 ~/.ssh，直到你主动封掉。讲解视频爱说凭据从此「隐身」——官方文档说得很直白：保护它们是你的事，用 sandbox.credentials 或 denyRead 规则。
写入止步于沙箱墙；读取保持敞开，直到你在下一步关上它。看原视频 1:30 处 - 8
放手自动化之前，先护住凭据
加一段 sandbox.credentials：把 ~/.ssh、~/.aws/credentials 之类的文件用 "mode": "deny" 列进去，再列出 GITHUB_TOKEN 这类敏感环境变量，让它们在每条沙箱命令里被清空。mask 模式更进一步——命令看到的是占位哨兵值，沙箱代理只在你允许的主机上换回真值。permissions.deny 的 Read 规则则在文件工具这一层再加一道闸。
针对 curl 和 .env 读取的 deny 规则——你的 sandbox 块也写在同一个设置文件里。看原视频 4:35 处 - 9
放行技术栈需要的网络域名
所有沙箱流量都走代理，且默认不放行任何域名。命令第一次需要访问某个主机时 Claude Code 会弹窗询问；选「Yes, and don't ask again」会保存一条 WebFetch(domain:...) 放行规则，以后会话继续有效。也可以用 sandbox.network.allowedDomains 预先放行 registry.npmjs.org 这类域名，用 deniedDomains 点名封禁，再开 strictAllowlist 让白名单变成硬上限而不是询问清单。
访问 registry 的请求顺利过代理；回连 evil.com 的 postinstall 脚本被当场拦下。看原视频 1:51 处 - 10
分层配置：项目、用户还是托管
项目级 .claude/settings.json 可以增加可写路径和域名，但不能关闭文件系统隔离、也不能启用 Apple Events——这些键只认用户设置、托管设置或 --settings 参数，所以检出一个陌生仓库不会削弱你的沙箱。团队统一强制沙箱走托管设置：enabled 设 true，failIfUnavailable 设 true，allowUnsandboxedCommands 设 false。
托管设置文件用大白话描述组织信任的环境——管理员配好，开发者自动继承。看原视频 4:10 处
验证与排障
- 11
用真实任务验证一遍
让它跑一次构建或测试。沙箱内命令直接执行、不再逐条弹窗；有东西被拦时，命令结果里会写明被挡的具体路径或主机，Claude 得以自行调整。打开 /sandbox 的 Config 标签能看到每条已生效规则，包括任何设置都改不动的受保护路径。想一次性体验严格模式，可以这样启动：claude --settings 'undefined}'。
一条任务敲下去，全程零弹窗——边界不用你盯着也守得住。看原视频 0:32 处 - 12
常见故障对号入座
jest 卡住——watchman 与沙箱不兼容，改跑 jest --no-watchman。docker 报错——它无法在沙箱内运行，把 "docker *" 加进 excludedCommands。macOS 上 open 或 osascript 报 -600——Apple Events 默认被拦，除非把 allowAppleEvents 设为 true。git merge 或 checkout 报 "unable to unlink old"——撞上了受保护路径或 denyWrite 规则，批准沙箱外重试或自己在另一个终端执行。容器里 bwrap 报 Operation not permitted——设置 enableWeakerNestedSandbox。剪贴板管道失效——用 /copy 代替 pbcopy。
真正有用的沙箱设置键
/sandbox 面板负责基础项，但真正的杠杆在 settings.json 里。下面是官方沙箱文档列出的关键键名——全部位于 "sandbox" 块下（最后一条在 "permissions" 下）。
- 1sandbox.enabled——不打开就不生效。在 ~/.claude/settings.json 设 true 覆盖你所有项目；/sandbox 面板写入的是项目级副本 .claude/settings.local.json。
- 2sandbox.autoAllowBashIfSandboxed——自动放行开关，默认 true。设为 false 后，即使在沙箱内运行的命令也会回到权限弹窗。
- 3sandbox.allowUnsandboxedCommands 与 sandbox.failIfUnavailable——第一个设 false 会禁用 dangerouslyDisableSandbox 重试（Overrides 标签里的 Strict sandbox mode）；第二个设 true 后，依赖缺失会直接拒绝启动，而不是警告后照跑。
- 4sandbox.filesystem——allowWrite 放行工具需要的项目外路径（"~/.kube"、"/tmp/build"），denyRead 配合 allowRead 圈出机密位置；disabled（v2.1.216+）可单独关掉文件系统层、保留网络隔离。
- 5sandbox.network——allowedDomains 与 deniedDomains，strictAllowlist（v2.1.219+）把未列域名一律封死，allowLocalBinding 让 dev server 能绑定端口，tlsTerminate 支持在代理处做凭据掩码。
- 6sandbox.credentials——files 与 envVars 条目，分 deny、mask 两种模式；mask 依赖 tlsTerminate，且只认用户、托管或 --settings 来源。搭配 permissions.blockReadsOutsideWorkingDirectories，把工作目录之外的读取一刀切掉。
Seatbelt 与 bubblewrap：平台差异
macOS 用 Seatbelt，系统自带、零安装。坑位也很具体：gh、gcloud、terraform 这类 Go 语言 CLI 在 Seatbelt 下可能 TLS 校验失败，需要列入 excludedCommands；open、osascript 和浏览器登录流程会报 -600 错误，除非把 allowAppleEvents 设为 true——这会削弱隔离性，且项目级设置里写了也不算数。
Linux 和 WSL2 用 bubblewrap 加 socat，包管理器直接装。可选的 seccomp 过滤器（npm install -g @anthropic-ai/sandbox-runtime）追加 Unix domain socket 拦截，也是 WSL2 挡住 Windows 二进制的功臣。Ubuntu 24.04 起默认 AppArmor 策略会阻止 bubblewrap 创建 user namespace——按文档写入 bwrap profile 再 reload AppArmor。在非特权容器里，设 enableWeakerNestedSandbox 让 bubblewrap 改用容器已有的 /proc。
WSL1 完全不支持——bubblewrap 依赖只有 WSL2 才有的内核特性。性能损耗很小，但个别文件系统操作会略慢。子代理与父会话同进程运行、继承同一份沙箱配置，所以代理内执行的 bash 同样受沙箱约束。
沙箱相关行为仍在版本间快速演进：v2.1.280 上线 VS Code Sandbox 对话框，v2.1.281 改进 /sandbox 标签键导航并给 dev server 加了 allowLocalBinding 提示，v2.1.282–2.1.283 修复了 excludedCommands 匹配、TMPDIR 写入和托管设置解析。依赖边缘行为前先翻一遍 CHANGELOG。