SpyBara
Go Premium

self-hosted-environments-reference.md 2026-09-27 23:59 UTC to 2026-09-28 22:01 UTC

This page contains 7 additions and 7 deletions.

2026
Sat 12 03:02 Fri 18 23:58 Sat 19 23:57 Mon 28 22:59

自託管環境參考

自託管執行器和協調器的完整參考：CLI 旗標、環境變數和 Prometheus 指標。

本頁面是您在自託管環境中執行的兩個程序的參考：執行器在您的主機上執行 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 列所述。

執行器 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 分鐘的預設值。

旗標 環境變數 預設值 說明
--api-url <url> 無 https://api.anthropic.com API 基礎 URL。僅為測試覆蓋。
--base-dir <path> SELF_HOSTED_RUNNER_BASE_DIR /workspace；Windows 上無 用於存放庫簽出和每個工作階段工作目錄的目錄。執行器需要對此路徑或其父目錄的寫入存取。執行器在啟動時建立目錄，當無法建立或寫入時以 cannot create or write to base directory 退出。在 v2.1.225 之前，執行器在第一個工作階段啟動時建立目錄，因此無法使用的路徑會導致工作階段失敗而不是啟動失敗。在 Windows 上（不是支援的執行器主機），沒有預設值：除非您傳遞旗標或設定變數，否則執行器在啟動時退出。在環境中的每個執行器上使用相同的值。請參閱在執行器之間保持基礎目錄和容量相同。
--capacity <n> 無 1 此執行器處理的最大並行工作階段。所有工作階段都屬於同一個鎖定的擁有者。在環境中的每個執行器上使用相同的值；請參閱在執行器之間保持基礎目錄和容量相同。
--client-label <label> SELF_HOSTED_RUNNER_CLIENT_LABEL 主機的主機名稱 執行器在註冊時傳送的標籤。執行器也將其報告為 claude_code_self_hosted_runner_info 的 client_label 標籤。需要 Claude Code v2.1.248 或更新版本。
--configure-git SELF_HOSTED_RUNNER_CONFIGURE_GIT=1 關閉 在啟動時，寫入全域 git 身份、啟用 Anthropic 提交簽署、開啟 git push 協商，並安裝附加 Co-authored-by: 預告片的提交掛鉤。Push 協商需要 Claude Code v2.1.257 或更新版本。請參閱配置 git。
--confine-repo-settings <mode> SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS warn 設定防護的模式，當存放庫的已提交設定嘗試授予對該工作階段自己的工作區之外的寫入或讀取存取、設定環境變數或覆蓋操作員的沙箱或掛鉤姿態時，該防護會標記工作階段，例如 sandbox.enabled: false 或 disableAllHooks。預設 warn 記錄違規並仍然啟動工作階段，enforce 拒絕工作階段，off 停用掃描。請參閱強化您的部署。
--debug-token-dir <path> SELF_HOSTED_RUNNER_DEBUG_TOKEN_DIR 未設定 將即時權杖寫入磁碟以供檢查。僅用於偵錯；不要在生產環境中使用。
--defer-shutdown-max-min <n> SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS 0 在第一個 SIGTERM 或 SIGINT 上，繼續為已附加的工作階段提供服務而不是排空它們，然後在 N 分鐘後釋放仍然附加的任何內容並退出。在設定此項之前提高主機的停止逾時。請參閱將排空延遲到第一個信號之後。0 停用。需要 Claude Code v2.1.238 或更新版本。
--drain-grace-sec <n> SELF_HOSTED_RUNNER_DRAIN_GRACE_MS 0 在執行器接收到關閉信號或達到其退休時間之前，控制執行器在其活動工作階段完成後何時退出：0 立即退出而不輪詢更多內容，正值使執行器保持活動並首先重新輪詢鎖定擁有者的佇列該許多秒，代價是強化部分中描述的每個工作階段容器隔離。在您使用 --defer-shutdown-max-min 延遲的第一個信號之後，執行器在不持有任何工作階段時立即退出，無論您在此設定什麼。
--drain-marker-file <path> SELF_HOSTED_RUNNER_DRAIN_MARKER_FILE 未設定 標記檔案，您的主機在傳送 SIGTERM 之前寫入以宣佈優雅排空。當檔案在排空開始時存在時，執行器將其退出報告給 Anthropic 為主機排空而不是純粹的關閉信號。排空本身（包括 --drain-wait-sec 保留）的執行方式與沒有旗標相同。在本地檔案系統上命名工作階段無法寫入的路徑。需要 Claude Code v2.1.271 或更新版本。
--drain-wait-sec <n> SELF_HOSTED_RUNNER_DRAIN_WAIT_MS 0 排空開始後（除非您設定 --defer-shutdown-max-min，否則在 SIGTERM 上），等待最多 N 秒讓每個工作階段的進行中轉向和背景工作完成，然後終止子程序。在此等待期間，執行器將剛完成的背景工作計為仍在執行，直到讀取其結果的後續轉向開始，最多 SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS 視窗。
--environment-secret-file <path> SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET 必需 包含環境祕密的檔案路徑，或對於由協調器產生的執行器，單次使用工作訂單 JWT。SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET 直接攜帶祕密值，而不是檔案路徑。較舊的 --pool-secret-file 旗標和 SELF_HOSTED_RUNNER_POOL_SECRET 變數仍然有效並列印棄用通知到 stderr；早於 2.1.216 的預覽程式執行器組建只識別那些較舊的名稱。
--exec-path <path> SELF_HOSTED_RUNNER_EXEC_PATH 自己的二進位檔 為每個工作階段產生的二進位檔或包裝指令碼。請參閱包裝指令碼。
--exit-if-unused-min <n> SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS 0 在 N 分鐘的輪詢後退出，沒有任何工作被指派，用於自動擴展器縮小。0 停用。
--git-host-rewrite <from>=<to> 無 未設定 在複製之前將 https://<from>/... 來源 URL 重寫為 https://<to>/...，用於分割視界 DNS。可重複；僅旗標。
--git-ssh-rewrite <host> 無 未設定 在複製之前將 https://<host>/... 來源 URL 重寫為 git@<host>:...，用於僅限 SSH 的 git 主機。可重複；僅旗標。
--health-port <port> SELF_HOSTED_RUNNER_HEALTH_PORT 8080 /healthz 和 /metrics 接聽器的連接埠。設定 0 以停用。
--hooks-dir <path> SELF_HOSTED_RUNNER_HOOKS_DIR 未設定 生命週期掛鉤指令碼的目錄。請參閱生命週期掛鉤。
--host-config-snapshot <mode> SELF_HOSTED_RUNNER_HOST_CONFIG_SNAPSHOT disk 執行器保持主機設定目錄啟動快照的位置，它從中播種每個工作階段。disk 將快照複製到 --base-dir 下執行器擁有的目錄中，並在每個工作階段啟動時，驗證每個檔案對照記憶體內摘要。如果副本中的檔案已被修改，工作階段失敗，執行器拒絕工作階段，直到您重新啟動它。memory 在堆上保持整個快照，上限為 64 MiB；超過上限，工作階段啟動時沒有主機設定並顯示說明這一點的通知。當執行器無法寫入磁碟快照時，它記錄失敗並為該執行使用 memory。需要 Claude Code v2.1.271 或更新版本。
--kill-session-after-min <n> SELF_HOSTED_RUNNER_MAX_LIFETIME_MS 0 將工作階段限制為 N 分鐘牆上時間，作為卡住工作階段的安全限制。在 v2.1.260 或更新版本上，執行器釋放達到限制的工作階段，以便它可以在其使用者的下一條訊息上繼續，並且只有在它在 SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS 寬限期結束時仍在執行器上時才終止它。在 v2.1.260 之前，執行器在限制時終止工作階段。請參閱某些工作階段不計為閒置以了解詳細資訊以及如何選擇值。0 停用。
--lock-to-account <id> SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT 未設定 在啟動時預先將執行器鎖定到特定帳戶，而不是在第一個工作階段時鎖定。接受環境組織中的電子郵件地址或 user_... ID。預先鎖定的執行器永遠不會拾取 Claude Tag 頻道工作階段，這些工作階段沒有帳戶。
--log-file <path> SELF_HOSTED_RUNNER_LOG_FILE 未設定 除了 stdout 和 stderr 外，還將執行器日誌鏡像到檔案，使用 0600 權限建立。self-hosted-runner doctor 在本地尾部日誌需要此項。
--log-level <level> 無 info info 或 debug
--post-session-hook-timeout-sec <n> SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS 60 post-session 掛鉤在每個工作階段結束時的預算，包括執行器關閉
--proxy-authorization-command <command> SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND 未設定 執行器為每個到您的出口代理的連線執行的 Shell 命令，使用其修剪的 stdout 作為 Proxy-Authorization 標頭值。需要 HTTPS_PROXY 或 HTTP_PROXY，不能與 --proxy-authorization-file 結合。請參閱驗證到出口代理。需要 Claude Code v2.1.238 或更新版本。
--proxy-authorization-file <path> SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE 未設定 執行器為每個到您的出口代理的連線讀取的檔案，使用其修剪的內容作為 Proxy-Authorization 標頭值。對於另一個程序就地輪換的權杖，使用此旗標。與 --proxy-authorization-command 具有相同的要求，不能與其結合。請參閱驗證到出口代理。需要 Claude Code v2.1.238 或更新版本。
--push-outcome-on-release SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE 關閉 在執行器啟動的工作階段結束（例如排空或閒置釋放）時，在刪除工作區之前將追蹤的結果分支推送到 origin，以便進行中的提交在重新啟動後存活。盡力而為；將關閉預算增加 30 秒，並需要 git 2.29 或更新版本以從推送的分支繼續。在啟用之前限制推送存取到 claude/* 參考；請參閱已繼續的工作階段會遺失未推送的工作。通過 checkout 生命週期掛鉤簽出的存放庫不會被推送；改為從 post-session 掛鉤快照這些。
--release-idle-session-min <n> SELF_HOSTED_RUNNER_SESSION_IDLE_MS 0 在轉向完成或工作階段等待使用者操作後，在 N 分鐘的不活動後釋放工作階段槽。仍在進行中轉向的工作階段（包括持有永不完成的背景工作或從執行中工具呼叫內部請求的批准的工作階段）不計為閒置；與 --kill-session-after-min 配對作為硬後擋。在工作階段的背景工作完成後，執行器將工作階段視為忙碌，直到讀取結果的後續轉向開始，最多 SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS 視窗。在執行器接收到關閉信號或達到其退休時間之前，留下執行器沒有活動工作階段的釋放會啟動與正常排空相同的退出路徑，由 --drain-grace-sec 管理。在您使用 --defer-shutdown-max-min 延遲的第一個信號之後，執行器在釋放使其不持有任何工作階段時立即退出。0 停用。
--remove-session-state [bool] SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE 關閉 當工作階段在此執行器上結束時，移除 <base-dir>/_sessions/ 下的工作階段的每個工作階段目錄，無論結果如何。重複使用預先加熱的簽出描述它們持有的內容以及當它們保留時誰可以讀取它們。移除是盡力而為：當執行器被終止或在清理執行之前達到其排空期限時，每個工作階段目錄保留在原位。啟用旗標後，失敗或中斷的工作階段的偵錯日誌不會保留在磁碟上。需要 Claude Code v2.1.268 或更新版本。
--retire-at <epoch-seconds> SELF_HOSTED_RUNNER_RETIRE_AT 未設定 在絕對 Unix 時間戳記（秒）時退休執行器，用於在已知時間終止執行器的基礎設施；執行器生命週期描述釋放序列以及如何調整邊距。2001 年之前或 5138 年之後的值被旗標拒絕，被環境變數忽略。
--session-stop-grace-sec <n> SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS 5 在工作階段結束後，在強制終止之前等待 Claude 程序乾淨退出的時間。如果子程序自己的 SessionEnd 掛鉤需要更多時間，請提高該值。
--startup-timeout-min <n> SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS 15 如果子程序在產生後 N 分鐘內未在活動頻道上發出初始化信號，則釋放工作階段槽。由子程序的初始化信號清除，而不是普通輸出，之後 --release-idle-session-min 接管。0 停用。
--trust-workspace [bool] SELF_HOSTED_RUNNER_TRUST_WORKSPACE 開啟 為每個工作階段的存放庫路徑播種持久化信任，以便尊重存放庫提交的 permissions.allow 和 additionalDirectories。設定 false 以放棄存放庫提交的權限授予，並改為在主機設定的 settings.json 中配置允許規則；存放庫提交的 sandbox.* 設定無論如何仍然適用，這就是為什麼存放庫設定防護無論此旗標如何都掃描它們。
--use-anthropic-git-proxy CLAUDE_RUNNER_USE_GIT_PROXY=1 關閉 通過 Anthropic git proxy 而不是客戶管理的 git 驗證進行複製。需要 --capacity 1 和 git 2.32 或更新版本；執行器否則拒絕啟動。取代重寫旗標。

大多數持續時間旗標都有最大值，選擇以將每個逾時保持在執行時間的 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 無上限。超過上限的行為因表面而異：

  • 旗標：啟動失敗並出現錯誤。
  • 環境變數：執行器將值夾住到計時器上限，而不是拒絕它。

協調器 CLI 旗標

self-hosted-runner orchestrator 子命令（產生按需執行器）接受 --api-url、--environment-secret-file、--hooks-dir、--health-port 和 --log-level，具有與執行器相同的預設值，以及執行器旗標具有的相同環境變數，除了 --hooks-dir 是必需的且必須包含 spawn-runner 掛鉤。它也採用自己的旗標：

旗標 預設值 說明
--hook-concurrency <n> 4 最大 spawn-runner 掛鉤並行執行。也限制每次輪詢聲稱多少個產生請求。
--hook-timeout <sec> 60 在此許多秒後終止掛鉤的程序樹。逾時加上其 5 秒終止寬限期必須保持在 --expected-spawn-seconds 以下；協調器在啟動時強制執行此項。
--expected-spawn-seconds <sec> 120 產生的執行器的預期 p99 啟動時間，在伺服器強制的範圍 10 到 3600 內。在每次輪詢時作為伺服器端租約發送；如果沒有執行器在其經過前註冊，工作階段會以新訂單 ID 重新提供。所有副本必須共享此值。
--min-idle <n> 0 通過主動產生待命執行器來保持至少 N 個閒置工作階段槽空閒。0 停用預熱。與執行器的 --exit-if-unused-min 配對，以便多餘的待命執行器回收自己。
--debug-dir <path> 未設定 將每個產生請求的工作訂單和掛鉤 stderr 寫入磁碟。僅用於偵錯；永遠不要在生產環境中設定。

SCM 連接器旗標

協調器可以與 Anthropic 的控制平面保持常設 WebSocket 連線，以便託管的預工作階段流程（例如存放庫選擇器和分支或參考解析器）可以到達只能從您的網路內部路由的 GitHub Enterprise Server 主機。除非您設定 --scm-connector-host，否則連接器保持關閉。

旗標 預設值 說明
--scm-connector-host <host[:port]> 未設定 要轉發請求的 GitHub Enterprise Server 主機名稱。連接埠預設為 443。設定此旗標會啟用連接器。
--scm-connector-id <n> 與 --scm-connector-host 必需 您組織的 GitHub Enterprise Server 連線的數字 ID。當您啟用連接器時，請聯絡您的 Anthropic 帳戶團隊以取得該值。
--scm-connector-provider <slug> ghe 識別提供者的路徑段，符合 ^[a-z0-9-]{1,32}$。
--scm-connector-ca-file <path> 未設定 額外的 CA 套件（PEM 格式），用於到 GitHub Enterprise Server 主機的 TLS 連線。
--scm-connector-host-rewrite <from>=<to_host:to_port> 未設定 僅用於端到端測試：重定向 TCP 連線，同時將主機標頭和 TLS SNI 保持為 --scm-connector-host。

連接器使用協調器的現有環境祕密進行驗證並自動重新連線：在連線中斷時使用指數退避，或當控制平面因另一個協調器副本已持有它而關閉連線時使用固定 30 秒延遲。

僅環境變數設定

這些執行器設定僅從環境讀取，涵蓋大多數部署保留在預設值的行為：

環境變數 預設值 說明
SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS 30000 執行器在背景工作完成後考慮工作階段忙碌的時間，而讀取結果的後續轉向尚未開始。--drain-wait-sec 和 --release-idle-session-min 列描述排空和閒置釋放時保持適用的位置，執行器生命週期描述它在 --retire-at 退休時適用的位置。0 或無法使用的值回退到預設值，因此無法關閉保持。需要 Claude Code v2.1.228 或更新版本。
SELF_HOSTED_RUNNER_HOST_CONFIG_DIR ~/.claude 捕獲到執行器啟動快照中並播種到每個工作階段的 CLAUDE_CONFIG_DIR 的目錄；磁碟上的變更在執行器重新啟動後適用。設定變數也會移動執行器讀取 .claude.json 的位置以進行 MCP 播種，因此設定它（包括其自己的預設值）會重新定位該查詢；指向空目錄以完全停用播種。
SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS 900000 執行器在工作階段達到其 --kill-session-after-min 限制後等待的時間，以便執行中的轉向完成或釋放完成，然後才終止工作階段
SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS 7000 執行器在轉向完成後計算工作階段忙碌的上限時間，用於 --drain-wait-sec 排空，而工作階段的程序向 Anthropic 報告轉向的結束。0 或無法使用的值回退到預設值，因此無法關閉保持。需要 Claude Code v2.1.275 或更新版本。
SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS 30000 執行器等待作業系統將 SIGKILL 傳遞到卡在不可中斷 I/O 中的子程序的時間，然後自己退出。下限為 --post-session-hook-timeout-sec 加 15 秒，以及設定 --push-outcome-on-release 時的 30 秒，因此有效最小值在預設值為 75 秒。
CLAUDE_RUNNER_FETCH_DEPTH 50 新複製的 git 提取深度。設定正整數，或 full 或 0 以進行完整提取。工作區中已存在的存放庫保持其現有深度。
CLAUDE_RUNNER_SKIP_GIT_VERIFY 未設定 當 1 時，在 checkout 掛鉤執行後跳過 .git 存在檢查。當您的掛鉤具體化非 git 來源時設定此項。
FORCE_AUTOUPDATE_PLUGINS 未設定 當 1 時，即使二進位檔被固定，也讓外掛程式市場自動更新
CLAUDE_CODE_DISABLE_ARTIFACT 未設定 當 1 時，無論組織的管理員設定如何，都在工作階段中停用 Artifact 工具，並放棄 *.frame.claudeusercontent.com 出口要求

遙測

工作階段子程序將操作遙測傳送給 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 主體描述當前狀態：

{
  "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 和一個 scm_connector 物件，其中包含 connected、last_connected_at、last_error、reconnects 和 requests_forwarded。當未設定 --scm-connector-host 時，兩個欄位都是 null。

Prometheus 指標

每個執行器在與 /healthz 相同的連接埠上的 GET /metrics 上提供 Prometheus 指標。關鍵序列：

序列 備註
claude_code_self_hosted_runner_info{runner_id,version,client_label} 始終 1；對艦隊清單和版本漂移檢測有用
claude_code_self_hosted_runner_capacity 配置的 --capacity
claude_code_self_hosted_runner_active_sessions 目前執行的工作階段
claude_code_self_hosted_runner_locked_account{email} 一旦執行器鎖定到使用者並發出攜帶 act.email 聲稱的工作階段權杖，就會出現。該序列在鎖定到 Claude Tag 代理的執行器上不存在，其工作階段權杖不攜帶 act.email。標籤值是帳戶電子郵件；如果您的指標存放區可廣泛讀取，在抓取時放棄或雜湊標籤，例如使用 Prometheus metric_relabel_configs。
claude_code_self_hosted_runner_last_poll_age_seconds 自上次成功輪詢以來的秒數。如果超過 60，則發出警報。
claude_code_self_hosted_runner_poll_errors_total{error_kind} 按類型累積 PollWork 失敗：transport、timeout、5xx、429 或 4xx。所有五個序列都從程序啟動開始存在；在 rate(...[5m]) > 0 時發出警報。
claude_code_self_hosted_runner_sessions_started_total{client_platform} 在執行器的生命週期內產生的工作階段子程序，每個工作階段來源一個序列，例如 web_claude_ai、ios、android、desktop_app 或 claude_code_cli，或當伺服器未傳送時 unknown。Slack 工作階段根據哪個 Slack 整合建立它們而攜帶 claude_in_slack 或 claude-in-slack，因此使用正規表達式選擇器（例如 {client_platform=~"claude[-_]in[-_]slack"} 匹配兩者。使用 sum() 表示艦隊總計。
claude_code_self_hosted_runner_sessions_completed_total{client_platform} 乾淨結束的工作階段，標籤方式相同。比普通乾淨退出更廣泛：請參閱工作階段生命週期計數器語義以了解計數的內容。
claude_code_self_hosted_runner_sessions_failed_total{client_platform} 以失敗結束的工作階段，標籤方式相同。相同的警告：請參閱工作階段生命週期計數器語義。
claude_code_self_hosted_runner_sessions_interrupted_total{client_platform} 執行器因操作原因而不是工作階段結果終止的工作階段，標籤方式相同。請參閱工作階段生命週期計數器語義。
claude_code_self_hosted_runner_initializing_sessions 目前處於初始化階段的工作階段，從指派到子程序的初始化事件
claude_code_self_hosted_runner_session_init_duration_seconds 工作階段初始化持續時間的直方圖
claude_code_self_hosted_runner_session_init_errors_total 在達到初始化前失敗的工作階段：簽出掛鉤失敗、git 準備、權杖問題或初始化前子程序崩潰
claude_code_self_hosted_runner_session_start_hook_errors_total 報告錯誤結果的 SessionStart 掛鉤，每個失敗的掛鉤執行一個
claude_code_self_hosted_runner_session_idle_seconds{session_id,client_platform} 每個工作階段的工作階段閒置以來秒數的量表。對於終止卡在未回答權限提示上的工作階段很有用。

協調器在與其 /healthz 相同的連接埠上的 GET /metrics 上提供自己的序列：

序列 備註
claude_code_self_hosted_orchestrator_info{version,pool_id,orchestrator_uuid,hostname} 始終 1
claude_code_self_hosted_orchestrator_connected 當最近輪詢成功時為 1；在任何失敗輪詢後下降到 0，無論失敗類型如何
claude_code_self_hosted_orchestrator_last_poll_age_seconds 自上次輪詢嘗試以來的秒數，成功或失敗，與執行器的同名指標不同，後者測量自上次成功以來；與 connected 配對以捕獲失敗的輪詢。協調器的輪詢迴圈等待掛鉤執行，因此在 --hook-timeout 加邊距（預設值約 90 秒）上方發出警報，而不是平面 60。
claude_code_self_hosted_orchestrator_poll_errors_total{error_kind} 按類型累積 PollSpawnHints 失敗：transport、timeout、5xx、429 或 4xx。所有五個序列都從程序啟動開始存在；在 rate(...[5m]) > 0 時發出警報。
claude_code_self_hosted_orchestrator_queue_pending_sessions 現在可聲稱的產生請求
claude_code_self_hosted_orchestrator_queue_backing_off_sessions 在可重試掛鉤失敗後退避重試的產生請求
claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions 被阻止的產生請求，直到擁有者從環境的活動標籤重試它們；如果高於零則發出警報
claude_code_self_hosted_orchestrator_pool_pending_sessions 等待此環境中執行器的總工作階段。環境範圍的聚合，在每個協調器實例上相同：在實例之間使用 MAX 而不是 SUM。
claude_code_self_hosted_orchestrator_pool_active_sessions 目前指派給此環境中活著執行器的工作階段。環境範圍的聚合，在每個協調器實例上相同：在實例之間使用 MAX 而不是 SUM。
claude_code_self_hosted_orchestrator_spawn_hooks_total{result} 累積 spawn-runner 掛鉤結果：ok、retryable、non_retryable。計數協調器掛鉤呼叫，而不是執行器產生的工作階段子程序：不可與 sessions_started_total 比較，因為容量高於 1、暖池和為同一工作階段再次產生的執行器都使兩者分歧。
claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds 掛鉤持續時間的直方圖
claude_code_self_hosted_orchestrator_warm_hints_dispatched_total 自程序啟動以來分派的待命產生請求
claude_code_self_hosted_orchestrator_session_queue_wait_seconds 每個工作階段在佇列中等待的秒數的直方圖，然後協調器聲稱它進行產生，從控制平面與每個工作階段的產生請求一起傳送的佇列等待時間戳記記錄。用於 p50/p99 佇列時間警報。預熱產生不被取樣。
claude_code_self_hosted_orchestrator_clock_skew_seconds 本地減去伺服器時鐘偏差；診斷，一旦測量就存在
claude_code_self_hosted_orchestrator_scm_connector_connected 當 SCM 連接器 的 WebSocket 開啟時為 1；在撥號或退避時為 0。當未設定 --scm-connector-host 時不存在。
claude_code_self_hosted_orchestrator_scm_connector_requests_forwarded_total 自程序啟動以來代理到配置的 SCM 主機的累積 HTTP 請求。當未設定 --scm-connector-host 時不存在。

對於自動擴展，選擇與您的擴展風格相符的序列並在其進入擴展器之前閘它：

  • 佇列深度擴展：將 claude_code_self_hosted_orchestrator_pool_pending_sessions 饋送到您的 HPA 或 KEDA 擴展器，而不是 queue_pending_sessions。
  • 容量擴展：根據執行器的 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 自託管執行器 + 協調器的範例 Prometheus Operator PodMonitor。
# 調整命名空間和標籤選擇器以符合您的部署。執行器和協調器都在其
# --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 配方中的執行器部署，加上任何
      # 按相同方式標籤的按需執行器工作和協調器 Pod
      # 並給予命名的 'health' containerPort。
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

這些範例警報規則是起點；為您的艦隊大小調整閾值：

# Claude Code 自託管執行器 + 協調器的範例 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: "執行器 {{ $labels.pod }} 已超過 60 秒未輪詢"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "執行器執行混合版本"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "執行器 {{ $labels.pod }}：10 分鐘內 >3 個工作階段初始化失敗（簽出掛鉤 / git / 權杖 / 初始化前崩潰）"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "執行器 {{ $labels.pod }}：PollWork 失敗（5 分鐘內 {{ $value | humanize }}/s）"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "執行器 {{ $labels.pod }}：10 分鐘內 >3 個 SessionStart 掛鉤失敗"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "協調器 {{ $labels.pod }} 無法到達 Anthropic 控制平面"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "協調器 {{ $labels.pod }} 已超過 90 秒未輪詢（輪詢迴圈等待掛鉤執行）"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "{{ $value }} 個工作階段斷路 — spawn-runner 掛鉤重複不可重試；修復基礎設施然後從活動標籤重試"
      - alert: ClaudeOrchestratorPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "協調器 {{ $labels.pod }}：PollSpawnHints 失敗（5 分鐘內 {{ $value | humanize }}/s）"
      - 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: "協調器 {{ $labels.pod }}：5 分鐘內 >3 個 spawn-runner 掛鉤失敗"

傳遞工作階段子程序指標

每個工作階段在其自己的子程序中執行，具有自己的 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。

在 v2.1.260 之前，執行器終止達到其 --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 在產生時增加並在工作階段的生命週期內保持可見，因此它可靠地顯示，但在一次性環境上它讀取更接近「目前執行的工作階段」而不是累積計數。

改為使用此表中的序列以達到相應的目標，而不是終端計數器：

目標 使用
吞吐量 claude_code_self_hosted_orchestrator_spawn_hooks_total{result="ok"}，長期協調器上的計數器，每個成功的 spawn-runner 掛鉤增加一次並在 rate() 下保持有意義。它計數掛鉤呼叫而不是工作階段，因此預熱和為同一工作階段重複產生使其與工作階段計數分歧。
利用率 sum(claude_code_self_hosted_runner_active_sessions) 對 sum(claude_code_self_hosted_runner_capacity)，兩個量表在每次抓取時有效，無論執行器生命週期如何
待辦項 claude_code_self_hosted_orchestrator_pool_pending_sessions 用於佇列深度，以及 claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions，如果高於零則發出警報
失敗 claude_code_self_hosted_runner_sessions_failed_total，盡力而為：產生後的真實崩潰確實增加它，rate() 在執行器上有意義，這些執行器以 --drain-grace-sec 高於 0 的方式超越其工作階段。一次性環境與其他終端計數器具有相同的抓取視窗問題，因此將您看到的任何非零值視為值得調查。產生前的失敗，例如簽出掛鉤失敗、git 準備或權杖問題，僅出現在 session_init_errors_total 中。

orchestrator_* 列僅存在於執行按需協調器的環境上。在固定艦隊上，其執行器以 --drain-grace-sec 高於 0 的方式超越其工作階段，使用 sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) 表示吞吐量；在一次性艦隊上，該序列與終端計數器具有相同的抓取視窗問題，因此改為依賴佇列工作階段計數。在環境的活動標籤上檢查待辦項，在雲端環境管理頁面上：執行器不匯出佇列深度序列。

對於每個工作階段結果報告，改為使用 post-session 掛鉤：它在每個工作階段結束時觸發，其中產生了子程序，除了突然執行器終止（例如 VM 搶佔），根據掛鉤自己的合約。

下一步