Codex-Testgerüst erschließen: App Server-Entwicklung

OpenAIs Coding-Agent Codex ist über viele verschiedene Umgebungen verfügbar: die Web-App⁠(wird in einem neuen Fenster geöffnet), die CLI⁠(wird in einem neuen Fenster geöffnet), die IDE-Erweiterung⁠(wird in einem neuen Fenster geöffnet) und die neue Codex macOS-App. Im Hintergrund werden sie alle vom selben Codex-Testgerüst angetrieben – der Agent-Schleife und Logik, die allen Codex-Erlebnissen zugrunde liegt. Die entscheidende Verbindung zwischen ihnen? Der Codex App Server⁠(wird in einem neuen Fenster geöffnet), eine clientfreundliche, bidirektionale JSON-RPC¹-API.

In diesem Beitrag stellen wir den Codex App Server vor; wir teilen unsere bisherigen Erkenntnisse zu den besten Wegen, Codex-Funktionen in dein Produkt zu bringen, damit deine Nutzer:innen ihre Workflows deutlich beschleunigen können. Wir behandeln die Architektur und das Protokoll des App Servers und wie er sich in verschiedene Codex-Umgebungen integriert, sowie Tipps zur Nutzung von Codex – egal, ob du Codex in einen Code-Reviewer, einen SRE-Agenten oder einen Coding-Assistenten verwandeln möchtest.

Bevor wir in die Architektur eintauchen, hilft ein Blick auf die Vorgeschichte des App Servers. Anfangs war der App Server eine praktische Möglichkeit, das Codex-Testgerüst produktübergreifend wiederzuverwenden, die sich nach und nach zu unserem Standardprotokoll entwickelte.

Codex CLI begann als TUI (terminal user interface), das heißt, der Zugriff auf Codex erfolgt über das Terminal. Als wir die VS Code-Erweiterung entwickelt haben – eine IDE-freundlichere Art, mit Codex-Agenten zu interagieren – brauchten wir eine Möglichkeit, dasselbe Testgerüst zu nutzen, um dieselbe Agent-Schleife aus einer IDE-Oberfläche heraus zu steuern, ohne sie neu zu implementieren. Das bedeutete, umfangreiche Interaktionsmuster über Anfrage/Antwort hinaus zu unterstützen, etwa den Workspace zu erkunden, Fortschritt zu streamen, während der Agent schlussfolgert, und Diffs auszugeben. Zunächst experimentierten wir damit, Codex als MCP-Server⁠(wird in einem neuen Fenster geöffnet) bereitzustellen, aber MCP-Semantik so zu pflegen, dass sie für VS Code sinnvoll ist, erwies sich als schwierig. Stattdessen führten wir ein JSON-RPC-Protokoll ein, das die TUI-Schleife widerspiegelte und zur inoffiziellen ersten Version⁠(wird in einem neuen Fenster geöffnet) des App Servers wurde. Damals erwarteten wir nicht, dass andere Clients vom App Server abhängig sein würden, daher war er nicht als stabile API konzipiert.

Als die Codex-Nutzung in den folgenden Monaten zunahm, wollten interne Teams und externe Partner die Möglichkeit, dasselbe Testgerüst in ihre eigenen Produkte einzubetten, um die Softwareentwicklungs-Workflows ihrer Nutzer:innen zu beschleunigen. Zum Beispiel wünschten sich JetBrains und Xcode ein Agentenerlebnis auf IDE-Niveau, während die Codex-Desktop-App viele Codex-Agenten parallel orchestrieren musste. Diese Anforderungen veranlassten uns, eine Plattform-Schnittstelle zu entwerfen, auf die sich sowohl unsere Produkte als auch Partnerintegrationen langfristig verlassen können. Sie sollte leicht zu integrieren und abwärtskompatibel sein, das heißt, wir können das Protokoll weiterentwickeln, ohne bestehende Clients zu beeinträchtigen.

Als Nächstes zeigen wir, wie wir Architektur und Protokoll so entworfen haben, dass unterschiedliche Clients dasselbe Testgerüst nutzen können.

Sehen wir uns zunächst genauer an, was sich im Codex-Testgerüst befindet und wie der Codex App Server es für Clients verfügbar macht. In unserem letzten Codex-Blog haben wir die zentrale Agent-Schleife erläutert, die die Interaktion zwischen Nutzer:in, Modell und Tools orchestriert. Das ist die Kernlogik des Codex-Testgerüsts, aber zur vollständigen Agentenerfahrung gehört mehr:

1. Thread-Lebenszyklus und Persistenz. Ein Thread ist eine Codex-Konversation zwischen einer Nutzerin oder einem Nutzer und einem Agenten. Codex erstellt, setzt fort, verzweigt und archiviert Threads und speichert den Eventverlauf dauerhaft, damit Clients sich wieder verbinden und eine konsistente Zeitleiste darstellen können.

2. Konfiguration und Authentifizierung. Codex lädt Konfigurationen, verwaltet Standardwerte und führt Authentifizierungsabläufe wie „Mit ChatGPT anmelden“ aus, einschließlich des Status der Anmeldedaten.

3. Tool-Ausführung und Erweiterungen. Codex führt Shell- und Datei-Tools in einer Sandbox aus und bindet Integrationen wie MCP-Server und Fähigkeiten an, damit sie unter einem einheitlichen Richtlinienmodell an der Agent-Schleife teilnehmen können.

Die gesamte hier erwähnte Agentenlogik, einschließlich der zentralen Agent-Schleife, befindet sich in einem Teil der Codex-CLI-Codebasis namens „Codex core⁠(wird in einem neuen Fenster geöffnet)“. Codex core ist sowohl eine Bibliothek, die den gesamten Agentencode enthält, als auch eine Laufzeitumgebung, die gestartet werden kann, um die Agent-Schleife auszuführen und die Persistenz eines Codex-Threads (Konversation) zu verwalten.

Damit das Codex-Testgerüst nützlich ist, muss es für Clients zugänglich sein. Hier kommt der App Server ins Spiel.

Der App Server ist sowohl das JSON-RPC-Protokoll zwischen Client und Server als auch ein langlebiger Prozess, der die Codex core-Threads hostet. Wie im obigen Diagramm zu sehen ist, hat ein App-Server-Prozess vier Hauptkomponenten: den stdio-Reader, den Codex-Nachrichtenprozessor, den Thread-Manager und die core-Threads. Der Thread-Manager startet für jeden Thread eine Core-Sitzung, und der Codex-Nachrichtenprozessor kommuniziert dann direkt mit jeder Core-Sitzung, um Clientanfragen zu übermitteln und Updates zu erhalten.

Eine einzelne Clientanfrage kann zu vielen Event-Updates führen, und diese detaillierten Events ermöglichen es uns, eine umfangreiche UI auf dem App Server aufzubauen. Außerdem dienen der stdio-Reader und der Codex-Nachrichtenprozessor als Übersetzungsschicht zwischen Client und Codex core-Threads. Sie übersetzen JSON-RPC-Anfragen von Clients in Codex-core-Operationen, hören auf den internen Event-Stream von Codex core und wandeln diese Low-Level-Events in eine kleine Menge stabiler, UI-tauglicher JSON-RPC-Benachrichtigungen um.

Das JSON-RPC-Protokoll zwischen Client und App Server ist vollständig bidirektional. Ein typischer Thread umfasst eine Clientanfrage und viele Serverbenachrichtigungen. Zusätzlich kann der Server Anfragen initiieren, wenn der Agent Eingaben benötigt, etwa eine Genehmigung, und die Runde dann pausieren, bis der Client antwortet.

Als Nächstes erläutern wir die Konversationsgrundbausteine, die Bausteine des App-Server-Protokolls. Eine API für eine Agent-Schleife zu entwerfen ist anspruchsvoll, weil die Interaktion zwischen Nutzer:in und Agent keine einfache Anfrage-Antwort ist. Eine einzelne Nutzeranfrage kann sich zu einer strukturierten Abfolge von Aktionen entwickeln, die der Client zuverlässig abbilden muss: die Eingabe der Nutzer:innen, den schrittweisen Fortschritt des Agenten und unterwegs erzeugte Artefakte (z. B. Diffs). Damit dieser Interaktionsstrom leicht zu integrieren und über verschiedene UIs hinweg robust ist, haben wir uns auf drei Kerngrundbausteine mit klaren Abgrenzungen und Lebenszyklen geeinigt:

1. Item: Ein Item ist die atomare Einheit von Ein- und Ausgabe in Codex. Items sind typisiert (z. B. Nutzernachricht, Assistentennachricht, Tool-Ausführung, Genehmigungsanfrage, Diff) und jedes hat einen expliziten Lebenszyklus:

• Item/gestartet, wenn das Item beginnt
• optionale Item/*/delta-Events, während Inhalte einfließen (für streamingfähige Item-Typen)
• Item/abgeschlossen, wenn das Item mit seiner finalen Payload abgeschlossen wird

Dieser Lebenszyklus ermöglicht es Clients, bei gestartet sofort mit dem Rendern zu beginnen, bei delta inkrementelle Updates zu streamen und bei abgeschlossen abzuschließen.

2. Runde: Eine Runde ist eine Arbeitseinheit des Agenten, die durch eine Nutzereingabe ausgelöst wird. Sie beginnt, wenn der Client eine Eingabe sendet (zum Beispiel „Tests ausführen und Fehler zusammenfassen“), und endet, wenn der Agent die Ausgaben für diese Eingabe fertig erzeugt hat. Eine Runde enthält eine Abfolge von Items, die die Zwischenschritte und Ausgaben auf dem Weg darstellen.

3. Thread: Ein Thread ist der dauerhafte Container für eine laufende Codex-Sitzung zwischen Nutzer:innen und einem Agenten. Er enthält mehrere Runden. Threads können erstellt, fortgesetzt, verzweigt und archiviert werden. Der Thread-Verlauf wird dauerhaft gespeichert, sodass Clients sich wieder verbinden und eine konsistente Zeitleiste darstellen können.

Sehen wir uns nun eine vereinfachte Konversation zwischen einem Client und einem Agenten an, bei der die Konversation durch Grundbausteine dargestellt wird:

Zu Beginn der Konversation müssen Client und Server den Initialisierungs-Handshake durchführen. Der Client muss genau eine Initialisierungsanfrage senden, bevor eine andere Methode aufgerufen wird, und der Server bestätigt mit einer Antwort. So kann der Server seine Fähigkeiten bekannt geben, und beide Seiten können sich auf Protokollversionen, Feature-Flags und Standardwerte einigen, bevor die eigentliche Arbeit beginnt. Hier ist eine Beispiel-Payload aus der OpenAI VS Code-Erweiterung:

So sieht die Antwort des Servers aus:

Wenn ein Client eine neue Anfrage stellt, erstellt er zuerst einen Thread und dann eine Runde. Der Server sendet Benachrichtigungen zum Fortschritt zurück (Thread/gestartet und Runde/gestartet). Außerdem sendet er Eingaben zurück, die er als Items registriert, wie hier die Nutzernachricht.

Tool-Aufrufe werden ebenfalls als Items an den Client zurückgesendet. Zusätzlich kann der Server eine Genehmigung des Clients anfordern, bevor er eine Aktion ausführen kann, indem er eine Serveranfrage sendet. Die Genehmigung pausiert die Runde, bis der Client entweder mit „erlauben“ oder „verweigern“ antwortet. So sieht dieser Genehmigungsablauf in der VS Code-Erweiterung aus:

Am Ende sendet der Server eine Assistentennachricht und beendet dann die Runde mit Runde/abgeschlossen. Die Delta-Events der Assistentennachricht streamen Teile der Nachricht zurück, bis die Nachricht mit Item/abgeschlossen abgeschlossen wird.

Die Nachrichten im Diagramm sind zur besseren Lesbarkeit vereinfacht. Wenn du das JSON für eine vollständige Runde sehen möchtest, kannst du den Test-Client aus dem Codex-CLI-Repo ausführen:

Sehen wir uns nun an, wie verschiedene Client-Oberflächen Codex über den App Server einbetten. Wir betrachten drei Muster: lokale Apps und IDEs, die Codex Web-Laufzeitumgebung und die TUI.

Bei allen drei erfolgt der Transport über JSON-RPC über stdio (JSONL). JSON-RPC macht es einfach, Client-Bindings in der Sprache deiner Wahl zu erstellen. Codex-Oberflächen und Partnerintegrationen haben App-Server-Clients unter anderem in Go, Python, TypeScript, Swift und Kotlin implementiert. Für TypeScript kannst du Definitionen direkt aus dem Rust-Protokoll generieren, indem du Folgendes ausführst:

Für andere Sprachen kannst du ein JSON-Schema-Bundle generieren und es in deinen bevorzugten Codegenerator einspeisen, indem du Folgendes ausführst:

Lokale Clients bündeln oder laden in der Regel eine plattformspezifische App-Server-Binärdatei, starten sie als langlebigen untergeordneten Prozess und halten einen bidirektionalen stdio-Kanal für JSON-RPC offen. In unserer VS Code-Erweiterung und der Desktop-App enthält das ausgelieferte Artefakt beispielsweise die plattformspezifische Codex-Binärdatei und ist auf eine getestete Version festgelegt, sodass der Client immer genau die von uns geprüfte Version ausführt.

Nicht jede Integration kann Client-Updates häufig ausliefern. Einige Partner wie Xcode entkoppeln Release-Zyklen, indem sie den Client stabil halten und ihm bei Bedarf erlauben, auf eine neuere App-Server-Binärdatei zu verweisen. So können sie serverseitige Verbesserungen (zum Beispiel bessere automatische Kompaktierung in Codex core oder neu unterstützte Konfigurationsschlüssel) übernehmen und Fehlerbehebungen einführen, ohne auf ein Client-Release zu warten. Die JSON-RPC-Oberfläche des App Servers ist abwärtskompatibel ausgelegt, sodass ältere Clients sicher mit neueren Servern kommunizieren können.

Codex Web verwendet das Codex-Testgerüst, führt es jedoch in einer Containerumgebung aus. Ein Worker stellt einen Container mit dem ausgecheckten Workspace bereit, startet darin die App-Server-Binärdatei und hält einen langlebigen JSON-RPC-over-stdio²-Kanal aufrecht. Die Web-App (die im Browser-Tab der Nutzer:innen läuft) kommuniziert über HTTP und SSE mit dem Codex-Backend, das vom Worker erzeugte Task-Events streamt. So bleibt die UI im Browser schlank, während wir dennoch eine einheitliche Laufzeitumgebung für Desktop und Web haben.

Da Web-Sessions flüchtig sind (Tabs werden geschlossen, Netzwerkverbindungen brechen zusammen), kann die Web-App nicht die maßgebliche Quelle für langlaufende Tasks sein. Wenn Status und Fortschritt auf dem Server gehalten werden, läuft die Arbeit weiter, selbst wenn der Tab verschwindet. Das Streaming-Protokoll und gespeicherte Thread-Sitzungen machen es einfach, dass eine neue Sitzung sich wieder verbindet, dort fortfährt, wo sie aufgehört hat, und aufholt, ohne den Status im Client neu aufbauen zu müssen.

Historisch war die TUI ein „nativer“ Client, der im selben Prozess wie die Agent-Schleife lief und direkt mit Rust-Core-Typen statt mit dem App-Server-Protokoll kommunizierte. Das machte frühe Iterationen schnell, machte die TUI aber auch zu einer Sonderlösung.

Jetzt, da es den App Server gibt, planen wir, die TUI so umzubauen⁠(wird in einem neuen Fenster geöffnet), dass sie ihn nutzt und sich wie jeder andere Client verhält: einen untergeordneten App-Server-Prozess starten, JSON-RPC über stdio sprechen und dieselben Streaming-Events und Genehmigungen darstellen. Das ermöglicht Workflows, bei denen die TUI sich mit einem Codex-Server auf einer entfernten Maschine verbindet, den Agenten nah an der Rechenleistung hält und die Arbeit fortsetzt, selbst wenn der Laptop in den Ruhezustand geht oder die Verbindung verliert, während lokal weiterhin Live-Updates und Steuerungsmöglichkeiten verfügbar sind.

Der Codex App Server wird künftig unsere primäre Integrationsmethode sein, aber es gibt auch andere Methoden mit eingeschränkterem Funktionsumfang. Standardmäßig empfehlen wir Clients, den Codex App Server für die Integration mit Codex zu nutzen, aber es lohnt sich, die verschiedenen Integrationsmethoden und ihre Vor- und Nachteile zu kennen. Unten findest du die gängigsten Wege, Codex anzusteuern, und wann sie jeweils gut passen.

Führe codex mcp-server⁠(wird in einem neuen Fenster geöffnet) aus und verbinde dich von einem beliebigen MCP-Client, der stdio-Server unterstützt (z. B. OpenAI Agents SDK⁠(wird in einem neuen Fenster geöffnet)). Das passt gut, wenn du bereits einen MCP-basierten Workflow hast und Codex als aufrufbares Tool nutzen möchtest. Der Nachteil ist, dass du nur das nutzen kannst, was MCP bereitstellt. Codex-spezifische Interaktionen, die reichhaltigere Sitzungssemantik nutzen (z. B. Diff-Updates), lassen sich über MCP-Endpunkte möglicherweise nicht sauber abbilden.

Einige Ökosysteme bieten eine portable Schnittstelle, die mehrere Modellanbieter und Laufzeitumgebungen ansprechen kann. Das passt gut, wenn du eine einheitliche Abstraktion möchtest, die mehrere Agenten koordiniert. Der Kompromiss ist, dass diese Protokolle sich oft auf die gemeinsame Schnittmenge der Fähigkeiten beschränken. Dadurch lassen sich umfangreichere Interaktionen schwerer darstellen, besonders wenn anbieter­spezifische Tool- und Sitzungssemantik wichtig ist. Dieser Bereich entwickelt sich schnell, und wir erwarten, dass sich weitere gemeinsame Standards herausbilden, während wir geeignete Grundbausteine für reale Agent-Workflows definieren (Fähigkeiten⁠(wird in einem neuen Fenster geöffnet) sind ein gutes Beispiel dafür).

Wähle den App Server, wenn du das vollständige Codex-Testgerüst als stabilen, UI-freundlichen Event-Stream nutzen möchtest. Du erhältst die volle Funktionalität der Agent-Schleife sowie unterstützende Funktionen wie „Mit ChatGPT anmelden“, Erkundung von Modellen und Konfigurationsverwaltung. Der Hauptaufwand liegt in der Integration, da du die clientseitige JSON-RPC-Anbindung in deiner Sprache umsetzen musst. In der Praxis kann Codex jedoch viel Vorarbeit leisten, wenn du ihm das JSON-Schema und die Dokumentation bereitstellst. Viele Teams, mit denen wir gearbeitet haben, konnten mit Codex zügig eine funktionierende Integration umsetzen.

Ein leichtgewichtiger, skriptbarer CLI-Modus für einmalige Aufgaben und CI-Läufe. Er eignet sich gut für Automatisierung und Pipelines, bei denen ein einzelner Befehl ohne Interaktion bis zum Abschluss laufen, strukturierte Ausgaben für Protokolle streamen und mit einem klaren Erfolgs- oder Fehlersignal enden soll.

Eine TypeScript-Bibliothek, mit der du lokale Codex-Agenten programmatisch aus deiner eigenen Anwendung heraus steuern kannst. Sie eignet sich besonders, wenn du eine native Bibliotheksschnittstelle für serverseitige Tools und Workflows möchtest, ohne einen separaten JSON-RPC-Client zu bauen. Da sie früher als der App Server veröffentlicht wurde, unterstützt sie derzeit weniger Sprachen und einen kleineren Funktionsumfang. Bei entsprechendem Interesse von Entwickler:innen könnten wir weitere SDKs bereitstellen, die das App-Server-Protokoll kapseln, sodass Teams mehr vom Funktionsumfang des Testgerüsts nutzen können, ohne selbst JSON-RPC-Bindings zu schreiben.

In diesem Beitrag haben wir gezeigt, wie wir einen neuen Standard für die Interaktion mit Agenten entwickeln und wie sich das Codex-Testgerüst in ein stabiles, clientfreundliches Protokoll überführen lässt. Wir haben erläutert, wie der App Server Codex core verfügbar macht, Clients die vollständige Agent-Schleife steuern lässt und eine Vielzahl von Oberflächen unterstützt, darunter die TUI, lokale IDE-Integrationen und die Web-Laufzeitumgebung.

Wenn das bei dir Ideen geweckt hat, Codex in deine eigenen Workflows zu integrieren, lohnt es sich, den App Server auszuprobieren. Der gesamte Quellcode liegt im Open-Source-Repo⁠(wird in einem neuen Fenster geöffnet) der Codex CLI. Teile gern dein Feedback mit und welche Features du dir wünschst. Wir freuen uns, von dir zu hören, und arbeiten weiter daran, Agenten für alle zugänglicher zu machen.