开发容器

开发容器（dev container）让你定义一个团队里每位工程师都能运行的、完全一致且隔离的环境。把 Claude Code 装进这个容器后，Claude 运行的命令在容器里执行，而不是在你的主机上，同时你对项目文件的编辑会随你工作出现在本地仓库里。

本页先讲如何在 dev container 里安装 Claude Code，然后是一组自成一体的配置主题：跨重建持久化认证、强制组织策略、限制网络出口和无权限提示运行。读与你的环境匹配的部分即可。

安全提醒：dev container 提供大量保护，但没有系统能完全免疫所有攻击。当用 --dangerously-skip-permissions 执行时，dev container 无法阻止恶意项目外泄容器内任何可访问的东西，包括存放在 ~/.claude 里的 Claude Code 凭据。只在开发受信任的仓库时使用 dev container 并监控 Claude 的活动；避免把 ~/.ssh 或云凭据文件这样的主机密钥挂载进容器，优先用仓库范围或短期的令牌。

dev container 如何与编辑器配合

dev container 以 Docker 容器的方式运行，可以在你的机器上，也可以在 GitHub Codespaces 这样的云主机上。支持 Dev Containers 规范的编辑器（VS Code、GitHub Codespaces、JetBrains IDE 或 Cursor）连接到该容器：你照常在编辑器里浏览和编辑文件，但集成终端、语言服务器和构建工具全部在容器内而不是在主机上运行。不支持 dev container 的编辑器（如纯 Vim）不属于这个工作流。

Claude Code 在容器内运行，所以它看到的文件、依赖和工具与项目工具链的其余部分一样。在 VS Code 里，你既可以用 Claude Code 扩展面板，也可以在集成终端里运行 claude；两者都在容器内运行，并共享同一份 ~/.claude 配置。仓库在主机上，以绑定挂载的方式作为工作区进入容器。

把 Claude Code 加进你的 dev container

Claude Code 通过 Claude Code Dev Container Feature 安装到任何 dev container。这些设置适用于任何支持 Dev Containers 规范的工具，如 VS Code、GitHub Codespaces 或 JetBrains IDE，下面的步骤以 VS Code 为例。在 VS Code 或 Codespaces 里打开容器时，该 feature 还会添加 Claude Code 的 VS Code 扩展；其他编辑器忽略这一部分。

1. 创建或更新 devcontainer.json。 把下面的内容存为仓库里的 .devcontainer/devcontainer.json，或把 features 块加进你现有的文件。末尾的版本标签（如 :1.0）固定的是 feature 的安装脚本，而不是 Claude Code 的发布版本：feature 安装最新的 Claude Code，并且 Claude Code 默认在容器内自动更新自己。要固定 CLI 版本或禁用自动更新，见「强制组织策略」。

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

把 image 一行换成你项目的基础镜像，或者如果你现有的文件用 Dockerfile 就删掉它。基础镜像没提供 Node.js 时，Claude Code feature 会自己安装 Node.js；如果该安装失败、构建以 Failed to install Node.js and npm 停止，就在 features 块里 Claude Code feature 之上加入 "ghcr.io/devcontainers/features/node:1": {} 并重建。

2. 重建容器。 用 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows 和 Linux）打开 VS Code 命令面板，运行 Dev Containers: Rebuild Container。其他工具按各自的重建操作：见 GitHub Codespaces 里重建容器的说明、Dev Containers CLI 或你的 IDE 的 dev container 文档。

3. 登录 Claude Code。 在重建后的容器里打开终端运行 claude，按认证提示操作。

认证提示的内容取决于你的提供商：

• Anthropic：用你的 Claude 或 Anthropic Console 账号通过浏览器登录。
• Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry：Claude Code 使用你的云提供商凭据，没有浏览器提示。

对云提供商，要通过 containerEnv、Codespaces 密钥或你的云的工作负载身份，把凭据作为环境变量传入容器，而不是从主机挂载凭据文件。Claude Code 读取的凭据链见各提供商页面；要决定哪条路径适合你的组织，见管理员设置里的「选择你的 API 提供商」。

如果浏览器登录完成了但回调从未到达容器，复制浏览器里显示的代码，粘贴到终端里的 Paste code here if prompted 提示处。编辑器的端口转发没有路由 localhost 回调时可能发生这种情况。

跨重建持久化认证和设置

默认情况下，容器的主目录在重建时被丢弃，所以工程师每次都要重新登录。Claude Code 把认证令牌、用户设置和会话历史存在 ~/.claude 目录下；它把你的 OAuth 账号、个人 MCP 服务器和逐项目信任存在 ~/.claude.json，这是该目录之外的另一个文件，所以只在 ~/.claude 挂载卷并不能保持登录。要在 ~/.claude 挂载一个命名卷，并把 CLAUDE_CONFIG_DIR 设为同一路径，让 Claude Code 把 .claude.json 写进卷里。

下面的例子为 remoteUser 是 node 的容器挂载卷并设置 CLAUDE_CONFIG_DIR：

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

把 /home/node 换成你容器 remoteUser 的主目录。如果你已经设置了 containerEnv（例如在「强制组织策略」里），把 CLAUDE_CONFIG_DIR 加进那个对象，而不是再加第二个。

要按项目隔离状态，而不是让所有仓库共享一个卷，在源名里包含 ${devcontainerId} 变量；参考配置为此使用 source=claude-code-config-${devcontainerId}。

在 GitHub Codespaces 里，~/.claude 在你停止再启动 codespace 时保留，但在重建容器时被清空，所以上面的配置在那里同样适用。要让认证跨 codespace 延续，把 ANTHROPIC_API_KEY，或由 claude setup-token 生成的 CLAUDE_CODE_OAUTH_TOKEN，存为 Codespaces 密钥；Codespaces 自动把密钥作为环境变量暴露在容器内。

强制组织策略

dev container 是应用组织策略的便利位置，因为同一个镜像和配置在每位工程师的机器上运行。

Claude Code 在 Linux 上读取 /etc/claude-code/managed-settings.json，并以设置层级里最高的优先级应用它，所以那里的值会覆盖工程师在 ~/.claude 或项目 .claude/ 目录里设置的任何东西。在 Dockerfile 里把文件复制到位：

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

因为 Dockerfile 在仓库里，任何有写权限的人都能改变或删掉这一步。对工程师无法通过编辑仓库文件绕过的策略，改用服务端托管设置或你的 MDM 来交付托管设置；可用的键和其他交付途径见托管设置文件说明。

要设置对容器里每个 Claude Code 会话都生效的环境变量，把它们加进 devcontainer.json 的 containerEnv。下面的例子退出遥测和错误报告，并阻止 Claude Code 在安装后自动更新：

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

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 还会禁用 Remote Control 和其他需要功能标志获取的功能所依赖的功能标志评估，所以容器里的会话无法使用它们。

Dev Container Feature 总是安装最新的 Claude Code 发布版。要为可复现构建固定特定的 Claude Code 版本，改在 Dockerfile 里用 npm install -g @anthropic-ai/claude-code@X.Y.Z 安装，而不用 feature，并在 containerEnv 里把 DISABLE_AUTOUPDATER 设为 1。包括权限规则、工具限制和 MCP 服务器允许列表在内的完整策略控制，见「为你的组织设置 Claude Code」。

要让 MCP 服务器在容器内可用，在仓库根目录的 .mcp.json 里按项目范围定义它们，使其与你的 dev container 配置一起被检入。把本地 stdio 服务器依赖的任何二进制文件装进你的 Dockerfile，并把远程服务器域名加进网络允许列表。

限制网络出口

你可以把容器的出站流量限制到只有 Claude Code 需要的域名。推理和认证域名见「网络访问要求」，可选的遥测和错误报告连接及如何禁用它们见「遥测服务」。

参考容器包含一个 init-firewall.sh 脚本，把出站流量限制到脚本允许的目的地。在容器里运行防火墙需要额外权限，所以参考配置通过 runArgs 添加 NET_ADMIN 和 NET_RAW 能力。防火墙脚本和这些能力对 Claude Code 本身不是必需的：你可以省掉它们，转而依赖自己的网络控制。

无权限提示运行

因为容器以非 root 用户运行 Claude Code 并把命令执行限制在容器内，你可以传 --dangerously-skip-permissions 做无人值守运行。CLI 在以 root 启动时拒绝这个标志，所以要确认 remoteUser 设为非 root 账号。

跳过权限提示会去掉你在工具调用运行前评审它们的机会。Claude 仍然可以修改绑定挂载的工作区里的任何文件（它直接出现在你的主机上），并访问容器网络策略允许的任何东西。把这个标志与上面的网络出口限制配合使用，以限制被绕过的会话能到达什么。

如果你想要更少的提示又不禁用安全检查，考虑改用 auto 模式，它会在动作运行前由分类器评审。要完全阻止工程师使用 --dangerously-skip-permissions，在托管设置里把 permissions.disableBypassPermissionsMode 设为 "disable"。

试试参考容器

anthropics/claude-code 仓库包含一个示例 dev container，把 CLI、出口防火墙、持久卷和基于 Zsh 的 shell 结合在一起。它是作为可工作的示例提供的，而不是维护的基础镜像；在把这些部件应用到你自己的配置之前，用它看看它们如何配合。

1. 安装前提条件：安装 VS Code 和 Dev Containers 扩展。
2. 克隆参考：克隆 Claude Code 仓库并在 VS Code 里打开。
3. 在容器中重新打开：提示时点 Reopen in Container，或在命令面板里运行 Dev Containers: Reopen in Container。
4. 启动 Claude Code：容器构建完成后，用 Ctrl+` 打开终端并运行 claude 登录并开始你的第一个会话。

要把这个配置用于你自己的项目，把 .devcontainer/ 目录复制进你的仓库并按你的工具链调整 Dockerfile，或者回到「把 Claude Code 加进你的 dev container」，只把 feature 加到你已有的设置里。

参考配置由三个文件组成。你通过 feature 把 Claude Code 加进自己的 dev container 时，它们都不是必需的，但它们展示了组合这些部件的一种方式。

下一步

Claude Code 在 dev container 里运行之后，下面这些页面涵盖组织推广的其余部分：选择认证路径、在仓库之外交付托管策略、监控用量，以及理解 Claude Code 存储和发送什么。

• 为你的组织设置 Claude Code：选择认证提供商、决定策略如何到达设备并规划推广。
• 服务端托管设置：从 claude.ai 管理控制台交付托管策略，工程师无法通过编辑仓库文件绕过它。
• 监控用量与审计活动：导出 OpenTelemetry 指标并检查团队在运行什么。
• 网络访问要求：代理和防火墙的完整域名允许列表。
• 遥测服务与退出：Claude Code 默认发送什么，以及禁用它的环境变量。
• 探索 .claude 目录：卷挂载里有什么，包括凭据、设置和会话历史。
• 沙盒环境：把 dev container 与内置 Bash 沙盒、自定义容器和虚拟机做比较。
• 安全模型：Claude Code 的权限系统、沙盒和提示注入防护如何配合。
• 权限模式：从 plan 模式到 auto 模式再到 bypass 的完整范围，以及各自何时使用。