Bash инструмент

Инструмент 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.

Инструмент bash позволяет Claude выполнять команды оболочки в постоянной сессии bash, обеспечивая системные операции, выполнение скриптов и автоматизацию командной строки. Доступ к оболочке является фундаментальной возможностью агента. На Terminal-Bench 2.0, эталоне, который оценивает реальные задачи терминала с использованием только валидации оболочки, Claude показывает значительный прирост производительности с доступом к постоянной сессии bash.

Обзор

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

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

Для поддержки моделей см. Справочник инструментов.

Варианты использования

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

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

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

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

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

Параметры

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

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

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

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 и не может быть изменена.

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

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

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

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

Инструмент 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 "message"

Контрольные точки на основе Git

Git служит структурированным механизмом восстановления в долгосрочных рабочих процессах агента, а не просто способом сохранения изменений:

Захват базовой линии: Перед началом работы агента зафиксируйте текущее состояние. Это известная хорошая начальная точка.
Коммит за функцию: Каждая завершенная функция получает свой собственный коммит. Они служат точками отката, если что-то пойдет не так позже.
Восстановление состояния при запуске сессии: Прочитайте git log вместе с файлом прогресса, чтобы понять, что уже было сделано и что будет дальше.
Откат при сбое: Если работа пойдет не так, git checkout вернет к последнему хорошему коммиту вместо попытки отладки сломанного состояния.

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

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

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

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

Ограничения

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

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

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

Если вы также используете инструмент выполнения кода, Claude имеет доступ к двум отдельным окружениям выполнения: вашей локальной сессии bash и изолированному контейнеру Anthropic. Состояние не общее между ними. См. Использование выполнения кода с другими инструментами выполнения для рекомендаций по подсказкам Claude для различения окружений.

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

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

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

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

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)

Настройка окружения 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()

Обработка выполнения команд

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

def execute_command(self, command):
    # Отправка команды в bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Захват вывода с тайм-аутом
    output = self._read_output(timeout=10)
    return output

Обработка вызовов инструментов 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 session restarted"
        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,
        }

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

Добавьте валидацию и ограничения. Используйте список разрешений вместо списка запретов, так как списки запретов легко обойти. Отклоняйте операторы оболочки, чтобы объединенные команды не могли пройти мимо списка разрешений:

import shlex

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


def validate_command(command):
    # Разрешить только команды из явного списка разрешений
    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"

    # Отклонить операторы оболочки, которые объединяют дополнительные команды
    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

Эта проверка является первой линией защиты. Для более сильной изоляции запускайте проверенные команды с shell=False и передавайте shlex.split(command) как список аргументов, чтобы оболочка никогда не интерпретировала строку.

Обзор

Варианты использования

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

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

Параметры

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

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

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

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

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

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

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

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

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

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

Цены

Распространенные паттерны

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

Контрольные точки на основе Git

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

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

Ограничения

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

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

Доступ запрещен

Сохранение состояния сессии

Обработка больших выводов

Логирование всех команд

Санитизация выводов