沙箱与隔离环境

沙箱的作用是限制已经被允许执行的命令能碰到什么文件、网络和凭据。权限模式决定“能不能运行”,沙箱决定“运行后被关在哪里”。当你让 Claude Code 自动运行命令、后台执行任务或处理不完全可信的仓库时,两者必须一起考虑。

#隔离方案对比

Bash 沙箱只约束 shell 命令。内置 Read/Edit、MCP server 和 hooks 不在它的进程边界里。如果需要把这些也放进同一个 OS 隔离边界,选择 Sandbox runtime、容器或 VM。

#与权限模式的关系

--dangerously-skip-permissions 会跳过大量逐项确认。只有在容器、VM、Sandbox runtime 或严格沙箱里才建议使用。Auto mode 有安全分类器,但它不是隔离边界,无人值守时仍建议叠加沙箱或容器。

#快速启用 Bash 沙箱

Linux 或 WSL2 需要安装:

sudo apt-get install bubblewrap socat

Fedora:

sudo dnf install bubblewrap socat

原生 Windows 不支持 Bash 沙箱,建议用 WSL2、容器或 VM。

#常用沙箱 settings

启用并要求沙箱可用:

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

允许特定目录写入:

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

默认读取策略仍可能读到家目录里的凭据文件。建议显式保护常见凭据:

{
  "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" }
      ]
    }
  }
}

需要让工具继续鉴权,但不暴露真实 token 时,可以用 mask。它依赖 TLS 终止和允许域名,只应放在用户、CLI 或托管 settings 中,不要放进项目仓库。

#网络控制

沙箱通过代理控制命令网络访问。默认没有预先允许的域名,第一次访问会询问。团队环境可以用 allowedDomains 固定允许列表,再用 managed settings 锁住。

{
  "sandbox": {
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "*.github.com",
        "passion8.cc"
      ]
    }
  }
}

如果要强制只允许托管策略里的域名,使用 allowManagedDomainsOnly。对网络隔离要求高的企业,应接入自定义代理并终止 TLS,否则仅靠主机名 allowlist 不能检查加密流量内容。

#组织强制策略

通过 MDM、系统 managed settings 或 server-managed settings 可以强制沙箱:

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

建议一起下发:

• sandbox.credentials: 阻止读取 SSH、云厂商、包管理器凭据。
• allowManagedReadPathsOnly: 防止用户通过本地 allowRead 扩大读取范围。
• allowManagedDomainsOnly: 防止用户通过本地配置扩大网络域名范围。
• 精简的 excludedCommands: 只把确实不能在沙箱里运行的命令放出去。

更多企业策略见 企业网络与集中管控。

#常见故障

#限制

• Bash 沙箱不隔离内置 Read/Edit、MCP server 和 hooks。
• 允许广泛网络域名会增加数据外传风险。
• 允许写 $PATH、shell 配置或系统目录会削弱隔离。
• Unix socket 可能绕过边界,尤其是 Docker socket。
• Computer Use 控制的是你的真实桌面,不在 Bash 沙箱内。

如果目标是安全地处理不可信代码,优先选择容器或 VM。如果目标是减少日常命令确认,从 /sandbox auto-allow 开始就够用。

#官方参考

• Configure the sandboxed Bash tool
• Choose a sandbox environment
• Development containers

#相关页面