配置云环境

为 Claude Code 云会话配置云环境：网络访问级别、环境变量、设置脚本和环境缓存。

每个云会话都在云环境中运行。您可以配置环境以允许或拒绝网络访问、为会话设置环境变量、在 Pro 和 Max 计划上存储会话使用的API 凭证而不会看到它们，以及在 Claude 开始工作前运行设置脚本。

相同的环境适用于您启动云会话的任何地方：Desktop 应用、Claude 移动应用、浏览器中的 claude.ai/code、终端中搭配 claude --cloud、例程和 Claude Tag。这些界面中的每一个也可以路由到自托管环境。可用性和限制涵盖了当 Claude Tag 会话在其中运行时 Claude 还不能使用的内容。

Default 环境

如果您还没有环境，引导设置会为您设置 Default 环境。具体方式取决于您在哪里进行引导：

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

Default 本身不带有任何配置：

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

只有 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 或更高版本。

当默认环境不够用时，请配置环境：当 Claude 需要访问默认允许列表之外的域、需要为其会话设置环境变量，或需要在开始工作前安装依赖项时。

配置你的环境

在环境选择器中创建、编辑和归档环境，你可以在网页快速入门后从claude.ai/code访问它，或从桌面应用的提示框中访问。你创建的环境是你账户的个人环境；由所有者创建的共享环境会出现在同一个选择器中。查看已安装的工具了解无需任何配置即可使用的工具。

1

打开环境选择器

在claude.ai/code上，选择显示当前环境名称的云图标，它位于消息框上方的行中。选择器没有设置页面或直接URL。

2

添加或编辑环境

选择Add cloud environment，或悬停在现有环境上并选择右侧出现的设置图标。对话框包括名称、网络访问级别、环境变量和设置脚本。当你在Pro或Max计划上编辑现有的云环境时，对话框还包括API凭证。

设置环境变量

环境变量使用.env格式，每行一个KEY=value对。普通值不需要引号，如果你用匹配的一对引号引用一个值，引号不会成为该值的一部分。引用跨越多行或包含#的值：在未引用的值中，#开始注释，该行的其余部分被丢弃。

以下示例定义了三个变量。

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

每个会话在启动时将环境的值复制一次到普通环境变量中，Claude运行的任何命令都可以读取这些变量。因为运行中的会话不会重新读取配置，编辑或添加变量会影响你之后启动的会话；已经运行的会话保持它们启动时的值。

云会话在启动时也会自己设置一些变量。对于CLAUDE_AUTOCOMPACT_PCT_OVERRIDE，会话设置的值会覆盖你在这里添加的值，所以在这里添加该键没有效果。

使用该环境的任何人都可以读取这些值。在Pro和Max计划上，对于代理可以附加到请求的键，请改用API凭证。从不获得凭证的请求在那里列出。

添加API凭证

API凭证是你存储在云环境上的API密钥或令牌，这样Claude可以从环境中的任何会话调用该API，而无需看到密钥。Anthropic的代理在每个请求离开会话的VM后，将密钥添加到你列出的主机的请求中。密钥永远不会到达Claude、它运行的命令或会话的环境变量。

API凭证在Pro和Max计划上可用。它们在Team和Enterprise计划上还不可用，所以API credentials部分不会出现在这些计划的环境对话框中。

要求

其中两个决定你是否可以添加凭证，两个决定代理在添加后是否可以使用它：

• Role：你的claude.ai组织中的组织管理员角色
  • 在Team和Enterprise上，所有者持有它，管理员没有
  • 在Pro和Max上，你在自己的组织中持有它
  • 没有它，你会看到一个注释而不是凭证列表，即使在你自己的环境上也是如此。请求所有者将凭证添加到共享环境并在那里运行你的会话
• Environment type：一个已经存在的Anthropic托管的云环境。自托管环境没有API凭证
• API reachability：API接受来自互联网的连接，因为请求来自Anthropic的网络
• Encryption keys：如果你的组织使用客户管理的加密密钥，你无法保存凭证

添加凭证

你从已经存在的环境的编辑器一次添加一个凭证。新环境的对话框不提供它们。也没有编辑。要更改凭证的主机或值，请删除它并再次添加。

要确认凭证有效，请在环境中启动会话并要求Claude调用API，例如使用curl。API的响应就像密钥在请求中一样，密钥不会出现在会话的环境变量或任何文件中。如果列表将凭证标记为Not sent，其下方的注释会说明原因和解决方法。两个主机重叠但不完全匹配的凭证不会获得标记，代理只会发送其中一个。

哪些请求获得凭证

当请求的主机与你在该凭证上列出的主机匹配时，代理会将凭证附加到请求。会话可以到达这些主机，即使环境的网络访问级别不允许，除了从不获得凭证的主机。凭证适用于在环境中运行的每个会话，无论谁启动它，直到你删除它。

从不获得凭证的请求

代理永远不会将你添加的凭证附加到这些请求：

• GitHub：GitHub代理改为对GitHub的请求进行身份验证，所以你不需要为它提供API凭证
• Anthropic API和公共包注册表：api.anthropic.com、registry.npmjs.org、jsr.io、npm.jsr.io、pypi.org、files.pythonhosted.org、index.crates.io和proxy.golang.org
• Setup script请求：Claude Code在启动时连接到代理，在setup script运行后

从CLI选择环境

在你的终端中运行/remote-env来为你从CLI创建的云会话（例如claude --cloud）选择默认环境。该命令打开你现有环境的选择器并将你的选择保存到你的用户设置中的remote.defaultEnvironmentId键，所以它适用于你机器上的每个项目，直到你更改它，除非在更高优先级的设置层（例如仓库的项目设置）上设置了相同的键。

自托管环境ID的形式为ccpool_...，遵循更严格的源规则。查看remote.defaultEnvironmentId了解Claude Code遵守它的设置层。

/remote-env仅设置默认值：它不启动会话，也不能添加或编辑环境。从环境选择器管理它们。

归档环境

要归档你自己的环境之一，请打开它进行编辑并选择Archive。所有者从管理设置中的Cloud environments页面归档共享环境。你不能删除环境，只能归档它。

归档影响新会话，不影响运行中的会话：

• 已经在环境中运行的会话继续工作。
• 环境从选择器和/remote-env中消失，所以你无法为新会话选择它。
• 环境上的API凭证在其运行的会话中保持附加。删除你不再需要的任何凭证，然后再归档。
• 没有新会话可以在任何表面上的归档环境中启动。如果该环境是你保存的CLI默认值，当你的列表有一个时，Claude Code会在Anthropic托管的环境中启动CLI云会话，否则在你列表中不是Remote Control bridge环境的第一个环境中启动。任何显式配置了该环境的东西，例如routine，无法在其中启动新会话。将其指向另一个环境。

组织共享环境

在Team和Enterprise计划上，所有者可以创建与组织的每个成员共享的云环境。同一角色管理Cloud environments管理页面上的其他所有内容，包括自托管环境；管理员角色无法打开该页面。可以打开它的完整角色列表是管理服务器管理的设置的角色列表。

共享环境出现在每个成员的环境选择器中，在Organization标题下，位于成员自己的环境之后（在Personal下），所以团队可以标准化一个配置，而不是每个成员重新创建它。在那里选择共享环境的设置图标会为每个成员（包括所有者）打开其配置的只读摘要。

所有者通过以下两种方式之一使环境对组织可用：

• 创建共享环境：使用admin settings中的Cloud environments页面，这也是所有者编辑和归档共享环境的地方。每个都有一个名称、一个网络访问级别、.env格式的环境变量和一个setup script。
• 共享个人环境：在环境选择器中打开你自己的环境之一进行编辑，然后从Who can use it行共享它。环境保持其ID，所以已经使用它的会话和routine不受影响，每个成员都可以看到它并在其中启动会话。

所有者在claude.ai/admin-settings/claude-code单独选择组织的默认环境。

每个成员在共享环境中的会话都读取其变量，所以不要在其中包含秘密。API凭证给予会话一个它们无法读取的密钥，在Team或Enterprise计划上还不可用。

设置Claude Tag频道使用的环境

在Claude Tag频道中，Claude作为你组织的共享身份工作，而不是任何成员，所以频道会话仅使用组织级别的环境，要么是共享环境，要么是自托管环境。要给频道一个不是预安装的工具链，例如.NET，所有者可以从Cloud environments管理页面创建一个共享环境，带有一个setup script来安装它。通过以下两种方式之一将频道指向一个环境：

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

网络访问

每个环境都设置一个网络访问级别，控制其会话可以进行的出站连接。默认级别 Trusted 允许包注册表和其他允许列表中的域；Custom 采用您自己的域列表。

要更改环境的网络访问，打开它进行编辑并在对话框中使用 Network access 选择器。共享环境在那里以只读方式打开，因此 Owner 改为从管理设置中的 Cloud environments 页面更改其网络访问。打开选择器的云图标出现在Default 环境下列出的应用界面上，以及例程编辑器中；个人环境在您的 claude.ai 账户设置中没有单独的页面。

访问级别

Network access 字段在环境对话框中采用以下四个级别之一：

无论您选择哪个级别，会话仍然可以访问这些，因为每一个都采用不经过会话的网络允许列表的路径：

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

允许特定域

要允许不在 Trusted 列表中的域，请在环境的网络访问设置中选择 Custom，然后在 Allowed domains 字段中每行列出一个域。此示例允许内部项目可能需要的三个主机。

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

此环境中的会话现在可以访问 api.example.com、internal.example.com 的任何子域和 registry.example.com，但无法通过会话的网络访问其他域。GitHub 流量、MCP 连接器流量和对环境 API 凭证的主机的请求（除了代理跳过的主机）不经过此允许列表。前导 *. 匹配每个子域。要同时保留 Trusted 域，请勾选 Also include default list of common package managers；不勾选则只允许您列出的内容。

如果您的组织使用工件，会话读取工件时不需要在列表中包含 *.frame.claudeusercontent.com。当列表中没有该主机时，Claude Code 通过会话与 Anthropic 的连接读取工件内容。在两种情况下保留允许列表中的主机：

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

每个环境都有自己的允许域列表；没有组织级别的允许列表可供管理员推送到每个成员的环境。服务器管理的设置在云会话内仍然适用，但其中没有任何设置会将域添加到环境的网络允许列表。要为团队提供一个标准列表，Owner 可以创建一个具有 Custom 网络访问和该列表的组织共享环境。

GitHub 代理

在 Anthropic 托管的环境中，所有 GitHub 操作都经过专用代理，使您的真实 GitHub 凭证保留在会话的 VM 之外，独立于环境的访问级别。自托管环境中的会话使用您的部署提供的凭证进行 git 操作身份验证；配置 git涵盖了选项，包括按会话生成的凭证和选择加入此同一代理。代理提供：

• Git 凭证：VM 内的 git 客户端使用范围受限的凭证，代理验证并将其交换为您的实际 GitHub 令牌。
• API 请求：来自内置 GitHub 工具的请求，以及来自 proxy-injected 占位符下的 gh 的请求，会在替换为您的真实凭证后发出。
• 推送保护：git push 仅适用于会话的当前工作分支；克隆、获取和 PR 操作正常工作。
• 存储库范围：GitHub API 和发布资产请求仅能到达附加到会话的存储库，因此从未附加的存储库下载发布资产的设置脚本会收到 403。
• GraphQL 限制：代理仅提供一组固定的 GraphQL 操作用于拉取请求工作流。代理在 GraphQL 端点上拒绝所有其他内容，返回 403，显示 This GraphQL query is not enabled for this session，并命名 REST 回退 gh api repos/{owner}/{repo}/...。无论您提供的凭证如何，限制都适用于通过代理的每个请求，因此您设置的 GH_TOKEN 会收到相同的 403。Claude 无法通过代理访问仅存在于 GraphQL 中的 GitHub API，例如 Projects v2。

来自公开存储库的已提交文件通过 raw.githubusercontent.com 到达，改由安全代理处理。该域在默认 Trusted 列表中，因此除非环境的访问级别排除它，否则这些文件保持可访问。

安全代理

Anthropic 托管环境中的云会话在 HTTP/HTTPS 网络代理后面运行，用于安全和滥用防范目的；在自托管环境中，出站流量通过您自己的网络边界离开。来自 Anthropic 托管会话的所有出站互联网流量都经过此代理，它提供：

• 防范恶意请求
• 速率限制和滥用防范
• 增强安全性的内容过滤
• 所请求主机名的 DNS 级审计踪迹

云会话中可用的内容

在 Anthropic 托管的环境中，每个会话都会获得一台运行 Ubuntu 24.04 的全新虚拟机 (VM)（x86_64 架构），无论您自己的操作系统和 CPU 架构是什么，您的存储库已克隆，常见的工具链已预安装。当依赖项提供预编译的二进制文件（例如具有本机扩展的 Ruby gem 或预构建的 Python wheel）时，请使用其 x86_64 Linux 构建以匹配 VM。本节涵盖 Anthropic 托管的默认值、内置 GitHub 工具、如何运行测试和服务，以及每台 VM 获得的资源限制。

您的设置中会保留的内容

云会话从您存储库的全新克隆开始。您提交到存储库的任何内容都可用。您只在自己机器上安装或配置的任何内容在会话中都不可用。您组织的策略通过服务器管理的设置单独到达。

要在云会话中提供您自己的配置，请将其提交到存储库。

任何使用环境的人都可以读取其环境变量和设置脚本。对话框在环境变量下的注释说明了这一点，并警告不要在那里放置密钥。在 Pro 和 Max 计划中，存储代理可以附加的密钥作为 API 凭证。

已安装的工具

云会话预安装了常见的语言运行时、构建工具和数据库。下表按类别总结了包含的内容。

¹ Bun 已安装，但在包获取时存在已知的代理兼容性问题。

要获取此表中大多数工具的版本，请让 Claude 在云会话中运行 check-tools。它是安装在会话 VM 上的 shell 命令，不是斜杠命令；您让 Claude 运行是因为 Claude 为您运行所有 VM 命令。对于它不报告的工具，例如 Ruby、PHP、bun、PostgreSQL 或 Redis，请让 Claude 运行该工具自己的版本命令，例如 psql --version。

Node.js 版本安装在 /opt/node20、/opt/node21 和 /opt/node22，默认情况下 22 在 PATH 上。要使用不同的版本，请让 Claude 将该版本的 bin 目录（例如 /opt/node20/bin）前置到 PATH。

此列表之外的工具链，例如 .NET SDK，即使其包注册表在默认允许列表上也不会预安装。请使用设置脚本安装它们。

使用 GitHub 问题和拉取请求

云会话包括内置 GitHub 工具，让 Claude 无需任何设置即可读取问题、列出拉取请求、获取差异和发布评论。这些工具通过 GitHub 代理，使用您在 GitHub 身份验证选项下设置的任何方法进行身份验证，因此您的令牌永远不会进入容器。

您可以在环境设置中自己设置 GH_TOKEN 或 GITHUB_TOKEN，或者两者都不设置，让 GitHub 代理为您进行身份验证：

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

您设置的令牌是普通环境变量，因此使用环境的任何人都可以读取它；代理路径将凭证保留在环境配置和会话 VM 之外。

要检查哪种情况适用于您的会话，请让 Claude 运行 echo $GH_TOKEN。

GitHub 的 gh CLI 已预安装。如果您需要内置工具未涵盖的 gh 命令，例如 gh release 或 gh workflow run，请让 Claude 运行它。gh 会自动读取 GH_TOKEN，因此您不需要运行 gh auth login。

将输出链接回会话

每个云会话在 claude.ai 上都有一个转录 URL，会话可以从 CLAUDE_CODE_REMOTE_SESSION_ID 环境变量读取自己的 ID。使用它在 PR 正文、提交消息、Slack 帖子或生成的报告中放置可追溯的链接，以便审阅者可以打开生成它们的运行。

Claude 在云会话中创建的提交包括 Claude-Session: <url> git 尾注，PR 正文在单独一行包括会话 URL。要省略尾注和 PR 正文链接，请将 attribution.sessionUrl 设置为 false。

要在提交或 PR 以外的内容中包含会话链接，例如 Claude 发布的 Slack 消息或它编写的报告文件，请让 Claude 运行以下命令并使用其输出。该命令将环境变量值中的 cse_ 前缀转换为转录 URL 预期的 session_ 前缀：

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

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

您无法进入会话 VM 的 shell。Claude 为您运行每个命令，因此请将本节中的工作表述为您提示中的请求。

运行测试

Claude 在处理工作的过程中运行测试。在您的提示中提出要求，例如"修复 tests/ 中的失败测试"或"在每次更改后运行 pytest"。随预安装的工具链提供的测试运行器（例如 pytest 和 cargo test）无需额外设置即可工作。您的项目声明为依赖项的运行器（例如 jest）会随您的依赖项一起安装。

启动服务

PostgreSQL 和 Redis 已预安装但默认不运行。让 Claude 启动您需要的任何一个；它运行的命令是：

service postgresql start

service redis-server start

Docker 可用于运行容器化服务。让 Claude 运行 docker compose up 以启动您项目的服务。拉取镜像的网络访问遵循您环境的访问级别，Trusted 默认值包括 Docker Hub 和其他常见注册表。

如果您的镜像很大或拉取速度很慢，请将 docker compose pull 或 docker compose build 添加到您的设置脚本。环境缓存保留拉取的镜像，因此每个新会话的磁盘上都有它们。缓存仅保存文件，不保存运行中的进程，因此 Claude 仍然在每个会话中启动容器。

添加包

要添加未预安装的包，请使用设置脚本。环境缓存保留脚本安装的内容，因此您在那里安装的包在每个会话开始时都可用，无需每次重新安装。您也可以让 Claude 在会话中途安装包，但这些安装不会带到其他会话。

资源限制

Anthropic 托管环境中的云会话运行时具有可能随时间变化的近似资源上限：

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

VM 可能会停止需要明显更多内存的工作，例如大型构建工作或内存密集型测试。对于超出这些限制的工作负载，请使用 Remote Control 在您自己的硬件上运行 Claude Code，或在自托管环境中运行云会话，该环境在您的组织运营的计算上。

设置脚本

设置脚本是一个 Bash 脚本，在新的云会话启动时运行，在 Claude Code 启动之前运行。使用设置脚本来安装依赖项、配置工具，或获取会话需要但未预安装的任何内容。

脚本以 root 身份在 Ubuntu 24.04 上运行，因此 apt install 和大多数语言包管理器都能工作。

要添加设置脚本，请打开环境设置对话框，并在 Setup script 字段中输入您的脚本。

此示例安装 ShellCheck，它不是预安装的。

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

脚本要求

设置脚本有三个需要考虑的约束：

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

环境缓存

设置脚本在您第一次在环境中启动会话时运行。完成后，Anthropic 会对文件系统进行快照，并将该快照重用作后续会话的起点。新会话以您的依赖项、工具和 Docker 镜像已在磁盘上的状态开始，并跳过设置脚本步骤。即使脚本安装大型工具链或拉取容器镜像，这也能保持启动速度快。

缓存是文件系统快照，因此它会保留设置脚本写入磁盘的内容，并丢失任何仅在运行中的内容。您安装的包、您拉取的 Docker 镜像和您写入的文件都会保留。脚本启动的数据库、docker compose up 堆栈或任何其他后台进程不会保留；请通过询问 Claude 或使用 SessionStart hook 在每个会话中启动这些。

当您更改环境的设置脚本或允许的网络主机时，以及当缓存在大约七天后到期时，设置脚本会再次运行以重建缓存。恢复现有会话永远不会重新运行设置脚本。

您不需要自己启用缓存或管理快照。

设置脚本与 SessionStart hooks

使用设置脚本来配备 VM 本身：未预安装的工具链和 CLI 工具。使用 SessionStart hook 进行应在各处运行的项目设置，包括云端和本地，例如 npm install。

设置脚本和 SessionStart hooks 在云会话启动时按固定顺序运行。下表比较了您在哪里配置它们、何时运行以及在哪里运行。

如果您在用户级 ~/.claude/settings.json 中有 SessionStart hooks，不要期望它们在云端生效。用户级设置保留在您的机器上。其他 hooks 运行的位置取决于会话运行的位置：

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

使用 SessionStart hook 安装依赖项

要仅在云会话中安装依赖项，请将 SessionStart hook 与检查其运行位置的脚本配对。

首先，将 SessionStart hook 添加到您的存储库的 .claude/settings.json。此配置告诉 Claude Code 在会话启动或恢复时运行存储库中的 scripts/install_pkgs.sh：

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

matcher 将 hook 限制为 startup 和 resume 事件，$CLAUDE_PROJECT_DIR 解析为存储库根目录，因此无论会话的工作目录是什么，hook 都能找到脚本。

接下来，在 scripts/install_pkgs.sh 创建脚本。它在云端之外立即退出，否则安装您的依赖项：

#!/bin/bash

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

npm install
pip install -r requirements.txt
exit 0

CLAUDE_CODE_REMOTE 检查是将安装限制在云会话的关键：会话 VM 的环境将该变量设置为 true，在本地永远不会是 true，因此在您的笔记本电脑上，脚本会在安装任何内容之前退出。

这两个文件一起使每个云会话在启动时获得全新的 npm install 和 pip install，同时保持本地会话不受影响。

云会话中的限制

SessionStart hooks 在云端的行为与本地相同，但有以下注意事项：

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

要自定义基础镜像，请使用设置脚本在提供的镜像上安装您需要的内容，或使用 docker compose 将您自己的镜像作为 Claude 旁边的容器运行。目前不支持完全替换基础镜像。

默认允许的域

使用 Trusted 网络访问，会话默认可以访问以下域。标记为 * 的域表示通配符子域匹配，因此 *.gcr.io 允许 gcr.io 的任何子域。

相关资源

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