Zum Hauptinhalt springen

​
Übersicht

Der Headless-Modus ermöglicht es Ihnen, Claude Code programmgesteuert aus Befehlszeilenskripten und Automatisierungstools ohne interaktive Benutzeroberfläche auszuführen.

​
Grundlegende Verwendung

Die primäre Befehlszeilenschnittstelle zu Claude Code ist der Befehl claude. Verwenden Sie das Flag --print (oder -p), um im nicht-interaktiven Modus zu laufen und das Endergebnis auszudrucken: 
claude -p "Stage my changes and write a set of commits for them" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

​
Konfigurationsoptionen

Der Headless-Modus nutzt alle CLI-Optionen, die in Claude Code verfügbar sind. Hier sind die wichtigsten für Automatisierung und Scripting:
FlagBeschreibungBeispiel
--print, -pIm nicht-interaktiven Modus ausführenclaude -p "query"
--output-formatAusgabeformat angeben (text, json, stream-json)claude -p --output-format json
--resume, -rKonversation nach Sitzungs-ID fortsetzenclaude --resume abc123
--continue, -cDie neueste Konversation fortsetzenclaude --continue
--verboseAusführliches Logging aktivierenclaude --verbose
--append-system-promptAn System-Prompt anhängen (nur mit --print)claude --append-system-prompt "Custom instruction"
--allowedToolsDurch Leerzeichen getrennte Liste zulässiger Tools oder

Zeichenkette mit durch Kommas getrennter Liste zulässiger Tools		claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsDurch Leerzeichen getrennte Liste verbotener Tools oder

Zeichenkette mit durch Kommas getrennter Liste verbotener Tools		claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configMCP-Server aus einer JSON-Datei ladenclaude --mcp-config servers.json
--permission-prompt-toolMCP-Tool zur Behandlung von Berechtigungsaufforderungen (nur mit --print)claude --permission-prompt-tool mcp__auth__prompt
Eine vollständige Liste der CLI-Optionen und Funktionen finden Sie in der Dokumentation zur CLI-Referenz.

​
Mehrteilige Konversationen

Für mehrteilige Konversationen können Sie Konversationen fortsetzen oder von der neuesten Sitzung aus fortfahren: 
# Die neueste Konversation fortsetzen
claude --continue "Now refactor this for better performance"

# Eine bestimmte Konversation nach Sitzungs-ID fortsetzen
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"

# Im nicht-interaktiven Modus fortsetzen
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix all linting issues" --no-interactive

​
Ausgabeformate

​
Textausgabe (Standard)

claude -p "Explain file src/components/Header.tsx"
# Output: This is a React component showing...

​
JSON-Ausgabe

Gibt strukturierte Daten einschließlich Metadaten zurück: 
claude -p "How does the data layer work?" --output-format json
Antwortformat: 
{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

​
Streaming-JSON-Ausgabe

Streamt jede Nachricht, während sie empfangen wird: 
claude -p "Build an application" --output-format stream-json
Jede Konversation beginnt mit einer anfänglichen init-Systemnachricht, gefolgt von einer Liste von Benutzer- und Assistentennachrichten, gefolgt von einer abschließenden result-Systemnachricht mit Statistiken. Jede Nachricht wird als separates JSON-Objekt ausgegeben.

​
Eingabeformate

​
Texteingabe (Standard)

# Direktes Argument
claude -p "Explain this code"

# Aus stdin
echo "Explain this code" | claude -p

​
Streaming-JSON-Eingabe

Ein Stream von Nachrichten, die über stdin bereitgestellt werden, wobei jede Nachricht eine Benutzerrunde darstellt. Dies ermöglicht mehrere Runden einer Konversation, ohne die claude-Binärdatei neu zu starten, und ermöglicht es, dem Modell Anleitung zu geben, während es eine Anfrage verarbeitet. Jede Nachricht ist ein JSON-Objekt vom Typ „Benutzernachricht”, das dem gleichen Format wie das Ausgabenachrichtenschema folgt. Nachrichten werden im jsonl-Format formatiert, wobei jede Eingabezeile ein vollständiges JSON-Objekt ist. Die Streaming-JSON-Eingabe erfordert -p und --output-format stream-json. 
echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

​
Beispiele für Agent-Integration

​
SRE-Incident-Response-Bot

#!/bin/bash

# Automatisierter Incident-Response-Agent
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "Incident: $incident_description (Severity: $severity)" \
      --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Verwendung
investigate_incident "Payment API returning 500 errors" "high"

​
Automatisierte Sicherheitsüberprüfung

# Sicherheitsaudit-Agent für Pull Requests
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Verwendung und in Datei speichern
audit_pr 123 > security-report.json

# Überprüfung von Rechtsdokumenten mit Sitzungspersistenz
session_id=$(claude -p "Start legal review session" --output-format json | jq -r '.session_id')

# Vertrag in mehreren Schritten überprüfen
claude -p --resume "$session_id" "Review contract.pdf for liability clauses"
claude -p --resume "$session_id" "Check compliance with GDPR requirements"
claude -p --resume "$session_id" "Generate executive summary of risks"

​
Best Practices

  • Verwenden Sie das JSON-Ausgabeformat für programmgesteuerte Analyse von Antworten: 
    # JSON-Antwort mit jq analysieren
result=$(claude -p "Generate code" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')
  • Fehler elegant behandeln - Überprüfen Sie Exit-Codes und stderr: 
    if ! claude -p "$prompt" 2>error.log; then
    echo "Error occurred:" >&2
    cat error.log >&2
    exit 1
fi
  • Verwenden Sie Sitzungsverwaltung zur Aufrechterhaltung des Kontexts in mehrteiligen Konversationen
  • Berücksichtigen Sie Timeouts für lang laufende Operationen: 
    timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
  • Beachten Sie Ratenlimits beim Erstellen mehrerer Anfragen, indem Sie Verzögerungen zwischen Aufrufen hinzufügen

​
Verwandte Ressourcen