在开发容器（devcontainer）里安全地跑 Claude Code

这篇适合谁，读完能做到什么

适合想让团队里每个工程师都在同一个隔离环境里运行 Claude Code 的开发者，也适合负责制定团队规则的人。读完这篇，你能在仓库里加上开发容器配置，让 Claude Code 的命令在容器里执行，跨重建保留登录状态，并且知道哪些设置会放大风险。

开发容器是什么

开发容器（dev container）是一份由配置定义的隔离环境，团队里每个人都能运行同一套环境^[1]。Claude Code 装在容器里之后，Claude 执行的命令都在容器内运行，你在项目里改的文件则会同步出现在本地仓库中^[1]。

开发容器以 Docker 容器的形式运行，可以在你自己的电脑上，也可以在 GitHub Codespaces 这样的云主机上^[1]。VS Code、GitHub Codespaces、JetBrains IDE 或 Cursor 这类支持 Dev Containers 规范的编辑器，都能连接到它。集成终端、语言服务器和构建工具全都在容器里运行。普通的 Vim 等不支持开发容器的编辑器，不在这个工作流里^[1]。

在 VS Code 里，你可以用 Claude Code 扩展面板，也可以在集成终端里运行 claude。两者都在容器内执行，并且共用同一份 ~/.claude 配置^[1]。

第一步：在 devcontainer.json 里加入 feature

把下面的内容保存为仓库里的 .devcontainer/devcontainer.json；如果已经有这个文件，就把 features 块加进去^[1]：

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

这个 :1.0 标签固定的是 feature 安装脚本的版本，而不是 Claude Code 的版本。安装的始终是最新版 Claude Code，而且容器内默认会自动更新^[1]。想固定版本或关闭自动更新，见后面的组织策略一节。

把 image 那一行换成项目用的基础镜像；如果你的文件用的是 Dockerfile，就直接删掉这一行^[1]。基础镜像里没有 Node.js 时，feature 会自己安装。如果构建时报 Failed to install Node.js and npm 并中止，就在 features 块里、Claude Code feature 之前加上 "ghcr.io/devcontainers/features/node:1": {}，然后重建^[1]。

第二步：重建容器

在 VS Code 里按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows 和 Linux），运行 Dev Containers: Rebuild Container^[1]。在 GitHub Codespaces 或其他工具里，使用该工具自己的重建操作即可^[1]。

第三步：登录

在重建好的容器里打开终端，运行 claude，按提示完成认证^[1]。

用 Anthropic 账号：通过浏览器登录，使用 Claude 或 Anthropic Console 账号^[1]。
用云服务商：通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时，Claude Code 直接使用云服务商的凭证，不会弹出浏览器^[1]。

云服务商的凭证，应当通过 containerEnv、Codespaces 密钥或云上的工作负载身份（workload identity）以环境变量的形式传入容器，不要把宿主机上的凭证文件挂进去^[1]。

重建后保留登录和设置

默认情况下，容器的主目录在重建时会被丢弃，所以工程师每次重建都得重新登录^[1]。Claude Code 把认证 token、用户设置和会话历史保存在 ~/.claude 下；账号信息、个人 MCP 服务器和项目信任记录则放在这个目录之外的 ~/.claude.json 里^[1]。

要两者都保留，就把一个命名卷挂到 ~/.claude，并把 CLAUDE_CONFIG_DIR 设成同一路径，这样 .claude.json 也会写进卷里^[1]：

"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
],
"containerEnv": {
  "CLAUDE_CONFIG_DIR": "/home/node/.claude"
}

这个例子假设容器的 remoteUser 是 node。把 /home/node 换成你的 remoteUser 的主目录即可。如果 containerEnv 已经存在，就把 CLAUDE_CONFIG_DIR 加进那个对象，不要再写一个^[1]。

卷已经挂上，但每次重建后仍然重复首次设置，就检查 CLAUDE_CONFIG_DIR 有没有设。没有它，~/.claude.json 会留在主目录里，重建时和「已完成设置」的记录一起丢失^[1]。

如果不想所有仓库共用一个卷，可以在卷名里加上 ${devcontainerId}，让每个项目的状态各自独立。参考配置用的就是 source=claude-code-config-${devcontainerId}^[1]。

GitHub Codespaces 中，停止再启动 codespace 时 ~/.claude 会保留，但重建容器会把它清空^[1]。要让登录状态跨 codespace 生效，把 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN 存为 Codespaces 密钥即可，密钥会自动以环境变量的形式注入容器^[1]。其中的 token 由 claude setup-token 生成^[1]。

用组织策略约束所有人

同一个镜像和配置在每位工程师的电脑上运行，所以开发容器很适合下发组织策略。Linux 上，Claude Code 会读取 /etc/claude-code/managed-settings.json，它在设置层级中优先级最高，会覆盖工程师在 ~/.claude 或项目 .claude/ 目录里设置的值^[1]。可以在 Dockerfile 里把这个文件复制到位^[1]：

RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json

Dockerfile 在仓库里，任何有写权限的人都能改掉或删掉这一步。如果策略不能让工程师自行绕过，就应该改用服务器端下发的托管设置，或 MDM^[1]。

要让容器里的每个会话都使用某些环境变量，就把它们加进 containerEnv。下面的例子关闭了遥测和错误上报，并禁止安装后自动更新^[1]：

"containerEnv": {
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
  "DISABLE_AUTOUPDATER": "1"
}

注意，CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 同时会关闭 Remote Control 依赖的功能开关拉取，所以容器里的会话无法使用 Remote Control^[1]。

要为可复现构建固定某个 Claude Code 版本，就不用 feature，改在 Dockerfile 里用 npm install -g @anthropic-ai/claude-code@X.Y.Z 安装，并在 containerEnv 里把 DISABLE_AUTOUPDATER 设为 1^[1]。

限制网络出口

可以把容器的对外流量限制在 Claude Code 需要的域名内。网络访问要求一节列出了推理和认证相关的域名，遥测一节则说明如何关闭可选的连接^[1]。

参考容器里有一个 init-firewall.sh 脚本，用来限制对外流量。在容器里运行防火墙需要 NET_ADMIN 和 NET_RAW 两项能力，参考配置通过 runArgs 加上它们。Claude Code 本身并不需要这个脚本或这两项能力，不用的话可以去掉，改用你自己的网络管控^[1]。

跳过权限确认的风险

容器会以非 root 用户运行 Claude Code，并把命令执行限制在容器内，所以无人值守时可以加 --dangerously-skip-permissions。CLI 在 root 下会拒绝这个参数，因此要确认 remoteUser 是非 root 账号^[1]。

这个参数会去掉你逐条审查工具调用的机会。Claude 仍然可以改动挂载进来的工作区文件，这些文件直接出现在你的宿主机上，也能访问容器网络策略允许的任何地址。所以最好和上面的出口限制一起使用^[1]。

即使在容器里，也没有哪个系统能完全免疫攻击。使用这个参数时，恶意项目可以把容器内可访问的任何内容发送出去，包括保存在 ~/.claude 里的 Claude Code 凭证^[1]。因此只在可信的仓库里使用开发容器，留意 Claude 的操作，并且不要把 ~/.ssh 或云凭证文件这类宿主机密钥挂进容器，优先使用限定在单个仓库内或短期有效的 token^[1]。

想减少确认次数又不放弃安全检查，可以改用自动模式（auto mode），由分类器在动作执行前审查^[1]。要禁止工程师使用这个参数，就在托管设置里把 permissions.disableBypassPermissionsMode 设为 "disable"^[1]。

参考容器

anthropics/claude-code 仓库里有一个示例开发容器，它把命令行版本、出口防火墙、持久卷和基于 Zsh 的 shell 组合在一起。它是可以直接运行的示例，并不是长期维护的基础镜像，适合先看各部分怎么配合，再改成自己的配置^[1]。它由三个文件组成：devcontainer.json 负责挂载、runArgs 能力、VS Code 扩展和 containerEnv；Dockerfile 负责基础镜像、开发工具和 Claude Code 的安装；init-firewall.sh 负责限制出口流量^[1]。