云端 Claude Code:云会话实战指南
云会话为每个任务在一台全新虚拟机上运行 Claude Code。四个真实会话、七种适用的工作流,以及如何连接 GitHub 而不被卡住。
你可能在自己的笔记本电脑的终端中运行 Claude Code。该会话在三个方面依赖于笔记本电脑:
- 它共享你的工作树,因此同一仓库上的两个会话可能会编辑相同的文件,并争用同一个端口。
- 它使用你的凭据运行。
- 当你的电脑进入睡眠状态或 Wi-Fi 断开时,它就会停止。
云端会话在一台独立的机器上运行 Claude Code。每个任务都会获得一个全新的虚拟机,其中克隆了你的仓库到一个新分支,并且你的环境配置也已完成。
你可以从 claude.ai/code、Claude 移动应用、桌面应用、你的终端以及 Slack 启动会话。之后,你可以通过浏览器、移动应用和桌面应用跟踪它。当工作完成后,它会停留在一个分支上,你可以将其转换为拉取请求。
云端会话包含在你的 Pro、Max、Team 或 Enterprise 计划中,无需额外付费:云端机器不单独收费,会话与 Claude Code 的其他部分使用相同的用量限制。根据你的计划,组织所有者可能需要先启用云端会话。
在本指南中,我针对一个小型示例仓库运行了四个真实的云端会话。它们的记录、差异和耗时在全文中均有呈现。截图中的仓库和用户均为虚构。工作内容、输出和数据均来自这些会话。
云端会话的主要优势之一是,你可以同时运行多个任务而不会相互干扰。以下是我相隔 16 秒内启动的三个会话,每个都在各自的机器上。如果在笔记本电脑上,我只能依次运行它们,或者花费时间来避免它们相互干扰。
三个任务,一个仓库,三台机器
示例仓库是 tidepool,一个为三个虚构港口预测潮汐的小型 Node API。它存在三个常见问题:一个测试大约每四次运行失败一次,API 文档描述了代码不再读取的参数,日志记录器通过字符串拼接来构建日志行。
我在 16 秒内启动了三个云端会话,每个对应一个问题。我是以编程方式启动它们的,由于 tidepool 不在 GitHub 上,每个会话首先根据其提示词中的文件重建仓库。对于真实仓库,你会跳过这一步,而在终端中,每个会话只需一条 claude --cloud 命令。简写后的三个提示词如下:
CODEShell
claude --cloud "npm test fails maybe one run in four. Find the flaky test, fix the root cause in the code (not the test), and prove it by running the suite at least 30 times in a row." claude --cloud "docs/API.md is out of date with src/server.js. Rewrite it so every endpoint, parameter, default and response shape matches the code. Start the server and run each curl example to check it." claude --cloud "Make src/logger.js emit one JSON object per line, keep LOG_LEVEL, and log method, path, status and duration_ms as fields. Add a test for the logger."
这些会话分别运行了 61、65 和 72 秒,且三个会话都在第一个会话启动后 87 秒内全部完成。重建仓库大约占每次运行时间的三分之一到略多于一半。以下是结果。
- 不稳定的测试。Claude 在
TtlCache.get中发现了一个竞态条件。缓存仅在加载器完成后才存储值,因此在加载过程中对同一键的第二个get会再次调用加载器。Claude 将缓存改为存储进行中的 promise,在加载失败时删除该条目,并连续运行npm test40 次,零失败。 - 文档。Claude 启动了服务器,对每个端点运行了 curl,发现旧文档有五处错误。它列出了 API 从不返回的字段、记录了一个代码忽略的
days参数、以英尺而非米给出高度、跳过了/next-high端点,还遗漏了错误响应。它还发现格式错误的from=值会返回一个带 200 状态码的空列表,并将其记录为注意事项,而不是去修改它未被要求改动的服务器代码。 - 日志记录器。Claude 编写了 JSON 日志记录器,将请求日志迁移到结构化字段,并添加了五个测试。它的提交带有一个失败的测试,于是 Claude 将缓存测试重跑了八次,发现其中五次失败,并将失败追溯到第一个会话正在修复的同一个竞态条件。它提出了相同的修复方案,没有碰缓存因为那超出了它的任务范围,并在总结中说明测试套件并非全部通过。
日志记录器的结果说明了为什么云会话适合并行工作。每个会话都有自己仓库副本、自己的进程和自己的分支。文档会话和日志记录器会话各自启动了 API 服务器进行测试,彼此互不影响。在一台笔记本电脑上,两个智能体在同一个检出目录中工作会编辑相同的文件,并且除非各自选择不同的端口,否则会在端口上发生冲突。
由于这种隔离,日志记录器会话无法访问第一个会话正在进行的缓存修复。按文件边界拆分并行任务,以合理的顺序合并分支,并预期某个会话会报告另一个会话已经在修复的问题。
CLAUDE CODE 云会话的底层机制
云会话是在 Anthropic 管理的基础设施上运行的 Claude Code 会话,或在您组织自己的机器上通过 自托管环境 运行。图中展示了各个部分。其后的四点要点将改变你的工作方式。
- 每个任务都有自己的机器。一个全新的虚拟机,将你的仓库克隆到新分支上,因此会话无法触及彼此的文件或端口。参见 已安装的内容。
- 你的 GitHub 令牌从不进入虚拟机。一个代理持有它,会话获得一个短期凭据,只能推送到自己的工作分支。参见 GitHub 代理。
- 仓库的 Claude 配置会随之而来,你的个人配置则不会。
CLAUDE.md、规则、技能、智能体和命令随仓库一起传输,而你的~/.claude留在你的笔记本电脑上。参见 云会话中的设置。 - 空闲的虚拟机会被回收。重新打开会话,你会得到一个恢复了对话的全新虚拟机,所以请提交你关心的工作。参见 环境过期。
本地还是云端?
云会话不会取代本地会话,大多数人两者都用。表格展示了它们的差异,其后的段落说明了各自适用的场景。
| 本地会话 | 云端会话 | |
|---|---|---|
| 运行于 | 你的机器 | 每个任务一台全新虚拟机 |
| 笔记本休眠或离线 | 会话停止 | 会话继续运行 |
| 同一仓库的多个任务 | 各自独立的工作树、端口和维护 | 每个任务一台虚拟机和一个分支 |
| 智能体可访问的范围 | 你的用户账户能访问的一切,包括 SSH 密钥、云 CLI 和 ~/.claude | 仓库、你设定的网络层级、你启用的连接器,以及一个仅限会话使用的 GitHub 凭据 |
| 从何处启动或跟进 | 该机器,或通过远程控制用手机 | 浏览器、手机、Desktop、终端、Slack、API 调用或定时任务 |
| 审批方式 | 任意模式,包括逐条命令审批 | 自动、接受编辑或计划 |
| 结束时留下 | 工作树中的更改 | 一个分支,以及需要时的一个拉取请求 |
| 计算费用 | 你的机器 | 无额外计算费用;使用你套餐的额度 |
当任务需要只有你机器上才有的东西时,保持本地。这包括带有真实本地数据的数据库、通过 VPN 访问的服务、GPU、手机模拟器,或你桌面上的硬件。当你希望在几秒内于自己的浏览器中看到每处更改的紧凑视觉循环时,也应保持本地;当你的组织采用 零数据保留(这会关闭云端会话)时同样如此。
两个功能介于这两种选择之间。远程控制让会话保持在你的机器上,并允许你用手机或浏览器操控它。自托管环境(Team 和 Enterprise 版处于测试阶段)在你组织自己的基础设施上运行云端会话,因此它们可以访问私有网络。
如果以上都不适用,这个任务就很适合云端。下一节介绍最能从中获益的工作流。
适合云端会话的七种工作流
这些工作流发挥了表格中的差异:每个任务一台独立机器、你离开时会话仍在继续运行,以及最后留下一个分支供你审查。
1. 并行清理积压任务
假设你有五个互不相关的小修复。在本地,你得一个接一个地做,或者设置五个工作树并把它们的端口和安装分开。在云端,你可以启动五个会话并审查五个分支。
CODEShell
claude --cloud "Fix the flaky test in auth.spec.ts" claude --cloud "Update the API documentation" claude --cloud "Refactor the logger to use structured output"
claude --cloud 会按你当前分支克隆你的 GitHub 远程仓库,所以请先推送你的本地提交。虚拟机启动时,CLI 会显示设置步骤的实时清单,并把你输入的内容排队。
把每个任务写成一个自包含的工单,说明哪里有问题、完成是什么样子,以及如何证明。那个不稳定测试的提示词指明了它的证明方式:连续运行测试套件至少 30 次。该会话运行了 40 次。
当这些任务属于一个更大的工作时,项目(Pro 和 Max 版公测中)会运行一个协调者对话,为你启动并跟踪云端会话。然后它按状态分组:进行中、等待你处理、以及待审查。
2. 让它证明修复
不稳定测试是需要反复证明的工作的最清晰案例:你必须一遍又一遍地运行测试套件,而你不想让这个循环占用你正在工作的机器。在云端,Claude 修补了缓存,并用一条命令把整个测试套件运行了 40 次。
虚拟机不产生计算费用,其 CPU 也不占用你的额度,所以尽管要求详尽的证明。把测试套件运行 200 次,对 50 个提交进行二分查找定位回归,运行缓慢的集成测试层,或者像文档会话那样启动应用并用 curl 请求它。
Claude 的每一轮对话仍会计入你的套餐,但在一条命令内进行的长时间测试运行成本很低。前台命令默认在 2 分钟后超时(最多 10 分钟),之后会在后台继续运行最多 30 分钟。你可以在环境变量中用 BASH_DEFAULT_TIMEOUT_MS 和 BASH_MAX_TIMEOUT_MS 提高默认值。
3. 在桌前规划,在云端构建,在终端中完成
对于较大的改动,先在往返沟通成本低的地方商定方法。以计划模式启动 Claude,共同制定计划,提交计划,然后推送它。
CODEShell
claude --permission-mode plan # ...agree on the plan, save it to docs/migration-plan.md, commit and push... claude --cloud "Execute the migration plan in docs/migration-plan.md"
当云端会话构建时,你的终端可以自由处理其他工作。构建完成后,把会话拉取下来手动完成收尾。
CODEShell
claude --teleport # pick a cloud session claude --teleport <session-id>
Teleport 会检查你是否在同一个仓库中,获取会话的分支,检出它,并将整个对话加载到你的终端中。你需要一个干净的工作区(它会提议暂存更改),且分支必须已推送。在 Claude Code 内部,/teleport(或 /tp)会打开相同的选择器,先 /tasks 再 t 也可以。桌面应用则方向相反,其 Open in 菜单可将本地会话发送到云端。
4. 用手机查看进度
Claude 应用中的 Code 标签页连接到相同的会话。你可以用手机启动任务、跟踪任务、引导任务、回答 Claude 提出的问题,或让 Claude 监控一个拉取请求。
手机适合那些等你走到键盘前就会忘记的问题。我给第四个会话提了一个适合在手机上输入的问题:tidepool 如何预测潮汐,在时间窗口的边缘它可能如何出错?它运行代码验证了答案,并发现了一个真实的 bug。该循环从不检查第一个或最后一个样本,因此 API 会漏掉恰好落在窗口起点的高潮。
5. 把 CI 失败和审查意见交给 Claude
在仓库上安装 Claude GitHub App 后,云端会话可以监控拉取请求并对其发生的情况采取行动。在 claude.ai/code 的会话中,从 CI 栏开启 Auto-fix。你也可以在终端的 PR 分支上运行 /autofix-pr,让移动应用监控该 PR,或将 PR URL 粘贴到会话中。
Claude 会为失败的检查和审查意见推送清晰的修复,并解释它改了什么。对于任何模糊或涉及架构的问题,它会询问你。在审查线程中的回复会以你的 GitHub 用户名发布,并标注为 Claude Code。Claude 不会收到与基础分支合并冲突的通知,所以要让它执行 rebase。它的评论也可以触发评论驱动的自动化工具,例如 Atlantis。
6. 不用亲自开始就能开始工作
A routine(研究预览)是若干已保存的资源,用于完成一项任务,例如提示词、仓库、连接器和环境。每次运行都是一个由触发器启动的云会话。触发器可以是计划任务(最常见为每小时一次)、对例程自身端点的 HTTP 调用,或 GitHub 事件(如拉取请求打开或发布)。可在 claude.ai/code/routines、桌面应用或使用 CLI 中的 /schedule 创建例程。例程运行时无需批准提示,默认推送到以 claude/ 为前缀的分支。
两个较小的工具在此有所帮助。你可以在任何已登录的机器上(包括 CI 任务)向正在运行的会话排队一个后续任务。
CODEShell
claude -p "The integration tier is green now; rebase on main and push" --cloud <session-id>
你还可以为预填好的会话添加书签。形如 claude.ai/code?prompt=Triage+the+newest+issues&repositories=acme-labs/tidepool 的 URL 会打开 claude.ai/code,提示词和仓库均已预先填好。
7. 运行你并不完全信任的代码
贡献者的拉取请求、新依赖的安装脚本,或你五分钟前克隆的仓库,都可能运行你未曾阅读过的代码。在你的笔记本电脑上,这些代码会在你的 SSH 密钥、云 CLI 会话和浏览器配置文件旁边运行。在云会话中,它运行在一个一次性虚拟机中,没有上述任何内容,只有会话范围的 GitHub 凭据,以及一个可以收窄的网络。
将环境的网络访问设置为 None 以获得最严格的运行,或保持 Trusted,它允许访问软件包注册表、GitHub 和主要的云 SDK 主机。即使在 None 模式下,Claude Code 仍会向 Anthropic API 发送请求,因此数据仍可能通过这种方式离开虚拟机,会话也仍可推送到其自身分支。所有出站流量都会经过一个记录主机名的代理。
CONNECTING GITHUB WITHOUT GETTING STUCK
如果您的首次云端会话出现问题,GitHub 是最可能的原因。大多数问题源于云端会话需要两项独立的 GitHub 权限。
- 使用 GitHub 登录会告知 Claude 您的身份。
- 在账户或组织上安装 Claude GitHub 应用可设置 Claude 在该处可查看哪些私有仓库。
公开仓库仅需第一项即可使用。私有仓库需要第二项,且需安装在拥有该仓库的账户或组织上。如果您已连接 GitHub 但某个私有仓库缺失,通常是因为拥有它的账户或组织上未安装该应用。
| 您已连接的内容 | 公开仓库 | 您的私有仓库 | 组织的私有仓库 | 自动修复、GitHub 触发器、项目 |
|---|---|---|---|---|
| 仅使用 GitHub 登录 | 是 | 否 | 否 | 否 |
| + 在您的个人账户上安装应用 | 是 | 是 | 否 | 您的仓库 |
| + 在组织上安装应用(需所有者批准) | 是 | 仅当您的账户上也已安装时 | 是 | 组织仓库 |
/web-setup(您的 gh 令牌) | 是 | 是 | 您的令牌可访问的任何内容 | 否,需要该应用 |
方式 A:在浏览器中连接(推荐)
在 claude.ai/connect-github 连接您的 GitHub 账户,然后在拥有您仓库的账户或组织上安装 Claude GitHub 应用。对于组织,通常需要所有者批准安装。快速入门 会逐步讲解每个步骤。
如果 GitHub 没有将你送回 claude.ai/code,claude.ai/connect-github 上的连接页面会显示一份简短清单,列出常见原因。其中之一是单点登录步骤,如果跳过它,组织的仓库将被隐藏。
自动修复、GitHub 触发的例程和项目也依赖于 App,因此即使你通过其他方式连接,也请安装它。
路径 B:从终端使用 /web-setup 进行连接
如果你已经在使用 gh CLI,请在 Claude Code 中运行 /web-setup,将你的 gh 令牌发送到你的 Claude 账户。之后,会话可以访问该令牌有权访问的任何仓库,无论是否安装了 App。有关分步说明,请参阅 从终端连接。在 Team 和 Enterprise 计划中,所有者必须先启用 快速设置。
路径 C:跳过 GitHub 进行一次性操作
在没有 GitHub 远程仓库的仓库中,或在未安装 App 的仓库中运行 claude --cloud,Claude Code 将上传你的仓库包,而不是克隆它。只有当你的 GitHub 连接对该仓库具有推送权限时,会话才能推送回去。文档列出了该包包含和不包含的内容。
如果你使用 Team 或 Enterprise
所有者有一份简短清单:在 claude.ai/admin-settings/connectors 启用 GitHub 连接器,在 Claude Code 管理设置 中允许云会话,在组织的仓库上安装 Claude GitHub App(或批准成员的请求),并决定是否启用 快速设置。使用 IP 允许列表或 GitHub Enterprise Server 的组织还有额外步骤。请参阅有关 IP 允许列表和 GitHub Enterprise Server 的文档。
当它仍然不起作用时
| 你看到的现象 | 原因 | 解决方法 |
|---|---|---|
| 私有仓库未出现在选择器中 | 拥有它的账户或组织未安装 App,或其仓库访问权限排除了它 | 在该处安装 App,或将仓库添加到你 GitHub 设置中 App 的仓库访问权限 |
| 出现错误,提示你必须是组织的所有者才能关联它 | 组织阻止了成员身份检查,通常是因为待处理的 App 权限请求、IP 允许列表或 SAML 单点登录 | 所有者在组织的 GitHub App 设置中接受待处理的权限请求,为已安装的 GitHub App 启用 IP 允许列表继承,或(在 SAML 下)授予 Claude 对该组织的访问权限 |
| 刚连接后,组织的仓库就缺失 | 该组织使用 SAML 单点登录,且其授权步骤被跳过 | 在 GitHub 的“登录到你的组织”步骤中,在继续之前点击每个组织旁边的授权。如果你已经跳过了它,请在你的 GitHub 设置中为该组织授权 Claude,然后重新连接 |
| 每个云会话都因身份验证错误而失败 | 你的 Claude 组织使用了 IP 允许列表 | 请求支持团队豁免 Anthropic 托管的服务 |
有关其他内容,请参阅文档中的故障排除,包括连接 GitHub 后没有显示仓库的情况。要完全断开 GitHub,请使用 claude.ai/customize/connectors。
让会话具备检查自身工作的条件
能够运行测试的会话会在把工作交还给你之前先检查自己的工作。没有这一点,你审查的就是没人运行过的改动。本指南演示中的大部分价值都来自 Claude 运行各种东西:测试套件运行 40 次、服务器及其 curl 请求、窗口边缘的潮汐计算。十分钟的环境配置就让 Claude 有了运行这些检查的途径。
- 从 Default 环境开始。它使用 Trusted 网络访问,没有变量也没有设置脚本,这对大多数 JavaScript、Python、Go 和 Rust 仓库来说已经足够。
- 为机器使用设置脚本。它在 Claude Code 启动之前以 root 身份运行,因此
apt install可以工作。它必须以 0 退出,否则会话将无法启动,并且应在大约五分钟内完成,以便环境被缓存。之后,新会话将从带有你磁盘上工具的快照启动。当你更改脚本或允许的主机时,缓存会重建,大约每七天重建一次。 - 为项目使用 SessionStart 钩子。将
npm install及类似步骤放入仓库的.claude/settings.json中的钩子里,这样它们在本地和云端的运行方式就相同。如果某一步骤仅应在云端运行,请检查CLAUDE_CODE_REMOTE。仓库钩子会在单仓库会话中加载。 - 按会话启动服务。缓存存储的是文件。正在运行的进程不会在缓存中存活。让 Claude 运行
service postgresql start,或在 SessionStart 钩子中执行。 - 选择最窄的可用网络级别。Trusted 覆盖常见注册表。使用 Custom 添加私有注册表,只有在任务需要开放互联网时才使用 Full。更改大约在一分钟内到达运行中的会话。
- 不要把机密信息放在共享变量中。环境变量对使用该环境的任何人都可见。在 Pro 和 Max 上,环境的 API 凭据会为发往你指定主机的请求附加一个密钥,该密钥位于虚拟机之外,因此密钥永远不会存放在变量中。
- 把命令写进 CLAUDE.md。你的个人
~/.claude不会到达云端虚拟机。如果 Claude 需要知道如何运行集成测试,仓库必须说明这一点。
值得养成的习惯
- 一个任务,一个会话。小而独立的会话更容易审查,丢弃起来成本也更低。
- 要求提供证据。指明能证明任务已完成的命令,并在查看差异之前阅读 Claude 的总结。
- 在
claude --cloud之前推送。虚拟机是从 GitHub 克隆的,因此未推送的提交不会到达它。 - 在长任务中随时提交。空闲的虚拟机可能会被回收。
- 在差异视图中审查。内联评论会批量放入你的下一条消息中,Create PR 可以打开完整的 PR、草稿,或 GitHub 的撰写页面。
- 在 Claude 工作时进行引导。你在 Claude 工作时发送的消息会排队,你可以撤回已排队的消息。
- 共享会话。在 Team 和 Enterprise 中,将会话的可见性设置为 Team,以便审阅者可以阅读更改是如何完成的。云端会话的提交会带有
Claude-Session尾注,链接回转录记录。 - 注意你的限额。并行会话会同时消耗你的套餐限额,因此五个会话消耗限额的速度大约是单个会话的五倍。Routines 有各自的每小时上限,projects 每天最多可启动 200 个新线程。
常见问题
谁可以使用云端会话?Pro、Max 和 Team 套餐,以及拥有高级席位或 Chat + Claude Code 席位并使用 claude.ai 账号登录的 Enterprise 用户。使用 Console API 密钥或第三方提供商时无法使用。请参阅 cloud sessions 文档。
我的数据会去哪里?Anthropic 存储会话转录记录,保留时长取决于你的套餐和模型改进设置。虚拟机在闲置后会被回收,删除会话会移除其数据。请参阅 数据使用 和 安全性。
Claude 会用我的云端会话数据进行训练吗?云端会话遵循与 Claude Code 其余部分相同的政策。在 Team、Enterprise 和 API 中,除非你的组织选择加入,否则 Anthropic 不会用你的代码或提示词训练模型。在 Free、Pro 和 Max 中,这取决于你的模型改进设置。请参阅 数据使用。
它能处理我的大型代码仓库吗?虚拟机大约有 4 个 vCPU、16 GB 内存和 30 GB 磁盘。将繁重的安装放在设置脚本中,这样它们只运行一次并进入缓存快照。
GitLab 或 Bitbucket 怎么办?claude --cloud 可以从任何 git 仓库上传 bundle,但会话无法推送到这些托管平台。GitHub Enterprise Server 在 Team 和 Enterprise 中受支持。请参阅 平台限制。
并行分支发生冲突时会怎样?会话之间彼此不知道。合并一个分支,然后向下一个会话发送后续指令,例如 claude -p "rebase on main and fix any conflicts" --cloud <session-id>。
我会失去我的本地工具吗?用户级配置不会随之传输,因此请将团队所需的内容移入代码仓库:将技能和命令提交到 .claude/ 下,将项目范围的 MCP 服务器添加到 .mcp.json,并在 CLAUDE.md 中记录测试命令。云端会话中的设置列出了每个会话读取的内容。
五分钟开始使用
设置大约需要五分钟。之后,你可以移交任务、合上笔记本电脑,然后回来查看一个可供审阅的分支。
- 打开 claude.ai/code,或在 Claude Code 中使用你的 claude.ai 账号运行
/login。 - 连接 GitHub 并在你的代码仓库所在位置安装 Claude GitHub App。
- 选择代码仓库和默认环境。
- 从你的待办事项中给 Claude 一个任务,并附上一条能证明任务完成的命令。
- 关闭标签页。稍后从手机上查看,然后在 claude.ai/code 上审阅差异并创建拉取请求。