Den Codex-Harness nutzen: Wie OpenAI den App Server aufgebaut hat

• Um Codex in eigene Produkte integrieren zu können, wurde eine standardisierte App-Server-Architektur und ein JSON-RPC-Protokoll entwickelt und bereitgestellt
• Anfangs war der Ausgangspunkt ein CLI-zentrierter TUI-Harness, doch mit der Einführung des JSON-RPC-Protokolls können mehrere Clients wie IDEs, Web und lokale Apps dieselbe Agent-Loop gemeinsam nutzen
• Der App Server ist ein langlebiger Prozess, der die Codex-Core-Bibliothek hostet, und stellt dem Client die gesamte Agent-Erfahrung bereit, einschließlich Verwaltung des Thread-Lebenszyklus, Konfiguration/Authentifizierung und Tool-Ausführung
• Über die drei Gesprächs-Primitiven Item, Turn und Thread lassen sich die komplexen Interaktionen der Agent-Loop strukturieren und umfangreiche UIs aufbauen
• Derselbe Harness wird über verschiedene Oberflächen hinweg wiederverwendet, darunter VS Code, JetBrains, Xcode, Desktop-App und Web-Runtime; unterstützt werden mehrsprachige Client-Bindings für Go, Python, TypeScript, Swift und Kotlin
• Es gibt auch alternative Integrationswege wie MCP-Server, CLI-Modus und TypeScript-SDK, doch der App Server hat sich als bevorzugter Integrationsstandard etabliert
• OpenAI will den App Server als Standardweg für Codex-Integrationen beibehalten und unterstützt über das Open-Source-CLI-Repo dabei, Codex in eigene Workflows zu integrieren

---

Hintergrund des App Servers

• Anfangs war er ein pragmatischer Weg, den Codex-Harness in mehreren Produkten wiederzuverwenden, entwickelte sich aber nach und nach zu einem Standardprotokoll
• Die Codex CLI begann als TUI (Terminal User Interface), und beim Aufbau einer VS-Code-Erweiterung wurde eine Möglichkeit benötigt, denselben Harness in einer IDE-Oberfläche zu betreiben
  • Dafür mussten verschiedenste Interaktionsmuster jenseits von Request/Response unterstützt werden, etwa Workspace-Erkundung, Streaming des Reasoning-Fortschritts und Diff-Ausgaben
• Zunächst wurde versucht, Codex als MCP-Server bereitzustellen, doch es erwies sich als schwierig, die MCP-Semantik in einer für VS Code geeigneten Form beizubehalten
• Als Alternative wurde ein JSON-RPC-Protokoll eingeführt, das die TUI-Loop abbildet; damit entstand die inoffizielle erste Version des App Servers
  • Da damals nicht erwartet wurde, dass andere Clients davon abhängen würden, wurde es nicht als stabile API entworfen
• Mit der zunehmenden Verbreitung von Codex forderten interne Teams und externe Partner wie JetBrains und Xcode die Möglichkeit, den Harness in ihre eigenen Produkte einzubetten
  • Dafür musste eine Plattformoberfläche entworfen werden, auf der sich das Protokoll weiterentwickeln lässt, ohne die Abwärtskompatibilität zu verlieren

Interner Aufbau des Codex-Harness

• Codex Core ist sowohl die Bibliothek mit dem gesamten Agent-Code als auch die Runtime, die die Agent-Loop ausführt und die Persistenz eines einzelnen Codex-Threads (Gesprächs) verwaltet
• Neben der zentralen Agent-Loop gibt es drei wichtige Funktionsbereiche:
  • Thread-Lebenszyklus und Persistenz: Erstellen, Fortsetzen, Forken und Archivieren von Threads sowie das Vorhalten von Event-Aufzeichnungen, sodass Clients sich erneut verbinden und eine konsistente Timeline rendern können
  • Konfiguration und Authentifizierung: Laden von Konfigurationen, Verwalten von Standardwerten, Status von Zugangsdaten und Ausführen von Authentifizierungsabläufen wie „Mit ChatGPT anmelden“
  • Tool-Ausführung und Erweiterung: Ausführen von Shell-/Datei-Tools in einer Sandbox und Einbinden von Integrationen wie MCP-Servern und Skills, damit sie unter einem einheitlichen Richtlinienmodell an der Agent-Loop teilnehmen können

App-Server-Architektur

• Der App Server ist ein JSON-RPC-Protokoll zwischen Client und Server sowie ein langlebiger Prozess, der Codex-Core-Threads hostet
• Es gibt vier Hauptkomponenten:
  • stdio-Reader: liest Eingaben des Clients
  • Codex Message Processor: kommuniziert direkt mit jeder Core-Session, übermittelt Client-Anfragen und empfängt Updates
  • Thread Manager: startet für jeden Thread genau eine Core-Session
  • Core Thread: führt die eigentliche Agent-Loop aus
• Eine einzelne Client-Anfrage kann viele Event-Updates auslösen; diese Detailereignisse machen den Aufbau umfangreicher UIs möglich
• stdio-Reader und Codex Message Processor fungieren als Transformationsschicht, die JSON-RPC-Anfragen des Clients in Codex-Core-Operationen umsetzt und interne Event-Streams in stabile, für UIs nutzbare JSON-RPC-Benachrichtigungen überführt
• Das JSON-RPC-Protokoll zwischen Client und App Server ist vollständig bidirektional
  • Wenn der Agent Eingaben wie eine Genehmigung benötigt, kann der Server eine Anfrage initiieren und den Turn pausieren, bis der Client antwortet

Gesprächs-Primitiven

• Zentral für das API-Design der Agent-Loop ist die Erkenntnis, dass sich die Interaktion zwischen Nutzer und Agent nicht als simples Request/Response-Modell, sondern als strukturierte Folge von Arbeitsschritten entfaltet
• Drei zentrale Primitiven:

• Item

  • Die Basiseinheit von Ein- und Ausgabe in Codex
  • Sie sind typisiert, etwa als Nutzernachricht, Agentennachricht, Tool-Ausführung, Genehmigungsanfrage oder Diff
  • Expliziter Lebenszyklus: item/started → optionales item/*/delta (Streaming) → item/completed (finale Payload)
  • Clients können bei started sofort mit dem Rendering beginnen, bei delta schrittweise Updates streamen und mit completed abschließen

• Turn

  • Eine Arbeitseinheit des Agenten, die mit einer Nutzereingabe beginnt
  • Beispiel: Reicht ein Client „run tests and summarize failures“ ein, beginnt ein Turn; er endet, wenn der Agent die Ausgabe fertig erzeugt hat
  • Ein Turn umfasst eine Reihe von Items, die Zwischenschritte und Ergebnisse darstellen

• Thread

  • Ein dauerhafter Container für eine laufende Codex-Session zwischen Nutzer und Agent
  • Er enthält mehrere Turns und kann erstellt, fortgesetzt, geforkt und archiviert werden
  • Der Thread-Verlauf bleibt dauerhaft erhalten, sodass Clients sich erneut verbinden und eine konsistente Timeline rendern können

Ablauf der Client-Server-Kommunikation

• Beim Start einer Unterhaltung müssen Client und Server per initialize einen Handshake etablieren
  • Der Client sendet vor allen anderen Methoden genau eine initialize-Anfrage, die der Server per Antwort bestätigt
  • Beide Seiten einigen sich auf Protokollversionierung, Feature-Flags und Standardwerte
• Bei einer neuen Anfrage erstellt der Server zuerst einen Thread und dann einen Turn und sendet die Benachrichtigungen thread/started und turn/started
• Tool-Aufrufe werden ebenfalls als Items an den Client gesendet, und der Server kann eine Freigabe zur Ausführung anfordern
  • Bei einer Genehmigungsanfrage wird der Turn pausiert, bis der Client mit „Zulassen“ oder „Ablehnen“ antwortet
• Danach sendet der Server die Agentennachricht und beendet den Turn mit turn/completed
  • Delta-Events der Agentennachricht streamen Teile der Nachricht, bevor sie mit item/completed final abgeschlossen wird
• Wer das JSON eines vollständigen Turns ansehen möchte, kann den Befehl codex debug app-server send-message-v2 "run tests and summarize failures" ausführen

Integrationsmuster mit Clients

• Lokale Apps und IDEs

  • Als Transport dient JSON-RPC (JSONL) über stdio
  • Lokale Clients bündeln oder laden das plattformspezifische App-Server-Binary und führen es als langlebigen Unterprozess aus
  • In der VS-Code-Erweiterung und der Desktop-App werden plattformspezifische Codex-Binaries in die Distributionsartefakte aufgenommen und auf getestete Versionen fixiert
  • App-Server-Clients wurden bereits in verschiedenen Sprachen umgesetzt, darunter Go, Python, TypeScript, Swift und Kotlin
    • TypeScript: Definitionen lassen sich direkt mit dem Befehl codex app-server generate-ts erzeugen
    • Andere Sprachen: Mit codex app-server generate-json-schema wird zunächst ein JSON-Schema-Bundle erzeugt, das dann in Codegeneratoren eingespeist wird
  • Partner wie Xcode trennen Release-Zyklen, indem sie ihren Client stabil halten und jeweils auf das aktuelle App-Server-Binary zeigen
    • So lassen sich serverseitige Verbesserungen wie bessere Auto-Kompaktierung, neue Konfigurationsschlüssel und Bugfixes ausrollen, ohne auf ein Client-Release zu warten
    • Die JSON-RPC-Oberfläche bleibt abwärtskompatibel, sodass auch ältere Clients sicher mit neueren Servern kommunizieren können

• Codex Web Runtime

  • Läuft in einer Container-Umgebung
  • Worker provisionieren Container mit ausgechecktem Workspace, starten darin das App-Server-Binary und halten JSON-RPC über einen stdio-Kanal aufrecht
  • Die Web-App im Browser des Nutzers kommuniziert per HTTP und SSE mit dem Codex-Backend, um Arbeitsevents zu streamen
  • So bleibt die Browser-seitige UI leichtgewichtig und bietet zugleich eine konsistente Runtime über Desktop und Web hinweg
  • Da Web-Sitzungen kurzlebig sind, etwa durch geschlossene Tabs oder Netzunterbrechungen, hält der Server Status und Fortschritt vor
    • Selbst wenn ein Tab verschwindet, läuft die Arbeit weiter, und eine neue Sitzung kann sich leicht erneut verbinden und an der unterbrochenen Stelle fortsetzen

• Geplantes TUI-Refactoring

  • Die bestehende TUI ist ein „nativer“ Client, der im selben Prozess wie die Agent-Loop läuft und nicht das App-Server-Protokoll nutzt, sondern direkt mit Rust-Core-Typen kommuniziert
  • Geplant ist ein Refactoring der TUI, damit sie mithilfe des App Servers wie andere Clients arbeitet
    • Dadurch kann sie sich mit einem Codex-Server verbinden, der auf einer entfernten Maschine läuft
    • Der Agent wäre dann eng mit der Compute-Infrastruktur gekoppelt und könnte auch bei Energiesparmodus des Laptops oder Verbindungsabbrüchen weiterarbeiten
    • Gleichzeitig blieben lokal Live-Updates und Steuerungsmöglichkeiten erhalten

Das passende Protokoll wählen

• Der App Server ist der bevorzugte Integrationsweg, daneben gibt es aber auch Alternativen mit eingeschränkterem Funktionsumfang

• MCP-Server

  • Start mit codex mcp-server; Verbindung ist aus jedem MCP-Client möglich, der einen stdio-Server unterstützt, etwa dem OpenAI Agents SDK
  • Geeignet, wenn bereits ein MCP-basierter Workflow existiert und Codex als aufrufbares Tool genutzt werden soll
  • Nachteil: Es steht nur das zur Verfügung, was MCP anbietet; Codex-spezifische Interaktionen wie Diff-Updates lassen sich womöglich nicht nahtlos abbilden

• Portable Schnittstellen

  • Geeignet, wenn eine einheitliche Abstraktion über mehrere Modellanbieter und Runtimes hinweg benötigt wird
  • Nachteil: Oft läuft es auf die gemeinsame kleinste Teilmenge an Funktionen hinaus, wodurch sich umfangreiche Interaktionen schwer ausdrücken lassen
  • Dieser Bereich entwickelt sich schnell weiter; es ist zu erwarten, dass mehr gemeinsame Standards entstehen, etwa agentskills.io

• App Server

  • Stellt den vollständigen Codex-Harness als stabilen, UI-freundlichen Event-Stream bereit
  • Neben den vollen Fähigkeiten der Agent-Loop sind auch unterstützende Funktionen wie Anmeldung mit ChatGPT, Model-Erkundung und Konfigurationsverwaltung nutzbar
  • Hauptaufwand: Es müssen clientseitige JSON-RPC-Bindings in der verwendeten Sprache aufgebaut werden
    • Wenn JSON-Schema und Dokumentation bereitstehen, kann Codex viele komplexe Aufgaben übernehmen; zahlreiche Teams konnten ihre Integration schnell umsetzen

• CLI-Modus

  • Ein leichtgewichtiger, skriptartiger Modus für Einmalaufgaben und CI-Ausführung
  • Führt einen einzelnen Befehl nicht interaktiv aus, streamt strukturierte Ausgaben und endet mit einem klaren Erfolgs-/Fehlersignal
  • Eignet sich gut für Automatisierung und Pipelines

• TypeScript-SDK

  • Eine TypeScript-Bibliothek, mit der sich ein lokaler Codex-Agent programmatisch in der eigenen Anwendung steuern lässt
  • Geeignet, wenn eine native Bibliotheksschnittstelle benötigt wird, ohne einen separaten JSON-RPC-Client zu bauen
  • Es erschien vor dem App Server, unterstützt weniger Sprachen und deckt einen kleineren Bereich ab
  • Je nach Interesse der Entwickler könnten künftig weitere SDKs angeboten werden, die das App-Server-Protokoll kapseln

Ausblick

• Der App Server legt Codex Core offen, ermöglicht Clients den Betrieb der vollständigen Agent-Loop und unterstützt eine breite Palette von Oberflächen wie TUI, lokale IDE-Integrationen und Web-Runtimes
• Der gesamte Quellcode ist im Open-Source-Repository der Codex CLI veröffentlicht
• Funktionswünsche und Feedback sind willkommen; geplant sind kontinuierliche Verbesserungen, damit sich Agenten noch einfacher nutzen lassen

• Offizielle Dokumentation zum Codex App Server