开发容器

在开发容器中运行 Claude Code，为整个团队提供一致、隔离的环境。

开发容器（也称 dev container）可用于定义一个完全相同且相互隔离的环境，团队中的每位工程师都能运行该环境。在容器中安装 Claude Code 后，Claude 运行的命令会在容器而不是主机上执行，同时，对项目文件的编辑会即时反映到本地仓库中。

本页先介绍如何在开发容器中安装 Claude Code，然后分别介绍几项可以独立使用的配置：在重建后保留身份验证、强制执行组织策略、限制网络出站流量，以及在不显示权限提示的情况下运行。请阅读与你的设置相关的部分。

开发容器如何与编辑器配合工作

开发容器以 Docker 容器形式运行，可以位于本机，也可以位于 GitHub Codespaces 等云主机上。支持 Dev Containers 规范的编辑器（例如 VS Code、GitHub Codespaces、JetBrains IDE 或 Cursor）会连接到该容器：你仍像往常一样在编辑器中浏览和编辑文件，但集成终端、语言服务器和构建工具都在容器内运行，而不是在主机上运行。普通 Vim 等不支持开发容器的编辑器不属于此工作流。

Claude Code 在容器内运行，因此看到的文件、依赖项和工具与项目工具链的其余部分相同。在 VS Code 中，既可以使用 Claude Code 扩展面板，也可以在集成终端中运行 claude；两者均在容器内运行，并共享同一份 ~/.claude 配置。

将 Claude Code 添加到开发容器

可以通过 Claude Code Dev Container Feature 将 Claude Code 安装到任意开发容器中。

这些设置适用于 VS Code、GitHub Codespaces、JetBrains IDE 等支持 Dev Containers 规范的工具。以下步骤以 VS Code 为例。

在 VS Code 或 Codespaces 中打开容器时，该 Feature 还会添加 Claude Code VS Code 扩展；其他编辑器会忽略这一部分。

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

身份验证提示中显示的内容取决于所用提供方：

• Anthropic：在浏览器中使用 Claude 或 Anthropic Console 账号登录
• Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry：Claude Code 使用云提供商凭据，不显示浏览器提示

对于云提供商，请通过 containerEnv、Codespaces secret 或云平台的 workload identity 将凭据传入容器，不要从主机挂载凭据文件。有关 Claude Code 读取的凭据链，请参阅 Amazon Bedrock、Google Cloud 的 Agent Platform或 Microsoft Foundry。

请参阅选择 API 提供方，确定哪种方式适合你的组织。

在重建后保留身份验证和设置

默认情况下，重建时会丢弃容器的主目录，因此工程师每次都必须重新登录。Claude Code 将身份验证 Token、用户设置和会话历史存储在 ~/.claude 下。请在该路径挂载 named volume，以便在重建后保留这些状态。

以下示例在 node 用户的主目录下挂载一个 volume：

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

将 /home/node 替换为容器 remoteUser 的主目录。如果 volume 挂载位置不是 ~/.claude，请将 CLAUDE_CONFIG_DIR 设为挂载路径，让 Claude Code 从中读写。

如果希望按项目隔离状态，而不是让所有仓库共用一个 volume，请在来源名称中加入 ${devcontainerId} 变量。参考配置使用 source=claude-code-config-${devcontainerId} 来实现此目的。

在 GitHub Codespaces 中，停止和启动 codespace 时会保留 ~/.claude，但重建容器时仍会将其清除，因此上述 volume 挂载同样适用。要在不同 codespace 之间保留身份验证，请将 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN（通过 claude setup-token 获得）存储为 Codespaces secret；Codespaces 会自动将 secret 作为容器内的环境变量提供。

强制执行组织策略

开发容器很适合应用组织策略，因为每位工程师的计算机上都会运行相同的镜像和配置。

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 下发托管设置。有关可用 key 和其他下发方式，请参阅托管设置文件。

要设置适用于容器内每个 Claude Code 会话的环境变量，请将它们添加到 containerEnv 中；该字段位于 devcontainer.json。以下示例会停用遥测和错误报告，并阻止 Claude Code 在安装后自动更新：

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

Dev Container Feature 始终安装最新版本的 Claude Code。要固定特定 Claude Code 版本以获得可复现构建，请从 Dockerfile 使用 npm install -g @anthropic-ai/claude-code@X.Y.Z 安装，而不是使用该 Feature，并按上例设置 DISABLE_AUTOUPDATER。

包含权限规则、工具限制和 MCP 服务器允许列表在内的完整策略控制，请参阅为组织设置 Claude Code。

要让 MCP 服务器能在容器内使用，请在仓库根目录的 .mcp.json 文件中以项目作用域定义这些服务器，使其与开发容器配置一起提交。请在 Dockerfile 中安装本地 stdio 服务器依赖的所有二进制文件，并将远程服务器域添加到网络允许列表。

限制网络出站流量

可以将容器的出站流量限制为仅访问 Claude Code 所需的域。推理和身份验证域请参阅网络访问要求；可选的遥测和错误报告连接及其禁用方法请参阅遥测服务。

参考容器包含一个 init-firewall.sh 脚本，用于阻止除 Claude Code 和开发工具所需域之外的所有出站流量。在容器内运行防火墙需要额外权限，因此参考配置添加了 NET_ADMIN 和 NET_RAW capability，并通过 runArgs 传入。Claude Code 本身不要求使用该防火墙脚本或这些 capability：可以省略它们，改用自己的网络控制措施。

在不显示权限提示的情况下运行

由于容器以非 root 用户身份运行 Claude Code，并将命令执行限制在容器中，因此可以传入 --dangerously-skip-permissions 进行无人值守操作。以 root 身份启动时，CLI 会拒绝此标志，因此请确认 remoteUser 设为非 root 账号。

跳过权限提示会使你失去在工具调用执行前进行检查的机会。Claude 仍可修改 bind-mounted 工作区中的任意文件，这些更改会直接出现在主机上；它也可以访问容器网络策略允许的任何目标。请将此标志与上文的网络出站限制配合使用，限制绕过权限的会话能够访问的内容。

如果希望减少提示而不禁用安全检查，可以考虑改用自动模式，由分类器在操作运行前进行检查。要彻底阻止工程师使用 --dangerously-skip-permissions，请在托管设置中将 permissions.disableBypassPermissionsMode 设为 "disable"。

试用参考容器

anthropics/claude-code 仓库包含一个示例开发容器，整合了 CLI、出站防火墙、持久卷和基于 Zsh 的 shell。它作为可运行示例提供，并非持续维护的基础镜像；请先用它了解各组件如何组合，再将其应用到自己的配置中。

要在自己的项目中使用此配置，请将 .devcontainer/ 目录复制到仓库中，并根据工具链调整 Dockerfile；也可以返回将 Claude Code 添加到开发容器，只将该 Feature 添加到已有设置中。

参考配置由三个文件组成。通过 Feature 将 Claude Code 添加到自己的开发容器时，并不要求使用其中任何文件；这些文件只展示一种组合各组件的方式。

后续步骤

Claude Code 在开发容器中运行后，以下页面介绍组织推广部署的其余工作：选择身份验证方式、从仓库外下发托管策略、监控用量，以及了解 Claude Code 存储和发送的内容。

• 为组织设置 Claude Code：选择身份验证提供方，确定策略如何到达设备，并规划推广部署
• 服务器托管设置：从 Claude.ai 管理控制台下发托管策略，使工程师无法通过编辑仓库文件绕过
• 监控用量和审计活动：导出 OpenTelemetry 指标并检查团队运行的内容
• 网络访问要求：代理和防火墙所需的完整域允许列表
• 遥测服务和停用方法：Claude Code 默认发送的内容，以及用于禁用这些流量的环境变量
• 了解 .claude 目录：volume 挂载保存的内容，包括凭据、设置和会话历史
• 沙箱环境：比较开发容器、内置 Bash 沙箱、自定义容器和 VM
• 安全模型：Claude Code 的权限系统、沙箱和 Prompt 注入防护如何协同工作
• 权限模式：从计划模式到自动模式再到绕过权限的完整范围，以及各模式的适用场景