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

Subagenten

Nutze Subagenten in ChatGPT und Codex und konfiguriere eigene Codex-Agenten

ChatGPT Work und Codex können spezialisierte Subagenten parallel starten und ihre Ergebnisse in einer Antwort zusammenführen. Das ist besonders hilfreich bei komplexen Aufgaben, bei denen sich viele Schritte parallel erledigen lassen, etwa wenn du eine Codebasis untersuchst oder ein Feature nach einem mehrstufigen Plan implementierst.

In lokalen Codex-Clients kannst du außerdem eigene Agenten definieren und für jede Aufgabe passende Modelleinstellungen und Anweisungen festlegen.

Verfügbarkeit

In aktuellen Codex-Versionen sind Workflows mit Subagenten standardmäßig aktiviert. Die Aktivitäten der Subagenten siehst du in der ChatGPT-Desktop-App, in der Codex CLI und in der IDE-Erweiterung.

Da jeder Subagent eigene Modell- und Toolaufrufe ausführt, verbrauchen Workflows mit Subagenten mehr Token als vergleichbare Durchläufe mit einem einzelnen Agenten.

Bitte Codex in einem Chat in der App, unabhängige Teilaufgaben an Subagenten zu delegieren. Aktuelle lokale Codex-Versionen delegieren Aufgaben, wenn du direkt darum bittest oder wenn die geltenden Anweisungen in AGENTS.md oder in einem Skill dies vorsehen. In der App siehst du den Thread jedes Subagenten. Dort kannst du seine Arbeit und die Zusammenfassung prüfen, die er an den Hauptchat zurückgibt.

Vorteile von Workflows mit Subagenten

Auch Modelle mit großen Kontextfenstern haben Grenzen. Im Hauptchat legst du Anforderungen und Rahmenbedingungen fest und triffst Entscheidungen. Wenn sich dort Zwischenausgaben wie Notizen zur Codeanalyse, Testprotokolle, Stacktraces und Befehlsausgaben ansammeln, kann die Sitzung mit der Zeit weniger zuverlässige Ergebnisse liefern.

Dafür sind zwei Begriffe gebräuchlich:

  • Kontextverschmutzung: Nützliche Informationen gehen in der Menge der Zwischenausgaben unter.
  • Kontextverfall: Die Leistung des Modells lässt nach, wenn sich im Chat immer mehr nebensächliche Details ansammeln.

Mehr dazu erfährst du im Beitrag von Chroma zum Kontextverfall.

Mit Subagenten kannst du Aufgaben, die viele Zwischenausgaben erzeugen, aus dem Haupt-Thread auslagern:

  • Lass den Hauptagenten die Anforderungen, Entscheidungen und Endergebnisse im Blick behalten.
  • Setze spezialisierte Subagenten parallel ein, um Code zu untersuchen, Tests auszuführen oder Protokolle auszuwerten.
  • Lass die Subagenten Zusammenfassungen statt unbearbeiteter Zwischenausgaben zurückgeben.

Wenn sich Aufgaben unabhängig voneinander parallel erledigen lassen, kannst du damit auch Zeit sparen. Größere Aufgaben lassen sich leichter bewältigen, wenn du sie in klar abgegrenzte Teile zerlegst. Codex kann zum Beispiel die Analyse eines Dokuments mit mehreren Millionen Token aufteilen und die wichtigsten Erkenntnisse an den Haupt-Thread zurückgeben.

Setze parallele Agenten zunächst für Aufgaben ein, bei denen sie vor allem Informationen lesen und auswerten, etwa für Codeanalysen, Tests, Triage und Zusammenfassungen. Bei parallelen Workflows mit vielen Schreibzugriffen ist mehr Vorsicht geboten. Wenn mehrere Agenten gleichzeitig Code bearbeiten, können Konflikte entstehen und der Abstimmungsaufwand kann steigen.

Grundbegriffe

Codex verwendet für Workflows mit Subagenten einige verwandte Begriffe:

  • Workflow mit Subagenten: Ein Ablauf, bei dem Codex Agenten parallel ausführt und ihre Ergebnisse zusammenführt.
  • Subagent: Ein Agent, den Codex startet, um ihm eine bestimmte Aufgabe zu übertragen.
  • Agenten-Thread: Der Thread, in dem ein Subagent seine Aufgabe bearbeitet. In Clients, die diese Funktion unterstützen, kannst du diese Threads öffnen, um den Fortschritt oder die Ergebnisse einzusehen.

Workflows mit Subagenten starten

Bitte direkt um Subagenten oder darum, mehrere Agenten parallel einzusetzen. Codex kann Aufgaben auch delegieren, wenn die geltenden Projekt- oder Skill-Anweisungen dies vorsehen.

Um den Workflow selbst zu starten, gib eine direkte Anweisung wie „Starte zwei Agenten“, „Delegiere diese Aufgaben zur parallelen Bearbeitung“ oder „Setze für jeden Punkt einen Agenten ein“. Workflows mit Subagenten verbrauchen mehr Token als vergleichbare Durchläufe mit einem einzelnen Agenten, da jeder Subagent eigene Modell- und Toolaufrufe ausführt.

Gib im Prompt an, wie Codex die Arbeit aufteilen soll, ob es vor dem nächsten Schritt auf alle Agenten warten soll und welche Zusammenfassung oder Ausgabe du erwartest.

Prüfe diesen Branch mit parallel arbeitenden Subagenten. Starte einen Subagenten für Sicherheitsrisiken, einen für Lücken in der Testabdeckung und einen für die Wartbarkeit. Warte auf alle drei und fasse dann die Ergebnisse nach Kategorie zusammen. Gib jeweils die zugehörigen Dateien an.

Modell und Reasoning-Aufwand auswählen

Je nach Aufgabe brauchen Agenten unterschiedliche Einstellungen für Modell und Reasoning-Aufwand.

Wenn du weder ein Modell für den Subagenten noch model_reasoning_effort festlegst, übernimmt der Subagent das Modell und den Reasoning-Aufwand des übergeordneten Agenten. Wählst du beim Start ausdrücklich ein Modell aus oder gibt eine Standardeinstellung unter [agents] ein Modell vor, ohne dass der Reasoning-Aufwand beim Start angegeben oder in der Konfiguration festgelegt ist, nutzt der Subagent den Standardwert des gewählten Modells. Um Intelligenz, Geschwindigkeit und Kosten auf die jeweilige Aufgabe abzustimmen, kannst du im Prompt ein bestimmtes Modell oder einen bestimmten Reasoning-Aufwand anfordern, die Standardwerte für [agents] in config.toml konfigurieren oder model und model_reasoning_effort direkt in der Datei des eigenen Agenten festlegen. Verwende zum Beispiel gpt-6-luna für schnelle Prüfungen oder gpt-6.1-sol mit höherem Reasoning-Aufwand für Aufgaben, die anspruchsvolleres Reasoning erfordern.

Verwende für die meisten Aufgaben in Codex zunächst gpt-6.1-sol, wenn du mit deinem angemeldeten Konto oder über deinen Workspace Zugriff auf das Modell hast. Wähle andernfalls ein Modell, auf das du zugreifen kannst. Für einfachere Aufgaben von Subagenten bietet gpt-6-luna eine schnellere und kostengünstigere Option.

Modellwahl

  • gpt-6.1-sol: Starte mit diesem Modell, wenn ein Agent anspruchsvolle Aufgaben übernimmt. Es eignet sich für mehrstufige Aufgaben mit offenen Fragen, bei denen der Agent in einem größeren Kontext planen, Tools einsetzen, Ergebnisse prüfen und die Arbeit bis zum Abschluss verfolgen muss.
  • gpt-6-luna: Nutze dieses Modell für schnelle Agenten mit eng umrissenem Auftrag, etwa für klar definierte, wiederkehrende oder in großer Zahl anfallende Aufgaben.

Reasoning-Aufwand (model_reasoning_effort)

Wähle für GPT-6.1 Sol einen Reasoning-Aufwand, den dein Client und das gewählte Modell unterstützen. Wenn du die Modelleinstellungen ausdrücklich festlegst, beginne mit high für GPT-6 Luna oder low für GPT-6 Astra. Passe die Stufe an die Aufgabe an und verwende dabei einen Wert, den das Modell unterstützt.

  • ultra: Wähle diese Stufe für besonders tiefgehendes Reasoning, wenn das gewählte Modell sie unterstützt.
  • max und xhigh: Verwende diese Stufen für besonders anspruchsvolles Reasoning, wenn das gewählte Modell sie unterstützt.
  • high: Wähle diese Stufe, wenn ein Agent komplexe Logik nachvollziehen, Annahmen prüfen oder Grenzfälle untersuchen muss, etwa bei der Code- oder Sicherheitsprüfung.
  • medium: Bietet ein ausgewogenes Verhältnis zwischen Geschwindigkeit und Analysetiefe.
  • low: Wähle diese Stufe für einfache Aufgaben, bei denen es vor allem auf Geschwindigkeit ankommt.

Ein höherer Reasoning-Aufwand verlängert die Antwortzeit und erhöht den Tokenverbrauch, kann aber bei komplexen Aufgaben die Qualität verbessern. Weitere Informationen findest du unter Modelle, Grundlagen der Konfiguration und Konfigurationsreferenz.

Agenten koordinieren und Threads steuern

ChatGPT oder Codex koordiniert die Agenten, startet neue Subagenten, leitet weitere Anweisungen an sie weiter, wartet auf Ergebnisse und schließt Agenten-Threads.

Wenn viele Agenten gleichzeitig laufen, wartet Codex, bis alle angeforderten Ergebnisse vorliegen, und fasst sie dann in einer Antwort zusammen.

Aktuelle lokale Codex-Versionen starten Agenten, wenn du direkt darum bittest oder wenn die geltenden Projekt- oder Skill-Anweisungen dies vorsehen.

Probiere den folgenden Prompt in deinem Projekt aus:

Prüfe den aktuellen Pull Request anhand der folgenden Punkte. Vergleiche dazu diesen Branch mit main. Starte für jeden Punkt einen Agenten, warte auf alle Agenten und fasse das Ergebnis für jeden Punkt zusammen.
1. Sicherheitsprobleme
2. Codequalität
3. Fehler
4. Race Conditions
5. Sporadisch fehlschlagende Tests
6. Wartbarkeit des Codes

Subagenten verwalten

  • Öffne über die Aktivitätsanzeige im Haupt-Thread den Thread eines Subagenten, um seine Arbeit zu prüfen.
  • Bitte Codex direkt, einem laufenden Subagenten weitere Anweisungen zu geben, ihn zu stoppen oder abgeschlossene Subagenten-Threads zu schließen.

Genehmigungen und Sandbox-Einstellungen

Subagenten übernehmen deine aktuelle Sandbox-Richtlinie.

Subagenten übernehmen den unterhalb des Editors ausgewählten Berechtigungsmodus. Wähle den Berechtigungsmodus für den übergeordneten Agentenschritt, bevor du Codex bittest, Aufgaben zu delegieren.

Lege die Sandbox- und Genehmigungseinstellungen in der übergeordneten Sitzung fest. Du kannst einen eigenen Agenten anweisen, nichts zu bearbeiten. Dadurch entsteht aber keine separate Sandbox ohne Schreibzugriff.

Eigene Agenten

Codex enthält die folgenden integrierten Agenten:

  • default: vielseitig einsetzbarer Agent, auf den Codex bei Bedarf zurückgreift.
  • worker: Agent für die Umsetzung von Änderungen und die Fehlerbehebung.
  • explorer: Agent, der die Codebasis vor allem durch Lesezugriffe untersucht.

Um eigene Agenten zu definieren, lege separate TOML-Dateien an. Verwende ~/.codex/agents/ für persönliche Agenten oder .codex/agents/ für Agenten, die nur im jeweiligen Projekt gelten.

Jede Datei definiert einen eigenen Agenten. Du kannst darin Modelleinstellungen und Anweisungen ändern oder unterstützte Funktionen deaktivieren. Berechtigungen, Anbieter und MCP-Server übernimmt der Agent vom übergeordneten Agenten. Diese Einstellungen lassen sich in der Agentendatei nicht überschreiben.

Jede eigenständige Datei für einen eigenen Agenten muss folgende Felder definieren:

  • name
  • description
  • developer_instructions

Wenn die Agentendatei model oder model_reasoning_effort festlegt, hat der Wert aus der Datei Vorrang. Bevor Codex die Datei anwendet, ermittelt es jede Einstellung in dieser Reihenfolge: zuerst der beim Start ausdrücklich angegebene Wert, dann der entsprechende Standardwert unter [agents], zuletzt der Wert des übergeordneten Agenten. Wenn beim Start oder über einen Standardwert unter [agents] ein Modell ausgewählt wird und keine der beiden Quellen einen Reasoning-Aufwand vorgibt, verwendet Codex den Standardwert des Modells. Eine Agentendatei, die nur model festlegt, behält den zuvor ermittelten Reasoning-Aufwand bei. Lege in der Datei auch model_reasoning_effort fest, wenn das gewählte Modell diesen Aufwand nicht unterstützt oder du einen anderen Wert verwenden möchtest. Skills werden vom übergeordneten Agenten übernommen. Mit skills.config kannst du einzelne Skills für deinen Agenten deaktivieren.

Globale Einstellungen

Die globalen Einstellungen für Subagenten findest du weiterhin unter [agents] in deiner Konfiguration.

Feld Typ Erforderlich Zweck
agents.enabled boolean Nein Aktiviert oder deaktiviert Tools für die Arbeit mit mehreren Agenten.
agents.max_concurrent_threads_per_session number Nein Begrenzt die Anzahl gleichzeitig geöffneter Threads gestarteter Agenten. Der Haupt-Thread zählt nicht mit.
agents.default_subagent_model string Nein Legt das Standardmodell für neu gestartete Agenten fest.
agents.default_subagent_reasoning_effort string Nein Legt den standardmäßigen Reasoning-Aufwand für neu gestartete Agenten fest.
agents.interrupt_message boolean Nein Protokolliert eine für das Modell sichtbare Nachricht, wenn ein Agentenschritt unterbrochen wird.

Hinweise:

  • agents.enabled hat den Standardwert true. Setze den Wert auf false, um die Tools für die Arbeit mit mehreren Agenten zu deaktivieren.
  • Wenn du agents.max_concurrent_threads_per_session nicht festlegst, wählt Codex den Standardwert. Bestehende Konfigurationen können weiterhin den älteren Alias agents.max_threads verwenden.
  • Beim Start ausdrücklich angegebene Werte haben Vorrang vor agents.default_subagent_model und agents.default_subagent_reasoning_effort.
  • agents.interrupt_message hat den Standardwert true. Setze den Wert auf false, damit die für das Modell sichtbare Nachricht zur Unterbrechung nicht in den Kontext des Agenten aufgenommen wird.
  • Wenn dein eigener Agent denselben Namen hat wie ein integrierter Agent, etwa explorer, hat dein Agent Vorrang.

Schema für eigene Agentendateien

Feld Typ Erforderlich Zweck
name string Ja Name, unter dem Codex den Agenten startet oder auf ihn verweist.
description string Ja Für Menschen verständliche Beschreibung, wann Codex diesen Agenten einsetzen soll.
developer_instructions string Ja Grundlegende Anweisungen, die das Verhalten des Agenten bestimmen.

Mit model, model_reasoning_effort, model_reasoning_summary und model_verbosity kannst du das Modellverhalten anpassen. Die zulässigen Werte findest du in der Konfigurationsreferenz.

Um die Funktionen eines eigenen Agenten einzuschränken, setze die entsprechenden unterstützten Konfigurationsschlüssel auf false: features.shell_tool, features.apps, features.plugins, features.memories oder features.request_permissions_tool. Deaktiviere einzelne Skills mit skills.config oder mitgelieferte Skills mit skills.bundled.enabled = false. Setze skills.include_instructions = false, um den automatisch eingefügten Block mit Skill-Anweisungen wegzulassen. Zentral verwaltete Vorgaben gelten weiterhin.

Andere Sitzungseinstellungen, darunter sandbox_mode, approval_policy, model_provider und mcp_servers, überschreiben die übergeordnete Konfiguration nicht, wenn du sie in eine eigene Agentendatei einträgst. Auch die Servicestufe richtet sich nach der Einstellung der Stammsitzung. Konfiguriere MCP-Server in der übergeordneten Sitzung, damit der Agent sie nutzen kann.

Codex identifiziert den eigenen Agenten anhand seines Felds name. Am einfachsten gibst du der Datei denselben Namen wie dem Agenten. Maßgeblich ist jedoch der Name im Feld.

Beispiele für eigene Agenten

Eigene Agenten arbeiten am besten mit einem eng umrissenen Auftrag und klaren Vorgaben. Gib jedem Agenten eine eindeutige Aufgabe, die dafür passenden Tools und Anweisungen, damit er sich auf seinen Zuständigkeitsbereich beschränkt.

Die Beispiele verwenden GPT-6.1 Sol, sofern du mit deinem angemeldeten Konto oder über deinen Workspace darauf zugreifen kannst. Wähle andernfalls ein Modell, das dir zur Verfügung steht.

Beispiel 1: Einen Pull Request prüfen

In diesem Beispiel teilen sich drei spezialisierte Agenten die Prüfung:

  • pr_explorer untersucht die Struktur der Codebasis und sammelt Belege.
  • reviewer sucht nach Fehlern, Sicherheitsrisiken und Risiken bei den Tests.
  • docs_researcher prüft die Framework- oder API-Dokumentation über einen eigens dafür vorgesehenen MCP-Server.

Projektkonfiguration (.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 8

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

.codex/agents/pr-explorer.toml:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

.codex/agents/reviewer.toml:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

.codex/agents/docs-researcher.toml:

name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""

Dieses Setup eignet sich für Prompts wie diesen:

Vergleiche diesen Branch mit main. Lass pr_explorer die betroffenen Codepfade ermitteln, reviewer nach konkreten Risiken suchen und docs_researcher die Framework-APIs überprüfen, von denen der Patch abhängt.

Beispiel 2: Integrationsfehler im Frontend untersuchen

Dieser Ansatz eignet sich für Regressionen in der Benutzeroberfläche, sporadisch fehlschlagende Abläufe im Browser oder Integrationsfehler, deren Untersuchung sowohl den Anwendungscode als auch das laufende Produkt erfordert.

Projektkonfiguration (.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 6

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20

.codex/agents/code-mapper.toml:

name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Map the code that owns the failing UI flow.
Do not edit files.
Identify entry points, state transitions, and likely files before the worker starts editing.
"""

.codex/agents/browser-debugger.toml:

name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"""

.codex/agents/ui-fixer.toml:

name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

Dieses Setup eignet sich für Prompts wie diesen:

Untersuche, warum das Speichern im Einstellungsdialog fehlschlägt. Lass browser_debugger den Fehler reproduzieren und code_mapper den dafür verantwortlichen Codepfad nachverfolgen. Sobald klar ist, wie sich der Fehler äußert, soll ui_fixer die kleinstmögliche Korrektur umsetzen.