沙箱（Sandboxing）是 Claude Code 的原生安全功能，通过 OS 级原语实现文件系统和网络双重隔离，让 Agent 在定义好的边界内自主运行，同时大幅减少权限提示疲劳。
为什么需要沙箱？
传统基于权限的安全依赖用户持续审批 Bash 命令，导致：
- 审批疲劳：反复点击「批准」导致注意力下降，反而不安全
- 效率损失：频繁中断开发流程
- 自主性受限：Claude 必须等待审批，无法高效工作
沙箱通过预先定义边界解决这些问题：边界内的安全命令无需审批，超出边界则立即触发通知。
有效的沙箱需要同时启用文件系统和网络隔离。只有网络隔离而无文件系统隔离时，受攻击的 Agent 可能通过文件系统后门获取网络访问；反之则可能通过网络泄露敏感文件（如 SSH Key）。
沙箱工作原理
文件系统隔离
| 默认行为 | 说明 |
|---|---|
| 写入权限 | 当前工作目录及其子目录 |
| 读取权限 | 整个系统（部分被拒目录除外） |
| 外部写入 | 需要显式授权才能修改工作目录外的文件 |
这些限制在 OS 级别强制执行，所有子进程命令（包括 kubectl、terraform、npm 等）都继承同样的边界，不仅限于 Claude 的文件工具。
网络隔离
通过运行在沙箱外的代理服务器控制网络访问：
- 域名限制：只有批准的域名可被访问
- 用户确认：新域名请求触发权限弹窗（启用
allowManagedDomainsOnly后直接拒绝未允许域名） - 全面覆盖：限制适用于所有脚本、程序和子进程
OS 级实现
| 平台 | 沙箱技术 |
|---|---|
| macOS | Seatbelt（内置，开箱即用） |
| Linux / WSL2 | bubblewrap |
| WSL1 | ❌ 不支持（bubblewrap 需要 WSL2 内核特性） |
安装与启用
macOS：无需安装，开箱即用。
Linux / WSL2：先安装依赖：
# Ubuntu / Debian
sudo apt-get install bubblewrap socat
# Fedora
sudo dnf install bubblewrap socat启用沙箱：
/sandbox
打开菜单选择沙箱模式。若缺少依赖，菜单显示平台安装指引。
两种沙箱模式
| 模式 | 说明 |
|---|---|
| Auto-allow mode | 沙箱内的 Bash 命令自动允许，无需权限提示。无法沙箱化的命令（如需访问非允许主机）回退到常规权限流程；已配置的 ask/deny 规则始终有效 |
| Regular permissions mode | 所有 Bash 命令经过标准权限流程，即便在沙箱内也需审批，提供更多控制 |
注意：Auto-allow mode 独立于权限模式设置。即使不在「accept edits」模式，沙箱内的 Bash 命令也会自动执行——包括修改文件的命令。
配置沙箱
通过 settings.json 的 sandbox 键配置：
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["~/.kube", "//tmp/build"],
"denyWrite": ["/secrets/**"],
"denyRead": ["~/.ssh/**"]
}
}
}路径前缀含义
| 前缀 | 含义 | 示例 |
|---|---|---|
// | 从文件系统根的绝对路径 | //tmp/build → /tmp/build |
~/ | 相对于 home 目录 | ~/.kube → $HOME/.kube |
/ | 相对于 settings 文件所在目录 | /build → $SETTINGS_DIR/build |
./ 或无前缀 | 相对路径（由沙箱运行时解析） | ./output |
多层 settings 合并行为
allowWrite、denyWrite、denyRead 数组在多层 settings 中合并（不覆盖）。如 managed settings 允许写 //opt/company-tools，用户添加 ~/.kube，最终配置包含两者。
工具兼容性说明
| 工具/情况 | 处理方式 |
|---|---|
kubectl、terraform、npm 需写外部路径 | 使用 allowWrite 授权特定路径 |
watchman（Jest 默认使用） | 与沙箱不兼容，使用 jest --no-watchman |
docker | 与沙箱不兼容，在 excludedCommands 中排除 |
| CLI 工具需要访问特定主机 | 首次使用时授权，后续自动允许 |
逃生舱机制（Escape Hatch）
Claude Code 内置一个有意为之的逃生舱：当命令因沙箱限制失败时，Claude 会分析失败原因，并可能用 dangerouslyDisableSandbox 参数重试——这类命令进入常规权限流程，需用户审批。
禁用逃生舱（强制所有命令必须在沙箱内运行）：
{
"sandbox": {
"allowUnsandboxedCommands": false
}
}禁用后，dangerouslyDisableSandbox 参数被完全忽略，命令要么在沙箱内运行，要么在 excludedCommands 中显式排除。
安全收益
| 安全能力 | 说明 |
|---|---|
| 防止提示词注入 | 即使恶意内容触发危险命令，沙箱边界也能阻止影响超出项目目录 |
| 缩小攻击面 | OS 级强制限制，所有子进程继承边界 |
| 透明运行 | 沙箱完全透明，不影响 Claude 正常工作，违规尝试立即通知 |
沙箱的局限性
- 不保护 Claude 文件工具本身（Read/Edit/Write），仅限制 Bash 子进程
- 沙箱是权限系统的补充，不是替代
- 内存攻击、内核漏洞利用等超出沙箱防护范围
开源
Claude Code 的沙箱实现是开源的，可在 GitHub 查看。
原文：Sandboxing - Claude Code Docs | 来源：Anthropic 官方文档