自托管环境（beta）

自托管环境在你的组织运营的基础设施上执行 Claude Code 云端会话。云端会话指任何不在开发者本机运行的会话：开发者从 claude.ai、手机和桌面应用、终端的 claude --cloud 以及定时例程启动。该功能在 Team 和 Enterprise 套餐上处于公开 beta，默认关闭。如果你的团队不使用云端会话，这里没有需要配置的东西：终端或 IDE 里的会话总是在开发者自己的机器上运行；想在自己常开的机器上运行 Claude Code 并从其他设备驱动它，用 Remote Control（Pro 和 Max 也可用）。

工作方式

自托管由三部分组成：

• 环境（Environment）：云端会话可以发往的命名目的地，由你的组织在 claude.ai 管理设置里创建，每个环境对应一组 runner
• Runner：运行在你网络内主机上的程序，负责执行会话，思路与自托管 CI runner 相同
• 会话（Session）：开发者启动的一个 Claude Code 任务

开发者启动云端会话时，会话启动界面显示环境选择器，列出 Anthropic 托管的环境和你的组织创建的环境。选了你的环境，Anthropic 的控制平面把会话放进该环境的队列，由某个 runner 认领、克隆仓库并运行。一个 runner 同一时间只服务一个所有者，认领第一个会话时就锁定到该所有者，所以检出的代码不会在所有者之间混用。你可以自己启动并保持 runner 运行，也可以运行自动伸缩的编排器（你托管的第二个进程），它在会话排队时启动 runner，每个 runner 在工作完成后自行退出。

可用性与限制

规划推行前先检查：

• 套餐：Team 和 Enterprise 组织的公开 beta；默认关闭，由 Owner 在 Cloud environments 管理页打开 Allow self-hosted environments（要求组织已启用云端会话）
• 零数据保留：启用了零数据保留的组织不可用
• 模型推理：会话使用 Anthropic API，推理不能通过 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 或 LLM 网关路由
• 入口：从 claude.ai/code、手机和桌面应用、定时例程以及终端（claude --cloud 或 --environment 派发）启动的会话可以在自托管环境里运行；Claude Tag 会话也可以，但其中 Claude 还不能使用 Access bundle
• 仓库：会话从 GitHub 检出仓库
• 计费：自托管环境里的会话与 Anthropic 托管环境里的会话一样消耗你组织的 Claude Code 用量

为什么自托管

多数团队用 Anthropic 托管环境更合适，它不需要运行或维护基础设施。自托管面向网络、工具或合规要求必须把会话执行放在自己控制的基础设施上的团队，要做好随之而来的运维责任。作为交换你得到：

• 网络访问：会话在你的网络内运行，可以访问内部服务、数据库和注册表，而不必把它们暴露到公网
• 自定义工具：在 runner 镜像里预装编译器、SDK 和内部 CLI，让每个会话开始时就能构建
• 合规：仓库检出和构建产物留在你控制的基础设施上；会话内容仍会发到 api.anthropic.com 做模型推理

关键概念

术语	含义
环境	在 claude.ai 设置里创建的一组命名 runner，会话路由到环境，而不是某个 runner
环境密钥	runner 向环境认证和注册用的单个共享凭据，创建环境时只显示一次（管理界面里标为 environment key）
Runner	你部署的长期运行进程，向环境注册、获得 runner 令牌并轮询会话
会话	一个 Claude Code 任务，每个会话作为 runner 派生的子 Claude Code 进程运行

在 API 字段、令牌声明和指标名里，环境显示为 pool，环境 ID 是 pool_id。runner 同一时间服务一个所有者：它接的第一个会话把它锁定到该会话的所有者，之后只为该所有者运行会话，最多到配置的容量。所有者是谁取决于会话如何启动：用户启动的会话，所有者是该用户的账号；Claude Tag 频道会话没有关联用户账号，所有者是启动会话的 Claude Tag 智能体。所以最小的 runner 数量是你预期同时活跃的所有者数量（用户和 Claude Tag 智能体都算）。

会话生命周期

1. 有空闲容量的 runner 认领会话并持有一个租约
2. runner 把仓库克隆到工作目录并派生一个子 Claude Code 进程
3. 子进程通过 HTTPS 流式回传事件，runner 持续轮询；每次轮询刷新租约并兼作心跳
4. 如果 runner 约 60 秒不再轮询，服务器把会话重新排队给另一个 runner

runner 默认容量用 --capacity 设置；默认值 0 的退休行为是：活动会话一结束 runner 就退出（不再轮询），让你部署它的编排器（如 Kubernetes）用全新磁盘重启它，可服务任何所有者；设为正数则在锁定所有者的队列上再轮询那么多秒后退出。基础设施用 SIGTERM 停止 runner 时无需额外标志，runner 会排空；如果基础设施在已知的时间点销毁主机，用 --retire-at，runner 会停止接新活，并在各会话状态合适时释放它们，让会话在用户下次发消息时于新 runner 上恢复。没有 --retire-at 时，无信号的主机被杀与崩溃无法区分，控制平面记为 worker 丢失，会话重新排队。

网络路径

runner 及其会话发起几类出站连接，不需要 Anthropic 的入站连接：控制平面（runner 轮询 api.anthropic.com 获取工作并发布设置进度和失败事件，全是出站 HTTPS，轮询兼作心跳）；SCM 连接器（可选的编排器 SCM 连接器隧道是唯一的 WebSocket 连接）；Git（runner 用你的部署提供的凭据通过 HTTPS 或 SSH 从你的 git 主机克隆和推送，可选的 Anthropic git 代理改为经 api.anthropic.com 路由 git）；会话子进程（保持到 api.anthropic.com 的事件流，并为模型推理以及会话期间运行的 git 命令发起自己的出站调用）。支持企业出口代理：runner 和编排器遵循 HTTPS_PROXY、NO_PROXY 等代理和 mTLS 环境变量，在每个进程的环境里设置；代理还要求 Proxy-Authorization 头时，runner 可以为它打开的每个到代理的连接加上。

哪些留在你的基础设施上

仓库检出、构建产物、密钥以及会话创建或修改的任何文件都留在你准备的机器上。对话本身（提示、回复、工具结果）发往 api.anthropic.com 做模型推理，Anthropic 存储会话转录以便你之后恢复会话。自托管环境把会话执行移进你的网络，控制平面仍由 Anthropic 托管：会话编排、排队和 claude.ai 界面继续运行在 Anthropic 的基础设施上。

开始

官方自托管环境页按你要做的事组织：快速开始（安装 Claude Code、创建环境、启动 runner、路由第一个会话）；部署到生产（安全加固、网络出口、git 凭据、Kubernetes 和 Compose 配方、已知问题和排障）；自定义会话（包装脚本、生命周期 hooks、按需 runner、MCP 服务器和权限）；端到端测试；参考（每个 CLI 标志、环境变量、指标和健康端点）；验证会话身份。这些系列页面以官方原文为准。