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.
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15require "openai"client = OpenAI::Client.newresponse = client.responses.create( model: "gpt-6-astra", input: "Run ls -lah /mnt/data, then show the Python and Node.js versions.", tools: [ { type: :shell, environment: { type: :container_auto } } ])puts(response.output_text)
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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "openai"client = OpenAI::Client.newresponse = client.responses.create( model: "gpt-6-astra", input: "List files in the container and show disk usage.", tools: [ { type: :shell, environment: { type: :container_reference, container_id: "cntr_08f3d96c87a585390069118b594f7481a088b16cda7d9415fe" } } ])puts(response.output_text)
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
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.
Ü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.
import OpenAI from "openai";const client = new OpenAI();await client.containers.delete("container_id");console.log("Container deleted");
# Replace the illustrative IDs and URLs below with your own resource values.from openai import OpenAIclient = OpenAI()container_id = "cntr_123"client.containers.delete(container_id)print("Container deleted")
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32curl-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" } ] } } } ] }'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36import OpenAI from "openai";const client = new OpenAI();const response = await client.responses.create({ 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", }, ], }, }, }, ],});console.log(response.output_text);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35from openai import OpenAIclient = OpenAI()response = client.responses.create( 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", } ], }, }, } ],)print(response.output_text)
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.
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
1
2
3
4
5
6
7
8
9curl-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" } }] }'
1
2
3
4
5
6
7
8
9
10
11
12import OpenAI from "openai";const client = new OpenAI();const response = await client.responses.create({ 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" } }],});console.log(response);
1
2
3
4
5
6
7
8
9
10
11
12from openai import OpenAIclient = OpenAI()response = client.responses.create( 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"}}],)print(response)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26package mainimport ( "context" "fmt" "github.com/openai/openai-go/v3" "github.com/openai/openai-go/v3/responses")func main() { client := openai.NewClient() tool := responses.ToolUnionParam{OfShell: &responses.FunctionShellToolParam{ Environment: responses.FunctionShellToolEnvironmentUnionParam{OfLocal: &responses.LocalEnvironmentParam{}}, }} response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{ Model: "gpt-6-astra", Instructions: openai.String("The local bash shell environment is on Mac."), Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("find me the largest pdf file in ~/Documents")}, Tools: []responses.ToolUnionParam{tool}, }) if err != nil { panic(err) } fmt.Println(response.Output)}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import com.openai.client.OpenAIClient;import com.openai.client.okhttp.OpenAIOkHttpClient;import com.openai.core.JsonValue;import com.openai.models.responses.ResponseCreateParams;import java.util.List;import java.util.Map;ResponseCreateParams params = ResponseCreateParams.builder() .model("gpt-6-astra") .input("Find the largest PDF in ~/Documents.") .instructions("The local shell environment is macOS.") .putAdditionalBodyProperty( "tools", JsonValue.from( List.of(Map.of("type", "shell", "environment", Map.of("type", "local"))))) .build();client.responses().create(params).output().stream() .flatMap(item -> item.shellCall().stream()) .flatMap(call -> call.action().commands().stream()) .forEach(System.out::println);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16require "openai"client = OpenAI::Client.newresponse = client.responses.create( model: "gpt-6-astra", instructions: "The local shell environment is macOS.", input: "Find the largest PDF in ~/Documents.", tools: [ { type: :shell, environment: { type: :local } } ])puts(response.output)
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.
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.
Ü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.