> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 自托管环境快速入门

> 设置您的第一个自托管环境：安装 Claude Code、创建环境、启动运行器，并将会话路由到该环境。

<Note>
  自托管环境在 Team 和 Enterprise 计划上处于公开测试阶段；[可用性和限制](/docs/zh-CN/self-hosted-environments#availability-and-limitations)涵盖了启用路径。本页面让您的第一个会话运行；有关它们是什么，请参阅[自托管环境](/docs/zh-CN/self-hosted-environments)，有关强化和部队配方，请参阅[部署到生产环境](/docs/zh-CN/self-hosted-environments-deploy)。
</Note>

[自托管环境](/docs/zh-CN/self-hosted-environments)在您的组织运营的基础设施上运行 Claude Code [云会话](/docs/zh-CN/claude-code-on-the-web)，由您部署的运行器进程执行。本快速入门建立您的第一个环境，这是最小的可行配置：一个主机上的一个运行器，运行一个测试会话。有两个步骤：[创建环境、启动运行器并将会话路由到该环境](#set-up-an-environment-and-runner)，然后[从您的终端向该会话发送后续消息](#send-a-follow-up-message-to-a-running-session)。您将在两个界面之间切换：claude.ai 用于创建环境、检查其状态和路由会话，以及主机上的终端用于运行器执行的所有操作。

完成后，您将在[**Cloud environments** 管理页面](https://claude.ai/admin-settings/cloud-environments)上拥有一个环境、一个轮询工作的运行器，以及在您的主机上运行的会话。在连接真实存储库或内部系统之前，请完成[部署到生产环境](/docs/zh-CN/self-hosted-environments-deploy)，其中涵盖了安全态势、出口控制、git 凭证和编排。

<h2 id="prerequisites">
  前置条件
</h2>

<h3 id="organization-and-roles">
  组织和角色
</h3>

claude.ai 端需要：

* **Allow self-hosted environments** 由[所有者](/docs/zh-CN/cloud-environments#organization-shared-environments)在[**Cloud environments** 管理页面](https://claude.ai/admin-settings/cloud-environments)上启用；在启用之前，**New** 按钮不会出现。如果您不拥有该角色，拥有该角色的人可以创建环境并将其密钥交给您；本页面上的运行器和终端步骤不需要 claude.ai 角色，当步骤在管理 UI 中检查状态时，运行器自己的日志行会给您相同的信号。
* 您的组织的 [GitHub 连接](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)，以便开发人员在启动会话时可以选择存储库。

<h3 id="host-and-network">
  主机和网络
</h3>

运行器主机需要：

* 一个 Linux 或 macOS 主机或容器，具有到 `api.anthropic.com` 的出站 HTTPS、到 `claude.ai` 和下面安装步骤重定向到的下载主机的出站 HTTPS，以及到您的 git 主机的出站 HTTPS 用于克隆；[网络要求表](/docs/zh-CN/self-hosted-environments-deploy#network-requirements)有完整列表。Windows 不支持作为运行器主机；改为在 Linux 容器中运行运行器。开发人员工作站不受影响，因为会话从浏览器中的 claude.ai 启动。
* 一个用于测试会话的仓库：可以是公共仓库，也可以是此主机已能通过其 HTTPS URL 克隆且无需提供凭据的仓库。
* 与实时同步的时钟，例如使用 NTP。当时钟偏离超过五分钟时，身份验证失败；请参阅[故障排除](/docs/zh-CN/self-hosted-environments-deploy#troubleshooting)。

<h3 id="software-on-the-runner-host">
  运行器主机上的软件
</h3>

在启动之前在主机上安装：

* **Claude Code v2.1.224 或更高版本**，使用任何[标准安装方法](/docs/zh-CN/setup)。运行器是标准 `claude` 二进制文件的一部分，较早的版本不识别 `self-hosted-runner` 子命令。本机安装程序的默认 `latest` 频道在发布后立即携带每个版本；`stable` 频道、Homebrew `claude-code` cask 和稳定的 apt、dnf 和 apk 存储库滞后约一周。要固定您的部队运行的确切版本，请参阅[安装特定版本](/docs/zh-CN/setup#install-a-specific-version)。对于容器镜像，请参阅[部署到生产环境](/docs/zh-CN/self-hosted-environments-deploy#build-the-runner-image)中的 Dockerfile。
* **Git 2.24 或更高版本**。部署页面上的某些 git 选项需要更高版本；[配置 git](/docs/zh-CN/self-hosted-environments-deploy#configure-git)说明了每个下限。

确认主机已准备好：

```bash theme={null}
claude self-hosted-runner --help
```

准备好的主机打印运行器的使用文本，列出诸如 `--environment-secret-file` 之类的标志。在 2.1.224 之前的版本上，该命令改为打印常规 `claude --help` 输出；使用 `claude update` 升级或从 `latest` 频道重新安装。

<h2 id="set-up-an-environment-and-runner">
  设置环境和运行器
</h2>

使用[引导式设置](#run-the-guided-setup)或[手动步骤](#set-up-manually)。引导式设置只需一条命令，它会启动一个交互式 Claude Code 会话，并引导您完成其余步骤。在无法进行交互式会话的主机上，请改用手动步骤。如果拥有所有者角色的人员已创建环境并将其密钥交给您，也请使用手动步骤，因为引导式设置需要以所有者身份登录。

<h3 id="run-the-guided-setup">
  运行引导式设置
</h3>

引导式设置会引导您在管理 UI 中创建环境、使用您保存的密钥文件启动本地运行器、确认运行器已注册，并将速查表写入 `./runner-setup/CHEAT-SHEET.md`。运行之前，请确认您的登录状态和版本：

* **登录**：在您已使用拥有所有者角色的帐户通过 `claude auth login` 登录的机器上运行它。如果仅使用 API 密钥或第三方模型提供商，会话虽然会启动，但其组织检查会失败。
* **版本**：确认[版本检查](#software-on-the-runner-host)已通过。在 2.1.224 之前的版本上，此设置命令会启动一个 Claude 会话，并将这些词作为提示词，而不是启动引导式设置。

要启动引导式设置，请在 shell 中运行设置子命令并按照提示进行操作：

```bash theme={null}
claude self-hosted-runner setup
```

设置本身不会启动测试会话：它会提示您在 claude.ai/code 启动一个。设置的最后一步会停止它所启动的运行器。如果您在该步骤之前退出设置，运行器将继续运行。要在最后一步之后继续，请在 shell 中使用 `./runner-setup/CHEAT-SHEET.md` 中的命令再次启动运行器，然后[将会话路由到环境](#route-a-session)。

<h3 id="set-up-manually">
  手动设置
</h3>

在 claude.ai 上创建环境，从主机上的终端启动运行器，然后返回 claude.ai 确认运行器出现并将会话路由到它。如果拥有所有者角色的人员已创建环境并将其密钥交给您，请从第 2 步开始。

<Steps>
  <Step title="创建环境">
    转到管理设置中的[**Cloud environments** 页面](https://claude.ai/admin-settings/cloud-environments)。在 **Self-hosted environments** 下，选择 **New**，命名环境，然后选择 **Create**。在向导的第二步，选择 **Copy environment key** 以复制环境密钥，管理 UI 将其标记为环境密钥。claude.ai 仅显示一次密钥，您之后无法检索它；它在创建后 365 天过期。环境的 `ccpool_...` ID 在其详细信息对话框中保持可见；您需要它用于[令牌验证](/docs/zh-CN/self-hosted-environments-identity)中的 `aud` 检查，以及用于从 CI [分派测试会话](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)。

    如果您丢失了密钥或需要轮换它，请从环境的 **Configuration** 选项卡创建新密钥，将新密钥推出到您的运行器，然后撤销旧密钥。持有已撤销密钥的运行器在其下一次经过身份验证的轮询时失败并退出，记录 `poll auth failed`，您的编排器使用新密钥重新启动它们。
  </Step>

  <Step title="启动运行器">
    创建密钥目录。此命令和下一条命令使用 `/etc/claude`，这需要 root 权限，并且它们创建的密钥文件仅可由运行这些命令的用户读取。如果运行器将以其他用户身份运行，它会退出并显示 `error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>')`。在这种情况下，请以运行器的用户身份运行这两条命令，并使用该用户可写入的目录代替 `/etc/claude`，同时将相同的路径传递给 `--environment-secret-file`。运行器进程可以读取的任何路径都有效。

    ```bash theme={null}
    mkdir -p /etc/claude
    ```

    将环境密钥写入文件。下面的命令从您的终端读取，以便密钥保持在 shell 历史记录之外：粘贴您复制的值，按 Enter，然后按 Ctrl-D，子 shell 的 `umask` 使文件仅可由其所有者读取。

    ```bash theme={null}
    (umask 077 && cat > /etc/claude/environment-secret)
    ```

    选择一个基目录，将下面运行器命令中的 `<writable-dir>` 替换为运行器可以写入或创建的绝对路径。运行器在启动时创建目录，然后检查存储库并在其下创建每个会话的目录。没有 `--base-dir`，它使用 `/workspace`，这仅在该目录已存在且可写或您以 root 身份启动运行器时有效。

    如果运行器无法创建或写入路径，它在启动时以命名目录的错误退出，而不是注册。请参阅[故障排除](/docs/zh-CN/self-hosted-environments-deploy#troubleshooting)。

    然后使用 `--environment-secret-file` 和 `--base-dir` 启动运行器：

    ```bash theme={null}
    claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'
    ```

    运行器向您的环境注册后会记录 `Registered: runner_id=<runner-id>`，然后开始轮询工作。如果运行器之后退出，请手动重新启动它。有关何时会发生这种情况，请参阅[如果运行器退出](#if-the-runner-exits)。
  </Step>

  <Step title="验证运行器出现">
    返回[**Cloud environments** 页面](https://claude.ai/admin-settings/cloud-environments)。您的环境状态在运行器启动后几秒内从 **No runners deployed** 更改为 **Healthy**；打开环境并选择 **Activity** 以查看运行器本身。如果您无权访问管理页面，上一步运行器日志中的 `Registered: runner_id=<runner-id>` 行可提供相同的信号。
  </Step>

  <Step title="将会话路由到环境">
    <span id="route-a-session" />在 claude.ai/code 启动会话，并从环境选择器中选择您的环境，其中自托管环境与 Anthropic 托管的环境一起出现。对于仓库，请选择[前提条件](#host-and-network)中的仓库：公共仓库，或此主机已可以克隆的仓库。运行器使用主机已有的任何 git 凭据进行克隆。

    下一个可用的运行器拾取排队的会话并记录 `Picked up session <session-id>` 以及其活跃计数和容量，因此您可以从运行器自己的输出中确认哪个主机接收了会话。在 [claude.ai/code](https://claude.ai/code) 观看会话工作并阅读 Claude 的回复。

    如果会话没有开始工作，请对照您看到的情况：

    * **会话保持排队状态**：请参阅[故障排除](/docs/zh-CN/self-hosted-environments-deploy#troubleshooting)。
    * **会话因 git 错误而无法启动**：错误会显示在会话和运行器的日志中。如果错误包含 git 的 `could not read Username for`，后跟您的 git 主机的 URL，则说明运行器没有该主机的 HTTPS 凭据。请参阅[配置 git](/docs/zh-CN/self-hosted-environments-deploy#configure-git)，其中还介绍了生产环境中私有仓库的凭据选项。
  </Step>
</Steps>

<h3 id="if-the-runner-exits">
  如果运行器退出
</h3>

如果运行器在本快速入门期间退出，请使用相同的命令再次启动它。运行器可能会自行退出：

* **会话已完成**：日志显示 `[runner:exit] account workload drained — exiting`。运行器在其活跃会话完成后按设计退出。请参阅[运行器生命周期](/docs/zh-CN/self-hosted-environments#runner-lifecycle)。
* **失去联系**：日志显示一行包含 `runner record gone server-side` 或 `poll auth failed` 的 `[runner:fatal]`。如果运行器与 Anthropic 失去联系一段时间（例如因为主机休眠），它可能会在下次连接到 Anthropic 时退出。

一个轮次结束并不会结束您的测试会话。第一轮之后，会话仍处于连接状态，运行器也仍在运行，因此您可以[向会话发送后续消息](#send-a-follow-up-message-to-a-running-session)，而无需先重新启动运行器。

对于生产，在编排器下部署运行器，该编排器在退出时重新启动它，并在运行器启动后立即继续退出时等待更长的时间再重新启动。请参阅[部署到生产环境](/docs/zh-CN/self-hosted-environments-deploy)和[当运行器退出时](/docs/zh-CN/self-hosted-environments-deploy#when-the-runner-exits)。

<h2 id="send-a-follow-up-message-to-a-running-session">
  向运行中的会话发送后续消息
</h2>

一旦会话在您的环境上运行，从任何您使用 `claude auth login` 登录的机器上的 `claude` CLI 向其发送后续消息；该命令不需要从启动会话的机器运行。该命令发布一条消息：

```bash theme={null}
claude -p "your message" --cloud <session-id>
```

对于 `<session-id>`，传递裸 `session_...` 或 `cse_...` ID 或会话的 claude.ai/code URL。成功发送打印 `Sent to cloud session.` 以及会话 ID 和查看链接。接受的 ID 形式、JSON 输出以及帐户和策略要求在[从 CLI 发送后续消息](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli)上，因为该命令对 Anthropic 托管的会话的工作方式相同。

<h2 id="what’s-next">
  接下来的步骤
</h2>

* [部署到生产环境](/docs/zh-CN/self-hosted-environments-deploy)：强化部署、控制出口、配置 git 凭证，并在 Kubernetes 或 Compose 下运行部队
* [自定义会话](/docs/zh-CN/self-hosted-environments-configuration)：包装脚本、生命周期钩子、按需运行器、MCP 服务器和权限
* [端到端测试](/docs/zh-CN/self-hosted-environments-testing)：一个 CI 烟雾测试，分派会话并读取 Claude 的回复