Ü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 /readyzgibt200 OKzurück, sobald der Listener neue Verbindungen annimmt.GET /healthzgibt200 OKzurück, wenn die Anfrage keinenOrigin-Header enthält.- Anfragen mit einem
Origin-Header weist der Server mit403 Forbiddenzurü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
- Starte den Server mit
codex app-server(Standardtransport über stdio),codex app-server --listen ws://127.0.0.1:4500(WebSocket über TCP) odercodex app-server --listen unix://(standardmäßiger Unix-Socket). - Verbinde einen Client über den ausgewählten Transport. Sende dann
initializeund anschließend die Benachrichtigunginitialized. - 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ßendinitialized. Vor diesem Handshake weist der Server alle anderen Anfragen über diese Verbindung zurück. - Thread starten oder fortsetzen: Rufe
thread/startfür ein neues Gespräch auf,thread/resume, um ein bestehendes fortzusetzen, oderthread/fork, um den Verlauf unter einer neuen Thread-ID zu forken. - Turn beginnen: Rufe
turn/startmit der gewünschtenthreadIdund der Nutzereingabe auf. Über optionale Felder kannst du das Modell, das Arbeitsverzeichnis und die Sandbox-Richtlinie überschreiben. - Aktiven Turn steuern: Rufe
turn/steerauf, um dem laufenden Turn weitere Nutzereingaben hinzuzufügen, ohne einen neuen Turn zu erstellen. - Ereignisse im Stream lesen: Lies nach
turn/startweiter die Benachrichtigungen auf stdout, darunterthread/archived,thread/unarchived,item/started,item/completed,item/agentMessage/delta, Fortschrittsmeldungen von Tools und weitere Aktualisierungen. - Turn abschließen: Der Server sendet
turn/completedmit dem endgültigen Status, sobald das Modell fertig ist oder der Turn durchturn/interruptabgebrochen 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:
optOutNotificationMethodsgibt 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.requestAttestationaktiviert die vom Server initiierte Anfrageattestation/generate. Desktop-Hosts, die eine Attestierung für vorgelagerte Dienste bereitstellen, antworten mit einem opaken Wert der Form{ "token": "..." }.mcpServerOpenaiFormElicitationerlaubt nachgelagerten MCP-Servern, die erweiterte Formularvariante von OpenAI fürmcpServer/elicitation/requestzu 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
capabilitiesweg oder setzeexperimentalApiauffalse, um ausschließlich die stabile API zu verwenden. Der Server weist experimentelle Methoden und Felder dann zurück. - Setze
capabilities.experimentalApiauftrue, 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/starterstellt einen Thread, sendetthread/startedund 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 vonturn/startihn fortsetzen.thread/forkforkt einen Thread unter einer neuen ID, indem es den gespeicherten Verlauf kopiert. ÜbergiblastTurnId, um den Verlauf bis einschließlich dieses Turns zu kopieren und spätere Turns auszulassen, oderephemeral: truefür einen Fork im Arbeitsspeicher. Die Methode sendetthread/startedfür den neuen Thread. Zurückgegebene Threads enthaltenforkedFromId, sofern verfügbar.thread/readliest gespeicherte Thread-Metadaten anhand der ID, ohne den Thread fortzusetzen. Lade den Verlauf mitthread/turns/listundthread/items/list. Die zurückgegebenenthread-Objekte enthalten den Laufzeitstatusstatus.thread/listliefert gespeicherte Threads und ihren Laufzeitstatus seitenweise. Weitere Informationen findest du im Abschnitt Paginierung und Filter.thread/turns/listliest die gespeicherten Turns eines Threads seitenweise, ohne ihn fortzusetzen.itemsViewlegt fest, ob die Elemente der Turns ausgelassen, zusammengefasst oder vollständig geladen werden.thread/items/listliest gespeicherte Thread-Elemente seitenweise, optional beschränkt auf eineturnId. Der aktive Thread-Speicher muss die Paginierung von Elementen unterstützen.thread/loaded/listlistet die IDs der aktuell im Arbeitsspeicher geladenen Threads auf.thread/name/setsetzt oder aktualisiert den sichtbaren Namen eines geladenen Threads oder einer gespeicherten Sitzungsaufzeichnung und sendetthread/name/updated.thread/goal/setlegt das Ziel eines Threads fest und sendetthread/goal/updated.thread/goal/getliest das aktuelle Ziel eines Threads.thread/goal/clearentfernt das Ziel eines Threads und sendetthread/goal/cleared.thread/metadata/updateaktualisiert die für einen Thread gespeicherten Git-Metadaten.thread/archiveverschiebt 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 Threadthread/archived.thread/deletelö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 Threadthread/deleted.thread/unsubscribebeendet 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 sendetthread/closed.thread/unarchiveverschiebt eine archivierte Thread-Aufzeichnung zurück in das Verzeichnis der aktiven Sitzungen, gibt den wiederhergestelltenthreadzurück und sendetthread/unarchived.thread/status/changedist eine Benachrichtigung, die der Server sendet, wenn sich der Laufzeitwertstatuseines geladenen Threads ändert.thread/compact/startstartet die Kontextverdichtung für den Gesprächsverlauf eines Threads. Die Methode gibt sofort{}zurück und meldet den Fortschritt überturn/*- unditem/*-Benachrichtigungen.thread/shellCommandfü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/cleanstoppt alle laufenden Hintergrundterminals eines Threads (experimentell, erfordertcapabilities.experimentalApi).thread/backgroundTerminals/listlistet die laufenden Hintergrundterminals eines geladenen Threads auf (experimentell, erfordertcapabilities.experimentalApi).thread/backgroundTerminals/terminatebeendet ein laufendes Hintergrundterminal anhand der vom App Server vergebenenprocessId(experimentell, erfordertcapabilities.experimentalApi).thread/revertentfernt 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ßendthread/reverted.turn/startfügt einem Thread Nutzereingaben oder eine eigenständige Toolausgabe hinzu und startet die Generierung durch Codex. Die Antwort enthält den anfänglichenturn, weitere Ereignisse folgen im Stream. FürcollaborationModebedeutetsettings.developer_instructions: null„die integrierten Anweisungen für den ausgewählten Modus verwenden“.thread/inject_itemsfügt dem für das Modell sichtbaren Verlauf eines geladenen Threads unverarbeitete Elemente der Responses API hinzu, ohne einen Nutzer-Turn zu starten.turn/steerfügt dem laufenden Turn eines Threads Nutzereingaben hinzu und gibt die akzeptierteturnIdzurück.turn/interruptfordert den Abbruch eines laufenden Turns an. Bei Erfolg lautet die Antwort{}, und der Turn endet mitstatus: "interrupted".review/startstartet das Code Review durch Codex für einen Thread und sendet Elemente vom TypenteredReviewModeundexitedReviewMode.command/execführt einen einzelnen Befehl in der Sandbox des Servers aus, ohne einen Thread oder Turn zu starten.command/exec/writeschreibt Bytes instdineiner laufendencommand/exec-Sitzung oder schließtstdin.command/exec/resizeändert die Terminalgröße einer laufendencommand/exec-Sitzung mit PTY.command/exec/terminatestoppt eine laufendecommand/exec-Sitzung.command/exec/outputDelta(Benachrichtigung) liefert Base64-kodierte Abschnitte von stdout und stderr aus einercommand/exec-Sitzung mit Streaming.process/spawnstartet explizit eine Prozesssitzung außerhalb der Codex-Sandbox (experimentell, erfordertcapabilities.experimentalApi).process/writeStdinschreibt Bytes in stdin einer laufendenprocess/spawn-Sitzung oder schließt stdin (experimentell).process/resizePtyändert die Terminalgröße einer laufenden Prozesssitzung mit PTY (experimentell).process/killbeendet eine laufende Prozesssitzung (experimentell).process/outputDeltaundprocess/exited(Benachrichtigungen) liefern die laufende Prozessausgabe und den Beendigungsstatus (experimentell).model/listlistet verfügbare Modelle auf (mitincludeHidden: trueauch Einträge mithidden: true). Jeder Eintrag enthält Optionen für den Reasoning-Aufwand, optionalupgradesowieinputModalities.modelProvider/capabilities/readliest die vom Anbieter vorgegebenen Funktionsgrenzen für Kombinationen aus Modell und Anbieter.experimentalFeature/listlistet Feature-Flags mit Metadaten zur Entwicklungsphase auf und unterstützt cursorbasierte Paginierung.experimentalFeature/enablement/setaktualisiert Laufzeiteinstellungen im Arbeitsspeicher für unterstützte Funktionsschlüssel wieappsundplugins.environment/infoverbindet sich mit einer konfigurierten Ausführungsumgebung und gibt deren Shell und Standardarbeitsverzeichnis zurück (experimentell).permissionProfile/listlistet Berechtigungsprofile in der Betaphase auf und gibt an, ob die geltenden Vorgaben sie zulassen. Die Methode unterstützt cursorbasierte Paginierung.collaborationMode/listlistet Voreinstellungen für den Zusammenarbeitsmodus auf (experimentell, ohne Paginierung).skills/listlistet Skills für einen oder mehrerecwd-Werte auf und unterstütztforceReloadsowie optionalperCwdExtraUserRoots.skills/extraRoots/setersetzt 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/listlistet die gefundenen Lebenszyklus-Hooks für einen oder mehrerecwd-Werte auf.marketplace/addfügt einen Remote-Marketplace für Plugins hinzu und speichert ihn in der persönlichen Marketplace-Konfiguration.marketplace/removeentfernt einen konfigurierten Marketplace und, sofern vorhanden, dessen installiertes Stammverzeichnis.marketplace/upgradeaktualisiert einen konfigurierten Git-Marketplace. Ohne Marketplace-Namen aktualisiert die Methode alle konfigurierten Git-Marketplaces.plugin/listbefindet 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-Versionversion, die lokale VersionlocalVersion, strukturierte Symbole für helle und dunkle Oberflächen sowieinstallPolicySourceenthalten. Bei aktuellen Remote-Einträgen kann der Wertnull,WORKSPACE_SETTINGoderIMPLICIT_CANONICAL_APPsein. Rufe diese Methode noch nicht aus Clients im Produktivbetrieb auf.plugin/readbefindet 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 eineshareUrl, sofern der Remote-Katalog eine bereitstellt. Rufe diese Methode noch nicht aus Clients im Produktivbetrieb auf.plugin/installbefindet 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/uninstallbefindet sich in Entwicklung und deinstalliert ein installiertes Plugin. Rufe diese Methode noch nicht aus Clients im Produktivbetrieb auf.plugin/skill/readliest bei Bedarf den Markdown-Text eines Remote-Plugin-Skills anhand von Remote-Marketplace, Plugin-ID und Skill-Namen.app/installedliest den Laufzeitstatus installierter Apps und gibt für jede App an, ob sie effektiv aktiviert und aufrufbar ist.app/listlistet verfügbare Apps (Konnektoren) seitenweise auf und gibt an, ob sie zugänglich und aktiviert sind.app/readruft für bestimmte App-IDs Metadaten und optional Toolzusammenfassungen zur Anzeige ab.skills/config/writeaktiviert oder deaktiviert Skills anhand ihres Pfads.mcpServer/oauth/loginstartet eine OAuth-Anmeldung für einen konfigurierten MCP-Server. Öffne die zurückgegebene HTTP- oder HTTPS-AdresseauthorizationUrlund ordne anhand derloginIddie zugehörige BenachrichtigungmcpServer/oauthLogin/completedzu.tool/requestUserInputstellt der nutzenden Person für einen Toolaufruf eine bis drei kurze Fragen (experimentell). MitisOtherkann 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 Toolrequest_permissionsangefordert hat.config/mcpServer/reloadlädt die MCP-Serverkonfiguration erneut vom Datenträger und reiht eine Aktualisierung für geladene Threads ein.mcpServerStatus/listlistet MCP-Server, Tools, Ressourcen und den Authentifizierungsstatus auf (Paginierung mit Cursor und Limit). Verwendedetail: "full"für alle Daten oderdetail: "toolsAndAuthOnly", um Ressourcen auszulassen. Beide Modi liefern die vom Server gemeldetenserverCapabilities, vor erfolgreicher Initialisierung den Wertnull. ÜbergibserverName, um einen einzelnen Server abzufragen. MitthreadIdnutzt die Anfrage die bestehende MCP-Verbindung dieses Threads.mcpServer/resource/readliest eine einzelne MCP-Ressource über einen initialisierten MCP-Server.mcpServer/tool/callruft 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/readinessprüft, ob die Windows-Sandbox bereit ist. Lautet das ErgebnisupdateRequired, rufewindowsSandbox/setupStartauf und warte aufwindowsSandbox/setupCompleted.feedback/uploadübermittelt einen Feedbackbericht mit Klassifizierung, optionaler Begründung und optionalen Protokollen sowie der Gesprächs-ID. ÜberextraLogFilessind zusätzliche Anhänge möglich.config/readliest die wirksame Konfiguration vom Datenträger, nachdem die Konfigurationsebenen zusammengeführt wurden.externalAgentConfig/detectermittelt mitincludeHomeund optionalcwds, welche Artefakte externer Agenten sich migrieren lassen. Jeder gefundene Eintrag enthältcwd(nullfür das Home-Verzeichnis).externalAgentConfig/importmigriert ausgewählte Artefakte externer Agenten. Übergib dafür explizitmigrationItemsmitcwd(nullfü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 mitexternalAgentConfig/import/progressund den Abschluss mitexternalAgentConfig/import/completed. Plugin- und Sitzungsimporte können asynchron abgeschlossen werden.config/value/writeschreibt einen einzelnen Konfigurationsschlüssel samt Wert in die persönlicheconfig.tomlauf dem Datenträger.config/batchWriteschreibt mehrere Konfigurationsänderungen atomar in die persönlicheconfig.tomlauf dem Datenträger.configRequirements/readliest Vorgaben ausrequirements.toml, aus MDM oder aus beiden Quellen, darunter Zulassungslisten und festgelegtefeatureRequirements. Clients mit aktiviertemexperimentalApikönnen auch verwaltete Netzwerkanforderungen lesen.fs/readFile,fs/writeFile,fs/createDirectory,fs/getMetadata,fs/readDirectory,fs/remove,fs/copy,fs/watch,fs/unwatchundfs/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:
supportedReasoningEffortsenthält die vom Modell unterstützten Stufen für den Reasoning-Aufwand.defaultReasoningEffortgibt den empfohlenen Standardwert für den Reasoning-Aufwand in Clients an.upgradeenthält optional die ID des empfohlenen Nachfolgemodells für Migrationshinweise in Clients.upgradeInfoenthält optionale Upgrade-Metadaten für Migrationshinweise in Clients.hiddengibt an, ob das Modell in der standardmäßigen Auswahlliste ausgeblendet ist.inputModalitiesenthält die unterstützten Eingabetypen des Modells, etwatextundimage.supportsPersonalityist ein veraltetes Kompatibilitätsfeld und hat immer den Wertfalse. Modelle unterstützen die Auswahl einer Persönlichkeit nicht mehr.isDefaultgibt 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/readliest gespeicherte Thread-Metadaten, ohne den Thread zu abonnieren.thread/turns/listliest den gespeicherten Turn-Verlauf eines Threads seitenweise, ohne ihn fortzusetzen. MititemsViewlegst du fest, ob die Elemente der Turns ausgelassen, zusammengefasst oder vollständig geladen werden.thread/items/listliest gespeicherte Thread-Elemente seitenweise, optional beschränkt auf einen Turn.thread/listliefert gespeicherte Threads seitenweise. VerwendesectionId, um die Threads eines Abschnitts aufzulisten, oderexcludedThreadIds, um bereits angezeigte Threads auszulassen.thread/loaded/listgibt die IDs der aktuell im Arbeitsspeicher geladenen Threads zurück.thread/archiveverschiebt das gespeicherte JSONL-Protokoll des Threads ins Archivverzeichnis und versucht, auch die noch nicht archivierten Protokolle aller daraus erzeugten Threads zu archivieren.thread/deletelöscht einen gespeicherten aktiven oder archivierten Thread und die daraus erzeugten Threads dauerhaft.thread/metadata/updateaktualisiert das für einen Thread gespeicherte FeldgitInfo.thread/unsubscribebeendet das Abonnement der aktuellen Verbindung für einen geladenen Thread. Nach einer Frist ohne Aktivität kann diesthread/closedauslösen.thread/unarchiveverschiebt eine archivierte Thread-Aufzeichnung zurück in das Verzeichnis der aktiven Sitzungen.thread/compact/startstartet die Kontextverdichtung und gibt sofort{}zurück.thread/revertentfernt einen angegebenen Turn und alle späteren Turns aus dem Verlauf eines dauerhaft gespeicherten, paginierten Threads. Lokale Dateien bleiben unverändert.thread/inject_itemsfü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: Beifalseoder fehlendem Feld enthält die Antwort nur die Thread-Zusammenfassung. Mittruewird der gesamte Verlauf geladen. Bei paginierten Threads ist dieses Verhalten veraltet und löstdeprecationNoticeaus. Verwende hierfür die Paginierungsmethoden.- Zurückgegebene
thread-Objekte enthalten den Laufzeitstatusstatus(notLoaded,idle,systemErroroderactivemitactiveFlags).
{ "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:
notLoadedlässt die Elemente aus.summaryliefert zusammengefasste Elementdaten und ist der Standardwert, wenn du das Feld weglässt.fullliefert 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:
cursorist eine opake Zeichenfolge aus einer vorherigen Antwort. Lass sie für die erste Seite weg.limitlegt die Seitengröße fest. Ohne Angabe verwendet der Server eine geeignete Standardgröße.sortKeyakzeptiertcreated_at(Standard),updated_at,recency_atodersection_position. Fürsection_positionmusst du einesectionIdangeben, die nicht null ist.sortDirectionakzeptiertascoderdesc. OhnesortDirectionsortiert der Server beisection_positionaufsteigend und bei zeitbasierten Schlüsseln absteigend.sectionId: Übergib die ID eines Abschnitts, um dessen Threads aufzulisten, odernullfü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.modelProvidersbeschränkt die Ergebnisse auf bestimmte Anbieter. Übergib[], um alle Anbieter einzubeziehen. Wenn du das Feld weglässt odernullübergibst, verwendet der Server den konfigurierten Anbieter. Filterst du dabei nach einer Thread-Beziehung, berücksichtigt er alle Anbieter.sourceKindsbeschränkt die Ergebnisse auf bestimmte Thread-Quellen. Bei fehlendem Wert oder[]berücksichtigt der Server standardmäßig nur die interaktiven Quellencliundvscode.archivedlistet beitruenur archivierte Threads auf. Beifalseoder fehlendem Wert erscheinen nur nicht archivierte Threads (Standard).cwdbeschrä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.useStateDbOnlyliefert beitrueErgebnisse aus der Zustandsdatenbank, ohne die JSONL-Thread-Protokolle zur Reparatur der Metadaten zu durchsuchen. Lass den Parameter weg oder übergibfalse, um die Protokolle wie gewohnt zu durchsuchen und Metadaten zu reparieren.searchTermbeschränkt die Ergebnisse auf Threads, deren extrahierter Titel das angegebene Textfragment enthält. Groß- und Kleinschreibung werden berücksichtigt.parentThreadIdbeschränkt die Ergebnisse auf direkte untergeordnete Threads des angegebenen Threads. Dieser Filter ist experimentell und erfordertcapabilities.experimentalApi = true.ancestorThreadIdbeschränkt die Ergebnisse auf Threads, die auf beliebiger Ebene aus dem angegebenen Thread erzeugt wurden. Dieser Filter ist experimentell und erfordertcapabilities.experimentalApi = true. Kombiniere ihn nicht mitparentThreadId.
sourceKinds akzeptiert folgende Werte:
clivscodeexecappServersubAgentsubAgentReviewsubAgentCompactsubAgentThreadSpawnsubAgentOtherunknown
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/adderwartetthreadId,attachmentType,identityKeyund das Feldpayloadmit 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/listliefert die Anhänge eines Threads seitenweise. Um Threads zu finden, die auf eine Ressource verweisen, rufethread/attachmentOwner/listmit ihremattachmentTypeundidentityKeyauf.thread/attachment/removeerwartetthreadId,attachmentTypeundidentityKey. Die verknüpfte Ressource bleibt verfügbar.thread/attachment/updatedmeldet die Operationcreatedoderdeleted, 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:
readOnlyunterstützt das optionale Feldaccess(standardmäßig{ "type": "fullAccess" }, alternativ beschränkt auf bestimmte Stammverzeichnisse).workspaceWriteunterstützt das optionale FeldreadOnlyAccess(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
expectedTurnIdan. Der Wert muss der ID des aktiven Turns entsprechen. - Die Anfrage schlägt fehl, wenn der Thread keinen aktiven Turn hat.
turn/steerlöst keine neueturn/started-Benachrichtigung aus.turn/steerakzeptiert keine abweichenden Einstellungen für den Turn (model,cwd,sandboxPolicyoderoutputSchema).
{ "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:
uncommittedChangesbaseBranch(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. sandboxPolicyakzeptiert dieselbe Struktur wieturn/start, etwadangerFullAccess,readOnly,workspaceWriteoderexternalSandbox.- Ohne Angabe gilt für
timeoutMsder Standardwert des Servers. - Setze
tty: truefür Sitzungen mit PTY. VerwendeprocessId, wenn du anschließendcommand/exec/write,command/exec/resizeodercommand/exec/terminateaufrufen möchtest. - Setze
streamStdoutStderr: true, um während der Befehlsausführungcommand/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:
elevatedführt das Setup der Windows-Sandbox mit erhöhten Rechten aus.unelevatedverwendet 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/deltaunterdrü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/sessionUpdatedliefert{ sessionId, query, files }mit den aktuellen Treffern für die aktive Suchanfrage.fuzzyFileSearch/sessionCompletedliefert{ sessionId }, sobald die Indexierung und der Abgleich für diese Suchanfrage abgeschlossen sind.
Warnungen
configWarningliefert{ summary, details?, path?, range? }bei behebbaren Konfigurations- oder Initialisierungsproblemen.warningliefert{ threadId?, message }bei Laufzeitwarnungen, die keinen Abbruch erfordern.
Ereignisse beim Setup der Windows-Sandbox
windowsSandbox/setupCompletedliefert{ mode, success, error }nach Abschluss einerwindowsSandbox/setupStart-Anfrage.
Turn-Ereignisse
turn/startedliefert{ turn }mit der Turn-ID, einem leerenitems-Array undstatus: "inProgress".turn/completedliefert{ turn }. Dabei istturn.statusentwedercompleted,interruptedoderfailed. Bei einem Fehler enthält die Nachricht{ error: { message, codexErrorInfo?, additionalDetails? } }.turn/diff/updatedliefert{ threadId, turnId, diff }mit dem aktuellen zusammengefassten Unified Diff aller Dateiänderungen im Turn.turn/plan/updatedliefert{ turnId, explanation?, plan }, sobald der Agent seinen Plan mitteilt oder ändert. Jederplan-Eintrag hat die Form{ step, status }. Fürstatussindpending,inProgressundcompletedmöglich.hook/startedundhook/completedliefern{ threadId, turnId?, run }, wenn ein synchroner Lebenszyklus-Hook startet bzw. die abschließende Zusammenfassung vorliegt. Für asynchrone Hooks entfallen diese Benachrichtigungen.model/safetyBuffering/updatedliefert{ threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel }, wenn eine Antwort für eine Sicherheitsprüfung vorübergehend gepuffert wird.model/reroutedliefert{ threadId, turnId, fromModel, toModel, reason }, wenn der Dienst eine Anfrage an ein anderes Modell weiterleitet.model/verificationliefert{ threadId, turnId, verifications }, wenn der Dienst eine zusätzliche Kontoverifizierung verlangt.thread/tokenUsage/updatedmeldet 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:
userMessageenthält{id, content}. Dabei istcontenteine Liste von Nutzereingaben (text,imageoderlocalImage).functionCallOutputenthält{id, name, namespace, output}für eine eigenständige Toolausgabe, die überturn/start.toolOutputübergeben wurde.namespacekannnullsein.agentMessageenthält in{id, text, phase?}die bisherige Antwort des Agenten. Falls vorhanden, verwendetphasedie Übertragungswerte der Responses API (commentary,partial_answer,final_answer). Einepartial_answerenthält bereits feststehenden Antworttext. Weitere Ausgaben oder Toolaufrufe können folgen.planenthält in{id, text}den vorgeschlagenen Plantext im Planmodus. Maßgeblich ist das endgültigeplan-Element ausitem/completed.reasoningenthält{id, summary, content}. Dabei enthältsummarydie im Stream übertragenen Reasoning-Zusammenfassungen undcontentdie unverarbeiteten Reasoning-Blöcke.commandExecutionenthält{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.fileChangebeschreibt vorgeschlagene Änderungen mit{id, changes, status}. Die Listechangesenthält Einträge der Form{path, kind, diff}.mcpToolCallerfasstid,server,tool,statusundargumentsdes Aufrufs. Hinzu kommenappContext,mcpAppUi,pluginId,readOnlyHint,result,errorunddurationMs. Jedes dieser zusätzlichen Felder kannnullsein. Das ältere FeldmcpAppResourceUriist optional. Bei vertrauenswürdigen MCP-Apps enthältappContextdieconnectorId. Die übrigen Felder (linkId,resourceUri,appNameundactionName) könnennullsein. Gibt der Tooldeskriptor einen Ressourcen-URI und einen Anzeigemodus (inlineoderfullscreen) an, enthältmcpAppUidie FelderresourceUriundpreferredModelDisplayMode. Bei Aufrufen, die ohne diese Anzeigemetadaten gespeichert wurden, liefert der App ServernullfürmcpAppUi.dynamicToolCallenthält{id, tool, arguments, status, contentItems?, success?, durationMs?}für dynamische Toolaufrufe, die der Client ausführt.collabToolCallenthält{id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}.webSearchenthält{id, query, action?}für Websuchen, die der Agent anfordert.imageViewenthält{id, path}, wenn der Agent das Tool zur Bildansicht aufruft.enteredReviewModeliefert{id, review}, wenn die Codeüberprüfung beginnt.exitedReviewModeliefert{id, review}, wenn die Codeüberprüfung endet.contextCompactionliefert{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/startedliefert das vollständigeitem, wenn ein neuer Arbeitsschritt beginnt. Dieitem.identspricht deritemIdin den Deltas.item/completedliefert das endgültigeitem, sobald der Arbeitsschritt abgeschlossen ist. Dieser Zustand ist maßgeblich.
Element-Deltas
item/agentMessage/deltahängt den im Stream empfangenen Text an die Agentennachricht an.item/plan/deltaüberträgt den vorgeschlagenen Plantext im Stream. Das endgültigeplan-Element kann vom Text der aneinandergereihten Deltas abweichen.item/reasoning/summaryTextDeltaüberträgt lesbare Reasoning-Zusammenfassungen.summaryIndexerhöht sich mit jedem neuen Abschnitt der Zusammenfassung.item/reasoning/summaryPartAddedmarkiert 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/outputDeltaist eine veraltete Kompatibilitätsbenachrichtigung für die frühere Textausgabe vonapply_patch. Aktuelle Versionen des App Server senden sie nicht mehr. VerwendefileChange-Elemente undturn/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,canceloder{ "acceptWithExecpolicyAmendment": { "execpolicy_amendment": ["cmd", "..."] } }. -
Mögliche Entscheidungen für Dateiänderungen sind
accept,acceptForSession,declineundcancel. -
Anfragen enthalten
threadIdundturnId. 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/completedab.
Genehmigungen für die Befehlsausführung
Reihenfolge der Nachrichten:
item/startedzeigt das ausstehendecommandExecution-Element mitcommand,cwdund weiteren Feldern.item/commandExecution/requestApprovalenthältitemId,threadId,turnIdsowie optionalreason,command,cwd,commandActions,proposedExecpolicyAmendment,networkApprovalContextundavailableDecisions. Beiinitialize.params.capabilities.experimentalApi = truekann die Nachricht außerdem das experimentelle FeldadditionalPermissionsenthalten. Es beschreibt den angeforderten Sandbox-Zugriff für diesen Befehl. Dateisystempfade inadditionalPermissionswerden als absolute Pfade übertragen.- Der Client antwortet mit einer der oben genannten Entscheidungen zur Befehlsausführung.
serverRequest/resolvedbestätigt, dass die ausstehende Anfrage beantwortet oder aufgehoben wurde.item/completedliefert das endgültigecommandExecution-Element mitstatus: 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:
item/startedliefert einfileChange-Element mit den vorgeschlagenenchangesundstatus: "inProgress".item/fileChange/requestApprovalenthältitemId,threadId,turnIdsowie optionalreasonundgrantRoot.- Der Client antwortet mit einer der oben genannten Entscheidungen für Dateiänderungen.
serverRequest/resolvedbestätigt, dass die ausstehende Anfrage beantwortet oder aufgehoben wurde.item/completedliefert das endgültigefileChange-Element mitstatus: 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"odermode: "openai/form"mitmessageundrequestedSchema.mode: "url"mitmessage,urlundelicitationId.
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:
item/startedenthältitem.type = "dynamicToolCall",status = "inProgress"sowietoolundarguments.item/tool/callgeht als Serveranfrage an den Client.- Der Client antwortet mit den zurückgegebenen Inhaltselementen.
item/completedenthältitem.type = "dynamicToolCall", den endgültigenstatussowie gegebenenfalls die zurückgegebenencontentItemsoder den Wert vonsuccess.
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 mittype: "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 mittype: "chatgpt"oder die Anmeldung per Gerätecode mittype: "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 übergibtaccessToken,chatgptAccountIdund optionalchatgptPlanTypedirekt. Auf Anforderung muss sie das Token aktualisieren. - Amazon Bedrock:
account/readmeldet Bedrock-Konten alstype: "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.authModeverwendet für von Codex verwaltete Bedrock-API-Schlüssel den WertbedrockApiKey.
API-Überblick
account/readruft die aktuellen Kontoinformationen ab und aktualisiert optional die Token.account/login/startstartet die Anmeldung (apiKey,chatgpt,chatgptDeviceCodeoder experimentellchatgptAuthTokens).account/login/completed(Benachrichtigung) meldet den Abschluss eines Anmeldeversuchs, unabhängig davon, ob er erfolgreich war oder fehlgeschlagen ist.account/login/cancelbricht eine ausstehende verwaltete ChatGPT-Anmeldung anhand derloginIdab.account/logoutmeldet das Konto ab und löstaccount/updatedaus.account/updated(Benachrichtigung) meldet Änderungen des Authentifizierungsmodus (authModemitapikey,chatgpt,chatgptAuthTokens,agentIdentity,personalAccessToken,bedrockApiKeyodernull) und enthältplanType, sofern verfügbar.account/chatgptAuthTokens/refresh(Serveranfrage) fordert nach einem Autorisierungsfehler neue extern verwaltete ChatGPT-Token an.account/rateLimits/readruft die ChatGPT-Ratenlimits ab.account/rateLimits/updated(Benachrichtigung) meldet Änderungen der persönlichen ChatGPT-Ratenlimits.account/sendAddCreditsNudgeEmailfordert ChatGPT auf, die für den Workspace verantwortliche Person per E-Mail über aufgebrauchte Credits oder ein erreichtes Nutzungslimit zu informieren.account/rateLimitResetCredit/consumelöst mit einem vom Client bereitgestelltenidempotencyKeyeine erworbene Rücksetzung des Ratenlimits ein.account/usage/readruft Zusammenfassungen und Tageswerte zur Tokennutzung des ChatGPT-Kontos ab.account/workspaceMessages/readruft aktive Workspace-Nachrichten einschließlich verfügbarer Benachrichtigungsüberschriften ab.mcpServer/oauthLogin/completed(Benachrichtigung) meldet den Abschluss einesmcpServer/oauth/login-Ablaufs und enthält{ name, threadId, loginId?, success, error? }. Ältere Server lassenloginIdweg.threadIdkann bei App-bezogenen oder Plugin-OAuth-Abläufennullsein.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 istthreadIdgleichnull. Schlägt der Start fehl, bedeutetfailureReason: "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 auftrue, um im verwalteten ChatGPT-Modus eine Tokenaktualisierung zu erzwingen. Im Modus für externe Token (chatgptAuthTokens) ignoriert der App Server dieses Flag.emailistnull, wenn dem ChatGPT-Konto keine E-Mail-Adresse zugeordnet ist.requiresOpenaiAuthrichtet sich nach dem aktiven Anbieter. Beifalsekann 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 escredentialSource: "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
-
Sende folgende Anfrage:
{ "method": "account/login/start", "id": 2, "params": { "type": "apiKey", "apiKey": "sk-..." } } -
Erwarte folgende Antwort:
{ "id": 2, "result": { "type": "apiKey" } } -
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
-
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 kannappBrandden Wert"codex"oder"chatgpt"haben. Fehlt die Angabe oder ist sienull, gilt"codex".{ "id": 3, "result": { "type": "chatgpt", "loginId": "<uuid>", "authUrl": "https://chatgpt.com/...&redirect_uri=http%3A%2F%2Flocalhost%3A<port>%2Fauth%2Fcallback" } } -
Öffne
authUrlin einem Browser. Der App Server stellt den lokalen Callback bereit. -
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.
-
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" } } -
Zeige der Person, die sich anmeldet,
verificationUrlunduserCodean. Die Gestaltung des Ablaufs übernimmt das Frontend. -
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.
-
Sende folgende Anfrage:
{ "method": "account/login/start", "id": 7, "params": { "type": "chatgptAuthTokens", "accessToken": "<jwt>", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } } -
Erwarte folgende Antwort:
{ "id": 7, "result": { "type": "chatgptAuthTokens" } } -
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:
rateLimitsist die abwärtskompatible Ansicht für ein einzelnes Kontingent.rateLimitsByLimitIdenthält, sofern vorhanden, die Ansicht für mehrere Kontingente. Als Schlüssel dient dielimit_idder jeweiligen Verbrauchsmessung, etwacodex.limitIdbezeichnet das Kontingent, dessen Verbrauch gemessen wird.limitNameist ein optionaler Anzeigename für das Kontingent.usedPercentgibt den aktuellen prozentualen Verbrauch innerhalb des Kontingentzeitfensters an.windowDurationMinsgibt die Länge des Kontingentzeitfensters an.resetsAtist der Unix-Zeitstempel in Sekunden für die nächste Rücksetzung.planTypeist enthalten, wenn der Server den einem Kontingent zugeordneten ChatGPT-Plan zurückgibt.creditsist enthalten, wenn der Server Details zu verbleibenden Workspace-Credits zurückgibt.rateLimitReachedTypebezeichnet den vom Server ermittelten Limitstatus, wenn ein Limit erreicht wurde.rateLimitResetCreditsenthält die Anzahl verfügbarer erworbener Rücksetzungen, sofern der Dienst sie bereitstellt. Andernfalls ist der Wertnull.rateLimitResetCredits.creditsistnull, 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 daheravailableCount.- Jeder Detaileintrag enthält eine opake
id,resetType,status,grantedAt,expiresAt(kannnullsein),title(kannnullsein) unddescription(kannnullsein). - Rufe nach dem Einlösen einer Rücksetzung
account/rateLimits/readauf.
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
summarykönnennullsein, wenn der Dienst die jeweilige Kennzahl nicht zurückgegeben hat. dailyUsageBucketskannnullsein. Liegen Tageswerte vor, enthält jeder EintragstartDateundtokens.- 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:
idempotencyKeydarf 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.creditIdist optional. Wenn du sie angibst, muss sie eine nicht leere opake ID ausaccount/rateLimits/readsein. Ohne diese Angabe wählt der Dienst den nächsten verfügbaren Credit aus.resetbedeutet, dass ein Credit eingelöst wurde.alreadyRedeemedbedeutet, dass derselbe Einlösevorgang bereits abgeschlossen wurde. Behandle dies als idempotenten Erfolg und aktualisiere die Kontolimits.nothingToResetbedeutet, dass kein Ratenlimit-Zeitfenster für eine Rücksetzung infrage kommt.noCreditbedeutet, dass für das Konto keine erworbenen Credits zur Rücksetzung verfügbar sind.- Rufe nach dem Einlösen einer Rücksetzung
account/rateLimits/readauf, 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 }
] } }