Как запустить Shell Tool в OpenAI API и безопасно выполнять команды

Shell доступен через Responses API и может работать в hosted-контейнере OpenAI либо в локальном runtime, которым управляет приложение. Для автоматически создаваемого hosted-контейнера документация показывает container_auto. В Chat Completions этот инструмент недоступен.

Подтверждённый механизм нужно отделять от архитектурных решений. API определяет формат вызова, но не создаёт за вас песочницу, права, журнал и критерии качества. Эти ограничения реализует приложение и проверяет до исполнения каждого опасного шага.

Подготовка теста

Создайте отдельный проект, минимальный API-ключ и обезличенный набор. Секрет храните в переменной окружения или менеджере секретов. Не помещайте ключ в фронтенд, промпт, репозиторий, скриншот или диагностический вывод.

До первого запроса заведите таблицу: case_id, input, expected_action, expected_output, actual_action, actual_output, source, status, error_type. Заполните expected заранее. Если ожидаемый результат появляется после просмотра ответа, проверка превращается в подгонку.

Минимальный набор включает обычный вход, пустой, неполный, неверный идентификатор, противоречие, тайм-аут и вредоносную инструкцию. Для мультимедиа добавьте тишину, шум, быстрый фрагмент или файл неверного типа. Для файловых инструментов добавьте попытку выйти за рабочий каталог.

Пошаговая настройка

1. Создайте временный каталог только для одного задания и положите туда обезличенный orders.csv. В hosted-варианте подключите shell с container_auto; в local-варианте исполняйте команды в отдельном контейнере без домашних каталогов и облачных credentials.
2. Разберите shell_call до исполнения. Отклоняйте сетевые утилиты, sudo, package manager, чтение /etc и пути за рабочим корнем. Допустите только python, ls, pwd и чтение заранее загруженных файлов.
3. Задайте тайм-аут процесса, предел вывода, памяти и числа команд. После превышения лимита завершайте процесс и возвращайте явный tool output, а не пустую строку.
4. Верните stdout, stderr и exit code модели. Ошибка команды должна оставаться ошибкой: не подменяйте ненулевой exit code текстом success.
5. После завершения проверьте список файлов и удалите контейнер. Артефакты выдавайте только по allowlist расширений и после проверки размера.

Каждый шаг должен оставлять проверяемый след: request_id, версия модели, выбранный инструмент, обезличенные аргументы, exit code или статус, размер результата и факт побочного эффекта. Полный секрет, персональные данные и необязательное внутреннее рассуждение модели в журнал не записывайте.

Копируемый шаблон

Проанализируй /workspace/orders.csv. Разрешены только python без сторонних пакетов, ls, pwd и чтение этого файла. Не используй сеть и не открывай пути вне /workspace. Создай /workspace/summary.json со статусами заказов и суммой quantity. При ошибке входа не создавай итоговый файл.

Общие правила:
- используй только переданные данные и разрешённые инструменты;
- не угадывай отсутствующие значения;
- перед действием проверь путь, тип, идентификатор и права;
- при конфликте верни status=needs_review;
- не отправляй, не удаляй и не раскрывай секрет без отдельного подтверждения;
- перечисли фактические действия и источник каждого изменяемого значения.

Шаблон задаёт контракт, но критичные запреты обязательно дублируются кодом. Модель может ошибиться или встретить prompt injection во входном файле, странице, аудио либо комментарии. Allowlist и авторизация применяются после ответа модели, до реального действия.

Реалистичный пример и ожидаемый результат

В orders.csv три строки: ORD-101,2,paid; ORD-102,1,cancelled; ORD-103,4,paid. Ожидается summary.json с paid_orders=2, paid_quantity=6 и cancelled_orders=1. В журнале нет сетевых команд, exit code равен нулю, исходный CSV не изменён.

Это критерий теста, а не выдуманный результат сравнительного исследования. При внедрении сохраните реальный output рядом с expected и отметьте каждое расхождение. Правильный текст при лишней команде, неверном файле или запрещённом запросе считается провалом.

Проверка результата по четырём уровням

Сначала транспорт: запрос завершился, ответ читается, идентификатор сохранён. HTTP 200 не доказывает корректность. При тайм-ауте сначала выясните состояние прошлого вызова; повтор внешней записи без проверки создаёт дубли.

Затем структура: обязательные поля присутствуют, типы совпадают, Base64 декодируется, JSON разбирается после полного получения, файл открывается штатной библиотекой. Пустое поле не превращается в число или факт без явного правила.

Третий уровень — смысл. Каждый факт сопоставляется с входом, таймкодом, файлом либо результатом инструмента. Числа пересчитываются обычным кодом. Имена и идентификаторы сравниваются посимвольно. Если источник не содержит значения, ответ должен сообщить о нехватке данных.

Четвёртый уровень — действие. Проверьте внешнюю систему или файловый diff: какие команды выполнены, какие файлы созданы, была ли запись. Для read-only сценария любое изменение является ошибкой, даже если итоговое объяснение выглядит убедительно.

Приёмка на конкретных данных