SpyBara
Go Premium

self-hosted-environments-configuration.md 2026-10-01 23:59 UTC to 2026-10-02 22:59 UTC

This page contains 180 additions and 42 deletions.

2026
Fri 2 22:59

Sitzungen in selbstgehosteten Umgebungen anpassen

Passen Sie selbstgehostete Umgebungssitzungen mit Wrapper-Skripten für Anmeldedaten pro Sitzung, Lifecycle-Hooks und On-Demand-Runner-Spawning an.

Eine selbstgehostete Umgebung führt Claude Code Cloud-Sitzungen auf Ihrer eigenen Infrastruktur aus, ausgeführt durch einen Runner-Prozess, den Sie bereitstellen. Ohne Konfiguration klont dieser Runner das Repository der Sitzung, startet Claude Code und räumt auf. Diese Seite ist für den Plattformingenieur, der die Runner betreibt: Sie behandelt die Erweiterungspunkte für den Fall, dass diese Standardeinstellungen nicht passen, von der Bereitstellung von Anmeldedaten pro Sitzung bis zum vollständigen Ersetzen des Checkouts. Wrapper und Hooks werden als ausführbare Dateien auf dem Runner-Host ausgeführt, bei dem es sich um Linux oder macOS handelt, und die Beispiele auf dieser Seite gehen von einer POSIX-Shell aus.

Einige Hook-Umgebungsvariablen auf dieser Seite verwenden noch pool, wie CLAUDE_RUNNER_POOL_ID; die CLI-Flag- und Umgebungsvariablennamen verwenden environment, wie --environment-secret-file.

Wrapper-Skripte

Verwenden Sie ein Wrapper-Skript, wenn jede Sitzung eine Einrichtung benötigt, die der Runner nicht selbst durchführen kann: Bereitstellung kurzlebiger Anmeldedaten mit Bereich auf den Sitzungsersteller, Export umgebungsspezifischer Geheimnisse, Vorbereitung von Sprach-Toolchains oder Anwendung von Ressourcenlimits um den untergeordneten Prozess. Der Runner startet Ihren Wrapper anstelle der Claude Code-Binärdatei, einmal pro Sitzung. Beenden Sie den Wrapper durch exec in $CLAUDE_RUNNER_CLAUDE_BIN, die eigene Binärdatei des Runners, damit Signale und Exit-Codes korrekt weitergegeben werden.

Zeigen Sie --exec-path oder SELF_HOSTED_RUNNER_EXEC_PATH auf den Wrapper, wenn Sie den Runner starten:

claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh

Der Runner setzt Folgendes in der Umgebung des Wrappers:

Variable Beschreibung
CLAUDE_CODE_SESSION_ACCESS_TOKEN Das Sitzungs-JWT, mit dem Präfix sk-ant-cc-. Sein act-Anspruch identifiziert den Sitzungsersteller, mit der E-Mail des Erstellers, wenn die erstellende Oberfläche diese aufgezeichnet hat. Der Wert ist das Token zum Zeitpunkt des Spawning; Aktualisierungen kommen über stdin des Kindes an, daher sieht ein Wrapper nur den Anfangswert. Siehe Sitzungsidentität überprüfen.
CCR_SESSION_ACCOUNT_EMAIL Die E-Mail des Sitzungserstellers, vom Runner aus dem act.email-Anspruch des Tokens ohne Signaturüberprüfung vorab extrahiert. Geeignet für Beschriftung, wie Commit-Trailer. Wenn die E-Mail die Ausstellung von Anmeldedaten steuert, überprüfen Sie das Token und lesen Sie den Anspruch stattdessen daraus; siehe Anmeldedaten mit Bereich auf den Sitzungsersteller bereitstellen. Nicht gesetzt, wenn das Token keine Ersteller-E-Mail enthält. Behandeln Sie als personenbezogene Informationen.
CLAUDE_RUNNER_CLIENT_PLATFORM Die Client-Oberfläche, die die Sitzung erstellt hat, wie web_claude_ai, desktop_app, ios, claude_code_cli oder scheduled_trigger. Anthropic zeichnet den Wert einmal bei der Sitzungserstellung auf, daher sehen der Wrapper und jeder Lifecycle-Hook denselben Wert. Verwenden Sie ihn nur für Adoptionsanalysen und Beschriftung, nicht als Autorisierungssignal. Nicht gesetzt, wenn die Sitzung keine aufgezeichnete oder erkannte Oberfläche hat, daher referenzieren Sie sie als ${CLAUDE_RUNNER_CLIENT_PLATFORM:-} unter set -u. Erfordert Claude Code v2.1.229 oder später.
CLAUDE_RUNNER_CLAUDE_BIN Absoluter Pfad zur eigenen Claude Code-Binärdatei des Runners. Beenden Sie Ihren Wrapper mit exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", um an die angeheftete Binärdatei zu übergeben, ohne einen Installationspfad hartcodieren zu müssen.
CLAUDE_CODE_REMOTE_SESSION_ID Sitzungs-ID in der getaggten Form cse_.... Dies ist dieselbe Sitzung, die die Lifecycle-Hooks als CLAUDE_RUNNER_SESSION_ID in der Form session_... sehen; die UUID-Variablen stimmen über beide überein, und das Ersetzen des Präfixes cse_ durch session_ ergibt die in der Sitzungs-URL angezeigte ID.
CLAUDE_CODE_REMOTE_SESSION_UUID Dieselbe Sitzungs-ID in kanonischer UUID-Form, für Systeme, die auf UUIDs basieren.
CLAUDE_SESSION_INGRESS_TOKEN_FILE Absoluter Pfad zu einer pro-Sitzungs-Datei, die das aktuelle Sitzungs-JWT enthält, das über Token-Aktualisierungen hinweg aktuell gehalten wird. Shell-Unterprozesse lesen es für ihren Authorization-Header beim Herunterladen von Anhängen, die der Benutzer zur Sitzung hinzugefügt hat. exec bewahrt die Variable automatisch; ein Wrapper, der die Umgebung des Kindes neu erstellt, muss die Variable übertragen, oder Anhang-Downloads funktionieren stillschweigend nicht mehr.
CLAUDE_CONFIG_DIR Pro-Sitzungs-Claude-Konfigurationsverzeichnis, geschrieben beim Sitzungsstart aus dem Snapshot der Konfiguration des Runner-Hosts, den der Runner beim Startup erfasst; siehe Berechtigungen und Tool-Genehmigung. Schreibvorgänge hier sind auf diese Sitzung isoliert. Das Verzeichnis bleibt unter <base-dir>/_sessions/ nach dem Sitzungsende, es sei denn, Sie starten den Runner mit --remove-session-state; siehe Einen vorgewärmten Checkout wiederverwenden.
ANTHROPIC_BASE_URL Die API-Basis-URL, die das Kind verwendet, bereitgestellt von der Kontrollebene pro Sitzung und normalerweise https://api.anthropic.com. Überschreiben Sie sie nicht: Die Inferenz-Anmeldedaten der Sitzung sind ein von Anthropic ausgegebenes OAuth-Token, das andere Anbieter nicht akzeptieren.
CLAUDE_CODE_OAUTH_TOKEN Das kurzlebige OAuth-Zugangstoken, das das Kind für Modell-Inferenz verwendet, mit Bereich auf Modell-Inferenz und Datei-Upload nur, mit einer Lebensdauer von etwa 30 Minuten. Der Runner prägt es vor Ablauf neu und liefert die Rotation über stdin des Kindes, daher sieht ein Wrapper, der stdin nicht angehängt hält, nur den Anfangswert. Verlassen Sie sich nicht auf die IP-Allowlist Ihrer Organisation, um die Verwendung dieses Tokens zu begrenzen: Behandeln Sie es als Bearer-Anmeldedaten, die etwa 30 Minuten lang verwendbar bleiben, wenn sie durchsickern, und protokollieren Sie es nicht, schreiben Sie es nicht auf die Festplatte oder leiten Sie es außerhalb des Sitzungs-Containers weiter.

Der Wrapper erbt auch den Rest der verwalteten Umgebung des Kindes, einschließlich aller vom Server bereitgestellten Umgebungsvariablen. exec propagiert alles automatisch; wenn Ihr Wrapper das Kind auf andere Weise startet, leiten Sie die vollständige Umgebung weiter.

Halten Sie stdin und Dateideskriptor 3 angehängt

Stdin des Kindes ist der Steuerkanal des Runners. Token-Rotationen und Sitzungsend-Signale kommen darauf an. Der Runner öffnet auch eine Pipe auf Dateideskriptor 3 und liest die Aktivitätssignale des Kindes daraus, um Idle- und Startup-Timeouts zu steuern. Ein einfaches exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" bewahrt beide automatisch.

Wenn Ihr Wrapper das Kind mit einem bloßen & in den Hintergrund versetzt, trennt es stdin des Kindes: Die Sitzung sieht gesund aus, bis die Lebensdauer des anfänglichen OAuth-Tokens von etwa 30 Minuten abläuft, dann schlagen alle API-Aufrufe mit 401 authentication_error fehl. Wenn Ihr Wrapper das Kind in den Hintergrund versetzen muss, zum Beispiel um eine Teardown-Falle am Leben zu erhalten, speichern Sie stdin auf Dateideskriptor 4 oder höher und hängen Sie ihn explizit wieder an:

exec 4<&0
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&4 4<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

Schließen oder verwenden Sie Dateideskriptor 3 im Wrapper nicht erneut. Das Umleiten von stdout und stderr des Kindes ist in Ordnung.

System-Prompt-Flags durchreichen

Der System-Prompt und der angehängte System-Prompt, die die Kontrollebene von Anthropic für eine Sitzung sendet, erreichen Ihren Wrapper als Dateipfade, nicht als Inline-Text. Der Runner schreibt jeden Prompt in eine Datei im Konfigurationsverzeichnis der Sitzung, CLAUDE_CONFIG_DIR, und übergibt deren Pfad in den Argumenten, die Ihr Wrapper erhält, als --system-prompt-file <path> oder --append-system-prompt-file <path>.

Runner ab Claude Code v2.1.281 liefern die Prompts als Dateien. Vor v2.1.281 übergab der Runner sie als --system-prompt <text> und --append-system-prompt <text>.

Behandeln Sie diese Flags in Ihrem Wrapper-Skript oder command-Hook wie folgt:

  • Reichen Sie sie durch: Beenden Sie den Wrapper mit exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", wodurch die Datei-Flags zusammen mit allen anderen Argumenten weitergeleitet werden. Entfernen oder ändern Sie sie nicht. Wenn einer Sitzung ein Prompt-Datei-Flag verloren geht, läuft sie ohne die Anweisungen, die die Kontrollebene für sie gesendet hat.
  • Auf einem Runner ab v2.1.281 ersetzt ein von Ihnen angehängtes Datei-Flag das des Servers, statt es zu ergänzen: Jedes Prompt-Datei-Flag nimmt einen einzelnen Wert an, und Claude Code behält das letzte Vorkommen. Wenn Sie also --append-system-prompt-file <path> nach "$@" anhängen, ersetzt der Inhalt Ihrer Datei die angehängten Anweisungen des Servers. Um Anweisungen zusätzlich zu denen des Servers hinzuzufügen, legen Sie sie in der CLAUDE.md des Runner-Images ab, die der Runner in die Konfiguration auf Benutzerebene jeder Sitzung einspielt.

Anmeldedaten mit Bereich auf den Sitzungsersteller bereitstellen

Verwenden Sie den Unterbefehl decode-token, um Ansprüche aus dem Sitzungs-JWT zu lesen. Er liest das Token aus einem Argument, aus CLAUDE_CODE_SESSION_ACCESS_TOKEN oder aus stdin, in dieser Reihenfolge; siehe Token innerhalb der Sitzung überprüfen für das, was es überprüft. Das folgende Beispiel dekodiert die Ersteller-Identität, tauscht sie gegen kurzlebige AWS-Anmeldedaten aus und führt in Claude Code aus:

#!/bin/bash
# Basieren Sie auf der stabilen Anthropic-Benutzer-ID und erfordern Sie einen menschlichen Ersteller.
CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \
  | jq -re '.act.sub // "" | select(startswith("user:"))') \
  || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \
  || { echo "credential exchange failed" >&2; exit 1; }
eval "$creds"

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

Verwenden Sie jq -re anstelle von jq -r, wenn der extrahierte Anspruch eine Autorisierungsentscheidung steuert, damit ein fehlender Anspruch ungleich Null endet, anstatt die Literalzeichenfolge null nachgelagert zu übergeben. Sitzungen, die von einer Organisationsservice-Identität erstellt wurden, wie Bot- und Agent-Sitzungen, tragen einen agent:-Betreff anstelle von user:, daher lehnt dieses Beispiel sie ab; wenn Ihre Umgebung diese Sitzungen bedient, entscheiden Sie explizit, ob der Wrapper stattdessen auf eine Standard-Anmeldedaten zurückfällt oder beendet wird. Wenn Ihr Anmeldedatenaustausch stattdessen die E-Mail benötigt, lesen Sie .act.email und behandeln Sie deren Abwesenheit: Das Token trägt sie nur, wenn die erstellende Oberfläche sie aufgezeichnet hat, und einer CLI-versandten Sitzung kann sie fehlen. Für die vollständige Anspruchsreferenz und Überprüfung von Diensten außerhalb des Runners siehe Sitzungsidentität überprüfen.

Lifecycle-Hooks

Lifecycle-Hooks ersetzen Phasen der Pro-Sitzungs-Pipeline des Runners durch Ihre eigenen Skripte. Zeigen Sie den Runner mit --hooks-dir <path> oder SELF_HOSTED_RUNNER_HOOKS_DIR auf ein Verzeichnis von Hooks. Der Runner sucht nach ausführbaren Dateien mit bekannten Namen; jeder Hook, der nicht vorhanden ist, fällt auf das integrierte Verhalten zurück, daher schreiben Sie nur die, die Sie benötigen. Hooks werden mit den eigenen Berechtigungen des Runners ausgeführt, und Sitzungskinder teilen diese UID, daher mounten Sie das Hooks-Verzeichnis schreibgeschützt oder backen Sie es in das Image, damit Sitzungscode es nicht ändern kann; siehe den Härtungsabschnitt.

Diese Hooks unterscheiden sich von Claude Code-Hooks, die innerhalb der Sitzung ausgeführt werden; Lifecycle-Hooks werden auf dem Runner um die Sitzung herum ausgeführt.

checkout

Wird einmal pro Repository anstelle des integrierten Klons und Abrufs des Runners ausgeführt. Verwenden Sie den Hook, um von einem Read-Through-Mirror zu klonen, einen Arbeitsbaum aus einem Archiv zu seeden oder Pro-Sitzungs-Git-Authentifizierung anzuwenden. Der Runner setzt diese Variablen und kann weitere CLAUDE_RUNNER_-Variablen setzen, die die Tabelle nicht aufführt:

Variable Beschreibung
CLAUDE_RUNNER_REPO_URL Repository-URL zum Klonen, nachdem alle --git-host-rewrite und --git-ssh-rewrite angewendet wurden
CLAUDE_RUNNER_REPO_REF Revision zum Auschecken: Branch, Tag oder Commit-SHA, wie die Sitzung sie angefordert hat. Leer bedeutet den Standard-Branch des Repositorys.
CLAUDE_RUNNER_CHECKOUT_PATH Absoluter Pfad, wo der Arbeitsbaum hinterlassen werden muss
CLAUDE_RUNNER_SESSION_ID Sitzungs-ID in der getaggten Form session_..., für Protokollierung und Korrelation
CLAUDE_RUNNER_SESSION_UUID Dieselbe Sitzungs-ID in kanonischer UUID-Form
CLAUDE_RUNNER_API_BASE_URL Anthropic-API-Basis-URL für Sitzungs-bezogene Aufrufe
CLAUDE_RUNNER_CLIENT_PLATFORM Die Client-Oberfläche, die die Sitzung erstellt hat, wie web_claude_ai, desktop_app oder ios. Nicht gesetzt, wenn die Sitzung keine aufgezeichnete oder erkannte Oberfläche hat.
CLAUDE_CODE_SESSION_ACCESS_TOKEN Das Sitzungs-Zugangstoken für Sitzungs-bezogene API-Aufrufe
GIT_CONFIG_COUNT, GIT_CONFIG_KEY_n, GIT_CONFIG_VALUE_n Git-Einstellungen, die der Runner für das Git festlegt, das Ihr Hook ausführt. Git-Konfiguration innerhalb von Lifecycle-Hooks beschreibt sie. Erfordert Claude Code v2.1.280 oder später.

Das Skript muss einen Arbeitsbaum bei CLAUDE_RUNNER_CHECKOUT_PATH hinterlassen, der bei der angeforderten Revision ausgecheckt ist. Detached HEAD ist in Ordnung; der Runner erstellt den Arbeitsbranch der Sitzung darauf. Der Runner überprüft danach, ob der Pfad eine .git enthält; wenn Ihr Hook eine Nicht-Git-Quelle wie Perforce oder ein entpacktes Tarball materialisiert, setzen Sie CLAUDE_RUNNER_SKIP_GIT_VERIFY=1 in der Umgebung des Runners, um diese Überprüfung zu überspringen. Git-basierte Flows wie Arbeitsbranch-Erstellung und Pushing-Ergebnisse erfordern einen Git-Checkout, daher exportieren Sie Ergebnisse aus Nicht-Git-Bäumen mit einem post-session-Hook.

Der Runner übergibt keine Git-Anmeldedaten an den Hook. Stattdessen prägen Sie eine Pro-Sitzungs-Klone-Anmeldedaten aus der Identität der Sitzung: Überprüfen Sie CLAUDE_CODE_SESSION_ACCESS_TOKEN mit einer Standard-JWT-Bibliothek gegen den JWKS-Endpunkt unter CLAUDE_RUNNER_API_BASE_URL, wie in Token von Ihrem Dienst überprüfen beschrieben, dann lassen Sie Ihren Anmeldedatendienst eine kurzlebige Klone-Anmeldedaten für die Identität im act-Anspruch des Tokens ausstellen. CLAUDE_RUNNER_CLAUDE_BIN ist nicht in der Checkout-Hook-Umgebung gesetzt, daher ist der Unterbefehl decode-token hier nicht verfügbar. Das Zurückfallen auf die Git-Authentifizierung, die der Host bereits hat, wie einen SSH-Agent, Anmeldedaten-Helper oder .netrc, ist auch eine Option.

Wenn der Hook mit ungleich Null endet oder mit 0 endet, ohne einen verwendbaren Checkout hinterlassen zu haben, hängt das, was der Runner tut, vom Repository ab:

  • Ein Repository, zu dem die Sitzung Ergebnisse pusht: Der Runner schlägt die Sitzung fehl, und bei einem Nicht-Null-Exit zeigt er das Ende des Stderr des Skripts dem Benutzer an.
  • Ein Repository, das die Sitzung nur liest, wie ein Repository, das zu einer laufenden Sitzung hinzugefügt wird: Der Runner protokolliert eine [runner:warn]-Zeile mit dem Fehlerdetail, postet einen Skipped-Schritt zur Sitzung, entfernt, was der Hook bei dem Checkout-Pfad hinterlassen hat, und fährt mit den verbleibenden Repositories fort. Wenn der Runner den Pfad nicht sofort entfernen kann, versucht er die Entfernung beim Sitzungsende erneut. Wenn das Überspringen die Sitzung ohne Repository verlässt, schlägt der Runner die Sitzung trotzdem fehl.

Vor v2.1.228 schlägt der Runner die Sitzung bei einem Hook-Fehler für jedes Repository fehl, daher schlägt ein Read-Only-Repository, das der Hook nicht bedienen konnte, die Sitzung erneut auf jedem frischen Runner fehl, auf dem die Sitzung fortgesetzt wurde.

Der Runner entfernt den Checkout-Pfad nach dem Sitzungsende.

post-session

Wird einmal pro Sitzung ausgeführt, nachdem das Claude Code-Kind beendet wurde und bevor der Runner den Arbeitsbereich abbaut. Dieser Hook ist Ihre einzige Chance, ungespeicherte Arbeit zu speichern: Bei --capacity über eins löscht der Runner Pro-Sitzungs-Worktrees direkt nach der Hook-Rückgabe, und bei --capacity 1 wird der wiederverwendete kanonische Klon hart zurückgesetzt, wenn die nächste Sitzung startet, daher überleben ungespeicherte verfolgte Änderungen auf keinem Pfad. Typische Verwendungen sind das Pushen eines Snapshot-Branches von ungespeicherten Änderungen, das Archivieren von Protokollen oder das Ausgeben eines Sitzungs-beendeten Ereignisses an Ihre eigenen Systeme.

Der Hook wird bei jedem Sitzungsende ausgelöst, bei dem ein untergeordneter Prozess gespawnt wurde, unabhängig von der Ursache; die CLAUDE_RUNNER_EXIT_REASON-Werte unten zählen die Fälle auf. Er kann nicht ausgelöst werden, wenn der Runner abrupt beendet wird, wie eine VM-Preemption oder ein Stromausfall; wenn Sie Garantien gegen abrupte Beendigung benötigen, snapshotten Sie regelmäßig von innerhalb der Sitzung mit einem Claude Code PostToolUse-Hook stattdessen. Der Runner setzt:

Variable Beschreibung
CLAUDE_RUNNER_SESSION_ID Sitzungs-ID in der getaggten Form session_...
CLAUDE_RUNNER_SESSION_UUID Dieselbe Sitzungs-ID in kanonischer UUID-Form
CLAUDE_RUNNER_EXIT_REASON Wie die Sitzung endete; siehe die Werte unter der Tabelle
CLAUDE_RUNNER_WORKSPACE_PATHS Doppelpunkt-getrennte absolute Pfade der Arbeitsbäume der Sitzung. Leer für Null-Repo-Sitzungen.
CLAUDE_RUNNER_DEBUG_LOG_PATH Pfad zum Debug-Protokoll der Sitzung, noch auf der Festplatte während der Hook-Ausführung
CLAUDE_RUNNER_API_BASE_URL Anthropic-API-Basis-URL für Sitzungs-bezogene Aufrufe
CLAUDE_RUNNER_CLIENT_PLATFORM Die Client-Oberfläche, die die Sitzung erstellt hat, wie web_claude_ai, desktop_app oder ios. Nicht gesetzt, wenn die Sitzung keine aufgezeichnete oder erkannte Oberfläche hat. Erfordert Claude Code v2.1.229 oder später.
CLAUDE_CODE_SESSION_ACCESS_TOKEN Das Sitzungs-Zugangstoken für Sitzungs-bezogene API-Aufrufe
GIT_CONFIG_COUNT, GIT_CONFIG_KEY_n, GIT_CONFIG_VALUE_n Git-Einstellungen, die der Runner für das Git festlegt, das Ihr Hook ausführt. Git-Konfiguration innerhalb von Lifecycle-Hooks beschreibt sie. Erfordert Claude Code v2.1.280 oder später.

CLAUDE_RUNNER_EXIT_REASON nimmt einen von vier Werten an:

  • completed: die Sitzung endete sauber. Der Claude Code-Prozess wurde normal beendet, oder die Sitzung wurde archiviert oder gelöscht, während sie noch lief.
  • failed: Der Claude Code-Prozess ist abgestürzt, oder das Setup ist nach dem Start fehlgeschlagen.
  • interrupted: Der Runner hat die Sitzung gestoppt. Er gab die Sitzung frei, um den Slot freizugeben, die Sitzung ist beim Startup abgelaufen, der Server hat die Sitzung von diesem Runner verschoben, der Runner wurde geleert, oder die Sitzung hat sein --kill-session-after-min-Limit überschritten.
  • abandoned: reserviert für eine Sitzung, die ein anderer Runner beansprucht hat. Der Hook wird derzeit in diesem Fall nicht ausgelöst.

Die Sitzungs-Lifecycle-Zähler zählen eine Freigabe, ein Startup-Timeout und einen Server-Umzug als completed statt interrupted, weil der Runner den Slot sauber zurückgegeben hat. Erwarten Sie diesen Unterschied, wenn Sie Hook-Quittungen mit den Zählern vergleichen.

Der Exit-Status des Hooks beeinflusst niemals das Sitzungsergebnis; ein Fehler wird protokolliert und ignoriert. Der Runner wartet bis zu --post-session-hook-timeout-sec, standardmäßig 60 Sekunden, bei jedem Sitzungsende einschließlich Runner-Shutdown. Dieses Beispiel speichert ungespeicherte Arbeit in einem Rettungs-Branch:

#!/usr/bin/env bash
set -u
IFS=':'
# -c-Überschreibungen schlagen Repo-lokale Einstellungen und verhindern, dass von der Sitzung
# geschriebene fsmonitor-, Hook-Pfad- und gpg-program-Konfiguration Code mit den Berechtigungen
# des Hooks ausführt. -c commit.gpgsign=false lässt diese Rettungs-Commits unter
# --configure-git außerdem unsigniert.
# Repo-lokale credential.helper und pushurl gelten weiterhin, und auf einem Runner
# vor v2.1.280 auch core.sshCommand; wenn der Hook Anmeldedaten hält, die die
# Sitzung nicht hatte, siehe die Notiz unter dem Skript.
g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
        -c commit.gpgsign=false "$@"; }
for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
  cd "$ws" 2>/dev/null || continue
  [ -z "$(g status --porcelain 2>/dev/null)" ] && continue
  g add -A
  g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue
  g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true
done

Der Hook pusht mit den Git-Anmeldedaten, die in seiner eigenen Umgebung auf dem Runner-Host verfügbar sind. Unter der Keine-Anmeldedaten-im-Image-Haltung, einschließlich wenn der integrierte Klon durch den Anthropic-Git-Proxy geht, gibt es keine, daher erzeugen Sie kurzlebige Push-Anmeldedaten innerhalb des Hooks, bevor Sie pushen: Tauschen Sie das Sitzungs-Token, das der Hook in CLAUDE_CODE_SESSION_ACCESS_TOKEN erhält, mit Ihrem eigenen Token-Dienst aus, und überprüfen Sie es, wie Sitzungsidentität überprüfen beschreibt. Wenn der Hook Anmeldedaten hält, die die Sitzung nicht hatte, ersetzen Sie origin durch eine vom Operator bereitgestellte URL und übergeben Sie -c credential.helper= plus Ihren eigenen Helper. Git-Konfiguration innerhalb von Lifecycle-Hooks beschreibt, was von der Sitzung geschriebene Konfiguration weiterhin beeinflussen kann.

Hook-Timing, wenn der Runner eine Sitzung freigibt

Eine freigegebene Sitzung kann auf einem anderen Runner fortgesetzt werden. Auf einem Runner mit v2.1.236 oder später entscheidet, was die Sitzung bei der Freigabe tat, ob sie fortgesetzt werden kann, bevor dieser Hook endet:

  • Idle nach einer Runde oder Timeout beim Startup: Der Runner stoppt das Kind und führt diesen Hook bis zum Ende aus. Erst dann gibt er die Sitzung frei. Eine Benutzernachricht, die gesendet wird, während der Hook ausgeführt wird, kann die Sitzung nicht auf einem anderen Runner fortsetzen, bevor der Hook endet.
  • Warten auf die Antwort des Benutzers auf eine Eingabeaufforderung, wie eine Berechtigungsaufforderung: Der Runner gibt die Sitzung zuerst frei, dann führt er diesen Hook aus. Eine Benutzernachricht, die gesendet wird, während der Hook ausgeführt wird, kann die Sitzung auf einem anderen Runner fortsetzen, bevor der Hook endet.

Dies gilt, wenn der Runner eine Sitzung freigibt: beim Idle-Timeout, zur --retire-at-Zeit, und, auf einem Runner mit v2.1.260 oder später, beim --kill-session-after-min-Limit einer Sitzung. Eine Sitzung, deren Runde beendet ist und die nur Hintergrundaufgaben hält, zählt hier als Idle. Vor v2.1.236 gab der Runner die Sitzung zuerst frei und führte dann diesen Hook in beiden Fällen aus.

Während eines SIGTERM-Drains hält der Runner das Sitzungs-Lease, bis der Hook endet; siehe Shutdown-Timing.

Git-Konfiguration innerhalb von Lifecycle-Hooks

Die Hooks checkout und post-session laufen mit dem Zugangstoken der Sitzung in ihrer Umgebung, und das Git, das sie ausführen, liest Konfigurationsdateien, die Sitzungen schreiben können, wie ~/.gitconfig und die .git/config eines Checkouts. Bevor einer der beiden Hooks läuft, setzt der Runner Git-Einstellungen in der Umgebung des Hooks, darunter die unten aufgeführten, als GIT_CONFIG_COUNT/GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n-Paare und Git-Umgebungsvariablen. Git stuft diese höher ein als jede Konfigurationsdatei, und sie gelten nur für das Git, das Ihre Hooks ausführen, nicht für das eigene Git der Sitzung. Beim Start gibt der Runner eine Zeile [runner:git] lifecycle hooks: aus, die den Hooks-Pfad, die erlaubten Protokolle, die gpg-Programme und den aktiven Signiermodus zeigt. Erfordert Claude Code v2.1.280 oder später.

  • Git-Hooks: Sofern Sie keinen Wert angeben, ist core.hooksPath /dev/null, sodass Git die Hooks in .git/hooks eines Repositorys und jedes Hooks-Verzeichnis überspringt, das ~/.gitconfig benennt. Um einen Wert anzugeben, exportieren Sie core.hooksPath als GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n-Paar in der Umgebung des Runners. Der Runner liest core.hooksPath auch aus der System-Git-Konfiguration und verwendet den Wert nur, wenn der Benutzer des Runners weder diese Datei noch das darin benannte Verzeichnis noch die Hook-Dateien darin schreiben kann. Wenn der Runner einen Wert ignoriert, nennt eine [runner:warn]-Zeile beim Start den Wert und den Grund.
  • Dateisystem-Monitor: core.fsmonitor ist leer, sodass Git in Ihrem Hook kein Monitorprogramm ausführt, das eine Konfigurationsdatei benennt.
  • Remote-Protokolle: GIT_ALLOW_PROTOCOL ist https:http:ssh. Ein Klonen, Abrufen oder Pushen, das einen lokalen Pfad, eine file://-URL oder eine git://-URL verwendet, schlägt mit fatal: transport 'file' not allowed oder fatal: transport 'git' not allowed fehl.
  • SSH-Befehl und Anmeldedaten-Abfrage: Git in Ihrem Hook ignoriert core.sshCommand und core.askPass aus Konfigurationsdateien. Um Ihren eigenen SSH-Befehl zu verwenden, setzen Sie GIT_SSH_COMMAND in der Umgebung des Runners. Um ein Programm für die Anmeldedaten-Abfrage zu verwenden, setzen Sie dort GIT_ASKPASS. Sitzungen erben die Umgebung des Runners, daher erreichen beide Variablen auch das eigene Git der Sitzung. Legen Sie in keiner der beiden Anmeldedaten ab.
  • gpg-Programme: gpg.program, gpg.openpgp.program, gpg.x509.program und gpg.ssh.program sind Pfade, die der Runner setzt, niemals Werte aus einer Konfigurationsdatei.
  • Commit-Signierung: Mit --configure-git werden Commits, die Sie aus einem Hook erstellen, als die Sitzung signiert. Ohne das Flag sind commit.gpgsign und tag.gpgsign false.

Um eine dieser Einstellungen zu ändern, verwenden Sie die Umgebung des Runners oder eine git -c-Option innerhalb des Hooks:

  • Konfigurationspaare: Ein GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n-Paar, das Sie in der Umgebung des Runners exportieren, ersetzt den Wert des Runners für denselben Schlüssel. Nummerieren Sie Ihre Paare ab 0 und setzen Sie GIT_CONFIG_COUNT auf ihre Anzahl. Wenn das letzte Paar, das die Anzahl ankündigt, fehlt, ignoriert der Runner alle Ihre Paare und protokolliert beim Start eine [runner:warn]-Zeile.
  • Git-Umgebungsvariablen: Der Runner belässt GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND und GIT_ASKPASS so, wie Sie sie in seiner Umgebung setzen.
  • git -c-Optionen: Eine git -c-Option innerhalb des Hooks überschreibt ein GIT_CONFIG_KEY_n-Paar, sei es das des Runners oder Ihr eigenes. Sie ändert nicht GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND oder GIT_ASKPASS, die Git vor jeder Konfiguration liest.

Git in Ihrem Hook liest weiterhin jede Einstellung, die der Runner nicht setzt, wie Anmeldedaten-Helper, url.*.insteadOf-Umschreibungen und Filtertreiber, aus jeder Konfigurationsdatei, einschließlich derer, die Sitzungen schreiben können. Ein Anmeldedaten-Helper oder Filtertreiber, der in einer dieser Dateien benannt ist, läuft als Programm mit den Berechtigungen Ihres Hooks, und Konfiguration in diesen Dateien kann weiterhin ändern, wohin ein Push aus Ihrem Hook geht, einschließlich eines Pushs an eine URL, die Sie auf der Befehlszeile übergeben.

Vor v2.1.280 setzte der Runner keine dieser Einstellungen, und unter --configure-git schlug ein Commit aus einem Hook fehl, sofern der Hook nicht -c commit.gpgsign=false übergab.

command

Wird einmal pro Sitzung nach dem Checkout anstelle des integrierten Kind-Spawns ausgeführt. Der Hook erhält dieselbe Umgebung wie ein Wrapper-Skript und sollte auf dieselbe Weise in "$CLAUDE_RUNNER_CLAUDE_BIN" exec ausführen. Verwenden Sie den command-Hook, um alle Anpassungen in einem Hooks-Verzeichnis zu halten; verwenden Sie --exec-path, wenn der Wrapper anderswo lebt. Wenn --exec-path auch gesetzt ist, hat das Flag Vorrang und der command-Hook wird ignoriert.

Führen Sie immer die eigene Binärdatei des Runners aus, anstatt ein PATH-aufgelöstes claude; andernfalls besiegen Sie Versions-Pinning.

On-Demand-Runner

Anstatt eine feste Fleet zu betreiben, können Sie einen Runner pro Sitzung starten. Der Orchestrator ist ein separater, zustandsloser Unterbefehl, der Anthropic nach Spawn-Anfragen abfragt, eine pro Sitzung, die in der Warteschlange mit keinem verfügbaren Runner steht, und führt Ihren spawn-runner-Hook für jeden aus. Ihr Hook sendet eine Workload an Ihre Plattform: einen Kubernetes Job, eine EC2-Instanz, einen Nomad-Dispatch.

On-Demand-Runner verbessern die Anmeldedaten-Hygiene. Bei einer festen Fleet lebt das Umgebungsgeheimnis auf jedem Runner-Host, das ist derselbe Host, der Benutzersitzungen ausführt. Mit dem Orchestrator bleibt das Umgebungsgeheimnis nur auf dem Orchestrator-Host, der niemals Benutzercode ausführt; jeder gespawnte Runner erhält eine einmalige Arbeitsorder, die genau einen Runner registriert und dann abläuft.

Um den Orchestrator zu starten, übergeben Sie das Umgebungsgeheimnis und ein Hooks-Verzeichnis, das ein ausführbares spawn-runner-Skript enthält:

claude self-hosted-runner orchestrator \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks

Der Orchestrator behält keinen Zustand zwischen Abfragen, daher können Sie zwei oder mehr Replikas gegen dieselbe Umgebung für Verfügbarkeit ausführen. Jede Spawn-Anfrage wird serverseitig von genau einer Replik beansprucht. Alle Replikas müssen denselben --expected-spawn-seconds-Wert verwenden; siehe den Hook-Vertrag.

Der spawn-runner-Hook

Der Orchestrator führt ${hooks-dir}/spawn-runner einmal pro Spawn-Anfrage aus. Der Hook muss Arbeit asynchron einreichen, ohne auf den Runner-Boot zu warten, und innerhalb von --hook-timeout, standardmäßig 60 Sekunden, zurückkehren. Der Hook erhält:

Variable Beschreibung
CLAUDE_RUNNER_WORK_ORDER_FILE Pfad zu einer Temp-Datei, die das signierte Arbeitsorder-JWT enthält, das der neue Runner registriert. Gelöscht nach dem Hook-Exit. Protokollieren Sie nicht den Inhalt der Datei.
CLAUDE_RUNNER_ORDER_ID Undurchsichtiger Idempotenz-Schlüssel, eindeutig pro Spawn-Anfrage und sicher für Kubernetes-Ressourcennamen. Verwenden Sie nur die Order-ID als Dedup-Schlüssel Ihres Provisioners.
CLAUDE_RUNNER_SESSION_ID Die Sitzung, für die diese Anfrage bestimmt ist. Sie wiederholt sich bei jeder Neuanfrage für die Sitzung, daher verwenden Sie sie für Protokollierung und Routing, nicht als Dedup-Schlüssel. Leer für Pre-Warming-Anfragen, die einen Standby-Runner im Voraus starten, bevor eine bestimmte Sitzung, wenn --min-idle gesetzt ist, daher nehmen Sie nicht an, dass die Variable gesetzt ist.
CLAUDE_RUNNER_SESSION_UUID Dieselbe Sitzungs-ID in kanonischer UUID-Form. Leer für Pre-Warming-Anfragen.
CLAUDE_RUNNER_ATTEMPT Wie viele Spawn-Anfragen diese Sitzung hatte. 0 für Pre-Warming-Anfragen.
CLAUDE_RUNNER_ORDER_SERVER_TIME Server-Zeit aus dem HTTP-Date-Header der Poll-Antwort. Wenn der Hook das Arbeitsorder-JWT exp überprüft, vergleichen Sie gegen diesen Wert anstelle der lokalen Uhr, um Skew zu tolerieren. Leer, wenn das Gateway den Header weggelassen hat.
CLAUDE_RUNNER_POOL_ID Die ID der Umgebung, der der neue Runner beitreten sollte, in der Form ccpool_...
CLAUDE_RUNNER_ACCOUNT_ID Getaggte ID des Kontos, das die Sitzung in die Warteschlange eingereiht hat, für Pro-Konto-Routing, Kontingent oder Chargeback. Leer, wenn nicht verfügbar, und immer leer für Claude Tag-Kanal-Sitzungen, die kein Konto einreiht.
CLAUDE_RUNNER_ACCOUNT_EMAIL E-Mail des Kontos, das die Sitzung in die Warteschlange eingereiht hat. Leer, wenn nicht verfügbar. Behandeln Sie die E-Mail als personenbezogene Informationen und protokollieren Sie sie nicht.
CLAUDE_RUNNER_PRIMARY_REPO_URL URL der ersten Git-Quelle der Sitzung, für Routing zu einem Runner mit diesem Repository pre-warmed. Leer, wenn die Sitzung keine Git-Quellen hat.
CLAUDE_RUNNER_PRIMARY_REPO_REVISION Revision der ersten Git-Quelle der Sitzung: Branch, SHA oder Tag. Leer, wenn nicht angegeben.
CLAUDE_RUNNER_REPO_SOURCES JSON-Array von {url, revision} für alle Git-Quellen der Sitzung, für Hooks, die auf einem sekundären Repository routen. Leer, wenn es keine Quellen gibt.
CLAUDE_RUNNER_CORRELATION_ID Die Korrelations-ID, die bei der Sitzungserstellung bereitgestellt wurde, echoed zurück, damit der Hook diese Arbeitsorder der Anfrage zuordnen kann, die die Sitzung erstellt hat. Leer, wenn die Sitzung keine hat.
CLAUDE_RUNNER_CLIENT_PLATFORM Die Client-Oberfläche, die die Sitzung erstellt hat, wie web_claude_ai, desktop_app, ios oder scheduled_trigger, für Adoptionsanalysen. Nicht gesetzt, wenn die Sitzung keine aufgezeichnete oder erkannte Oberfläche hat, und für Pre-Warming-Anfragen; überprüfen Sie sie mit [ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ], was unter set -u sicher bleibt.

Der gespawnte Runner registriert sich mit der Arbeitsorder anstelle des Umgebungsgeheimnisses:

  • Starten Sie ihn mit der Arbeitsorder: Zeigen Sie --environment-secret-file auf eine Datei, die das Arbeitsorder-JWT enthält, oder setzen Sie SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET auf den JWT-Wert.
  • Kopieren Sie das JWT, bevor der Hook endet: Der Orchestrator löscht die Arbeitsorder-Datei nach dem Hook-Exit, daher kopieren Sie das JWT in die Workload, die Sie einreichen, wie ein Kubernetes Secret auf dem gespawten Job, anstatt den Dateipfad durchzuleiten.
  • Verwenden Sie --capacity 1 auf gespawten Runnern: Eine Sitzungs-gebundene Arbeitsorder registriert genau einen Runner, der an diese Sitzung gebunden ist, daher fügt eine höhere Kapazität Slots hinzu, die niemals Arbeit erhalten, und der Runner protokolliert eine Warnung beim Startup.
  • Pre-Warming-Arbeitsorder registrieren ungebunden: Der Standby-Runner ist nicht an eine Sitzung gebunden und beansprucht in der Warteschlange befindliche Arbeit wie ein Fixed-Fleet-Runner.

Der Vertrag hat vier Provisioner-agnostische Regeln:

  1. Seien Sie idempotent auf CLAUDE_RUNNER_ORDER_ID. Neulieferung derselben Anfrage muss höchstens einen Runner spawnen. Leiten Sie einen deterministischen Ressourcennamen von der Order-ID ab und lassen Sie Ihre Plattform das Duplikat ablehnen. Keying Sie nicht auf CLAUDE_RUNNER_SESSION_ID stattdessen. Jede Neuanfrage für eine Sitzung trägt dieselbe Sitzungs-ID mit einer neuen Order-ID, daher wird eine Workload, die nach der Sitzungs-ID benannt oder dedupliziert ist, einmal erstellt und nie wieder für diese Sitzung.
  2. Versuchen Sie nicht, die Workload erneut zu versuchen. Eine Order-ID bedeutet höchstens eine erstellte Workload. Wenn sich der Runner nie registriert, fordert Anthropic nach --expected-spawn-seconds mit einer frischen Order-ID erneut an.
  3. Verwenden Sie den Exit-Code-Vertrag. Exit 0 bedeutet eingereicht. Exit 1 bedeutet wiederholbarer Fehler; die Sitzung sichert sich ab und wird erneut angeboten. Exit 2 oder höher bedeutet nicht wiederholbar; die Sitzung wird blockiert, bis ein Owner auf der Registerkarte Aktivität der Umgebung Erneut versuchen auswählt. Bei Nicht-Null-Exit erscheint das Ende des Stderr des Hooks dort als Fehlergrund, daher schreiben Sie den umsetzbaren Fehler auf stderr und niemals Geheimnisse. Für eine Pre-Warming-Anfrage gibt es keine Sitzung zum Fehlschlag: Der Orchestrator protokolliert einen Nicht-Null-Exit lokal nur, und der Server fordert den Spawn nach dem Lease erneut an.
  4. Setzen Sie --expected-spawn-seconds auf mindestens Ihre p99-Boot-Zeit. Dies ist das serverseitige Lease. Alle Orchestrator-Replikas müssen denselben Wert verwenden.

Alles, was der Hook auf stdout oder stderr schreibt, erscheint im Protokoll des Orchestrators mit automatisch redigierten Anmeldedaten. Wenn Sitzungen in der Warteschlange bleiben, überprüfen Sie den /healthz-Body des Orchestrators auf Warteschlangen-Zählungen, öffnen Sie dann die Registerkarte Aktivität Ihrer Umgebung auf der Cloud-Umgebungen-Administratorseite: Erweitern Sie eine fehlgeschlagene Sitzung dort für ihren Spawn-Fehler und wählen Sie Erneut versuchen, um sie erneut anzufordern.

Eine Sitzung, die in der Warteschlange bleibt, ohne dass ein Spawn-Fehler auf der Registerkarte Aktivität vorhanden ist, kann bedeuten, dass der Hook nach der Sitzungs-ID keyed ist. Um dies zu bestätigen, überprüfen Sie, ob Ihre Plattform eine Workload für die erste Spawn-Anfrage dieser Sitzung hat und keine für die Neuanfragen. Wenn ja, keying Sie die Workload auf CLAUDE_RUNNER_ORDER_ID stattdessen.

Modellanfragen an Bedrock oder Agent Platform senden

Wenn Ihre Organisation Modellanfragen über ihr eigenes AWS- oder Google-Cloud-Konto leiten muss, konfigurieren Sie den Runner für Amazon Bedrock oder Google Cloud's Agent Platform, ehemals Vertex AI. Jede Sitzung, die dieser Runner startet, ruft das Modell dann in Ihrem Cloud-Konto mit Ihren Cloud-Anmeldedaten auf. Ohne diese Konfiguration senden Sitzungen Modellanfragen an die Anthropic API.

Der Runner fragt Sitzungen weiterhin bei Anthropic ab, und jede Sitzung sendet ihren Event-Stream weiterhin an api.anthropic.com. Der Event-Stream enthält Prompts, Antworten und Tool-Ergebnisse. Die Planvoraussetzung und der Ausschluss von Zero Data Retention unter Verfügbarkeit und Einschränkungen gelten weiterhin.

Sitzungen werden an eine Umgebung weitergeleitet, nicht an einen Runner, und eine erneut eingereihte oder fortgesetzte Sitzung kann auf einem anderen Runner laufen. Konfigurieren Sie jeden Runner in der Umgebung auf die gleiche Weise. Lesen Sie vor dem Start, was bei diesen Anbietern anders ist.

1

Cloud-Konto und Egress-Regeln vorbereiten

Richten Sie Modellzugriff, eine eng gefasste Richtlinie oder Rolle sowie Netzwerkzugriff ein:

  • Amazon Bedrock: Übermitteln Sie Details zum Anwendungsfall und erstellen Sie dann die Richtlinie unter IAM-Konfiguration, wobei Sie bedrock:InvokeModel und bedrock:InvokeModelWithResponseStream auf die Inferenzprofile beschränken, die Ihre Sitzungen verwenden, sowie auf die zugrunde liegenden Foundation-Modelle
  • Agent Platform: Aktivieren Sie die API und beantragen Sie Modellzugriff, und erstellen Sie dann die benutzerdefinierte Rolle, die unter IAM-Konfiguration beschrieben ist, ausschließlich mit aiplatform.endpoints.predict
  • Egress: Lassen Sie die Endpunkte Ihres Anbieters in Ihren Egress-Regeln zu. Siehe Netzwerkanforderungen. Wenn Sitzungen sie nicht erreichen können, kann Claude Code stundenlang erneute Versuche unternehmen, bevor die Sitzung einen Fehler anzeigt.
2

Sitzungen eng gefasste Anmeldedaten geben

Weisen Sie die Richtlinie oder Rolle aus Schritt 1 einer Identität zu, die sonst nichts tun kann. Die Methoden, die Claude Code akzeptiert, finden Sie unter AWS-Anmeldedaten konfigurieren und GCP-Anmeldedaten konfigurieren.

Prüfen Sie die gewählte Methode anhand dieser Verhaltensweisen des Runners:

  • Metadaten-Endpunkt: Wenn Sie Sitzungen den Cloud-Metadaten-Endpunkt vollständig verweigern, erreichen daraus bereitgestellte Anmeldedaten, etwa ein Instanzprofil, Claude Code ebenfalls nicht. Eine dateibasierte Web-Identität, etwa IAM Roles for Service Accounts (IRSA) auf Amazon EKS oder eine Anmeldedaten-Datei für Workload Identity Federation, hängt nicht davon ab.
  • Erneuerung: Eine Sitzung kann länger bestehen als Anmeldedaten, verwenden Sie daher eine Methode, die sich selbst erneuert, etwa eine dateibasierte Web-Identität
  • Wrapper-Skript: Der Runner startet Ihr Wrapper-Skript einmal pro Sitzung, daher werden Anmeldedaten, die es exportiert, nicht erneuert. Claude Code liest AWS-Anmeldedaten aus seiner Umgebung. Wenn Ihr Wrapper also bereits AWS-Anmeldedaten für andere Aufgaben exportiert, kann Claude Code Modellanfragen damit signieren.
3

Die Variablen eines Anbieters in der Umgebung des Runners setzen

Setzen Sie die Variablen genau eines Anbieters dort, wo Sie auch die anderen Umgebungsvariablen des Runners setzen, etwa in der Container-Spezifikation oder der Service-Unit, und starten Sie den Runner dann neu. Die Beispiele zeigen sie als Shell-Exports. Bei On-Demand-Runnern setzen Sie sie für die Workload, die Ihr spawn-runner-Hook startet.

Starten Sie diese Runner mit --confine-repo-settings enforce. Dadurch werden Sitzungen in Repositorys abgelehnt, deren committete Einstellungen gekennzeichnet werden. Führen Sie den Runner daher zunächst im Standardmodus warn aus und beheben Sie, was protokolliert wird.

Ersetzen Sie die Region durch Ihre eigene:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

Wie Claude Code die Region ermittelt, erfahren Sie unter Claude Code konfigurieren. Welches Präfix für Inferenzprofile Claude Code für Ihre Region verwendet, erfahren Sie unter Präfixe für regionsübergreifende Inferenzprofile.

4

Prüfen, ob die Variablen eine Sitzung erreicht haben

Ihre eigene Shell auf dem Host ist ein anderer Prozess, prüfen Sie daher innerhalb einer Sitzung. Starten Sie eine Sitzung in der Umgebung und bitten Sie Claude, diesen Befehl auszuführen:

env | grep -E 'CLAUDE_CODE_USE_(BEDROCK|VERTEX)'

Eine Zeile, die CLAUDE_CODE_USE_BEDROCK oder CLAUDE_CODE_USE_VERTEX auf 1 setzt, bedeutet, dass die Variable die Sitzung erreicht hat. Wenn beide erscheinen, verwendet Claude Code Amazon Bedrock. Keine Ausgabe bedeutet, dass keine der beiden sie erreicht hat.

Der Befehl zeigt die Konfiguration, nicht den Datenverkehr. Um die Anfragen selbst zu bestätigen, suchen Sie in den Metriken oder Anfrage-Logs Ihres Cloud-Kontos danach. Wenn stattdessen die erste Nachricht fehlschlägt, lesen Sie die Fehlerbehebung für Amazon Bedrock oder Agent Platform.

Unterschiede zu Sitzungen über die Anthropic API

Eine Sitzung, die Modellanfragen an Amazon Bedrock oder Google Cloud's Agent Platform sendet, unterscheidet sich auf folgende Weise von einer Sitzung über die Anthropic API:

  • Richtlinien aus claude.ai: Serververwaltete Einstellungen erreichen diese Sitzungen nicht. Ebenso wenig die Organisationsrichtlinien, die ein Owner in den Claude Code Admin-Einstellungen festlegt, daher setzt Claude Code sie innerhalb der Sitzung nicht durch. Legen Sie die Regeln, auf die Sie sich verlassen, in der Datei für verwaltete Einstellungen des Runner-Images ab.
  • Dateien: Dateien, die Personen in claude.ai oder der mobilen oder Desktop-App an eine Sitzung anhängen, erreichen diese nicht, und Claude kann mit dem SendUserFile-Tool keine Dateien zurücksenden. Legen Sie Eingabedateien stattdessen im Repository oder auf dem Runner ab.
  • Modellauswahl: Die Control Plane von Anthropic sendet das Modell jeder Sitzung, und wenn eine Sitzung ohne Modell startet, verwendet Claude Code seinen Standard für den Anbieter. Der Runner entfernt ANTHROPIC_MODEL und ANTHROPIC_DEFAULT_MODEL aus der Umgebung, die er an Sitzungen übergibt. Die Beispiele auf den Anbieterseiten setzen ANTHROPIC_MODEL, aber in der Umgebung des Runners hat keine der beiden Variablen eine Wirkung. Die familienspezifischen Variablen unter „Modellversionen festlegen“ für Amazon Bedrock und Agent Platform erreichen Sitzungen hingegen. Sie bestimmen, worauf ein Alias wie opus aufgelöst wird, nicht, worauf eine vollständige Modell-ID aufgelöst wird.
  • Modelle, die Ihr Konto nicht bereitstellt: Eine Sitzung kann bei einer Nachricht mit einem Fehler fehlschlagen, der das Modell nennt. Aktivieren Sie die Modelle, die Ihre Entwickler auswählen können, das unter „Modellversionen festlegen“ beschriebene Hintergrundmodell sowie das Klassifikatormodell, das der Auto-Modus verwendet. Lassen Sie bei Amazon Bedrock jedes davon in Ihrer Richtlinie zu.
  • Websuche und Fast-Modus: Die Websuche ist auf Amazon Bedrock nicht verfügbar, und der Fast-Modus ist bei keinem der beiden Anbieter verfügbar. Weitere Funktionen, die sich je nach Anbieter unterscheiden, finden Sie unter CLI-Funktionen, die je nach Anbieter variieren.

MCP-Server

Um MCP-Server in jeder Sitzung verfügbar zu machen, fügen Sie sie beim Bauen des Images mit demselben Befehl claude mcp add hinzu, den Sie auch bei einer Desktop-Installation verwenden. Wenn Ihr Runner ein einfacher Prozess und kein Container ist, führen Sie denselben Befehl als Benutzer des Runners auf dem Host aus und starten Sie den Runner anschließend neu: Er liest die Host-Konfiguration einmalig beim Start. Das Flag --scope user ist erforderlich; der standardmäßige lokale Geltungsbereich schreibt unter einen verzeichnisspezifischen Schlüssel, den der Runner nicht an Sitzungen weitergibt. Zum Beispiel in Ihrem Dockerfile:

RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar
RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

Der Runner erstellt beim Start einmalig einen Snapshot der Host-Konfiguration. Der Snapshot erfasst den Schlüssel mcpServers aus der Datei .claude.json des Hosts, die neben und nicht innerhalb von ~/.claude/ liegt, und der Runner überträgt nur diesen Schlüssel in die isolierte Konfiguration jeder Sitzung; Kontostatus und Projektverlauf werden verworfen. Um zu bestätigen, dass die Server in den Sitzungen angekommen sind, starten Sie eine Sitzung in der Umgebung und bitten Sie Claude, seine MCP-Tools aufzulisten; der Runner protokolliert außerdem beim Start eine Warnung für jeden erfassten Eintrag, dessen type er nicht erkennt, und verwirft diesen Eintrag, sodass Sie sehen können, warum dieser Server in den Sitzungen fehlt. Wenn SELF_HOSTED_RUNNER_HOST_CONFIG_DIR gesetzt ist, liest der Runner .claude.json stattdessen aus diesem Verzeichnis; wenn Sie die Variable auf ein leeres Verzeichnis zeigen lassen, wird daher auch die Übertragung der MCP-Server deaktiviert.

Claude Code lädt MCP-Server auch aus anderen Quellen:

  • Die verwaltete MCP-Datei im Enterprise-Geltungsbereich an ihrem Standard-Systempfad: /etc/claude-code/managed-mcp.json auf Linux-Runner-Hosts, /Library/Application Support/ClaudeCode/managed-mcp.json auf macOS-Hosts. Verwenden Sie sie für abgeschottete Umgebungen, in denen nur vom Administrator aufgeführte Server geladen werden dürfen. Die Regeln zum Vorrang finden Sie unter Exklusive Kontrolle mit managed-mcp.json. Wenn sich diese Datei auf dem Runner-Host befindet, überspringt Claude Code die MCP-Server, die die Control Plane von Anthropic an eine Sitzung übermittelt, einschließlich claude.ai-Konnektoren, und nennt sie in einer Warnung auf stderr des Sitzungs-Kindprozesses, die der Runner auf der Log-Ebene debug aufzeichnet. Vor v2.1.229 wurden diese Sitzungen beim Start mit You cannot dynamically configure MCP servers when an enterprise MCP config is present beendet.
  • Der Schlüssel managedMcpServers in den verwalteten Einstellungen auf dem Runner-Host: Stellt HTTP- und SSE-Server bereit, ohne die exklusive Kontrolle zu übernehmen, sodass Server aus den anderen Quellen weiterhin geladen werden. Erfordert Claude Code v2.1.259 oder neuer.
  • <repo>/.mcp.json: Projekt-Geltungsbereich. Committen Sie die Datei in das Repository; ihre Server werden in Cloud-Sitzungen automatisch genehmigt.

Wenn die Bereitstellung von Konnektoren für Ihre Organisation aktiviert ist, übermittelt die Control Plane von Anthropic die Konnektoren, die Sie auf claude.ai konfiguriert haben, über serverseitig bereitgestellte MCP-Konfiguration an interaktiv erstellte Sitzungen, geleitet über api.anthropic.com. Programmgesteuert erstellte Sitzungen, wie etwa CLI-Dispatches, erhalten keine Konnektoren; stellen Sie ihnen MCP-Server stattdessen über eine der anderen in diesem Abschnitt aufgeführten Quellen bereit. Das OAuth-Token des Kindprozesses enthält keinen Scope zum direkten Abrufen von Konnektoren, daher versucht der Kindprozess diesen Abruf nicht selbst; die Bereitstellung erfolgt serverseitig.

settings.json enthält keine MCP-Server-Definitionen, und das Einstellungsschema hat kein Feld mcpServers auf oberster Ebene. Stellen Sie Server in verwalteten Einstellungen stattdessen mit dem Schlüssel managedMcpServers bereit.

Sitzungen erben die Umgebung des Runners. Setzen Sie daher ENABLE_TOOL_SEARCH dort, um MCP Tool Search für jede Sitzung zu steuern, die ein Runner startet; die MCP-Seite beschreibt die möglichen Werte.

Integrierte Sitzungstools ausschalten

Die Control Plane von Anthropic bindet einen eigenen MCP-Server namens Claude Code Remote an Cloud-Sitzungen an. Claude verwendet die Tools dieses Servers, um Routinen zu planen, andere Cloud-Sitzungen zu starten und zu steuern, weitere Repositorys anzubinden und Aktivitäten in Pull Requests zu verfolgen.

Um den gesamten Server auszuschalten, fügen Sie Ihren Einstellungen eine Deny-Regel auf Serverebene hinzu. Die Control Plane registriert den Server je nachdem, wie die Sitzung erstellt wurde, unter einem von drei Namen. Claude Code gleicht den Namen in einer Regel exakt ab, einschließlich Groß- und Kleinschreibung. Schreiben Sie die Regel daher wie gezeigt einmal pro Name:

{
  "permissions": {
    "deny": [
      "mcp__Claude_Code_Remote",
      "mcp__claude-code-remote",
      "mcp__bf7c680d-5fdc-5ef4-b4a0-abadb619bf0a"
    ]
  }
}

Eine Regel, die den gesamten Server benennt, erfasst auch Tools, die der Server später hinzubekommt. Um ein einzelnes Tool auszuschalten und die übrigen beizubehalten, hängen Sie an jede Regel zwei weitere Unterstriche und den Tool-Namen an, wie in mcp__Claude_Code_Remote__add_repo. Um zu verhindern, dass der Server überhaupt eine Verbindung herstellt, statt nur seine Tools zu entfernen, fügen Sie die drei Namen ohne das Präfix mcp__ stattdessen als serverName-Einträge unter deniedMcpServers hinzu.

Legen Sie die Regeln in serververwaltete Einstellungen, um Sitzungen ohne Änderung am Runner zu erreichen, oder in ~/.claude/settings.json auf dem Runner. Auf einem Runner, der Modellanfragen an Bedrock oder Agent Platform sendet, verwenden Sie diese Datei, da serververwaltete Einstellungen diese Sitzungen nicht erreichen. Unter Berechtigungen und Tool-Genehmigung wird erläutert, wie Einstellungen auf dem Runner die Sitzungen erreichen.

Um zu bestätigen, dass die Regeln wirksam sind, starten Sie eine Sitzung in der Umgebung und bitten Sie Claude, seine MCP-Tools aufzulisten. Claude Code entfernt ein abgelehntes Tool aus dem Kontext von Claude, sodass die abgelehnten Tools in der Antwort fehlen.

Fordern Sie Sitzungen auf, ihre Arbeit zu pushen

Anthropic-gehostete Sitzungen führen einen Stop-Hook aus, den Claude Code-Hook, der ausgeführt wird, wenn Claude fertig mit der Antwort ist, der Claude auffordert, seine Arbeit zu committen und zu pushen. Der Runner installiert keinen. Ohne ihn hinterlässt eine Sitzung, die mit ungespeicherten Änderungen endet, diese Arbeit nur auf der Festplatte des Runners, und die Schaltfläche PR erstellen in claude.ai/code bleibt inaktiv, bis der Branch auf dem Remote existiert.

Die Referenzimplementierung unten hat zwei Teile. Führen Sie den Settings-Block in ~/.claude/settings.json auf dem Runner-Host zusammen, den der Runner in jede Sitzung seeded, und speichern Sie das Skript als ~/.claude/hooks/stop-hook-nudge.sh auf dem Runner-Host und machen Sie es ausführbar:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# Stop-Hook-Referenzimplementierung für selbstgehostete Runner.
#
# Nudgt Claude einmal pro Runde, wenn das Projektverzeichnis ungespeicherte
# Änderungen ODER ungepushte Commits hat, damit Arbeit nicht verloren geht, wenn eine Idle-Sitzung
# freigegeben wird und damit die Schaltfläche "PR erstellen" auf claude.ai/code leuchtet.
#
# Runner-Ebene (keine Repo-Änderungen): Legen Sie diese Datei auf dem Runner-Host unter ~/.claude/hooks/ ab und
# führen Sie den begleitenden Stop-Hook-Settings-Block
# in ~/.claude/settings.json zusammen — der Runner seeded beide in jede Sitzung.
# Repo-Ebene-Alternative: Committen Sie zu <repo>/.claude/hooks/ und ändern Sie den
# settings.json-Befehlspfad zu $CLAUDE_PROJECT_DIR/.claude/hooks/.
#
# stdin: Hook-JSON-Payload (siehe https://code.claude.com/docs/en/hooks)
# stdout: {"decision":"block","reason":"..."} zum Nudgen oder nichts zum Zulassen des Stops.

# Re-Entry-Guard: Das Harness setzt stop_hook_active=true, wenn der Stop-Hook erneut aufgerufen wird
# nach einem Block. Bail, damit wir nur einmal pro Runde nudgen. Das
# Harness gibt kompaktes JSON aus (kein Leerzeichen nach dem Doppelpunkt), das dieses
# Muster nutzt; verwenden Sie jq, wenn Sie eine Whitespace-tolerante Überprüfung benötigen.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# Kein Git-Repo → nichts zum Nudgen.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# Kein Remote → "zum Remote pushen" ist nicht erfüllbar; bail.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# Ungespeicherte Änderungen (staged, unstaged oder untracked). Schließen Sie .claude/ aus
# vollständig — Operator-gekeimte Einstellungen und CLI-geschriebener Laufzeitzustand
# (Scheduler-Sperre, Worktrees, Routine-Zustand) leben dort und keiner ist
# "ungespeicherte Arbeit", die das Modell pushen muss.
s=$(git -C "$d" status --porcelain -- . ':(exclude).claude/' 2>/dev/null)
if [ -n "$s" ]; then
  printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'
  exit 0
fi

# Ungepushte Commits. Zählen Sie Commits auf HEAD, die von keinem
# Remote-Tracking-Ref oder FETCH_HEAD erreichbar sind. Dies funktioniert einheitlich für:
#   - init+fetch-Checkouts (Runner-Standard: nur FETCH_HEAD existiert)
#   - Clone-basierte Checkouts (origin/* existieren)
#   - der Runner-Standard: Das Kind startet auf dem Outcome-
#     Branch der Sitzung, den der Runner nach dem Checkout erstellt
#   - Detached HEAD, wenn ein benutzerdefiniertes Setup diese Branch-Erstellung überspringt
# Ohne Referenzpunkt überhaupt (nie abgerufen), bleiben Sie still, anstatt
# falsch-positiv auf einer Read-Only-Runde.
base=""
git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"
if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then
  exit 0
fi
# shellcheck disable=SC2086  # $base ist entweder "" oder "FETCH_HEAD", beabsichtigter Word-Split
unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0
if [ "$unpushed" -gt 0 ]; then
  branch=$(git -C "$d" symbolic-ref --short -q HEAD)
  if [ -n "$branch" ]; then
    # $branch ist Angreifer-beeinflusst — git-check-ref-format(1) erlaubt `"`
    # in Ref-Namen. `\` ist verboten (Regel 10), aber trotzdem als billiger
    # Defense-in-Depth escaped.
    # Escape JSON-Metazeichen vor der Interpolation in die handgebaute
    # Payload, damit ein Branch wie x","continue":false keine Schlüssel in
    # das Hook-Output-JSON injizieren kann, das das Harness parst. $unpushed ist sicher — das
    # -gt-Guard oben lehnt alles ab, das keine einfache Ganzzahl ist.
    branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"
  else
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"
  fi
  exit 0
fi

exit 0

Der Hook fordert Claude auf, vor dem Sitzungsende zu committen und zu pushen, und bleibt still, wenn das Verzeichnis kein Git-Repository ist oder keinen Remote hat.

Berechtigungen und Tool-Genehmigung

Eine selbstgehostete Sitzung hat kein angeschlossenes Terminal, daher blockiert eine unbeantwortete Berechtigungsabfrage den Turn, bis der Benutzer in der UI antwortet. Die Steuerungsebene von Anthropic sendet die Tool-Liste und die Berechtigungsregeln jeder Sitzung mit der Arbeits-Payload; die Standardkonfiguration genehmigt alltägliche Tool-Aufrufe vorab, einschließlich Bash, und Cloud-Sitzungen genehmigen Dateibearbeitungen unabhängig vom Modus vorab. Bei einem Aufruf, den nichts vorab genehmigt, wird über die Sitzungs-UI nachgefragt.

Um Berechtigungsabfragen unabhängig davon, was die Steuerungsebene sendet, auf ein Minimum zu reduzieren, legen Sie den Auto-Modus in Ihrem Wrapper-Skript oder command-Hook fest. Im Auto-Modus laufen Sitzungen ohne alltägliche Berechtigungsabfragen: Ein separates Klassifikatormodell prüft Aktionen, bevor sie ausgeführt werden, und blockiert diejenigen, die es ablehnt, und explizite ask-Regeln erzwingen weiterhin eine Abfrage; die Seite zu den Berechtigungsmodi beschreibt, was der Klassifikator prüft. Der Runner hängt serverseitig berechnete Flags an, bevor er den Wrapper aufruft, und bei Flags mit einem einzelnen Wert wie --permission-mode berücksichtigt der Parser das letzte Vorkommen, sodass ein Flag, das Sie nach "$@" anhängen, den vom Server gesendeten Wert überschreibt:

#!/bin/bash
exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

Um stattdessen bestimmte Tools vorab zu genehmigen, hängen Sie --allowed-tools mit Ihren Regeln an, zum Beispiel --allowed-tools "Bash(bazel *) Bash(yarn *) mcp__internal__*". Listen-Flags wie --allowed-tools und --disallowed-tools werden über mehrere Vorkommen hinweg kumuliert, statt sich zu überschreiben, sodass Ihre Regeln zusätzlich zu allen Regeln gelten, die die Steuerungsebene sendet. Zum Einschränken hängen Sie --disallowed-tools an, das Tools verweigert, auch wenn eine andere Regel sie zulässt.

Wie die Konfiguration jeder Sitzung zusammengestellt wird

Der Runner gibt jeder Sitzung ein eigenes Konfigurationsverzeichnis, das aus einem Snapshot des ~/.claude/ des Hosts befüllt wird, den der Runner einmalig beim Start erstellt: settings.json, CLAUDE.md, Hooks, Agenten, Befehle und Skills in Ihrem Runner-Image gelten für jede Sitzung als Basis auf Benutzerebene. Wenn Sie die Konfiguration auf einem laufenden Host ändern, wird die Änderung erst wirksam, nachdem Sie den Runner neu gestartet haben.

Setzen Sie SELF_HOSTED_RUNNER_HOST_CONFIG_DIR, um von einem anderen Pfad zu befüllen, oder lassen Sie die Variable auf ein leeres Verzeichnis zeigen, um das Befüllen zu deaktivieren.

Eine im Repository committete .claude/settings.json wird als Projekteinstellungen darübergelegt. Sitzungen lesen außerdem managed-settings.json aus dem standardmäßigen Systempfad in Ihrem Runner-Image. Ob deren Schlüssel neben serververwalteten Einstellungen gelten, richtet sich danach, wie Claude Code verwaltete Quellen kombiniert: Wenn Ihre Organisation serververwaltete Schlüssel bereitstellt, ignorieren Sitzungen standardmäßig die Datei des Runner-Images, abgesehen von den Schlüsseln, die Claude Code aus jeder Admin-Quelle liest, etwa dem env-Block, den Sandbox-Sperren, den Pfaden zu den Sandbox-Binärdateien und forceRemoteSettingsRefresh. Siehe Vorrang der Einstellungen.

Wenn die Steuerungsebene von Anthropic eine Sitzung mit Claude Code-Hooks versorgt, installiert der Runner diese neben Ihrer eigenen Konfiguration, nicht an deren Stelle. Erfordert Claude Code v2.1.229 oder höher.

  • Wo sie abgelegt werden: Der Runner schreibt jedes bereitgestellte Hook-Skript in ein reserviertes Unterverzeichnis hooks/.ccr-launcher/ des Konfigurationsverzeichnisses der Sitzung und registriert die Skripte in einer separaten Einstellungsdatei, die er der Sitzung mit --settings übergibt; die befüllte settings.json und Ihre eigenen Skripte unter hooks/<name> bleiben dabei unberührt. Der Runner erstellt das reservierte Unterverzeichnis für jede Sitzung neu und übernimmt keine Host-Inhalte unter ~/.claude/hooks/.ccr-launcher/ in Sitzungen.
  • Wer sie erstellt: Die Steuerungsebene füllt die Skripte aus festen Konstanten in ihrem eigenen Deployment, niemals aus sitzungsspezifischen Eingaben oder Eingaben von Drittanbietern.
  • Was weiterhin für sie gilt: Hooks, die über --settings bereitgestellt werden, gehen in die gewöhnliche zusammengeführte Hook-Konfiguration ein, nicht in die verwaltete Ebene, sodass Ihre verwalteten Einstellungen weiterhin gelten. disableAllHooks deaktiviert sie, und sie gehören nicht zu den Kategorien, die allowManagedHooksOnly geladen lässt.

Außerhalb von Claude Tag-Sitzungen läuft eine Sitzung in einer selbstgehosteten Umgebung standardmäßig mit ausgeschaltetem Auto-Memory. Für Anweisungen, die über Sitzungen hinweg erhalten bleiben sollen, verwenden Sie die CLAUDE.md in Ihrem Runner-Image oder im Repository.

Der Snapshot, den der Runner vom ~/.claude/ des Hosts erstellt, lässt das Verzeichnis projects/ aus. Der standardmäßige Speicherort von Auto-Memory liegt unterhalb dieses Verzeichnisses. Wenn Sie dort Memory-Dateien ablegen, übernimmt der Runner sie nicht in Sitzungen, und sie schalten Auto-Memory nicht ein.

Im Repository committete Berechtigungsregeln

Tragen Sie keinen bloßen "Edit"-, "Write"- oder "NotebookEdit"-Eintrag in eine im Repository committete permissions.allow ein. Eine bloße Datei-Tool-Regel greift für das Tool unabhängig vom Pfad und erlaubt Schreibzugriffe überall auf dem Host statt nur im Arbeitsbereich, daher kennzeichnet der Schutzmechanismus des Runners zur Beschränkung des Schreibbereichs die Sitzung; mit --confine-repo-settings enforce verweigert er den Start der Sitzung, statt nur zu protokollieren und fortzufahren. Siehe den Abschnitt zur Härtung.

Ein Repository benötigt überhaupt keine Datei-Tool-Regel: Cloud-Sitzungen genehmigen Dateibearbeitungen unabhängig vom Modus vorab. Wenn Sie dennoch eine Regel committen, beschränken Sie sie auf den Arbeitsbereich, etwa "Edit(/**)"; ein einzelner führender Schrägstrich ist relativ zum Projektstammverzeichnis, das der Arbeitsbereich der Sitzung ist. Bloße Datei-Tool-Regeln sind in der settings.json auf Host-Ebene des Betreibers unproblematisch, da diese Datei nicht im Repository committet ist.

Ein defaultMode von auto wird nur aus der imageweiten Einstellungsdatei oder der Einstellungsdatei auf Benutzerebene berücksichtigt, sodass sich ein ausgechecktes Repository nicht selbst den Auto-Modus gewähren kann. Welche Modi Cloud-Sitzungen akzeptieren und die vollständige Regelsyntax finden Sie unter Berechtigungsmodi.

Nächste Schritte