Strumento bash

Strumento Bash

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.

Lo strumento bash consente a Claude di eseguire comandi shell in una sessione bash persistente, permettendo operazioni di sistema, esecuzione di script e automazione da riga di comando. L'accesso alla shell è una capacità fondamentale degli agenti. Su Terminal-Bench 2.0, un benchmark che valuta compiti terminali del mondo reale utilizzando la validazione solo shell, Claude mostra forti guadagni di prestazioni con accesso a una sessione bash persistente.

Panoramica

Lo strumento bash fornisce a Claude:

Sessione bash persistente che mantiene lo stato
Capacità di eseguire qualsiasi comando shell
Accesso alle variabili di ambiente e alla directory di lavoro
Capacità di concatenamento di comandi e scripting

Per il supporto del modello, vedi il Riferimento degli strumenti.

Casi d'uso

Flussi di lavoro di sviluppo: Eseguire comandi di build, test e strumenti di sviluppo
Automazione del sistema: Eseguire script, gestire file, automatizzare attività
Elaborazione dei dati: Elaborare file, eseguire script di analisi, gestire dataset
Configurazione dell'ambiente: Installare pacchetti, configurare ambienti

Avvio rapido

Come funziona

Lo strumento bash mantiene una sessione persistente:

Claude determina quale comando eseguire
Esegui il comando in una shell bash
Restituisci l'output (stdout e stderr) a Claude
Lo stato della sessione persiste tra i comandi (variabili di ambiente, directory di lavoro)

Parametri

Parametro	Obbligatorio	Descrizione
`command`	Sì*	Il comando bash da eseguire
`restart`	No	Impostare su `true` per riavviare la sessione bash

*Obbligatorio a meno che non si utilizzi restart

Esempio: Automazione multi-step

Claude può concatenare comandi per completare compiti complessi:

Richiesta dell'utente:
"Installa la libreria requests e crea un semplice script Python che
recupera una barzelletta da un'API, quindi eseguilo."

Lo strumento di Claude utilizza:
1. Installa il pacchetto
   {"command": "pip install requests"}

2. Crea lo 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. Esegui lo script
   {"command": "python fetch_joke.py"}

La sessione mantiene lo stato tra i comandi, quindi i file creati nel passaggio 2 sono disponibili nel passaggio 3.

Implementare lo strumento bash

Lo strumento bash è implementato come uno strumento senza schema. Quando utilizzi questo strumento, non è necessario fornire uno schema di input come con altri strumenti; lo schema è integrato nel modello di Claude e non può essere modificato.

Gestire gli errori

Quando implementi lo strumento bash, gestisci vari scenari di errore:

Seguire le migliori pratiche di implementazione

Sicurezza

Lo strumento bash fornisce accesso diretto al sistema. Implementa queste misure di sicurezza essenziali:

Esecuzione in ambienti isolati (Docker/VM)
Implementazione del filtraggio dei comandi e delle liste di autorizzazione
Impostazione dei limiti di risorse (CPU, memoria, disco)
Registrazione di tutti i comandi eseguiti

Raccomandazioni chiave

Usa ulimit per impostare vincoli di risorse
Filtra i comandi pericolosi (sudo, rm -rf, ecc.)
Esegui con permessi utente minimi
Monitora e registra tutta l'esecuzione dei comandi

Prezzi

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

Vedi prezzi dell'uso degli strumenti per i dettagli completi sui prezzi.

Modelli comuni

Flussi di lavoro di sviluppo

Esecuzione di test: pytest && coverage report
Costruzione di progetti: npm install && npm run build
Operazioni Git: git status && git add . && git commit -m "message"

Checkpoint basato su Git

Git serve come meccanismo di recupero strutturato nei flussi di lavoro degli agenti di lunga durata, non solo come modo per salvare le modifiche:

Acquisire una baseline: Prima che inizi qualsiasi lavoro dell'agente, esegui il commit dello stato attuale. Questo è il punto di partenza noto e funzionante.
Commit per funzionalità: Ogni funzionalità completata ottiene il proprio commit. Questi servono come punti di rollback se qualcosa va storto in seguito.
Ricostruire lo stato all'inizio della sessione: Leggi git log insieme a un file di progresso per capire cosa è già stato fatto e cosa viene dopo.
Ripristina in caso di errore: Se il lavoro va male, git checkout ripristina l'ultimo commit buono invece di provare a eseguire il debug di uno stato rotto.

Operazioni su file

Elaborazione dei dati: wc -l *.csv && ls -lh *.csv
Ricerca nei file: find . -name "*.py" | xargs grep "pattern"
Creazione di backup: tar -czf backup.tar.gz ./data

Compiti di sistema

Verifica delle risorse: df -h && free -m
Gestione dei processi: ps aux | grep python
Configurazione dell'ambiente: export PATH=$PATH:/new/path && echo $PATH

Limitazioni

Nessun comando interattivo: Non può gestire vim, less o prompt di password
Nessuna applicazione GUI: Solo riga di comando
Ambito della sessione: Lo stato della sessione bash è lato client. L'API è senza stato. La tua applicazione è responsabile del mantenimento della sessione shell tra i turni.
Limiti di output: Gli output di grandi dimensioni possono essere troncati
Nessuno streaming: I risultati vengono restituiti dopo il completamento

Combinazione con altri strumenti

Lo strumento bash è più potente quando combinato con l'editor di testo e altri strumenti.

Se stai anche utilizzando lo strumento di esecuzione del codice, Claude ha accesso a due ambienti di esecuzione separati: la tua sessione bash locale e il contenitore sandbox di Anthropic. Lo stato non è condiviso tra loro. Vedi Utilizzo dell'esecuzione del codice con altri strumenti di esecuzione per indicazioni su come indicare a Claude di distinguere tra gli ambienti.

Passaggi successivi

Panoramica dell'uso degli strumenti

Scopri l'uso degli strumenti con Claude

Strumento editor di testo

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)

Configurare un ambiente bash

Crea una sessione bash persistente con cui Claude può interagire:

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

Gestire l'esecuzione dei comandi

Crea una funzione per eseguire comandi e acquisire l'output:

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

Elaborare le chiamate degli strumenti di Claude

Estrai ed esegui i comandi dalle risposte di Claude:

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,
        }

Implementare misure di sicurezza

Aggiungi validazione e restrizioni. Usa una lista di autorizzazione piuttosto che una lista di blocco, poiché le liste di blocco sono facili da aggirare. Rifiuta gli operatori shell in modo che i comandi concatenati non possano superare la lista di autorizzazione:

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

Questo controllo è una prima linea di difesa. Per un isolamento più forte, esegui i comandi validati con shell=False e passa shlex.split(command) come elenco di argomenti, in modo che la shell non interpreti mai la stringa.

Panoramica

Casi d'uso

Avvio rapido

Come funziona

Parametri

Esempio di utilizzo

Esempio: Automazione multi-step

Implementare lo strumento bash

Gestire gli errori

Timeout dell'esecuzione del comando

Comando non trovato

Seguire le migliori pratiche di implementazione

Usa timeout dei comandi

Sicurezza

Raccomandazioni chiave

Prezzi

Modelli comuni

Flussi di lavoro di sviluppo

Checkpoint basato su Git

Operazioni su file

Compiti di sistema

Limitazioni

Combinazione con altri strumenti

Passaggi successivi

Permesso negato

Mantieni lo stato della sessione

Gestire output di grandi dimensioni

Registra tutti i comandi

Sanitizza gli output