Claude Code SDK #30：Sandboxing 全解——/sandbox × allowed paths × allowed domains，把 Bash 的活动范围关进笼子

开局先说结论：让 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 等。1

Permission rules 更像细粒度白名单 / 黑名单：Allow 让匹配动作免确认，Ask 要求每次确认，Deny 直接阻止；规则评估顺序是 deny → ask → allow，所以一个更具体的 allow 不能覆盖更宽的 deny。2

Sandboxing 解决的是另一个层面：即便某条 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

可以把它想成一层控制栈：

Claude Code sandbox 控制栈示意图 — *自制示意图：从 permission mode、permission rules 到 sandbox 边界，再到 dev container / VM 级隔离；依据 Anthropic 官方 permission 与 sandbox 文档整理。3*

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

Claude Code sandbox 配置旋钮示意图 — *自制示意图：把 allowed paths、allowed domains、unsandboxed fallback 当成三类独立旋钮，不要用一个总开关替代最小授权。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

Claude Code 隔离方式选择示意图 — *自制示意图：按隔离对象从 Sandboxed Bash、sandbox runtime、dev container 到 VM / hosted OS 逐级比较；依据 Anthropic 官方 sandbox environments 对比表整理。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 真的把活动范围关住了。