AIREITEREl flujo de trabajo de OpenRouter Shell resulta útil cuando un modelo necesita leer un archivo, ejecutar código, analizar un error y devolver un artefacto. La limitación importante es que openrouter:shell, los contenedores y Files API siguen en beta, así que conviene empezar con tareas acotadas y no con procesos críticos de producción.
La respuesta corta: cuándo merece la pena usar OpenRouter Shell
openrouter:shell proporciona a los modelos capaces de usar herramientas un entorno Linux alojado. El modelo puede ejecutar comandos, recibir stdout, stderr y el código de salida, y corregir el trabajo a partir de esos resultados. Files API se encarga de mover las entradas y las salidas entre las distintas partes del flujo.
Es una buena opción si necesitas:
- Un agente independiente del modelo que ejecute código fuera del servidor de tu aplicación.
- Un proceso repetible para trabajar con archivos, como analizar CSV, extraer datos de PDF o generar informes.
- Ejecutar herramientas en el servidor sin tener que construir primero tu propio sandbox.
No lo trates como un sustituto directo de un shell local. La red está desactivada por defecto, los contenedores no son persistentes automáticamente y la API puede cambiar durante la beta.
La arquitectura que importa en la práctica
| Componente | Qué hace | El detalle que condiciona el diseño |
|---|---|---|
openrouter:shell | Permite que un modelo compatible con herramientas ejecute comandos | Está disponible mediante Responses API y Anthropic Messages API (anuncio) |
| Contenedor | Ejecuta comandos en un entorno Linux aislado | Los contenedores nuevos parten de cero, salvo que reutilices una sesión o referencia de contenedor |
| Files API | Almacena las entradas y las salidas promocionadas | Los archivos subidos directamente se pueden adjuntar, pero la documentación indica que no se pueden descargar (referencia de subida) |
openrouter:bash es la alternativa compatible con Anthropic. Su ruta de ejecución predeterminada pide a la aplicación que ejecute los comandos localmente; establece engine: "openrouter" cuando necesites ejecución remota, tal como se explica en el anuncio de Shell.
El recorrido de un archivo por el sistema
1. Sube el archivo y adjúntalo como entrada
Sube el archivo mediante POST /api/v1/files y datos de formulario multipart. La referencia de subida establece un tamaño máximo de 100 MB por archivo y un parámetro de consulta opcional llamado workspace_id.
curl -X POST https://openrouter.ai/api/v1/files \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-F "file=@data/sales.csv"La respuesta incluye metadatos como el ID del archivo, el nombre, el tipo MIME, el tamaño en bytes, la fecha de creación y un indicador downloadable. Añade el ID recibido al array file_ids del entorno de Shell.
Los archivos adjuntos se copian en el contenedor como copias modificables. Cada contenedor puede recibir hasta 20 archivos adjuntos, según el anuncio de Shell. Editar la copia no modifica el archivo original del workspace.
Un desarrollador agradeció expresamente la compatibilidad con Files API después de describir los problemas que había tenido antes con PDF y OCR. Es una señal pequeña, pero concreta, de que la gestión de archivos era un problema real de integración (publicación).
2. Ejecuta, inspecciona y repite
El modelo envía un lote de comandos al contenedor. Cada invocación devuelve la salida y el estado de finalización, de modo que el modelo puede reparar un script fallido en lugar de limitarse a adivinar a partir de la instrucción original (anuncio de Shell).
La política de red predeterminada bloquea todo el tráfico. Si el trabajo necesita descargar paquetes o realizar peticiones externas, configura una lista de permitidos al crear el contenedor. OpenRouter documenta los puertos 80 y 443 para los hosts autorizados; la política no se puede modificar después del arranque. Las peticiones a dominios que no estén en la lista pueden fallar con HTTP 520 (anuncio de Shell).
En los resultados de Shell solo se capturan los archivos que estén bajo /workspace/home. Si esperas que la API informe de un artefacto, guárdalo ahí. Los archivos creados o modificados por Shell reciben identificadores cfile_ (anuncio de Shell).
3. Descarga o promociona la salida
Puedes recuperar un archivo generado por Shell mediante el endpoint de contenido de archivos del contenedor:
GET /api/v1/containers/{container_id}/files/{file_id}/contentEl identificador cfile_ pertenece al contenedor. Si el artefacto debe sobrevivir al ciclo de vida del contenedor, promociónalo al almacenamiento del workspace. La promoción crea un nuevo identificador or_file_ que podrás adjuntar en ejecuciones posteriores (anuncio de Shell).
| Tipo de archivo | ID habitual | ¿Puede descargarlo Files API? | Uso más adecuado |
|---|---|---|---|
| Subida directa | or_file_... | No, según la referencia de descarga | Entrada para una ejecución posterior |
| Artefacto del contenedor | cfile_... | A través del endpoint del contenedor | Salida temporal |
| Artefacto promocionado | or_file_... | Sí | Salida reutilizable o de mayor duración |
Los archivos de los contenedores se conservan durante 30 días. Promociona todo lo que necesites guardar durante más tiempo (anuncio de Shell). El endpoint general de descarga de archivos devuelve bytes sin procesar y documenta HTTP 400 para los archivos subidos por el usuario. Por tanto, una subida directa debe tratarse como una entrada, no como un objeto de almacenamiento de propósito general.
Costes y límites que condicionan el diseño
El anuncio de Shell de OpenRouter indica que el tiempo activo del sandbox cuesta $0.0001 por segundo. Un contenedor en frío tiene un mínimo de 30 segundos, por lo que el cargo mínimo del sandbox es de $0.003, calculado a partir de esa tarifa. El uso de tokens se cobra aparte.
| Restricción | Valor documentado | Implicación para el diseño |
|---|---|---|
| Tiempo activo del sandbox | $0.0001/segundo | Los comandos largos incrementan el coste continuamente |
| Mínimo de un contenedor en frío | 30 segundos | Las tareas pequeñas pueden activar el mínimo |
| Suspensión del contenedor | 5 minutos de inactividad | Tras la suspensión, reutilizarlo puede volver a generar el mínimo de arranque en frío |
| Archivos por contenedor | 20 | Agrupa las entradas o organízalas de forma deliberada |
| Tamaño de cada archivo subido | 100 MB | Divide o preprocesa los archivos más grandes |
| Almacenamiento del workspace | 10 GiB | Elimina o archiva los artefactos antiguos |
| Retención de contenedores no promocionados | 30 días | Promociona las salidas importantes |
Reutiliza un contenedor activo para los pasos relacionados, evita los bucles innecesarios entre el modelo y las herramientas, y registra por separado el coste de los tokens y el del sandbox. El anuncio indica que la vista Logs muestra la actividad del modelo y la ejecución del sandbox en filas independientes de la línea de tiempo.
Estructura básica de la petición
El esquema exacto del entorno puede cambiar durante la beta, pero el flujo documentado es este: primero sube el archivo y después pasa el ID devuelto a una petición compatible con Shell. Mantén pequeño el adaptador de peticiones para poder actualizarlo si cambia el esquema de la beta.
{
"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"
}Envía esta estructura al endpoint de Responses que se documenta en el anuncio. Antes de usarla en producción, comprueba el esquema actual de la petición y los campos de respuesta en la documentación activa de las herramientas del servidor.
Para una primera integración, sigue esta secuencia:
- Sube un archivo de entrada pequeño y guarda el ID recibido.
- Crea una petición para un modelo compatible con herramientas e incluye
openrouter:shellentools. - Adjunta el archivo explícitamente mediante
file_ids. - Pide al modelo que escriba las salidas bajo
/workspace/home. - Comprueba el código de salida y la lista de archivos antes de dar el trabajo por terminado.
- Descarga el artefacto del contenedor o promociónalo si necesitas reutilizarlo.
- Registra el uso de tokens y la duración del sandbox en campos de coste independientes.
En un flujo con varias peticiones, pasa un session_id o una referencia explícita al contenedor. De lo contrario, una petición posterior puede recibir un contenedor nuevo sin nada del estado anterior.
Qué suele fallar primero y cómo prepararte
| Problema | Respuesta de diseño |
|---|---|
| El modelo no puede usar la herramienta | Selecciona un modelo compatible con llamadas a herramientas; declarar una herramienta del servidor no añade esa capacidad. |
| El comando no puede acceder a Internet | Empieza con la red bloqueada y configura la lista de permitidos antes de arrancar. |
| La salida desaparece | Escribe bajo /workspace/home y utiliza el ID cfile_ devuelto. Promociona los artefactos que deban conservarse. |
| No se puede descargar una subida | Trata las subidas directas como entradas; recupera las salidas de Shell mediante el endpoint del contenedor o el flujo de promoción. |
| La segunda petición pierde el proyecto | Reutiliza la sesión o la referencia al contenedor. Los contenedores nuevos son el comportamiento predeterminado. |
| La factura es más alta de lo esperado | Separa los cargos de tokens del tiempo de sandbox e incluye el mínimo de 30 segundos de los contenedores en frío. |
| La interfaz cambia | Mantén la integración beta detrás de un adaptador y prueba los identificadores, la posibilidad de descarga y la reutilización. |
Preguntas frecuentes sobre OpenRouter Shell y Files API
¿OpenRouter Shell ejecuta comandos en mi ordenador?
No. openrouter:shell está diseñado para ejecutar comandos en un sandbox alojado por OpenRouter. El openrouter:bash compatible con Anthropic tiene otros valores predeterminados; utiliza engine: "openrouter" para la ejecución remota (anuncio de Shell).
¿Cómo mantengo los archivos entre peticiones?
Reutiliza una sesión o una referencia al contenedor. Sin esa ruta explícita de reutilización, una petición posterior puede iniciar un contenedor nuevo.
¿Cuál es la diferencia entre or_file_ y cfile_?
or_file_ identifica un objeto de Files API almacenado en el workspace. cfile_ identifica un archivo creado o modificado dentro de un contenedor. La promoción convierte un artefacto del contenedor en un nuevo ID de archivo del workspace.
¿Files API cobra una tarifa de uso independiente?
El anuncio de Shell indica que el uso de Files API no tiene un cargo independiente, aunque el almacenamiento del workspace está limitado a 10 GiB. El tiempo del sandbox y el uso de tokens del modelo siguen facturándose según las tarifas aplicables.
¿Shell Tool está listo para producción?
Está documentado como beta y el anuncio advierte de que la API puede cambiar. Antes de colocarlo detrás de un flujo de producción desatendido, utiliza límites explícitos, comandos acotados, restricciones a nivel de aplicación y una ruta alternativa.
Elige esta opción si tu flujo genera un artefacto real
OpenRouter Shell y Files API encajan en una cadena de trabajo por etapas que produzca un CSV limpio, un informe, una imagen transformada o un artefacto compilado. Utiliza IDs de archivo explícitos, una política de red definida de antemano, reutilización de contenedores y promoción para las salidas que deban conservarse.
Si la tarea solo requiere una respuesta de texto, el coste adicional del sandbox y la gestión de su ciclo de vida no compensan. Y si necesita credenciales locales, acceso de red sin restricciones o garantías estrictas de producción, mantén la ejecución en una infraestructura bajo tu control hasta que la beta esté suficientemente madura para asumir ese riesgo.
Fuentes: anuncio de OpenRouter Shell y Files API, referencia de subida de Files API, referencia de descarga del contenido de archivos.