Bash-Tool

ErstellenTools

Bash-Tool

Das Bash-Tool ermöglicht Claude, Shell-Befehle in einer persistenten Bash-Sitzung auszuführen und ermöglicht Systemoperationen, Skriptausführung und Befehlszeilenautomatisierung.

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

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)

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.

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.

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

Anzeigen und Bearbeiten von Textdateien mit Claude

Was this page helpful?

ErstellenTools

Bash-Tool

Das Bash-Tool ermöglicht Claude, Shell-Befehle in einer persistenten Bash-Sitzung auszuführen und ermöglicht Systemoperationen, Skriptausführung und Befehlszeilenautomatisierung.

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.

Ü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

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)

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

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

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

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.

Nächste Schritte

Tool-Use-Übersicht

Erfahren Sie mehr über Tool-Use mit Claude

Text-Editor-Tool

Anzeigen und Bearbeiten von Textdateien mit Claude

Was this page helpful?

Übersicht

Anwendungsfälle

Schnellstart

Funktionsweise

Parameter

Beispielverwendung

Beispiel: Mehrstufige Automatisierung

Implementieren Sie das Bash-Tool

Behandeln Sie Fehler

Befehlsausführungs-Timeout

Befehl nicht gefunden

Berechtigung verweigert

Befolgen Sie Best Practices für die Implementierung

Verwenden Sie Befehlszeitüberschreitungen

Behalten Sie den Sitzungszustand bei

Behandeln Sie große Ausgaben

Protokollieren Sie alle Befehle

Bereinigen Sie Ausgaben

Sicherheit

Wichtige Empfehlungen

Preisgestaltung

Häufige Muster

Entwicklungs-Workflows

Git-basierte Checkpointing

Dateioperationen

Systemaufgaben

Einschränkungen

Kombinieren mit anderen Tools

Nächste Schritte

Übersicht

Anwendungsfälle

Schnellstart

Funktionsweise

Parameter

Beispielverwendung

Beispiel: Mehrstufige Automatisierung

Implementieren Sie das Bash-Tool

Behandeln Sie Fehler

Befehlsausführungs-Timeout

Befehl nicht gefunden

Berechtigung verweigert

Befolgen Sie Best Practices für die Implementierung

Verwenden Sie Befehlszeitüberschreitungen

Behalten Sie den Sitzungszustand bei

Behandeln Sie große Ausgaben

Protokollieren Sie alle Befehle

Bereinigen Sie Ausgaben

Sicherheit

Wichtige Empfehlungen

Preisgestaltung

Häufige Muster

Entwicklungs-Workflows

Git-basierte Checkpointing

Dateioperationen

Systemaufgaben

Einschränkungen

Kombinieren mit anderen Tools

Nächste Schritte