> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Referenz für selbstgehostete Umgebungen
> Vollständige Referenz für den selbstgehosteten Runner und Orchestrator: CLI-Flags, Umgebungsvariablen und Prometheus-Metriken.
Selbstgehostete Umgebungen befinden sich in der öffentlichen Beta auf Team- und Enterprise-Plänen; ein [Inhaber](/docs/de/cloud-environments#organization-shared-environments) aktiviert sie, indem er **Selbstgehostete Umgebungen zulassen** auf der [**Cloud-Umgebungen** Admin-Seite](https://claude.ai/admin-settings/cloud-environments) einschaltet. Diese Seite ist die Flag- und Metrik-Referenz; siehe den [Schnellstart](/docs/de/self-hosted-environments-quickstart) für die Einrichtung und [In Produktion bereitstellen](/docs/de/self-hosted-environments-deploy) für die Fleet-Rezepte.
Diese Seite ist die Referenz für die zwei Prozesse, die Sie in einer [selbstgehosteten Umgebung](/docs/de/self-hosted-environments) ausführen: der Runner, der Claude Code [Cloud-Sitzungen](/docs/de/claude-code-on-the-web) auf Ihren Hosts ausführt, und der optionale Autoscaling-Orchestrator, der Runner startet, wenn Sitzungen in die Warteschlange eingereiht werden. Jeder hat seine eigene Flag-Tabelle. Beide laufen auf Linux- oder macOS-Hosts, wobei die Standardwerte wie `/workspace` und `~/.claude` angenommen werden. Führen Sie `claude self-hosted-runner --help` aus, um die autoritative Liste in Ihrer installierten Version zu erhalten.
Metrische Reihen und einige wenige API-Felder verwenden immer noch `pool` für das, was diese Seiten eine Umgebung nennen; beide Begriffe bezeichnen dasselbe. Die Umgebungs-ID ist das Feld `pool_id` mit der Form `ccpool_...`: Überall dort, wo diese Seiten einen `pool`-Bezeichner anzeigen, benennt er die Umgebung. CLI-Flags und Umgebungsvariablen schreiben es als `environment`, wie z. B. `--environment-secret-file`; die veralteten `pool`-Schreibweisen funktionieren immer noch, wie die Zeile [`--environment-secret-file`](#runner-cli-flags) beschreibt.
Runner-CLI-Flags
Die meisten Flags haben eine entsprechende Umgebungsvariable. Wenn beide gesetzt sind, hat das Flag Vorrang. Duration-Flags nehmen Minuten oder Sekunden in der CLI, aber die gepaarte Umgebungsvariable ist immer in Millisekunden, angezeigt durch das Suffix `_MS`, und die Spalte Standard zeigt die Einheit des Flags: `--exit-if-unused-min 10` entspricht `SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000`, und ein Helm-Wert wie `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15"` bedeutet 15 Millisekunden, nicht die 15-Minuten-Standard.
| Flag | Env var | Standard | Beschreibung |
| :---------------------------------------- | :------------------------------------------------ | :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--api-url ` | keine | `https://api.anthropic.com` | API-Basis-URL. Nur zum Testen überschreiben. |
| `--base-dir ` | `SELF_HOSTED_RUNNER_BASE_DIR` | `/workspace`; keine unter Windows | Verzeichnis für Repository-Checkouts und pro-Sitzungs-Arbeitsverzeichnisse. Der Runner benötigt Schreibzugriff auf diesen Pfad oder sein übergeordnetes Verzeichnis. Der Runner erstellt das Verzeichnis beim Start und beendet sich mit `cannot create or write to base directory`, wenn er es nicht erstellen oder beschreiben kann. Vor v2.1.225 erstellte der Runner das Verzeichnis, wenn die erste Sitzung startete, sodass ein unbrauchbarer Pfad Sitzungen fehlschlagen ließ, anstatt beim Start zu fehlschlagen. Unter Windows, das kein unterstützter Runner-Host ist, gibt es keinen Standard: Der Runner beendet sich beim Start, es sei denn, Sie übergeben das Flag oder setzen die Variable. Verwenden Sie denselben Wert auf jedem Runner in einer Umgebung. Siehe [Halten Sie das Basisverzeichnis und die Kapazität auf allen Runnern identisch](/docs/de/self-hosted-environments-deploy#keep-the-base-directory-and-capacity-identical-across-runners). |
| `--capacity ` | keine | `1` | Maximale gleichzeitige Sitzungen, die dieser Runner verarbeitet. Alle Sitzungen gehören demselben gesperrten [Owner](/docs/de/self-hosted-environments#key-concepts). Verwenden Sie denselben Wert auf jedem Runner in einer Umgebung; siehe [Halten Sie das Basisverzeichnis und die Kapazität auf allen Runnern identisch](/docs/de/self-hosted-environments-deploy#keep-the-base-directory-and-capacity-identical-across-runners). |
| `--client-label ` | `SELF_HOSTED_RUNNER_CLIENT_LABEL` | der Hostname des Hosts | Beschriften Sie den Runner, den er beim Registrieren sendet. Der Runner meldet ihn auch als das Label `client_label` von [`claude_code_self_hosted_runner_info`](#prometheus-metrics). Erfordert Claude Code v2.1.248 oder später. |
| `--configure-git` | `SELF_HOSTED_RUNNER_CONFIGURE_GIT=1` | aus | Beim Start globale Git-Identität schreiben, Anthropic-Commit-Signing aktivieren, Git-Push-Verhandlung einschalten und Commit-Hooks installieren, die einen `Co-authored-by:` Trailer anhängen. Push-Verhandlung erfordert Claude Code v2.1.257 oder später. Siehe [Git konfigurieren](/docs/de/self-hosted-environments-deploy#configure-git). |
| `--confine-repo-settings ` | `SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS` | `warn` | Setzt den Modus des Schutzes, der eine Sitzung kennzeichnet, wenn die festgeschriebenen Einstellungen eines Repositorys versuchen, Schreib- oder Lesezugriff außerhalb des eigenen Arbeitsbereichs dieser Sitzung zu gewähren, Umgebungsvariablen zu setzen oder die Sandbox- oder Hooks-Haltung des Operators zu überschreiben, wie `sandbox.enabled: false` oder `disableAllHooks`. Der Standard `warn` protokolliert die Verletzung und startet die Sitzung trotzdem, `enforce` lehnt die Sitzung ab, und `off` deaktiviert den Scan. Siehe [Härten Sie Ihre Bereitstellung](/docs/de/self-hosted-environments-deploy#harden-your-deployment). |
| `--debug-token-dir ` | `SELF_HOSTED_RUNNER_DEBUG_TOKEN_DIR` | nicht gesetzt | Schreiben Sie Live-Tokens zur Überprüfung auf die Festplatte. Nur zum Debuggen; nicht in der Produktion verwenden. |
| `--defer-shutdown-max-min ` | `SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS` | `0` | Beim ersten `SIGTERM` oder `SIGINT` bedienen Sie weiterhin die bereits angehängten Sitzungen, anstatt sie zu entleeren, und geben dann alles frei, das noch angehängt ist, N Minuten später und beenden sich. Erhöhen Sie das Stop-Timeout Ihres Hosts, bevor Sie dies setzen. Siehe [Verschieben Sie die Entleerung über das erste Signal hinaus](/docs/de/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal). `0` deaktiviert. Erfordert Claude Code v2.1.238 oder später. |
| `--drain-grace-sec ` | `SELF_HOSTED_RUNNER_DRAIN_GRACE_MS` | `0` | Bis der Runner ein Shutdown-Signal empfängt oder seine Ruhestandszeit erreicht, steuert, wann der Runner beendet wird, nachdem seine aktiven Sitzungen beendet sind: `0` beendet sich sofort ohne Abfrage nach mehr, und ein positiver Wert hält den Runner am Leben und fragt die Warteschlange des gesperrten Owners N Sekunden lang erneut ab, auf Kosten der Pro-Sitzungs-Container-Isolation, die im [Härtungsabschnitt](/docs/de/self-hosted-environments-deploy#harden-your-deployment) beschrieben ist. Nach einem ersten Signal, das Sie mit [`--defer-shutdown-max-min`](/docs/de/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) verschoben haben, beendet sich der Runner, sobald er keine Sitzungen mehr hält, unabhängig davon, was Sie hier setzen. |
| `--drain-wait-sec ` | `SELF_HOSTED_RUNNER_DRAIN_WAIT_MS` | `0` | Sobald die Entleerung beginnt, was bei `SIGTERM` der Fall ist, es sei denn, Sie setzen [`--defer-shutdown-max-min`](/docs/de/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), warten Sie bis zu N Sekunden, damit die laufenden Aufgaben und Hintergrundaufgaben jeder Sitzung beendet werden, bevor Sie das Kind beenden. Während dieses Wartens zählt der Runner eine Hintergrundaufgabe, die gerade beendet wurde, als immer noch laufend, bis der Folgezug, der sein Ergebnis liest, beginnt, für höchstens das Fenster [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings). |
| `--environment-secret-file ` | `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` | erforderlich | Pfad zu einer Datei, die das Umgebungsgeheimnis enthält, oder für Runner, die vom [Orchestrator](/docs/de/self-hosted-environments-configuration#on-demand-runners) erzeugt werden, das einmalige Work-Order-JWT. `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` trägt den Geheimniswert direkt, nicht einen Dateipfad. Das ältere Flag `--pool-secret-file` und die Variable `SELF_HOSTED_RUNNER_POOL_SECRET` funktionieren immer noch und geben eine Veraltungswarnung auf stderr aus; Preview-Programm-Runner-Builds älter als 2.1.216 erkennen nur diese älteren Namen. |
| `--exec-path ` | `SELF_HOSTED_RUNNER_EXEC_PATH` | eigene Binärdatei | Binärdatei oder Wrapper-Skript zum Erzeugen für jede Sitzung. Siehe [Wrapper-Skripte](/docs/de/self-hosted-environments-configuration#wrapper-scripts). |
| `--exit-if-unused-min ` | `SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS` | `0` | Beenden Sie sich nach N Minuten Abfrage ohne jemals zugewiesene Arbeit, für Autoscaler-Skalierung nach unten. `0` deaktiviert. |
| `--git-host-rewrite =` | keine | nicht gesetzt | Schreiben Sie `https:///...` Quell-URLs zu `https:///...` um, bevor Sie klonen, für Split-Horizon-DNS. Wiederholbar; nur Flag. |
| `--git-ssh-rewrite ` | keine | nicht gesetzt | Schreiben Sie `https:///...` Quell-URLs zu `git@:...` um, bevor Sie klonen, für SSH-only Git-Hosts. Wiederholbar; nur Flag. |
| `--health-port ` | `SELF_HOSTED_RUNNER_HEALTH_PORT` | `8080` | Port für den `/healthz`- und `/metrics`-Listener. Setzen Sie `0`, um zu deaktivieren. |
| `--hooks-dir ` | `SELF_HOSTED_RUNNER_HOOKS_DIR` | nicht gesetzt | Verzeichnis von Lifecycle-Hook-Skripten. Siehe [Lifecycle-Hooks](/docs/de/self-hosted-environments-configuration#lifecycle-hooks). |
| `--kill-session-after-min ` | `SELF_HOSTED_RUNNER_MAX_LIFETIME_MS` | `0` | Begrenzen Sie eine Sitzung auf N Minuten Wanduhr, als Sicherheitslimit für steckengebliebene Sitzungen. In v2.1.260 oder später gibt der Runner eine Sitzung frei, die das Limit erreicht, damit sie in der nächsten Nachricht des Benutzers fortgesetzt werden kann, und beendet sie nur, wenn sie sich noch auf dem Runner befindet, wenn das Gnadenfenster [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](#environment-variable-only-settings) endet. Vor v2.1.260 beendete der Runner die Sitzung beim Limit. Siehe [Einige Sitzungen zählen nicht als untätig](/docs/de/self-hosted-environments-deploy#some-sessions-don%E2%80%99t-count-as-idle) für die Details und wie Sie einen Wert wählen. `0` deaktiviert. |
| `--lock-to-account ` | `SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT` | nicht gesetzt | Sperren Sie den Runner beim Start vorab auf ein bestimmtes Konto, anstatt beim ersten Session zu sperren. Akzeptiert eine E-Mail-Adresse oder eine `user_...` ID in der Organisation der Umgebung. Ein vorgespannter Runner nimmt niemals Claude Tag-Kanal-Sitzungen auf, die kein Konto haben. |
| `--log-file ` | `SELF_HOSTED_RUNNER_LOG_FILE` | nicht gesetzt | Spiegeln Sie Runner-Protokolle zusätzlich zu stdout und stderr in eine Datei, erstellt mit `0600`-Berechtigungen. Erforderlich für `self-hosted-runner doctor`, um Protokolle lokal zu verfolgen. |
| `--log-level ` | keine | `info` | `info` oder `debug` |
| `--post-session-hook-timeout-sec ` | `SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS` | `60` | Budget für den [`post-session` Hook](/docs/de/self-hosted-environments-configuration#post-session) am Ende jeder Sitzung, einschließlich Runner-Shutdown |
| `--proxy-authorization-command ` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | nicht gesetzt | Shell-Befehl, den der Runner für jede Verbindung zu Ihrem Egress-Proxy ausführt, wobei seine gekürzte Standardausgabe als Wert des Headers `Proxy-Authorization` verwendet wird. Erfordert `HTTPS_PROXY` oder `HTTP_PROXY`, und kann nicht mit `--proxy-authorization-file` kombiniert werden. Siehe [Authentifizieren Sie sich bei einem Egress-Proxy](/docs/de/self-hosted-environments-deploy#authenticate-to-an-egress-proxy). Erfordert Claude Code v2.1.238 oder später. |
| `--proxy-authorization-file ` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | nicht gesetzt | Datei, die der Runner für jede Verbindung zu Ihrem Egress-Proxy liest, wobei ihr gekürzter Inhalt als Wert des Headers `Proxy-Authorization` verwendet wird. Verwenden Sie dieses Flag für ein Token, das ein anderer Prozess an Ort und Stelle rotiert. Trägt dieselben Anforderungen wie `--proxy-authorization-command` und kann nicht damit kombiniert werden. Siehe [Authentifizieren Sie sich bei einem Egress-Proxy](/docs/de/self-hosted-environments-deploy#authenticate-to-an-egress-proxy). Erfordert Claude Code v2.1.238 oder später. |
| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | aus | Bei einem Runner-initiierten Session-Ende, wie einer Entleerung oder Idle-Freigabe, pushen Sie verfolgte Outcome-Branches zu `origin`, bevor Sie den Arbeitsbereich löschen, sodass laufende Commits einen Neustart überstehen. Best-Effort; fügt 30 Sekunden zum Shutdown-Budget hinzu und erfordert Git 2.29 oder neuer, um vom gepushten Branch fortzufahren. Beschränken Sie den Push-Zugriff auf `claude/*` Refs, bevor Sie dies aktivieren; siehe [Fortgesetzte Sitzungen verlieren nicht gepushte Arbeit](/docs/de/self-hosted-environments-deploy#additional-limitations). Repositories, die über einen `checkout` Lifecycle-Hook ausgecheckt werden, werden nicht gepusht; erstellen Sie stattdessen Snapshots von diesen vom [`post-session` Hook](/docs/de/self-hosted-environments-configuration#post-session). |
| `--release-idle-session-min ` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | Geben Sie einen Session-Slot nach N Minuten Inaktivität frei, sobald ein Zug beendet ist oder die Sitzung auf die Aktion des Benutzers wartet. Eine Sitzung, die sich noch mitten in einem Zug befindet, einschließlich einer, die eine nie endende Hintergrundaufgabe hält oder eine Genehmigung anfordert, die von innerhalb eines laufenden Tool-Aufrufs angefordert wird, zählt nicht als untätig; koppeln Sie mit `--kill-session-after-min` als harter Backstop. Nachdem die Hintergrundaufgabe einer Sitzung beendet ist, betrachtet der Runner die Sitzung als beschäftigt, bis der Folgezug, der das Ergebnis liest, beginnt, für höchstens das Fenster [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings). Bis der Runner ein Shutdown-Signal empfängt oder seine Ruhestandszeit erreicht, startet eine Freigabe, die den Runner ohne aktive Sitzungen hinterlässt, denselben Ausstiegspfad wie eine normale Entleerung, gesteuert durch `--drain-grace-sec`. Nach einem ersten Signal, das Sie mit [`--defer-shutdown-max-min`](/docs/de/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) verschoben haben, beendet sich der Runner, sobald eine Freigabe ihn ohne Sitzungen hinterlässt. `0` deaktiviert. |
| `--retire-at ` | `SELF_HOSTED_RUNNER_RETIRE_AT` | nicht gesetzt | Ruhestand des Runners bei einem absoluten Unix-Zeitstempel in Sekunden, für Infrastruktur, die den Runner zu einem bekannten Zeitpunkt beendet; [Runner-Lebenszyklus](/docs/de/self-hosted-environments#runner-lifecycle) beschreibt die Freigabesequenz und wie Sie die Marge dimensionieren. Werte vor 2001 oder nach dem Jahr 5138 werden vom Flag abgelehnt und von der Umgebungsvariable ignoriert. |
| `--session-stop-grace-sec ` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | Wie lange Sie warten, bis der Claude-Prozess nach einer Sitzung sauber beendet wird, bevor Sie ihn gewaltsam beenden. Erhöhen Sie den Wert, wenn die eigenen `SessionEnd` Hooks des Kindes mehr Zeit benötigen. |
| `--startup-timeout-min ` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | Geben Sie einen Session-Slot frei, wenn das Kind nicht signalisiert hat, dass es sich innerhalb von N Minuten nach dem Erzeugen initialisiert hat. Gelöscht durch das Init-Signal des Kindes auf dem [Activity-Kanal](/docs/de/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached), nicht durch gewöhnliche Ausgabe, danach übernimmt `--release-idle-session-min`. `0` deaktiviert. |
| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | an | Seed persistierte Vertrauenswürdigkeit für die Repository-Pfade jeder Sitzung, sodass im Repo festgeschriebene `permissions.allow` und `additionalDirectories` berücksichtigt werden. Setzen Sie `false`, um im Repo festgeschriebene Berechtigungszuschüsse zu verwerfen und Zulassungsregeln stattdessen in der Host-Konfiguration `settings.json` zu konfigurieren; Repository-festgeschriebene `sandbox.*` Einstellungen gelten trotzdem, weshalb der [Repo-Settings-Schutz](/docs/de/self-hosted-environments-deploy#harden-your-deployment) sie unabhängig von diesem Flag scannt. |
| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | aus | Klonen Sie über den [Anthropic Git-Proxy](/docs/de/self-hosted-environments-deploy#use-the-anthropic-git-proxy) anstatt über kundenverwaltete Git-Authentifizierung. Erfordert `--capacity 1` und Git 2.32 oder neuer; der Runner weigert sich, andernfalls zu starten. Ersetzt die Rewrite-Flags. |
Die meisten Duration-Flags haben ein Maximum, das gewählt wurde, um jeden Timeout unter der 32-Bit-Timer-Obergrenze der Laufzeit von ungefähr 24,85 Tagen zu halten. Die `--*-min` Flags sind auf 10080 Minuten, 7 Tage begrenzt; `--drain-grace-sec` auf 604800 Sekunden, auch 7 Tage; und `--drain-wait-sec` auf 86400 Sekunden, 24 Stunden. `--session-stop-grace-sec` und `--post-session-hook-timeout-sec` sind unbegrenzt. Das Überschreiten einer Obergrenze verhält sich je nach Oberfläche unterschiedlich:
* **Flag**: Der Start schlägt mit einem Fehler fehl.
* **Umgebungsvariable**: Der Runner begrenzt den Wert auf die Timer-Obergrenze, anstatt ihn abzulehnen.
Orchestrator-CLI-Flags
Der Unterbefehl `self-hosted-runner orchestrator`, der [On-Demand-Runner](/docs/de/self-hosted-environments-configuration#on-demand-runners) erzeugt, akzeptiert `--api-url`, `--environment-secret-file`, `--hooks-dir`, `--health-port` und `--log-level` mit denselben Standardwerten wie der Runner und, wo das Flag des Runners einen hat, dieselbe Umgebungsvariable, außer dass `--hooks-dir` erforderlich ist und einen `spawn-runner` Hook enthalten muss. Es nimmt auch seine eigenen Flags:
| Flag | Standard | Beschreibung |
| :------------------------------- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--hook-concurrency ` | `4` | Maximale `spawn-runner` Hooks, die parallel laufen. Begrenzt auch, wie viele Spawn-Anfragen pro Abfrage beansprucht werden. |
| `--hook-timeout ` | `60` | Beenden Sie den Prozessbaum des Hooks nach dieser vielen Sekunden. Das Timeout plus seine 5-Sekunden-Kill-Gnadenfrist müssen unter `--expected-spawn-seconds` bleiben; der Orchestrator erzwingt dies beim Start. |
| `--expected-spawn-seconds ` | `120` | Erwartete p99-Bootzeit für erzeugte Runner, im servererzwungenen Bereich 10 bis 3600. Wird bei jeder Abfrage als Server-seitige Lease gesendet; wenn sich kein Runner registriert, bevor er verstreicht, wird die Sitzung mit einer frischen Bestellungs-ID erneut angeboten. Alle Replikas müssen diesen Wert teilen. |
| `--min-idle ` | `0` | Halten Sie mindestens N untätige Session-Slots frei, indem Sie proaktiv Standby-Runner erzeugen. `0` deaktiviert Vorwärmung. Koppeln Sie mit dem `--exit-if-unused-min` des Runners, sodass überschüssige Standby-Runner sich selbst zurückfordern. |
| `--debug-dir ` | nicht gesetzt | Schreiben Sie die Work-Order und Hook-Stderr jeder Spawn-Anfrage auf die Festplatte. Nur zum Debuggen; niemals in der Produktion setzen. |
SCM-Connector-Flags
Der Orchestrator kann eine stehende WebSocket-Verbindung zur Anthropic-Kontrolleben halten, sodass gehostete Pre-Session-Flows, wie der Repository-Picker und der Branch- oder Ref-Resolver, einen GitHub Enterprise Server-Host erreichen können, der nur von innerhalb Ihres Netzwerks erreichbar ist. Der Connector bleibt aus, es sei denn, Sie setzen `--scm-connector-host`.
| Flag | Standard | Beschreibung |
| :------------------------------------------------------ | :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--scm-connector-host ` | nicht gesetzt | GitHub Enterprise Server-Hostname, an den Anfragen weitergeleitet werden. Der Port ist standardmäßig `443`. Das Setzen dieses Flags aktiviert den Connector. |
| `--scm-connector-id ` | erforderlich mit `--scm-connector-host` | Die numerische ID der GitHub Enterprise Server-Verbindung Ihrer Organisation. Kontaktieren Sie Ihr Anthropic-Kontoteam für den Wert, wenn Sie den Connector aktivieren. |
| `--scm-connector-provider ` | `ghe` | Pfadsegment, das den Anbieter identifiziert, passend zu `^[a-z0-9-]{1,32}$`. |
| `--scm-connector-ca-file ` | nicht gesetzt | Zusätzliches CA-Bundle im PEM-Format für TLS-Verbindungen zum GitHub Enterprise Server-Host. |
| `--scm-connector-host-rewrite =` | nicht gesetzt | Nur für End-to-End-Tests: leitet die TCP-Verbindung um, während der Host-Header und TLS SNI als `--scm-connector-host` beibehalten werden. |
Der Connector authentifiziert sich mit dem bestehenden Umgebungsgeheimnis des Orchestrators und verbindet sich automatisch erneut: mit exponentiellem Backoff bei einer unterbrochenen Verbindung oder einer festen 30-Sekunden-Verzögerung, wenn die Kontrolleben die Verbindung schließt, weil ein anderes Orchestrator-Replikat sie bereits hält.
Nur-Umgebungsvariablen-Einstellungen
Diese Runner-Einstellungen werden nur aus der Umgebung gelesen und decken Verhalten ab, das die meisten Bereitstellungen bei der Standardeinstellung belassen:
| Env var | Standard | Beschreibung |
| :----------------------------------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS` | `30000` | Wie lange der Runner eine Sitzung als beschäftigt betrachtet, nachdem eine Hintergrundaufgabe beendet ist, während der Folgezug, der das Ergebnis liest, nicht gestartet hat. Die Zeilen [`--drain-wait-sec` und `--release-idle-session-min`](#runner-cli-flags) beschreiben, wo die Sperre bei Entleerung und Idle-Freigabe angewendet wird, und [Runner-Lebenszyklus](/docs/de/self-hosted-environments#runner-lifecycle) beschreibt, wo sie bei `--retire-at` Ruhestand angewendet wird. `0` oder ein unbrauchbarer Wert fällt auf den Standard zurück, sodass die Sperre nicht ausgeschaltet werden kann. Erfordert Claude Code v2.1.228 oder später. |
| `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` | `~/.claude` | Verzeichnis, das in den Startup-Snapshot des Runners erfasst und in die `CLAUDE_CONFIG_DIR` jeder Sitzung eingegeben wird; Änderungen auf der Festplatte gelten nach einem Runner-Neustart. Das Setzen der Variable verschiebt auch, wo der Runner `.claude.json` für [MCP-Seeding](/docs/de/self-hosted-environments-configuration#mcp-servers) liest, sodass das Setzen, einschließlich auf seinen eigenen Standard, diese Suche verlagert; zeigen Sie auf ein leeres Verzeichnis, um das Seeding vollständig zu deaktivieren. |
| `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS` | `900000` | Wie lange der Runner wartet, nachdem eine Sitzung ihr `--kill-session-after-min` Limit erreicht hat, damit ein laufender Zug beendet wird oder die Freigabe abgeschlossen wird, bevor die Sitzung beendet wird |
| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | Wie lange der Runner wartet, bis das Betriebssystem `SIGKILL` an ein Kind sendet, das in nicht unterbrechbarem I/O steckt, bevor es sich selbst beendet. Auf `--post-session-hook-timeout-sec` plus 15 Sekunden begrenzt, und 30 weitere, wenn `--push-outcome-on-release` gesetzt ist, sodass das effektive Minimum 75 Sekunden bei Standardwerten ist. |
| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | Git-Fetch-Tiefe für frische Klone. Setzen Sie eine positive Ganzzahl oder `full` oder `0` für einen vollständigen Fetch. Repositories, die bereits im Arbeitsbereich vorhanden sind, behalten ihre bestehende Tiefe. |
| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | nicht gesetzt | Wenn `1`, überspringen Sie die `.git` Präsenzprüfung, nachdem ein `checkout` Hook ausgeführt wird. Setzen Sie dies, wenn Ihr Hook eine Nicht-Git-Quelle materialisiert. |
| `FORCE_AUTOUPDATE_PLUGINS` | nicht gesetzt | Wenn `1`, lassen Sie Plugin-Marktplätze automatisch aktualisieren, obwohl die Binärdatei angeheftet ist |
| `CLAUDE_CODE_DISABLE_ARTIFACT` | nicht gesetzt | Wenn `1`, deaktivieren Sie das Artifact-Tool in Sitzungen unabhängig von der Admin-Einstellung der Organisation und löschen Sie die `*.frame.claudeusercontent.com` Egress-Anforderung |
Telemetrie
Session-Kinder senden operative Telemetrie an Anthropic, es sei denn, Sie schalten sie aus. Kein Code oder Repository-Inhalt wird gesendet. Setzen Sie Telemetrie-Variablen auf dem Runner-Prozess; der Runner bekräftigt sie erneut, nachdem er von der Kontrolleben bereitgestellte Umgebungsvariablen angewendet hat, sodass die Einstellung des Operators immer Vorrang hat.
Ein Steuerelement ist spezifisch für selbstgehostete Umgebungen: `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1` meldet sich für Datadog-Operationsmetriken an, die in selbstgehosteten Umgebungen standardmäßig aus sind. Die allgemeinen Claude Code-Telemetrie-Steuerelemente, `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_ERROR_REPORTING` und `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, gelten für Session-Kinder wie in der [Umgebungsvariablen-Referenz](/docs/de/env-vars) dokumentiert. `DISABLE_GROWTHBOOK` ist verwandt, aber anders: Das Setzen von `DISABLE_GROWTHBOOK=1` deaktiviert das Abrufen von Feature-Flags, und die Telemetrie bleibt an, es sei denn, `DISABLE_TELEMETRY` ist auch gesetzt.
`CLAUDE_CODE_ENABLE_TELEMETRY` ist nicht verwandt: Es aktiviert OpenTelemetry-Export zu Ihrem eigenen Collector, wie in [Überwachung](/docs/de/monitoring-usage) beschrieben, und steuert nicht Anthropics Analytik.
Health-Endpunkt
Der Runner bedient `GET /healthz` auf dem konfigurierten Health-Port. Die Antwort ist `200 OK`, wann immer der Prozess am Leben ist, unabhängig davon, in welchem Zustand sich die Abfrageschleife befindet, sodass ein HTTP-Probe auf diesem Endpunkt nur einen toten Prozess erkennt. Der JSON-Body beschreibt den aktuellen Zustand:
```json theme={null}
{
"status": "ok",
"runner_id": "ccrunner_...",
"active_sessions": 2,
"last_poll_at": "2026-03-31T18:04:11.220Z",
"last_poll_age_ms": 842
}
```
Verwenden Sie `last_poll_age_ms` als Lebendigkeitssignal in benutzerdefinierten Proben; ein Wert, der unbegrenzt wächst, zeigt an, dass die Abfrageschleife steckt. Sowohl `last_poll_at` als auch `last_poll_age_ms` sind `null`, bis die erste Abfrage abgeschlossen ist.
Der Orchestrator bedient sein eigenes `/healthz` auf seinem Health-Port. Sein Endpunkt gibt immer `200` zurück, und der Body trägt ein Feld `connected`, das meldet, ob die letzte Abfrage erfolgreich war, plus Pro-Status-Spawn-Queue-Zählungen in `queue_counts`. Gate-Bereitschaft und Warnungen auf `connected` statt auf dem Statuscode.
Wenn der [SCM-Connector](#scm-connector-flags) konfiguriert ist, trägt der Body des `/healthz` des Orchestrators auch `scm_connector_connected` und ein Objekt `scm_connector` mit `connected`, `last_connected_at`, `last_error`, `reconnects` und `requests_forwarded`. Beide Felder sind `null`, wenn `--scm-connector-host` nicht gesetzt ist.
Prometheus-Metriken
Jeder Runner bedient Prometheus-Metriken bei `GET /metrics` auf demselben Port wie `/healthz`. Wichtige Reihen:
| Reihe | Notizen |
| :-------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `claude_code_self_hosted_runner_info{runner_id,version,client_label}` | Immer `1`; nützlich für Fleet-Inventar und Versions-Drift-Erkennung |
| `claude_code_self_hosted_runner_capacity` | Konfiguriert `--capacity` |
| `claude_code_self_hosted_runner_active_sessions` | Sitzungen, die derzeit laufen |
| `claude_code_self_hosted_runner_locked_account{email}` | Vorhanden, sobald sich der Runner auf einen Benutzer gesperrt hat und ein Session-Token mit einem `act.email` Anspruch ausgestellt wurde. Die Reihe fehlt auf einem Runner, der auf einen Claude Tag-Agent gesperrt ist, dessen Session-Tokens keinen `act.email` Anspruch tragen. Der Labelwert ist die Konto-E-Mail; wenn Ihr Metrik-Store weit lesbar ist, löschen oder hashen Sie das Label zum Scrape-Zeitpunkt, zum Beispiel mit Prometheus `metric_relabel_configs`. |
| `claude_code_self_hosted_runner_last_poll_age_seconds` | Sekunden seit der letzten erfolgreichen Abfrage. Warnung, wenn über 60. |
| `claude_code_self_hosted_runner_poll_errors_total{error_kind}` | Kumulative PollWork-Fehler nach Art: `transport`, `timeout`, `5xx`, `429` oder `4xx`. Alle fünf Reihen sind vom Prozessstart vorhanden; Warnung bei `rate(...[5m]) > 0`. |
| `claude_code_self_hosted_runner_sessions_started_total{client_platform}` | Session-Kindprozesse, die über die Lebensdauer des Runners erzeugt wurden, eine Reihe pro Session-Ursprung wie `web_claude_ai`, `ios`, `android`, `desktop_app` oder `claude_code_cli`, oder `unknown`, wenn der Server einen nicht gesendet hat. Slack-Sitzungen tragen entweder `claude_in_slack` oder `claude-in-slack`, je nachdem, welche Slack-Integration sie erstellt hat, also passen Sie beide mit einem Regex-Selektor wie `{client_platform=~"claude[-_]in[-_]slack"}` an. Verwenden Sie `sum()` für die Fleet-Summe. |
| `claude_code_self_hosted_runner_sessions_completed_total{client_platform}` | Sitzungen, die sauber endeten, mit denselben Labels. Breiter als ein einfacher sauberer Ausstieg: siehe [Session-Lebenszyklus-Zähler-Semantik](#session-lifecycle-counter-semantics) für das, was zählt. |
| `claude_code_self_hosted_runner_sessions_failed_total{client_platform}` | Sitzungen, die in Fehler endeten, mit denselben Labels. Gleicher Vorbehalt: siehe [Session-Lebenszyklus-Zähler-Semantik](#session-lifecycle-counter-semantics). |
| `claude_code_self_hosted_runner_sessions_interrupted_total{client_platform}` | Sitzungen, die der Runner aus operativen Gründen beendete, anstatt aus einem Session-Ergebnis oder Runner-Fehler, mit denselben Labels. Siehe [Session-Lebenszyklus-Zähler-Semantik](#session-lifecycle-counter-semantics). |
| `claude_code_self_hosted_runner_initializing_sessions` | Sitzungen, die sich derzeit in der Init-Phase befinden, von der Zuweisung bis zum Init-Ereignis des Kindes |
| `claude_code_self_hosted_runner_session_init_duration_seconds` | Histogramm der Session-Init-Dauern |
| `claude_code_self_hosted_runner_session_init_errors_total` | Sitzungen, die vor Erreichen von Init fehlschlugen: ein Checkout-Hook-Fehler, Git-Vorbereitung, Token-Problem oder ein Pre-Init-Kind-Crash |
| `claude_code_self_hosted_runner_session_start_hook_errors_total` | `SessionStart` Hooks, die ein Fehler-Ergebnis meldeten, einer pro fehlgeschlagener Hook-Ausführung |
| `claude_code_self_hosted_runner_session_idle_seconds{session_id,client_platform}` | Pro-Session-Gauge von Sekunden, seit die Sitzung untätig wurde. Nützlich zum Beenden von Sitzungen, die auf einer unbeantworteten Berechtigungsaufforderung stecken. |
Der Orchestrator bedient seine eigenen Reihen bei `GET /metrics` auf demselben Port wie sein `/healthz`:
| Reihe | Notizen |
| :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `claude_code_self_hosted_orchestrator_info{version,pool_id,orchestrator_uuid,hostname}` | Immer `1` |
| `claude_code_self_hosted_orchestrator_connected` | `1`, wenn die letzte Abfrage erfolgreich war; fällt auf `0` nach jeder fehlgeschlagenen Abfrage, unabhängig von der Fehlerart |
| `claude_code_self_hosted_orchestrator_last_poll_age_seconds` | Sekunden seit dem letzten Abfrageversuch, Erfolg oder Fehler, anders als die identisch benannte Metrik des Runners, die seit dem letzten Erfolg misst; koppeln Sie mit `connected`, um fehlgeschlagene Abfragen zu erfassen. Die Abfrageschleife des Orchestrators wartet auf Hook-Ausführung, also Warnung über `--hook-timeout` plus eine Marge, etwa 90 Sekunden bei Standardwerten, anstatt einer flachen 60. |
| `claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}` | Kumulative PollSpawnHints-Fehler nach Art: `transport`, `timeout`, `5xx`, `429` oder `4xx`. Alle fünf Reihen sind vom Prozessstart vorhanden; Warnung bei `rate(...[5m]) > 0`. |
| `claude_code_self_hosted_orchestrator_queue_pending_sessions` | Spawn-Anfragen, die jetzt beanspruchbar sind |
| `claude_code_self_hosted_orchestrator_queue_backing_off_sessions` | Spawn-Anfragen in Retry-Backoff nach einem wiederholbaren Hook-Fehler |
| `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions` | Spawn-Anfragen, die blockiert sind, bis ein Owner sie von der Registerkarte **Aktivität** der Umgebung erneut versucht; Warnung, wenn über Null |
| `claude_code_self_hosted_orchestrator_pool_pending_sessions` | Gesamtsitzungen, die auf einen Runner für diese Umgebung warten. Umgebungsweites Aggregat, identisch auf jeder Orchestrator-Instanz: Verwenden Sie `MAX` statt `SUM` über Instanzen. |
| `claude_code_self_hosted_orchestrator_pool_active_sessions` | Sitzungen, die derzeit einem lebenden Runner in dieser Umgebung zugewiesen sind. Umgebungsweites Aggregat, identisch auf jeder Orchestrator-Instanz: Verwenden Sie `MAX` statt `SUM` über Instanzen. |
| `claude_code_self_hosted_orchestrator_spawn_hooks_total{result}` | Kumulative `spawn-runner` Hook-Ergebnisse: `ok`, `retryable`, `non_retryable`. Zählt Orchestrator-Hook-Aufrufe, nicht Session-Kinder, die die Runner erzeugen: nicht vergleichbar mit `sessions_started_total`, da Kapazität über eins, warme Pools und Runner, die erneut für dieselbe Sitzung erzeugt werden, die beiden divergieren. |
| `claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds` | Histogramm der Hook-Dauern |
| `claude_code_self_hosted_orchestrator_warm_hints_dispatched_total` | Standby-Spawn-Anfragen, die seit Prozessstart versendet wurden |
| `claude_code_self_hosted_orchestrator_session_queue_wait_seconds` | Histogramm von Sekunden, die jede Sitzung in der Warteschlange wartete, bevor der Orchestrator sie zum Erzeugen beanspruchte, aufgezeichnet vom Queue-Wait-Zeitstempel, den die Kontrolleben mit jeder Spawn-Anfrage der Sitzung sendet. Verwenden Sie für p50/p99 Queue-Zeit-Warnungen. Vorwärm-Spawns werden nicht gesampelt. |
| `claude_code_self_hosted_orchestrator_clock_skew_seconds` | Lokale-minus-Server-Uhr-Skew; diagnostisch, vorhanden, sobald gemessen |
| `claude_code_self_hosted_orchestrator_scm_connector_connected` | `1`, wenn der [SCM-Connector](#scm-connector-flags) WebSocket offen ist; `0` während Wählen oder Backoff. Fehlt, wenn `--scm-connector-host` nicht gesetzt ist. |
| `claude_code_self_hosted_orchestrator_scm_connector_requests_forwarded_total` | Kumulative HTTP-Anfragen, die seit Prozessstart zum konfigurierten SCM-Host weitergeleitet wurden. Fehlt, wenn `--scm-connector-host` nicht gesetzt ist. |
Für Autoscaling wählen Sie die Reihe, die zu Ihrem Skalierungsstil passt, und gaten Sie sie, bevor sie den Scaler speist:
* **Queue-Tiefe-Skalierung**: Speisen Sie `claude_code_self_hosted_orchestrator_pool_pending_sessions` in Ihren HPA- oder KEDA-Scaler, nicht `queue_pending_sessions`.
* **Kapazitäts-Skalierung**: Skalieren Sie auf das Verhältnis der `active_sessions` des Runners zu `capacity`.
* **Gate auf `connected`**: Filtern Sie die Abfrage mit `claude_code_self_hosted_orchestrator_connected == 1` pro Instanz, sodass der veraltete Wert eines getrennten Replikas nicht den Scaler speist.
Während eines vollständigen Abfrageausfalls, jedes Replikat getrennt, gibt die gated-Abfrage keine Daten zurück. HPA hält die aktuelle Replikaanzahl bei einer fehlenden Metrik, aber KADAs Prometheus-Scaler bei seinem Standard `ignoreNullValues: "true"` liest das leere Ergebnis als Null und skaliert ein; setzen Sie `ignoreNullValues: "false"` auf dem ScaledObject, optional mit einem `fallback` Replikafloor.
Der folgende Prometheus Operator `PodMonitor` deckt beide Prozesse ab. Er wählt Pods nach dem Label `app.kubernetes.io/part-of: claude-code-self-hosted-runner` und dem benannten Port `health`, den das [Kubernetes-Rezept](/docs/de/self-hosted-environments-deploy#kubernetes) setzt; passen Sie die Namespaces an Ihre Bereitstellung an:
```yaml theme={null}
# Beispiel Prometheus Operator PodMonitor für den Claude Code Self-Hosted
# Runner + Orchestrator. Passen Sie die Namespace- und Label-Selektoren an Ihre
# Bereitstellung an. Sowohl der Runner als auch der Orchestrator bedienen /metrics auf
# ihrem --health-port (Standard 8080).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
name: claude-code-self-hosted-runner
namespace: monitoring
spec:
namespaceSelector:
matchNames:
- claude-runners
selector:
matchExpressions:
# Passt die Runner-Bereitstellung aus dem Kubernetes-Rezept sowie alle
# On-Demand-Runner-Jobs und Orchestrator-Pods an, die Sie gleich beschriften
# und einen benannten 'health' containerPort geben.
- key: app.kubernetes.io/part-of
operator: In
values: [claude-code-self-hosted-runner]
podMetricsEndpoints:
- port: health
path: /metrics
interval: 30s
```
Diese Beispiel-Warnregeln sind ein Ausgangspunkt; stimmen Sie die Schwellwerte für Ihre Fleet-Größe ab:
```yaml theme={null}
# Beispiel Prometheus-Warnregeln für den Claude Code Self-Hosted Runner
# + Orchestrator. Stimmen Sie die Schwellwerte für Ihre Fleet-Größe und SLOs ab.
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 }} hat nicht in >60s abgefragt"
- alert: ClaudeRunnerVersionDrift
expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
for: 30m
labels: {severity: info}
annotations:
summary: "Runner führen gemischte Versionen aus"
- 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-Fehler in 10m (Checkout-Hook / Git / Token / Pre-Init-Kind-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 fehlgeschlagen ({{ $value | humanize }}/s über 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-Fehler 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 }} kann die Anthropic-Kontrolleben nicht erreichen"
- alert: ClaudeOrchestratorPollStale
expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
for: 2m
labels: {severity: warning}
annotations:
summary: "Orchestrator {{ $labels.pod }} hat nicht in >90s abgefragt (Abfrageschleife wartet auf Hook-Ausführung)"
- alert: ClaudeOrchestratorCircuitBroken
expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0
for: 1m
labels: {severity: critical}
annotations:
summary: "{{ $value }} Sitzungen unterbrochen — spawn-runner Hook ist wiederholt nicht wiederholbar; beheben Sie die Infrastruktur und versuchen Sie es erneut von der Registerkarte Aktivität"
- 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 fehlgeschlagen ({{ $value | humanize }}/s über 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-Fehler in 5m"
```
Durchlauf-Session-Kind-Metriken
Jede Sitzung läuft in ihrem eigenen Kind-Prozess mit ihren eigenen OpenTelemetry-Metriken; bei `--capacity` über eins schreibt der Runner um, wie diese Kind-Metriken verfügbar gemacht werden. Das Setzen von `OTEL_METRICS_EXPORTER=prometheus` auf dem Runner-Host und `CLAUDE_CODE_ENABLE_TELEMETRY=1` in der Umgebung der Sitzung, zum Beispiel aus Ihrem [Wrapper-Skript](/docs/de/self-hosted-environments-configuration#wrapper-scripts) oder der Umgebung des Runners selbst, die Sitzungen erben, macht die Zähler- und Gauge-Instrumente jedes Kindes auf dem `/metrics` Endpunkt des Runners erneut verfügbar, neben den Reihen des Runners. Der Runner schreibt den Exporter des Kindes um, um über OTLP zu einem Loopback-only-Receiver auf dem Health-Port zu pushen, markiert jede Reihe mit `session_id`- und `client_platform`-Labels und entfernt die Reihen einer Sitzung, wenn diese Sitzung endet. Histogramme gehen nicht durch, und eine Kind-Metrik, deren Name mit dem eigenen Präfix des Runners kollidieren würde, wird gelöscht.
Bei der Standard `--capacity 1` gilt die Umschreibung nicht: Das Kind des Kindes bindet seinen eigenen Prometheus-Endpunkt auf Port 9464 wie üblich.
Session-Lebenszyklus-Zähler-Semantik
Die Zähler `sessions_started_total`, `sessions_completed_total`, `sessions_failed_total` und `sessions_interrupted_total` klassifizieren jede Sitzung danach, wie sie endete. Jedes erzeugte Session-Kind erhöht `sessions_started_total` zum Spawn-Zeitpunkt, und genau einer der anderen drei erhöht sich beim Beenden, sodass `sessions_started_total` minus die Summe der anderen drei der Anzahl der derzeit laufenden Session-Kinder entspricht.
* `completed`: Die Sitzung endete sauber. Dies deckt das Kind ab, das auf eigene Faust mit Code `0` beendet wird, die Sitzung wird archiviert oder gelöscht, während das Kind noch verbunden war, und der Runner gibt den Slot sauber zurück: Freigabe der Sitzung beim Idle-Timeout, zur Retire-Zeit oder am `--kill-session-after-min` Limit; ein Startup-Timeout; oder ein serverseitiges Deassign, das die Abfrageschleife bemerkte, bevor das Kind beendet wurde. Erhöht `sessions_completed_total`.
* `failed`: Das Kind beendete sich auf eigene Faust mit einem Nicht-Null-Code, entweder ein Crash oder ein Setup-Fehler nach dem Erzeugen. Erhöht `sessions_failed_total`.
* `interrupted`: Der Runner beendete das Kind aus operativen Gründen, die weder ein Session-Erfolg noch ein Runner-Fehler sind, wie eine Entleerung oder die Beendigung einer Sitzung, die sich noch auf dem Runner befand, wenn das [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](#environment-variable-only-settings) Kulanzfenster nach seinem `--kill-session-after-min` Limit endete. Ein Kubernetes-Rolling-Restart, der `SIGTERM` sendet, ist ein Beispiel für eine Entleerung. Erhöht `sessions_interrupted_total`.
Vor v2.1.260 beendete der Runner jede Sitzung, die ihr `--kill-session-after-min` Limit erreichte, und zählte sie in `sessions_interrupted_total`.
Der [`post-session` Hook](/docs/de/self-hosted-environments-configuration#post-session) `CLAUDE_RUNNER_EXIT_REASON` klassifiziert saubere Übergaben unterschiedlich. Der Hook meldet eine Freigabe, ein Startup-Timeout und eine Server-Deassign als `interrupted`, da der Runner das Kind stoppte. Diese Zähler zeichnen die gleichen Ereignisse als `completed` auf, da der Slot sauber zurückgegeben wurde.
Wenn Sie Hook-Quittungen direkt gegen `sessions_completed_total` abstimmen, unterzählen Sie Abschlüsse. Verwenden Sie den Hook für Pro-Session-Garantien und die Zähler für Aggregatraten.
In einer One-Shot-Umgebung, `--capacity 1` mit dem Standard `--drain-grace-sec 0`, beendet sich jeder Runner-Prozess Momente nach seiner einen Sitzung endet. `sessions_completed_total`, `sessions_failed_total` und `sessions_interrupted_total` erhöhen sich nur beim Session-Ende, direkt bevor dieser Ausstieg, sodass ein Prometheus-Scrape alle 15 bis 60 Sekunden die Erhöhung selten erfasst, bevor die Reihen des Runners verschwinden; diese drei End-of-Session-Zähler sind die Terminal-Zähler, auf die sich der Rest dieses Abschnitts bezieht. `sessions_started_total` erhöht sich beim Erzeugen und bleibt für die Lebensdauer der Sitzung sichtbar, sodass es zuverlässig angezeigt wird, aber in einer One-Shot-Umgebung liest es näher an "Sitzungen, die derzeit laufen" als an einer kumulativen Anzahl.
Verwenden Sie die Reihe in dieser Tabelle für das entsprechende Ziel statt der Terminal-Zähler:
| Ziel | Verwenden |
| :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Durchsatz | `claude_code_self_hosted_orchestrator_spawn_hooks_total{result="ok"}`, ein Zähler auf dem langlebigen Orchestrator, der sich einmal pro erfolgreichem `spawn-runner` Hook erhöht und unter `rate()` aussagekräftig bleibt. Er zählt Hook-Aufrufe statt Sitzungen, sodass Vorwärmung und wiederholte Spawns für dieselbe Sitzung ihn von Session-Zählungen divergieren. |
| Auslastung | `sum(claude_code_self_hosted_runner_active_sessions)` gegen `sum(claude_code_self_hosted_runner_capacity)`, beide Gauges gültig bei jedem Scrape unabhängig von der Runner-Lebensdauer |
| Rückstand | `claude_code_self_hosted_orchestrator_pool_pending_sessions` für Queue-Tiefe und `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions`, Warnung, wenn über Null |
| Fehler | `claude_code_self_hosted_runner_sessions_failed_total`, Best-Effort: echte Crashes nach dem Erzeugen erhöhen ihn, und `rate()` ist aussagekräftig auf Runnern, die ihre Sitzungen mit `--drain-grace-sec` über `0` überleben. Eine One-Shot-Umgebung hat das gleiche Scrape-Fenster-Problem wie die anderen Terminal-Zähler, also behandeln Sie jeden Nicht-Null-Wert, den Sie sehen, als wert, untersucht zu werden. Fehler vor dem Erzeugen, wie ein Checkout-Hook-Fehler, Git-Vorbereitung oder ein Token-Problem, erscheinen nur in `session_init_errors_total`. |
Die `orchestrator_*` Zeilen existieren nur auf Umgebungen, die den [On-Demand-Orchestrator](/docs/de/self-hosted-environments-configuration#on-demand-runners) ausführen. In einer festen Fleet, deren Runner ihre Sitzungen mit `--drain-grace-sec` über `0` überleben, verwenden Sie `sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m]))` für Durchsatz; in einer One-Shot-Fleet hat diese Reihe das gleiche Scrape-Fenster-Problem wie die Terminal-Zähler, also verlassen Sie sich stattdessen auf die Zählung der Sitzungen in der Warteschlange. Überprüfen Sie den Rückstand auf der Registerkarte **Aktivität** der Umgebung, auf der [**Cloud-Umgebungen**-Administratorseite](https://claude.ai/admin-settings/cloud-environments): Die Runner exportieren keine Queue-Tiefe-Reihe.
Für Pro-Session-Ergebnis-Berichterstattung verwenden Sie stattdessen den [`post-session` Hook](/docs/de/self-hosted-environments-configuration#post-session): Er wird bei jedem Session-Ende ausgelöst, wo ein Kind-Prozess erzeugt wurde, abgesehen von abruptem Runner-Beendigung wie eine VM-Preemption, pro dem [eigenen Vertrag des Hooks](/docs/de/self-hosted-environments-configuration#post-session).
Nächste Schritte
* [Selbstgehostete Umgebungen](/docs/de/self-hosted-environments): die Umgebung, den Runner und das Session-Modell; der [Schnellstart](/docs/de/self-hosted-environments-quickstart) und [In die Produktion bereitstellen](/docs/de/self-hosted-environments-deploy) enthalten Einrichtung und Betrieb
* [Passen Sie Sitzungen an](/docs/de/self-hosted-environments-configuration): Wrapper-Skripte, Lifecycle-Hooks und On-Demand-Runner
* [Überprüfen Sie die Session-Identität](/docs/de/self-hosted-environments-identity): das Session-Token, seine Ansprüche und wie man es überprüft