Инструмент Bash

Инструмент bash позволяет Claude выполнять команды оболочки в постоянной сессии bash, обеспечивая системные операции, выполнение скриптов и автоматизацию командной строки.

Инструмент bash позволяет Claude выполнять команды оболочки в постоянной сессии bash, обеспечивая системные операции, выполнение скриптов и автоматизацию командной строки.

Обзор

Инструмент bash предоставляет Claude:

• Постоянную сессию bash, которая сохраняет состояние
• Возможность выполнять любые команды оболочки
• Доступ к переменным окружения и рабочему каталогу
• Возможности объединения команд в цепочки и создания скриптов

Версии инструмента

Модель	Версия инструмента
Модели Claude 4 и Sonnet 3.7	bash_20250124
Claude Sonnet 3.5 (устарел)	bash_20241022

Claude Sonnet 3.5 (устарел) требует бета-заголовок computer-use-2024-10-22 при использовании инструмента bash.

Инструмент bash общедоступен в моделях Claude 4 и Sonnet 3.7.

Случаи использования

• Рабочие процессы разработки: Выполнение команд сборки, тестов и инструментов разработки
• Автоматизация системы: Выполнение скриптов, управление файлами, автоматизация задач
• Обработка данных: Обработка файлов, выполнение скриптов анализа, управление наборами данных
• Настройка окружения: Установка пакетов, настройка окружений

Быстрый старт

Python

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "bash_20250124",
            "name": "bash"
        }
    ],
    messages=[
        {"role": "user", "content": "Перечисли все файлы Python в текущем каталоге."}
    ]
)

Как это работает

Инструмент bash поддерживает постоянную сессию:

1. Claude определяет, какую команду выполнить
2. Вы выполняете команду в оболочке bash
3. Возвращаете вывод (stdout и stderr) Claude
4. Состояние сессии сохраняется между командами (переменные окружения, рабочий каталог)

Параметры

Параметр	Обязательный	Описание
command	Да*	Команда bash для выполнения
restart	Нет	Установите в true для перезапуска сессии bash

*Обязательный, если не используется restart

Пример использования

// Выполнить команду
{
  "command": "ls -la *.py"
}

// Перезапустить сессию
{
  "restart": true
}

Пример: Многошаговая автоматизация

Claude может объединять команды в цепочки для выполнения сложных задач:

# Запрос пользователя
"Установи библиотеку requests и создай простой Python-скрипт, который получает шутку из API, затем запусти его."

# Использование инструмента Claude:
# 1. Установить пакет
{"command": "pip install requests"}

# 2. Создать скрипт
{"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. Запустить скрипт
{"command": "python fetch_joke.py"}

Сессия сохраняет состояние между командами, поэтому файлы, созданные на шаге 2, доступны на шаге 3.

---

Реализация инструмента bash

Инструмент bash реализован как инструмент без схемы. При использовании этого инструмента вам не нужно предоставлять входную схему, как с другими инструментами; схема встроена в модель Claude и не может быть изменена.

1. Настройка окружения bash

   Создайте постоянную сессию bash, с которой может взаимодействовать Claude:

   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. Обработка выполнения команд

   Создайте функцию для выполнения команд и захвата вывода:

   def execute_command(self, command):
       # Отправить команду в bash
       self.process.stdin.write(command + '\n')
       self.process.stdin.flush()
       
       # Захватить вывод с таймаутом
       output = self._read_output(timeout=10)
       return output
   

3. Обработка вызовов инструментов Claude

   Извлеките и выполните команды из ответов 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 перезапущена"
           else:
               command = content.input.get("command")
               result = bash_session.execute_command(command)
           
           # Вернуть результат Claude
           tool_result = {
               "type": "tool_result",
               "tool_use_id": content.id,
               "content": result
           }
   

4. Реализация мер безопасности

   Добавьте валидацию и ограничения:

   def validate_command(command):
       # Блокировать опасные команды
       dangerous_patterns = ['rm -rf /', 'format', ':(){:|:&};:']
       for pattern in dangerous_patterns:
           if pattern in command:
               return False, f"Команда содержит опасный паттерн: {pattern}"
       
       # Добавить больше валидации по необходимости
       return True, None
   

Обработка ошибок

При реализации инструмента bash обрабатывайте различные сценарии ошибок:

Таймаут выполнения команды

Если команда выполняется слишком долго:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Ошибка: Команда превысила время ожидания через 30 секунд",
      "is_error": true
    }
  ]
}

Команда не найдена

Если команда не существует:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: nonexistentcommand: команда не найдена",
      "is_error": true
    }
  ]
}

Отказано в доступе

Если есть проблемы с разрешениями:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: /root/sensitive-file: Отказано в доступе",
      "is_error": true
    }
  ]
}

Следуйте лучшим практикам реализации

Используйте таймауты команд

Реализуйте таймауты для предотвращения зависания команд:

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"Команда превысила время ожидания через {timeout} секунд"

Поддерживайте состояние сессии

Сохраняйте сессию bash постоянной для поддержания переменных окружения и рабочего каталога:

# Команды, выполняемые в одной сессии, сохраняют состояние
commands = [
    "cd /tmp",
    "echo 'Привет' > test.txt",
    "cat test.txt"  # Это работает, потому что мы все еще в /tmp
]

Обрабатывайте большие выводы

Обрезайте очень большие выводы для предотвращения проблем с лимитом токенов:

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... Вывод обрезан ({len(lines)} всего строк) ..."
    return output

Логируйте все команды

Ведите аудиторский след выполненных команд:

import logging

def log_command(command, output, user_id):
    logging.info(f"Пользователь {user_id} выполнил: {command}")
    logging.info(f"Вывод: {output[:200]}...")  # Логировать первые 200 символов

Очищайте выводы

Удаляйте конфиденциальную информацию из выводов команд:

def sanitize_output(output):
    # Удалить потенциальные секреты или учетные данные
    import re
    # Пример: Удалить учетные данные 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

Безопасность

Инструмент bash предоставляет прямой доступ к системе. Реализуйте эти важные меры безопасности:

• Запуск в изолированных окружениях (Docker/VM)
• Реализация фильтрации команд и списков разрешенных команд
• Установка ограничений ресурсов (CPU, память, диск)
• Логирование всех выполненных команд

Ключевые рекомендации

• Используйте ulimit для установки ограничений ресурсов
• Фильтруйте опасные команды (sudo, rm -rf, и т.д.)
• Запускайте с минимальными разрешениями пользователя
• Мониторьте и логируйте все выполнение команд

Ценообразование

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

См. ценообразование использования инструментов для полных деталей ценообразования.

Общие паттерны

Рабочие процессы разработки

• Запуск тестов: pytest && coverage report
• Сборка проектов: npm install && npm run build
• Операции Git: git status && git add . && git commit -m "сообщение"

Операции с файлами

• Обработка данных: wc -l *.csv && ls -lh *.csv
• Поиск в файлах: find . -name "*.py" | xargs grep "паттерн"
• Создание резервных копий: tar -czf backup.tar.gz ./data

Системные задачи

• Проверка ресурсов: df -h && free -m
• Управление процессами: ps aux | grep python
• Настройка окружения: export PATH=$PATH:/new/path && echo $PATH

Ограничения

• Нет интерактивных команд: Не может обрабатывать vim, less или запросы паролей
• Нет GUI-приложений: Только командная строка
• Область сессии: Сохраняется в рамках разговора, теряется между вызовами API
• Ограничения вывода: Большие выводы могут быть обрезаны
• Нет потоковой передачи: Результаты возвращаются после завершения

Комбинирование с другими инструментами

Инструмент bash наиболее мощен при комбинировании с текстовым редактором и другими инструментами.

Следующие шаги

Обзор использования инструментов

Узнайте об использовании инструментов с Claude

Инструмент текстового редактора

Просматривайте и редактируйте текстовые файлы с Claude