Headless-Modus

​

Überblick

Der Headless-Modus ermöglicht es Ihnen, Claude Code programmatisch über Kommandozeilen-Skripte und Automatisierungstools ohne interaktive Benutzeroberfläche auszuführen.

​

Grundlegende Verwendung

Die primäre Kommandozeilen-Schnittstelle zu Claude Code ist der claude-Befehl. Verwenden Sie das --print (oder -p) Flag, um im nicht-interaktiven Modus zu laufen und das endgültige Ergebnis auszugeben:

claude -p "Stage my changes and write a set of commits for them" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

​

Konfigurationsoptionen

Das SDK nutzt alle CLI-Optionen, die in Claude Code verfügbar sind. Hier sind die wichtigsten für die SDK-Verwendung:

Für eine vollständige Liste der CLI-Optionen und Features siehe die CLI-Referenz Dokumentation.

​

Multi-Turn-Unterhaltungen

Für Multi-Turn-Unterhaltungen können Sie Unterhaltungen fortsetzen oder von der neuesten Session weitermachen:

# Die neueste Unterhaltung fortsetzen
claude --continue "Now refactor this for better performance"

# Eine spezifische Unterhaltung nach Session-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"
# Ausgabe: 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, sobald sie empfangen wird:

claude -p "Build an application" --output-format stream-json

Jede Unterhaltung beginnt mit einer anfänglichen init System-Nachricht, gefolgt von einer Liste von Benutzer- und Assistenten-Nachrichten, gefolgt von einer finalen result System-Nachricht mit Statistiken. Jede Nachricht wird als separates JSON-Objekt ausgegeben.

​

Eingabeformate

​

Texteingabe (Standard)

# Direktes Argument
claude -p "Explain this code"

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

​

Streaming JSON-Eingabe

Ein Stream von Nachrichten, die über stdin bereitgestellt werden, wobei jede Nachricht einen Benutzer-Turn darstellt. Dies ermöglicht mehrere Turns einer Unterhaltung ohne Neustart der claude-Binärdatei und ermöglicht es, dem Modell Anleitung zu geben, während es eine Anfrage verarbeitet.

Jede Nachricht ist ein JSON ‘User message’-Objekt, das dem gleichen Format wie das Ausgabe-Nachrichtenschema folgt. Nachrichten werden im jsonl-Format formatiert, wobei jede Eingabezeile ein vollständiges JSON-Objekt ist. 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

​

Agent-Integrationsbeispiele

​

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

# Sicherheits-Audit-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

​

Multi-Turn-Rechtsassistent

# Rechtsdokument-Überprüfung mit Session-Persistenz
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

• JSON-Ausgabeformat verwenden für programmatisches Parsen von Antworten:

  # JSON-Antwort mit jq parsen
  result=$(claude -p "Generate code" --output-format json)
  code=$(echo "$result" | jq -r '.result')
  cost=$(echo "$result" | jq -r '.cost_usd')
  

• Fehler elegant behandeln - Exit-Codes und stderr prüfen:

  if ! claude -p "$prompt" 2>error.log; then
      echo "Error occurred:" >&2
      cat error.log >&2
      exit 1
  fi
  

• Session-Management verwenden für die Aufrechterhaltung des Kontexts in Multi-Turn-Unterhaltungen

• Timeouts berücksichtigen für langwierige Operationen:

  timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
  

• Rate-Limits respektieren bei mehreren Anfragen durch Hinzufügen von Verzögerungen zwischen Aufrufen

​

Verwandte Ressourcen

• CLI-Verwendung und -Steuerung - Vollständige CLI-Dokumentation
• Häufige Workflows - Schritt-für-Schritt-Anleitungen für häufige Anwendungsfälle