Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Codex SDK

Lokale Codex-Agenten per Code steuern

Wenn du Codex über die Codex CLI, die IDE-Erweiterung oder Codex Cloud nutzt, kannst du Codex auch per Code steuern.

Das SDK eignet sich für folgende Aufgaben:

  • Codex in deiner CI/CD-Pipeline steuern
  • Einen eigenen Agenten entwickeln, der gemeinsam mit Codex komplexe Entwicklungsaufgaben löst
  • Codex in deine internen Tools und Workflows einbinden
  • Codex in deine eigene Anwendung integrieren

Mit dem Codex SDK kannst du Programmieraufgaben automatisieren, auch in CI-Jobs. Mit dem Codex App Server kannst du eigene Clients entwickeln, die die Authentifizierung übernehmen, Gesprächsverläufe und Genehmigungen verwalten und Agentenereignisse als Stream verarbeiten.

Der Befehl codex mcp-server und die eigenständige Binärdatei codex-mcp-server wurden entfernt. Verwende für bestehende Integrationen den Codex App Server.

Wenn du Beta-Zugriff hast und bei Sicherheitsscans von Repositorys oder Änderungen strukturierte Angaben zu den Befunden und zur Prüfabdeckung benötigst, verwende das TypeScript-SDK für Codex Security.

TypeScript-Bibliothek

Mit der TypeScript-Bibliothek kann deine Anwendung lokale Codex-Threads starten, fortsetzen und später wieder aufnehmen.

Verwende die Bibliothek auf dem Server. Sie setzt Node.js 18 oder höher voraus.

Installation

Installiere das Codex SDK mit npm:

npm install @openai/codex-sdk

Verwendung

Starte einen Thread mit Codex und führe darin deinen Prompt aus.

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result.finalResponse);

Rufe run() erneut auf, um im selben Thread weiterzuarbeiten. Einen früheren Thread kannst du über seine Thread-ID wieder aufnehmen.

// running the same thread
const result = await thread.run("Implement the plan");

console.log(result.finalResponse);

// resuming past thread

const threadId = thread.id!;
const thread2 = codex.resumeThread(threadId, {
  sandboxMode: "workspace-write",
});
const result2 = await thread2.run("Pick up where you left off");

console.log(result2.finalResponse);

Setze beim Erstellen eines Threads threadSource, damit du die von deiner Integration erstellten Threads erkennen kannst. Beispielsweise kennzeichnet codex.startThread({ threadSource: "ci" }) den Thread als ci. Wenn du einen Thread wieder aufnimmst, behält er seine ursprüngliche Quellenangabe.

Konfiguration überschreiben

Übergib config, um die Codex-Konfiguration in strukturierter Form festzulegen. Für Schlüssel, die sich nicht als Pfade in Punktnotation ausdrücken lassen, kannst du mit configOverrides TOML-Zeichenfolgen direkt als separate --config-Argumente übergeben:

const codex = new Codex({
  config: { default_permissions: "audit" },
  configOverrides: [
    'permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}',
  ],
});

Direkt übergebene TOML-Werte haben Vorrang vor den strukturierten Angaben in config. Das SDK wendet verwaltete Einstellungen wie baseUrl und threadspezifische Optionen anschließend an. Sie haben daher Vorrang vor beiden. Deine Codex-Konfigurationsdateien bleiben dabei unverändert.

Weitere Informationen findest du im TypeScript-Repository.

Python-Bibliothek

Das Python-SDK steuert den lokalen Codex App Server über JSON-RPC. Es setzt Python 3.10 oder höher voraus. Veröffentlichte SDK-Builds enthalten die Laufzeitumgebung der Codex CLI als Abhängigkeit in einer festgelegten Version.

Installation

Installiere das SDK mit folgendem Befehl:

pip install openai-codex

Veröffentlichte SDK-Builds verwenden automatisch die jeweils festgelegte Version der Laufzeitumgebung. Übergib CodexConfig(codex_bin=...) nur, wenn du gezielt eine bestimmte lokale Codex-Binärdatei verwenden möchtest.

Das Python-SDK ist als stabile Version verfügbar. Mit pip install openai-codex installierst du die neueste stabile Version. Mit pip install --pre openai-codex kannst du neuere Vorabversionen installieren.

Verwendung

Starte Codex, erstelle einen Thread und führe darin einen Prompt aus. Die Beispiele verwenden GPT-6.1 Sol. Dafür muss das Konto, mit dem du angemeldet bist, Zugriff auf das Modell haben. Lass andernfalls model weg, um dein konfiguriertes Standardmodell zu verwenden. Weitere Informationen findest du in der Übersicht zur Verfügbarkeit von GPT-6.1 Sol nach Plan.

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-6.1-sol",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

Verwende AsyncCodex, wenn deine Anwendung bereits asynchron arbeitet:

import asyncio
from openai_codex import AsyncCodex


async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-6.1-sol")
        result = await thread.run("Implement the plan")
        print(result.final_response)


asyncio.run(main())

Inhalte aus einem anderen System übergeben

Wenn ein Tool, eine Anwendung oder ein anderer Agent Inhalte liefert, übergib ein Objekt vom Typ ExternalMessage als gesamte Eingabe an thread.run() oder thread.turn(). Beispielsweise gibt ExternalMessage(tool_name="issue_tracker", content=issue_body) an, welches Tool die Beschreibung eines Issues geliefert hat. Codex behandelt die Beschreibung als Toolausgabe und räumt ihr eine niedrigere Priorität ein als den Anweisungen von Nutzenden und Entwickelnden. Die Nachricht kann einen neuen Schritt starten oder in einen laufenden regulären Schritt einfließen.

Einen Thread wieder aufnehmen, ohne seinen Verlauf zu laden

Übergib include_turns=False an codex.thread_resume() oder codex.thread_fork(), damit die Antwort keine früheren Schritte enthält. Dem Modell steht der Kontext des Threads weiterhin zur Verfügung. Um den Verlauf später abzurufen, rufe thread.read(include_turns=True) auf.

Verwende ab Version 0.166.0 der Codex CLI den für den Thread gespeicherten Modellanbieter, um den Thread wieder aufzunehmen. Wenn du den Anbieter wechselst, rufe codex.thread_fork(thread_id) auf, um beim neuen Anbieter mit demselben Verlauf weiterzuarbeiten.

Die Servicestufe für einen einzelnen Schritt festlegen

Um die Servicestufe für einen einzelnen neuen Schritt festzulegen, übergib turn_service_tier an run() oder turn(). Mit turn_service_tier="default" verwendest du beispielsweise die Standardgeschwindigkeit für diesen Schritt. Um die Servicestufe für diesen und die folgenden Schritte zu ändern, übergib service_tier. Wenn du dich einem laufenden Schritt anschließt, behält er seine Servicestufe.

Wenn du eine eigene Codex-Binärdatei verwendest, benötigst du Codex CLI 0.151.0 oder höher, um ExternalMessage zu verwenden, include_turns beim Wiederaufnehmen oder Forken eines Threads explizit anzugeben oder turn_service_tier zu setzen.

Sandbox-Voreinstellungen

Verwende dieselben Sandbox-Voreinstellungen, wenn du einen Thread erstellst oder seinen Dateisystemzugriff für einen späteren Schritt änderst:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

Verfügbare Voreinstellungen:

  • Sandbox.read_only: Erlaubt das Lesen von Dateien ohne Schreibzugriff.
  • Sandbox.workspace_write: Erlaubt das Lesen von Dateien sowie das Schreiben im Workspace und in den Stammverzeichnissen, für die Schreibzugriff konfiguriert ist.
  • Sandbox.full_access: Erlaubt die Ausführung ohne Einschränkungen beim Dateisystemzugriff.

Wenn du sandbox= weglässt, verwendet der App Server seine konfigurierte Standardeinstellung. Eine Sandbox, die du an run(...) oder turn(...) übergibst, gilt für diesen und alle weiteren Schritte im selben Thread.

Weitere Informationen findest du im Python-Repository.