本页目录11
- 通过 `/sandbox` 命令即可启用沙盒，macOS 开箱即用，Linux/WSL2 需额外安装 `bubblewrap` 和 `socat`
- 沙盒有两种模式：auto-allow（自动放行沙盒内命令）和 regular permissions（保留常规审批提示）
- 文件系统默认只允许写入工作目录和临时目录，可通过 `sandbox.filesystem.allowWrite` 扩展，也可用 `denyRead`/`denyWrite` 收窄
- 网络隔离采用代理方式，默认无预授权域名，首次访问新域名会弹出审批；可用 `allowedDomains` 预授权
- 企业可通过 managed settings 强制开启沙盒并设置 `failIfUnavailable: true` 和 `allowUnsandboxedCommands: false` 实现硬性隔离
- 沙盒不是完整隔离边界：仅约束 Bash 子进程，不覆盖 Read/Edit/Write 工具；网络代理不做 TLS 检查，存在域名前置绕过风险
本文是对官方文档的中文要点摘要，完整内容以原文为准：https://code.claude.com/docs/en/sandboxing
什么是沙盒 Bash 工具
Claude Code 内置的沙盒允许 Claude 直接运行大多数 shell 命令，无需逐条审批。你预先定义哪些文件路径和网络域名可被访问，操作系统在进程级别强制执行这一边界，包括所有子进程（如 kubectl、npm、terraform 等）。
快速开始
平台支持
| 平台 | 隔离机制 | 前置条件 |
|---|---|---|
| macOS | Seatbelt | 无需安装 |
| Linux | bubblewrap | sudo apt-get install bubblewrap socat |
| WSL2 | bubblewrap | 同 Linux；WSL1 不支持 |
| 原生 Windows | 不支持 | 需在 WSL2 中运行 |
Ubuntu 24.04+ 还需额外配置 AppArmor 规则，允许 bwrap 创建用户命名空间（详见原文）。
开启步骤
- 在 Claude Code 会话中运行
/sandbox，打开配置面板 - 在 Mode 标签页选择沙盒模式
- 让 Claude 运行命令，首次访问新网络域名时会弹出审批
默认写入到当前工作目录和会话临时目录（$TMPDIR）；若缺少依赖，面板只显示 Dependencies 标签页。
两种沙盒模式
Auto-allow 模式：沙盒内命令直接运行，无需审批。但以下情况仍会触发提示：
- 命中显式 deny 规则
rm/rmdir目标是/或 home 目录等关键路径- 带内容范围的 ask 规则（如
Bash(git push *)）
Regular permissions 模式：所有 Bash 命令走常规审批流程，即使已沙盒化。
Auto-allow 模式与 permission mode 是独立的——即便未开启「accept edits」模式，沙盒内命令仍会自动执行。
配置文件系统隔离
在 settings.json 中通过 sandbox.filesystem 配置：
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["~/.kube", "/tmp/build"],
"denyRead": ["~/"],
"allowRead": ["."]
}
}
}
路径前缀规则：
/开头 → 绝对路径~/开头 → 相对于 home 目录./或无前缀 → 项目设置时相对于项目根目录，用户设置时相对于~/.claude
多个配置作用域的数组会合并（不覆盖），所有路径共同生效。
注意：默认读权限允许访问整机，包括 ~/.aws/credentials、~/.ssh/ 等凭据文件，建议主动加入 denyRead，或使用 sandbox.credentials 屏蔽凭据文件并清除敏感环境变量。
配置网络隔离
网络通过运行在沙盒外的代理服务器控制，默认无预授权域名。可用 allowedDomains 预授权域名，用 deniedDomains 屏蔽特定域名（即使更宽泛的 allowedDomains 通配符已放行）：
{
"sandbox": {
"enabled": true,
"allowedDomains": ["registry.npmjs.org", "api.github.com"],
"deniedDomains": ["example.com"]
}
}
代理只基于客户端提供的主机名做放行决策，不做 TLS 检查。允许
github.com这类宽泛域名可能存在域名前置（domain fronting）等数据外泄绕过风险。如需更强保障，需配置自定义 MITM 代理并在沙盒内安装其 CA 证书。
逃生舱（Escape Hatch）
当命令因沙盒限制失败时，Claude 会分析错误并尝试以 dangerouslyDisableSandbox 参数在沙盒外重试（仍需用户审批）。
设置 "allowUnsandboxedCommands": false 可禁用此机制，进入严格沙盒模式，所有命令必须在沙盒内执行或在 excludedCommands 中显式排除。
企业级部署
通过 managed settings（MDM 或 server-managed settings）强制执行：
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"allowUnsandboxedCommands": false
}
}
failIfUnavailable: true：沙盒依赖缺失时，Claude Code 拒绝启动（而非降级运行）allowManagedReadPathsOnly: true：忽略用户/项目添加的allowRead条目，只信任 managed 值allowManagedDomainsOnly: true：同上，锁定网络域名；非放行域名被直接拦截而非弹窗- 自定义代理：通过
sandbox.network下的httpProxyPort/socksProxyPort接入企业安全基础设施
已知限制与注意事项
| 限制 | 说明 |
|---|---|
| 覆盖范围 | 只隔离 Bash 子进程；Read/Edit/Write 工具走独立权限体系 |
| 网络安全 | 代理不检查 TLS，存在域名前置绕过可能 |
| Apple Events | 默认禁止；开启 allowAppleEvents 会降低代码执行隔离性 |
| Docker | 与沙盒不兼容，需将 docker * 加入 excludedCommands |
jest | 需加 --no-watchman 参数 |
| 环境变量 | 沙盒命令默认继承父进程环境（含凭据），可用 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 过滤 |
常见工具故障排查速查
- host-not-allowed 错误：在提示时授权该域名即可
- Go 工具 TLS 验证失败（macOS）：将
gh、gcloud、terraform加入excludedCommands - bubblewrap 在容器内失败：设置
enableWeakerNestedSandbox: true（需确保外层容器已提供隔离） - seccomp 过滤器缺失：运行
npm install -g @anthropic-ai/sandbox-runtime安装