自託管環境在 Team 和 Enterprise 方案上處於公開測試版；擁有者可以在 Cloud environments 管理頁面上開啟 Allow self-hosted environments 來啟用它們。本頁面是旗標和指標參考；請參閱 快速入門以了解設定，以及 部署到生產環境以了解艦隊配方。
/workspace 和 ~/.claude 假設。執行 claude self-hosted-runner --help 以取得您已安裝版本上的權威清單。
指標序列和一些 API 欄位仍然使用 pool 來表示這些頁面所稱的環境；兩個術語都命名相同的東西。環境 ID 是 pool_id 欄位，形式為 ccpool_...：無論這些頁面在何處顯示 pool 識別碼，它都命名環境。CLI 旗標和環境變數將其拼寫為 environment，例如 --environment-secret-file；已棄用的 pool 拼寫仍然有效，如 --environment-secret-file 列所述。
執行器 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 的日誌。
協調器 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 連線。它的設計目的是讓託管的預工作階段流程（例如存放庫選擇器和分支或參考解析器）能夠到達只能從您的網路內部路由的 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 hook的 CLAUDE_RUNNER_EXIT_REASON 以不同方式分類乾淨交接。hook 將這些情況報告為 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 搶佔），根據掛鉤自己的合約。