配置云环境

​

Default 环境

• CLI 流程（例如 /web-setup）：为您创建 Default
• Pro 和 Max 上的网页引导：为您创建 Default
• Team 和 Enterprise 上的网页引导：显示 Create your first cloud environment 表单，除非所有者已启用快速设置；保持表单的默认值并点击 Create & finish 以获得相同的 Default 环境

• Trusted 网络访问：会话可以访问包注册表和其他允许列表中的域，但无法通过会话的网络访问其他任何内容。
• 无其他配置：Default 不定义任何环境变量或设置脚本，因此会话只以预安装的工具开始。

• 在网页、Desktop 应用和移动应用上，会话使用选择器中显示的环境。当您尚未选择时，所有者设置的组织默认值会填入选择。线程在项目中使用项目设置中设置的环境。
• 从 CLI，Claude Code 使用您的 /remote-env 选择，或在您的列表中有一个 Anthropic 托管环境时回退到该环境，否则回退到您列表中第一个不是桥接环境的环境，即 Remote Control 注册的条目，用于代表您自己的机器而不是云环境。对于自托管环境，在分派会话时使用其 ccpool_ ID 传递 --environment <environment-id> 会覆盖该调用的 /remote-env 选择和回退。Claude Code 拒绝传递给该标志的 Anthropic 托管 env_ ID，因此请使用 /remote-env 来定位这些。该标志需要 Claude Code v2.1.224 或更高版本。

​

配置您的环境

​

设置环境变量

NODE_ENV=development
LOG_LEVEL=debug
DATABASE_URL=postgres://localhost:5432/myapp

• VM 在空闲后被恢复：在几分钟没有活动后，会话的 VM 会暂停，其文件会被保存。您的下一条消息会恢复同一个 VM 并再次启动 Claude Code。
• VM 被回收并被重建：如果暂停的 VM 已经被回收，重新打开会话会配置一个新的 VM。

​

添加网络机密

​

要求

• Role：在 Pro、Max 和 Team 计划上，无论您的角色如何，您都可以在自己的环境中添加和删除机密。在 Team 和 Enterprise 上，所有者在您的 claude.ai 组织中持有组织管理员角色，管理员（Admin）不持有，这会改变您在以下情况下看到的内容：
  • Enterprise 上您自己的环境：拥有组织管理员角色时，您可以添加和删除机密。没有该角色时，Network secrets 部分会在说明”Only an organization admin can add or delete network secrets”下列出机密，且没有 Add secret 或删除按钮。请让所有者将机密添加到共享环境，然后在该环境中运行您的会话
  • 共享环境：所有者从管理设置中添加和删除其机密。没有组织管理员角色时，请让所有者添加机密，因为该环境的对话框中没有 Network secrets 部分
  • Team 上您自己的环境：没有组织管理员角色时，Add secret 会打开一个只接受一个主机的简化表单
• Environment type：一个已存在的 Anthropic 托管云环境。自托管环境没有网络机密
• API reachability：API 接受来自互联网的连接，因为请求从 Anthropic 的网络发出
• Encryption keys：如果您的组织使用客户管理的加密密钥，则无法保存网络机密

​

添加机密

​

在没有组织管理员角色的 Team 计划上添加机密

• Host：获得该机密的唯一主机，例如 api.example.com。该表单不接受 *. 通配符
• Name：机密的可选标签
• Secret type：对于在请求头中传输的密钥选择 Token，或选择 Username and password。对于令牌，请将密钥粘贴为 Value

​

哪些请求会获得机密

​

永远不会获得机密的请求

• GitHub：GitHub 代理会代为对发往 GitHub 的请求进行身份验证，因此您无需为其设置网络机密
• Anthropic API 和公共包注册表：api.anthropic.com、registry.npmjs.org、jsr.io、npm.jsr.io、pypi.org、files.pythonhosted.org、index.crates.io 和 proxy.golang.org
• 设置脚本请求：Claude Code 在启动时才连接到 Agent 代理，此时设置脚本已经运行完毕
• Claude Code 的遥测导出：Claude Code 自行发送其遥测导出，而不是通过它运行的命令发送，该请求不会经过 Agent 代理

​

从 CLI 选择环境

​

归档环境

• 已经在环境中运行的会话会继续工作。
• 环境会从选择器和 /remote-env 中消失，因此您无法为新会话选择它。
• 环境中的网络机密在其正在运行的会话中仍保持附加状态。请在归档前删除不再需要的机密。
• 在任何使用入口上都无法在已归档的环境中启动新会话。如果该环境是您保存的 CLI 默认值，当您的列表中有 Anthropic 托管的环境时，Claude Code 会在该环境中启动 CLI 云端会话，否则会在列表中第一个不是 Remote Control bridge 环境的环境中启动。任何显式配置了该环境的内容，例如 Routine，都无法在其中启动新会话。请将其指向另一个环境。

​

组织共享环境

• 创建共享环境：使用管理设置中的 Cloud environments 页面，所有者也在该页面编辑和归档共享环境。每个共享环境都有一个名称、一个网络访问级别、.env 格式的环境变量和一个设置脚本。
• 共享个人环境：在环境选择器中打开您自己的某个环境进行编辑，然后从 Who can use it 行共享它。环境会保留其 ID，因此已经使用它的会话和 Routine 不受影响，每个成员随后都可以看到它并在其中启动会话。

​

设置 Claude Tag 频道使用的环境

• 在 claude.ai/admin-settings/claude-code 将共享环境或自托管环境设置为组织的默认环境。
• 在 Claude Tag 管理设置中将某个环境固定到频道。

​

网络访问

​

访问级别

• GitHub，通过其单独的代理
• 您启用的 MCP 连接器，其流量通过 Anthropic 的服务器传输
• 您在环境的网络密钥上列出的主机，除了永远不会获得该密钥的主机
• Anthropic API，用于 Claude Code 自己的请求，即使在 None 下也是如此，如安全性和隔离下所述

​

允许特定域

api.example.com
*.internal.example.com
registry.example.com

• 此环境中的会话打开另一个组织的公开 Artifact：Claude Code 直接从主机获取这些 Artifact，因此将其添加到此列表。
• 您正在配置本地 CLI 或自托管运行器：在该允许列表中保留主机。请参阅网络访问要求和自托管网络要求。

​

GitHub 代理

• Git 凭据：VM 内的 git 客户端使用范围受限的凭据，代理验证并将其交换为您的实际 GitHub 令牌。
• API 请求：来自内置 GitHub 工具的请求，以及来自 proxy-injected 占位符下的 gh 的请求，会在替换为您的真实凭据后发出。
• 推送限制：代理会拒绝分支删除，以及推送分支以外的任何内容（例如标签）。它不限制推送可以更新哪些分支。如需限制，请在 GitHub 上使用分支保护规则或规则集。
• 仓库范围：代理为附加到会话的仓库处理 GitHub API 请求。针对其他仓库的 API 请求会收到 403，其消息以 GitHub access to 开头并包含 is not enabled for this session。当仓库未附加时，您通过 github.com/{owner}/{repo}/archive/ 或 codeload.github.com URL 获取的源代码归档也会收到相同的 403，即使是公开仓库也是如此。
• GraphQL 限制：代理会拒绝发往 GitHub GraphQL 端点的请求，返回 403，其消息以 GitHub GraphQL is not available from Claude Code sessions 开头，并指明 REST 回退方式 gh api repos/{owner}/{repo}/...。使用 GraphQL 的 gh 子命令（例如 gh pr 和 gh issue）也会收到相同的 403。无论您提供的凭据如何，限制都适用于通过代理的每个请求，因此您设置的 GH_TOKEN 会收到相同的 403。Claude 无法通过代理访问仅存在于 GraphQL 中的 GitHub API，例如 Projects v2。

​

安全代理

• 防范恶意请求
• 速率限制和滥用防范

​

云端会话中可用的内容

​

您的设置中会保留的内容

​

添加个人偏好而无需提交到仓库

#!/bin/bash
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md <<'EOF'
Use conventional commit messages.
EOF

​

已安装的工具

​

使用 GitHub 问题和 Pull Request

• 如果您设置了令牌，它会原封不动地传递到容器中，因此您的脚本和 GitHub 的 gh CLI 会直接使用它。
• 如果您都不设置，且由 GitHub 代理为您的会话处理身份验证，这两个变量在 Claude 运行的命令中读取为占位符字符串 proxy-injected，代理在出站 GitHub 请求上替换为您的真实凭据。针对已附加仓库的 gh api 调用无需您自己的令牌即可工作，但直接读取 GITHUB_TOKEN 的脚本会得到占位符，而不是可用的令牌。

​

将输出链接回会话

echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

​

运行测试、启动服务和添加包

​

运行测试

​

启动服务

service postgresql start

service redis-server start

​

添加包

​

资源限制

• 4 vCPU
• 16 GB RAM
• 30 GB 磁盘

​

时间限制

• Claude 运行的命令：云环境不设置自己的命令超时时间，因此 Bash 工具的默认值适用。Claude 默认为前台命令等待 2 分钟，最多可以要求 10 分钟。 当命令达到其超时时，Claude Code 将其移到后台，而不是停止它，除非命令以 sleep 开头。以这种方式移动的命令可以继续运行最多 30 分钟，然后 Claude Code 在其后台时间限制处停止它。将 BASH_DEFAULT_TIMEOUT_MS 设置为 1800000 毫秒以上会延长该限制以及前台默认值。
• SessionStart hook：Claude Code 在 600 秒后取消 command hook，除非您在 hook 条目上设置 timeout（以秒为单位）。Claude Code 不会对您使用 async: true 运行的 hook 强制执行超时。
• 设置脚本：花费超过大约五分钟的脚本不会被缓存。脚本要求涵盖如何保持在该时间以下。
• 空闲会话：在几分钟没有活动后，会话的 VM 会暂停并保存其文件，暂停的 VM 之后可能会被回收。设置环境变量描述会话在每种情况下会获取什么，环境已过期涵盖如何重新打开 VM 被回收的会话。

​

设置脚本

#!/bin/bash
apt update && apt install -y shellcheck

​

脚本要求

• 以零退出：如果脚本以非零状态结束，会话将无法启动。在非关键命令后附加 || true，以便间歇性安装失败不会阻止会话。
• 在五分钟内完成：将脚本的总运行时间保持在大约五分钟以内，以便环境缓存可以建立。当设置耗时超过五分钟时，环境不会被缓存。使用 & 和 wait 并行运行独立的安装，并将任何无法容纳的单个下载移至 SessionStart hook，在后台启动它。如果新会话在设置期间停滞或失败，请参阅新会话在设置期间挂起或超时。
• 安装需要网络访问：包安装需要连接到注册表。默认的 Trusted 级别涵盖常见包注册表，包括 npm、PyPI、RubyGems 和 crates.io；使用 None 网络访问时，安装会失败。

​

环境缓存

​

设置脚本与 SessionStart hooks

• Anthropic 托管环境：Claude Code 运行来自存储库和您组织的服务器管理的设置的 hooks。Claude Tag 会话不会接收服务器管理的设置，因此来自服务器管理的设置的 hooks 不会在那里运行。
• 自托管环境：Claude Code 还运行运行程序主机的 ~/.claude/ 中的运行程序操作员播种的 hooks，以及运行程序镜像的托管设置文件中的 hooks，当该文件是 Claude Code 应用的托管源之一时。

​

使用 SessionStart hook 安装依赖项

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash

if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi

cd "$CLAUDE_PROJECT_DIR" || exit 1
hashes=node_modules/.install_pkgs.sha256

if ! sha256sum --check --status "$hashes" 2>/dev/null; then
  # Delete the old hashes first, so a failed install runs again next time
  rm -f "$hashes"
  if npm install; then
    sha256sum scripts/install_pkgs.sh package.json package-lock.json > "$hashes" || rm -f "$hashes"
  fi
fi

# pip skips requirements that are already satisfied
pip install -r requirements.txt
exit 0

​

云会话中的限制

• 每个会话一个仓库：在 Anthropic 托管环境中，具有多个仓库的会话不会从任何仓库的 .claude/settings.json 加载 hook，因此您在那里定义的 SessionStart hook 不会运行。请改为使用设置脚本为这些会话安装依赖项。对于自托管环境，请参阅适用哪个仓库的设置。
• 没有仅云端的范围：hooks 在本地和云会话中都运行。要跳过本地运行，请在 CLAUDE_CODE_REMOTE 环境变量不为 true 时提前退出，就像依赖项安装脚本所做的那样。
• 需要网络访问：安装命令需要连接到包注册表。如果您的环境使用 None 网络访问，这些 hooks 会失败。Trusted 下的默认允许列表涵盖 npm、PyPI、RubyGems 和 crates.io。
• 代理兼容性：在 Anthropic 托管环境中，所有出站流量都经过安全代理，某些包管理器无法与此代理正确配合工作；Bun 是一个已知的例子。在自托管环境中，出站流量改为经过您自己的网络边界。
• 增加启动延迟：hook 在每次会话启动或恢复时运行，不同于受益于环境缓存的设置脚本。请通过跳过已完成的工作来保持安装脚本快速，就像依赖项安装脚本所做的那样。

​

默认允许的域

​

相关资源

• Cloud sessions reference：启动、管理和共享云会话
• Cloud sessions quickstart：连接 GitHub 并启动您的第一个云会话
• Claude Tag：Claude 从 Slack 启动的会话在相同的环境中运行
• Routines：计划运行使用相同的环境和网络访问级别
• Remote Control：改为在您自己的机器的网络和文件上运行会话
• Self-hosted environments：在您的组织自己的基础设施上运行云会话
• SessionStart hooks：存储库提交的设置，在本地和云会话中运行
• Server-managed settings：从管理控制台交付的组织策略