# Claude Code Sandbox 与 Dev Container

> 比较 Claude Code 内置 Bash sandbox、Sandbox runtime、Dev Container、自定义容器和 VM,并说明持久化认证、网络出口、凭据保护和缓存边界。

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

当你让 Claude Code 少问确认、自动跑测试、处理第三方仓库或在 CI/远程环境里执行任务时,要先决定隔离边界。权限规则控制“能不能运行”,sandbox 和容器控制“运行后能碰到什么”。




任何 sandbox 都不会改变已经发送给模型的 prompt、文件内容和工具结果。它保护本机文件、网络和凭据,不是数据保留或训练策略边界。




## 隔离方案对比

| 方案 | 隔离范围 | 需要 Docker | 适合 |
| --- | --- | --- | --- |
| Sandboxed Bash tool | Bash 命令和子进程 | 否 | 日常减少命令确认 |
| Sandbox runtime | 整个 Claude Code 进程、MCP、Hooks | 否 | 不想用 Docker,但要隔离更多进程 |
| Dev Container | 完整开发环境 | 是 | 团队统一工具链、Codespaces、IDE container |
| 自定义容器 | 完整开发环境 | 是 | 企业已有容器平台、CI、远程执行 |
| VM | 完整操作系统 | 否 | 不可信仓库、强隔离、合规 |
| Claude Code on the web | Anthropic 托管环境 | 否 | 移动端委派、无需本地环境 |

内置 Bash sandbox 只约束 shell 命令。内置 Read/Edit、MCP server 和 hooks 不一定在同一个 OS 边界里。需要更强隔离时,用 Sandbox runtime、容器或 VM。

## Dev Container 基线

最小 `.devcontainer/devcontainer.json`:

```json title=".devcontainer/devcontainer.json"
{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}
```

常见增强:

```json title=".devcontainer/devcontainer.json"
{
  "mounts": [
    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
  ],
  "containerEnv": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "DISABLE_AUTOUPDATER": "1"
  }
}
```

`~/.claude` 存放认证、用户 settings 和 session history。没有 volume 时,每次 rebuild 都要重新登录。用 `${devcontainerId}` 可以按项目隔离认证状态。

## 容器里的组织策略

在 Linux 容器中,Claude Code 会读取 `/etc/claude-code/managed-settings.json`:

```dockerfile title="Dockerfile"
RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json
```

这适合统一默认值,但它仍然在项目仓库里,有写权限的人可以改 Dockerfile。真正不可绕过的策略应通过 MDM、server-managed settings、系统文件或平台策略下发。

## 网络出口

Dev Container 可以用防火墙脚本只允许必要域名。参考做法:

| 域名 | 用途 |
| --- | --- |
| `passion8.cc` | Passion8 模型请求和控制台 |
| `api.anthropic.com` | Anthropic API、WebFetch 预检、server-managed settings |
| `claude.ai` | 官方账号登录和 Web 入口 |
| `downloads.claude.ai` | 原生 binary、插件可执行文件、更新 |
| `raw.githubusercontent.com` | release notes、插件市场和参考配置 |

如果完全禁用非必要流量,设置:

```bash
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
```

但安装、插件、WebFetch、Chrome bridge 或 Artifacts 仍可能需要额外域名。企业应把“模型请求域名”和“客户端辅助流量域名”分开列。

## 凭据保护

不要把宿主机长期凭据直接 mount 进容器,尤其是:

- `~/.ssh`
- `~/.aws/credentials`
- `~/.config/gcloud`
- `.env`
- npm、GitHub、云厂商长期 token

更稳的做法:

| 需求 | 建议 |
| --- | --- |
| Git 访问 | repo-scoped deploy key 或短期 token |
| 云 provider | workload identity、Codespaces secret、OIDC |
| Passion8 API Key | 用户级 secret 或 token helper |
| npm/pnpm install | 只读 registry token,并限制域名 |

如果启用 Claude Code sandbox,还可以保护常见凭据:

```json title=".claude/settings.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" }
      ]
    }
  }
}
```

## 权限模式搭配

| 模式 | 建议环境 |
| --- | --- |
| default | 日常本机开发 |
| plan | 高风险改动、先审方案 |
| auto | 有 sandbox 或容器时减少确认 |
| bypassPermissions | 只在可信 repo、非 root 容器、VM 或强 sandbox 中使用 |

`--dangerously-skip-permissions` 会移除逐项确认。容器能降低宿主机风险,但不能防止仓库内文件被修改,也不能防止容器内可访问凭据被使用或外传。

## 缓存和成本

| 场景 | 5m / 1h 解释 |
| --- | --- |
| 每次 rebuild 清空 `~/.claude` | 会话、settings 和认证状态变化,缓存命中更差 |
| 持久化 `.claude` volume | 同项目连续会话前缀更稳定 |
| 容器固定 Claude Code 版本 | system prompt 和工具行为更稳定 |
| 每个 CI job 新容器 | 多数情况下是冷前缀,5 分钟 TTL 帮助有限 |
| 网络/权限策略变更 | tools、settings、sandbox 提示变化会影响 cache key |
| Passion8 网关 | 仍要看上游是否支持 1 小时 TTL 和 usage 字段透传 |

## 官方参考

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

## 相关页面



- [沙箱与隔离环境](https://docs.passion8.cc/docs/claude-code/sandboxing): Bash sandbox、Sandbox runtime、Docker、VM、网络和凭据边界。
- [权限与模式](https://docs.passion8.cc/docs/claude-code/permissions): allow/ask/deny、auto mode、plan mode 和 bypassPermissions。
- [企业部署总览](https://docs.passion8.cc/docs/claude-code/enterprise-deployment-overview): provider、策略、权限、监控和数据边界的组织级决策。
- [Headless 自动化](https://docs.passion8.cc/docs/claude-code/headless): CI、脚本、JSON 输出、权限、沙箱和结构化结果。