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.

​
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

​
Compatibilità del modello

ModelloVersione dello strumento
Modelli Claude 4 e Sonnet 3.7 (deprecato)bash_20250124
Le versioni precedenti dello strumento non sono garantite essere retrocompatibili con i modelli più recenti. Utilizza sempre la versione dello strumento che corrisponde alla versione del tuo modello.

​
Casi d’uso

  • Flussi di lavoro di sviluppo: Esegui comandi di build, test e strumenti di sviluppo
  • Automazione di sistema: Esegui script, gestisci file, automatizza attività
  • Elaborazione dati: Elabora file, esegui script di analisi, gestisci dataset
  • Configurazione dell’ambiente: Installa pacchetti, configura ambienti

​
Avvio rapido

import anthropic

client = anthropic.Anthropic()

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

​
Come funziona

Lo strumento bash mantiene una sessione persistente:
  1. Claude determina quale comando eseguire
  2. Esegui il comando in una shell bash
  3. Restituisci l’output (stdout e stderr) a Claude
  4. Lo stato della sessione persiste tra i comandi (variabili di ambiente, directory di lavoro)

​
Parametri

ParametroObbligatorioDescrizione
commandSì*Il comando bash da eseguire
restartNoImposta su true per riavviare la sessione bash
*Obbligatorio a meno che non si utilizzi restart 
// Esegui un comando
{
  "command": "ls -la *.py"
}

// Riavvia la sessione
{
  "restart": true
}

​
Esempio: Automazione multi-step

Claude può concatenare comandi per completare attività complesse: 
# Richiesta dell'utente
"Install the requests library and create a simple Python script that fetches a joke from an API, then run it."

# 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.

​
Implementa 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.
1

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

Gestisci l'esecuzione dei comandi

Crea una funzione per eseguire comandi e catturare l’output:
def execute_command(self, command):
    # Invia il comando a bash
    self.process.stdin.write(command + '\n')
    self.process.stdin.flush()
    
    # Cattura l'output con timeout
    output = self._read_output(timeout=10)
    return output
3

Elabora le chiamate di strumento 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)
        
        # Restituisci il risultato a Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }
4

Implementa misure di sicurezza

Aggiungi convalida e restrizioni:
def validate_command(command):
    # Blocca i comandi pericolosi
    dangerous_patterns = ['rm -rf /', 'format', ':(){:|:&};:']
    for pattern in dangerous_patterns:
        if pattern in command:
            return False, f"Command contains dangerous pattern: {pattern}"
    
    # Aggiungi ulteriore convalida secondo necessità
    return True, None

​
Gestisci gli errori

Quando implementi lo strumento bash, gestisci vari scenari di errore:
Se un comando impiega troppo tempo per essere eseguito:
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Command timed out after 30 seconds",
      "is_error": true
    }
  ]
}
Se un comando non esiste:
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: nonexistentcommand: command not found",
      "is_error": true
    }
  ]
}
Se ci sono problemi di permessi:
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: /root/sensitive-file: Permission denied",
      "is_error": true
    }
  ]
}

​
Segui le migliori pratiche di implementazione

Implementa timeout per prevenire comandi bloccati:
def execute_with_timeout(command, timeout=30):
    try:
        result = subprocess.run(
            command, 
            shell=True, 
            capture_output=True, 
            text=True, 
            timeout=timeout
        )
        return result.stdout + result.stderr
    except subprocess.TimeoutExpired:
        return f"Command timed out after {timeout} seconds"
Mantieni la sessione bash persistente per conservare le variabili di ambiente e la directory di lavoro:
# I comandi eseguiti nella stessa sessione mantengono lo stato
commands = [
    "cd /tmp",
    "echo 'Hello' > test.txt",
    "cat test.txt"  # Questo funziona perché siamo ancora in /tmp
]
Tronca output molto grandi per prevenire problemi di limite di token:
def truncate_output(output, max_lines=100):
    lines = output.split('\n')
    if len(lines) > max_lines:
        truncated = '\n'.join(lines[:max_lines])
        return f"{truncated}\n\n... Output truncated ({len(lines)} total lines) ..."
    return output
Mantieni un audit trail dei comandi eseguiti:
import logging

def log_command(command, output, user_id):
    logging.info(f"User {user_id} executed: {command}")
    logging.info(f"Output: {output[:200]}...")  # Registra i primi 200 caratteri
Rimuovi informazioni sensibili dagli output dei comandi:
def sanitize_output(output):
    # Rimuovi potenziali segreti o credenziali
    import re
    # Esempio: Rimuovi credenziali AWS
    output = re.sub(r'aws_access_key_id\s*=\s*\S+', 'aws_access_key_id=***', output)
    output = re.sub(r'aws_secret_access_key\s*=\s*\S+', 'aws_secret_access_key=***', output)
    return output

​
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 allowlist
  • Impostazione di limiti di risorse (CPU, memoria, disco)
  • Registrazione di tutti i comandi eseguiti

​
Raccomandazioni chiave

  • Utilizza 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’utilizzo 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"

​
Operazioni su file

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

​
Attività 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: Persiste all’interno della conversazione, perso tra le chiamate API
  • 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.

​
Passaggi successivi

Panoramica dell'utilizzo degli strumenti

Scopri l’utilizzo degli strumenti con Claude

Strumento editor di testo

Visualizza e modifica file di testo con Claude