Руководство по OpenRouter Shell Tool и Files API (бета)

Shell-сценарий OpenRouter пригодится, когда модели нужно прочитать файл, запустить код, разобраться с ошибкой и вернуть готовый артефакт. Но есть важная оговорка: openrouter:shell, контейнеры и Files API пока находятся в стадии бета-тестирования. Поэтому начинать лучше с ограниченной по объёму задачи, а не с критичного для продакшена процесса.

Коротко: когда OpenRouter shell действительно полезен

openrouter:shell даёт модели с поддержкой вызова инструментов удалённую Linux-среду. Модель может выполнять команды, получать stdout, stderr и код завершения, а затем исправлять результат с учётом полученного вывода. Files API в этой схеме отвечает за передачу входных данных и сохранение результатов.

Инструмент стоит выбрать, если вам нужен:

• Агент, не привязанный к конкретной модели, который запускает код за пределами сервера приложения.
• Повторяемый процесс обработки файлов — например, анализ CSV, извлечение данных из PDF или генерация отчётов.
• Серверный запуск инструментов без необходимости сначала самостоятельно собирать песочницу.

Но это не полноценная замена локальному shell. По умолчанию сеть отключена, контейнеры не сохраняются автоматически, а интерфейс API может измениться в ходе бета-тестирования.

Как устроена связка на практике

openrouter:bash — совместимая с Anthropic альтернатива. В стандартном режиме приложение должно выполнять команды локально; если нужен удалённый запуск, укажите engine: "openrouter", как описано в анонсе Shell Tool.

Как файл проходит через систему

1. Загрузите файл и прикрепите его к запросу

Загрузить файл можно через POST /api/v1/files, передав multipart form data. В документации по загрузке указано максимальное индивидуальное ограничение в 100 МБ; также можно передать необязательный параметр запроса workspace_id.

curl -X POST https://openrouter.ai/api/v1/files \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -F "file=@data/sales.csv"

В ответе возвращаются метаданные: ID файла, имя, MIME-тип, размер в байтах, время создания и флаг downloadable. Полученный ID передайте в массиве file_ids окружения Shell Tool.

Прикреплённые файлы копируются в контейнер как доступные для записи копии. Согласно анонсу Shell Tool, один контейнер может получить до 20 прикреплённых файлов. Изменения в копии не затрагивают исходный файл в рабочем пространстве.

Один из разработчиков отдельно положительно отозвался о поддержке Files API, вспоминая прежние сложности с PDF и OCR. Это небольшой, но показательный сигнал: работа с файлами действительно была заметной интеграционной проблемой (пост).

2. Запустите команды, проверьте результат и повторите попытку

Модель отправляет в контейнер набор команд. Каждый запуск возвращает вывод и статус завершения, поэтому при сбое модель может исправить скрипт, а не пытаться угадать причину проблемы по одному лишь исходному запросу (анонс Shell Tool).

По умолчанию действует политика полного запрета сети. Если задаче нужны загрузка пакетов или внешние запросы, настройте список разрешённых адресов при создании контейнера. OpenRouter указывает порты 80 и 443 для разрешённых хостов; после запуска изменить политику нельзя. Запросы к доменам за пределами списка могут завершаться ошибкой HTTP 520 (анонс Shell Tool).

В результаты Shell Tool попадают только файлы из каталога /workspace/home. Если API должен увидеть артефакт, сохраняйте его именно туда. Файлы, созданные или изменённые Shell Tool, получают идентификаторы с префиксом cfile_ (анонс Shell Tool).

3. Скачайте результат или сохраните его в рабочем пространстве

Файл, созданный Shell Tool, можно получить через endpoint содержимого файла контейнера:

GET /api/v1/containers/{container_id}/files/{file_id}/content

Идентификатор cfile_ относится к конкретному контейнеру. Если артефакт должен пережить жизненный цикл контейнера, сохраните его в рабочем пространстве. В результате появится новый идентификатор or_file_, который можно прикрепить к следующему запуску (анонс Shell Tool).

Файлы контейнера хранятся 30 дней. Всё, что нужно сохранить дольше, следует перенести в рабочее пространство (анонс Shell Tool). Общий endpoint скачивания файлов возвращает необработанные байты и документирует HTTP-ошибку 400 для пользовательских загрузок. Поэтому напрямую загруженный файл стоит воспринимать как входные данные, а не как универсальный объект в файловом хранилище.

Стоимость и ограничения, которые влияют на архитектуру

В анонсе Shell Tool OpenRouter указано, что активное время работы песочницы стоит $0.0001 в секунду. Для холодного контейнера действует минимум в 30 секунд, поэтому минимальная плата за песочницу составляет $0.003 — это следует из расчёта. Токены оплачиваются отдельно.

Для связанных этапов переиспользуйте тёплый контейнер, не допускайте лишних циклов между моделью и инструментом и учитывайте стоимость токенов отдельно от стоимости песочницы. В анонсе говорится, что в разделе Logs активность модели и выполнение команд в песочнице отображаются отдельными строками временной шкалы.

Базовая структура запроса

Точная схема окружения в период бета-тестирования может измениться, но общий процесс выглядит так: сначала загрузите файл, затем передайте полученный ID в запрос с поддержкой Shell Tool. Держите адаптер запросов небольшим — это упростит обновление при изменении бета-схемы.

{
  "model": "your/tool-capable-model",
  "tools": [
    {
      "type": "openrouter:shell",
      "environment": {
        "type": "container_auto",
        "file_ids": ["or_file_your_uploaded_file_id"]
      }
    }
  ],
  "input": "Analyze the attached CSV and write a summary to /workspace/home/report.md"
}

Передайте такую структуру в Responses endpoint, описанный в анонсе. До запуска в продакшене проверьте актуальную схему запроса и поля ответа по текущей документации серверных инструментов.

Для первой интеграции используйте такой порядок:

1. Загрузите небольшой входной файл и сохраните полученный ID.
2. Создайте запрос к модели с поддержкой инструментов, добавив openrouter:shell в tools.
3. Явно прикрепите файл через file_ids.
4. Попросите модель сохранять результаты в /workspace/home.
5. Проверьте код завершения и список файлов, прежде чем считать задачу выполненной.
6. Скачайте артефакт контейнера или сохраните его в рабочем пространстве, если он понадобится повторно.
7. Записывайте расход токенов и длительность работы песочницы в отдельные поля стоимости.

В многошаговом процессе между несколькими запросами передавайте session_id или явную ссылку на контейнер. Иначе следующий запрос может получить новый контейнер без предыдущего состояния.

Что обычно ломается первым и как этого избежать

FAQ об OpenRouter shell и Files API

OpenRouter shell выполняет команды на моём компьютере?

Нет. openrouter:shell предназначен для выполнения команд в песочнице, размещённой OpenRouter. У совместимого с Anthropic openrouter:bash другие значения по умолчанию; для удалённого запуска используйте engine: "openrouter" (анонс Shell Tool).

Как сохранить файлы между запросами?

Переиспользуйте сессию или ссылку на контейнер. Без явно указанного механизма повторного использования следующий запрос может запуститься в новом контейнере.

Чем отличаются or_file_ и cfile_?

or_file_ обозначает объект Files API в рабочем пространстве. cfile_ — файл, созданный или изменённый внутри контейнера. При сохранении артефакта он превращается в новый ID файла рабочего пространства.

Взимается ли отдельная плата за использование Files API?

В анонсе Shell Tool говорится, что отдельной платы за использование Files API нет, однако объём рабочего пространства ограничен 10 ГиБ. Время работы песочницы и токены модели по-прежнему оплачиваются по соответствующим тарифам.

Готов ли Shell Tool к продакшену?

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

Выбирайте его, если процесс действительно создаёт артефакт

Связка OpenRouter Shell и Files API хорошо подходит для поэтапного процесса, на выходе которого получается очищенный CSV, отчёт, преобразованное изображение или скомпилированный артефакт. Используйте явные ID файлов, заранее заданную сетевую политику, повторное использование контейнеров и сохранение результатов, которые должны пережить их жизненный цикл.

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

Источники: анонс OpenRouter Shell и Files API, документация по загрузке через Files API, документация по скачиванию содержимого файла.