自托管环境快速开始

自托管环境在你的组织运营的基础设施上运行 Claude Code 云端会话，由你部署的 runner 进程执行。本快速开始搭建最小可用的第一个：一台主机上一个 runner，运行一个测试会话。结束时你会在 Cloud environments 管理页有一个环境、一个轮询工作的 runner，以及在你主机上运行的会话。连接真实仓库或内部系统之前，先读「部署到生产」（安全加固等）。该功能处于 Team 和 Enterprise 的公开 beta。

前提

组织和角色：Owner 在 Cloud environments 管理页打开 Allow self-hosted environments（打开前 New 按钮不出现；没有该角色的人可以请有的人创建环境并把密钥交给你）；组织要有 GitHub 连接，开发者启动会话时才能选仓库。

主机和网络：runner 主机需要 Linux 或 macOS 主机或容器，能出站 HTTPS 访问 api.anthropic.com、claude.ai（及安装步骤重定向到的下载主机）和你的 git 主机；Windows 不支持。时钟要与真实时间同步（如 NTP），时钟偏差超过五分钟认证会失败。

runner 主机上的软件：Claude Code v2.1.224 或更高版本（runner 是标准 claude 二进制的一部分，更早的版本不认识 self-hosted-runner 子命令）；Git 2.24 或更新（部署页的一些 git 选项需要更新的版本）。确认主机就绪：

claude self-hosted-runner --help

就绪的主机会打印 runner 的用法文本，列出 --environment-secret-file 等标志；旧于 2.1.224 的版本会打印通用的 claude --help，用 claude update 升级。

设置环境和 runner

Claude Code 带有引导式设置：一个交互式 Claude Code 会话，带你在管理界面创建环境、用你保存的密钥文件启动本地 runner、确认 runner 注册成功，并写一份速查表：

claude self-hosted-runner setup

手动设置：

1. 在管理设置的 Cloud environments 页，Self-hosted environments 下选 New，给环境命名并选 Create。向导第二步选 Copy environment key 复制环境密钥（只显示一次）。密钥丢失或需要轮换时，在环境的 Configuration 标签页创建新密钥，推行到你的 runner，再撤销旧的；持有已撤销密钥的 runner 在下次认证轮询时失败并退出

2. 创建密钥目录并写入环境密钥文件（命令从终端读取，让密钥不进 shell 历史；umask 让文件只有所有者可读）：

   mkdir -p /etc/claude
   (umask 077 && cat > /etc/claude/environment-secret)

3. 选择基础目录，把下面命令里的 <writable-dir> 换成 runner 能写或创建的绝对路径；runner 在启动时创建该目录，然后在其下检出仓库并创建每会话目录。runner 无法创建或写入该路径时，会在启动时以点名该目录的错误退出，而不是注册

4. 用 --environment-secret-file 和 --base-dir 启动 runner，它向你的环境注册并开始轮询工作：

   claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

5. 回到 Cloud environments 页，环境状态在 runner 启动后几秒内从 No runners deployed 变成 Healthy；打开环境选 Activity 可以看到 runner 本身

6. 在 claude.ai/code 启动会话，从环境选择器里选你的环境（自托管环境与 Anthropic 托管环境一起出现）。runner 用主机上已有的 git 凭据克隆，所以选一个该主机能克隆的仓库

runner 按设计在其活动会话结束后退出（见「自托管环境」的 runner 生命周期）；生产环境下，把它部署在会在其退出时重启它、并在 runner 启动后立即反复退出时拉长重启间隔的编排器之下。

给运行中的会话发后续消息

会话在你的环境上运行后，可以从任何用 claude auth login 登录的机器上的 claude CLI 给它发后续消息（命令不需要在启动会话的机器上运行），命令发送一条消息：

claude -p "your message" --cloud <session-id>

<session-id> 传裸的 session_... 或 cse_... ID，或会话的 claude.ai/code URL。发送成功时打印 Sent to cloud session. 以及会话 ID 和查看链接。

接下来

部署到生产（加固部署、控制出口、配置 git 凭据、在 Kubernetes 或 Compose 下运行 runner 集群）；自定义会话（包装脚本、生命周期 hooks、按需 runner、MCP 服务器和权限）；端到端测试（派发会话并读取 Claude 回复的 CI 冒烟测试）。这些以官方原文为准。