Headless-Modus: Agenten ohne Interaktion betreiben

Im Headless- oder Non-interactive-Modus läuft ein KI-Agent ohne Chat-Fenster – ideal für Skripte und CI, aber ohne Rückfragen an dich.

Was Headless bedeutet

Normalerweise chattest du live mit einem Agenten: Er fragt nach, du antwortest, er macht weiter. Im Headless- oder Non-interactive-Modus fällt dieser Dialog weg. Du gibst einen Prompt als Argument oder über eine Pipe mit, der Agent arbeitet ihn ab und gibt am Ende eine Antwort zurück – ohne Zwischenfragen, ohne Chat-Fenster.

Wie das bei Claude Code aussieht

Der Befehl claude -p "Finde den Bug in auth.py" startet Claude Code non-interaktiv. Du kannst auch Daten hineinpipen: cat fehler.log | claude -p "Erkläre die Ursache". Die Ausgabe lässt sich als reiner Text oder als strukturiertes JSON abrufen (--output-format json), was sich gut in Skripte einbauen lässt.

Wofür man das nutzt

Batch-Verarbeitung: viele Dateien oder Tickets automatisch durchgehen
CI/CD: z. B. jeden Pull Request automatisch auf Tippfehler oder Sicherheitsprobleme prüfen
Cron-Jobs und geplante Automationen ohne menschliches Zutun

Das Risiko: keine Rückfragen

Der größte Unterschied zum interaktiven Modus: Der Agent kann dich nicht um Erlaubnis oder Klärung bitten. Läuft er auf ein Problem, für das er normalerweise nachfragen würde, muss er selbst entscheiden oder abbrechen. Deshalb ist die Wahl des Berechtigungs-Modus (siehe eigener Eintrag) im Headless-Betrieb besonders wichtig: Ohne klare Regeln kann ein Agent entweder zu wenig tun (bricht ständig ab) oder zu viel (führt riskante Aktionen ohne Nachfrage aus).

BEISPIEL

# CI-Skript: Tippfehler-Check für jeden PR-Diff git diff main | claude -p "Finde Tippfehler in diesem Diff. Gib für jeden Fund 'datei:zeile' und den Fehler aus, sonst nichts." --output-format json

🛠️ ÜBUNG — MACH DAS BEI DIR

Baue einen einfachen Headless-Aufruf, der eine Datei zusammenfasst, und beobachte, wie er sich ohne Rückfragen verhält.

Führe in einem Terminal aus: claude -p "Fasse diese Datei in 3 Sätzen zusammen" --allowedTools "Read" mit einer echten Datei aus deinem Projekt.
Wiederhole den Aufruf, aber gib eine Datei an, die nicht existiert – beobachte, wie der Agent ohne Rückfrage reagiert (Fehler statt Nachfrage).
Probiere --output-format json aus und schau dir das Ergebnis-JSON an: Welche Felder außer dem eigentlichen Text enthält es?

✅ SELBST-CHECK

☐ Konntest du erklären, warum der Agent bei der fehlenden Datei nicht einfach nachgefragt hat?
☐ Hast du verstanden, wofür --allowedTools in diesem Kontext gut ist?
☐ Weißt du, in welchen zwei Szenarien (Batch, CI) Headless-Betrieb aus dem Eintrag am meisten Sinn ergibt?

KURZ-QUIZ

Was ist das größte Risiko beim Betrieb eines Agenten im Headless-/Non-interactive-Modus?