Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Shell

Führe Shell-Befehle in gehosteten Containern oder in deiner eigenen lokalen Laufzeitumgebung aus.

Mit dem Shell-Tool können Modelle in einer vollständigen Terminalumgebung arbeiten. Die Responses API unterstützt die Ausführung von Shell-Befehlen sowohl lokal als auch in gehosteten Containern.

Das Shell-Tool unterstützt zwei Umgebungen, in denen Modelle Befehle ausführen können:

Das Shell-Tool ist über die Responses API verfügbar. Die Chat Completions API unterstützt es nicht.

Die Ausführung beliebiger Shell-Befehle kann gefährlich sein. Führe Befehle immer in einer Sandbox aus. Erlaube oder sperre nach Möglichkeit gezielt einzelne Befehle und protokolliere die Aktivitäten des Tools für spätere Prüfungen.

Schnellstart mit Hosted Shell

Hosted Shell bietet eine integrierte, unkomplizierte Möglichkeit, Aufgaben auszuführen, die eine komplexere, deterministische Verarbeitung erfordern. Das reicht von Berechnungen bis zur Verarbeitung von Multimediadaten.

Verwende container_auto, wenn OpenAI für die Anfrage einen Container bereitstellen und verwalten soll.

Shell-Tool mit container_auto
curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [
      { "type": "shell", "environment": { "type": "container_auto" } }
    ],
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Execute: ls -lah /mnt/data && python --version && node --version" }
        ]
      }
    ],
    "tool_choice": "auto"
  }'

Details zur gehosteten Laufzeitumgebung

  • Die Laufzeitumgebung basiert derzeit auf Debian 12. Das kann sich ändern.
  • Das Standardarbeitsverzeichnis ist /mnt/data.
  • /mnt/data ist immer vorhanden und der unterstützte Pfad für Artefakte, die sich herunterladen lassen.
  • Hosted Shell unterstützt keine interaktiven TTY-Sitzungen.
  • Hosted Shell führt Befehle ohne sudo aus.
  • Wenn dein Workflow Dienste benötigt, kannst du sie im Container ausführen.

Derzeit sind unter anderem folgende Sprachen und Laufzeitumgebungen vorinstalliert:

  • Python 3.11
  • Node.js 22.16
  • Java 17.0
  • PHP 8.2
  • Ruby 3.1
  • Go 1.23

Einen Container für mehrere Anfragen verwenden

Wenn du für einen iterativen Workflow eine Umgebung benötigst, die über längere Zeit aktiv bleibt, erstelle einen Container und verweise bei nachfolgenden Aufrufen der Responses API auf ihn.

1. Container erstellen

Einen wiederverwendbaren Container erstellen
curl -L 'https://api.openai.com/v1/containers' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "name": "analysis-container",
    "memory_limit": "1g",
    "expires_after": { "anchor": "last_active_at", "minutes": 20 }
  }'

2. In der Responses API auf den Container verweisen

Shell mit container_reference verwenden
curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "container_reference",
          "container_id": "cntr_08f3d96c87a585390069118b594f7481a088b16cda7d9415fe"
        }
      }
    ],
    "input": "List files in the container and show disk usage."
  }'

Skills einbinden

Skills sind wiederverwendbare, versionierte Pakete, die du in Umgebungen für Hosted Shell einbinden kannst. Damit legst du fest, welche Skills verfügbar sind. Beim Ausführen von Shell-Befehlen entscheidet das Modell, ob es die Skills aufruft.

Einzelheiten zum Hochladen und zur Versionierung findest du im Leitfaden zu Skills.

Einen Container mit eingebundenen Skills erstellen
curl -L 'https://api.openai.com/v1/containers' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "name": "skill-container",
    "skills": [
      { "type": "skill_reference", "skill_id": "skill_4db6f1a2c9e73508b41f9da06e2c7b5f" },
      { "type": "skill_reference", "skill_id": "openai-spreadsheets", "version": "latest" }
    ]
  }'

Netzwerkzugriff

Gehostete Container haben standardmäßig keinen ausgehenden Netzwerkzugriff.

Um ihn zu aktivieren, sind zwei Schritte erforderlich:

  1. Eine Person mit Administratorrechten muss im Dashboard die Freigabeliste deiner Organisation konfigurieren.
  2. Du musst in deiner Anfrage network_policy für die Containerumgebung explizit festlegen.
Shell-Tool mit Freigabeliste für den Netzwerkzugriff
curl -L 'https://api.openai.com/v1/responses' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "tool_choice": "required",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "container_auto",
          "network_policy": {
            "type": "allowlist",
            "allowed_domains": ["pypi.org", "files.pythonhosted.org", "github.com"]
          }
        }
      }
    ],
    "input": [
      {
        "role": "user",
        "content": "In the container, pip install httpx beautifulsoup4, fetch release pages, and write /mnt/data/release_digest.md."
      }
    ]
  }'

Die Freigabe von Domains birgt Sicherheitsrisiken. Beispielsweise können durch Prompt Injection Daten abfließen. Gib nur Domains frei, denen du vertraust und die Angreifende nicht zum Empfang gestohlener Daten nutzen können. Lies den Abschnitt Risiken und Sicherheit weiter unten sorgfältig durch, bevor du dieses Tool verwendest.

Rangfolge der Netzwerkrichtlinien

Wenn mehrere Zugriffsregeln gelten, greifen sie wie folgt ineinander:

  • Die Freigabeliste deiner Organisation legt fest, welche Domains insgesamt für allowed_domains zulässig sind.
  • Mit network_policy wird der Zugriff für die einzelne Anfrage weiter eingeschränkt.
  • Anfragen schlagen fehl, wenn allowed_domains Domains enthält, die nicht auf der Freigabeliste deiner Organisation stehen.

Datenaufbewahrung und Lebenszyklus von Containern

Solange ein gehosteter Container für Hosted Shell oder Code Interpreter aktiv ist, kann die Anwendung ihren Zustand vorübergehend im Dateisystem des Containers speichern. Das Dateisystem nutzt flüchtigen Blockspeicher. Die Containerdaten werden gelöscht, sobald der Container abläuft oder explizit gelöscht wird.

Weitere Informationen zu den Kontrollmöglichkeiten für deine Daten findest du im Leitfaden ZDR und Datenresidenz.

Artefakte herunterladen

Hosted Shell kann Dateien zum Download bereitstellen. Verwende dieselben APIs für Container und Dateien wie beim Code Interpreter, um Artefakte aus /mnt/data abzurufen.

Weitere Möglichkeiten zur Datenkontrolle

Wenn Inhalte und Dateien nur für die Lebensdauer des gehosteten Containers verfügbar sein sollen, kannst du Dateien direkt in der Anfrage übergeben und inline übergebene Skills in den Container einbinden.

Dateien und Skills inline übergeben
INLINE_ZIP=$(base64 -i ./csv_insights.zip)
REPORT_CSV=$(base64 -i ./report.csv)

CONTAINER_ID=$(
  curl -sL 'https://api.openai.com/v1/containers' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
      "name": "inline-skill-container",
      "skills": [
        {
          "type": "inline",
          "name": "csv-insights",
          "description": "Summarize CSV files and produce a markdown report.",
          "source": {
            "type": "base64",
            "media_type": "application/zip",
            "data": "'"$INLINE_ZIP"'"
          }
        }
      ]
    }' | jq -r '.id'
)

curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "container_reference",
          "container_id": "'"$CONTAINER_ID"'"
        }
      }
    ],
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_file",
            "filename": "report.csv",
            "file_data": "data:text/csv;base64,'"${REPORT_CSV}"'"
          },
          {
            "type": "input_text",
            "text": "Use the csv-insights skill to summarize report.csv."
          }
        ]
      }
    ]
  }'

Übergib bei Folgeanfragen dieselbe container_id mit container_reference. Die eingebundenen Skills und die vorhandenen Dateien im Container bleiben verfügbar, solange der Container aktiv ist.

Einen Container vorzeitig löschen

Sobald die Arbeit abgeschlossen ist, kannst du den Container explizit löschen, ohne zu warten, bis er wegen Inaktivität abläuft.

Einen Container löschen
curl -L -X DELETE 'https://api.openai.com/v1/containers/container_id' \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Secrets für Domains

Verwende domain_secrets, wenn eine Domain in deiner Liste allowed_domains einen Autorisierungsheader mit vertraulichen Daten erfordert, etwa Authorization: Bearer <token>.

Jeder Secret-Eintrag enthält folgende Angaben:

  • Zieldomain
  • Aussagekräftiger Name für das Secret
  • Wert des Secrets

Zur Laufzeit gilt Folgendes:

  • Das Modell und die Laufzeitumgebung sehen nur Platzhalternamen (zum Beispiel $API_KEY) anstelle der tatsächlichen Zugangsdaten.
  • Der Sidecar für die Authentifizierung setzt die tatsächlichen Secret-Werte nur bei Anfragen an genehmigte Ziele ein.
  • Die tatsächlichen Secret-Werte werden auf den API-Servern nicht dauerhaft gespeichert und erscheinen nicht im Kontext, den das Modell einsehen kann.

So kann der Assistent geschützte Dienste aufrufen. Zugleich sinkt das Risiko, dass Zugangsdaten offengelegt werden.

Shell-Tool mit domain_secrets
curl -L 'https://api.openai.com/v1/responses' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "input": [
      {
        "role": "user",
        "content": "Use curl to call https://httpbin.org/headers with header Authorization: Bearer $API_KEY. Tell me what you see in the final text response."
      }
    ],
    "tool_choice": "required",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "container_auto",
          "network_policy": {
            "type": "allowlist",
            "allowed_domains": ["httpbin.org"],
            "domain_secrets": [
              {
                "domain": "httpbin.org",
                "name": "API_KEY",
                "value": "debug-secret-123"
              }
            ]
          }
        }
      }
    ]
  }'

Workflows über mehrere Anfragen hinweg

Um in derselben gehosteten Umgebung weiterzuarbeiten, verwende den Container erneut und übergib previous_response_id.

Einen Shell-Workflow fortsetzen
curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "previous_response_id": "resp_2a8e5c9174d63b0f18a4c572de9f64a1b3c76d508e12f9ab47",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "container_reference",
          "container_id": "cntr_f19c2b51e4a06793d82d54a7be0fc9154d3361ab28ce7f6041"
        }
      }
    ],
    "input": "Read /mnt/data/top5.csv and report the top candidate."
  }'

Shell-Ausgaben in der Responses API

Hosted Shell und die lokale Shell verwenden dieselben Typen von Ausgabeelementen. Jede Shell-Ausführung wird durch ein Paar von Ausgabeelementen dargestellt:

  • shell_call: die vom Modell angeforderten Befehle.
  • shell_call_output: die Befehlsausgabe und Angaben dazu, wie die Ausführung endete.
Beispiel für ein shell_call-Element
{
  "type": "shell_call",
  "call_id": "call_9d14ac6f2b73485e91c0f4da6e1b27c8",
  "action": {
    "commands": ["ls -l"],
    "timeout_ms": 120000,
    "max_output_length": 4096
  },
  "status": "in_progress"
}

Lokaler Shell-Modus

Du kannst Shell-Befehle auch in deiner eigenen lokalen Laufzeitumgebung ausführen. Führe dazu die Aktionen vom Typ shell_call aus und sende shell_call_output an das Modell zurück.

Verwende diesen Modus, wenn du die Kontrolle über das Dateisystem oder Zugriff auf interne Tools benötigst. Setze den Typ des Tools auf shell und den Typ seiner Umgebung auf local. Wenn du vom eingestellten Tool local_shell umsteigst, aktualisiere deine Anfrage und verarbeite shell_call und shell_call_output in deiner Ausführungsschleife.

Anfrage für die lokale Shell
curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "instructions": "The local bash shell environment is on Mac.",
    "input": "find me the largest pdf file in ~/Documents",
    "tools": [{ "type": "shell", "environment": { "type": "local" } }]
  }'

Wenn du Ausgabeelemente vom Typ shell_call erhältst, gehe wie folgt vor:

  • Prüfe jeden Befehl vor der Ausführung. Verwende eine Freigabeliste. Verlange eine Genehmigung für Befehle, die destruktiv sind oder auf sensible Daten zugreifen.
  • Führe genehmigte Befehle in einer Sandbox aus. Beschränke ausdrücklich den Zugriff auf Dateisystem und Netzwerk sowie den Speicherverbrauch und die Ausführungsdauer. Setze dein eigenes Zeitlimit durch, auch wenn das Modell eines vorschlägt.
  • Protokolliere die Befehle und ihre Ergebnisse für spätere Prüfungen.
  • Erfasse stdout, stderr und das Ergebnis der Ausführung.
  • Gib die Ergebnisse in der nächsten Anfrage als shell_call_output zurück.
Beispiel für einen lokalen Shell-Executor
from contextlib import suppress
from dataclasses import dataclass
import os
import signal
import subprocess


@dataclass
class CmdResult:
    stdout: str
    stderr: str
    exit_code: int | None
    timed_out: bool


class ShellExecutor:
    def __init__(self, default_timeout: float = 60):
        self.default_timeout = default_timeout

    def run(self, cmd: str, timeout: float | None = None) -> CmdResult:
        t = self.default_timeout if timeout is None else timeout
        p = subprocess.Popen(
            cmd,
            shell=True,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            start_new_session=True,
        )
        try:
            out, err = p.communicate(timeout=t)
            return CmdResult(out, err, p.returncode, False)
        except subprocess.TimeoutExpired:
            # Stop the shell and its children before draining their output pipes.
            with suppress(ProcessLookupError):
                os.killpg(p.pid, signal.SIGKILL)
            out, err = p.communicate()
            return CmdResult(out, err, p.returncode, True)

Diese Beispiele setzen Linux oder macOS voraus. Läuft das Zeitlimit eines Befehls ab, beendet der Beispielcode die gesamte Prozessgruppe des Befehls.

Beispiel für die Nutzdaten von shell_call_output
{
  "type": "shell_call_output",
  "call_id": "call_3ef1b8c79a4d6520f9e3ab7d41c68f25",
  "max_output_length": 4096,
  "output": [
    {
      "stdout": "...",
      "stderr": "...",
      "outcome": {
        "type": "exit",
        "exit_code": 0
      }
    },
    {
      "stdout": "...",
      "stderr": "...",
      "outcome": {
        "type": "timeout"
      }
    }
  ]
}

Wenn ein Befehl fehlschlägt oder sein Zeitlimit überschreitet, gib das Ergebnis zurück. So kann das Modell entscheiden, ob es einen weiteren Versuch unternimmt. Siehe auch den Hinweis zur Abschaltung des früheren Tools.

Die lokale Shell mit dem Agents SDK verwenden

Wenn du das Agents SDK verwendest, kannst du der Hilfsfunktion für das Shell-Tool deine eigene Implementierung eines Shell-Executors übergeben.

Die lokale Shell mit dem Agents SDK verwenden
import {
  Agent,
  run,
  withTrace,
  shellTool,
  type ShellAction,
  type ShellResult,
} from "@openai/agents";

class LocalShell {
  async run(action: ShellAction): Promise<ShellResult> {
    return {
      output: [
        {
          stdout: "Shell is not available. Needs to be implemented first.",
          stderr: "",
          outcome: {
            type: "exit",
            exitCode: 1,
          },
        },
      ],
      maxOutputLength: action.maxOutputLength,
    };
  }
}

const shell = new LocalShell();

const agent = new Agent({
  name: "Shell Assistant",
  model: "gpt-6-astra",
  instructions:
    "You can execute shell commands to inspect the repository. Keep responses concise and include command output when helpful.",
  tools: [
    shellTool({
      shell,
      needsApproval: true,
      onApproval: async (_ctx, _approvalItem) => {
        return { approve: true };
      },
    }),
  ],
});

await withTrace("shell-tool-example", async () => {
  const result = await run(agent, "Show the Node.js version.");
  console.log(`\nFinal response:\n${result.finalOutput}`);
});

In den SDK-Repositories findest du lauffähige Beispiele.

Beispiel für das Shell-Tool in TypeScript

TypeScript-Beispiel für das Shell-Tool im Agents SDK.

Beispiel für das Shell-Tool in Python

Python-Beispiel für das Shell-Tool im Agents SDK.

Häufige Fehler behandeln

  • Überschreitet ein Befehl das Zeitlimit für die Ausführung, melde die Zeitüberschreitung als Ergebnis und gib die bis dahin erfasste Ausgabe mit zurück.
  • Wenn max_output_length in shell_call angegeben ist, übernimm den Wert in shell_call_output.
  • Verlasse dich nicht auf interaktive Befehle. Das Shell-Tool sollte Befehle ohne Benutzereingaben ausführen.
  • Behalte die Ausgabe auch bei einem Exit-Code ungleich null bei, damit das Modell geeignete Schritte zur Fehlerbehebung ableiten kann.

Risiken und Sicherheit

Wenn du den Netzwerkzugriff in der Containers API aktivierst, erweiterst du die Möglichkeiten der Container erheblich. Damit gehen erhebliche Risiken für die Sicherheit und den Umgang mit Daten einher. Standardmäßig ist der Netzwerkzugriff deaktiviert. Wenn du ihn aktivierst, solltest du ausgehende Verbindungen auf vertrauenswürdige Domains beschränken, die für die Aufgabe erforderlich sind.

Container mit Netzwerkzugriff können mit Diensten von Drittanbietern und Paketregistries interagieren. Dadurch können Daten abfließen, Tools durch Prompt Injection missbraucht oder Zugriffe unbeabsichtigt über die vorgesehenen Grenzen hinaus ermöglicht werden. Die Risiken steigen, wenn Richtlinien zu weit gefasst sind, unverändert bleiben oder uneinheitlich durchgesetzt werden.

Risiken durch Prompt Injection in Inhalten aus dem Netzwerk verstehen

Alle externen Inhalte, die du über das Netzwerk abrufst, können versteckte Anweisungen enthalten, die das Verhalten des Modells manipulieren sollen. Rechne bei nicht vertrauenswürdigen Netzwerkinhalten mit möglichen Angriffen. Sei besonders vorsichtig bei Aktionen, die Daten oder Systeme verändern können.

Verbindungen nur zu vertrauenswürdigen Zielen zulassen

Gib nur Domains frei, denen du vertraust und die du aktiv pflegst. Sei vorsichtig bei Vermittlungsdiensten und Aggregatoren, die Anfragen an andere Dienste weiterleiten. Prüfe, wie sie Daten verarbeiten und aufbewahren, bevor du ihre Domains in deine Freigabeliste aufnimmst.

Prüfungen vor und nach der Ausführung von Anfragen einplanen

Prüfe den Befehl des Shell-Tools und seine Ausgabe. Beides findest du in der Antwort der Responses API. Protokolliere für jede Sitzung die angeforderten Hosts und die tatsächlichen Ziele ausgehender Verbindungen. Prüfe die Protokolle regelmäßig, um festzustellen, ob die Zugriffsmuster deinen Erwartungen entsprechen, ob sie sich mit der Zeit verändern und ob verdächtiges Verhalten auftritt.

Anforderungen an Datenresidenz und Datenaufbewahrung prüfen

Datenkontrollen von OpenAI gelten innerhalb der Systeme von OpenAI. Für Daten, die über Netzwerkverbindungen an Dienste von Drittanbietern übertragen werden, gelten die Aufbewahrungsrichtlinien dieser Anbieter. Stelle sicher, dass externe Endpunkte deine Anforderungen an Datenresidenz, Aufbewahrung und Compliance erfüllen.