本页面是您在自托管环境中运行的两个进程的参考：运行器，它在您的主机上执行 Claude Code 云会话，以及可选的自动扩展编排器，它在会话队列时启动运行器。每个都有自己的标志表。两者都在 Linux 或 macOS 主机上运行，默认值如
/workspace 和 ~/.claude 假设。运行 claude self-hosted-runner --help 以获取已安装版本上的权威列表。
指标系列和一些 API 字段仍然使用 pool 来表示这些页面所称的环境；两个术语都指同一事物。环境 ID 是 pool_id 字段，形式为 ccpool_...：无论这些页面在哪里显示 pool 标识符，它都命名环境。CLI 标志和环境变量将其拼写为 environment，例如 --environment-secret-file；已弃用的 pool 拼写仍然有效，如--environment-secret-file 行所述。
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 无上限。超过上限的行为因表面而异：
- 标志：启动失败并出现错误。
- 环境变量：运行器将值夹紧到计时器上限，而不是拒绝它。
自动模式规则列表
--server-auto-mode-lists 让您决定来自运行器外部的哪些自动模式分类器规则可以到达您的运行器上的会话。Anthropic 的控制平面可以随会话发送规则列表，并要求运行器应用它们。其中某些条目可能是您组织的管理员编写的规则。这些列表是 environment、soft_deny 和 allow：
environment：条目既可以让分类器允许更多操作，也可以让其允许更少操作。soft_deny：条目会阻止某个操作，除非用户明确要求执行该操作，或者适用某个allow例外。allow：soft_deny条目的例外。
no-allow：默认值。应用environment和soft_deny，不应用allow。environment条目仍然可以让分类器允许更多操作，因此默认值并不能排除所有放宽。all：应用全部三个列表。none：不应用其中任何列表。选择none可排除来自这些列表的所有放宽。它也会丢弃soft_deny限制。
--log-level debug 启动运行器。随后，运行器会为每个会话记录一行包含 the server asked this runner to apply 的日志，或一行包含 the server did not ask this runner to apply the auto mode lists it sends 的日志。
Orchestrator CLI 标志
self-hosted-runner orchestrator 子命令（生成按需运行器）接受 --api-url、--environment-secret-file、--hooks-dir、--health-port 和 --log-level，与运行器具有相同的默认值，以及运行器的标志具有的相同环境变量（除了 --hooks-dir 是必需的，必须包含 spawn-runner 钩子）。它还采用自己的标志：
SCM 连接器标志
SCM 连接器不可用，因此请将本部分中的标志保持未设置。如果您设置--scm-connector-host，连接不会打开，编排器会继续重试。运行器仍然作为会话队列启动。
连接器是从编排器到 Anthropic 控制平面的常设 WebSocket 连接。它的设计目的是让托管的预会话流（例如存储库选择器和分支或 ref 解析器）能够到达仅从您的网络内部可路由的 GitHub Enterprise Server 主机。请参阅 GitHub Enterprise Server 页面上的网络要求，了解这些流需要什么。
在每次连接尝试时，编排器发送其现有的环境密钥，并使用指数退避自动重试，上限为 30 秒加抖动。
仅环境变量设置
这些运行器设置仅从环境读取，涵盖大多数部署保留在默认值的行为：遥测
会话子进程向 Anthropic 发送操作遥测，除非您关闭它。不发送代码或存储库内容。在运行器进程上设置遥测变量；运行器在应用服务器提供的环境变量后重新声明它们，因此操作员的设置始终优先。 一个控制特定于自托管环境：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 的分析。
健康端点
运行器在配置的健康端口上提供GET /healthz。只要进程活跃，响应就是 200 OK，无论轮询循环处于什么状态，因此此端点上的 HTTP 探针仅检测死进程。JSON 正文描述当前状态：
last_poll_age_ms 作为活跃信号；无限增长的值表示轮询循环卡住。last_poll_at 和 last_poll_age_ms 都是 null，直到第一次轮询完成。
编排器在其健康端口上提供自己的 /healthz。其端点始终返回 200，正文携带报告最近一次轮询是否成功的 connected 字段，加上 queue_counts 中的每个状态生成队列计数。在自定义探针中使用 connected 而不是状态代码来控制就绪和警报。
当SCM 连接器被配置时，编排器的 /healthz 正文也携带 scm_connector_connected 和一个 scm_connector 对象，包含 connected、last_connected_at、last_error、reconnects 和 requests_forwarded。当未设置 --scm-connector-host 时，两个字段都是 null。
Prometheus 指标
每个运行器在与/healthz 相同的端口上的 GET /metrics 处提供 Prometheus 指标。关键系列：
编排器在与其
/healthz 相同的端口上的 GET /metrics 处提供自己的系列：
对于自动扩展，选择与您的扩展风格匹配的系列，并在将其馈送到扩展器之前对其进行门控：
- 队列深度扩展：将
claude_code_self_hosted_orchestrator_pool_pending_sessions馈送到您的 HPA 或 KEDA 扩展器，而不是queue_pending_sessions。 - 容量扩展：按运行器的
active_sessions与capacity的比率进行扩展。 - 在
connected上门控：使用claude_code_self_hosted_orchestrator_connected == 1按实例过滤查询，以便断开连接的副本的陈旧值不会馈送到扩展器。
ignoreNullValues: "true" 处将空结果读取为零并缩小；在 ScaledObject 上设置 ignoreNullValues: "false"，可选择使用 fallback 副本下限。
以下 Prometheus Operator PodMonitor 涵盖两个进程。它通过 app.kubernetes.io/part-of: claude-code-self-hosted-runner 标签和Kubernetes 配方设置的命名 health 端口选择 pod；调整命名空间以匹配您的部署：
传递会话子进程指标
每个会话在其自己的子进程中运行，具有自己的 OpenTelemetry 指标；在--capacity 高于 1 时，运行器重写这些子指标的公开方式。在运行器主机上设置 OTEL_METRICS_EXPORTER=prometheus 和会话环境中的 CLAUDE_CODE_ENABLE_TELEMETRY=1（例如从您的包装脚本或运行器自己的环境，会话继承），重新公开每个子进程的计数器和仪表工具在运行器自己的 /metrics 端点上，与运行器的系列一起。运行器将子进程的导出器重写为通过 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自行退出、会话在子进程仍连接时被存档或删除，以及运行器干净地交还槽：在空闲超时、退休时间或--kill-session-after-min限制处释放会话；启动超时；或轮询循环在子进程退出前注意到的服务器端取消分配。增加sessions_completed_total。failed：子进程以非零代码自行退出，要么是崩溃，要么是生成后的设置失败。增加sessions_failed_total。interrupted：运行器因既不是会话成功也不是运行器故障的操作原因终止子进程，例如排空，或终止在SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS宽限期结束时仍在运行器上的会话，在其--kill-session-after-min限制之后。Kubernetes 滚动重启发送SIGTERM是排空的一个示例。增加sessions_interrupted_total。
--kill-session-after-min 限制的每个会话，并在 sessions_interrupted_total 中计数。
post-session 钩子的 CLAUDE_RUNNER_EXIT_REASON 以不同方式分类干净交接。钩子将以下情况报告为 interrupted，因为运行器停止了子进程：释放、启动超时、服务器取消分配，以及轮询先注意到的存档或删除。这些计数器记录与 completed 相同的事件，因为槽被干净地交还。
如果您直接根据 sessions_completed_total 协调钩子收据，您会低估完成。对每个会话保证使用钩子，对聚合速率使用计数器。
在一次性环境中，--capacity 1 与默认 --drain-grace-sec 0，每个运行器进程在其一个会话结束后片刻退出。sessions_completed_total、sessions_failed_total 和 sessions_interrupted_total 仅在会话结束时增加，在该退出之前，因此每 15 到 60 秒轮询一次 Prometheus 很少在运行器的系列消失前捕获增加；这三个会话结束计数器是本节其余部分所指的终端计数器。sessions_started_total 在生成时增加并在会话的生命周期内保持可见，因此它可靠地显示，但在一次性环境中它读取更接近”当前运行的会话”而不是累积计数。
对应目标使用此表中的系列而不是终端计数器：
orchestrator_* 行仅存在于运行按需编排器的环境中。在固定舰队上，其运行器以 --drain-grace-sec 高于 0 的方式超过其会话，对吞吐量使用 sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m]))；在一次性舰队上，该系列与终端计数器具有相同的抓取窗口问题，因此依赖排队会话计数。在环境的活动选项卡上检查积压，在云环境管理页面上：运行器不导出队列深度系列。
对于每个会话结果报告，改为使用 post-session 钩子：它在每个会话结束处触发，其中生成了子进程，除了突然的运行器终止（例如 VM 抢占），根据钩子自己的合同。