Bash-Tool

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Das Bash-Tool ermöglicht Claude, Shell-Befehle in einer persistenten Bash-Sitzung auszuführen, was Systemoperationen, Skriptausführung und Befehlszeilenautomatisierung ermöglicht. Shell-Zugriff ist eine grundlegende Agent-Fähigkeit. Auf Terminal-Bench 2.0, einem Benchmark, der reale Terminal-Aufgaben mit Shell-only-Validierung bewertet, zeigt Claude starke Leistungsgewinne mit Zugriff auf eine persistente Bash-Sitzung.

Übersicht

Das Bash-Tool bietet Claude:

Persistente Bash-Sitzung, die den Zustand beibehält
Möglichkeit, jeden Shell-Befehl auszuführen
Zugriff auf Umgebungsvariablen und Arbeitsverzeichnis
Befehlsverkettung und Skriptfähigkeiten

Für Modellunterstützung siehe die Tool-Referenz.

Anwendungsfälle

Entwicklungs-Workflows: Führen Sie Build-Befehle, Tests und Entwicklungstools aus
Systemautomatisierung: Führen Sie Skripte aus, verwalten Sie Dateien, automatisieren Sie Aufgaben
Datenverarbeitung: Verarbeiten Sie Dateien, führen Sie Analyseskripte aus, verwalten Sie Datensätze
Umgebungssetup: Installieren Sie Pakete, konfigurieren Sie Umgebungen

Schnellstart

Funktionsweise

Das Bash-Tool verwaltet eine persistente Sitzung:

Claude bestimmt, welcher Befehl ausgeführt werden soll
Sie führen den Befehl in einer Bash-Shell aus
Geben Sie 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, es sei denn, restart wird verwendet

Beispiel: Mehrstufige Automatisierung

Claude kann Befehle verketten, um komplexe Aufgaben zu erledigen:

Benutzeranfrage:
"Installieren Sie die Requests-Bibliothek und erstellen Sie ein einfaches Python-Skript, das
einen Witz von einer API abruft, und führen Sie es dann aus."

Claudes Tool verwendet:
1. Paket installieren
   {"command": "pip install requests"}

2. Skript erstellen
   {"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. Skript ausführen
   {"command": "python fetch_joke.py"}

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

Implementieren Sie das Bash-Tool

Das Bash-Tool wird als schemalooses Tool implementiert. Bei der Verwendung dieses Tools müssen Sie kein Eingabeschema wie bei anderen Tools bereitstellen; das Schema ist in Claudes Modell integriert und kann nicht geändert werden.

Behandeln Sie Fehler

Bei der Implementierung des Bash-Tools müssen Sie verschiedene Fehlerszenarien behandeln:

Befolgen Sie Best Practices für die Implementierung

Sicherheit

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

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

Wichtige Empfehlungen

Verwenden Sie ulimit, um Ressourcenbeschränkungen festzulegen
Filtern Sie gefährliche Befehle (sudo, rm -rf, usw.)
Führen Sie mit minimalen Benutzerberechtigungen aus
Überwachen und protokollieren Sie alle Befehlsausführungen

Preisgestaltung

The bash tool adds 245 input tokens to your API calls.

Additional tokens are consumed by:

Command outputs (stdout/stderr)
Error messages
Large file contents

Siehe Tool-Use-Preisgestaltung für vollständige Preisdetails.

Häufige Muster

Entwicklungs-Workflows

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

Git-basierte Checkpointing

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

Erfassen Sie eine Baseline: Bevor die Agent-Arbeit beginnt, committen Sie den aktuellen Zustand. Dies ist der bekannt gute Ausgangspunkt.
Commit pro Feature: Jedes abgeschlossene Feature erhält seinen eigenen Commit. Diese dienen als Rollback-Punkte, falls später etwas schief geht.
Rekonstruieren Sie den Zustand beim Sitzungsstart: Lesen Sie git log zusammen mit einer Fortschrittsdatei, um zu verstehen, was bereits erledigt wurde und was als nächstes kommt.
Revert bei Fehler: Wenn die Arbeit schiefgeht, stellt git checkout den letzten guten Commit wieder her, anstatt zu versuchen, einen fehlerhaften Zustand zu debuggen.

Dateioperationen

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

Systemaufgaben

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

Einschränkungen

Keine interaktiven Befehle: Kann vim, less oder Passwort-Eingabeaufforderungen nicht verarbeiten
Keine GUI-Anwendungen: Nur Befehlszeilenversion
Sitzungsumfang: Der Bash-Sitzungszustand ist clientseitig. Die API ist zustandslos. Ihre Anwendung ist verantwortlich für die Verwaltung der Shell-Sitzung zwischen Umdrehungen.
Ausgabelimits: Große Ausgaben können gekürzt werden
Kein Streaming: Ergebnisse werden nach Abschluss zurückgegeben

Kombinieren mit anderen Tools

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

Wenn Sie auch das Code-Ausführungs-Tool verwenden, hat Claude Zugriff auf zwei separate Ausführungsumgebungen: Ihre lokale Bash-Sitzung und Anthropics Sandbox-Container. Der Zustand wird nicht zwischen ihnen geteilt. Siehe Verwendung der Code-Ausführung mit anderen Ausführungs-Tools für Anleitung zum Prompting von Claude, um zwischen Umgebungen zu unterscheiden.

Nächste Schritte

Tool-Use-Übersicht

Erfahren Sie mehr über Tool-Use mit Claude

Text-Editor-Tool

import anthropic

client = anthropic.Anthropic()

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

print(response)

Richten Sie eine Bash-Umgebung ein

Erstellen Sie 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()

Behandeln Sie die Befehlsausführung

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

def execute_command(self, command):
    # Send command to bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Capture output with timeout
    output = self._read_output(timeout=10)
    return output

Verarbeiten Sie Claudes Tool-Aufrufe

Extrahieren und führen Sie 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)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implementieren Sie Sicherheitsmaßnahmen

Fügen Sie Validierung und Einschränkungen hinzu. Verwenden Sie eine Allowlist anstelle einer Blocklist, da Blocklists leicht zu umgehen sind. Lehnen Sie Shell-Operatoren ab, damit verkettete Befehle nicht an der Allowlist vorbeigehen können:

import shlex

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


def validate_command(command):
    # Allow only commands from an explicit 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"

    # Reject shell operators that would chain additional commands
    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 Überprüfung ist eine erste Verteidigungslinie. Für stärkere Isolierung führen Sie validierte Befehle mit shell=False aus und übergeben Sie shlex.split(command) als Argumentliste, sodass die Shell den String nie interpretiert.

Übersicht

Anwendungsfälle

Schnellstart

Funktionsweise

Parameter

Beispielverwendung

Beispiel: Mehrstufige Automatisierung

Implementieren Sie das Bash-Tool

Behandeln Sie Fehler

Befehlsausführungs-Timeout

Befehl nicht gefunden

Befolgen Sie Best Practices für die Implementierung

Verwenden Sie Befehlszeitüberschreitungen

Sicherheit

Wichtige Empfehlungen

Preisgestaltung

Häufige Muster

Entwicklungs-Workflows

Git-basierte Checkpointing

Dateioperationen

Systemaufgaben

Einschränkungen

Kombinieren mit anderen Tools

Nächste Schritte

Berechtigung verweigert

Behalten Sie den Sitzungszustand bei

Behandeln Sie große Ausgaben

Protokollieren Sie alle Befehle

Bereinigen Sie Ausgaben