Claude Code 自托管环境实战：把云端会话跑到你自己的机器上（2026）

Claude Code 的自托管环境（self-hosted environments）是一种部署模式：云端发起的编码会话由你自己机器上的 runner 进程执行——代码检出、构建、密钥全部留在你的基础设施里，Anthropic 只托管控制面。2026 年 8 月 7 日随 v2.1.224 进入 public beta，官方文档仍在快速演进。本文基于 2026 年 9 月的官方文档，覆盖概念模型、从零到第一个会话的完整步骤、生产部署要点与安全边界。

TL;DR

• 三个概念：Environment（命名 runner 组）、Runner（你机器上的常驻进程）、Session（一次任务）
• 控制面在 Anthropic，连接全部由 runner 出站 HTTPS 发起——不开放任何入站端口
• 上手四步：claude self-hosted-runner setup → 存 environment key → 启动 runner → claude.ai/code 里选环境
• 代码、构建产物、密钥不出你的机器；模型流量也不能改走 Bedrock / Vertex / LLM 网关
• 生产部署用官方 Kubernetes / Compose 配方，靠 --drain-grace-sec 控制排水

概念模型：Environment、Runner、Session

三个角色各司其职：

| 概念 | 是什么 | 类比 | |---|---|---| | Environment | 一个命名的 runner 组，在 claude.ai 管理页创建 | CI 里的 runner fleet | | Runner | 跑在你主机上的常驻进程，认领并执行会话 | self-hosted CI runner | | Session | 一次具体的编码任务，由 web/desktop 发起 | 一次 CI job |

和 GitHub Actions 上跑 Claude Code 自动化的关键区别：那是事件驱动的无状态 job（PR 触发、跑完即销毁），而自托管环境承载的是可交互的长会话——你在 claude.ai/code 里发起，会话路由到你的 runner，中途可以随时从手机或网页继续。会话结束后磁盘状态按配置保留或重置。

控制面由 Anthropic 托管，但所有连接都由 runner 侧出站发起（HTTPS），Anthropic 不会反向连进你的网络——这是整个安全模型的基点。

快速上手：从零到第一个会话

前置：Claude Code ≥ v2.1.224。先确认二进制支持 runner 子命令：

claude self-hosted-runner --help
# 若打印的是通用 claude --help，先升级：
claude update

第一步：创建 Environment。 在 claude.ai 的 Cloud environments 管理页，Self-hosted environments 下选 New，命名并创建；在向导第二步 Copy environment key——这个 secret 只显示一次，365 天后过期。

第二步：把 key 存到 runner 主机。

mkdir -p /etc/claude
(umask 077 && cat > /etc/claude/environment-secret)
# 粘贴 key，回车，Ctrl-D 结束

umask 077 保证文件只有当前用户可读——这是官方文档给出的原样做法，别省。

第三步：启动 runner。

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<可写目录>'

几秒内回到管理页，环境状态应从 "No runners deployed" 变为 Healthy。

第四步：路由第一个会话。 在 claude.ai/code 发起会话，environment 选择器里挑你的环境；runner 日志出现 Picked up session <session-id> 即接单成功。之后甚至能从本地 CLI 给会话追加消息：

claude -p "你的消息" --cloud <session-id>

懒人路线：直接跑 claude self-hosted-runner setup，向导会带你走完上面全程。

生产部署：从单机到编排

单机 runner 适合验证；生产要考虑生命周期与扩缩。官方 deploy 文档给了 Kubernetes 与 Docker Compose 两套原生配方，要点三个：

镜像与版本固定。 runner 镜像里把 Claude Code 版本 pin 住，避免环境漂移；预热常用的仓库 checkout 可以显著缩短会话启动时间。

排水与重启。 runner 生命周期用 --drain-grace-sec 控制：默认值 0 意味着收到停止信号后立即排水，Kubernetes 可以用全新磁盘重启 runner——无状态、可随缘重建。--retire-at <epoch-seconds> 让 runner 到点退役；--defer-shutdown-max-min（v2.1.238+）可以把关机推迟到会话边界。

自动扩缩。 官方支持跑一个 autoscaling orchestrator，按会话队列深度拉起 runner；不必自己写 HPA。

安全边界：什么在你机器上，什么不能改道

• 出站 only。 runner 到控制面全部出站 HTTPS；企业网络用 HTTPS_PROXY / NO_PROXY 接（支持 mTLS 与 Proxy-Authorization 头注入，v2.1.248+）。
• 数据停留。 checkout、构建产物、密钥留在你的机器；Anthropic 侧只有会话编排信息。
• 推理鉴权最小化。 runner 拿到的是 session 级 OAuth token，只用于推理调用。
• 模型流量不可改道。 自托管环境的模型调用不能路由到 Bedrock、Vertex、Agent Platform、Foundry 或自建 LLM 网关——这是当前版本的硬边界，做合规评估时要写进结论。
• Git 凭据四种方案（含 per-session 现签凭据与 Anthropic git proxy），按你 git host 的形态选，别把长期 PAT 塞进 runner。

常见坑

坑 1：self-hosted-runner 子命令不存在。 老版本会静默打印通用 help。先 claude update，v2.1.224 才有这个子命令。

坑 2：environment key 丢了。 只显示一次、365 天过期。丢了就重新生成，注意轮换时所有 runner 都要换新 key。

坑 3：runner 一直不 Healthy。 出站被企业防火墙拦是最常见原因——按 deploy 文档核对代理与目标域名白名单；claude --debug 能看到 runner 侧握手日志。

坑 4：会话被 K8s 重启打断。 默认 --drain-grace-sec 0 是设计行为（新磁盘重启更干净），不是 bug；长会话主机要配 --defer-shutdown-max-min 等会话走完。

坑 5：想走自建模型网关。 做不到（见安全边界），别在采购流程里假设可以。

相关指南

• 基础先行：Claude Code 完全指南——安装、权限模式与日常工作流
• 事件驱动的无状态路线：Claude Code 接入 GitHub Actions
• 容器化跑 CLI 的另一条路与 container-use 等工具，见资源库
• 会话状态怎么看：Claude Code 状态栏完全指南

常见问题

自托管环境和在容器里直接跑 claude CLI 有什么区别？

容器里跑 claude -p 是你发起、你编排的一次性调用；自托管环境是 Anthropic 托管控制面、你提供算力的可交互会话——从 claude.ai/code 或手机发起、路由到你的 runner、中途可跨设备继续。前者适合 CI 步骤，后者适合把「云端 Claude Code 的体验」落到自己的基础设施上。

Runner 需要开放入站端口吗？

不需要。所有连接由 runner 出站发起（HTTPS），Anthropic 不会反向连入你的网络。这也是它和传统「暴露 webhook 的自托管方案」在安全模型上的核心差别。

environment secret 丢失或过期了怎么办？

在管理页重新生成并更新所有 runner 主机上的 /etc/claude/environment-secret。它只在创建时显示一次、365 天过期——把「到期轮换」写进日历，别等 runner 集体掉线才想起来。

会话的代码和密钥会经过 Anthropic 吗？

代码检出、构建产物和密钥都留在你的机器；Anthropic 控制面只处理会话编排。推理请求由 runner 出站发往模型 API，鉴权用 session 级 OAuth token。

模型流量能走我们的 Bedrock / Vertex 或自建 LLM 网关吗？

当前版本不能——自托管环境的模型调用被限制为 Anthropic 托管端点， Bedrock / Vertex / Foundry / LLM 网关路线都不支持。需要这条路线的场景请评估在容器里跑 CLI 的方案。

什么样的团队适合自托管环境？

两类最典型：合规要求数据不出内网的团队（出站-only 模型通常过得去安全评审），以及想在自有算力（含裸金属/GPU 机型）上跑云端会话体验的团队。如果只是想要 CI 里的 Claude，GitHub Actions 路线更简单。

官方参考资料

• Claude Code — Self-hosted environments（概念与安全模型）
• Claude Code — Self-hosted environments quickstart（本文命令依据）
• Claude Code — Self-hosted environments deploy（K8s / Compose 配方）
• Anthropic 官方博客 — Run Claude Code sessions on your own compute（public beta 公告）

本文基于截至 2026 年 9 月 2 日的公开文档（v2.1.251），该特性处于 public beta、演进很快，以官方文档为准。