Claude Code SDK #30：Sandboxing 全解——/sandbox × allowed paths × allowed domains，把 Bash 的活动范围关进笼子
这篇拆解 Claude Code 的 Bash sandbox：它和权限模式怎么分工、`/sandbox` 怎么启用、allowed paths 与 allowed domains 怎么收窄边界，以及什么时候该升级到 sandbox runtime、dev container 或 VM。
开局先说结论：让 Claude Code 少弹权限确认，不等于它更安全。
在 Claude Code 里，权限模式回答的是「这一步要不要问你」；sandbox 回答的是「命令真的跑起来以后，最多能碰到哪些文件和网络」。这两个问题分开，很多自动化脚本才不会一边顺手，一边把风险放大。
这一篇拆 Claude Code 的 Sandboxing：
/sandbox、Sandboxed Bash、allowed paths、allowed domains、sandbox runtime、dev container，以及它和 permission modes / permission rules 的边界。1/ 先把四个概念拆开：mode、rule、sandbox、environment
如果只记一句话：permission 是闸门，sandbox 是笼子。
Claude Code 的 permission modes 控制模型在编辑文件、运行 shell、发起网络请求等动作前，是否需要向你确认；官方列出的模式包括
default、acceptEdits、plan、auto、dontAsk、bypassPermissions 等。1Permission rules 更像细粒度白名单 / 黑名单：
Allow 让匹配动作免确认，Ask 要求每次确认，Deny 直接阻止；规则评估顺序是 deny → ask → allow，所以一个更具体的 allow 不能覆盖更宽的 deny。2Sandboxing 解决的是另一个层面：即便某条 Bash 命令被允许执行，它和它启动的子进程也只能访问被放进 sandbox 的路径和网络域名；官方把 Bash sandbox 定位成减少 permission prompt、同时用 OS 限制 Bash 命令活动范围的机制。3
Environment isolation 则再往外一层：不是只关 Bash，而是把整个 Claude Code process 或完整开发环境放进隔离边界，例如 sandbox runtime、dev container、custom container、VM 或 Claude Code on the web。4
可以把它想成一层控制栈：
2/ /sandbox 不是一个开关，而是一个配置面板
Claude Code 提供
/sandbox 命令打开 sandbox 配置面板。官方页面把面板拆成 Mode、Overrides、Config；如果缺依赖，还会显示 Dependencies。3我建议你把这三个区域这样理解：
| 面板区域 | 你该关心什么 | 实战判断 |
|---|---|---|
| Mode | 当前 Bash 是否在 sandbox 下跑 | 先确认它有没有真正启用，不要只看权限弹窗少没少 |
| Overrides | 某些命令是否临时绕过 sandbox | 只给你非常确定的命令开例外 |
| Config | 哪些路径、哪些网络域名可以访问 | 按任务最小授权，不要一次性全开 |
默认情况下，sandboxed commands 只能写工作目录和 session temp directory；第一次访问新的网络域名时，Claude Code 会询问。3
这点很关键。很多人看到 Claude 能自动跑测试、装包、查文档，就会把它理解成「已经全自动」。实际更准确的说法是：它可以自动跑，但自动跑的活动范围应该被你预先框住。
3/ Sandboxed Bash 的边界：只关 Bash，不关所有东西
Sandboxed Bash 主要隔离 Bash 命令和 Bash 启动的子进程；它不需要 Docker，macOS 上配置成本最低，Linux / WSL2 需要额外依赖，原生 Windows 不支持，Windows 用户需要在 WSL2 中运行。3
但别把它误读成「整个 Claude Code 都进了沙箱」。官方在 sandbox environment 对比里明确区分：Sandboxed Bash 限制的是 Bash；内置 file tools、MCP servers、hooks 仍直接运行在 host。4
这就是很多安全误区的来源：
- 你以为「Bash 被关住了」等于「所有文件读取都被关住了」。不一定。
- 你以为「网络域名要确认」等于「不会泄露数据」。也不一定。
- 你以为「项目目录可写」等于「只会改安全文件」。更不一定。
官方也提醒：sandbox 降低风险，但不消除风险；只要允许网络出口，可读数据仍有泄露可能；只要把项目目录挂成可写，代码仍可能被修改。4
所以，Sandboxed Bash 最适合的不是「我从此完全放心」，而是这三类场景：
- 你想减少常见 Bash 操作的确认弹窗；
- 你愿意把命令限制在当前 repo 和少量临时目录；
- 你能明确列出本任务需要访问的外部域名。
4/ permission 和 sandbox 应该叠着用
Claude Code 的权限规则由 Claude Code 执行，不由模型、prompt 或
CLAUDE.md 改写。官方还区分了 bare tool deny 和 scoped deny：例如裸 Bash deny 会把整个 Bash 工具从上下文中移除，而类似 Bash(rm *) 的 scoped deny 会保留工具，但阻止匹配调用。2这意味着你可以把两层控制拆成下面这套顺序：
- Deny 先挡危险动作。比如删除、上传、改密钥、访问敏感目录这类，不要交给模型自己判断。
- Ask 用来保留人工确认点。比如第一次访问新域名、执行数据库迁移、安装陌生脚本。
- Allow 只放行高频低风险动作。比如
npm test、pytest、只读检查命令。 - Sandbox 再限制执行后的实际活动范围。即使命令被 allow，它也只能触达被允许的路径和域名。
这里有个容易踩坑的细节：permission modes 和 rules 不是 sandbox 的替代品。除
bypassPermissions 外，protected paths 不会被自动批准；deny 和 explicit ask 规则在所有模式下适用；allow rules 对 bypassPermissions 无效。1换成人话：你可以减少确认，但不要把确认系统当成隔离系统；你可以加 sandbox，但不要把 sandbox 当成规则系统。
5/ allowed paths 与 allowed domains：只开任务真正需要的旋钮
Sandbox 配置最值得花时间的是两类旋钮：路径和网络。
路径决定 Bash 能读写哪里。默认能写工作目录和 session 临时目录，这对跑测试、生成构建文件、写临时脚本通常够用；如果你把更多 host 目录加进去，就等于把更多真实文件暴露给命令及其子进程。3
网络域名决定命令能连哪里。官方说明首次访问新的网络域名会询问，这适合把「装依赖、查包源、访问 API」和「随便向外发请求」区分开。3
我的实战建议是反过来写配置：不要先问「我能不能全开」，而是先问「这个任务如果少了哪个权限就一定失败」。
举个常见 repo 任务：
目标：让 Claude 修一个前端组件 bug，并跑测试。
建议开放：
- 当前项目目录：可读写
- session temp：可读写
- npm / pnpm registry：按需联网
建议继续拦住：
- ~/.ssh
- 云厂商凭据目录
- 浏览器 Cookie / 本地密钥
- 和任务无关的个人目录这不是繁琐，是把「自动化」变成「可控自动化」。
6/ 什么时候该升级到 sandbox runtime、dev container 或 VM？
如果你只想限制 Bash，Sandboxed Bash 是轻量选项；如果你想把整个 Claude Code process，包括 file tools、MCP servers、hooks 都放进隔离边界，就要看 sandbox runtime 或更重的环境隔离方案。4
官方的环境对比大致可以这样读：
| 方案 | 隔离对象 | Docker 依赖 | 适合场景 |
|---|---|---|---|
| Sandboxed Bash tool | Bash 命令及其子进程 | 不需要 | 想减少 Bash prompt，但仍在本机开发 |
| Sandbox runtime | 整个 Claude Code process | 不需要 | 想把 file tools / MCP / hooks 也纳入边界 |
| Dev container | 完整开发环境 | 需要 | 团队已有容器化开发流，需要一致环境 |
| Custom container | 完整开发环境 | 需要 | 需要自己定义更复杂的容器镜像 |
| Virtual machine | 完整 OS | 不需要 Docker | 处理不信任代码，愿意付出更高配置成本 |
| Claude Code on the web | Anthropic 托管完整 OS | 无需本地配置 | 使用托管环境，依赖 Claude subscription 与 GitHub |
这些选项来自官方 sandbox environments 对比表；核心差异不是「谁更高级」，而是「你要隔离 Bash，还是隔离整个运行环境」。4
我给一个简单决策法：
- 日常可信 repo：先用 Sandboxed Bash，少开路径，少开域名。
- 需要无人值守跑较长任务：考虑 sandbox runtime，把更多 Claude Code 行为纳入边界。
- 团队开发环境已经容器化：用 dev container，顺便解决依赖一致性。
- 代码来源不完全可信：别在主力机器裸跑，优先 VM 或一次性隔离环境。
7/ dev container 不是免死金牌，尤其别乱挂 secrets
Dev container 的价值是定义一致、隔离的开发环境：Claude Code 在容器内运行，命令也在容器内执行，本地仓库仍能看到文件编辑；官方文档提到它支持 VS Code、GitHub Codespaces、JetBrains IDE、Cursor 等 dev container 工作流。5
但 dev container 不会自动保护你主动挂进去的东西。官方特别提醒：使用
--dangerously-skip-permissions 时，dev container 不能阻止恶意项目泄露容器内可访问内容，包括 ~/.claude 中的 Claude Code 凭据。5所以别把
~/.ssh、云厂商凭据、长期 token 这类 host secrets 顺手挂进容器。更稳的做法是用 repo-scoped token、短期 token，或者把敏感凭据留在容器外。5这段值得反复念：容器隔离的是边界，不是你的配置习惯。你把钥匙挂进去，容器就不能替你证明钥匙安全。
8/ 给 AI 开发者的一套最小落地顺序
如果你今天只想把 sandboxing 用起来，不用一上来设计复杂安全体系。按这个顺序就够了：
- 找一个非敏感项目，打开 Claude Code。
- 输入
/sandbox，先看 Mode 是否启用。 - 看 Config 里哪些路径可写、哪些网络域名会被询问。
- 只允许当前 repo、session temp 和必要包源。
- 给高风险 Bash pattern 加 deny，不要指望模型自觉避开。
- 跑一次真实任务：读代码、改一处小 bug、执行测试。
- 如果发现 file tools / MCP / hooks 也需要隔离，再评估 sandbox runtime 或 dev container。
到这里，Claude Code 的自动化才更接近你想要的状态：不是「一路全放行」，而是「能自动做事，但只能在你画好的边界里做事」。
9/ 最后给一张速记卡
| 你想控制的问题 | 用什么机制 | 不要误会成什么 |
|---|---|---|
| 要不要问我 | permission mode | 不是安全隔离 |
| 某类动作能不能做 | permission rules | 不是文件系统边界 |
| Bash 跑起来能碰哪里 | Sandboxed Bash | 不覆盖所有 Claude Code 工具 |
| 整个 Claude Code 进边界 | sandbox runtime / container / VM | 成本更高，需要按场景选择 |
| 容器里有没有 secrets | dev container 配置习惯 | 容器不会自动保护你挂进去的密钥 |
本期实践建议：下次让 Claude Code 自动修 bug 前，先别急着开
bypassPermissions 或全局放行。先跑 /sandbox，把路径和域名收窄到任务所需，再用 deny / ask / allow 把危险动作、确认点和高频动作分层。权限弹窗变少可以是效率提升，但前提是 sandbox 真的把活动范围关住了。References
- 1Choose a permission mode - Claude Code Docs
docs.anthropic.com
- 2Configure permissions - Claude Code Docs
docs.anthropic.com
- 3Configure the sandboxed Bash tool - Claude Code Docs
docs.anthropic.com
- 4Choose a sandbox environment - Claude Code Docs
docs.anthropic.com
- 5Development containers - Claude Code Docs
docs.anthropic.com
This story was produced automatically by a channel. One sentence is all it takes for Neodrop to keep producing for you.