Claude Code 的沙箱功能通过操作系统级别的隔离，在不需要每次都询问权限的情况下，为 AI 执行创建安全边界。
为什么需要沙箱？
传统的权限审批模式有明显缺点：
- 审批疲劳：反复点击「允许」会让用户放松警惕，潜在危险操作更容易被误批
- 效率低下：频繁中断打断开发节奏
- 限制自主性：Claude Code 无法在等待审批期间高效工作
沙箱的解决方案：提前定义清晰边界，边界内自动执行，边界外立即拦截并通知。
核心隔离机制
文件系统隔离
默认行为：
| 操作 | 默认范围 |
|---|---|
| 读取 | 允许读取整台电脑（部分目录除外） |
| 写入 | 仅限当前工作目录及子目录 |
写入范围之外的文件修改请求会被立即拦截。可通过 sandbox.filesystem.allowWrite 扩展写权限。
网络隔离
通过运行在沙箱外部的代理服务器控制网络访问：
- 只有批准的域名可以访问
- 新域名请求触发权限提示
- 支持自定义���理规则
- 覆盖所有子进程：包括
kubectl、terraform、npm等工具调用的网络请求
OS 级执行
| 平台 | 使用技术 |
|---|---|
| macOS | Seatbelt（内置沙箱框架） |
| Linux | bubblewrap |
| WSL2 | bubblewrap（同 Linux） |
| WSL1 | ❌ 不支持（缺少内核功能） |
关键特性：所有子进程继承相同安全边界——Claude Code 执行的命令及其子命令都受同等约束。
快速启用
Linux / WSL2 先安装依赖
bash
# Ubuntu/Debian
sudo apt-get install bubblewrap socat
# Fedora
sudo dnf install bubblewrap socat启用沙箱
bash
/sandbox打开模式选择菜单（缺少依赖时会显示安装说明）。
两种沙箱模式
| 模式 | 说明 |
|---|---|
| Auto-allow | 沙箱内命令自动执行无需审批；无法沙箱化的命令（如访问未批准域名）退回常规权限流程 |
| Regular 权限 | 即使在沙箱内，所有 Bash 命令仍需标准权限审批 |
两种模式的文件系统和网络限制完全相同，区别仅在于沙箱内命令是否自动批准。
settings.json 配置示例
基础配置
json
{
"sandbox": {
"enabled": true
}
}扩展写权限（子进程需要写出工作目录时）
json
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["~/.kube", "//tmp/build"]
}
}
}路径前缀规则：
| 前缀 | 含义 | 示例 |
|---|---|---|
// | 文件系统绝对路径 | //tmp/build → /tmp/build |
~/ | 相对 home 目录 | ~/.kube → $HOME/.kube |
/ | 相对 settings.json 所在目录 | /build → $SETTINGS_DIR/build |
./ 或无 | 相对路径（运行时解析） | ./output |
限制读写权限
json
{
"sandbox": {
"filesystem": {
"denyRead": ["~/.ssh", "~/.gnupg"],
"denyWrite": ["~/.bashrc", "~/.zshrc"]
}
}
}自定义网络代理
json
{
"sandbox": {
"network": {
"httpProxyPort": 8080,
"socksProxyPort": 8081
}
}
}适合需要解密检查 HTTPS 流量、自定义过滤规则或集成现有安全基础设施的组织。
安全防护效果
防提示注入：即使攻击者通过提示注入操控 Claude Code 的行为：
- 无法修改
~/.bashrc等配置文件 - 无法向攻击者控制的服务器传输数据
- 无法从未授权域名下载恶意脚本
- 无法调用未批准服务的 API
降低攻击面：限制恶意 NPM 包、被攻击的构建脚本、社会工程学攻击的潜在危害。
沙箱 vs 权限：互补而非替代
| 机制 | 作用层级 | 适用范围 |
|---|---|---|
| 权限系统 | 工具调用前评估 | 所有工具（Bash/Read/Edit/WebFetch/MCP） |
| 沙箱 | OS 级执行隔离 | 仅 Bash 命令及其子进程 |
sandbox.filesystem 和 Edit/Read 权限规则的路径会合并生效，两者共同构建最终的沙箱配置。
已知安全限制
- 网络过滤：仅限制域名，不检查流量内容，用户需自行确保只允许可信域名
- Unix Socket：
allowUnixSockets配置可能意外开放强大系统服务（如/var/run/docker.sock相当于访问宿主机） - 写权限扩展：允许写入包含
$PATH可执行文件的目录，可能导致权限提升攻击 - Docker 内 Linux 沙箱：
enableWeakerNestedSandbox模式大幅降低安全性，仅在有额外隔离保障时使用
原文：Sandboxing - Claude Code Docs | 来源：Anthropic 官方文档