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

Codex App Server

Integriere Codex mit dem App-Server-Protokoll in dein Produkt

Über den Codex App Server stellt Codex Clients wie der Codex-Erweiterung für VS Code umfangreiche Funktionen bereit. Nutze diese Schnittstelle, wenn du Authentifizierung, Gesprächsverläufe, Genehmigungen und einen Stream von Agentenereignissen in dein eigenes Produkt integrieren möchtest. Der Quellcode ist im Codex-Repository auf GitHub verfügbar (openai/codex/codex-rs/app-server). Eine vollständige Liste der quelloffenen Codex-Komponenten findest du auf der Seite Open Source.

Wenn du Jobs automatisierst oder Codex in CI ausführst, verwende stattdessen das Codex SDK.

Terminaloberfläche der CLI verbinden

Im Remote-Modus kannst du den App Server auf einem Rechner ausführen und dich von einem anderen Rechner aus über die Terminaloberfläche der Codex CLI damit verbinden. Starte einen WebSocket-Listener:

codex app-server --listen ws://127.0.0.1:4500

Verbinde anschließend die Terminaloberfläche:

codex --remote ws://127.0.0.1:4500

Konfiguriere für eine nicht lokale Verbindung die WebSocket-Authentifizierung und sichere die Verbindung mit TLS. Speichere das Bearer-Token in einer Umgebungsvariablen und übergib deren Namen, damit das Token selbst nicht in der Befehlszeile steht:

export CODEX_REMOTE_TOKEN="$(cat "$HOME/.codex/app-server-token")"
codex --remote wss://remote-host:4500 \
  --remote-auth-token-env CODEX_REMOTE_TOKEN

Die Option --remote akzeptiert Endpunkte der Form ws://, wss://, unix:// und unix://PATH. Verwende unverschlüsselte WebSockets nur für localhost oder für Verbindungen mit SSH-Portweiterleitung.

Einen Remote-Host für Code Mode verbinden

Standardmäßig startet der App Server einen lokalen Host für Code Mode. Damit Threads im selben App-Server-Prozess einen Remote-Host gemeinsam nutzen können, übergib dessen gRPC-Endpunkt für HTTP/2 an --code-mode-host.

codex app-server --code-mode-host https://code-mode.example.com

Verwende für einen Remote-Host HTTPS, um Toolargumente und Ergebnisse zu schützen. Verwende HTTP nur über die Loopback-Schnittstelle oder einen sicheren Tunnel. Gib in der URL den Hostnamen und optional einen Port an. Lass Zugangsdaten, Pfade, Abfragezeichenfolgen und Fragmente weg. Mit --listen konfigurierst du die separate Verbindung der Clients zum App Server.

Protokoll

Wie MCP unterstützt codex app-server die Kommunikation in beide Richtungen über JSON-RPC-2.0-Nachrichten. Bei der Übertragung entfällt der Header "jsonrpc":"2.0".

Unterstützte Transportarten:

  • stdio (--listen stdio://, Standard): JSON mit einem Eintrag pro Zeile (JSONL).
  • websocket (--listen ws://IP:PORT, experimentell und ohne Support): eine JSON-RPC-Nachricht pro WebSocket-Textframe.
  • Unix-Socket (--listen unix:// oder --listen unix://PATH): WebSocket-Verbindungen über den standardmäßigen Steuerungssocket des Codex App Server oder einen eigenen Unix-Socket-Pfad. Der Verbindungsaufbau erfolgt über den üblichen HTTP-Upgrade-Handshake.
  • off (--listen off): stellt keinen lokalen Transport bereit.

Wenn du den Server mit --listen ws://IP:PORT ausführst, beantwortet derselbe Listener auch einfache HTTP-Anfragen zur Zustandsprüfung:

  • GET /readyz gibt 200 OK zurück, sobald der Listener neue Verbindungen annimmt.
  • GET /healthz gibt 200 OK zurück, wenn die Anfrage keinen Origin-Header enthält.
  • Anfragen mit einem Origin-Header weist der Server mit 403 Forbidden zurück.

Der WebSocket-Transport ist experimentell und wird ohne Support bereitgestellt. Lokale Listener wie ws://127.0.0.1:PORT eignen sich für localhost und SSH-Portweiterleitungen. Während der Einführung lassen WebSocket-Listener außerhalb der Loopback-Schnittstelle standardmäßig Verbindungen ohne Authentifizierung zu. Konfiguriere die WebSocket-Authentifizierung, bevor du einen solchen Listener für den Remote-Zugriff freigibst.

Unterstützte Optionen für die WebSocket-Authentifizierung:

  • --ws-auth capability-token --ws-token-file /absolute/path
  • --ws-auth capability-token --ws-token-sha256 HEX
  • --ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path

Für signierte Bearer-Token kannst du zusätzlich --ws-issuer, --ws-audience und --ws-max-clock-skew-seconds festlegen. Clients übermitteln die Zugangsdaten beim WebSocket-Handshake als Authorization: Bearer <token>. Der App Server verlangt die Authentifizierung vor dem JSON-RPC-Aufruf initialize.

Verwende vorzugsweise --ws-token-file, damit du Bearer-Token nicht im Klartext auf der Befehlszeile übergeben musst. Verwende --ws-token-sha256 nur, wenn der Client das ursprüngliche Token mit hoher Entropie in einem separaten lokalen Geheimnisspeicher aufbewahrt. Der Hash dient nur zur Prüfung. Clients benötigen weiterhin das ursprüngliche Token.

Im WebSocket-Modus verwendet der App Server Warteschlangen mit begrenzter Kapazität. Ist die Warteschlange für eingehende Anfragen voll, weist der Server neue Anfragen mit dem JSON-RPC-Fehlercode -32001 und der Meldung "Server overloaded; retry later." zurück. Clients sollten die Anfrage erneut senden und dabei die Wartezeit exponentiell erhöhen und zufällig variieren.

Nachrichtenschema

Anfragen enthalten method, params und id.

Die Beispiele verwenden GPT-6.1 Sol. Das angemeldete Konto oder der Workspace benötigt Zugriff auf dieses Modell. Wähle bei Bedarf mit model/list ein verfügbares Modell aus.

{ "method": "thread/start", "id": 10, "params": { "model": "gpt-6.1-sol" } }

Antworten geben die id zusammen mit result oder error zurück:

{ "id": 10, "result": { "thread": { "id": "thr_123" } } }
{ "id": 10, "error": { "code": 123, "message": "Something went wrong" } }

Benachrichtigungen enthalten keine id und verwenden nur method und params:

{ "method": "turn/started", "params": { "turn": { "id": "turn_456" } } }

Über die CLI kannst du ein TypeScript-Schema oder ein Paket mit JSON-Schemas generieren. Die generierten Dateien entsprechen genau der Codex-Version, mit der du den Befehl ausführst:

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

Erste Schritte

  1. Starte den Server mit codex app-server (Standardtransport über stdio), codex app-server --listen ws://127.0.0.1:4500 (WebSocket über TCP) oder codex app-server --listen unix:// (standardmäßiger Unix-Socket).
  2. Verbinde einen Client über den ausgewählten Transport. Sende dann initialize und anschließend die Benachrichtigung initialized.
  3. Starte einen Thread und einen Turn. Lies anschließend fortlaufend die Benachrichtigungen aus dem aktiven Transportstream.

Beispiel (Node.js / TypeScript):

import { spawn } from "node:child_process";
import readline from "node:readline";
const proc = spawn("codex", ["app-server"], {
  stdio: ["pipe", "pipe", "inherit"],
});
const rl = readline.createInterface({ input: proc.stdout });
const send = (message: unknown) => {
  proc.stdin.write(`${JSON.stringify(message)}\n`);
};
let threadId: string | null = null;
rl.on("line", (line) => {
  const msg = JSON.parse(line) as any;
  console.log("server:", msg);
  if (msg.id === 0 && msg.result) {
    send({ method: "initialized", params: {} });
    send({
      method: "thread/start",
      id: 1,
      params: { model: "gpt-6.1-sol" },
    });
  }
  if (msg.method === "turn/completed") {
    if (msg.params?.turn?.status !== "completed") {
      console.error(msg.params?.turn?.error ?? "The turn did not complete.");
      process.exitCode = 1;
    }
    proc.stdin.end();
    rl.close();
  }
  if (msg.error) {
    console.error(msg.error);
    process.exitCode = 1;
    proc.stdin.end();
    rl.close();
  }
  if (msg.id === 1 && msg.result?.thread?.id && !threadId) {
    threadId = msg.result.thread.id;
    send({
      method: "turn/start",
      id: 2,
      params: {
        threadId,
        input: [{ type: "text", text: "Summarize this repo." }],
      },
    });
  }
});
send({
  method: "initialize",
  id: 0,
  params: {
    clientInfo: {
      name: "my_product",
      title: "My Product",
      version: "0.1.0",
    },
  },
});
proc.on("error", (error) => {
  console.error(error);
  process.exitCode = 1;
  rl.close();
});
proc.on("exit", (code) => {
  if (code !== 0) process.exitCode = code ?? 1;
});

Grundbegriffe

  • Thread: Ein Gespräch zwischen einer Person und dem Codex-Agenten. Ein Thread enthält Turns.
  • Turn: Eine einzelne Nutzeranfrage und die anschließende Arbeit des Agenten. Ein Turn enthält Elemente und liefert laufend Aktualisierungen.
  • Element: Eine einzelne Ein- oder Ausgabe, etwa eine Nachricht der Person oder des Agenten, eine Befehlsausführung, eine Dateiänderung oder ein Toolaufruf.

Mit den Thread-APIs kannst du Gespräche erstellen, auflisten oder archivieren. Mit den Turn-APIs steuerst du das Gespräch. Über Turn-Benachrichtigungen verfolgst du den Fortschritt im Stream.

Ablauf im Überblick

  • Einmal pro Verbindung initialisieren: Sende unmittelbar nach dem Öffnen der Transportverbindung eine initialize-Anfrage mit den Metadaten deines Clients und anschließend initialized. Vor diesem Handshake weist der Server alle anderen Anfragen über diese Verbindung zurück.
  • Thread starten oder fortsetzen: Rufe thread/start für ein neues Gespräch auf, thread/resume, um ein bestehendes fortzusetzen, oder thread/fork, um den Verlauf unter einer neuen Thread-ID zu forken.
  • Turn beginnen: Rufe turn/start mit der gewünschten threadId und der Nutzereingabe auf. Über optionale Felder kannst du das Modell, das Arbeitsverzeichnis und die Sandbox-Richtlinie überschreiben.
  • Aktiven Turn steuern: Rufe turn/steer auf, um dem laufenden Turn weitere Nutzereingaben hinzuzufügen, ohne einen neuen Turn zu erstellen.
  • Ereignisse im Stream lesen: Lies nach turn/start weiter die Benachrichtigungen auf stdout, darunter thread/archived, thread/unarchived, item/started, item/completed, item/agentMessage/delta, Fortschrittsmeldungen von Tools und weitere Aktualisierungen.
  • Turn abschließen: Der Server sendet turn/completed mit dem endgültigen Status, sobald das Modell fertig ist oder der Turn durch turn/interrupt abgebrochen wurde.

Initialisierung

Clients müssen pro Transportverbindung genau eine initialize-Anfrage senden, bevor sie über diese Verbindung andere Methoden aufrufen. Anschließend bestätigen sie die Initialisierung mit der Benachrichtigung initialized. Bei Anfragen vor der Initialisierung meldet der Server Not initialized. Wiederholte initialize-Aufrufe über dieselbe Verbindung liefern Already initialized.

Der Server gibt die User-Agent-Zeichenfolge zurück, mit der er sich gegenüber vorgelagerten Diensten ausweist. Die Werte platformFamily und platformOs beschreiben die Zielplattform der Laufzeit. Gib in clientInfo an, um welche Integration es sich handelt.

initialize.params.capabilities unterstützt außerdem folgende Clientfunktionen:

  • optOutNotificationMethods gibt die exakten Namen der Benachrichtigungsmethoden an, die der Server für diese Verbindung unterdrücken soll. Der Abgleich unterstützt weder Platzhalter noch Präfixe. Unbekannte Namen sind zulässig und werden ignoriert.
  • requestAttestation aktiviert die vom Server initiierte Anfrage attestation/generate. Desktop-Hosts, die eine Attestierung für vorgelagerte Dienste bereitstellen, antworten mit einem opaken Wert der Form { "token": "..." }.
  • mcpServerOpenaiFormElicitation erlaubt nachgelagerten MCP-Servern, die erweiterte Formularvariante von OpenAI für mcpServer/elicitation/request zu senden.

Wichtig: Gib in clientInfo.name an, wie die Plattform für Compliance-Protokolle von OpenAI deinen Client identifizieren soll. Wenn du eine neue Codex-Integration für den Einsatz in Unternehmen entwickelst, wende dich an OpenAI, damit dein Client in die Liste bekannter Clients aufgenommen wird. Weitere Informationen findest du in der Referenz zu Codex-Protokollen.

Beispiel aus der Codex-Erweiterung für VS Code:

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "codex_vscode",
      "title": "Codex VS Code Extension",
      "version": "0.1.0"
    }
  }
}

Beispiel mit deaktivierten Benachrichtigungen:

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true,
      "optOutNotificationMethods": ["thread/started", "item/agentMessage/delta"]
    }
  }
}

Experimentelle API aktivieren

Bestimmte Methoden und Felder des App Server sind nur verfügbar, wenn der Client experimentalApi aktiviert.

  • Lass capabilities weg oder setze experimentalApi auf false, um ausschließlich die stabile API zu verwenden. Der Server weist experimentelle Methoden und Felder dann zurück.
  • Setze capabilities.experimentalApi auf true, um experimentelle Methoden und Felder zu aktivieren.
{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true
    }
  }
}

Sendet ein Client eine experimentelle Methode oder ein experimentelles Feld, ohne die experimentelle API aktiviert zu haben, weist der App Server die Anfrage mit folgender Meldung zurück:

<descriptor> requires experimentalApi capability

API-Überblick

  • thread/start erstellt einen Thread, sendet thread/started und abonniert für deine Verbindung automatisch die Turn- und Elementereignisse dieses Threads.
  • thread/resume öffnet einen bestehenden Thread anhand seiner ID erneut, sodass spätere Aufrufe von turn/start ihn fortsetzen.
  • thread/fork forkt einen Thread unter einer neuen ID, indem es den gespeicherten Verlauf kopiert. Übergib lastTurnId, um den Verlauf bis einschließlich dieses Turns zu kopieren und spätere Turns auszulassen, oder ephemeral: true für einen Fork im Arbeitsspeicher. Die Methode sendet thread/started für den neuen Thread. Zurückgegebene Threads enthalten forkedFromId, sofern verfügbar.
  • thread/read liest gespeicherte Thread-Metadaten anhand der ID, ohne den Thread fortzusetzen. Lade den Verlauf mit thread/turns/list und thread/items/list. Die zurückgegebenen thread-Objekte enthalten den Laufzeitstatus status.
  • thread/list liefert gespeicherte Threads und ihren Laufzeitstatus seitenweise. Weitere Informationen findest du im Abschnitt Paginierung und Filter.
  • thread/turns/list liest die gespeicherten Turns eines Threads seitenweise, ohne ihn fortzusetzen. itemsView legt fest, ob die Elemente der Turns ausgelassen, zusammengefasst oder vollständig geladen werden.
  • thread/items/list liest gespeicherte Thread-Elemente seitenweise, optional beschränkt auf eine turnId. Der aktive Thread-Speicher muss die Paginierung von Elementen unterstützen.
  • thread/loaded/list listet die IDs der aktuell im Arbeitsspeicher geladenen Threads auf.
  • thread/name/set setzt oder aktualisiert den sichtbaren Namen eines geladenen Threads oder einer gespeicherten Sitzungsaufzeichnung und sendet thread/name/updated.
  • thread/goal/set legt das Ziel eines Threads fest und sendet thread/goal/updated.
  • thread/goal/get liest das aktuelle Ziel eines Threads.
  • thread/goal/clear entfernt das Ziel eines Threads und sendet thread/goal/cleared.
  • thread/metadata/update aktualisiert die für einen Thread gespeicherten Git-Metadaten.
  • thread/archive verschiebt die Protokolldatei eines Threads ins Archivverzeichnis und versucht, auch die noch nicht archivierten Protokolle aller daraus erzeugten Threads zu archivieren. Bei Erfolg gibt die Methode {} zurück und sendet für jeden archivierten Thread thread/archived.
  • thread/delete löscht einen gespeicherten aktiven oder archivierten Thread und alle daraus erzeugten Threads dauerhaft. Bei Erfolg gibt die Methode {} zurück und sendet für jeden gelöschten Thread thread/deleted.
  • thread/unsubscribe beendet das Abonnement dieser Verbindung für Turn- und Elementereignisse des Threads. War dies das letzte Abonnement, entlädt der Server den Thread nach einer Frist ohne Aktivität und ohne Abonnements und sendet thread/closed.
  • thread/unarchive verschiebt eine archivierte Thread-Aufzeichnung zurück in das Verzeichnis der aktiven Sitzungen, gibt den wiederhergestellten thread zurück und sendet thread/unarchived.
  • thread/status/changed ist eine Benachrichtigung, die der Server sendet, wenn sich der Laufzeitwert status eines geladenen Threads ändert.
  • thread/compact/start startet die Kontextverdichtung für den Gesprächsverlauf eines Threads. Die Methode gibt sofort {} zurück und meldet den Fortschritt über turn/*- und item/*-Benachrichtigungen.
  • thread/shellCommand führt einen von der nutzenden Person veranlassten Shell-Befehl für einen Thread aus. Der Befehl läuft außerhalb der Sandbox mit Vollzugriff und übernimmt die Sandbox-Richtlinie des Threads nicht.
  • thread/backgroundTerminals/clean stoppt alle laufenden Hintergrundterminals eines Threads (experimentell, erfordert capabilities.experimentalApi).
  • thread/backgroundTerminals/list listet die laufenden Hintergrundterminals eines geladenen Threads auf (experimentell, erfordert capabilities.experimentalApi).
  • thread/backgroundTerminals/terminate beendet ein laufendes Hintergrundterminal anhand der vom App Server vergebenen processId (experimentell, erfordert capabilities.experimentalApi).
  • thread/revert entfernt einen angegebenen Turn und alle späteren Turns aus dem Verlauf eines dauerhaft gespeicherten, paginierten Threads. Die Methode gibt aktualisierte Metadaten und Cursor für den Verlauf zurück und sendet anschließend thread/reverted.
  • turn/start fügt einem Thread Nutzereingaben oder eine eigenständige Toolausgabe hinzu und startet die Generierung durch Codex. Die Antwort enthält den anfänglichen turn, weitere Ereignisse folgen im Stream. Für collaborationMode bedeutet settings.developer_instructions: null „die integrierten Anweisungen für den ausgewählten Modus verwenden“.
  • thread/inject_items fügt dem für das Modell sichtbaren Verlauf eines geladenen Threads unverarbeitete Elemente der Responses API hinzu, ohne einen Nutzer-Turn zu starten.
  • turn/steer fügt dem laufenden Turn eines Threads Nutzereingaben hinzu und gibt die akzeptierte turnId zurück.
  • turn/interrupt fordert den Abbruch eines laufenden Turns an. Bei Erfolg lautet die Antwort {}, und der Turn endet mit status: "interrupted".
  • review/start startet das Code Review durch Codex für einen Thread und sendet Elemente vom Typ enteredReviewMode und exitedReviewMode.
  • command/exec führt einen einzelnen Befehl in der Sandbox des Servers aus, ohne einen Thread oder Turn zu starten.
  • command/exec/write schreibt Bytes in stdin einer laufenden command/exec-Sitzung oder schließt stdin.
  • command/exec/resize ändert die Terminalgröße einer laufenden command/exec-Sitzung mit PTY.
  • command/exec/terminate stoppt eine laufende command/exec-Sitzung.
  • command/exec/outputDelta (Benachrichtigung) liefert Base64-kodierte Abschnitte von stdout und stderr aus einer command/exec-Sitzung mit Streaming.
  • process/spawn startet explizit eine Prozesssitzung außerhalb der Codex-Sandbox (experimentell, erfordert capabilities.experimentalApi).
  • process/writeStdin schreibt Bytes in stdin einer laufenden process/spawn-Sitzung oder schließt stdin (experimentell).
  • process/resizePty ändert die Terminalgröße einer laufenden Prozesssitzung mit PTY (experimentell).
  • process/kill beendet eine laufende Prozesssitzung (experimentell).
  • process/outputDelta und process/exited (Benachrichtigungen) liefern die laufende Prozessausgabe und den Beendigungsstatus (experimentell).
  • model/list listet verfügbare Modelle auf (mit includeHidden: true auch Einträge mit hidden: true). Jeder Eintrag enthält Optionen für den Reasoning-Aufwand, optional upgrade sowie inputModalities.
  • modelProvider/capabilities/read liest die vom Anbieter vorgegebenen Funktionsgrenzen für Kombinationen aus Modell und Anbieter.
  • experimentalFeature/list listet Feature-Flags mit Metadaten zur Entwicklungsphase auf und unterstützt cursorbasierte Paginierung.
  • experimentalFeature/enablement/set aktualisiert Laufzeiteinstellungen im Arbeitsspeicher für unterstützte Funktionsschlüssel wie apps und plugins.
  • environment/info verbindet sich mit einer konfigurierten Ausführungsumgebung und gibt deren Shell und Standardarbeitsverzeichnis zurück (experimentell).
  • permissionProfile/list listet Berechtigungsprofile in der Betaphase auf und gibt an, ob die geltenden Vorgaben sie zulassen. Die Methode unterstützt cursorbasierte Paginierung.
  • collaborationMode/list listet Voreinstellungen für den Zusammenarbeitsmodus auf (experimentell, ohne Paginierung).
  • skills/list listet Skills für einen oder mehrere cwd-Werte auf und unterstützt forceReload sowie optional perCwdExtraUserRoots.
  • skills/extraRoots/set ersetzt auf Prozessebene die zusätzlichen Stammverzeichnisse für die Suche nach eigenständigen Skills, ohne die Änderung dauerhaft zu speichern.
  • skills/changed (Benachrichtigung) meldet Änderungen an überwachten lokalen Skill-Dateien.
  • hooks/list listet die gefundenen Lebenszyklus-Hooks für einen oder mehrere cwd-Werte auf.
  • marketplace/add fügt einen Remote-Marketplace für Plugins hinzu und speichert ihn in der persönlichen Marketplace-Konfiguration.
  • marketplace/remove entfernt einen konfigurierten Marketplace und, sofern vorhanden, dessen installiertes Stammverzeichnis.
  • marketplace/upgrade aktualisiert einen konfigurierten Git-Marketplace. Ohne Marketplace-Namen aktualisiert die Methode alle konfigurierten Git-Marketplaces.
  • plugin/list befindet sich in Entwicklung. Die Methode listet erkannte Plugin-Marketplaces und den Plugin-Status auf, einschließlich Metadaten zu Installations- und Authentifizierungsrichtlinien, Ladefehlern der Marketplaces, IDs hervorgehobener Plugins sowie Metadaten zu lokalen Quellen, Git-Quellen, Paketregistrys und Remote-Quellen. Zusammenfassungen können die Remote-Version version, die lokale Version localVersion, strukturierte Symbole für helle und dunkle Oberflächen sowie installPolicySource enthalten. Bei aktuellen Remote-Einträgen kann der Wert null, WORKSPACE_SETTING oder IMPLICIT_CANONICAL_APP sein. Rufe diese Methode noch nicht aus Clients im Produktivbetrieb auf.
  • plugin/read befindet sich in Entwicklung. Die Methode liest ein Plugin anhand seines Namens und des Marketplace-Pfads oder Remote-Marketplace-Namens. Das Ergebnis enthält mitgelieferte Skills, Apps, Namen von MCP-Servern und bei Remote-Plugins eine shareUrl, sofern der Remote-Katalog eine bereitstellt. Rufe diese Methode noch nicht aus Clients im Produktivbetrieb auf.
  • plugin/install befindet sich in Entwicklung und installiert ein Plugin über einen Marketplace-Pfad oder einen Remote-Marketplace-Namen. Rufe diese Methode noch nicht aus Clients im Produktivbetrieb auf.
  • plugin/uninstall befindet sich in Entwicklung und deinstalliert ein installiertes Plugin. Rufe diese Methode noch nicht aus Clients im Produktivbetrieb auf.
  • plugin/skill/read liest bei Bedarf den Markdown-Text eines Remote-Plugin-Skills anhand von Remote-Marketplace, Plugin-ID und Skill-Namen.
  • app/installed liest den Laufzeitstatus installierter Apps und gibt für jede App an, ob sie effektiv aktiviert und aufrufbar ist.
  • app/list listet verfügbare Apps (Konnektoren) seitenweise auf und gibt an, ob sie zugänglich und aktiviert sind.
  • app/read ruft für bestimmte App-IDs Metadaten und optional Toolzusammenfassungen zur Anzeige ab.
  • skills/config/write aktiviert oder deaktiviert Skills anhand ihres Pfads.
  • mcpServer/oauth/login startet eine OAuth-Anmeldung für einen konfigurierten MCP-Server. Öffne die zurückgegebene HTTP- oder HTTPS-Adresse authorizationUrl und ordne anhand der loginId die zugehörige Benachrichtigung mcpServer/oauthLogin/completed zu.
  • tool/requestUserInput stellt der nutzenden Person für einen Toolaufruf eine bis drei kurze Fragen (experimentell). Mit isOther kann eine Frage eine freie Antwort erlauben.
  • mcpServer/elicitation/request (Serveranfrage) fordert vom Client strukturierte Formulareingaben oder die Bestätigung eines vom MCP-Server angeforderten URL-basierten Ablaufs an.
  • item/permissions/requestApproval (Serveranfrage) fordert den Client auf, eine Teilmenge der Netzwerk- oder Dateisystemberechtigungen zu gewähren, die das integrierte Tool request_permissions angefordert hat.
  • config/mcpServer/reload lädt die MCP-Serverkonfiguration erneut vom Datenträger und reiht eine Aktualisierung für geladene Threads ein.
  • mcpServerStatus/list listet MCP-Server, Tools, Ressourcen und den Authentifizierungsstatus auf (Paginierung mit Cursor und Limit). Verwende detail: "full" für alle Daten oder detail: "toolsAndAuthOnly", um Ressourcen auszulassen. Beide Modi liefern die vom Server gemeldeten serverCapabilities, vor erfolgreicher Initialisierung den Wert null. Übergib serverName, um einen einzelnen Server abzufragen. Mit threadId nutzt die Anfrage die bestehende MCP-Verbindung dieses Threads.
  • mcpServer/resource/read liest eine einzelne MCP-Ressource über einen initialisierten MCP-Server.
  • mcpServer/tool/call ruft ein Tool auf einem für den Thread konfigurierten MCP-Server auf.
  • mcpServer/startupStatus/updated (Benachrichtigung) meldet Änderungen am Startstatus eines konfigurierten MCP-Servers für einen geladenen Thread.
  • windowsSandbox/readiness prüft, ob die Windows-Sandbox bereit ist. Lautet das Ergebnis updateRequired, rufe windowsSandbox/setupStart auf und warte auf windowsSandbox/setupCompleted.
  • feedback/upload übermittelt einen Feedbackbericht mit Klassifizierung, optionaler Begründung und optionalen Protokollen sowie der Gesprächs-ID. Über extraLogFiles sind zusätzliche Anhänge möglich.
  • config/read liest die wirksame Konfiguration vom Datenträger, nachdem die Konfigurationsebenen zusammengeführt wurden.
  • externalAgentConfig/detect ermittelt mit includeHome und optional cwds, welche Artefakte externer Agenten sich migrieren lassen. Jeder gefundene Eintrag enthält cwd (null für das Home-Verzeichnis).
  • externalAgentConfig/import migriert ausgewählte Artefakte externer Agenten. Übergib dafür explizit migrationItems mit cwd (null für das Home-Verzeichnis). Unterstützt werden Konfigurationen, Skills, AGENTS.md, Plugins, MCP-Serverkonfigurationen, Subagenten, Hooks, Befehle und Sitzungen. Bei nicht leeren Importen meldet der Server den Fortschritt mit externalAgentConfig/import/progress und den Abschluss mit externalAgentConfig/import/completed. Plugin- und Sitzungsimporte können asynchron abgeschlossen werden.
  • config/value/write schreibt einen einzelnen Konfigurationsschlüssel samt Wert in die persönliche config.toml auf dem Datenträger.
  • config/batchWrite schreibt mehrere Konfigurationsänderungen atomar in die persönliche config.toml auf dem Datenträger.
  • configRequirements/read liest Vorgaben aus requirements.toml, aus MDM oder aus beiden Quellen, darunter Zulassungslisten und festgelegte featureRequirements. Clients mit aktiviertem experimentalApi können auch verwaltete Netzwerkanforderungen lesen.
  • fs/readFile, fs/writeFile, fs/createDirectory, fs/getMetadata, fs/readDirectory, fs/remove, fs/copy, fs/watch, fs/unwatch und fs/changed (Benachrichtigung) arbeiten über die Dateisystem-API v2 des App Server mit absoluten Pfaden.

Plugin-Zusammenfassungen enthalten einen Union-Typ source. Lokale Plugins liefern { "type": "local", "path": ... }, Git-basierte Marketplace-Einträge { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }, Einträge aus Paketregistrys { "type": "npm", "package": ..., "version": ..., "registry": ... } und Remote-Katalogeinträge { "type": "remote" }. Für ausschließlich remote verfügbare Katalogeinträge kann PluginMarketplaceEntry.path den Wert null haben. Übergib beim Lesen oder Installieren dieser Plugins remoteMarketplaceName anstelle von marketplacePath.

Modelle

Modelle auflisten (model/list)

Rufe model/list auf, um in der Modellauswahl die verfügbaren Modelle und die jeweiligen Stufen für den Reasoning-Aufwand anzuzeigen. Übergib modelProvider, um die Modelle eines bestimmten konfigurierten Anbieters aufzulisten. Ohne diese Angabe verwendet der Server den beim Serverstart ausgewählten Standardanbieter.

Die folgende Antwort zeigt den Aufbau. Welche Modelle, Stufen für den Reasoning-Aufwand und Standardwerte verfügbar sind, hängt vom Client und Konto ab. Verwende die zurückgegebenen Werte, statt die Beispielwerte fest zu hinterlegen.

{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }
{ "id": 6, "result": {
  "data": [{
    "id": "gpt-6.1-sol",
    "model": "gpt-6.1-sol",
    "displayName": "GPT-6.1 Sol",
    "hidden": false,
    "defaultReasoningEffort": "medium",
    "supportedReasoningEfforts": [{
      "reasoningEffort": "medium",
      "description": "Balances speed and reasoning depth for everyday tasks"
    }],
    "inputModalities": ["text", "image"],
    "supportsPersonality": false,
    "isDefault": true
  }],
  "nextCursor": null
} }

Jeder Modelleintrag kann folgende Felder enthalten:

  • supportedReasoningEfforts enthält die vom Modell unterstützten Stufen für den Reasoning-Aufwand.
  • defaultReasoningEffort gibt den empfohlenen Standardwert für den Reasoning-Aufwand in Clients an.
  • upgrade enthält optional die ID des empfohlenen Nachfolgemodells für Migrationshinweise in Clients.
  • upgradeInfo enthält optionale Upgrade-Metadaten für Migrationshinweise in Clients.
  • hidden gibt an, ob das Modell in der standardmäßigen Auswahlliste ausgeblendet ist.
  • inputModalities enthält die unterstützten Eingabetypen des Modells, etwa text und image.
  • supportsPersonality ist ein veraltetes Kompatibilitätsfeld und hat immer den Wert false. Modelle unterstützen die Auswahl einer Persönlichkeit nicht mehr.
  • isDefault gibt an, ob das Modell als Standard empfohlen wird.

Gibst du für modelProvider einen unbekannten Anbieter an, gibt der Server den Fehler -32600 zurück. Dabei hat data.type den Wert modelProviderNotConfigured. Erfüllt der ausgewählte Anbieter die verwalteten Vorgaben nicht mehr, gibt model/list den Fehler -32600 zurück und fordert den Client auf, Codex neu zu starten.

Standardmäßig liefert model/list nur Modelle, die in der Auswahl sichtbar sind. Setze includeHidden: true, wenn du die vollständige Liste benötigst und im Client anhand von hidden filtern möchtest.

Fehlt inputModalities wie in älteren Modellkatalogen, verwende aus Gründen der Abwärtskompatibilität ["text", "image"] als Wert.

Experimentelle Funktionen auflisten (experimentalFeature/list)

Über diesen Endpunkt kannst du Feature-Flags mit ihren Metadaten und ihrer Entwicklungsphase abrufen:

{ "method": "experimentalFeature/list", "id": 7, "params": { "limit": 20 } }
{ "id": 7, "result": {
  "data": [{
    "name": "unified_exec",
    "stage": "beta",
    "displayName": "Unified exec",
    "description": "Use the unified PTY-backed execution tool.",
    "announcement": "Beta rollout for improved command execution reliability.",
    "enabled": false,
    "defaultEnabled": false
  }],
  "nextCursor": null
} }

stage kann beta, underDevelopment, stable, deprecated oder removed sein. Bei Flags außerhalb der Betaphase können displayName, description und announcement den Wert null haben.

Ausführungsumgebung prüfen (experimentell)

Verwende environment/info, um eine konfigurierte Remote-Umgebung zu prüfen, bevor du dort mit der Arbeit beginnst. Die Methode erfordert capabilities.experimentalApi = true.

{ "method": "environment/info", "id": 8, "params": { "environmentId": "devbox" } }
{ "id": 8, "result": {
  "shell": { "name": "zsh", "path": "/bin/zsh" },
  "cwd": "file:///workspace/project"
} }

cwd kann null sein. Ist ein Wert vorhanden, handelt es sich um einen kanonischen file:-URI in der nativen Pfadsyntax der Umgebung. Bei unbekannten Umgebungs-IDs sowie Verbindungs- oder Protokollfehlern schlägt die Anfrage fehl.

Threads

  • thread/read liest gespeicherte Thread-Metadaten, ohne den Thread zu abonnieren.
  • thread/turns/list liest den gespeicherten Turn-Verlauf eines Threads seitenweise, ohne ihn fortzusetzen. Mit itemsView legst du fest, ob die Elemente der Turns ausgelassen, zusammengefasst oder vollständig geladen werden.
  • thread/items/list liest gespeicherte Thread-Elemente seitenweise, optional beschränkt auf einen Turn.
  • thread/list liefert gespeicherte Threads seitenweise. Verwende sectionId, um die Threads eines Abschnitts aufzulisten, oder excludedThreadIds, um bereits angezeigte Threads auszulassen.
  • thread/loaded/list gibt die IDs der aktuell im Arbeitsspeicher geladenen Threads zurück.
  • thread/archive verschiebt das gespeicherte JSONL-Protokoll des Threads ins Archivverzeichnis und versucht, auch die noch nicht archivierten Protokolle aller daraus erzeugten Threads zu archivieren.
  • thread/delete löscht einen gespeicherten aktiven oder archivierten Thread und die daraus erzeugten Threads dauerhaft.
  • thread/metadata/update aktualisiert das für einen Thread gespeicherte Feld gitInfo.
  • thread/unsubscribe beendet das Abonnement der aktuellen Verbindung für einen geladenen Thread. Nach einer Frist ohne Aktivität kann dies thread/closed auslösen.
  • thread/unarchive verschiebt eine archivierte Thread-Aufzeichnung zurück in das Verzeichnis der aktiven Sitzungen.
  • thread/compact/start startet die Kontextverdichtung und gibt sofort {} zurück.
  • thread/revert entfernt einen angegebenen Turn und alle späteren Turns aus dem Verlauf eines dauerhaft gespeicherten, paginierten Threads. Lokale Dateien bleiben unverändert.
  • thread/inject_items fügt dem für das Modell sichtbaren Verlauf eines geladenen Threads unverarbeitete Elemente der Responses API hinzu, ohne einen Nutzer-Turn zu starten.

Einen Thread starten oder fortsetzen

Starte einen neuen Thread, wenn du ein neues Gespräch mit Codex beginnen möchtest.

{ "method": "thread/start", "id": 10, "params": {
"model": "gpt-6.1-sol",
"cwd": "/Users/me/project",
"approvalPolicy": "never",
"sandbox": "workspace-write",
"serviceName": "my_app_server_client"
} }
{ "id": 10, "result": {
"thread": {
  "id": "thr_123",
  "sessionId": "thr_123",
  "preview": "",
  "ephemeral": false,
  "modelProvider": "openai",
  "createdAt": 1730910000
}
} }
{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }

serviceName ist optional. Gib den Wert an, wenn der App Server Thread-Metriken mit dem Dienstnamen deiner Integration kennzeichnen soll.

thread/start, thread/resume und thread/fork geben instructionSources zurück. Dieses Array enthält die Pfade der geladenen Anweisungsdateien. Jeder Pfad verwendet die native Syntax für absolute Pfade der jeweiligen Quellumgebung, auch bei Remote-Umgebungen.

Neue dauerhaft gespeicherte lokale Threads verwenden standardmäßig einen paginierten Verlauf. Lade den Verlauf mit thread/turns/list und thread/items/list. Das explizite Setzen von historyMode auf "legacy" oder "paginated" bei thread/start ist experimentell und erfordert capabilities.experimentalApi = true.

Beta-Clients, die capabilities.experimentalApi aktivieren, können die ID eines benannten Berechtigungsprofils in permissions anstelle des älteren Felds sandbox übergeben. Sende permissions und sandbox nicht zusammen. Ermittle mit permissionProfile/list und dem cwd des Projekts, welche Profile verfügbar sind und welche die verwalteten Vorgaben zulassen.

thread.sessionId bezeichnet die Wurzel des aktuellen aktiven Sitzungsbaums. Bei einem Wurzel-Thread entspricht die Sitzungs-ID seiner Thread-ID. Geforkte Threads behalten die Sitzungs-ID ihres ursprünglichen Wurzel-Threads. Clients sollten die Sitzungs-ID aus thread.sessionId lesen, statt sie aus der Thread-ID abzuleiten.

Um eine gespeicherte Sitzung fortzusetzen, rufe thread/resume mit der zuvor gespeicherten thread.id auf. Übergib excludeTurns: true, um Thread-Metadaten und den aktuellen Sitzungsstatus zu erhalten. Lade den Verlauf anschließend mit den Paginierungsmethoden:

{ "method": "thread/resume", "id": 11, "params": {
  "threadId": "thr_123",
  "excludeTurns": true
} }
{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

Bei paginierten Threads sind Antworten von thread/resume und thread/fork mit vollständigem Verlauf veraltet und lösen deprecationNotice aus. Beide Methoden akzeptieren excludeTurns: true, auch wenn die experimentelle API nicht aktiviert ist. Eine Antwort von thread/resume kann außerdem turnsBackwardsCursor und itemsBackwardsCursor enthalten. Übergib jeden Cursor mit sortDirection: "desc" an die passende Paginierungsmethode. Die erste Seite enthält den Anker des Cursors.

Das Fortsetzen eines Threads allein ändert weder thread.updatedAt noch den Änderungszeitpunkt der Aufzeichnungsdatei. Der Zeitstempel wird aktualisiert, wenn du einen Turn startest.

Wenn du einen aktivierten MCP-Server in der Konfiguration als required kennzeichnest und seine Initialisierung fehlschlägt, schlagen auch thread/start und thread/resume fehl. Der Thread läuft in diesem Fall nicht ohne den MCP-Server weiter.

dynamicTools ist bei thread/start ein experimentelles Feld und erfordert capabilities.experimentalApi = true. Codex speichert die dynamischen Tools in den Metadaten der Thread-Aufzeichnung und stellt sie bei thread/resume wieder her, wenn du keine neuen dynamischen Tools angibst.

Weicht der konfigurierte Modellanbieter vom gespeicherten Anbieter des Threads ab, liefern thread/resume und neue Eingaben den Fehler -32600. Dabei hat data.type den Wert modelProviderMismatch. Um den Verlauf anzuzeigen, lies die Turns seitenweise mit thread/turns/list. Wechsle zum gespeicherten Anbieter zurück, um den Thread fortzusetzen. Mit thread/fork kannst du aus seinem Verlauf einen neuen Thread mit dem aktuellen Anbieter starten.

Wenn du einen Thread mit einem anderen Modell fortsetzt als dem in der Aufzeichnung gespeicherten, gibt Codex eine Warnung aus und verwendet beim nächsten Turn einmalig eine Anweisung für den Modellwechsel.

Das Ziel eines Threads verwalten

Mit thread/goal/set, thread/goal/get und thread/goal/clear verwaltest du denselben gespeicherten Zielzustand, den /goal in der TUI anzeigt.

{ "method": "thread/goal/set", "id": 13, "params": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000
} }
{ "id": 13, "result": { "goal": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000,
  "tokensUsed": 0,
  "timeUsedSeconds": 0
} } }
{ "method": "thread/goal/updated", "params": {
  "threadId": "thr_123",
  "goal": {
    "threadId": "thr_123",
    "objective": "Finish the migration and keep tests green",
    "status": "active",
    "tokenBudget": 40000,
    "tokensUsed": 0,
    "timeUsedSeconds": 0
  }
} }

Eine Zielbeschreibung darf nicht leer sein und höchstens 4.000 Zeichen umfassen. Eine neue Beschreibung ersetzt das Ziel und setzt die Verbrauchszähler zurück. Wenn du die aktuelle Beschreibung eines noch nicht abgeschlossenen Ziels übergibst oder objective weglässt, kannst du Status oder Tokenbudget aktualisieren, ohne den bisherigen Verbrauch zurückzusetzen.

Um eine gespeicherte Sitzung zu forken, rufe thread/fork mit der thread.id auf. Dadurch entsteht ein Thread mit einer neuen ID, für den der Server eine thread/started-Benachrichtigung sendet. Übergib lastTurnId, um den Verlauf bis einschließlich dieses Turns zu kopieren und spätere Turns auszulassen:

{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123", "lastTurnId": "turn_456", "excludeTurns": true } }
{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }
{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

Der App Server weist eine lastTurnId zurück, die auf einen laufenden Turn verweist. Wenn du das Feld weglässt, während im Quell-Thread ein Turn läuft, markiert der Fork diesen unvollständigen Turn als unterbrochen.

Übergib ephemeral: true, um einen Fork im Arbeitsspeicher zu erstellen, der nicht in der Liste gespeicherter Threads erscheint:

{
  "method": "thread/fork",
  "id": 13,
  "params": {
    "threadId": "thr_123",
    "ephemeral": true,
    "excludeTurns": true
  }
}
{
  "id": 13,
  "result": {
    "thread": {
      "id": "thr_789",
      "sessionId": "thr_789",
      "forkedFromId": "thr_123",
      "ephemeral": true
    }
  }
}

Flüchtige Forks paginierter Threads erfordern excludeTurns: true.

Sobald ein sichtbarer Thread-Titel festgelegt wurde, befüllt der App Server thread.name in den Antworten auf thread/list, thread/read, thread/resume und thread/unarchive. thread/start und thread/fork können name auslassen oder null zurückgeben, solange noch kein Titel festgelegt wurde.

Einen gespeicherten Thread lesen, ohne ihn fortzusetzen

Verwende thread/read, wenn du gespeicherte Thread-Daten benötigst, ohne den Thread fortzusetzen oder seine Ereignisse zu abonnieren.

  • includeTurns: Bei false oder fehlendem Feld enthält die Antwort nur die Thread-Zusammenfassung. Mit true wird der gesamte Verlauf geladen. Bei paginierten Threads ist dieses Verhalten veraltet und löst deprecationNotice aus. Verwende hierfür die Paginierungsmethoden.
  • Zurückgegebene thread-Objekte enthalten den Laufzeitstatus status (notLoaded, idle, systemError oder active mit activeFlags).
{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123" } }
{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

Anders als thread/resume lädt thread/read den Thread nicht in den Arbeitsspeicher und sendet auch kein thread/started.

Turns eines Threads auflisten

Mit thread/turns/list liest du den gespeicherten Turn-Verlauf eines Threads seitenweise, ohne ihn fortzusetzen. Standardmäßig stehen die neuesten Turns zuerst. Über nextCursor können Clients ältere Turns abrufen. Die Antwort enthält außerdem backwardsCursor. Übergib diesen als cursor mit der entgegengesetzten sortDirection, um die Leserichtung umzukehren. Dabei wird der Turn am Anker erneut einbezogen, sodass du Aktualisierungen dieses Turns erfassen kannst.

itemsView legt fest, welche Daten zu den Elementen eines Turns die Antwort enthält:

  • notLoaded lässt die Elemente aus.
  • summary liefert zusammengefasste Elementdaten und ist der Standardwert, wenn du das Feld weglässt.
  • full liefert die vollständigen Elementdaten.
{ "method": "thread/turns/list", "id": 20, "params": {
  "threadId": "thr_123",
  "limit": 50,
  "sortDirection": "desc",
  "itemsView": "summary"
} }
{ "id": 20, "result": {
  "data": [],
  "nextCursor": "older-turns-cursor-or-null",
  "backwardsCursor": "newer-turns-cursor-or-null"
} }

Elemente eines Threads auflisten

thread/items/list liest gespeicherte Elemente seitenweise, ohne den Thread fortzusetzen. Übergib turnId, um die Ergebnisse auf einen Turn zu beschränken. Ohne diese Angabe liest du die Elemente des gesamten Threads. Standardmäßig stehen die ältesten Elemente zuerst (sortDirection: "asc"). Der aktive Thread-Speicher muss die Paginierung von Elementen unterstützen. Andernfalls meldet der Server, dass die Methode nicht unterstützt wird.

Übergib den opaken nextCursor aus einer vorherigen Antwort, um die nächste Seite abzurufen. Um nach einem bekannten Element zu beginnen, übergib einen Elementanker und eine nicht leere turnId:

{ "method": "thread/items/list", "id": 21, "params": {
  "threadId": "thr_123",
  "turnId": "turn_456",
  "cursor": { "type": "item", "itemId": "item_123" },
  "sortDirection": "asc",
  "limit": 50
} }
{ "id": 21, "result": {
  "data": [],
  "nextCursor": null,
  "backwardsCursor": null
} }

Bei Elementankern bleibt das Ankerelement selbst ausgeschlossen. In aufsteigender Reihenfolge erhältst du neuere, in absteigender Reihenfolge ältere Elemente. Das Element muss zum sichtbaren Verlauf des angefragten Turns gehören. Fehlt turnId, ist die Element-ID leer oder ist das Element unbekannt oder außerhalb des angefragten Verlaufs, meldet der Server ungültige Parameter (-32602). Verwende für weitere Seiten die zurückgegebene Zeichenfolge nextCursor. Jeder Ergebniseintrag enthält turnId, item und, sofern aufgezeichnet, Zeitstempel für Beginn und Abschluss.

Threads mit Paginierung und Filtern auflisten

Mit thread/list kannst du den Verlauf in einer Benutzeroberfläche anzeigen. Standardmäßig stehen die neuesten Ergebnisse nach createdAt zuerst. Der Server filtert vor der Paginierung. Du kannst die folgenden Parameter kombinieren:

  • cursor ist eine opake Zeichenfolge aus einer vorherigen Antwort. Lass sie für die erste Seite weg.
  • limit legt die Seitengröße fest. Ohne Angabe verwendet der Server eine geeignete Standardgröße.
  • sortKey akzeptiert created_at (Standard), updated_at, recency_at oder section_position. Für section_position musst du eine sectionId angeben, die nicht null ist.
  • sortDirection akzeptiert asc oder desc. Ohne sortDirection sortiert der Server bei section_position aufsteigend und bei zeitbasierten Schlüsseln absteigend.
  • sectionId: Übergib die ID eines Abschnitts, um dessen Threads aufzulisten, oder null für nicht zugeordnete Threads. Ohne das Feld erhältst du Threads aus allen Abschnitten sowie nicht zugeordnete Threads.
  • excludedThreadIds: Gib bis zu 100 Thread-IDs an, die der Server ausschließen soll. Doppelte IDs zählen zur Obergrenze von 100 IDs. Der Server schließt die entsprechenden Threads aus, bevor er die Seitengröße anwendet. Sende mit jedem Cursor dieselben Ausschlüsse.
  • modelProviders beschränkt die Ergebnisse auf bestimmte Anbieter. Übergib [], um alle Anbieter einzubeziehen. Wenn du das Feld weglässt oder null übergibst, verwendet der Server den konfigurierten Anbieter. Filterst du dabei nach einer Thread-Beziehung, berücksichtigt er alle Anbieter.
  • sourceKinds beschränkt die Ergebnisse auf bestimmte Thread-Quellen. Bei fehlendem Wert oder [] berücksichtigt der Server standardmäßig nur die interaktiven Quellen cli und vscode.
  • archived listet bei true nur archivierte Threads auf. Bei false oder fehlendem Wert erscheinen nur nicht archivierte Threads (Standard).
  • cwd beschränkt die Ergebnisse auf Threads, deren aktuelles Sitzungsarbeitsverzeichnis genau dem angegebenen Pfad oder einem Pfad im angegebenen Array entspricht. Relative Pfade beziehen sich auf das Arbeitsverzeichnis des App-Server-Prozesses.
  • useStateDbOnly liefert bei true Ergebnisse aus der Zustandsdatenbank, ohne die JSONL-Thread-Protokolle zur Reparatur der Metadaten zu durchsuchen. Lass den Parameter weg oder übergib false, um die Protokolle wie gewohnt zu durchsuchen und Metadaten zu reparieren.
  • searchTerm beschränkt die Ergebnisse auf Threads, deren extrahierter Titel das angegebene Textfragment enthält. Groß- und Kleinschreibung werden berücksichtigt.
  • parentThreadId beschränkt die Ergebnisse auf direkte untergeordnete Threads des angegebenen Threads. Dieser Filter ist experimentell und erfordert capabilities.experimentalApi = true.
  • ancestorThreadId beschränkt die Ergebnisse auf Threads, die auf beliebiger Ebene aus dem angegebenen Thread erzeugt wurden. Dieser Filter ist experimentell und erfordert capabilities.experimentalApi = true. Kombiniere ihn nicht mit parentThreadId.

sourceKinds akzeptiert folgende Werte:

  • cli
  • vscode
  • exec
  • appServer
  • subAgent
  • subAgentReview
  • subAgentCompact
  • subAgentThreadSpawn
  • subAgentOther
  • unknown

Beispiel:

{ "method": "thread/list", "id": 20, "params": {
  "cursor": null,
  "limit": 25,
  "sortKey": "created_at"
} }
{ "id": 20, "result": {
  "data": [
    { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "section": { "id": "01984de2-8f74-7c91-a3b2-5c5e937cf318", "name": "Pinned", "appearance": null }, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
    { "id": "thr_b", "preview": "Fix tests", "ephemeral": false, "section": null, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
  ],
  "nextCursor": "opaque-token-or-null"
} }

Wenn nextCursor den Wert null hat, hast du die letzte Seite erreicht.

Threads in Abschnitten organisieren

Erstelle mit threadSection/create einen benannten Abschnitt und verwende die zurückgegebene section.id in thread/section/move. Übergib beforeThreadId, um den Thread vor einem anderen Thread im Abschnitt einzufügen. Ohne diese Angabe wird er am Ende angefügt. Übergib sectionId: null, um einen Thread aus seinem Abschnitt zu entfernen. Mit threadSection/list, threadSection/update und threadSection/delete kannst du eigene Abschnitte seitenweise auflisten, umbenennen und entfernen. Um einen Thread anzuheften, verschiebe ihn in den integrierten Abschnitt „Pinned“, den threadSection/list zurückgibt.

Thread-Anhänge verwalten

Über Anhänge kannst du Ressourcen wie Pull Requests mit einem gespeicherten Thread verknüpfen. Du kannst diese Verweise verwalten, ohne den Thread fortzusetzen.

  • thread/attachment/add erwartet threadId, attachmentType, identityKey und das Feld payload mit JSON-Daten. Wenn du denselben Typ und Schlüssel erneut zum selben Thread hinzufügst, erhältst du den bestehenden Anhang zurück.
  • thread/attachment/list liefert die Anhänge eines Threads seitenweise. Um Threads zu finden, die auf eine Ressource verweisen, rufe thread/attachmentOwner/list mit ihrem attachmentType und identityKey auf.
  • thread/attachment/remove erwartet threadId, attachmentType und identityKey. Die verknüpfte Ressource bleibt verfügbar.
  • thread/attachment/updated meldet die Operation created oder deleted, wenn sich die Zuordnung ändert.

Gespeicherte Thread-Metadaten aktualisieren

Mit thread/metadata/update aktualisierst du einzelne gespeicherte Metadaten, ohne den Thread fortzusetzen. Übergib die zu ändernden Git-Felder in gitInfo. Lass ein Feld weg, um seinen Wert beizubehalten, oder übergib null, um den Wert zu löschen.

{ "method": "thread/metadata/update", "id": 21, "params": {
  "threadId": "thr_123",
  "gitInfo": { "branch": "feature/sidebar-pr" }
} }
{ "id": 21, "result": {
  "thread": {
    "id": "thr_123",
    "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }
  }
} }

Statusänderungen eines Threads verfolgen

Der Server sendet thread/status/changed, sobald sich der Laufzeitstatus eines geladenen Threads ändert. Die Nachricht enthält threadId und den neuen status.

{
  "method": "thread/status/changed",
  "params": {
    "threadId": "thr_123",
    "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }
  }
}

Geladene Threads auflisten

thread/loaded/list gibt die IDs der aktuell im Arbeitsspeicher geladenen Threads zurück.

{ "method": "thread/loaded/list", "id": 21 }
{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }

Abonnement für einen geladenen Thread beenden

thread/unsubscribe beendet das Thread-Abonnement der aktuellen Verbindung. Die Antwort enthält einen der folgenden Statuswerte:

  • unsubscribed, wenn die Verbindung den Thread abonniert hatte und das Abonnement beendet wurde.
  • notSubscribed, wenn die Verbindung diesen Thread nicht abonniert hatte.
  • notLoaded, wenn der Thread nicht geladen ist.

Nach dem Ende des letzten Abonnements entlädt der App Server den Thread standardmäßig nach 60 Sekunden Inaktivität. Über thread_unload_delay_secs kannst du diese Frist ändern. Beim Entladen sendet der App Server thread/status/changed mit dem Status notLoaded sowie die Benachrichtigung thread/closed.

{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }
{ "id": 22, "result": { "status": "unsubscribed" } }

Wenn die Frist für den Thread später abläuft:

{ "method": "thread/status/changed", "params": {
    "threadId": "thr_123",
    "status": { "type": "notLoaded" }
} }
{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

Einen Thread archivieren

Mit thread/archive verschiebst du das als JSONL-Datei gespeicherte Thread-Protokoll in das Verzeichnis der archivierten Sitzungen. Der Server versucht dabei auch, die noch nicht archivierten Threads zu archivieren, die aus diesem Thread erzeugt wurden.

{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }
{ "id": 22, "result": {} }
{ "method": "thread/archived", "params": { "threadId": "thr_b" } }
{ "method": "thread/archived", "params": { "threadId": "thr_child" } }

Archivierte Threads erscheinen bei späteren Aufrufen von thread/list nur, wenn du archived: true übergibst. Der Server sendet für jeden tatsächlich archivierten Thread eine thread/archived-Benachrichtigung. Kann er einen daraus erzeugten Thread nicht archivieren, kann die Anfrage trotzdem erfolgreich sein. Für diesen Thread entfällt dann die Archivierungsbenachrichtigung.

Einen Thread löschen

Mit thread/delete löschst du einen gespeicherten aktiven oder archivierten Thread und alle daraus erzeugten Threads dauerhaft. Bevor der Server den Erfolg bestätigt, entfernt er vorhandene Aufzeichnungsdateien und zugehörige Metadaten. Fehlende Aufzeichnungsdateien gelten als bereits gelöscht. Flüchtige Wurzel-Threads lassen sich nicht löschen.

{ "method": "thread/delete", "id": 23, "params": { "threadId": "thr_b" } }
{ "id": 23, "result": {} }
{ "method": "thread/deleted", "params": { "threadId": "thr_b" } }
{ "method": "thread/deleted", "params": { "threadId": "thr_child" } }

Einen Thread aus dem Archiv zurückholen

Mit thread/unarchive verschiebst du eine archivierte Thread-Aufzeichnung zurück in das Verzeichnis der aktiven Sitzungen.

{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }
{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }
{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

Kontextverdichtung für einen Thread starten

Mit thread/compact/start startest du manuell die Kontextverdichtung für den Verlauf eines Threads. Die Anfrage gibt sofort {} zurück.

Der App Server meldet den Fortschritt über die üblichen turn/*- und item/*-Benachrichtigungen für dieselbe threadId. Dazu gehört der Lebenszyklus eines contextCompaction-Elements mit item/started und anschließend item/completed.

{ "method": "thread/compact/start", "id": 25, "params": { "threadId": "thr_b" } }
{ "id": 25, "result": {} }

Einen Shell-Befehl für einen Thread ausführen

Verwende thread/shellCommand für Shell-Befehle, die eine Person explizit für einen Thread auslöst. Die Anfrage gibt sofort {} zurück. Fortschrittsmeldungen folgen über die üblichen turn/*- und item/*-Benachrichtigungen.

Diese API läuft außerhalb der Sandbox mit Vollzugriff und übernimmt die Sandbox-Richtlinie des Threads nicht. Clients sollten sie ausschließlich für Befehle bereitstellen, die eine Person ausdrücklich selbst auslöst.

Hat der Thread bereits einen aktiven Turn, läuft der Befehl als zusätzliche Aktion dieses Turns. Die formatierte Ausgabe wird in den Nachrichtenstream des Turns eingefügt. Ist der Thread inaktiv, startet der App Server einen eigenständigen Turn für den Shell-Befehl.

Lege mit timeoutMs die maximale Laufzeit in Millisekunden fest. Ohne Angabe oder bei null gilt der Standardwert von einer Stunde. 0 fordert einen sofortigen Timeout an. Negative Werte werden zurückgewiesen. Der Timeout verzögert die sofortige Bestätigung des RPC-Aufrufs nicht.

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short", "timeoutMs": 10000 } }
{ "id": 26, "result": {} }

Hintergrundterminals beenden

Mit thread/backgroundTerminals/clean stoppst du alle laufenden Hintergrundterminals eines Threads. Diese Methode ist experimentell und erfordert capabilities.experimentalApi = true.

{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }
{ "id": 27, "result": {} }

Mit thread/backgroundTerminals/list kannst du die laufenden Hintergrundterminals eines geladenen Threads prüfen. Die Anfrage unterstützt die übliche Paginierung mit cursor und limit. Die zurückgegebene processId ist die vom App Server verwendete Prozess-ID. Diese Methode ist experimentell und erfordert capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/list", "id": 28, "params": { "threadId": "thr_b" } }
{ "id": 28, "result": { "data": [
  {
    "itemId": "item_456",
    "processId": "42",
    "command": "python3 -m http.server",
    "cwd": "/workspace",
    "osPid": null,
    "cpuPercent": null,
    "rssKb": null
  }
], "nextCursor": null } }

Verwende thread/backgroundTerminals/terminate mit dieser processId, um ein einzelnes Hintergrundterminal zu stoppen. Diese Methode ist experimentell und erfordert capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/terminate", "id": 29, "params": { "threadId": "thr_b", "processId": "42" } }
{ "id": 29, "result": { "terminated": true } }

Thread-Verlauf zurücksetzen

Mit thread/revert entfernst du den durch beforeTurnId bezeichneten Turn und alle späteren Turns aus dem Gesprächsverlauf eines dauerhaft gespeicherten, paginierten Threads. Lokale Dateiänderungen werden dabei nicht rückgängig gemacht. Setze den Thread zuerst fort, falls er nicht geladen ist. Flüchtige Threads und Threads mit Verlauf im älteren Format werden nicht unterstützt.

{ "method": "thread/revert", "id": 30, "params": { "threadId": "thr_b", "beforeTurnId": "turn_456" } }
{ "id": 30, "result": {
  "thread": { "id": "thr_b", "ephemeral": false, "turns": [] },
  "turnsBackwardsCursor": "retained-turn-cursor-or-null",
  "itemsBackwardsCursor": "retained-item-cursor-or-null"
} }
{ "method": "thread/reverted", "params": { "threadId": "thr_b" } }

Das zurückgegebene Feld thread.turns ist immer leer. Verwende die zurückgegebenen Cursor mit thread/turns/list oder thread/items/list und sortDirection: "desc", um den verbleibenden Verlauf einschließlich des Cursor-Ankers zu laden.

thread/rollback wurde entfernt. Ein Aufruf meldet eine unbekannte Methode. Bereits vorhandene Rollback-Markierungen in älteren gespeicherten Threads bleiben lesbar.

Turns

Das Feld input akzeptiert eine Liste von Elementen:

  • { "type": "text", "text": "Explain this diff" }
  • { "type": "image", "url": "https://.../design.png" }
  • { "type": "localImage", "path": "/tmp/screenshot.png" }

Du kannst Konfigurationseinstellungen für einzelne Turns überschreiben (Modell, Reasoning-Aufwand, cwd, Sandbox-Richtlinie, Zusammenfassung). Angegebene Einstellungen gelten als Standardwerte für spätere Turns im selben Thread. outputSchema gilt nur für den aktuellen Turn. Bei sandboxPolicy.type = "externalSandbox" setzt du networkAccess auf restricted oder enabled. Für workspaceWrite bleibt networkAccess ein boolescher Wert.

Bei turn/start.collaborationMode bedeutet settings.developer_instructions: null, dass die integrierten Anweisungen für den ausgewählten Modus verwendet werden. Die Modusanweisungen werden dadurch nicht gelöscht.

Lesezugriff in der Sandbox (ReadOnlyAccess)

Mit sandboxPolicy kannst du den Lesezugriff explizit steuern:

  • readOnly unterstützt das optionale Feld access (standardmäßig { "type": "fullAccess" }, alternativ beschränkt auf bestimmte Stammverzeichnisse).
  • workspaceWrite unterstützt das optionale Feld readOnlyAccess (standardmäßig { "type": "fullAccess" }, alternativ beschränkt auf bestimmte Stammverzeichnisse).

Struktur für eingeschränkten Lesezugriff:

{
  "type": "restricted",
  "includePlatformDefaults": true,
  "readableRoots": ["/Users/me/shared-read-only"]
}

Unter macOS ergänzt includePlatformDefaults: true für Sitzungen mit eingeschränktem Lesezugriff eine gezielt zusammengestellte plattformspezifische Seatbelt-Standardrichtlinie. Das verbessert die Kompatibilität mit Tools, ohne ganz /System freizugeben.

Beispiele:

{ "type": "readOnly", "access": { "type": "fullAccess" } }
{
  "type": "workspaceWrite",
  "writableRoots": ["/Users/me/project"],
  "readOnlyAccess": {
    "type": "restricted",
    "includePlatformDefaults": true,
    "readableRoots": ["/Users/me/shared-read-only"]
  },
  "networkAccess": false
}

Einen Turn starten

{ "method": "turn/start", "id": 30, "params": {
"threadId": "thr_123",
"input": [ { "type": "text", "text": "Run tests" } ],
"cwd": "/Users/me/project",
"approvalPolicy": "on-request",
"sandboxPolicy": {
  "type": "workspaceWrite",
  "writableRoots": ["/Users/me/project"],
  "networkAccess": true
},
"model": "gpt-6.1-sol",
"effort": "medium",
"summary": "concise",
"outputSchema": {
  "type": "object",
  "properties": { "answer": { "type": "string" } },
  "required": ["answer"],
  "additionalProperties": false
}
} }
{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }

Mit serviceTierForTurn überschreibst du die Servicestufe für einen einzelnen neuen Turn. Verwende "default" für die Standardgeschwindigkeit oder lass das Feld weg, um die Servicestufe des Threads zu übernehmen. Um die Stufe für diesen und spätere Turns zu ändern, setze serviceTier.

Um einen Turn mit der Ausgabe eines vom Client ausgeführten Tools zu starten, übergib toolOutput mit einem nicht leeren name und optional einem namespace. Als output ist eine Zeichenfolge oder ein Array von Inhaltselementen zulässig. Setze input auf ein leeres Array. toolOutput lässt sich nicht mit einer nicht leeren Nutzereingabe kombinieren.

{
  "method": "turn/start",
  "id": 31,
  "params": {
    "threadId": "thr_123",
    "input": [],
    "toolOutput": {
      "name": "run_tests",
      "namespace": null,
      "output": "All 42 tests passed."
    }
  }
}

Die Ausgabe bleibt im Gespräch als Toolausgabe gekennzeichnet und erscheint in Benachrichtigungen und im gespeicherten Verlauf als functionCallOutput-Element. Läuft bereits ein regulärer Turn, reiht Codex die Ausgabe für diesen Turn ein.

Elemente in einen Thread einfügen

Mit thread/inject_items fügst du vorbereitete Elemente der Responses API in den Prompt-Verlauf eines geladenen Threads ein, ohne einen Nutzer-Turn zu starten. Die Elemente werden in der Sitzungsaufzeichnung gespeichert und in nachfolgenden Modellanfragen berücksichtigt.

{ "method": "thread/inject_items", "id": 31, "params": {
  "threadId": "thr_123",
  "items": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Previously computed context." }]
    }
  ]
} }
{ "id": 31, "result": {} }

Einen aktiven Turn steuern

Mit turn/steer fügst du einem laufenden Turn weitere Nutzereingaben hinzu.

  • Gib expectedTurnId an. Der Wert muss der ID des aktiven Turns entsprechen.
  • Die Anfrage schlägt fehl, wenn der Thread keinen aktiven Turn hat.
  • turn/steer löst keine neue turn/started-Benachrichtigung aus.
  • turn/steer akzeptiert keine abweichenden Einstellungen für den Turn (model, cwd, sandboxPolicy oder outputSchema).
{ "method": "turn/steer", "id": 32, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Actually focus on failing tests first." } ],
  "expectedTurnId": "turn_456"
} }
{ "id": 32, "result": { "turnId": "turn_456" } }

Einen Turn mit einem Skill starten

Rufe einen Skill explizit auf, indem du $<skill-name> in die Texteingabe einfügst und daneben ein Eingabeelement vom Typ skill übergibst.

{ "method": "turn/start", "id": 33, "params": {
  "threadId": "thr_123",
  "input": [
    { "type": "text", "text": "$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage." },
    { "type": "skill", "name": "skill-creator", "path": "/Users/me/.codex/skills/skill-creator/SKILL.md" }
  ]
} }
{ "id": 33, "result": { "turn": { "id": "turn_457", "status": "inProgress", "items": [], "error": null } } }

Einen Turn unterbrechen

{ "method": "turn/interrupt", "id": 31, "params": { "threadId": "thr_123", "turnId": "turn_456" } }
{ "id": 31, "result": {} }

Bei Erfolg endet der Turn mit status: "interrupted".

Code Review

review/start startet das Code Review durch Codex für einen Thread und überträgt die zugehörigen Elemente im Stream. Mögliche Prüfziele sind:

  • uncommittedChanges
  • baseBranch (Diff gegenüber einem Branch)
  • commit (einen bestimmten Commit überprüfen)
  • custom (frei formulierte Anweisungen)

review/start führt die Überprüfung im angegebenen Thread aus. Lass delivery weg oder übergib "inline". Für eine separate Überprüfung kannst du mit thread/fork den bisherigen Verlauf übernehmen oder mit thread/start einen neuen Thread ohne Verlauf erstellen. Rufe anschließend review/start mit der neuen Thread-ID auf.

Beispiel für Anfrage und Antwort:

{ "method": "review/start", "id": 40, "params": {
  "threadId": "thr_123",
  "delivery": "inline",
  "target": { "type": "commit", "sha": "1234567deadbeef", "title": "Polish tui colors" }
} }
{ "id": 40, "result": {
  "turn": {
    "id": "turn_900",
    "status": "inProgress",
    "items": [
      { "type": "userMessage", "id": "turn_900", "content": [ { "type": "text", "text": "Review commit 1234567: Polish tui colors" } ] }
    ],
    "error": null
  },
  "reviewThreadId": "thr_123"
} }

Codex sendet die übliche Benachrichtigung turn/started, gefolgt von item/started mit einem Element vom Typ enteredReviewMode:

{
  "method": "item/started",
  "params": {
    "item": {
      "type": "enteredReviewMode",
      "id": "turn_900",
      "review": "current changes"
    }
  }
}

Nach Abschluss der Überprüfung sendet der Server item/started und item/completed. Beide enthalten ein exitedReviewMode-Element mit dem endgültigen Prüfbericht:

{
  "method": "item/completed",
  "params": {
    "item": {
      "type": "exitedReviewMode",
      "id": "turn_900",
      "review": "Looks solid overall..."
    }
  }
}

Verwende diese Benachrichtigung, um den Prüfbericht in deinem Client anzuzeigen.

Prozesse ausführen

process/* ist eine experimentelle API zur expliziten Prozesssteuerung. Sie erfordert capabilities.experimentalApi = true und läuft außerhalb der Codex-Sandbox. Verwende sie nur, wenn dein Client bewusst eine lokale Prozesssteuerung ohne Sandbox anbietet.

Starte einen Prozess mit process/spawn und gib ein processHandle an. Verwende dieses Handle anschließend für Anfragen zur Standardeingabe, zur Änderung der Terminalgröße und zum Beenden des Prozesses. Die Ausgabe erhältst du über process/outputDelta-Benachrichtigungen, den Abschluss meldet process/exited.

{ "method": "process/spawn", "id": 48, "params": {
  "command": ["python3", "-m", "pytest", "-q"],
  "processHandle": "pytest-1",
  "cwd": "/Users/me/project",
  "tty": true
} }
{ "id": 48, "result": {} }
{ "method": "process/outputDelta", "params": {
  "processHandle": "pytest-1",
  "stream": "stdout",
  "deltaBase64": "Li4u"
} }
{ "method": "process/exited", "params": {
  "processHandle": "pytest-1",
  "exitCode": 0
} }

Verwende process/writeStdin mit deltaBase64, closeStdin oder beiden Feldern, um Eingaben zu senden. Verwende process/resizePty für Änderungen der PTY-Größe und process/kill, um einen laufenden Prozess zu beenden.

Befehle ausführen

command/exec führt einen einzelnen Befehl (argv-Array) in der Sandbox des Servers aus, ohne einen Thread zu erstellen.

{ "method": "command/exec", "id": 50, "params": {
  "command": ["ls", "-la"],
  "cwd": "/Users/me/project",
  "sandboxPolicy": { "type": "workspaceWrite" },
  "timeoutMs": 10000
} }
{ "id": 50, "result": { "exitCode": 0, "stdout": "...", "stderr": "" } }

Verwende sandboxPolicy.type = "externalSandbox", wenn der Serverprozess bereits in deiner eigenen Sandbox läuft und Codex seine eigenen Sandbox-Regeln nicht zusätzlich anwenden soll. Setze networkAccess im externen Sandbox-Modus auf restricted (Standard) oder enabled. Für readOnly und workspaceWrite gilt die oben gezeigte optionale Struktur mit access bzw. readOnlyAccess.

Hinweise:

  • Der Server weist leere command-Arrays zurück.
  • sandboxPolicy akzeptiert dieselbe Struktur wie turn/start, etwa dangerFullAccess, readOnly, workspaceWrite oder externalSandbox.
  • Ohne Angabe gilt für timeoutMs der Standardwert des Servers.
  • Setze tty: true für Sitzungen mit PTY. Verwende processId, wenn du anschließend command/exec/write, command/exec/resize oder command/exec/terminate aufrufen möchtest.
  • Setze streamStdoutStderr: true, um während der Befehlsausführung command/exec/outputDelta-Benachrichtigungen zu erhalten.

Administrative Vorgaben lesen (configRequirements/read)

Mit configRequirements/read prüfst du die wirksamen administrativen Vorgaben, die aus requirements.toml, aus MDM oder aus beiden Quellen geladen wurden.

{ "method": "configRequirements/read", "id": 52, "params": {} }
{ "id": 52, "result": {
  "requirements": {
    "allowedApprovalPolicies": ["on-request", "never"],
    "allowedSandboxModes": ["read-only", "workspace-write"],
    "featureRequirements": {
      "unified_exec": false
    }
  }
} }

result.requirements ist null, wenn keine Vorgaben konfiguriert sind. Hat result.supportsIndependentSpeedModes den Wert true, gelten die Vorgaben für fast_mode und ultrafast_mode unabhängig voneinander. Ältere Server lassen dieses Feld weg und verwenden fast_mode für beide Modi. Die unterstützten Schlüssel und Werte findest du in der Referenz zu requirements.toml.

Setup der Windows-Sandbox (windowsSandbox/setupStart)

Rufe windowsSandbox/readiness auf, bevor du zum Setup aufforderst. Sowohl MXC als auch eine konfigurierte Sandbox der älteren Generation können ready zurückgeben. Meldet die ältere Sandbox updateRequired, rufe windowsSandbox/setupStart auf, um das Setup asynchron zu starten. Die Prüfung liefert notConfigured, wenn die Windows-Sandbox deaktiviert ist oder der Host ein anderes Betriebssystem verwendet.

{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }
{ "id": 53, "result": { "started": true } }

Der App Server startet das Setup im Hintergrund und sendet nach Abschluss eine Benachrichtigung:

{
  "method": "windowsSandbox/setupCompleted",
  "params": { "mode": "elevated", "success": true, "error": null }
}

Modi:

  • elevated führt das Setup der Windows-Sandbox mit erhöhten Rechten aus.
  • unelevated verwendet das ältere Verfahren für Setup und Vorabprüfung.

Dateisystem

Die Dateisystem-APIs v2 arbeiten mit absoluten Pfaden. Verwende fs/watch, wenn ein Client nach Änderungen an einer Datei oder einem Verzeichnis den bisherigen Zustand seiner Oberfläche als veraltet markieren muss.

{ "method": "fs/watch", "id": 54, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "path": "/Users/me/project/.git/HEAD"
} }
{ "id": 54, "result": { "path": "/Users/me/project/.git/HEAD" } }
{ "method": "fs/changed", "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "changedPaths": ["/Users/me/project/.git/HEAD"]
} }
{ "method": "fs/unwatch", "id": 55, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1"
} }
{ "id": 55, "result": {} }

Bei einer überwachten Datei meldet fs/changed Änderungen am angegebenen Pfad, auch wenn die Datei ersetzt oder umbenannt wurde.

Ereignisse

Über Ereignisbenachrichtigungen meldet der Server fortlaufend, was mit Threads, Turns und ihren Elementen geschieht. Lies nach dem Starten oder Fortsetzen eines Threads weiter den aktiven Transportstream, um Benachrichtigungen zu thread/started, thread/archived, thread/unarchived, thread/closed, thread/status/changed, turn/*, item/* und serverRequest/resolved zu empfangen.

Benachrichtigungen deaktivieren

Clients können einzelne Benachrichtigungen pro Verbindung unterdrücken, indem sie die exakten Methodennamen in initialize.params.capabilities.optOutNotificationMethods angeben.

  • Nur exakte Treffer zählen. item/agentMessage/delta unterdrückt ausschließlich diese Methode.
  • Unbekannte Methodennamen werden ignoriert.
  • Die Einstellung gilt für die aktuellen thread/*-, turn/*-, item/*- und zugehörigen v2-Benachrichtigungen.
  • Anfragen, Antworten und Fehler sind davon ausgenommen.

Ereignisse der unscharfen Dateisuche (experimentell)

Die Sitzungs-API für die unscharfe Dateisuche sendet für jede Suchanfrage eigene Benachrichtigungen:

  • fuzzyFileSearch/sessionUpdated liefert { sessionId, query, files } mit den aktuellen Treffern für die aktive Suchanfrage.
  • fuzzyFileSearch/sessionCompleted liefert { sessionId }, sobald die Indexierung und der Abgleich für diese Suchanfrage abgeschlossen sind.

Warnungen

  • configWarning liefert { summary, details?, path?, range? } bei behebbaren Konfigurations- oder Initialisierungsproblemen.
  • warning liefert { threadId?, message } bei Laufzeitwarnungen, die keinen Abbruch erfordern.

Ereignisse beim Setup der Windows-Sandbox

  • windowsSandbox/setupCompleted liefert { mode, success, error } nach Abschluss einer windowsSandbox/setupStart-Anfrage.

Turn-Ereignisse

  • turn/started liefert { turn } mit der Turn-ID, einem leeren items-Array und status: "inProgress".
  • turn/completed liefert { turn }. Dabei ist turn.status entweder completed, interrupted oder failed. Bei einem Fehler enthält die Nachricht { error: { message, codexErrorInfo?, additionalDetails? } }.
  • turn/diff/updated liefert { threadId, turnId, diff } mit dem aktuellen zusammengefassten Unified Diff aller Dateiänderungen im Turn.
  • turn/plan/updated liefert { turnId, explanation?, plan }, sobald der Agent seinen Plan mitteilt oder ändert. Jeder plan-Eintrag hat die Form { step, status }. Für status sind pending, inProgress und completed möglich.
  • hook/started und hook/completed liefern { threadId, turnId?, run }, wenn ein synchroner Lebenszyklus-Hook startet bzw. die abschließende Zusammenfassung vorliegt. Für asynchrone Hooks entfallen diese Benachrichtigungen.
  • model/safetyBuffering/updated liefert { threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel }, wenn eine Antwort für eine Sicherheitsprüfung vorübergehend gepuffert wird.
  • model/rerouted liefert { threadId, turnId, fromModel, toModel, reason }, wenn der Dienst eine Anfrage an ein anderes Modell weiterleitet.
  • model/verification liefert { threadId, turnId, verifications }, wenn der Dienst eine zusätzliche Kontoverifizierung verlangt.
  • thread/tokenUsage/updated meldet den aktuellen Tokenverbrauch des aktiven Threads.

turn/diff/updated und turn/plan/updated enthalten derzeit leere items-Arrays, auch wenn Elementereignisse im Stream eintreffen. Maßgeblich für die Elemente eines Turns sind die item/*-Benachrichtigungen.

Elemente

ThreadItem ist ein Union-Typ mit Typkennzeichen, den Turn-Antworten und item/*-Benachrichtigungen enthalten. Häufige Elementtypen sind:

  • userMessage enthält {id, content}. Dabei ist content eine Liste von Nutzereingaben (text, image oder localImage).
  • functionCallOutput enthält {id, name, namespace, output} für eine eigenständige Toolausgabe, die über turn/start.toolOutput übergeben wurde. namespace kann null sein.
  • agentMessage enthält in {id, text, phase?} die bisherige Antwort des Agenten. Falls vorhanden, verwendet phase die Übertragungswerte der Responses API (commentary, partial_answer, final_answer). Eine partial_answer enthält bereits feststehenden Antworttext. Weitere Ausgaben oder Toolaufrufe können folgen.
  • plan enthält in {id, text} den vorgeschlagenen Plantext im Planmodus. Maßgeblich ist das endgültige plan-Element aus item/completed.
  • reasoning enthält {id, summary, content}. Dabei enthält summary die im Stream übertragenen Reasoning-Zusammenfassungen und content die unverarbeiteten Reasoning-Blöcke.
  • commandExecution enthält {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.
  • fileChange beschreibt vorgeschlagene Änderungen mit {id, changes, status}. Die Liste changes enthält Einträge der Form {path, kind, diff}.
  • mcpToolCall erfasst id, server, tool, status und arguments des Aufrufs. Hinzu kommen appContext, mcpAppUi, pluginId, readOnlyHint, result, error und durationMs. Jedes dieser zusätzlichen Felder kann null sein. Das ältere Feld mcpAppResourceUri ist optional. Bei vertrauenswürdigen MCP-Apps enthält appContext die connectorId. Die übrigen Felder (linkId, resourceUri, appName und actionName) können null sein. Gibt der Tooldeskriptor einen Ressourcen-URI und einen Anzeigemodus (inline oder fullscreen) an, enthält mcpAppUi die Felder resourceUri und preferredModelDisplayMode. Bei Aufrufen, die ohne diese Anzeigemetadaten gespeichert wurden, liefert der App Server null für mcpAppUi.
  • dynamicToolCall enthält {id, tool, arguments, status, contentItems?, success?, durationMs?} für dynamische Toolaufrufe, die der Client ausführt.
  • collabToolCall enthält {id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}.
  • webSearch enthält {id, query, action?} für Websuchen, die der Agent anfordert.
  • imageView enthält {id, path}, wenn der Agent das Tool zur Bildansicht aufruft.
  • enteredReviewMode liefert {id, review}, wenn die Codeüberprüfung beginnt.
  • exitedReviewMode liefert {id, review}, wenn die Codeüberprüfung endet.
  • contextCompaction liefert {id}, wenn Codex den Gesprächsverlauf verdichtet.

Bei webSearch.action kann der Aktionstyp type den Wert search (query?, queries?), openPage (url?) oder findInPage (url?, pattern?) haben.

Die ältere Benachrichtigung thread/compacted des App Server ist veraltet. Verwende stattdessen das Element contextCompaction.

Für alle Elemente gibt es zwei gemeinsame Lebenszyklusereignisse:

  • item/started liefert das vollständige item, wenn ein neuer Arbeitsschritt beginnt. Die item.id entspricht der itemId in den Deltas.
  • item/completed liefert das endgültige item, sobald der Arbeitsschritt abgeschlossen ist. Dieser Zustand ist maßgeblich.

Element-Deltas

  • item/agentMessage/delta hängt den im Stream empfangenen Text an die Agentennachricht an.
  • item/plan/delta überträgt den vorgeschlagenen Plantext im Stream. Das endgültige plan-Element kann vom Text der aneinandergereihten Deltas abweichen.
  • item/reasoning/summaryTextDelta überträgt lesbare Reasoning-Zusammenfassungen. summaryIndex erhöht sich mit jedem neuen Abschnitt der Zusammenfassung.
  • item/reasoning/summaryPartAdded markiert den Übergang zwischen Abschnitten der Reasoning-Zusammenfassung.
  • item/reasoning/textDelta überträgt unverarbeiteten Reasoning-Text, sofern das Modell dies unterstützt.
  • item/commandExecution/outputDelta überträgt stdout und stderr eines Befehls. Hänge die Deltas in ihrer Empfangsreihenfolge aneinander.
  • item/fileChange/outputDelta ist eine veraltete Kompatibilitätsbenachrichtigung für die frühere Textausgabe von apply_patch. Aktuelle Versionen des App Server senden sie nicht mehr. Verwende fileChange-Elemente und turn/diff/updated.

Fehler

Weist der App Server beim geordneten Herunterfahren neue Aufträge zurück, liefert er einen JSON-RPC-Fehler mit dem Code -32600. Dabei hat data.reason den Wert serverShuttingDown.

Die Benachrichtigung error enthält ein verschachteltes error-Objekt mit message und optional additionalDetails. Sein Feld codexErrorInfo kann null sein. Hat willRetry den Wert true, versucht es der Server erneut und der Turn bleibt aktiv. Ein fehlgeschlagener Turn endet mit status: "failed". Häufige Werte für codexErrorInfo sind contextWindowExceeded, usageLimitExceeded, badRequest, unauthorized und sandboxError. Schlägt eine Anfrage an einen vorgelagerten Dienst fehl, kann der Wert ein Objekt wie { "httpConnectionFailed": { "httpStatusCode": 503 } } sein.

Genehmigungen

Je nach persönlichen Codex-Einstellungen kann für die Ausführung von Befehlen und für Dateiänderungen eine Genehmigung erforderlich sein. Der App Server sendet dazu von sich aus eine JSON-RPC-Anfrage an den Client. Der Client antwortet mit der Entscheidung.

  • Mögliche Entscheidungen für die Befehlsausführung sind accept, acceptForSession, decline, cancel oder { "acceptWithExecpolicyAmendment": { "execpolicy_amendment": ["cmd", "..."] } }.

  • Mögliche Entscheidungen für Dateiänderungen sind accept, acceptForSession, decline und cancel.

  • Anfragen enthalten threadId und turnId. Ordne damit den Zustand der Oberfläche dem aktiven Gespräch zu.

  • Der Server setzt die Arbeit fort oder lehnt sie ab und schließt das Element mit item/completed ab.

Genehmigungen für die Befehlsausführung

Reihenfolge der Nachrichten:

  1. item/started zeigt das ausstehende commandExecution-Element mit command, cwd und weiteren Feldern.
  2. item/commandExecution/requestApproval enthält itemId, threadId, turnId sowie optional reason, command, cwd, commandActions, proposedExecpolicyAmendment, networkApprovalContext und availableDecisions. Bei initialize.params.capabilities.experimentalApi = true kann die Nachricht außerdem das experimentelle Feld additionalPermissions enthalten. Es beschreibt den angeforderten Sandbox-Zugriff für diesen Befehl. Dateisystempfade in additionalPermissions werden als absolute Pfade übertragen.
  3. Der Client antwortet mit einer der oben genannten Entscheidungen zur Befehlsausführung.
  4. serverRequest/resolved bestätigt, dass die ausstehende Anfrage beantwortet oder aufgehoben wurde.
  5. item/completed liefert das endgültige commandExecution-Element mit status: completed | failed | declined.

Ist networkApprovalContext vorhanden, gilt die Genehmigungsanfrage nur für den verwalteten Netzwerkzugriff. Das aktuelle v2-Schema gibt das Ziel mit host und protocol an. Clients sollten eine netzwerkspezifische Genehmigungsanfrage anzeigen. Sie können sich nicht darauf verlassen, dass command eine für die nutzende Person aussagekräftige Vorschau des Shell-Befehls enthält.

Codex gruppiert gleichzeitige Genehmigungsanfragen für Netzwerkzugriff nach Ziel (host, Protokoll und Port). Eine einzelne Anfrage des App Server kann daher mehrere wartende Zugriffe auf dasselbe Ziel freigeben. Verschiedene Ports desselben Hosts werden getrennt behandelt.

Genehmigungen für Dateiänderungen

Reihenfolge der Nachrichten:

  1. item/started liefert ein fileChange-Element mit den vorgeschlagenen changes und status: "inProgress".
  2. item/fileChange/requestApproval enthält itemId, threadId, turnId sowie optional reason und grantRoot.
  3. Der Client antwortet mit einer der oben genannten Entscheidungen für Dateiänderungen.
  4. serverRequest/resolved bestätigt, dass die ausstehende Anfrage beantwortet oder aufgehoben wurde.
  5. item/completed liefert das endgültige fileChange-Element mit status: completed | failed | declined.

tool/requestUserInput

Wenn der Client auf item/tool/requestUserInput antwortet, sendet der App Server serverRequest/resolved mit { threadId, requestId }. Wird die ausstehende Anfrage durch den Start, Abschluss oder Abbruch eines Turns aufgehoben, bevor der Client antwortet, sendet der Server dieselbe Benachrichtigung.

Die Anfrageparameter enthalten autoResolutionMs als ganzzahligen Timeout in Millisekunden oder null. Ist eine Frist angegeben und bleibt eine Antwort aus, können Host-Clients die Anfrage nach Ablauf dieser Frist automatisch abschließen.

Berechtigungsanfragen

Das integrierte Tool request_permissions sendet item/permissions/requestApproval mit threadId, turnId, itemId, environmentId, cwd, optional reason sowie den angeforderten Netzwerk- oder Dateisystemberechtigungen. Antworte mit permissions und gib darin nur die tatsächlich gewährten Berechtigungen an. Setze scope auf "session", damit die Berechtigung auch für spätere Turns derselben Sitzung gilt. Lass das Feld weg oder verwende "turn", um sie auf den Turn zu beschränken. Nicht angeforderte Berechtigungen werden ignoriert.

Elizitationsanfragen von MCP-Servern

Ein MCP-Server kann einen Turn mit mcpServer/elicitation/request unterbrechen. Die Anfrage enthält threadId, optional turnId, serverName und eine der folgenden Strukturen:

  • mode: "form" oder mode: "openai/form" mit message und requestedSchema.
  • mode: "url" mit message, url und elicitationId.

Antworte mit action: "accept" und dem angeforderten content oder mit action: "decline" bzw. "cancel" und content: null. Anschließend sendet der App Server serverRequest/resolved. Aktiviere für den Empfang der Variante openai/form die Funktion initialize.params.capabilities.mcpServerOpenaiFormElicitation.

Dynamische Toolaufrufe (experimentell)

Das Feld dynamicTools bei thread/start und der zugehörige Anfrage- und Antwortablauf für item/tool/call gehören zur experimentellen API.

Die Namen dynamischer Tools und ihrer Namespaces müssen den Namensregeln der Responses API entsprechen. Verwende keine reservierten Namespace-Namen integrierter Codex-Tools.

Beim Aufruf eines dynamischen Tools während eines Turns läuft der Austausch mit dem App Server wie folgt ab:

  1. item/started enthält item.type = "dynamicToolCall", status = "inProgress" sowie tool und arguments.
  2. item/tool/call geht als Serveranfrage an den Client.
  3. Der Client antwortet mit den zurückgegebenen Inhaltselementen.
  4. item/completed enthält item.type = "dynamicToolCall", den endgültigen status sowie gegebenenfalls die zurückgegebenen contentItems oder den Wert von success.

Genehmigungen für MCP-Toolaufrufe (Apps)

Toolaufrufe von Apps (Konnektoren) können ebenfalls eine Genehmigung erfordern. Hat ein App-Toolaufruf Nebenwirkungen, kann der Server mit tool/requestUserInput eine Genehmigung anfordern und Optionen wie Annehmen, Ablehnen und Abbrechen anbieten. Kennzeichnet eine Annotation das Tool als destruktiv, ist immer eine Genehmigung erforderlich, auch wenn andere Hinweise geringere Berechtigungen nahelegen. Lehnt die Person ab oder bricht sie ab, endet das zugehörige mcpToolCall-Element mit einem Fehler. Das Tool wird nicht ausgeführt.

Skills

Rufe einen Skill auf, indem du $<skill-name> in die Texteingabe einfügst. Füge möglichst ein Eingabeelement vom Typ skill hinzu. Dann fügt der Server die vollständigen Skill-Anweisungen ein, ohne dass das Modell den Namen selbst auflösen muss.

{
  "method": "turn/start",
  "id": 101,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI."
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}

Wenn du das skill-Element weglässt, erkennt das Modell die Markierung $<skill-name> trotzdem und versucht, den Skill zu finden. Dadurch kann sich die Antwort verzögern.

Beispiel:

$skill-creator Erstelle einen neuen Skill zur Untersuchung sporadischer CI-Fehler und beschreibe Schritt für Schritt, wie man ihn verwendet.

Mit skills/list rufst du verfügbare Skills ab, optional beschränkt auf cwds und mit forceReload. Über perCwdExtraUserRoots kannst du zusätzliche absolute Pfade im Geltungsbereich user für bestimmte cwd-Werte durchsuchen lassen. Der App Server ignoriert Einträge, deren cwd nicht in cwds enthalten ist. skills/list kann für jedes cwd ein zwischengespeichertes Ergebnis verwenden. Setze forceReload: true, um die Daten erneut vom Datenträger zu lesen. Sofern vorhanden, liest der Server interface und dependencies aus SKILL.json.

{ "method": "skills/list", "id": 25, "params": {
  "cwds": ["/Users/me/project", "/Users/me/other-project"],
  "forceReload": true,
  "perCwdExtraUserRoots": [
    {
      "cwd": "/Users/me/project",
      "extraUserRoots": ["/Users/me/shared-skills"]
    }
  ]
} }
{ "id": 25, "result": {
  "data": [{
    "cwd": "/Users/me/project",
    "skills": [
      {
        "name": "skill-creator",
        "description": "Create or update a Codex skill",
        "enabled": true,
        "interface": {
          "displayName": "Skill Creator",
          "shortDescription": "Create or update a Codex skill"
        },
        "dependencies": {
          "tools": [
            {
              "type": "env_var",
              "value": "GITHUB_TOKEN",
              "description": "GitHub API token"
            },
            {
              "type": "mcp",
              "value": "github",
              "transport": "streamable_http",
              "url": "https://example.com/mcp"
            }
          ]
        }
      }
    ],
    "errors": []
  }]
} }

Ändern sich überwachte lokale Skill-Dateien, sendet der Server außerdem skills/changed. Betrachte dein bisheriges Ergebnis dann als veraltet und rufe bei Bedarf skills/list mit den aktuellen Parametern erneut auf.

So aktivierst oder deaktivierst du einen Skill anhand seines Pfads:

{
  "method": "skills/config/write",
  "id": 26,
  "params": {
    "path": "/Users/me/.codex/skills/skill-creator/SKILL.md",
    "enabled": false
  }
}

Apps (Konnektoren)

Mit app/installed liest du den zuletzt festgeschriebenen Laufzeitstand der installierten Apps. Jeder Eintrag enthält die App-id, den runtimeName (oder null), den wirksamen Aktivierungsstatus enabled und den Status callable. Eine App ist nur aufrufbar, wenn die wirksame Konfiguration sie aktiviert und mindestens ein für das Modell sichtbares Tool die App- und Toolrichtlinien erfüllt.

{
  "method": "app/installed",
  "id": 49,
  "params": {
    "threadId": "thread-1",
    "forceRefresh": false
  }
}
{
  "id": 49,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "runtimeName": "Demo App",
        "enabled": true,
        "callable": true
      }
    ]
  }
}

Lass threadId weg, um die globale Konfiguration statt der Konfiguration eines geladenen Threads zu verwenden. Setze forceRefresh: true, um den Laufzeitstand der Konnektoren vor dem Lesen zu aktualisieren. Wenn eine globale oder Workspace-Richtlinie den Zugriff blockiert, kann eine erkannte App weiterhin in der Liste erscheinen. In diesem Fall haben enabled und callable den Wert false.

Rufe verfügbare Apps mit app/list ab. In der CLI/TUI öffnet /apps die App-Auswahl. In eigenen Clients rufst du app/list direkt auf. Jeder Eintrag enthält sowohl isAccessible (für die Person verfügbar) als auch isEnabled (in config.toml aktiviert). So können Clients Installation und Zugänglichkeit von der lokalen Aktivierung unterscheiden. App-Einträge können außerdem die optionalen Felder branding, appMetadata und labels enthalten.

{ "method": "app/list", "id": 50, "params": {
  "cursor": null,
  "limit": 50,
  "threadId": "thread-1",
  "forceRefetch": false
} }
{ "id": 50, "result": {
  "data": [
    {
      "id": "demo-app",
      "name": "Demo App",
      "description": "Example connector for documentation.",
      "logoUrl": "https://example.com/demo-app.png",
      "logoUrlDark": null,
      "distributionChannel": null,
      "branding": null,
      "appMetadata": null,
      "labels": null,
      "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
      "isAccessible": true,
      "isEnabled": true
    }
  ],
  "nextCursor": null
} }

Wenn du threadId angibst, bestimmt der Konfigurationsstand dieses Threads, ob die App-Funktion (features.apps) verfügbar ist. Ohne diese Angabe verwendet der App Server die neueste globale Konfiguration.

app/list antwortet, sobald sowohl die zugänglichen Apps als auch die Apps aus dem Verzeichnis geladen sind. Setze forceRefetch: true, um die App-Caches zu umgehen und aktuelle Daten abzurufen. Cache-Einträge werden nur bei erfolgreicher Aktualisierung ersetzt.

Der Server sendet außerdem app/list/updated, sobald eine der beiden Quellen (zugängliche Apps oder Apps aus dem Verzeichnis) fertig geladen ist. Jede Benachrichtigung enthält die aktuelle zusammengeführte App-Liste.

{
  "method": "app/list/updated",
  "params": {
    "data": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "logoUrl": "https://example.com/demo-app.png",
        "logoUrlDark": null,
        "distributionChannel": null,
        "branding": null,
        "appMetadata": null,
        "labels": null,
        "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
        "isAccessible": true,
        "isEnabled": true
      }
    ]
  }
}

Verwende app/read, wenn du die App-IDs bereits kennst und die Metadaten der Apps statt des Laufzeitstatus der installierten Apps benötigst. Übergib höchstens 100 appIds. Bei mehrfach angegebenen IDs berücksichtigt der Server nur das erste Vorkommen. Diese Reihenfolge bleibt sowohl in apps als auch in missingAppIds erhalten. Unbekannte oder unzugängliche Apps erscheinen in missingAppIds, ohne dass die gesamte Anfrage fehlschlägt.

{
  "method": "app/read",
  "id": 52,
  "params": {
    "appIds": ["demo-app", "missing-app"],
    "includeTools": true
  }
}
{
  "id": 52,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "iconUrl": null,
        "iconUrlDark": null,
        "distributionChannel": null,
        "installUrl": null,
        "pluginDisplayNames": [],
        "toolSummaries": [
          {
            "name": "search",
            "title": "Search",
            "description": "Search the app.",
            "isEnabled": true,
            "disabledReason": null,
            "isReadOnly": true
          }
        ]
      }
    ],
    "missingAppIds": ["missing-app"]
  }
}

Setze includeTools: true, um öffentliche Toolzusammenfassungen zur Anzeige anzufordern. Die Metadatenantwort enthält keinen Laufzeitstatus der installierten Apps und autorisiert keinen Toolaufruf. Prüfe mit app/installed die wirksamen Werte von enabled und callable.

Um eine App aufzurufen, füge $<app-slug> in die Texteingabe ein. Ergänze möglichst ein Eingabeelement vom Typ mention mit dem Pfad app://<id>.

{
  "method": "turn/start",
  "id": 51,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$demo-app Pull the latest updates from the team."
      },
      {
        "type": "mention",
        "name": "Demo App",
        "path": "app://demo-app"
      }
    ]
  }
}

RPC-Beispiele zur Konfiguration von App-Einstellungen

Mit config/read, config/value/write und config/batchWrite prüfst oder änderst du die App-Einstellungen in config.toml.

Lies die wirksame App-Konfiguration einschließlich _default und abweichender Einstellungen für einzelne Tools:

{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }
{ "id": 60, "result": {
  "config": {
    "apps": {
      "_default": {
        "enabled": true,
        "destructive_enabled": true,
        "open_world_enabled": true,
        "approvals_reviewer": "user",
        "default_tools_approval_mode": "auto"
      },
      "google_drive": {
        "enabled": true,
        "destructive_enabled": false,
        "approvals_reviewer": "auto_review",
        "default_tools_approval_mode": "prompt",
        "tools": {
          "files/delete": { "enabled": false, "approval_mode": "approve" }
        }
      }
    }
  }
} }

apps._default.approvals_reviewer legt fest, wer Genehmigungsanfragen für alle Apps prüft, sofern für eine einzelne App kein anderer Wert festgelegt ist. Fehlen beide Angaben, übernimmt die App den Wert von approvals_reviewer auf oberster Ebene. apps._default.default_tools_approval_mode legt den Standardmodus für Tools fest, für die weder auf App- noch auf Toolebene eine abweichende Einstellung gilt. Verwaltete Vorgaben für den Genehmigungsmodus haben Vorrang vor den Einstellungen einzelner Tools.

Eine einzelne App-Einstellung aktualisieren:

{
  "method": "config/value/write",
  "id": 61,
  "params": {
    "keyPath": "apps.google_drive.default_tools_approval_mode",
    "value": "prompt",
    "mergeStrategy": "replace"
  }
}

Mehrere App-Einstellungen atomar ändern:

{
  "method": "config/batchWrite",
  "id": 62,
  "params": {
    "edits": [
      {
        "keyPath": "apps._default.destructive_enabled",
        "value": false,
        "mergeStrategy": "upsert"
      },
      {
        "keyPath": "apps.google_drive.tools.files/delete.approval_mode",
        "value": "approve",
        "mergeStrategy": "upsert"
      }
    ]
  }
}

Konfiguration externer Agenten erkennen und importieren

Ermittle mit externalAgentConfig/detect, welche Artefakte externer Agenten sich migrieren lassen. Übergib die ausgewählten Einträge anschließend an externalAgentConfig/import.

Beispiel für die Erkennung:

{ "method": "externalAgentConfig/detect", "id": 63, "params": {
  "includeHome": true,
  "cwds": ["/Users/me/project"]
} }
{ "id": 63, "result": {
  "items": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    },
    {
      "itemType": "SKILLS",
      "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",
      "cwd": null
    }
  ]
} }

Beispiel für den Import:

{ "method": "externalAgentConfig/import", "id": 64, "params": {
  "migrationItems": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    }
  ],
  "source": "claude-code"
} }
{ "id": 64, "result": { "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868" } }

Der optionale Importparameter source auf oberster Ebene bezeichnet das Produkt, aus dem die ausgewählten Migrationseinträge stammen.

Der Server sendet externalAgentConfig/import/progress, sobald die Verarbeitung eines Elementtyps abgeschlossen ist, und externalAgentConfig/import/completed, sobald alle synchronen Importe und Hintergrundimporte abgeschlossen sind. Beide Benachrichtigungen enthalten dieselbe importId wie die Antwort sowie itemTypeResults mit successes und failures für jeden Typ. Die Abschlussmeldung kann unmittelbar nach der Antwort oder nach Abschluss der Remote-Importe im Hintergrund eintreffen.

{ "method": "externalAgentConfig/import/progress", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }
{ "method": "externalAgentConfig/import/completed", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }

Frühere abgeschlossene Importe abrufen:

{ "method": "externalAgentConfig/import/readHistories", "id": 65 }
{ "id": 65, "result": { "data": [
  {
    "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
    "completedAtMs": 1781784000000,
    "successes": [
      { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
    ],
    "failures": []
  }
] } }

Unterstützte Werte für itemType sind AGENTS_MD, CONFIG, SKILLS, PLUGINS, MCP_SERVER_CONFIG, SUBAGENTS, HOOKS, COMMANDS und SESSIONS. Für Elemente vom Typ PLUGINS enthält details.plugins jeweils den marketplaceName und die pluginNames, deren Migration Codex versuchen kann. Die Erkennung liefert nur Einträge, für die noch Arbeit aussteht. Codex überspringt beispielsweise die AGENTS-Migration, wenn AGENTS.md bereits existiert und nicht leer ist. Beim Skill-Import werden vorhandene Skill-Verzeichnisse nicht überschrieben.

Bei der Erkennung von Plugins aus .claude/settings.json liest Codex die konfigurierten Marketplace-Quellen aus extraKnownMarketplaces. Enthält enabledPlugins Plugins aus claude-plugins-official, fehlt aber die Marketplace-Quelle, verwendet Codex anthropics/claude-plugins-official als abgeleitete Quelle.

Endpunkte für die Authentifizierung

Wenn du eine lokale oder quelloffene Anwendung mit der Authentifizierung des Codex App Server entwickelt hast, kannst du diese Authentifizierung weiterhin verwenden. Wir empfehlen den Umstieg auf „Mit ChatGPT anmelden“, damit Nutzende ihren Verbrauch besser einsehen und steuern können. Weitere Informationen findest du in der Entwicklungsdokumentation zu „Mit ChatGPT anmelden“ und in unserem Leitfaden zur Implementierung. Für kommerzielle oder gehostete Dienste war die Authentifizierung des App Server zu keinem Zeitpunkt zulässig. Für diese Anwendungsfälle haben wir „Mit ChatGPT anmelden“ eingeführt. Wir sind gespannt, welche Anwendungen du damit entwickelst. Trag dich in unsere Warteliste für Partner ein.

Die JSON-RPC-Schnittstelle für Authentifizierung und Konten bietet Methoden mit Anfrage und Antwort sowie vom Server initiierte Benachrichtigungen ohne id. Damit kannst du den Authentifizierungsstatus ermitteln, Anmeldungen starten oder abbrechen, dich abmelden, ChatGPT-Ratenlimits prüfen und die für einen Workspace verantwortlichen Personen über aufgebrauchte Credits oder erreichte Nutzungslimits informieren.

Authentifizierungsmodi

Codex unterstützt die folgenden Authentifizierungsmodi. account/updated.authMode zeigt den aktiven Modus. Die Benachrichtigung enthält außerdem den aktuellen planType für ChatGPT, sofern verfügbar. account/read liefert ebenfalls Angaben zu Konto und Plan.

  • API-Schlüssel (apikey): Der aufrufende Client übergibt einen OpenAI-API-Schlüssel mit type: "apiKey". Codex speichert ihn für API-Anfragen.
  • Verwaltete ChatGPT-Anmeldung (chatgpt): Codex übernimmt den OAuth-Ablauf für ChatGPT, speichert Token dauerhaft und aktualisiert sie automatisch. Starte den Browserablauf mit type: "chatgpt" oder die Anmeldung per Gerätecode mit type: "chatgptDeviceCode".
  • Externe ChatGPT-Token (chatgptAuthTokens): Dieser experimentelle Modus ist für Host-Apps vorgesehen, die die ChatGPT-Authentifizierung der nutzenden Person bereits selbst verwalten. Die Host-App übergibt accessToken, chatgptAccountId und optional chatgptPlanType direkt. Auf Anforderung muss sie das Token aktualisieren.
  • Amazon Bedrock: account/read meldet Bedrock-Konten als type: "amazonBedrock" und gibt an, ob die Zugangsdaten aus einem von Codex verwalteten Bedrock-API-Schlüssel (credentialSource: "codexManaged") oder aus der externen AWS-Anmeldeinformationskette (credentialSource: "awsManaged") stammen. account/updated.authMode verwendet für von Codex verwaltete Bedrock-API-Schlüssel den Wert bedrockApiKey.

API-Überblick

  • account/read ruft die aktuellen Kontoinformationen ab und aktualisiert optional die Token.
  • account/login/start startet die Anmeldung (apiKey, chatgpt, chatgptDeviceCode oder experimentell chatgptAuthTokens).
  • account/login/completed (Benachrichtigung) meldet den Abschluss eines Anmeldeversuchs, unabhängig davon, ob er erfolgreich war oder fehlgeschlagen ist.
  • account/login/cancel bricht eine ausstehende verwaltete ChatGPT-Anmeldung anhand der loginId ab.
  • account/logout meldet das Konto ab und löst account/updated aus.
  • account/updated (Benachrichtigung) meldet Änderungen des Authentifizierungsmodus (authMode mit apikey, chatgpt, chatgptAuthTokens, agentIdentity, personalAccessToken, bedrockApiKey oder null) und enthält planType, sofern verfügbar.
  • account/chatgptAuthTokens/refresh (Serveranfrage) fordert nach einem Autorisierungsfehler neue extern verwaltete ChatGPT-Token an.
  • account/rateLimits/read ruft die ChatGPT-Ratenlimits ab.
  • account/rateLimits/updated (Benachrichtigung) meldet Änderungen der persönlichen ChatGPT-Ratenlimits.
  • account/sendAddCreditsNudgeEmail fordert ChatGPT auf, die für den Workspace verantwortliche Person per E-Mail über aufgebrauchte Credits oder ein erreichtes Nutzungslimit zu informieren.
  • account/rateLimitResetCredit/consume löst mit einem vom Client bereitgestellten idempotencyKey eine erworbene Rücksetzung des Ratenlimits ein.
  • account/usage/read ruft Zusammenfassungen und Tageswerte zur Tokennutzung des ChatGPT-Kontos ab.
  • account/workspaceMessages/read ruft aktive Workspace-Nachrichten einschließlich verfügbarer Benachrichtigungsüberschriften ab.
  • mcpServer/oauthLogin/completed (Benachrichtigung) meldet den Abschluss eines mcpServer/oauth/login-Ablaufs und enthält { name, threadId, loginId?, success, error? }. Ältere Server lassen loginId weg. threadId kann bei App-bezogenen oder Plugin-OAuth-Abläufen null sein.
  • mcpServer/startupStatus/updated (Benachrichtigung) meldet Änderungen am Startstatus eines konfigurierten MCP-Servers und enthält { threadId, name, status, error, failureReason }. Bei einem Start auf App-Ebene ist threadId gleich null. Schlägt der Start fehl, bedeutet failureReason: "reauthenticationRequired", dass die gespeicherten OAuth-Zugangsdaten abgelaufen sind und nicht aktualisiert werden konnten. Der Client sollte dann anbieten, die Verbindung zum Server neu herzustellen.

Bei einem konfigurierten Gateway anmelden

Wenn dein Client die Gateway-Anmeldung übernimmt, setze capabilities.explicitGatewayOauth bei der Initialisierung auf true. Rufe für jede Verbindung zuerst account/gatewayOAuth/read auf. Sende authentifizierte Anfragen erst, wenn dieser Aufruf erfolgreich war. Übergib modelProvider, um den Anmeldestatus eines bestimmten Gateways zu prüfen oder dich dort anzumelden. Ohne diese Angabe verwendet der Server den aktuellen Anbieter.

Prüfe für die Anmeldung per Gerätecode, ob account/gatewayOAuth/read den Wert supportsDeviceAuth: true zurückgibt. Rufe account/gatewayOAuth/login mit demselben modelProvider und deviceAuth: true auf. Hat der Prompt den Wert null, hat der Server die Zugangsdaten wiederverwendet oder aktualisiert. Zeige andernfalls prompt.verificationUrl und prompt.userCode an. Warte dann auf die Benachrichtigung account/gatewayOAuth/changed mit der passenden loginId. Sie gibt an, ob die Anmeldung erfolgreich war.

1) Authentifizierungsstatus prüfen

Anfrage:

{ "method": "account/read", "id": 1, "params": { "refreshToken": false } }

Beispiele für Antworten:

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": false } }
{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": true } }
{
  "id": 1,
  "result": { "account": { "type": "apiKey" }, "requiresOpenaiAuth": true }
}
{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "codexManaged"
    },
    "requiresOpenaiAuth": false
  }
}
{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "awsManaged"
    },
    "requiresOpenaiAuth": false
  }
}
{
  "id": 1,
  "result": {
    "account": {
      "type": "chatgpt",
      "email": "user@example.com",
      "planType": "pro"
    },
    "requiresOpenaiAuth": true
  }
}

Hinweise zu den Feldern:

  • refreshToken (boolesch): Setze den Wert auf true, um im verwalteten ChatGPT-Modus eine Tokenaktualisierung zu erzwingen. Im Modus für externe Token (chatgptAuthTokens) ignoriert der App Server dieses Flag.
  • email ist null, wenn dem ChatGPT-Konto keine E-Mail-Adresse zugeordnet ist.
  • requiresOpenaiAuth richtet sich nach dem aktiven Anbieter. Bei false kann Codex ohne OpenAI-Zugangsdaten ausgeführt werden.
  • Amazon Bedrock meldet credentialSource: "codexManaged", wenn es einen von Codex verwalteten Bedrock-API-Schlüssel verwendet. Für die externe AWS-Anmeldeinformationskette meldet es credentialSource: "awsManaged". Der Wert bezeichnet die ausgewählte Quelle. Er bestätigt nicht, dass die AWS-Anmeldeinformationskette tatsächlich Zugangsdaten liefern kann.

2) Mit einem API-Schlüssel anmelden

  1. Sende folgende Anfrage:

    {
      "method": "account/login/start",
      "id": 2,
      "params": { "type": "apiKey", "apiKey": "sk-..." }
    }
  2. Erwarte folgende Antwort:

    { "id": 2, "result": { "type": "apiKey" } }
  3. Benachrichtigungen:

    {
      "method": "account/login/completed",
      "params": { "loginId": null, "success": true, "error": null }
    }
    {
      "method": "account/updated",
      "params": { "authMode": "apikey", "planType": null }
    }

3) Mit ChatGPT im Browser anmelden

  1. Starte die Anmeldung:

    {
      "method": "account/login/start",
      "id": 3,
      "params": {
        "type": "chatgpt",
        "useHostedLoginSuccessPage": true,
        "appBrand": "chatgpt"
      }
    }

    Standardmäßig leitet ein erfolgreicher Browser-Callback auf eine lokale Bestätigungsseite weiter. Setze useHostedLoginSuccessPage: true, um die gehostete Bestätigungsseite zu verwenden, wenn kein Organisations-Setup erforderlich ist. Bei aktivierter gehosteter Bestätigungsseite kann appBrand den Wert "codex" oder "chatgpt" haben. Fehlt die Angabe oder ist sie null, gilt "codex".

    {
      "id": 3,
      "result": {
        "type": "chatgpt",
        "loginId": "<uuid>",
        "authUrl": "https://chatgpt.com/...&redirect_uri=http%3A%2F%2Flocalhost%3A<port>%2Fauth%2Fcallback"
      }
    }
  2. Öffne authUrl in einem Browser. Der App Server stellt den lokalen Callback bereit.

  3. Warte auf die Benachrichtigungen:

    {
      "method": "account/login/completed",
      "params": { "loginId": "<uuid>", "success": true, "error": null }
    }
    {
      "method": "account/updated",
      "params": { "authMode": "chatgpt", "planType": "plus" }
    }

3b) Mit ChatGPT per Gerätecode anmelden

Verwende diesen Ablauf, wenn dein Client die Anmeldung selbst steuert oder ein Browser-Callback unzuverlässig ist.

  1. Starte die Anmeldung:

    {
      "method": "account/login/start",
      "id": 4,
      "params": { "type": "chatgptDeviceCode" }
    }
    {
      "id": 4,
      "result": {
        "type": "chatgptDeviceCode",
        "loginId": "<uuid>",
        "verificationUrl": "https://auth.openai.com/codex/device",
        "userCode": "ABCD-1234"
      }
    }
  2. Zeige der Person, die sich anmeldet, verificationUrl und userCode an. Die Gestaltung des Ablaufs übernimmt das Frontend.

  3. Warte auf die Benachrichtigungen:

    {
      "method": "account/login/completed",
      "params": { "loginId": "<uuid>", "success": true, "error": null }
    }
    {
      "method": "account/updated",
      "params": { "authMode": "chatgpt", "planType": "plus" }
    }

3c) Mit extern verwalteten ChatGPT-Token anmelden (chatgptAuthTokens)

Verwende diesen experimentellen Modus nur, wenn die Host-Anwendung die ChatGPT-Authentifizierung der nutzenden Person selbst verwaltet und die Token direkt bereitstellt. Clients müssen capabilities.experimentalApi = true beim Aufruf von initialize setzen, bevor sie diese Anmeldeart verwenden.

  1. Sende folgende Anfrage:

    {
      "method": "account/login/start",
      "id": 7,
      "params": {
        "type": "chatgptAuthTokens",
        "accessToken": "<jwt>",
        "chatgptAccountId": "org-123",
        "chatgptPlanType": "business"
      }
    }
  2. Erwarte folgende Antwort:

    { "id": 7, "result": { "type": "chatgptAuthTokens" } }
  3. Benachrichtigungen:

    {
      "method": "account/login/completed",
      "params": { "loginId": null, "success": true, "error": null }
    }
    {
      "method": "account/updated",
      "params": { "authMode": "chatgptAuthTokens", "planType": "business" }
    }

Erhält der Server 401 Unauthorized, kann er bei der Host-App aktualisierte Token anfordern:

{
  "method": "account/chatgptAuthTokens/refresh",
  "id": 8,
  "params": { "reason": "unauthorized", "previousAccountId": "org-123" }
}
{ "id": 8, "result": { "accessToken": "<jwt>", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } }

Nach einer erfolgreichen Antwort auf die Aktualisierungsanfrage wiederholt der Server die ursprüngliche Anfrage. Das Zeitlimit für Anfragen beträgt etwa zehn Sekunden.

4) Eine ChatGPT-Anmeldung abbrechen

{ "method": "account/login/cancel", "id": 4, "params": { "loginId": "<uuid>" } }
{ "method": "account/login/completed", "params": { "loginId": "<uuid>", "success": false, "error": "..." } }

5) Abmelden

{ "method": "account/logout", "id": 5 }
{ "id": 5, "result": {} }
{ "method": "account/updated", "params": { "authMode": null, "planType": null } }

6) Ratenlimits (ChatGPT)

{ "method": "account/rateLimits/read", "id": 6 }
{ "id": 6, "result": {
  "rateLimits": {
    "limitId": "codex",
    "limitName": null,
    "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
    "secondary": null,
    "rateLimitReachedType": null
  },
  "rateLimitsByLimitId": {
    "codex": {
      "limitId": "codex",
      "limitName": null,
      "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
      "secondary": null,
      "rateLimitReachedType": null
    },
    "codex_other": {
      "limitId": "codex_other",
      "limitName": "codex_other",
      "primary": { "usedPercent": 42, "windowDurationMins": 60, "resetsAt": 1730950800 },
      "secondary": null,
      "rateLimitReachedType": null
    }
  },
  "rateLimitResetCredits": {
    "availableCount": 2,
    "credits": [{
      "id": "RateLimitResetCredit_1",
      "resetType": "codexRateLimits",
      "status": "available",
      "grantedAt": 1781654400,
      "expiresAt": 1784246400,
      "title": "Rate-limit reset",
      "description": "Reset an eligible Codex rate-limit window."
    }]
  }
} }
{ "method": "account/rateLimits/updated", "params": {
  "rateLimits": {
    "limitId": "codex",
    "primary": { "usedPercent": 31, "windowDurationMins": 15, "resetsAt": 1730948100 }
  }
} }

Hinweise zu den Feldern:

  • rateLimits ist die abwärtskompatible Ansicht für ein einzelnes Kontingent.
  • rateLimitsByLimitId enthält, sofern vorhanden, die Ansicht für mehrere Kontingente. Als Schlüssel dient die limit_id der jeweiligen Verbrauchsmessung, etwa codex.
  • limitId bezeichnet das Kontingent, dessen Verbrauch gemessen wird.
  • limitName ist ein optionaler Anzeigename für das Kontingent.
  • usedPercent gibt den aktuellen prozentualen Verbrauch innerhalb des Kontingentzeitfensters an.
  • windowDurationMins gibt die Länge des Kontingentzeitfensters an.
  • resetsAt ist der Unix-Zeitstempel in Sekunden für die nächste Rücksetzung.
  • planType ist enthalten, wenn der Server den einem Kontingent zugeordneten ChatGPT-Plan zurückgibt.
  • credits ist enthalten, wenn der Server Details zu verbleibenden Workspace-Credits zurückgibt.
  • rateLimitReachedType bezeichnet den vom Server ermittelten Limitstatus, wenn ein Limit erreicht wurde.
  • rateLimitResetCredits enthält die Anzahl verfügbarer erworbener Rücksetzungen, sofern der Dienst sie bereitstellt. Andernfalls ist der Wert null.
  • rateLimitResetCredits.credits ist null, wenn nur die Anzahl bekannt ist. Ein leeres Array bedeutet, dass der Dienst die Details abgerufen und keine verfügbaren Credits zurückgegeben hat. Der Dienst kann die Anzahl der Detaileinträge begrenzen. Maßgeblich ist daher availableCount.
  • Jeder Detaileintrag enthält eine opake id, resetType, status, grantedAt, expiresAt (kann null sein), title (kann null sein) und description (kann null sein).
  • Rufe nach dem Einlösen einer Rücksetzung account/rateLimits/read auf.

7) Tokennutzung (ChatGPT)

Mit account/usage/read rufst du Kennzahlen zur Tokennutzung in ChatGPT und optional Tageswerte ab.

{ "method": "account/usage/read", "id": 7 }
{ "id": 7, "result": {
  "summary": {
    "lifetimeTokens": 1234567,
    "peakDailyTokens": 45678,
    "longestRunningTurnSec": 540,
    "currentStreakDays": 8,
    "longestStreakDays": 14
  },
  "dailyUsageBuckets": [
    { "startDate": "2026-06-18", "tokens": 12345 }
  ]
} }

Hinweise zu den Feldern:

  • Werte in summary können null sein, wenn der Dienst die jeweilige Kennzahl nicht zurückgegeben hat.
  • dailyUsageBuckets kann null sein. Liegen Tageswerte vor, enthält jeder Eintrag startDate und tokens.
  • Der Endpunkt erfordert eine Authentifizierung über Codex-Dienste. Unterstützt werden ChatGPT, externe ChatGPT-Token, Agentenidentität und persönliche Zugriffstoken. Eine Authentifizierung ausschließlich per API-Schlüssel oder über Bedrock reicht nicht aus.

8) Erworbene Rücksetzungen des Ratenlimits (ChatGPT)

Mit account/rateLimitResetCredit/consume löst du eine erworbene Rücksetzung ein.

{ "method": "account/rateLimitResetCredit/consume", "id": 8, "params": { "idempotencyKey": "8ae96ff3-3425-4f4c-8772-b6fd61502868", "creditId": "RateLimitResetCredit_1" } }
{ "id": 8, "result": { "outcome": "reset" } }

Hinweise zu den Feldern:

  • idempotencyKey darf nicht leer sein. Verwende für jeden eigenständigen Einlösevorgang eine UUID. Wiederholst du die Anfrage für denselben Vorgang, verwende dieselbe UUID erneut.
  • creditId ist optional. Wenn du sie angibst, muss sie eine nicht leere opake ID aus account/rateLimits/read sein. Ohne diese Angabe wählt der Dienst den nächsten verfügbaren Credit aus.
  • reset bedeutet, dass ein Credit eingelöst wurde.
  • alreadyRedeemed bedeutet, dass derselbe Einlösevorgang bereits abgeschlossen wurde. Behandle dies als idempotenten Erfolg und aktualisiere die Kontolimits.
  • nothingToReset bedeutet, dass kein Ratenlimit-Zeitfenster für eine Rücksetzung infrage kommt.
  • noCredit bedeutet, dass für das Konto keine erworbenen Credits zur Rücksetzung verfügbar sind.
  • Rufe nach dem Einlösen einer Rücksetzung account/rateLimits/read auf, um die aktualisierten Zeitfenster abzurufen. Leite sie nicht aus der Antwort auf die Einlösung ab.

9) Die für den Workspace verantwortliche Person über ein Limit informieren

Mit account/sendAddCreditsNudgeEmail forderst du ChatGPT auf, die für den Workspace verantwortliche Person per E-Mail zu benachrichtigen, wenn die Credits aufgebraucht sind oder ein Nutzungslimit erreicht wurde.

{ "method": "account/sendAddCreditsNudgeEmail", "id": 9, "params": { "creditType": "credits" } }
{ "id": 9, "result": { "status": "sent" } }

Verwende creditType: "credits", wenn die Workspace-Credits aufgebraucht sind, oder creditType: "usage_limit", wenn das Nutzungslimit des Workspace erreicht wurde. Wurde die verantwortliche Person vor Kurzem bereits benachrichtigt, lautet der Antwortstatus cooldown_active.

10) Workspace-Nachrichten (ChatGPT)

Mit account/workspaceMessages/read rufst du aktive Nachrichten für den aktuellen Workspace ab, einschließlich der Überschriften von Benachrichtigungen, sofern verfügbar.

{ "method": "account/workspaceMessages/read", "id": 10 }
{ "id": 10, "result": { "featureEnabled": true, "messages": [
  { "messageId": "msg_123", "messageType": "headline", "messageBody": "Workspace maintenance starts at 5pm.", "createdAt": 1781395200, "archivedAt": null }
] } }