# Claude Code 沙箱与隔离环境

> 比较 Claude Code 的 Bash 沙箱、Sandbox runtime、Dev Container、Docker、VM 和 Web 云端环境,并说明权限模式、网络、凭据和组织策略。

URL: https://docs.passion8.cc/docs/claude-code/sandboxing
Language: zh-CN
Publisher: Passion8

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




沙箱不会改变发送给模型的内容。Claude Code 读取到的提示词和文件内容,仍会发往 Anthropic API、Passion8 或你配置的 Provider。




## 隔离方案对比

| 方案 | 隔离范围 | 需要 Docker | 适合 |
| --- | --- | --- | --- |
| Bash 沙箱 | Bash 命令和子进程 | 否 | 日常减少命令确认 |
| Sandbox runtime | 整个 Claude Code 进程、MCP、Hooks | 否 | 想隔离 MCP 和 Hooks,但不想用 Docker |
| Dev Container | 完整开发环境 | 是 | 团队标准化开发环境和无人值守任务 |
| 自定义容器 | 完整开发环境 | 是 | 企业已有容器、CI、远程执行平台 |
| 虚拟机 | 完整操作系统 | 否 | 不可信仓库、强隔离、合规场景 |
| Claude Code on the web | Anthropic 托管 VM | 否 | 不想配本地环境,或从移动设备委派任务 |

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

## 与权限模式的关系

| 层 | 控制什么 | 典型配置 |
| --- | --- | --- |
| 权限规则 | 哪些工具、路径、命令、域名可以用 | `permissions.allow`、`permissions.deny` |
| 权限模式 | 是否提示用户批准 | default、plan、auto、bypassPermissions |
| 沙箱 | 命令运行后能访问什么 | `/sandbox`、`sandbox.filesystem`、`sandbox.network` |

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

## 快速启用 Bash 沙箱




  
### 打开沙箱面板

    在 Claude Code 会话中运行:

    ```text
    /sandbox
    ```

    面板会显示 Mode、Overrides、Config。Linux 和 WSL2 还会检查 `bubblewrap`、`socat` 等依赖。
  


  
### 选择模式

    Auto-allow 会自动运行能被沙箱约束的 Bash 命令。Regular permissions 仍保留常规命令确认,但命令运行时会受沙箱限制。
  


  
### 运行测试命令

    默认只允许写当前工作目录和会话临时目录。首次访问新网络域名时会询问。需要更严格时,关闭 unsandboxed fallback。
  





Linux 或 WSL2 需要安装:

```bash
sudo apt-get install bubblewrap socat
```

Fedora:

```bash
sudo dnf install bubblewrap socat
```

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

## 常用沙箱 settings

启用并要求沙箱可用:

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

允许特定目录写入:

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

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

```json
{
  "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 锁住。

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

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

## 组织强制策略

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

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

建议一起下发:

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

更多企业策略见 [企业网络与集中管控](https://docs.passion8.cc/docs/claude-code/enterprise-admin)。

## 常见故障

| 现象 | 处理 |
| --- | --- |
| 命令提示 host not allowed | 允许该域名,或加入 `sandbox.network.allowedDomains` |
| Jest 卡住 | 改用 `jest --no-watchman` |
| Docker 命令失败 | Docker socket 不适合放进沙箱,通常把 `docker *` 放进 `excludedCommands` 并用外层容器隔离 |
| macOS `open` 或 `osascript` 失败 | Apple Events 默认阻止,优先排除该命令; 谨慎启用 `allowAppleEvents` |
| 容器里 bubblewrap 启动失败 | 外层容器已提供隔离时,再考虑 `enableWeakerNestedSandbox` |
| `--dangerously-skip-permissions` 以 root 运行失败 | 不要以 root 跑; 在非 root 容器用户或 VM 中运行 |

## 限制

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

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

## 官方参考

- [Configure the sandboxed Bash tool](https://code.claude.com/docs/en/sandboxing.md)
- [Choose a sandbox environment](https://code.claude.com/docs/en/sandbox-environments.md)
- [Development containers](https://code.claude.com/docs/en/devcontainer.md)

## 相关页面



- [Sandbox 与 Dev Container](https://docs.passion8.cc/docs/claude-code/sandbox-devcontainers): Dev Container、容器、VM、持久化认证、网络出口和缓存边界。
- [权限与模式](https://docs.passion8.cc/docs/claude-code/permissions): 理解 allow/ask/deny、auto mode 和 bypassPermissions 的边界。
- [工具参考](https://docs.passion8.cc/docs/claude-code/tools): 确认哪些工具受权限系统控制,哪些会触发 Bash。
- [Headless 自动化](https://docs.passion8.cc/docs/claude-code/headless): 在 CI 或脚本里运行 Claude Code 时组合沙箱与权限。