Skripte und CI

Die meisten Kapitel dieser Rubrik setzen voraus, dass jemand im Terminal sitzt, liest und antwortet. Claude Code läuft auch ohne diesen Menschen. Ein Shell-Skript ruft es mit einer einzigen Aufgabe auf und liest die Antwort. Ein eigenes Programm bindet es als Bibliothek ein. Eine Pipeline startet es bei jedem neuen Pull Request oder jede Nacht. Die Doku fasst alle drei Wege unter dem Namen Agent SDK zusammen. Es gibt ihn als Kommandozeile für Skripte und CI/CD und als Paket für Python und TypeScript (Doku zum Lauf ohne Terminal (externe Seite, code.claude.com)).

In allen drei Fällen fehlt der Mensch, der Rückfragen beantwortet, Fehler bemerkt und die Kosten im Blick behält. Dieses Kapitel zeigt, wie man das vorher festlegt. Wie Arbeit nach Zeitplan oder in der Cloud weiterläuft, steht in Kapitel 28.

Ein Auftrag ohne Dialog

Der Schalter -p, ausgeschrieben --print, macht aus Claude Code ein gewöhnliches Kom­man­do­zei­len­pro­gramm. Es nimmt die Aufgabe als Argument, arbeitet sie ab, gibt das Ergebnis aus und beendet sich. Was über eine Pipe hereinkommt, liest es mit:

cat build-error.txt \
  | claude -p \
  'Erkläre knapp die
  Ursache dieses
  Build-Fehlers' \
  > ursache.txt

Den Schalter gibt es seit dem ersten Tag. Die Doku vom 24.02.2025 führte claude -p als einmalige Anfrage, nach der das Programm endet (Archivfassung (externe Seite, docs.anthropic.com)). Ein Skript kann am Rückgabewert verzweigen: 0 heißt Erfolg, jeder andere Wert ein Fehlschlag.

Mit --output-format json kommt statt Text ein Objekt mit Ergebnis, Kennung der Sitzung und Verbrauch, mit --json-schema zusätzlich in einer vorgegebenen Form. Das nächste Programm liest es ohne Raten. Die Doku zeigt als Beispiel einen Prüfer für Tippfehler, der den Diff gegen main über die Pipe bekommt. Claude braucht dafür kein Recht auf die Shell. Wie ein Log über die Pipe bei der Wartung eines Rechners hilft, zeigt Kapitel 12.

Rechte vorher festlegen

Im Dialog fragt Claude Code nach, wenn weder eine Regel noch der Modus eine Aktion freigibt. Im Lauf mit -p sitzt niemand da, der antwortet. Was sonst eine Rückfrage auslöst, wird abgelehnt, und Claude arbeitet ohne diesen Schritt weiter. Die Rechte gehören deshalb in den Aufruf:

• --allowedTools gibt einzelne Werkzeuge frei, auch eng gefasst. Die Regel Bash(git diff *) erlaubt alle Befehle, die mit git diff beginnen.
• --permission-mode setzt die Haltung für den ganzen Lauf. Für eine abgeschottete CI nennt die Doku den Modus dontAsk: Claude Code lehnt dann jeden Aufruf ab, der sonst eine Rückfrage auslösen würde. Einen Teil davon kann ein installierter Mod trotzdem freigeben. Was ausdrücklich erlaubt ist oder ohnehin keine Freigabe braucht, etwa Lesen im Arbeits­ver­zeichnis, läuft weiter.

Setzen weder Aufruf noch Einstellungen einen Modus, beginnt der Lauf im eingebauten Startmodus. Für -p ist das Manual. Seit Version 2.1.302 vom 16.10.2026 gilt das auch bei einem Cloud-Anbieter, mit abgeschalteter Telemetrie und nach einer frischen Installation (Versionsliste (externe Seite, code.claude.com)). Von Version 2.1.285 bis 2.1.301 begann ein solcher Lauf dort im Auto-Modus. Wer sich auf einen Modus verlassen will, gibt ihn deshalb mit --permission-mode mit. Was eine still abgelehnte Aktion für das Ergebnis bedeutet, zeigt Vibe-Coding / Agentic Engineering, Kapitel 08.

Gleiches Ergebnis auf jeder Maschine

Ein Lauf mit -p lädt in der Voreinstellung alles, was auch eine Sitzung im Terminal lädt: Hooks, Skills, Plugins, MCP-Server, Gedächtnis und CLAUDE.md, aus dem Projekt wie aus ~/.claude. Auf dem eigenen Rechner ist das bequem. In der Pipeline kann derselbe Aufruf dann auf zwei Rechnern verschieden laufen. In einem fremden Repository führt er außerdem dessen Hooks aus und verbindet dessen MCP-Server, auch in einem Ordner, dem man nie vertraut hat. Eine Frage nach dem Vertrauen stellt ein Lauf mit -p nicht.

--bare schaltet dieses Einsammeln ab. Der Lauf startet schneller und lädt nur, was im Aufruf steht: zusätzliche Anweisungen, Einstellungen, MCP-Server, Subagents oder ein Plugin, je über einen eigenen Schalter. Die Doku nennt den Modus für CI und Skripte, die auf jeder Maschine dasselbe Ergebnis brauchen. Anthropic empfiehlt ihn für Skripte und Aufrufe aus dem SDK und will ihn in einer künftigen Version zum Standard für -p machen. Ein Datum dafür nennt die Doku nicht. Eine Bedingung hat der Modus: Er liest keine Anmeldung aus dem Abo, dazu unten mehr.

Claude Code als Bibliothek

Ein Aufruf mit -p reicht, solange ein Skript eine Frage stellt und eine Antwort liest. Ein eigenes Programm will mehr: Rückfragen an die eigene Oberfläche, eigene Werkzeuge, Sitzungen über viele Anfragen. Dafür gibt es das Agent SDK als Paket für TypeScript und Python. Es bietet dieselben Werkzeuge, dieselbe Schleife des Agenten und dieselbe Verwaltung des Kontexts wie Claude Code (Überblick zum Agent SDK (externe Seite, code.claude.com)). Unter der Oberfläche startet die Bibliothek das Programm Claude Code selbst.

Vorgestellt hat Anthropic das Claude Code SDK am 22.05.2025, zusammen mit Claude 4 (Ankündigung (externe Seite, anthropic.com)). Die Pakete für TypeScript und Python führt die Versionsliste unter Version 1.0.23 vom 16.06.2025 (Versionsliste (externe Seite, code.claude.com)). Mit Version 2.0.0 vom 29.09.2025 bekam es den heutigen Namen Claude Agent SDK, weil man damit Agenten auch für andere Aufgaben als Programmieren baut (Anleitung zum Umstieg (externe Seite, code.claude.com)).

Wer auf dem SDK ein Produkt für andere baut, darf ohne Zustimmung von Anthropic keine Anmeldung über claude.ai und keine Kontingente eines Abos anbieten. Die Doku verweist dafür auf API-Schlüssel.

Ein Token für Skripte und Pipelines

Die Anmeldung im Browser hilft in einer Pipeline nicht weiter. Zwei Wege führen dort zum Modell (Doku zur Anmeldung (externe Seite, code.claude.com)):

• Ein API-Schlüssel aus der Claude Console steht in der Variable ANTHROPIC_API_KEY und wird nach Verbrauch abgerechnet. Im Lauf mit -p nimmt Claude Code ihn ohne Rückfrage, sobald er gesetzt ist, auch auf einem Rechner, der im Abo angemeldet ist.
• Ein Token aus dem Abo erzeugt claude setup-token. Es gilt ein Jahr und gehört in die Variable CLAUDE_CODE_OAUTH_TOKEN. Die Doku nennt es ausdrücklich für Pipelines und Skripte ohne Browser. Es setzt Pro, Max, Team oder Enterprise voraus und kann nur Anfragen an das Modell stellen. Wie man es erzeugt, steht in Kapitel 02.

Im schlanken Modus mit --bare liest Claude Code keine Anmeldung aus dem Abo und keinen Schlüsselbund. Dort braucht es einen API-Schlüssel oder ein Skript, das einen liefert. Ein Token hängt außerdem am Abo der Person, die es erzeugt hat. Für ein Geheimnis, das viele Repositorys teilen, rät die Doku deshalb zu einem API-Schlüssel (Doku zu GitHub Actions (externe Seite, code.claude.com)).

Claude Code in GitHub Actions und GitLab CI/CD

Eine Pipeline startet Claude Code bei einem Ereignis: einem Kommentar, einem neuen Pull Request, einem Zeitplan. Für GitHub gibt es dafür die fertige Action anthropics/claude-code-action. Sie läuft in den Workflows des Repositorys und baut auf dem Agent SDK auf (Doku zu GitHub Actions (externe Seite, code.claude.com)). Anthropic stellte die Anbindung an GitHub am 22.05.2025 als Beta vor, als Beispiel für das SDK (Ankündigung (externe Seite, anthropic.com)).

Steht im Workflow kein Prompt, wartet die Action, bis jemand @claude in einem Issue oder Pull Request erwähnt, und antwortet dort. Steht ein Prompt darin, läuft sie bei jedem Ereignis, das den Workflow auslöst, auch nach Zeitplan. Die Workflow-Datei legt den Auslöser fest, die Rechte des Workflows, das Geheimnis für die Anmeldung und in claude_args die Schalter für Claude Code. Den Schlüssel selbst committet man nie. Er steht als Secret in den Einstellungen, und der Workflow verweist nur darauf. Wie die Arbeit mit @claude für ein Team aussieht und was /install-github-app einrichtet, beschreibt Kapitel 26.

In GitLab ist Claude Code ein gewöhnlicher Job in der .gitlab-ci.yml. Er installiert das Programm und ruft claude -p auf, der API-Schlüssel steht als maskierte Variable in den Einstellungen für CI/CD (Doku zu GitLab CI/CD (externe Seite, code.claude.com)). Die Anbindung ist eine Beta, und gepflegt wird sie von GitLab. Auf eine Erwähnung mit @claude reagiert ein solcher Job erst, wenn ein eigener Dienst die Kommentare über einen Webhook abhört und die Pipeline mit dem Auftrag startet.

Cloud-Sitzungen auf eigenen Rechnern

Ein Workflow auf GitHub läuft auf einem Runner, einem Rechner, der Jobs abholt und ausführt. Dasselbe Prinzip gibt es für die Cloud-Sitzungen von Claude Code (Doku zu selbst betriebenen Umgebungen (externe Seite, code.claude.com)). Seit Version 2.1.224 vom 07.08.2026 macht der Befehl claude self-hosted-runner einen eigenen Rechner oder Container zu einem Ort, an dem Sitzungen aus dem Web, der App fürs Handy und der Desktop-App laufen (Versionsliste (externe Seite, code.claude.com)). Selbst betriebene Umgebungen sind eine öffentliche Beta für Team und Enterprise und ab Werk ausgeschaltet.

Die Sitzungen erreichen dann interne Dienste, und Checkouts und Build-Ergebnisse bleiben auf eigenen Rechnern. Das Gespräch selbst geht weiter an Anthropic, und Anthropic verbindet sich laut Doku nie von außen in das eigene Netz. Die meisten Teams fahren laut Doku mit den Umgebungen bei Anthropic besser, weil die keinen eigenen Betrieb brauchen.

Was ein Lauf ohne Mensch kostet

Ein Lauf in der Pipeline verbraucht zweierlei: Rechenzeit auf dem Runner und Token beim Modell. Auf GitHub laufen die Jobs auf Runnern von GitHub und zehren vom Kontingent an Minuten für Actions. Mit dem Token aus dem Abo zählen die Läufe gegen das Abo, mit einem API-Schlüssel wird nach Verbrauch abgerechnet.

Drei Grenzen setzt man vorher:

• --max-turns begrenzt die Zahl der Runden und beendet den Lauf mit einem Fehler, wenn sie erreicht ist (CLI-Referenz (externe Seite, code.claude.com)).
• --max-budget-usd hält den Lauf an, sobald die geschätzten Kosten einen Betrag erreichen. Die Schätzung kann von der Rechnung abweichen, und der Lauf kann den Betrag überschreiten.
• eine Zeitgrenze für den Job in GitHub oder GitLab, damit ein hängender Lauf nicht weiterrechnet.

Einen gründlichen Review aus der Pipeline startet der Unterbefehl claude ultrareview. Er ist eine Research Preview, braucht ein Konto bei claude.ai und wird eigens abgerechnet, siehe Kapitel 25.

Wann sich welcher Weg lohnt

• Eine Frage, eine Antwort im Skript: claude -p, mit --output-format json oder einem Schema, wenn ein Programm weiterliest.
• Dasselbe Verhalten auf jedem Rechner: --bare mit API-Schlüssel und allem Nötigen im Aufruf.
• Ein Agent im eigenen Produkt: das Agent SDK, mit API-Schlüssel.
• Arbeit an Issues und Pull Requests: die Action für GitHub oder ein Job in GitLab, mit Rechten und Geheimnissen in der Workflow-Datei.
• Sitzungen, die interne Dienste erreichen müssen: ein eigener Runner, als Beta in Team und Enterprise.

Zwei häufige Fälle kommen ohne eigenen Workflow aus. Code Review prüft Pull Requests als Dienst von Anthropic, in den Tarifen Team und Enterprise, siehe Kapitel 25. Eine Routine startet bei einem Ereignis auf GitHub in der Cloud, ohne Workflow-Datei und ohne Runner, als Research Preview, siehe Kapitel 28.

Die erste Ebene hat die drei Wege ohne Terminal vorgestellt. Hier geht es um die Stellen, an denen ein solcher Lauf im Alltag hakt:

• ein Skript, das einen Fehlschlag für einen Erfolg hält,
• ein Lauf, der still einen Schritt auslässt,
• eine Pipeline, die auf zwei Rechnern verschieden arbeitet,
• ein Geheimnis, das an der falschen Person hängt.

Ausgabeformate und Rückgabewert

Mit --output-format json gibt claude -p ein Objekt aus. Die Antwort steht im Feld result, daneben die Kennung der Sitzung und die geschätzten Kosten in total_cost_usd, aufgeteilt nach Modell (Doku zum Lauf ohne Terminal (externe Seite, code.claude.com)). Wer mit --continue oder --resume an ein früheres Gespräch anknüpft, bekommt die Summe des ganzen Gesprächs, frühere Läufe eingerechnet. Ein Programm, das die Kosten je Lauf zählt, muss die Differenz bilden.

claude -p \
  "Fasse dieses Projekt
  zusammen" \
  --output-format json \
  | jq -r '.result'

--json-schema verlangt ein gültiges JSON Schema. Seit Version 2.1.205 vom 08.07.2026 (Versionsliste (externe Seite, code.claude.com)) bricht der Aufruf bei einem ungültigen Schema mit einer Meldung ab. Davor lieferte er still unstrukturierten Text. Das Schlüsselwort format, etwa für eine E-Mail-Adresse, nimmt Claude Code als Hinweis und prüft es nicht.

Am Rückgabewert hängt jede Verzweigung im Skript. Drei Fälle unterscheidet die Doku:

• Ein ungültiger Schalter meldet sich auf der Fehlerausgabe, bevor der Lauf beginnt.
• Ein Fehler im Lauf, etwa eine fehlende Anmeldung, steht als Ergebnis auf der Standardausgabe, und der Rückgabewert ist ungleich 0.
• Ein Abbruch von außen mit SIGTERM, etwa durch kill oder einen Prozesswächter, endet mit dem Wert 143. Die laufende Antwort bleibt unvollendet und hinterlässt kein Ergebnis. Wer die Antwort sauber beenden will, schickt vorher SIGINT.

Was über die Pipe hereinkommt, darf höchstens 10 MB groß sein. Darüber bricht der Lauf mit einer Meldung ab. Größere Eingaben schreibt man in eine Datei und nennt ihren Pfad im Prompt.

Was im Ereignisstrom steht

--output-format stream-json schreibt je Zeile ein JSON-Objekt. Die Doku ruft es zusammen mit --verbose auf. Mit --include-partial-messages, seit Version 1.0.109 vom 09.09.2025, kommen auch die einzelnen Textstücke, während das Modell schreibt. Die letzte Zeile ist immer eine Meldung vom Typ result mit Antwort, Kosten und Angaben zur Sitzung. Drei Ereignisse sind für eine Pipeline besonders nützlich:

• system/init kommt am Anfang und nennt Modell, Werkzeuge, MCP-Server und geladene Plugins. Die Felder plugin_errors und mcp_server_errors listen, was nicht geladen wurde. Ein Eintrag aus --mcp-config, der die Prüfung beim Start nicht besteht, fehlt im Lauf einfach, und der Lauf endet trotzdem regulär. Eine Prüfung in der CI kann deshalb scheitern lassen, sobald die Liste nicht leer ist.
• system/api_retry meldet neue Versuche nach einem behebbaren Fehler der Schnittstelle, mit Zähler, Wartezeit und Fehlerart, etwa rate_limit oder overloaded.
• permission_denied meldet abgelehnte Aktionen, und die Schlussmeldung zählt sie unter permission_denials auf.

Was Subagents tun, erscheint ebenfalls im Strom. Das Feld parent_tool_use_id sagt, zu welchem Lauf eine Meldung gehört, und ist für das Hauptgespräch leer. Text und Denkschritte der Subagents kommen erst mit --forward-subagent-text dazu, seit Version 2.1.211 vom 15.07.2026 (Versionsliste (externe Seite, code.claude.com)).

Rechtemodi im Lauf ohne Rückfrage

Drei Modi nennt die Doku für einen Lauf mit -p:

• auto: Ohne Rückfrage läuft, was ein Klassifikator an Stelle des Menschen durchwinkt. Abgelehnt wird, was er ablehnt.
• dontAsk: Ohne Rückfrage läuft, was Regeln erlauben oder ohnehin keine Freigabe braucht, etwa Lesen im Arbeits­ver­zeichnis. Abgelehnt wird alles, was sonst eine Rückfrage wäre. Einen Teil davon kann ein installierter Mod trotzdem freigeben.
• acceptEdits: Ohne Rückfrage laufen Schreiben in Dateien und gängige Dateibefehle wie mkdir, mv, cp. Abgelehnt werden andere Shell-Befehle und Netzzugriffe ohne Regel.

In dontAsk gilt eine Ausnahme: Rückfragen an den Menschen, Lesen über Netzwerkpfade und bestimmte MCP-Werkzeuge werden abgelehnt, selbst wenn eine Regel passt. Wie die Modi im Einzelnen arbeiten, steht in Vibe-Coding / Agentic Engineering, Kapitel 08. In welcher Reihenfolge Regeln, Modus und Klassifikator entscheiden, zeigt Kapitel 16.

--dangerously-skip-permissions, gleichbedeutend mit dem Modus bypassPermissions, schaltet Rückfragen und Sicher­heits­prü­fungen ab. Verbotsregeln gelten auch dort. Die Doku rät, ihn nur in abgeschotteten Umgebungen wie Containern oder VMs ohne Internetzugang zu nutzen (Doku zu den Rechtemodi (externe Seite, code.claude.com)). Gegen Prompt Injection schützt dieser Modus nicht.

Bei --allowedTools kommt es auf ein Leerzeichen an (Doku zum Lauf ohne Terminal (externe Seite, code.claude.com)). Bash(git diff *) erlaubt jeden Befehl, der mit git diff beginnt. Ohne das Leerzeichen vor dem Stern passt die Regel auch auf git diff-index. Ein bloßer Eintrag Bash gibt jeden Shell-Befehl frei, außer in einem Lauf im Auto-Modus. Dort streicht Claude Code den Eintrag und lässt jeden Befehl vom Klassifikator prüfen.

--permission-prompts none, seit Version 2.1.259 vom 02.09.2026, ist für Läufe gedacht, auf die niemand antworten kann, etwa einen geplanten Job. Regeln, Modus und ein Hook für PermissionRequest entscheiden weiter zuerst. Was danach noch eine Rückfrage wäre, wird abgelehnt, und Claude erfährt, dass niemand freigeben kann und ein neuer Versuch nichts bringt. Das Werkzeug für Fragen an den Menschen, AskUserQuestion, nimmt Claude Code aus dem Lauf. Ältere Fassungen kennen den Schalter nicht und brechen mit einer Meldung ab.

Befehle mit Schrägstrich gehen im Lauf nur zum Teil. Eigene Skills laufen: Steht /skill-name im Prompt, setzt Claude Code den Skill vor dem Lauf ein. Befehle, die nur die Oberfläche im Terminal kennt, etwa /login, gibt es nicht. /model, /effort und einige andere nehmen ihren Wert seit Version 2.1.205 als Argument, etwa /model sonnet.

Der schlanke Modus im Einzelnen

--bare lässt alles weg, was Claude Code sonst von selbst findet: Hooks, Skills, eigene Befehle, Subagents, Plugins, MCP-Server, das automatische Gedächtnis und die CLAUDE.md (Doku zum Lauf ohne Terminal (externe Seite, code.claude.com)). Claude hat dann die Shell und die Werkzeuge zum Lesen und Bearbeiten von Dateien. Was der Lauf sonst braucht, kommt über Schalter:

Eine Ausnahme: Aus einem Verzeichnis, das --add-dir nennt, lädt der Modus die Skills im Ordner .claude/skills/. Befehle und Subagents aus demselben Verzeichnis bleiben draußen.

Seit Version 2.1.286 vom 30.09.2026 gelten drei weitere Grenzen. Nur die MCP-Server aus der Befehlszeile werden verbunden. Claude bekommt keine Systemhinweise mehr, erfährt also zum Beispiel nicht, dass sich eine Datei geändert hat, die es vorher gelesen hat. Und es laufen keine Hin­ter­grund­auf­gaben: Ein Befehl, der seine Zeitgrenze erreicht, endet, statt in den Hintergrund zu wechseln (Versionsliste (externe Seite, code.claude.com)). Vorher galten diese Grenzen nur zum Teil.

Anmelden kann sich ein solcher Lauf über ANTHROPIC_API_KEY oder über ein apiKeyHelper in den Einstellungen, das einen Schlüssel liefert. Die Anmeldung aus dem Abo und den Schlüsselbund des Systems liest er nicht. Amazon Bedrock, Google Cloud und Microsoft Foundry lesen ihre Zugangsdaten wie gewohnt.

Ohne --bare lädt ein Lauf auch die installierten Plugins. Soll ein Container zur Laufzeit nichts klonen, legt man sie beim Bauen des Abbilds in einen Ordner und zeigt mit CLAUDE_CODE_PLUGIN_SEED_DIR darauf (Doku zu Umge­bungs­va­ria­blen (externe Seite, code.claude.com)). Claude Code registriert beim Start die Marktplätze aus diesem Ordner und nimmt die vorab geladenen Plugins, ohne sie neu zu klonen.

Was am Ende eines Laufs noch wartet

Hat Claude seine Antwort beendet, kann ein Lauf mit -p noch offen bleiben, weil Arbeit im Hintergrund läuft. Darauf wartet er (Doku zum Lauf ohne Terminal (externe Seite, code.claude.com)):

• Befehle aus dem Hauptgespräch, etwa ein Testserver, bis sie enden oder ihre Zeitgrenze erreichen. Danach antwortet Claude ein weiteres Mal mit dem Ergebnis.
• Subagents und Workflows im Hintergrund, bis sie fertig sind, weil ihr Ergebnis zur Ausgabe gehört.
• Beobachtungen mit Monitor, bis sie ablaufen.
• Weckrufe eines /loop, der sich selbst taktet, bis der Loop endet. Das gilt, wenn der Prompt als Text kam.

Wartet der Lauf zehn Minuten am Stück, ohne dass etwas geschieht, beendet Claude Code die übrige Arbeit und verwirft deren Teilergebnis. Ausgenommen sind Befehle aus dem Hauptgespräch, die noch laufen, und die Weckrufe eines /loop. Die Grenze verschiebt CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, der Wert 0 hebt sie auf. Erreicht der Lauf seinen Deckel aus --max-budget-usd, beendet Claude Code die Hintergrundarbeit, ohne zu warten. Wie lange ein einzelner Befehl im Hintergrund laufen darf, wenn niemand zusieht, steht in Kapitel 04.

Gespräche über mehrere Aufrufe

Ein Lauf mit -p legt eine Sitzung an wie jede andere. --continue setzt das jüngste Gespräch fort, --resume mit der Kennung ein bestimmtes. Die Kennung liest man aus der Ausgabe im Format JSON:

session_id=$(claude -p \
  "Beginne einen
  Review" \
  --output-format json \
  | jq -r '.session_id')
claude -p "Setze den
  Review fort" \
  --resume "$session_id"

Der zweite Aufruf darf aus einem anderen Verzeichnis kommen, Claude Code findet die Sitzung über ihre Kennung. Wer keine Spuren auf der Platte will, startet mit --no-session-persistence. Die Sitzung lässt sich dann nicht fortsetzen (CLI-Referenz (externe Seite, code.claude.com)). Eine Eigenart hat die Auswahl: Ein claude --continue im Terminal überspringt Sitzungen aus -p und dem SDK, ein claude -p --continue nimmt sie mit (Doku zu Sitzungen (externe Seite, code.claude.com)). Wie Sitzungen sonst gespeichert und fortgesetzt werden, steht in Kapitel 05.

Welche Zugangsdaten gelten

Liegen mehrere Zugangsdaten bereit, nimmt Claude Code die erste in dieser Reihenfolge (Doku zur Anmeldung (externe Seite, code.claude.com)):

1. die eines Cloud-Anbieters, wenn eine der Variablen CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX oder CLAUDE_CODE_USE_FOUNDRY gesetzt ist,
2. ANTHROPIC_AUTH_TOKEN für ein Gateway oder einen Proxy,
3. ANTHROPIC_API_KEY,
4. die Ausgabe eines apiKeyHelper, etwa für kurzlebige Schlüssel aus einem Tresor,
5. CLAUDE_CODE_OAUTH_TOKEN aus claude setup-token,
6. benannte Profile und Zugangsdaten über Workload Identity Federation,
7. die Anmeldung aus /login.

Für Skripte heißt das: Ein gesetzter API-Schlüssel schlägt das Token aus dem Abo. In der Sitzung im Terminal fragt Claude Code einmal, ob es den Schlüssel nehmen soll. Im Lauf mit -p nimmt es ihn ohne Frage. Wer im Abo abrechnen will, sorgt dafür, dass ANTHROPIC_API_KEY in der Umgebung des Laufs fehlt. Eine Cloud-Sitzung meldet sich dagegen immer mit dem Abo an, auch wenn dort ein Schlüssel gesetzt ist. Vor Version 2.1.225 vom 08.08.2026 konnte ein kurzer Fehler 401 das langlebige Token durch eine gespeicherte, kurzlebige Anmeldung ersetzen. Läufe ohne Terminal standen dann bis zum Neustart still (Versionsliste (externe Seite, code.claude.com)).

Die Workflow-Datei für GitHub Actions

So sieht ein Workflow aus, der auf @claude in Kommentaren antwortet (Doku zu GitHub Actions (externe Seite, code.claude.com)):

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Vier Zeilen darin sind keine Formsache. id-token: write braucht die Action für ihre Anmeldung als GitHub App. actions: read lässt Claude die Ergebnisse der CI an einem Pull Request lesen. actions/checkout legt eine Kopie des Repositorys auf den Runner, in der Claude arbeitet. Und die Bedingung unter if: verhindert, dass für jeden Kommentar ohne @claude ein Runner anläuft.

Mit einem Eingabewert prompt wird aus dem Workflow ein Automat, der bei jedem Ereignis läuft, auch nach Zeitplan unter schedule:. Bei einem Prompt aus reinem Text hat Claude dann weder Shell noch Zugriff auf die Schnittstelle von GitHub, bis man die nötigen Werkzeuge freigibt. Das geschieht über --allowedTools in claude_args oder über eine Regel im Eingabewert settings. Ein Skill als Prompt bringt die Werkzeuge mit, die sein Kopf erlaubt. Zwei Eigenarten von GitHub gehören dazu: Geplante Workflows laufen nur vom Standardbranch, und in öffentlichen Repositorys schaltet GitHub den Zeitplan nach 60 Tagen ohne Aktivität ab.

Eine dritte Eigenart fällt oft erst spät auf. Commits, die mit dem voreingestellten GITHUB_TOKEN entstehen, lösen bei GitHub keine Workflows aus. Gibt man der Action dieses Token mit, starten Claudes Commits also keine Workflows, auch keine Tests. Ohne den Eingabewert meldet sich die Action als Claude GitHub App an, und die CI läuft wie gewohnt. Unter welchem Namen Claude sonst auf GitHub schreibt, zeigt Kapitel 26.

Wer Workflows noch mit anthropics/claude-code-action@beta betreibt, stellt auf @v1 um. Der Eingabewert mode entfällt, weil die Action die Art selbst erkennt, aus direct_prompt wird prompt, und Schalter wie max_turns und model wandern nach claude_args.

Wer einen Lauf auslösen darf

Vor jedem Lauf prüft die Action den Auslöser zweimal. Bei Ereignissen an Issues und Pull Requests braucht die auslösende Person Schreibrecht im Repository. Ausnahmen stehen unter allowed_non_write_users und gelten nur mit einem eigenen github_token. Bots weist die Action ab, solange sie nicht unter allowed_bots stehen. Das verhindert, dass Bots Claude in einer Schleife immer wieder auslösen. Auch ein geplanter Lauf zählt dabei für eine Person, meist die, die den Zeitplan zuletzt geändert hat. War das ein Bot, muss er auf die Liste.

Bei öffentlichen Repositorys gibt GitHub die Secrets nicht an Läufe aus Pull Requests aus einem Fork weiter. Ein Review über einen Workflow läuft dort also nur für Branches im selben Repository.

Die Claude GitHub App bringt einen festen Satz von Rechten mit, den alle Funktionen von Claude auf GitHub teilen, darunter Code Review. GitHub erlaubt nur den ganzen Satz. Wer der Action nur Inhalte, Issues und Pull Requests geben will, legt eine eigene GitHub App mit genau diesen drei Rechten an. Code Review und die automatische Korrektur an Pull Requests brauchen weiter die offizielle App.

Ohne gespeicherten Schlüssel

Für eine ganze Organisation installiert man die App einmal, legt das Geheimnis als Secret der Organisation ab und legt den Workflow in jedes Repository oder ruft ihn dort als wie­der­ver­wend­baren Workflow auf. Ganz ohne langlebiges Geheimnis geht es über Workload Identity Federation: Die Action tauscht das OIDC-Token des Workflows gegen Zugang zur Schnittstelle von Anthropic, über ein Dienstkonto in der Claude Console. Der Workflow braucht dafür id-token: write.

Dasselbe Prinzip gilt für die Cloud-Anbieter. Ein Eingabewert der Action wählt den Anbieter:

• Amazon Bedrock mit use_bedrock: "true",
• Google Cloud mit use_vertex: "true",
• Microsoft Foundry mit use_foundry: "true".

Auf der Seite des Anbieters vertraut man dem OIDC-Token von GitHub, beschränkt auf das eigene Repository. Jeder Lauf bekommt damit kurzlebige Zugangsdaten (Doku zu Cloud-Anbietern in GitHub Actions (externe Seite, code.claude.com)). Für Commits und Kommentare wählt man selbst, unter welchem Namen die Action auftritt: als offizielle Claude GitHub App, als eigene App oder mit dem GITHUB_TOKEN, mit der Eigenart von oben.

Ein Job in GitLab CI/CD

In GitLab schreibt man den Job selbst (Doku zu GitLab CI/CD (externe Seite, code.claude.com)). Die Doku zeigt einen, der Claude Code im Container installiert und mit -p aufruft, hier gekürzt:

claude:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  before_script:
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"

Der API-Schlüssel steht als maskierte Variable unter Einstellungen, CI/CD, Variablen. Für Kommentare und Merge Requests braucht der Job Zugang zur Schnittstelle von GitLab, über CI_JOB_TOKEN oder ein Zugangstoken des Projekts mit dem Bereich api.

Auf @claude in einem Kommentar reagiert GitLab von sich aus nicht. Dafür braucht es einen Webhook für Kommentare, der einen eigenen Dienst aufruft. Der startet die Pipeline über die Schnittstelle für Auslöser und gibt den Auftrag in Variablen wie AI_FLOW_INPUT und AI_FLOW_CONTEXT mit. Für Amazon Bedrock und Google Cloud zeigt die Doku eigene Jobs, die sich über OIDC anmelden, ohne gespeicherten Schlüssel. Microsoft Foundry nennt die Seite für GitLab nicht.

Jeder Lauf arbeitet in einem Container mit strengen Regeln für Netz und Dateisystem, und jede Änderung kommt als Merge Request. Die Doku rät, diese Merge Requests zu prüfen wie die jedes anderen Beitragenden. Die Kosten setzen sich wie bei GitHub zusammen: Rechenminuten auf den Runnern des eigenen GitLab und Token beim Modell, begrenzt über --max-turns und das Schlüsselwort timeout des Jobs. Die genauen Schalter können sich mit der Fassung von Claude Code ändern.

Das Agent SDK im eigenen Programm

Das SDK heißt in npm @anthropic-ai/claude-agent-sdk und in Python claude-agent-sdk. Bis zur Umbenennung hießen die Pakete @anthropic-ai/claude-code und claude-code-sdk (Anleitung zum Umstieg (externe Seite, code.claude.com)). Mit der Fassung 0.1.0 des SDK kam eine Änderung, die beim Umstieg leicht durchrutscht: Das SDK nimmt nicht mehr von selbst die Systemanweisung von Claude Code. Wer sie will, verlangt sie ausdrücklich über die Vorgabe claude_code. Vorgaben wie Modell und Rechtemodus übergibt man im SDK als Optionen, in Python etwa model und permission_mode in ClaudeAgentOptions.

Die Einstellungen dagegen lädt das SDK ohne weitere Angabe wie die Kommandozeile, aus dem Nutzerverzeichnis, dem Projekt und der lokalen Datei, samt CLAUDE.md und eigenen Befehlen. Wer das nicht will, übergibt settingSources: [], in Python setting_sources=[]. Das Python-Paket bis Fassung 0.1.59 behandelte die leere Liste allerdings wie eine fehlende Angabe. Die Doku nennt diese Trennung besonders wichtig für Pipelines, Tests und Systeme mit mehreren Mandanten.

Im SDK stehen dieselben Bausteine bereit wie im Terminal: eingebaute Werkzeuge, Hooks, Subagents, MCP, Rechte und Sitzungen (Überblick zum Agent SDK (externe Seite, code.claude.com)). Rückfragen nach Erlaubnis beantwortet das eigene Programm über eine Rückruffunktion. Wer den Agenten auf einem Server betreibt, wählt, wie lange ein Container lebt: einer je Aufgabe, ein dauerhafter für viele Sitzungen oder einer, der seine Sitzungen aus einem Speicher wiederherstellt (Doku zum Betrieb des SDK (externe Seite, code.claude.com)). Der Unterschied zählt, weil der Zustand eines Agenten in der Voreinstellung im Dateisystem des Containers liegt. Ein Neustart löscht ihn.

Runner im eigenen Netz

Eine selbst betriebene Umgebung hat drei Teile (Doku zu selbst betriebenen Umgebungen (externe Seite, code.claude.com)):

• die Umgebung, ein benanntes Ziel, das die Organisation in den Einstellungen von claude.ai anlegt,
• den Runner, ein Programm auf eigenen Rechnern, das Sitzungen abholt und ausführt,
• die Sitzung, eine einzelne Aufgabe, die jemand gestartet hat.

Eine Cloud-Sitzung kann dort laufen, ob sie aus claude.ai, einer App, einer geplanten Routine oder dem Terminal kommt. Wer sie startet, wählt die Umgebung aus einer Liste. Ein Runner mit freier Kapazität übernimmt die Sitzung, klont das Repository und startet darin einen eigenen Prozess von Claude Code. Aus dem Terminal geht das mit claude --cloud oder mit -p und --environment samt der Kennung der Umgebung. Ein Runner arbeitet jeweils nur für einen Besitzer, meist die Person, die die Sitzung gestartet hat. Die erste Sitzung bindet ihn an diesen Besitzer, damit sich ausgecheckter Code verschiedener Besitzer nie mischt. Die kleinste Flotte hat deshalb so viele Runner, wie Besitzer gleichzeitig aktiv sind, Personen und Agenten von Claude Tag zusammengezählt.

Das Modell rufen die Sitzungen in der Voreinstellung über die Schnittstelle von Anthropic auf, auf Wunsch über Amazon Bedrock oder Google Cloud. Das Gespräch geht in beiden Fällen an Anthropic. Für Organisationen mit Zero Data Retention oder der Konfiguration für HIPAA gibt es die Funktion nicht, und Code Review und Claude Security laufen bisher nicht darüber. Abgerechnet wird wie bei den Umgebungen von Anthropic. Was eine Cloud-Sitzung ist und wie Routines darin laufen, steht in Kapitel 28.

Ein Lauf ohne Terminal hat drei Fragen zu beantworten, die im Dialog ein Mensch beantwortet: Was darf der Agent, mit wessen Zugang arbeitet er, und woran sieht man hinterher, was er getan hat. Diese Ebene zeigt, wie die Antworten in Versionen gewachsen sind, wo die Grenzen zu anderen Werkzeugen von Anthropic liegen und was Codex anders macht.

Wie die Funktionen dazukamen

Versionen mit Datum stammen aus der Versionsliste (externe Seite, code.claude.com), der Start aus der Archivfassung (externe Seite, docs.anthropic.com) der ersten Doku. Version 0.2.66 führt die Versionsliste mit vier Nachbarversionen unter einem gemeinsamen Tag, deshalb steht dort nur der Monat. SDK und Anbindung an GitHub stammen aus der Ankündigung von Claude 4 (externe Seite, anthropic.com).

Die ersten Monate brachten Formate und Pakete: Ausgabe für Programme, die SDKs, die Anbindung an GitHub. Seit dem Frühjahr 2026 kommen vor allem Schalter dazu, die einen Lauf ohne Menschen vorhersagbar machen:

• Der schlanke Modus lädt nichts von selbst.
• Der Kostendeckel greift auch auf Subagents.
• Die Fehlerlisten im Strom machen einen fehlenden Server sichtbar.
• --permission-prompts none beendet das Warten auf eine Antwort, die nie kommt.

Die Rückfragen zu übergehen war von Anfang an möglich. Die Doku vom Februar 2025 führte dafür --dangerously-skip-permissions und nannte ihn nur für Docker-Container ohne Internet (Archivfassung wie oben). Den Schalter gibt es weiter, gleichbedeutend mit dem Modus bypassPermissions, und die Doku rät auch heute zu abgeschotteten Umgebungen ohne Internetzugang, siehe die zweite Ebene. Für Läufe ohne Menschen gibt es daneben die Modi dontAsk und auto, siehe Kapitel 16.

Vier Wege zum selben Agenten

Agent SDK, Kommandozeile, Client SDK und Managed Agents unterscheiden sich darin, wer den Agenten betreibt, was eingebaut ist und wie man ihn erreicht (Überblick zum Agent SDK (externe Seite, code.claude.com)).

Jede Zeile kann etwas, das die anderen nicht können. Das Client SDK lässt die ganze Schleife in der eigenen Hand. Man schreibt sie selbst oder überlässt sie dem Tool Runner des Client SDK, einer Beta. Managed Agents nehmen den Betrieb ab, die Sitzungen laufen in einer Umgebung bei Anthropic oder in einer eigenen. Das Agent SDK liegt dazwischen. Es bringt die Werkzeuge, Rechte und Sitzungen von Claude Code mit und läuft dafür im eigenen Prozess, den man selbst betreibt. Was ein Harness ist und warum er die Leistung eines Modells mitbestimmt, steht in Agenten und Harness, Kapitel 04. Was das SDK anders voreinstellt als das Terminal, etwa einen knapperen Systemprompt, zeigt Kapitel 31 auf der zweiten Ebene.

Für Skripte ist die Abgrenzung zwischen claude -p und dem SDK fließend. Die Doku zum Lauf ohne Terminal behandelt -p als das Agent SDK über die Kommandozeile (Doku zum Lauf ohne Terminal (externe Seite, code.claude.com)). Die Pakete für Python und TypeScript bieten dazu strukturierte Ausgabe, Rückruffunktionen für Freigaben und Nachrichten als Objekte.

Fremder Text als Angriffsfläche

Im Dialog liest ein Mensch mit, was Claude tut. In einer Pipeline kommt der Auftrag oft von außen: aus dem Text eines Issues, einem Kommentar, dem Code eines Pull Requests. Wer dort etwas hineinschreibt, schreibt in den Prompt. Das ist der Fall der Prompt Injection, und die Hinweise zur Sicherheit der Action für GitHub gehen an mehreren Stellen darauf ein (Sicher­heits­hin­weise zur Action (externe Seite, github.com)):

• Schreibrecht als erste Schranke. Auslösen dürfen nur Personen mit Schreibrecht im Repository. Wer diese Prüfung mit allowed_non_write_users aufweicht, gibt den Workflow für Fremde frei. Bots auf der Liste allowed_bots prüft die Action nicht auf Rechte im Repository.
• Kurzlebige Token. Für Läufe mit allowed_non_write_users braucht die Action ein eigenes Token für GitHub. Ein persönliches Zugangstoken ändert sich zwischen den Läufen nicht. Über Prompt Injection kann es nach und nach ganz oder teilweise abfließen. Die Hinweise raten zum automatisch erzeugten Token des Workflows, das mit dem Job abläuft.
• Kein fremder Code im Arbeits­ver­zeichnis. Workflows mit pull_request_target oder workflow_run laufen mit den Secrets des Hauptrepositorys. Wer vor der Action den Stand eines fremden Pull Requests auscheckt, lässt Claude in diesem Stand arbeiten.

Für Läufe, die Fremde auslösen dürfen, entfernt die Action Schlüssel von Anthropic, der Cloud und GitHub so weit wie möglich aus der Umgebung der Unterprozesse. Die Hinweise sagen selbst, wie weit das reicht: Es senkt das Risiko der Prompt Injection, ein Rest bleibt. Deshalb gelten zwei Regeln für jeden solchen Workflow. Er bekommt nur die Rechte, die er braucht, und seine Ausgaben werden geprüft. Bei Pull Requests holt die Action die Konfiguration von Claude, etwa .claude/, .mcp.json und CLAUDE.md, vor dem Start aus dem Basisbranch. Wer Claude Code selbst mit -p aufruft, braucht eine dritte Regel: Ohne --bare führt Claude Code die Hooks und MCP-Server eines Repositorys aus, auch eines fremden, siehe die erste Ebene und Vibe-Coding / Agentic Engineering, Kapitel 08.

Wessen Zugang ein Lauf benutzt

Jede Anmeldung bindet einen Lauf an jemanden, und die Wahl entscheidet über Abrechnung und Grenzen:

• Ein Token aus claude setup-token gehört einer Person und ihrem Abo. Für den eigenen Rechner und eigene Skripte passt das. Für ein Geheimnis der Organisation passt es schlecht. Alle Läufe hängen dann am Abo dieser Person, und das Token kann nur Anfragen an das Modell stellen.
• Ein API-Schlüssel stammt aus der Claude Console und wird nach Verbrauch abgerechnet. Im Lauf mit -p gewinnt er gegen das Token, sobald er in der Umgebung steht (Doku zur Anmeldung (externe Seite, code.claude.com)).
• Workload Identity Federation tauscht das kurzlebige Token des Workflows gegen Zugang über ein Dienstkonto. Ein langlebiges Geheimnis liegt dann nirgends (Doku zu GitHub Actions (externe Seite, code.claude.com)).

Produkte auf dem Agent SDK melden sich mit einem API-Schlüssel an. Die Anmeldung über claude.ai darf ein fremdes Produkt nur mit Zustimmung von Anthropic anbieten, siehe die erste Ebene. In Enterprise legt seit Version 2.1.212 vom 17.07.2026 die Einstellung forceLoginMethod auch für SDK, setup-token und install-github-app fest, welche Art der Anmeldung gilt (Versionsliste (externe Seite, code.claude.com)). Die Prüfung der Organisation über forceLoginOrgUUID greift bei setup-token und install-github-app dagegen nicht. Beide können ein Token in einer anderen Organisation erzeugen. Wie Einstellungen einer Organisation verteilt werden, beschreibt Kapitel 15.

Was Codex anders löst

OpenAI bietet für Codex dieselben Wege an: codex exec für Skripte und CI, ein SDK und eine Action für GitHub. Drei Unterschiede fallen in der Doku auf (Doku zu Codex ohne Dialog (externe Seite, learn.chatgpt.com)).

Der erste betrifft die Voreinstellung. codex exec läuft ohne weitere Angabe in einer Sandbox, die nur lesen darf. Schreiben erlaubt man ausdrücklich. Claude Code beginnt im Lauf mit -p im eingebauten Startmodus. Das ist seit Version 2.1.302 überall Manual, siehe die erste Ebene. Die Sandbox für Befehle ist eine eigene Einstellung. Wer bei Claude Code dieselbe Ausgangslage will, setzt den Modus und die Sandbox selbst, siehe Kapitel 16.

Der zweite betrifft den Schlüssel. Die Action von Codex startet einen Proxy für die Schnittstelle und soll so den API-Schlüssel seltener offenlegen. Die Doku nennt auch den Grund: Steht der Schlüssel als Variable des Jobs bereit, können Build-Skripte, Tests und Hooks von Abhängigkeiten im selben Job ihn lesen. Die Action von Claude Code geht dasselbe Problem mit Workload Identity Federation an und, bei Läufen für Fremde, mit dem Ausräumen der Umgebung von Unterprozessen.

Der dritte betrifft das Verzeichnis. Codex verlangt ein Git-Repository, um zerstörerische Änderungen zu verhindern, und lässt sich nur mit einem eigenen Schalter davon abbringen. Bei der Anmeldung sind sich beide einig: Für Automatisierung empfiehlt auch OpenAI den API-Schlüssel.

Was offen bleibt

• Wann --bare Standard wird. Die Doku kündigt den Wechsel für -p an, ohne Datum. Skripte, die heute ohne den Schalter auf Hooks, Skills oder die CLAUDE.md des Projekts bauen, ändern dann ihr Verhalten.
• Wie es mit GitLab weitergeht. Die Anbindung ist eine Beta und wird von GitLab gepflegt. Ihre Funktionen können sich laut Doku noch ändern. Für Hilfe verweist die Doku auf einen Vorgang bei GitLab. Microsoft Foundry nennt sie dort nicht.
• Was selbst betriebene Umgebungen noch lernen. Sie sind eine öffentliche Beta. Code Review und Claude Security laufen dort bisher nicht, die Doku kündigt das getrennt an (Doku zu selbst betriebenen Umgebungen (externe Seite, code.claude.com)).
• Was ein Lauf wirklich gekostet hat. total_cost_usd und der Kostendeckel rechnen mit einer Schätzung im Programm. Die Rechnung kommt vom Anbieter und kann abweichen.