自托管环境：runner 参考

自托管环境目前处于 Team 和 Enterprise 套餐的公开测试阶段，由 Owner 在 Cloud environments 管理页打开 Allow self-hosted environments。本页是你在自托管环境里运行的两个进程的参考：runner（在你的主机上执行 Claude Code 云端会话）和可选的自动伸缩编排器（会话排队时启动 runner）。两者都运行在 Linux 或 macOS 主机上（/workspace、~/.claude 等默认值基于此）。以你安装版本的 claude self-hosted-runner --help 为权威列表。

指标序列和少数 API 字段里仍用 pool 指代本文所说的环境，两者是同一个东西：环境 ID 是形如 ccpool_... 的 pool_id 字段；CLI 标志和环境变量则拼作 environment（如 --environment-secret-file），已弃用的 pool 拼写仍可用。

Runner CLI 标志

多数标志有对应的环境变量；两者都设时以标志为准。时长类标志在 CLI 上用分钟或秒，但配对的环境变量始终是毫秒（带 _MS 后缀），「默认」列显示的是标志的单位：--exit-if-unused-min 10 等价于 SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000；而 Helm 值 SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" 表示 15 毫秒，不是默认的 15 分钟。

多数时长标志有上限，取值是为了让每个超时都在运行时 32 位计时器上限（约 24.85 天）之内：--*-min 标志上限 10080 分钟（7 天）；--drain-grace-sec 上限 604800 秒（同为 7 天）；--drain-wait-sec 上限 86400 秒（24 小时）；--session-stop-grace-sec 和 --post-session-hook-timeout-sec 没有上限。超出上限时各接口行为不同：标志启动失败并报错；环境变量则由 runner 钳到计时器上限，而不是拒绝。

编排器 CLI 标志

self-hosted-runner orchestrator 子命令负责生成按需 runner，接受 --api-url、--environment-secret-file、--hooks-dir、--health-port 和 --log-level，默认值与 runner 相同，并且在 runner 的标志有对应环境变量时，用同样的环境变量；不同的是 --hooks-dir 必填且必须包含 spawn-runner hook。它还有自己的标志：

SCM 连接器标志

SCM 连接器目前不可用，所以不要设置本节的标志。设了 --scm-connector-host 连接不会打开，编排器会一直重试；runner 仍会随会话排队而启动。连接器是编排器到 Anthropic 控制平面的常驻 WebSocket 连接，设计目的是让托管的会话前流程（如仓库选择器和分支/引用解析器）能到达只在你网络内可路由的 GitHub Enterprise Server 主机。

每次连接尝试时，编排器发送它已有的环境密钥，并以指数退避自动重试，上限 30 秒加抖动。

仅环境变量的设置

这些 runner 设置只从环境读取，涉及大多数部署保持默认的行为：

遥测

会话子进程会向 Anthropic 发送运营遥测，除非你关掉；不发送代码或仓库内容。要在 runner 进程上设遥测变量；runner 在应用服务端提供的环境变量之后会重新断言它们，所以运营者的设置总是优先。

自托管环境特有的一个控制是 CLAUDE_CODE_BYOC_ENABLE_DATADOG=1，它选择加入 Datadog 运营指标，该指标在自托管环境里默认关闭。通用的 Claude Code 遥测控制 DISABLE_TELEMETRY、DO_NOT_TRACK、DISABLE_ERROR_REPORTING 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 适用于会话子进程，如环境变量参考所述。DISABLE_GROWTHBOOK 相关但不同：设 DISABLE_GROWTHBOOK=1 禁用的是功能标志获取，除非同时设了 DISABLE_TELEMETRY，遥测仍然开着。CLAUDE_CODE_ENABLE_TELEMETRY 与此无关：它启用到你自己收集器的 OpenTelemetry 导出，并不控制 Anthropic 的分析。

健康端点

runner 在配置的健康端口上提供 GET /healthz。只要进程存活，不论轮询循环处于什么状态都返回 200 OK，所以对该端点的 HTTP 探测只能发现进程已死。JSON 正文描述当前状态：

{
  "status": "ok",
  "runner_id": "ccrunner_...",
  "active_sessions": 2,
  "last_poll_at": "2026-03-31T18:04:11.220Z",
  "last_poll_age_ms": 842
}

在自定义探测里把 last_poll_age_ms 当作存活信号；它无限增长说明轮询循环卡住了。第一次轮询完成前，last_poll_at 和 last_poll_age_ms 都是 null。

编排器在它的健康端口上有自己的 /healthz，总是返回 200，正文里的 connected 字段报告最近一次轮询是否成功，queue_counts 给出按状态的生成队列计数；就绪判断和告警要基于 connected 而不是状态码。配置了 SCM 连接器时，编排器的 /healthz 正文还带有 scm_connector_connected 和一个含 connected、last_connected_at、last_error、reconnects、requests_forwarded 的 scm_connector 对象；没设 --scm-connector-host 时两者都是 null。

Prometheus 指标

每个 runner 在与 /healthz 同一端口的 GET /metrics 提供 Prometheus 指标。主要序列：

编排器在与其 /healthz 同一端口的 GET /metrics 提供自己的序列：

自动伸缩时，选与你的伸缩方式匹配的序列，并在喂给伸缩器之前加门控：按队列深度伸缩把 claude_code_self_hosted_orchestrator_pool_pending_sessions（不是 queue_pending_sessions）喂给 HPA 或 KEDA；按容量伸缩用 runner 的 active_sessions 与 capacity 之比；用 connected 门控，对每个实例用 claude_code_self_hosted_orchestrator_connected == 1 过滤查询，使已断开副本的陈旧值不会喂给伸缩器。整个轮询中断（所有副本都断开）期间，门控后的查询返回无数据：HPA 在指标缺失时保持当前副本数，但 KEDA 的 Prometheus 伸缩器在默认的 ignoreNullValues: "true" 下把空结果读作零并缩容，所以要在 ScaledObject 上设 ignoreNullValues: "false"，可选地再配一个 fallback 副本下限。

下面的 Prometheus Operator PodMonitor 覆盖两个进程，它按 app.kubernetes.io/part-of: claude-code-self-hosted-runner 标签和 Kubernetes 配方设置的命名端口 health 选 pod，按你的部署调整命名空间：

# Claude Code 自托管 runner + 编排器的 Prometheus Operator PodMonitor 示例。
# 按你的部署调整命名空间和标签选择器。runner 与编排器都在各自的
# --health-port（默认 8080）上提供 /metrics。
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # 匹配 Kubernetes 配方里的 runner Deployment，以及你以同样方式打标签、
      # 并给了名为 'health' 的 containerPort 的按需 runner Job 和编排器 pod。
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

下面的告警规则只是起点，阈值要按机队规模调整：

# Claude Code 自托管 runner + 编排器的 Prometheus 告警规则示例。
# 按机队规模和 SLO 调整阈值。
groups:
  - name: claude-code-self-hosted-runner
    rules:
      - alert: ClaudeRunnerPollStale
        expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }} has not polled in >60s"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Runners are running mixed versions"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: >3 session init failures in 10m (checkout hook / git / token / pre-init crash)"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: PollWork failing ({{ $value | humanize }}/s over 5m)"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: >3 SessionStart hook failures in 10m"
  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} cannot reach the Anthropic control plane"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} has not polled in >90s (poll loop waits on hook execution)"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "{{ $value }} sessions circuit-broken — spawn-runner hook is repeatedly non-retryable; fix infra then retry from the Activity tab"
      - alert: ClaudeOrchestratorPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }}: PollSpawnHints failing ({{ $value | humanize }}/s over 5m)"
      - alert: ClaudeOrchestratorSpawnHookFailing
        expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }}: >3 spawn-runner hook failures in 5m"

透传会话子进程指标

每个会话运行在自己的子进程里，有自己的 OpenTelemetry 指标；--capacity 大于一时，runner 会重写这些子进程指标的暴露方式。在 runner 主机上设 OTEL_METRICS_EXPORTER=prometheus、并在会话环境里设 CLAUDE_CODE_ENABLE_TELEMETRY=1（例如来自你的包装脚本或 runner 自己的环境，会话会继承），就会把每个子进程的计数器和仪表指标重新暴露在 runner 自己的 /metrics 端点上，与 runner 的序列并列。runner 把子进程的导出器改写为向健康端口上仅限环回的接收器经 OTLP 推送，给每个序列打上 session_id 和 client_platform 标签，并在会话结束后清除它的序列。默认的 --capacity 1 下不做这种重写：会话子进程照常在端口 9464 上绑定自己的 Prometheus 端点。

会话生命周期计数器语义

sessions_started_total、sessions_completed_total、sessions_failed_total、sessions_interrupted_total 按会话如何结束来分类。每个生成的会话子进程在生成时让 sessions_started_total 加一，退出时另外三个中恰好一个加一，所以 sessions_started_total 减去另外三者之和等于当前正在运行的会话子进程数。

• completed：会话干净结束。涵盖子进程自己以代码 0 退出、子进程仍连接时会话被归档或删除，以及 runner 干净地交还槽位：在空闲超时、退休时间或 --kill-session-after-min 限制处释放会话、启动超时，或在子进程退出前轮询循环注意到的服务端取消分配。
• failed：子进程自己以非零代码退出，崩溃或生成后的设置失败。
• interrupted：runner 因运营原因终止子进程，既不是会话成功也不是 runner 故障，如排空，或终止在其 --kill-session-after-min 限制后的 SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS 宽限窗口结束时仍在 runner 上的会话。Kubernetes 滚动重启发出 SIGTERM 就是排空的一个例子。

v2.1.260 之前，runner 终止每个达到 --kill-session-after-min 限制的会话，并把它计入 sessions_interrupted_total。post-session hook 的 CLAUDE_RUNNER_EXIT_REASON 对干净交还的分类不同：hook 把释放、启动超时和服务端取消分配报告为 interrupted，因为是 runner 停了子进程；而这些计数器把同样的事件记为 completed，因为槽位是被干净交还的。直接拿 hook 回执去对账 sessions_completed_total 会少算完成数。每会话的保证用 hook，聚合速率用计数器。

在一次性（one-shot）环境，即 --capacity 1 且默认 --drain-grace-sec 0 时，每个 runner 进程在它唯一的会话结束后很快退出。sessions_completed_total、sessions_failed_total、sessions_interrupted_total 只在会话结束、退出之前增加，所以每 15 到 60 秒一次的 Prometheus 抓取很少能在 runner 的序列消失前抓到这次增加（这三个会话结束时的计数器就是本节所说的终态计数器）。sessions_started_total 在生成时增加并在会话期间一直可见，所以可靠地出现，但在一次性环境里它更接近「当前运行的会话」而不是累计吞吐。下表给出对应目标该用的序列：

orchestrator_* 行只存在于运行按需编排器的环境。在 runner 比会话活得久（--drain-grace-sec 大于 0）的固定机队上，吞吐用 sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m]))；在一次性机队上该序列有与终态计数器相同的抓取窗口问题，所以改靠排队会话数。积压要在 Cloud environments 管理页上该环境的 Activity 标签页查看：runner 不导出队列深度序列。要做每会话结果报告，用 post-session hook：除 VM 被抢占这类 runner 突然终止外，它在每个生成了子进程的会话结束时触发，这是 hook 自己契约的一部分。