配置云端环境

每个云端会话都运行在一个云端环境里。云端会话适用于 Pro、Max 和 Team 套餐，以及有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。你可以配置环境来允许或拒绝网络访问、为会话设置环境变量、（在 Pro 和 Max 套餐上）存储会话可以使用但看不到的 API 凭据，并在 Claude 开始工作前运行 setup 脚本。无论你在哪里启动云端会话（桌面应用、Claude 手机应用、浏览器里的 claude.ai/code、终端里的 claude --cloud、例程、Claude Tag），适用的都是同样的环境；这些入口也都可以路由到自托管环境。Remote Control 会话把网页和手机界面连接到你自己机器上的会话，用的是你机器的网络和文件，不是云端环境；Claude Tag 频道会话只使用组织级环境（共享环境或自托管环境）。

Default 环境

如果你还没有环境，入门流程会设置 Default 环境：CLI 流程（如 /web-setup）和 Pro、Max 的网页入门会为你创建它；Team 和 Enterprise 的网页入门会显示 Create your first cloud environment 表单（除非 Owner 打开了 Quick web setup），保留表单默认值并点 Create & finish 就得到同样的 Default 环境。Default 自身没有配置：Trusted 网络访问（会话可访问包注册表和其他允许列表里的域名，通过会话网络不能访问别的），不定义环境变量或 setup 脚本，所以会话只带预装工具启动。只有 Default 时每个会话都在其中运行；有多个环境时，各入口选择不同：桌面应用、手机应用和 claude.ai/code 上你自己启动的会话使用选择器里显示的环境（你没选时由 Owner 设置的组织默认填充；项目里的线程改用项目设置里设置的环境）；CLI 使用你 /remote-env 的选择，没选时在列表里有 Anthropic 托管环境就回退到它，否则回退到列表里第一个不是桥接环境（Remote Control 为代表你自己的机器而注册的条目）的环境。当默认值不够用时才需要配置环境：Claude 需要访问默认允许列表之外的域名、需要为会话设置环境变量，或需要在开始工作前安装依赖。

配置环境

在环境选择器里创建、编辑和归档环境（网页入门后在 claude.ai/code，或桌面应用的提示框）。你创建的环境是个人的；Owner 创建的共享环境出现在同一个选择器里。步骤：在 claude.ai/code 点消息框上方一行里显示当前环境名称的云图标打开选择器（没有设置页或直接 URL）；选 Add cloud environment，或悬停在已有环境上点右侧出现的设置图标；对话框包含名称、网络访问级别、环境变量和 setup 脚本。

设置环境变量

环境变量用 .env 格式，每行一个 KEY=value。纯值不需要引号，用成对引号括起来的值其引号不会成为值的一部分；跨多行或含 # 的值要加引号（不加引号的值里 # 开始注释）。例如：

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

会话把环境的值读成普通环境变量，Claude 运行的任何命令都能读，OTEL_* 变量除外（Claude Code 用它们导出自己的遥测，不会传给它运行的命令）。在 Anthropic 托管环境里，会话在你创建时读取环境的值，之后每次 Claude Code 在会话 VM 里重新启动时再读一次：空闲几分钟后会话的 VM 暂停并保存文件，你的下一条消息恢复同一个 VM 并重新启动 Claude Code；暂停的 VM 若已被回收，重新打开会话时会预配一个全新的 VM。所以编辑、添加或删除变量后，托管环境里已有的会话保持它上次读取的值，直到其 VM 下次恢复或重建。云端会话启动时也会自己设置一些变量；对 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE，会话设置的值覆盖你在这里加的。任何使用该环境的人都能读到这些值，所以不要放机密；在 Pro 和 Max 套餐上，对代理可以附加到请求上的密钥改用 API 凭据。

添加 API 凭据

API 凭据是你存放在云端环境上的 API Key 或令牌，让 Claude 能在该环境的任何会话里调用那个 API 而看不到密钥：Anthropic 的智能体代理在请求离开会话 VM 之后，把密钥加到发往你所列主机的请求上，密钥永远到不了会话。API 凭据适用于 Pro 和 Max 套餐，Team 和 Enterprise 暂不可用（环境对话框里不出现 API credentials 一节）。

要求：决定你能否添加凭据的有两项：角色（你 claude.ai 组织里的管理员角色；Team 和 Enterprise 上是 Owner 而非 Admin，Pro 和 Max 上你在自己的组织里拥有它；没有它会看到说明而不是凭据列表，请 Owner 往共享环境加凭据并在那里运行会话）和环境类型（已存在的 Anthropic 托管云端环境；自托管环境没有 API 凭据）。决定代理能否使用它的有两项：API 能接受来自互联网的连接（因为请求从 Anthropic 的网络发出），以及组织若使用客户管理的加密密钥则无法保存凭据。

添加：逐个从已存在环境的编辑器里添加（新环境的对话框不提供，也不能编辑，要改凭据的主机或值就删除后重新添加）：在 claude.ai/code 打开环境编辑，在 Update cloud environment 对话框里 Environment variables 下方找到 API credentials；选 Add credential 填表，对放在请求头里传送的 API Key 保留默认的 Credential type 为 Bearer，填 Name（标签，如 Internal billing API）、Allowed websites（API 的主机，如 api.example.com，前导 *. 匹配每个子域名）、Custom headers（携带密钥的请求头一行，默认以 Authorization 为 Name、Bearer 为 Prefix，把密钥本身粘贴为 Value；对 X-Api-Key 这样接受裸值的头，改名并清除前缀）；选 Connect，凭据连同它的主机出现在列表里，保存后再也看不到值。验证：在环境里启动会话并让 Claude 调用该 API（如用 curl），API 的响应就像请求里带了密钥，而密钥不出现在会话的环境变量或任何文件里。

哪些请求得到凭据：代理在请求的主机与你在该凭据上列出的主机匹配时，把凭据附加到请求上；会话可以访问这些主机，即使环境的网络访问级别原本不允许（从不得到凭据的主机除外）。从不得到凭据的请求：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 脚本的请求（Claude Code 在启动时、setup 脚本运行之后才连接代理）；Claude Code 的遥测导出。

从 CLI 选择环境

在终端运行 /remote-env 选择你从 CLI 创建的云端会话（如 claude --cloud）的默认环境，它打开你现有环境的选择器，并把选择保存到用户设置的 remote.defaultEnvironmentId 键。自托管环境 ID（形如 ccpool_...）遵循更严格的来源规则。/remote-env 只设置默认值：不启动会话，也不能添加或编辑环境。

归档环境

要归档你自己的环境，打开编辑并选 Archive；Owner 在管理设置的 Cloud environments 页归档共享环境。不能删除环境，只能归档。归档影响新会话，不影响运行中的会话：已在环境里运行的会话继续工作；环境从选择器和 /remote-env 里消失；环境上的 API 凭据在其运行中的会话里保持附加（归档前先删除不想要的）；任何入口都不能在已归档环境里启动新会话。

组织共享环境

在 Team 和 Enterprise 套餐上，Owner 可以创建与组织每个成员共享的云端环境（管理设置里 Cloud environments 页的所有事务（包括自托管环境）由同一角色管理，Admin 角色打不开该页）。共享环境显示在每个成员的选择器里的 Organization 标题下（在成员自己的 Personal 环境之后），让团队统一一个配置而不必每人重建。Owner 有两种方式让环境对组织可用：在管理设置的 Cloud environments 页创建共享环境（每个有名称、网络访问级别、.env 格式的环境变量和 setup 脚本）；或把个人环境共享出去（在选择器里打开自己的环境编辑，从 Who can use it 一行共享；环境保留其 ID，所以已使用它的会话和例程不受影响）。组织默认环境由 Owner 单独在 claude.ai/admin-settings/claude-code 选择。每个成员在共享环境里的会话都读取它的变量，所以不要放机密。

设置 Claude Tag 频道使用的环境：在 Claude Tag 频道里 Claude 以组织的共享身份工作，而不是任何成员，所以频道会话只使用组织级环境（共享环境或自托管环境）。要给频道一个未预装的工具链（如 .NET），Owner 可以创建一个带 setup 脚本的环境：把共享或自托管环境设为 claude.ai/admin-settings/claude-code 的组织默认环境，或在 Claude Tag 管理设置里把一个环境固定到某个频道。

网络访问

每个环境设置一个网络访问级别，控制其会话能发起的出站连接；默认级别 Trusted 允许包注册表和其他允许列表里的域名，Custom 接受你自己的域名列表。要改网络访问，打开环境编辑并用对话框里的 Network access 选择器（共享环境在那里是只读的，由 Owner 在管理设置的 Cloud environments 页修改）。更改 Anthropic 托管环境的网络访问后，它现有的会话在约一分钟内遵循新设置（对经会话网络允许列表的请求），无需开始新会话。你在会话或例程上启用的 MCP 连接器不必把它们的主机加进 Allowed domains，因为连接器流量经 Anthropic 的服务器而不是会话的网络。

访问级别

无论选哪个级别，会话仍可访问这些，因为它们各自走不经会话网络允许列表的路径：通过独立代理的 GitHub；你启用的 MCP 连接器（流量经 Anthropic 的服务器）；你在环境 API 凭据上列出的主机（从不得到凭据的主机除外）；Claude Code 自己请求所需的 Anthropic API（即使在 None 下）。

允许特定域名

要允许不在 Trusted 列表里的域名，在环境的网络访问设置里选 Custom，然后在 Allowed domains 字段里每行列一个域名：

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

这个环境里的会话现在可以访问 api.example.com、internal.example.com 的任何子域名和 registry.example.com，通过会话网络不能访问其他域名。如果你的组织使用 Artifacts，会话读取它们不需要把 *.frame.claudeusercontent.com 加进列表（列表里没有该主机时，Claude Code 通过会话到 Anthropic 的连接读取 Artifact 内容）；在两种情形下要把它保留在允许列表里：这个环境里的会话打开别的组织的公开 Artifact（Claude Code 直接从该主机获取），以及你在配置本地 CLI 或自托管运行器时。每个环境有自己的允许域名列表，没有管理员能推送到每个成员环境的组织级允许列表，也没有服务端托管设置能给环境的网络允许列表添加域名；要给团队一个标准列表，Owner 可以创建一个带该列表的组织共享环境。

GitHub 代理

在 Anthropic 托管环境里，所有 GitHub 操作都经过一个专用代理，它把你真正的 GitHub 凭据保留在会话 VM 之外，与环境的访问级别无关（自托管环境里的会话用你的部署提供的凭据认证 git 操作）：Git 凭据（VM 内的 git 客户端使用一个限定范围的凭据，代理验证后换成你真正的 GitHub 令牌）；API 请求（内置 GitHub 工具和使用 proxy-injected 占位符的 gh 发出的请求，会被替换成你的真实凭据）；推送保护（git push 只对会话当前的工作分支有效，克隆、获取和 PR 操作正常）；仓库范围（GitHub API 和发布资产请求只到达附加到会话的仓库，所以从未附加的仓库下载发布资产的 setup 脚本会得到 403）；GraphQL 限制（代理只提供一组固定的、用于 PR 工作流的 GraphQL 操作，其他一律以 403 This GraphQL query is not enabled for this session 拒绝并点名 REST 回退）。公开仓库里已提交的文件通过 raw.githubusercontent.com 到达，由安全代理处理，该域名在默认 Trusted 列表里。

安全代理

Anthropic 托管环境里的云端会话运行在 HTTP/HTTPS 网络代理之后，用于安全和防滥用（自托管环境里出站流量改走你自己的网络边界）。托管会话的所有出站互联网流量都经过它，提供：防恶意请求保护、速率限制和防滥用、内容过滤，以及所请求主机名的 DNS 级审计线索。

云端会话里有什么

在 Anthropic 托管环境里，每个会话得到一个全新的虚拟机（Ubuntu 24.04、x86_64，与你自己的操作系统和 CPU 架构无关），克隆了你的仓库并预装了常用工具链。你的组织路由到自托管环境的会话则在你自己的运行器上运行，用运行器镜像提供的工具。

你的设置里哪些会带过来

云端会话从你仓库的全新克隆开始：你提交到仓库里的都可用；只安装或配置在你自己机器上的不可用；组织策略通过服务端托管设置单独到达。

要让你自己的配置在云端会话里可用，把它提交到仓库。任何使用该环境的人都能读到它的环境变量和 setup 脚本，对话框里 Environment variables 下的说明也这么警告。

预装工具

要查看表里多数工具的版本，让 Claude 在云端会话里运行 check-tools（会话 VM 上的 shell 命令，不是你用 / 输入的命令）。Node.js 版本安装在 /opt/node20、/opt/node21 和 /opt/node22，默认 PATH 上是 22；要用别的版本，让 Claude 把该版本的 bin 目录（如 /opt/node20/bin）放到 PATH 前面。不在列表里的工具链（如 .NET SDK）即使它们的包注册表在默认允许列表里也没有预装，用 setup 脚本安装。

处理 GitHub issue 和 PR

云端会话带有内置 GitHub 工具，让 Claude 无需任何设置就能读 issue、列 PR、获取 diff 和发表评论；这些工具通过 GitHub 代理认证，所以你的令牌不会进入会话。你可以在环境设置里自己设置 GH_TOKEN 或 GITHUB_TOKEN，或者两者都不设让 GitHub 代理为你认证：设置了令牌会原样传给容器，你的脚本和 GitHub 的 gh CLI 直接使用它；都不设且由 GitHub 代理处理会话认证时，两个变量在 Claude 运行的命令里读到占位字符串 proxy-injected，代理在出站 GitHub 请求上替换成你的真实凭据。你设置的令牌是普通环境变量，使用该环境的任何人都能读到，代理路径让凭据留在环境配置和会话 VM 之外。要检查适用哪种情形，让 Claude 运行 echo $GH_TOKEN。gh CLI 已预装，内置工具没覆盖的命令（如 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 trailer，PR 正文单独一行带会话 URL；要省略 trailer 和 PR 正文链接，把 attribution.sessionUrl 设为 false。要在提交或 PR 之外的东西（如 Claude 发的 Slack 消息或写的报告文件）里放会话链接，让 Claude 运行下面的命令（它把环境变量值里的 cse_ 前缀转换成链接所需的 session_ 前缀）并使用其输出：

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

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

你没有进入会话 VM 的 shell，Claude 替你运行每条命令，所以要把这些任务用请求的方式写在提示里。运行测试：在提示里要求（如「fix the failing tests in tests/」），随预装工具链来的测试运行器（pytest、cargo test）无需额外设置即可工作。启动服务：PostgreSQL 和 Redis 已预装但默认不运行，让 Claude 启动你需要的（命令是 service postgresql start、service redis-server start）；Docker 可用于运行容器化服务，让 Claude 运行 docker compose up，拉取镜像的网络访问遵循环境的访问级别，Trusted 默认包括 Docker Hub 和其他常见注册表；镜像大或拉取慢时，把 docker compose pull 或 docker compose build 加进 setup 脚本（环境缓存会保留拉取的镜像，每个新会话磁盘上就有；缓存只存文件不存运行中的进程，所以 Claude 仍要每个会话启动容器）。添加包：用 setup 脚本；环境缓存保留脚本安装的内容，所以包在每个会话开始时就可用；你也可以让 Claude 在会话中途安装，但那些安装不会持久。

资源限制

Anthropic 托管环境里的云端会话以近似的资源上限运行（可能随时间变化）：4 个 vCPU、16 GB 内存、30 GB 磁盘。VM 可能终止需要明显更多内存的任务（如大型构建或内存密集的测试）。超出这些限制的工作负载，用 Remote Control 在你自己的硬件上运行 Claude Code，或在你的组织运营的计算资源上用自托管环境运行云端会话。

时间限制

在 Anthropic 托管环境里，这些时间限制适用于云端会话中长时间运行的工作（构建、安装、测试运行）：Claude 运行的命令（云端环境不设自己的命令超时，所以 Bash 工具的默认值适用：前台命令默认等待 2 分钟，Claude 最多可以要求 10 分钟；命令到达超时时 Claude Code 把它移到后台而不是停止它（以 sleep 开头的命令除外），这样移走的命令最多可再运行 30 分钟，之后 Claude Code 在后台时间限制处停止它）；SessionStart hooks（command hook 在 600 秒后被取消，除非在 hook 条目上设置以秒为单位的 timeout；用 async: true 运行的 hook 不强制超时）；setup 脚本（耗时超过约五分钟的脚本不会被缓存）；空闲会话（几分钟没有活动后，会话的 VM 暂停并保存文件，暂停的 VM 之后可能被回收）。要提高环境会话的命令超时，在其环境变量里添加 BASH_DEFAULT_TIMEOUT_MS 和 BASH_MAX_TIMEOUT_MS（单位毫秒，如 BASH_DEFAULT_TIMEOUT_MS=600000 让默认值为 10 分钟）。

Setup 脚本

setup 脚本是新云端会话启动时、Claude Code 启动前运行的 Bash 脚本，用来安装依赖、配置工具，或获取会话需要的任何未预装的东西。脚本在 Ubuntu 24.04 上以 root 运行，所以 apt install 和大多数语言包管理器可以工作。在环境设置对话框的 Setup script 字段输入脚本，例如安装未预装的 ShellCheck：

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

脚本要求

• 以零退出：脚本以非零退出会让会话启动失败；对非关键命令加 || true，让偶发的安装失败不会阻塞会话
• 五分钟内完成：总运行时间保持在约五分钟以内，环境缓存才能构建；超过则环境不被缓存。独立的安装用 & 和 wait 并行运行
• 安装所需的网络访问：包安装需要访问注册表；默认 Trusted 级别覆盖 npm、PyPI、RubyGems 和 crates.io 等常见包注册表，None 网络访问下安装会失败

环境缓存

setup 脚本在你首次在环境里启动会话时运行。完成时间在约五分钟内，Anthropic 会对文件系统做快照，并把该快照作为后续会话的起点，新会话一开始就带着你的依赖、工具和 Docker 镜像。缓存是文件系统快照，所以保留 setup 脚本写到磁盘上的内容，丢失只在运行的东西：安装的包、拉取的 Docker 镜像和写入的文件会延续；脚本启动的数据库、docker compose up 的栈或任何其他后台进程不会。当你更改环境的 setup 脚本或允许的网络主机，以及缓存在约七天后过期时，setup 脚本会再次运行来重建缓存；在 Anthropic 托管环境里，会话的 VM 在空闲后恢复时 setup 脚本不会运行。你不需要自己启用缓存或管理快照。

Setup 脚本 vs SessionStart hooks

用 setup 脚本预配 VM 本身（未预装的工具链和 CLI 工具）；用 SessionStart hook 做应在所有地方（云端和本地）运行的项目设置，如 npm install。

如果你的用户级 ~/.claude/settings.json 里有 SessionStart hooks，不要指望它们在云端运行，用户级设置留在你机器上。在 Anthropic 托管环境里，Claude Code 运行来自仓库和你组织服务端托管设置的 hooks（Claude Tag 会话不接收服务端托管设置，所以那里不运行来自它的 hooks）；在自托管环境里，Claude Code 还运行运营者从运行器主机的 ~/.claude/ 播种的 hooks，以及运行器镜像托管设置文件里的 hooks（当该文件是 Claude Code 应用的托管来源之一时）。

用 SessionStart hook 安装依赖

要只在云端会话里安装依赖，把 SessionStart hook 与检查运行位置的脚本搭配。先在仓库的 .claude/settings.json 里加 hook：

{
  "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，所以在你的笔记本上脚本在安装任何东西之前就退出了。

云端会话里的限制：SessionStart hooks 在云端的行为与本地相同，但有这些注意点：每个会话一个仓库（含多个仓库的会话不加载任何仓库 .claude/settings.json 里的 hooks，对这类会话改用 setup 脚本安装依赖）；没有仅云端的范围（hooks 在本地和云端会话里都运行，要跳过本地执行就在 CLAUDE_CODE_REMOTE 不是 true 时提前退出）；需要网络访问（None 网络访问下这些 hooks 会失败）；代理兼容性（Anthropic 托管环境里所有出站流量经安全代理，有些包管理器工作不正常，Bun 就是已知的例子）；增加启动延迟（hooks 每次会话启动或恢复时运行，不像 setup 脚本受益于环境缓存，所以安装脚本要先检查依赖是否已存在再重装）。要自定义基础镜像，用 setup 脚本在提供的镜像之上安装你需要的，或用 docker compose 在 Claude 旁边运行你自己的镜像作为容器；暂不支持完全替换基础镜像。

默认允许的域名

Trusted 网络访问下，会话默认可以访问以下几类域名（* 表示通配子域名匹配，如 *.gcr.io 允许 gcr.io 的任何子域名）：Anthropic 服务（api.anthropic.com、docs.claude.com、platform.claude.com、code.claude.com、claude.ai、claude.com、support.claude.com、anthropic.com、www.anthropic.com）；版本控制（github.com 及其相关子域名如 api.github.com、raw.githubusercontent.com、codeload.github.com，gitlab.com、registry.gitlab.com，bitbucket.org 等）；容器注册表（registry-1.docker.io、auth.docker.io、hub.docker.com 等，以及 gcr.io、ghcr.io 等）；各语言的包注册表（npm、PyPI、RubyGems、crates.io、Go、Maven、NuGet 等）和云平台 SDK 的域名。完整且最新的域名列表以官方原文为准。