{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 开发容器

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

[开发容器](https://containers.dev/)（dev container）让您定义一个相同的、隔离的环境，团队中的每个工程师都可以运行。在该容器中安装 Claude Code 后，Claude 运行的命令在容器内执行而不是在宿主机上，同时对项目文件的编辑会在您工作时出现在本地仓库中。

本页面涵盖[在开发容器中安装 Claude Code](#add-claude-code-to-your-dev-container) 以及后续的配置主题。每个主题都是独立的，因此请跳转到与您需要设置的内容匹配的主题：

* [跨重建持久化身份验证和设置](#persist-authentication-and-settings-across-rebuilds)
* [强制执行组织策略](#enforce-organization-policy)
* [限制网络出口](#restrict-network-egress)
* [无需权限提示运行](#run-without-permission-prompts)

<Warning>
  虽然开发容器提供了实质性保护，但没有任何系统能完全免疫所有攻击。
  使用 `--dangerously-skip-permissions` 执行时，开发容器不能阻止恶意项目渗出容器内可访问的任何内容，包括存储在 [`~/.claude`](/en/claude-directory) 中的 Claude Code 凭据。
  仅在使用受信任仓库进行开发时使用开发容器，并监视 Claude 的活动。
  避免将宿主机密钥（如 `~/.ssh` 或云凭据文件）挂载到容器中；优先使用仓库范围的或短期令牌。
</Warning>

<Accordion title="开发容器如何与您的编辑器配合工作">
  <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="图表显示宿主机上的编辑器连接到 Docker 开发容器。Claude Code、终端和构建工具在容器内运行。宿主仓库被绑定挂载到容器中作为工作区。" width="640" height="300" data-path="images/devcontainer-architecture.svg" />

  <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=ef00c8e25b1ea7a3a152895f1488831b" className="hidden dark:block" alt="图表显示宿主机上的编辑器连接到 Docker 开发容器。Claude Code、终端和构建工具在容器内运行。宿主仓库被绑定挂载到容器中作为工作区。" width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />

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

  Claude Code 在容器内运行，因此它看到与项目工具链其余部分相同的文件、依赖项和工具。在 VS Code 中，您可以使用 [Claude Code 扩展面板](/en/vs-code)或在集成终端中运行 `claude`；两者都在容器内运行并共享相同的 `~/.claude` 配置。
</Accordion>

## 将 Claude Code 添加到您的开发容器

Claude Code 通过 [Claude Code Dev Container Feature](https://github.com/anthropics/devcontainer-features/tree/main/src/claude-code) 安装到任何开发容器中。

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

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

<Tip>
  开发容器新手？[VS Code Dev Containers 教程](https://code.visualstudio.com/docs/devcontainers/tutorial)引导您安装 Docker、扩展并打开第一个容器。有关带防火墙和持久卷的更完整加固示例，请参阅[尝试参考容器](#try-the-reference-container)。
</Tip>

<Steps>
  <Step title="创建或更新 devcontainer.json">
    将以下内容保存为仓库中的 `.devcontainer/devcontainer.json`，或将 `features` 块添加到现有文件中。

    末尾的版本标签（如 `:1.0`）固定的是功能的安装脚本，而不是 Claude Code 版本。该功能安装最新的 Claude Code，Claude Code 默认在容器内自动更新。

    要固定 CLI 版本或禁用自动更新，请参阅[强制执行组织策略](#enforce-organization-policy)。

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

    将 `image` 行替换为您的项目基础镜像，或者如果现有文件使用 Dockerfile 则删除它。
  </Step>

  <Step title="重建容器">
    在 Mac 上使用 `Cmd+Shift+P` 或在 Windows 和 Linux 上使用 `Ctrl+Shift+P` 打开 VS Code 命令面板，然后运行 **Dev Containers: Rebuild Container**。

    对于其他工具，请遵循该工具的重建操作：请参阅 [GitHub Codespaces 中的重建](https://docs.github.com/en/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace)、[Dev Containers CLI](https://github.com/devcontainers/cli) 或您的 IDE 的开发容器文档。
  </Step>

  <Step title="登录 Claude Code">
    在重建的容器中打开终端并运行 `claude`，然后按照身份验证提示操作。
  </Step>
</Steps>

您在身份验证提示中看到的内容取决于您的提供程序：

* **Anthropic**：通过浏览器使用您的 Claude 或 Anthropic Console 帐户登录
* **[Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry](/en/third-party-integrations)**：Claude Code 使用您的云提供程序凭据，没有浏览器提示

对于云提供程序，通过 `containerEnv`、Codespaces secret 或您的云工作负载身份将凭据作为环境变量传递到容器中，而不是从宿主机挂载凭据文件。有关 Claude Code 读取的凭据链，请参阅 [Amazon Bedrock](/en/amazon-bedrock)、[Google Vertex AI](/en/google-vertex-ai) 或 [Microsoft Foundry](/en/microsoft-foundry)。

请参阅[选择您的 API 提供程序](/en/admin-setup#choose-your-api-provider)以决定哪种路径适合您的组织。

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

## 跨重建持久化身份验证和设置

默认情况下，容器的主目录在重建时被丢弃，因此工程师每次都必须重新登录。Claude Code 将其身份验证令牌、用户设置和会话历史存储在 [`~/.claude`](/en/claude-directory) 下。在该路径挂载命名卷以在重建之间保持此状态。

以下示例在 `node` 用户的主目录挂载卷：

```json devcontainer.json theme={null}
"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
]
```

将 `/home/node` 替换为容器的 `remoteUser` 的主目录。如果您将卷挂载到 `~/.claude` 以外的位置，请将 [`CLAUDE_CONFIG_DIR`](/en/env-vars) 设置为挂载路径，以便 Claude Code 在该处读取和写入。

要按项目隔离状态而不是跨所有仓库共享一个卷，请在源名称中包含 `${devcontainerId}` 变量。[参考配置](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json)使用 `source=claude-code-config-${devcontainerId}` 实现此目的。

在 GitHub Codespaces 中，`~/.claude` 在停止和启动 codespace 之间持久存在，但在重建容器时仍会被清除，因此上面的卷挂载也适用于此。要在 codespace 之间携带身份验证，将 `ANTHROPIC_API_KEY` 或来自 [`claude setup-token`](/en/authentication#generate-a-long-lived-token) 的 `CLAUDE_CODE_OAUTH_TOKEN` 存储为 [Codespaces secret](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces)；Codespaces 自动使 secrets 作为环境变量在容器内可用。

## 强制执行组织策略

开发容器是应用组织策略的便利场所，因为相同的镜像和配置在每个工程师的机器上运行。

Claude Code 在 Linux 上读取 `/etc/claude-code/managed-settings.json` 并在[设置层次结构](/en/settings#how-scopes-interact)中以最高优先级应用它，因此那里的值覆盖工程师在 `~/.claude` 或项目的 `.claude/` 目录中设置的任何内容。从 Dockerfile 将文件复制到位：

```dockerfile Dockerfile theme={null}
RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json
```

由于 Dockerfile 位于仓库中，任何具有写访问权限的人都可以更改或删除此步骤。对于工程师无法通过编辑仓库文件绕过的策略，请通过[服务器托管设置](/en/server-managed-settings)或您的 MDM 下发托管设置。有关可用键和其他下发路径，请参阅[托管设置文件](/en/settings#settings-files)。

要设置适用于容器中每个 Claude Code 会话的[环境变量](/en/env-vars)，请将它们添加到 `devcontainer.json` 中的 `containerEnv`。以下示例选择退出遥测和错误报告，并防止 Claude Code 在安装后自动更新：

```json devcontainer.json theme={null}
"containerEnv": {
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
  "DISABLE_AUTOUPDATER": "1"
}
```

Dev Container Feature 始终安装最新的 Claude Code 版本。要为可重现的构建固定特定的 Claude Code 版本，请使用 `npm install -g @anthropic-ai/claude-code@X.Y.Z` 从 Dockerfile 安装它，而不是使用该功能，并如上所示设置 `DISABLE_AUTOUPDATER`。

有关策略控制的完整列表（包括权限规则、工具限制和 MCP 服务器允许列表），请参阅[为您的组织设置 Claude Code](/en/admin-setup)。

要使 [MCP 服务器](/en/mcp)在容器内可用，请在仓库根目录的 `.mcp.json` 文件中在[项目作用域](/en/mcp#mcp-installation-scopes)定义它们，以便它们与您的开发容器配置一起签入。在 Dockerfile 中安装本地 stdio 服务器依赖的任何二进制文件，并将远程服务器域名添加到您的网络允许列表。

## 限制网络出口

您可以将容器的出站流量限制为仅 Claude Code 需要的域名。有关推理和身份验证域名，请参阅[网络访问要求](/en/network-config#network-access-requirements)，有关可选的遥测和错误报告连接以及如何禁用它们，请参阅[遥测服务](/en/data-usage#telemetry-services)。

参考容器包含一个 [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) 脚本，阻止除 Claude Code 和您的开发工具需要的域名之外的所有出站流量。在容器内运行防火墙需要额外权限，因此参考通过 `runArgs` 添加 `NET_ADMIN` 和 `NET_RAW` 功能。防火墙脚本和这些功能对于 Claude Code 本身不是必需的：您可以省略它们并依靠您自己的网络控制。

## 无需权限提示运行

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

跳过权限提示会移除您在工具调用运行之前审查它们的机会。Claude 仍然可以修改绑定挂载工作区中的任何文件（这直接出现在您的宿主机上），并访问容器网络策略允许的任何内容。将此标志与上面的[网络出口限制](#restrict-network-egress)配对，以限制被绕过的会话可以访问的内容。

如果您想要更少的提示而不禁用安全检查，请考虑[自动模式](/en/permission-modes#eliminate-prompts-with-auto-mode)，它有一个分类器在操作运行之前审查它们。要完全阻止工程师使用 `--dangerously-skip-permissions`，请在[托管设置](/en/settings#permission-settings)中将 `permissions.disableBypassPermissionsMode` 设置为 `"disable"`。

## 尝试参考容器

[`anthropics/claude-code`](https://github.com/anthropics/claude-code/tree/main/.devcontainer) 仓库包含一个示例开发容器，组合了 CLI、出口防火墙、持久卷和基于 Zsh 的 shell。它作为工作示例提供，而不是维护的基础镜像；使用它来查看各部分如何组合在一起，然后再应用到您自己的配置中。

<Steps>
  <Step title="安装前提条件">
    安装 VS Code 和 [Dev Containers 扩展](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)。
  </Step>

  <Step title="克隆参考">
    克隆 [Claude Code 仓库](https://github.com/anthropics/claude-code)并在 VS Code 中打开它。
  </Step>

  <Step title="在容器中重新打开">
    出现提示时，点击 **Reopen in Container**，或从命令面板运行 **Dev Containers: Reopen in Container**。
  </Step>

  <Step title="启动 Claude Code">
    容器构建完成后，使用 `` Ctrl+` `` 打开终端并运行 `claude` 以登录并开始您的第一个会话。
  </Step>
</Steps>

要将此配置用于您自己的项目，请将 `.devcontainer/` 目录复制到您的仓库中并为您的工具链调整 Dockerfile，或者返回[将 Claude Code 添加到您的开发容器](#add-claude-code-to-your-dev-container)仅将该功能添加到您已有的设置中。

参考配置由三个文件组成。当您通过该功能将 Claude Code 添加到自己的开发容器时，它们都不是必需的，但它们展示了一种组合各部分的方式。

| 文件                                                                                                       | 用途                                                                       |
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [`devcontainer.json`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json) | 卷挂载、`runArgs` 功能、VS Code 扩展和 `containerEnv` |
| [`Dockerfile`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile)               | 基础镜像、开发工具和 Claude Code 安装                    |
| [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh)   | 阻止除允许域名之外的所有出站网络流量                |

## 后续步骤

一旦 Claude Code 在您的开发容器中运行，以下页面涵盖了组织推出的其余部分：选择身份验证路径、在仓库外下发托管策略、监控使用情况以及了解 Claude Code 存储和发送的内容。

* [为您的组织设置 Claude Code](/en/admin-setup)：选择身份验证提供程序、决定策略如何到达设备并规划推出
* [服务器托管设置](/en/server-managed-settings)：从 Claude.ai 管理控制台下发托管策略，使工程师无法通过编辑仓库文件绕过
* [监控使用情况和审计活动](/en/monitoring-usage)：导出 OpenTelemetry 指标并审查您的团队正在运行的内容
* [网络访问要求](/en/network-config#network-access-requirements)：代理和防火墙的完整域名允许列表
* [遥测服务和选择退出](/en/data-usage#telemetry-services)：Claude Code 默认发送什么以及禁用它的环境变量
* [探索 `.claude` 目录](/en/claude-directory)：卷挂载包含什么，包括凭据、设置和会话历史
* [沙箱环境](/en/sandbox-environments)：将开发容器与内置 Bash 沙箱、自定义容器和 VM 进行比较
* [安全模型](/en/security)：Claude Code 的权限系统、沙箱和提示注入保护如何协同工作
* [权限模式](/en/permission-modes)：从计划模式到自动模式再到绕过的完整范围，以及何时使用每种