它到底是什么

/sandbox 是 Claude Code 的沙箱控制面板命令。运行后弹出一个交互面板，让你为当前会话的 Bash 工具开启 OS 级别的文件系统与网络隔离。沙箱由操作系统原语（macOS 上为 Seatbelt、Linux/WSL2 上为 bubblewrap）在进程层面强制执行，覆盖 Bash 命令及其所有子进程。

/sandbox 不是 权限模式（permission mode）。权限模式决定工具调用"能不能跑"，沙箱决定命令跑起来之后"能访问什么"。

平台支持：

怎么触发 / 怎么使用

1. 打开沙箱面板

在任意 Claude Code 会话中直接输入：

/sandbox

面板包含三个 Tab：

• Mode：选择审批方式（见下方"沙箱模式"）
• Overrides：控制沙箱失败时是否允许命令降级到无沙箱流程（allowUnsandboxedCommands）
• Config：查看最终合并后的沙箱配置

若面板只显示 Dependencies Tab，表示缺少必要依赖，需先安装再重启 Claude Code。

2. 安装 Linux / WSL2 依赖（如适用）

# Ubuntu / Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

可选——用于 Unix domain socket 阻断的 seccomp filter：

npm install -g @anthropic-ai/sandbox-runtime

3. Ubuntu 24.04+ 额外步骤（AppArmor 限制）

Ubuntu 24.04 及更高版本（含 WSL2）的 AppArmor 默认阻止 bubblewrap 创建用户命名空间。检查是否受影响：

sysctl kernel.apparmor_restrict_unprivileged_userns
# 返回 1 时需要以下操作，返回 0 或不存在则跳过

添加允许 bwrap 的 AppArmor profile：

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

4. 选择沙箱模式

在 Mode Tab 选择以下两种模式之一：

Auto-allow 模式：沙箱内的 Bash 命令自动放行，无需逐条确认。无法在沙箱内运行的命令降级到常规权限流程。

Regular permissions 模式：即使命令在沙箱内运行，仍走常规权限流程逐条提示。控制更精细，但确认次数更多。

保存 / 配置 / 集成

设置作用域

选择模式后，Claude Code 将配置写入：

常用配置片段

允许子进程写入工作目录之外的路径（如 kubectl、terraform、npm 常需要）：

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

屏蔽读取凭证目录（默认读权限覆盖全盘，含 ~/.aws、~/.ssh）：

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

专用凭证保护 sandbox.credentials(v2.1.187+):声明沙箱命令不可访问的凭证文件与环境变量。列出的文件路径在沙箱内被拒绝读取(等同 filesystem.denyRead),列出的环境变量在每条沙箱命令运行前被 unset。该专用块把凭证规则与待 unset 的环境变量集中在一起,与一般文件系统规则分开。每个条目的 mode 仅支持 "deny" 一个值(显式字段是为兼容未来的模式)。注意:默认不存在内置凭证拒绝清单,只有你列出的文件/变量才受限;且仅作用于沙箱内的 Bash 命令。

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

严格模式（组织强制部署推荐）：

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

自定义代理（用于 HTTPS 流量审计）：

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

凭证隔离

沙箱内 Bash 命令默认继承父进程环境变量（含 API 密钥）。要从所有子进程(不限沙箱)中擦除 Anthropic 及云提供商凭证,设置 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 环境变量(官方 sandboxing/env-vars 页只说 "set CLAUDE_CODE_SUBPROCESS_ENV_SCRUB",未指定具体取值):

export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1

注:官方文档仅要求「设置该变量」,=1 是常见约定写法,但官方页面未明确规定其值;若需仅针对沙箱命令精确擦除特定变量,优先用上文的 sandbox.credentials.envVars。

路径前缀规则

运行约束 / 限制

跟同类原语对比

经典使用场景

• 自主长跑任务：开启 auto-allow 模式 + 沙箱，让 Claude 跑测试、构建、脚手架生成而无需频繁点击确认，同时通过 OS 边界限制影响范围。
• 保护凭证目录：将 ~/.aws、~/.ssh 加入 denyRead，防止提示注入攻击通过沙箱内命令外泄密钥。
• 组织强制部署：在 managed settings 中配置 failIfUnavailable: true + allowUnsandboxedCommands: false，确保所有开发者 Bash 操作都在沙箱内执行。
• 容器环境内运行：在无特权容器（如 CI Docker）中设置 enableWeakerNestedSandbox: true，允许 bubblewrap 在已有容器隔离边界内工作。

常见坑

1. jest 挂起或失败：watchman 与沙箱不兼容。改用 jest --no-watchman。

2. docker 命令失败：docker 与沙箱不兼容。将 docker * 加入 excludedCommands 使其在沙箱外运行。

3. macOS 上 Go 系 CLI（gh、gcloud、terraform）TLS 验证失败：这些工具在 Seatbelt 下可能出现 TLS 验证错误。将其加入 excludedCommands，或配合 MITM 代理时设置 enableWeakerNetworkIsolation: true。

4. Ubuntu 24.04+ bubblewrap 启动失败：AppArmor 默认阻止用户命名空间创建，按上方步骤添加 bwrap profile 后重启 Claude Code 和 AppArmor 即可。

5. WSL1 用户无法使用：/sandbox 面板会提示 Sandboxing requires WSL2。需将发行版升级至 WSL2 或在没有沙箱的情况下运行 Claude Code。

6. allowWrite 路径被用于权限升级：向含有 $PATH 可执行文件的目录、~/.bashrc/~/.zshrc 等 shell 配置文件开放写权限，可能导致其他进程以不同安全上下文执行恶意代码。开放前需仔细评估目标路径。

7. 宽泛 allowedDomains（如 github.com）可能被域名前置技术绕过：内置代理不做 TLS 检查，domain fronting 等手法可能突破 hostname 过滤。高安全要求场景需配置带 TLS 终止的自定义代理。

来源

• Configure the sandboxed Bash tool — Claude Code 官方文档
• Commands — Claude Code 官方文档
• Settings — Sandbox settings 参考（Claude Code 官方文档）