MessagesTools

Bash-Tool

Diese Funktion ist für Zero Data Retention (ZDR) qualifiziert. Wenn deine Organisation eine ZDR-Vereinbarung hat, werden Daten, die über diese Funktion gesendet werden, nicht gespeichert, nachdem die API-Antwort zurückgegeben wurde.

Das Bash-Tool ermöglicht es Claude, Shell-Befehle in einer persistenten Bash-Sitzung auszuführen, wodurch Systemoperationen, Skriptausführung und Kommandozeilen-Automatisierung möglich werden. Shell-Zugriff ist eine grundlegende Agent-Fähigkeit. Bei Terminal-Bench 2.0, einem Benchmark, der reale Terminal-Aufgaben mit reiner Shell-Validierung bewertet, zeigt Claude deutliche Leistungssteigerungen mit Zugriff auf eine persistente Bash-Sitzung.

Überblick

Das Bash-Tool bietet Claude:

Eine persistente Bash-Sitzung, die ihren Zustand beibehält
Die Möglichkeit, beliebige Shell-Befehle auszuführen
Zugriff auf Umgebungsvariablen und das Arbeitsverzeichnis
Befehlsverkettung und Scripting-Fähigkeiten

Informationen zur Modellunterstützung findest du in der Tool-Referenz.

Anwendungsfälle

Entwicklungs-Workflows: Build-Befehle, Tests und Entwicklungstools ausführen
Systemautomatisierung: Skripte ausführen, Dateien verwalten, Aufgaben automatisieren
Datenverarbeitung: Dateien verarbeiten, Analyseskripte ausführen, Datensätze verwalten
Umgebungseinrichtung: Pakete installieren, Umgebungen konfigurieren

Schnellstart

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Funktionsweise

Das Bash-Tool verwaltet eine persistente Sitzung:

Claude bestimmt, welcher Befehl ausgeführt werden soll
Du führst den Befehl in einer Bash-Shell aus
Du gibst die Ausgabe (stdout und stderr) an Claude zurück
Der Sitzungszustand bleibt zwischen Befehlen erhalten (Umgebungsvariablen, Arbeitsverzeichnis)

Parameter

Parameter	Erforderlich	Beschreibung
`command`	Ja*	Der auszuführende Bash-Befehl
`restart`	Nein	Auf `true` setzen, um die Bash-Sitzung neu zu starten

*Erforderlich, sofern nicht restart verwendet wird

Beispiel: Mehrstufige Automatisierung

Claude kann Befehle verketten, um komplexe Aufgaben zu erledigen:

User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Claude's tool uses:
1. Install package
   {"command": "pip install requests"}

2. Create script
   {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

3. Run script
   {"command": "python fetch_joke.py"}

Die Sitzung behält ihren Zustand zwischen Befehlen bei, sodass in Schritt 2 erstellte Dateien in Schritt 3 verfügbar sind.

Das Bash-Tool implementieren

Das Bash-Tool ist als schemaloses Tool implementiert. Bei der Verwendung dieses Tools musst du kein Input-Schema bereitstellen wie bei anderen Tools; das Schema ist in Claudes Modell integriert und kann nicht geändert werden.

Eine Bash-Umgebung einrichten

Erstelle eine persistente Bash-Sitzung, mit der Claude interagieren kann:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Befehlsausführung handhaben

Erstelle eine Funktion, um Befehle auszuführen und die Ausgabe zu erfassen:

def execute_command(self, command):
    # Sende Befehl an bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Erfasse Ausgabe mit Timeout
    output = self._read_output(timeout=10)
    return output

Claudes Tool-Aufrufe verarbeiten

Extrahiere und führe Befehle aus Claudes Antworten aus:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Gib das Ergebnis an Claude zurück
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Sicherheitsmaßnahmen implementieren

Füge Validierung und Einschränkungen hinzu. Verwende eine Allowlist statt einer Blocklist, da Blocklists leicht zu umgehen sind. Lehne Shell-Operatoren ab, damit verkettete Befehle nicht an der Allowlist vorbeikommen:

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Erlaube nur Befehle aus einer expliziten Allowlist
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # Lehne Shell-Operatoren ab, die zusätzliche Befehle verketten würden
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

Diese Prüfung ist eine erste Verteidigungslinie. Für eine stärkere Isolation führe validierte Befehle mit shell=False aus und übergib shlex.split(command) als Argumentliste, damit die Shell den String niemals interpretiert.

Fehler behandeln

Bei der Implementierung des Bash-Tools solltest du verschiedene Fehlerszenarien behandeln:

Best Practices für die Implementierung befolgen

Sicherheit

Das Bash-Tool bietet direkten Systemzugriff. Implementiere diese wesentlichen Sicherheitsmaßnahmen:

Ausführung in isolierten Umgebungen (Docker/VM)
Implementierung von Befehlsfilterung und Allowlists
Festlegen von Ressourcenlimits (CPU, Speicher, Festplatte)
Protokollierung aller ausgeführten Befehle

Wichtige Empfehlungen

Verwende ulimit, um Ressourcenbeschränkungen festzulegen
Filtere gefährliche Befehle (sudo, rm -rf usw.)
Führe mit minimalen Benutzerberechtigungen aus
Überwache und protokolliere die gesamte Befehlsausführung

Preise

Das Bash-Tool fügt deinen API-Aufrufen 245 Input-Tokens hinzu.

Zusätzliche Tokens werden verbraucht durch:

Befehlsausgaben (stdout/stderr)
Fehlermeldungen
Große Dateiinhalte

Siehe Preise für Tool-Nutzung für vollständige Preisdetails.

Gängige Muster

Entwicklungs-Workflows

Tests ausführen: pytest && coverage report
Projekte bauen: npm install && npm run build
Git-Operationen: git status && git add . && git commit -m "message"

Git-basiertes Checkpointing

Git dient in lang laufenden Agent-Workflows als strukturierter Wiederherstellungsmechanismus, nicht nur als Möglichkeit, Änderungen zu speichern:

Eine Baseline erfassen: Bevor die Agent-Arbeit beginnt, committe den aktuellen Zustand. Dies ist der bekannte, funktionierende Ausgangspunkt.
Commit pro Feature: Jedes abgeschlossene Feature erhält einen eigenen Commit. Diese dienen als Rollback-Punkte, falls später etwas schiefgeht.
Zustand beim Sitzungsstart rekonstruieren: Lies git log zusammen mit einer Fortschrittsdatei, um zu verstehen, was bereits erledigt wurde und was als Nächstes kommt.
Bei Fehlern zurücksetzen: Wenn die Arbeit schiefläuft, setzt git checkout auf den letzten funktionierenden Commit zurück, anstatt zu versuchen, einen kaputten Zustand zu debuggen.

Dateioperationen

Daten verarbeiten: wc -l *.csv && ls -lh *.csv
Dateien durchsuchen: find . -name "*.py" | xargs grep "pattern"
Backups erstellen: tar -czf backup.tar.gz ./data

Systemaufgaben

Ressourcen prüfen: df -h && free -m
Prozessverwaltung: ps aux | grep python
Umgebungseinrichtung: export PATH=$PATH:/new/path && echo $PATH

Einschränkungen

Keine interaktiven Befehle: Kann vim, less oder Passwortabfragen nicht verarbeiten
Keine GUI-Anwendungen: Nur Kommandozeile
Sitzungsumfang: Der Zustand der Bash-Sitzung liegt clientseitig. Die API ist zustandslos. Deine Anwendung ist dafür verantwortlich, die Shell-Sitzung zwischen den Turns aufrechtzuerhalten.
Ausgabelimits: Große Ausgaben können gekürzt werden
Kein Streaming: Ergebnisse werden nach Abschluss zurückgegeben

Kombination mit anderen Tools

Das Bash-Tool ist am leistungsfähigsten, wenn es mit dem Texteditor und anderen Tools kombiniert wird.

Wenn du auch das Code-Execution-Tool verwendest, hat Claude Zugriff auf zwei separate Ausführungsumgebungen: deine lokale Bash-Sitzung und Anthropics Sandbox-Container. Der Zustand wird nicht zwischen ihnen geteilt. Siehe Code-Ausführung mit anderen Ausführungstools verwenden für Hinweise, wie du Claude anweisen kannst, zwischen den Umgebungen zu unterscheiden.

Nächste Schritte

Überblick über Tool-Nutzung

Erfahre mehr über Tool-Nutzung mit Claude

Texteditor-Tool

Textdateien mit Claude anzeigen und bearbeiten

Was this page helpful?

MessagesTools

Bash-Tool

Überblick

Das Bash-Tool bietet Claude:

Eine persistente Bash-Sitzung, die ihren Zustand beibehält
Die Möglichkeit, beliebige Shell-Befehle auszuführen
Zugriff auf Umgebungsvariablen und das Arbeitsverzeichnis
Befehlsverkettung und Scripting-Fähigkeiten

Informationen zur Modellunterstützung findest du in der Tool-Referenz.

Anwendungsfälle

Entwicklungs-Workflows: Build-Befehle, Tests und Entwicklungstools ausführen
Systemautomatisierung: Skripte ausführen, Dateien verwalten, Aufgaben automatisieren
Datenverarbeitung: Dateien verarbeiten, Analyseskripte ausführen, Datensätze verwalten
Umgebungseinrichtung: Pakete installieren, Umgebungen konfigurieren

Schnellstart

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Funktionsweise

Das Bash-Tool verwaltet eine persistente Sitzung:

Claude bestimmt, welcher Befehl ausgeführt werden soll
Du führst den Befehl in einer Bash-Shell aus
Du gibst die Ausgabe (stdout und stderr) an Claude zurück
Der Sitzungszustand bleibt zwischen Befehlen erhalten (Umgebungsvariablen, Arbeitsverzeichnis)

Parameter

Parameter	Erforderlich	Beschreibung
`command`	Ja*	Der auszuführende Bash-Befehl
`restart`	Nein	Auf `true` setzen, um die Bash-Sitzung neu zu starten

*Erforderlich, sofern nicht restart verwendet wird

Beispiel: Mehrstufige Automatisierung

Claude kann Befehle verketten, um komplexe Aufgaben zu erledigen:

User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Claude's tool uses:
1. Install package
   {"command": "pip install requests"}

2. Create script
   {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

3. Run script
   {"command": "python fetch_joke.py"}

Die Sitzung behält ihren Zustand zwischen Befehlen bei, sodass in Schritt 2 erstellte Dateien in Schritt 3 verfügbar sind.

Das Bash-Tool implementieren

Eine Bash-Umgebung einrichten

Erstelle eine persistente Bash-Sitzung, mit der Claude interagieren kann:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Befehlsausführung handhaben

Erstelle eine Funktion, um Befehle auszuführen und die Ausgabe zu erfassen:

def execute_command(self, command):
    # Sende Befehl an bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Erfasse Ausgabe mit Timeout
    output = self._read_output(timeout=10)
    return output

Claudes Tool-Aufrufe verarbeiten

Extrahiere und führe Befehle aus Claudes Antworten aus:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Gib das Ergebnis an Claude zurück
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Sicherheitsmaßnahmen implementieren

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Erlaube nur Befehle aus einer expliziten Allowlist
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # Lehne Shell-Operatoren ab, die zusätzliche Befehle verketten würden
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

Fehler behandeln

Bei der Implementierung des Bash-Tools solltest du verschiedene Fehlerszenarien behandeln:

Best Practices für die Implementierung befolgen

Sicherheit

Das Bash-Tool bietet direkten Systemzugriff. Implementiere diese wesentlichen Sicherheitsmaßnahmen:

Ausführung in isolierten Umgebungen (Docker/VM)
Implementierung von Befehlsfilterung und Allowlists
Festlegen von Ressourcenlimits (CPU, Speicher, Festplatte)
Protokollierung aller ausgeführten Befehle

Wichtige Empfehlungen

Verwende ulimit, um Ressourcenbeschränkungen festzulegen
Filtere gefährliche Befehle (sudo, rm -rf usw.)
Führe mit minimalen Benutzerberechtigungen aus
Überwache und protokolliere die gesamte Befehlsausführung

Preise

Das Bash-Tool fügt deinen API-Aufrufen 245 Input-Tokens hinzu.

Zusätzliche Tokens werden verbraucht durch:

Befehlsausgaben (stdout/stderr)
Fehlermeldungen
Große Dateiinhalte

Siehe Preise für Tool-Nutzung für vollständige Preisdetails.

Gängige Muster

Entwicklungs-Workflows

Tests ausführen: pytest && coverage report
Projekte bauen: npm install && npm run build
Git-Operationen: git status && git add . && git commit -m "message"

Git-basiertes Checkpointing

Git dient in lang laufenden Agent-Workflows als strukturierter Wiederherstellungsmechanismus, nicht nur als Möglichkeit, Änderungen zu speichern:

Eine Baseline erfassen: Bevor die Agent-Arbeit beginnt, committe den aktuellen Zustand. Dies ist der bekannte, funktionierende Ausgangspunkt.
Commit pro Feature: Jedes abgeschlossene Feature erhält einen eigenen Commit. Diese dienen als Rollback-Punkte, falls später etwas schiefgeht.
Zustand beim Sitzungsstart rekonstruieren: Lies git log zusammen mit einer Fortschrittsdatei, um zu verstehen, was bereits erledigt wurde und was als Nächstes kommt.
Bei Fehlern zurücksetzen: Wenn die Arbeit schiefläuft, setzt git checkout auf den letzten funktionierenden Commit zurück, anstatt zu versuchen, einen kaputten Zustand zu debuggen.

Dateioperationen

Daten verarbeiten: wc -l *.csv && ls -lh *.csv
Dateien durchsuchen: find . -name "*.py" | xargs grep "pattern"
Backups erstellen: tar -czf backup.tar.gz ./data

Systemaufgaben

Ressourcen prüfen: df -h && free -m
Prozessverwaltung: ps aux | grep python
Umgebungseinrichtung: export PATH=$PATH:/new/path && echo $PATH

Einschränkungen

Keine interaktiven Befehle: Kann vim, less oder Passwortabfragen nicht verarbeiten
Keine GUI-Anwendungen: Nur Kommandozeile
Sitzungsumfang: Der Zustand der Bash-Sitzung liegt clientseitig. Die API ist zustandslos. Deine Anwendung ist dafür verantwortlich, die Shell-Sitzung zwischen den Turns aufrechtzuerhalten.
Ausgabelimits: Große Ausgaben können gekürzt werden
Kein Streaming: Ergebnisse werden nach Abschluss zurückgegeben

Kombination mit anderen Tools

Das Bash-Tool ist am leistungsfähigsten, wenn es mit dem Texteditor und anderen Tools kombiniert wird.

Nächste Schritte

Überblick über Tool-Nutzung

Erfahre mehr über Tool-Nutzung mit Claude

Texteditor-Tool

Textdateien mit Claude anzeigen und bearbeiten

Was this page helpful?

Überblick

Anwendungsfälle

Schnellstart

Funktionsweise

Parameter

Beispielverwendung

Beispiel: Mehrstufige Automatisierung

Das Bash-Tool implementieren

Fehler behandeln

Timeout bei der Befehlsausführung

Befehl nicht gefunden

Zugriff verweigert

Best Practices für die Implementierung befolgen

Befehls-Timeouts verwenden

Sitzungszustand beibehalten

Große Ausgaben handhaben

Alle Befehle protokollieren

Ausgaben bereinigen

Sicherheit

Wichtige Empfehlungen

Preise

Gängige Muster

Entwicklungs-Workflows

Git-basiertes Checkpointing

Dateioperationen

Systemaufgaben

Einschränkungen

Kombination mit anderen Tools

Nächste Schritte

Überblick

Anwendungsfälle

Schnellstart

Funktionsweise

Parameter

Beispielverwendung

Beispiel: Mehrstufige Automatisierung

Das Bash-Tool implementieren

Fehler behandeln

Timeout bei der Befehlsausführung

Befehl nicht gefunden

Zugriff verweigert

Best Practices für die Implementierung befolgen

Befehls-Timeouts verwenden

Sitzungszustand beibehalten

Große Ausgaben handhaben

Alle Befehle protokollieren

Ausgaben bereinigen

Sicherheit

Wichtige Empfehlungen

Preise

Gängige Muster

Entwicklungs-Workflows

Git-basiertes Checkpointing

Dateioperationen

Systemaufgaben

Einschränkungen

Kombination mit anderen Tools

Nächste Schritte

Überblick

Anwendungsfälle

Schnellstart

Funktionsweise

Parameter

Beispiel: Mehrstufige Automatisierung

Das Bash-Tool implementieren

Fehler behandeln

Best Practices für die Implementierung befolgen

Sicherheit

Wichtige Empfehlungen

Preise

Gängige Muster

Entwicklungs-Workflows

Git-basiertes Checkpointing

Dateioperationen

Systemaufgaben

Einschränkungen

Kombination mit anderen Tools

Nächste Schritte

Überblick

Anwendungsfälle

Schnellstart

Funktionsweise

Parameter

Beispiel: Mehrstufige Automatisierung

Das Bash-Tool implementieren

Fehler behandeln

Best Practices für die Implementierung befolgen

Sicherheit

Wichtige Empfehlungen

Preise

Gängige Muster

Entwicklungs-Workflows

Git-basiertes Checkpointing

Dateioperationen

Systemaufgaben

Einschränkungen

Kombination mit anderen Tools

Nächste Schritte