OpenRouter Shell Tool und Files API im Praxistest (Beta)

OpenRouters Shell-Workflow ist praktisch, wenn ein Modell Dateien einlesen, Code ausführen, Fehler untersuchen und am Ende ein Artefakt zurückgeben soll. Der entscheidende Haken: openrouter:shell, Container und Files API befinden sich noch in der Beta. Für den Einstieg solltest du deshalb mit einem klar begrenzten Job beginnen – nicht mit einem produktionskritischen Ausführungspfad.

Die Kurzfassung: Wann sich OpenRouter Shell lohnt

openrouter:shell stellt einem Tool-fähigen Modell eine gehostete Linux-Umgebung bereit. Das Modell kann Befehle ausführen, stdout, stderr und den Exit-Code auswerten und seine Arbeit anschließend korrigieren. Die Files API übernimmt dabei die Übergabe von Eingaben und Ausgaben.

Das Tool eignet sich besonders, wenn du Folgendes brauchst:

• Ein modellunabhängiger Agent, der Code außerhalb deines Application-Servers ausführt.
• Einen wiederholbaren Datei-Workflow, etwa für CSV-Analysen, PDF-Extraktion oder die Report-Erstellung.
• Serverseitige Tool-Ausführung, ohne zunächst eine eigene Sandbox bauen zu müssen.

Als direkten Ersatz für eine lokale Shell solltest du das Ganze trotzdem nicht betrachten. Netzwerkzugriff ist standardmäßig deaktiviert, Container bleiben nicht automatisch erhalten und die API kann sich während der Beta noch ändern.

Die Architektur, auf die es in der Praxis ankommt

openrouter:bash ist die Anthropic-kompatible Alternative. Standardmäßig soll die Anwendung die Befehle lokal ausführen. Für die Remote-Ausführung setzt du engine: "openrouter", wie in der Shell-Ankündigung beschrieben.

Der Weg einer Datei durch das System

1. Eingabe hochladen und anhängen

Lade die Datei per POST /api/v1/files als Multipart-Formulardaten hoch. Die Upload-Referenz nennt eine maximale Einzeldateigröße von 100 MB sowie den optionalen Query-Parameter workspace_id.

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

Die Antwort enthält Metadaten wie Datei-ID, Dateiname, MIME-Typ, Byte-Größe, Erstellungszeitpunkt und ein downloadable-Flag. Die zurückgegebene Datei-ID trägst du im Array file_ids der Shell-Umgebung ein.

Angehängte Dateien werden als beschreibbare Kopien in den Container übernommen. Laut Shell-Ankündigung kann ein Container bis zu 20 angehängte Dateien erhalten. Änderungen an der Kopie wirken sich nicht auf die ursprüngliche Workspace-Datei aus.

Ein Entwickler begrüßte die Unterstützung der Files API ausdrücklich, nachdem er zuvor von Problemen mit PDF und OCR berichtet hatte. Das ist ein kleines, aber konkretes Indiz dafür, dass der Umgang mit Dateien in der Integration tatsächlich eine relevante Hürde war (Beitrag).

2. Ausführen, prüfen, nachbessern

Das Modell schickt einen Befehlsblock an den Container. Jede Ausführung liefert die Ausgabe und den Exit-Status zurück. So kann das Modell ein fehlgeschlagenes Skript reparieren, statt nur anhand der ursprünglichen Anfrage zu raten (Shell-Ankündigung).

Die Netzwerkregeln stehen standardmäßig auf Deny-All. Braucht der Job Paket-Downloads oder externe Requests, legst du beim Erstellen des Containers eine Allowlist an. OpenRouter dokumentiert für freigegebene Hosts die Ports 80 und 443; nach dem Start lässt sich diese Richtlinie nicht mehr ändern. Anfragen an Domains außerhalb der Allowlist können mit HTTP 520 fehlschlagen (Shell-Ankündigung).

In den Shell-Ergebnissen werden nur Dateien unter /workspace/home erfasst. Wenn die API dein Artefakt melden soll, musst du es dort ablegen. Dateien, die von der Shell erstellt oder verändert wurden, erhalten eine cfile_-ID (Shell-Ankündigung).

3. Ausgabe herunterladen oder dauerhaft übernehmen

Eine von der Shell erzeugte Datei rufst du über den Dateiinhalt-Endpunkt des Containers ab:

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

Die cfile_-ID gehört zum jeweiligen Container. Soll das Artefakt über den Lebenszyklus des Containers hinaus erhalten bleiben, übernimmst du es in den Workspace-Speicher. Dabei entsteht eine neue or_file_-ID, die du bei einem späteren Lauf wieder anhängen kannst (Shell-Ankündigung).

Container-Dateien bleiben 30 Tage erhalten. Alles, was länger benötigt wird, solltest du in den Workspace übernehmen (Shell-Ankündigung). Der allgemeine Download-Endpunkt für Dateien liefert rohe Bytes und dokumentiert HTTP 400 für von Nutzern hochgeladene Dateien. Einen direkten Upload solltest du daher als Eingabe behandeln – nicht als frei verfügbares Objekt in einem allgemeinen Object Store.

Kosten und Limits mit Einfluss auf das Design

In der Shell-Ankündigung nennt OpenRouter für aktive Sandbox-Zeit Kosten von $0.0001 pro Sekunde. Für einen kalten Container gilt ein Mindestwert von 30 Sekunden; daraus ergibt sich rechnerisch eine minimale Sandbox-Gebühr von $0.003. Token-Kosten kommen separat hinzu.

Nutze für zusammengehörige Schritte einen warmen Container, vermeide unnötige Modell-Tool-Schleifen und protokolliere Token-Kosten getrennt von den Sandbox-Kosten. Laut Ankündigung zeigt die Logs-Ansicht Modellaktivität und Sandbox-Ausführung als separate Zeilen in der Zeitleiste.

Grundstruktur einer Anfrage

Das genaue Schema der Umgebung kann sich während der Beta noch ändern. Strukturell sieht der dokumentierte Ablauf aber so aus: Erst hochladen, dann die zurückgegebene Datei-ID an eine Shell-fähige Anfrage übergeben. Halte den Adapter für diese Anfrage schlank, damit du ihn bei Änderungen am Beta-Schema schnell anpassen kannst.

{
  "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"
}

Diese Struktur schickst du an den in der Ankündigung dokumentierten Responses-Endpunkt. Vor dem Einsatz in Produktion solltest du Request-Schema und Antwortfelder noch einmal gegen die aktuelle Dokumentation der Server-Tools prüfen.

Für die erste Integration empfiehlt sich diese Reihenfolge:

1. Eine kleine Eingabedatei hochladen und die zurückgegebene Datei-ID speichern.
2. Eine Anfrage für ein Tool-fähiges Modell erstellen und openrouter:shell in tools eintragen.
3. Die Datei explizit über file_ids anhängen.
4. Das Modell anweisen, Ausgaben unter /workspace/home zu speichern.
5. Exit-Code und Dateiliste prüfen, bevor du den Job als erfolgreich behandelst.
6. Das Container-Artefakt herunterladen oder übernehmen, wenn es später wiederverwendet werden soll.
7. Token-Verbrauch und Sandbox-Dauer als getrennte Kostenfelder speichern.

Für einen Workflow über mehrere Anfragen hinweg übergibst du eine session_id oder eine explizite Container-Referenz. Andernfalls kann die nächste Anfrage in einem frischen Container landen, dem der bisherige Zustand fehlt.

Was zuerst schiefgeht – und wie du es abfängst

FAQ zu OpenRouter Shell und Files API

Führt OpenRouter Shell Befehle auf meinem Computer aus?

Nein. openrouter:shell ist für die Ausführung von Befehlen in einer von OpenRouter gehosteten Sandbox gedacht. Die Anthropic-kompatible Variante openrouter:bash hat andere Standardeinstellungen; für die Remote-Ausführung setzt du engine: "openrouter" (Shell-Ankündigung).

Wie bleiben Dateien zwischen mehreren Anfragen erhalten?

Verwende dieselbe Session oder Container-Referenz erneut. Ohne diesen expliziten Wiederverwendungsweg kann die nächste Anfrage in einem frischen Container starten.

Was ist der Unterschied zwischen or_file_ und cfile_?

or_file_ bezeichnet ein Workspace-Objekt der Files API. cfile_ steht für eine Datei, die innerhalb eines Containers erstellt oder verändert wurde. Durch die Übernahme wird aus einem Container-Artefakt eine neue Workspace-Datei-ID.

Fallen für die Files API separate Nutzungskosten an?

Laut Shell-Ankündigung verursacht die Nutzung der Files API keine separate Nutzungsgebühr. Der Workspace-Speicher ist jedoch auf 10 GiB begrenzt. Sandbox-Zeit und Modell-Token werden weiterhin nach den jeweils geltenden Tarifen abgerechnet.

Ist das Shell Tool bereit für den Produktionseinsatz?

Das Tool ist als Beta dokumentiert, und in der Ankündigung wird darauf hingewiesen, dass sich die API ändern kann. Bevor du es in einen unbeaufsichtigten Produktions-Workflow einhängst, solltest du klare Limits, begrenzte Befehle, Einschränkungen auf Anwendungsebene und einen Fallback einplanen.

Die richtige Wahl, wenn am Ende ein echtes Artefakt steht

OpenRouter Shell und Files API passen zu einer schrittweisen Pipeline, die etwa eine bereinigte CSV-Datei, einen Report, ein transformiertes Bild oder ein kompiliertes Artefakt erzeugt. Arbeite mit expliziten Datei-IDs, einer vorab festgelegten Netzwerkregel, wiederverwendbaren Containern und der Übernahme für dauerhafte Ausgaben.

Geht es nur um eine Textantwort, sind die zusätzlichen Sandbox-Kosten und der Aufwand für den Lebenszyklus unnötig. Braucht der Job lokale Zugangsdaten, uneingeschränkten Netzwerkzugriff oder harte Produktionsgarantien, solltest du die Ausführung zunächst in einer Infrastruktur belassen, die du selbst kontrollierst – bis die Beta für dieses Risikoniveau ausgereift genug ist.

Quellen: OpenRouter-Ankündigung zu Shell und Files API, Upload-Referenz der Files API, Referenz zum Herunterladen von Dateiinhalten.