Einrichten Ihrer Umgebung und AGENTS.md
Auf dieser Seite
Aktualisiert am 3. November 2026 basierend auf der Codex-Dokumentation (Codex CLI, Authentifizierung, Codex IDE-Erweiterung, Benutzerdefinierte Anweisungen mit AGENTS.md): Die Pakete
@openai/codex-cliund der Befehlcodex auth loginexistieren nicht (verwenden Sie stattdessennpm install -g @openai/codexundcodex login); die Erweiterungs-ID lautetopenai.chatgpt; die Adressen von codex.openai.com und die Pläne „Team, Enterprise oder API” wurden durch aktuelle Zugriffswege ersetzt; zudem wurde die Lese-Reihenfolge von AGENTS.md geklärt (Projektwurzel → aktueller Verzeichnisbaum). Quellen: Codex CLI · Authentifizierung · AGENTS.md · Preise.
Vorbereiten Ihres Projekts für Codex
Bevor Sie Ihre erste Aufgabe durchführen können, müssen zwei Dinge bereitgestellt sein: Ihr Codex-Zugang – also Ihr Konto und die GitHub-Verbindung – sowie Ihr Projekt selbst, definiert durch die AGENTS.md-Datei, die den Agenten leiten wird. Der erste Teil dauert etwa 15 Minuten und ist eine einmalige Einrichtung. Der zweite Teil bestimmt die Qualität aller Ergebnisse, die Sie von Codex erhalten, und unterscheidet Teams, die mit Codex zufrieden sind, von denen, die ihn enttäuschend finden.
Schritt 1: Ihr Codex-Zugang
Sie können Codex mit einem ChatGPT-Konto oder einem API-Schlüssel verwenden. Die Free- und Go-Pläne bieten je nach aktueller Bereitstellung Zugang zu GPT-6 Luna in der Desktop-App. Ab dem Plus-Plan ist Codex im Web, in der CLI, in der Editor-Erweiterung und auf iOS verfügbar, mit Cloud-Integrationen wie automatischer Code-Überprüfung. Ein API-Schlüssel funktioniert für Automatisierungen in geteilten Umgebungen wie CI, unter Verwendung der CLI, des SDK oder der Erweiterung – wobei einige Funktionen möglicherweise nicht verfügbar sind. Details und Nutzungslimits finden Sie auf der Codex-Preisschaltfläche.
Um in der Cloud auf Ihren Repositories zu arbeiten, verbinden Sie GitHub, wenn Sie Ihre erste Codex-Cloud-Umgebung erstellen (Lektion 2). Bei der Gewährung von Berechtigungen halten Sie es minimal: Beschränken Sie den Zugriff auf nur die Repositories, die Sie tatsächlich benötigen.
Schritt 2: Installieren der Editor-Erweiterung
Installieren Sie in VS Code und seinen Derivaten (Cursor, Windsurf) die Codex-Erweiterung aus dem Marketplace – ihre Kennung ist openai.chatgpt:
code --install-extension openai.chatgpt
Öffnen Sie Codex dann über sein Symbol oder über die Befehlspalette mit Codex: Codex-Seitenleiste öffnen und melden Sie sich an. Xcode und JetBrains-IDEs verfügen über eigene Integrationen: Öffnen Sie in JetBrains AI Chat und wählen Sie Codex aus.
Schritt 3: Installieren der CLI
# Installation (macOS und Linux), oder npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Installation überprüfen
codex --version
# Anmelden (Browser) oder Verbindungsstatus prüfen
codex login
codex login status
codex login öffnet den Anmeldevorgang in Ihrem Browser. Für einen API-Schlüssel geben Sie diesen über die Standardeingabe ein (printenv OPENAI_API_KEY | codex login --with-api-key). Codex speichert Credentials entweder in einer Klartextdatei, ~/.codex/auth.json, oder im System-Keychain, abhängig von der Einstellung cli_auth_credentials_store (file, keyring, auto oder ephemeral). Wenn die Datei verwendet wird, behandeln Sie sie wie ein Passwort: Sie enthält Zugriffstoken, daher dürfen Sie sie niemals committen. Die CLI und die Erweiterung teilen sich diesen Cache.
Die AGENTS.md-Datei – Ihr Projektleitfaden
AGENTS.md ist zentral für die effektive Nutzung von Codex. Es handelt sich um eine einfache Markdown-Datei, die an der Wurzel Ihres Repositories platziert wird und Anweisungen, Konventionen und Befehle sammelt, die spezifisch für Ihr Projekt sind. Wenn Codex das Repository klonen, liest es diese Datei zuerst: Denken Sie daran, als wäre es eine automatische Onboarding-Prozedur für den Agenten, genau das, was Sie einem neuen Teammitglied mündlich erklären würden.
Die Wirkung ist sofort spürbar. Ohne AGENTS.md besteht bei einer Anfrage nach einer Unit-Test für ein Projekt, das Vitest verwendet, eine gute Chance, dass Codex Ihnen Jest liefert, da dies die häufigste Wahl im Ökosystem ist. Eine einzige Zeile Konvention reicht aus, um Vitest beim ersten Mal richtig zu machen und Sie davor zu bewahren, dieselbe Korrektur hundertmal vornehmen zu müssen. Hier ist die Struktur einer grundlegenden Datei für ein SaaS-Rechnungsverwaltungsprojekt.
# AGENTS.md
## Projektkontext
SaaS-Anwendung zur Rechnungsverwaltung.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.
## Code-Konventionen
- Verwenden Sie React-Funktionskomponenten (keine Klassen)
- Benennen Sie Dateien in kebab-case
- TypeScript-Typen in separaten .types.ts-Dateien
- Tests mit Vitest, .test.ts-Dateien neben dem Code
## Nützliche Befehle
- `npm run dev` — Entwicklungsserver
- `npm run test` — Tests ausführen
- `npm run lint` — Linting prüfen
- `npm run build` — Produktionsbuild
## Projektstruktur
src/
app/ → Next.js-Seiten (App Router)
components/ → Wiederverwendbare React-Komponenten
lib/ → Geschäftslogik und Hilfsprogramme
prisma/ → DB-Schema und Migrationen
## Strenge Regeln
- PRISMA-Schema NIEMALS ohne Migration ändern
- .env-Dateien NIEMALS committen
- Immer Server Actions für Mutationen verwenden
Wie Codex AGENTS.md-Dateien findet
Eine einzelne Wurzeldatei wird schnell zu allgemein. Codex ermöglicht es Ihnen, Anweisungen in einer präzisen Reihenfolge zu stapeln, die Sie kennen müssen:
- Globale Ebene: In Ihrem Codex-Ordner (
~/.codex, es sei denn,CODEX_HOMEüberschreibt dies) liest CodexAGENTS.override.md, falls vorhanden, sonstAGENTS.md. - Projektebene: Beginnend bei der Projektwurzel (meistens die Git-Wurzel) durchläuft Codex bis zum aktuellen Verzeichnis und liest in jedem durchlaufenen Ordner
AGENTS.override.mdoder, falls dies fehlschlägt,AGENTS.md. - Zusammenfügen: Dateien werden von der Wurzel bis zum aktuellen Verzeichnis concatenated; die Dateien, die dem aktuellen Verzeichnis am nächsten liegen, kommen zuletzt und überschreiben daher allgemeinere Anweisungen.
my-project/
AGENTS.md → Projektanweisungen
src/
api/
AGENTS.md → "API-Routen verwenden Zod für Validierung"
Praktische Konsequenz: src/api/AGENTS.md wird nur gelesen, wenn Codex aus src/api oder einem seiner Unterordner gestartet wird, nicht, wenn es aus der Wurzel gestartet wird. Leere Dateien werden ignoriert, und die Concatenation stoppt standardmäßig bei 32 KiB (project_doc_max_bytes). Wenn Ihr Repo bereits einen anderen Namen verwendet, wie TEAM_GUIDE.md, fügen Sie diesen zu project_doc_fallback_filenames in ~/.codex/config.toml hinzu.
Um zu überprüfen, was Codex tatsächlich geladen hat, fragen Sie einfach: codex --ask-for-approval never "Zusammenfassung der aktuellen Anweisungen.". Codex baut die Anweisungskette bei jedem Start neu auf: Im Zweifel starten Sie es im korrekten Verzeichnis neu.
Best Practices für AGENTS.md
Das leitende Prinzip ist Explizitheit. „Verwenden Sie Vitest, nicht Jest” ist besser als „Verwenden Sie unser Test-Framework”, da dies Annahmen macht, die der Agent nicht hat. Geben Sie immer Befehle an: Ohne sie weiß Codex nicht, wie Ihre Tests, Ihren Linter oder Ihren Build auszuführen sind, und es wird Code liefern, den es nicht verifizieren kann. Dokumentieren Sie die Struktur als Verzeichnisbaum, was verhindert, dass es blind erkundet und Dateien am falschen Ort erstellt.
Schließlich listen Sie die Verbote auf. Regeln, die als „NIEMALS” geschrieben sind, sind im Dateikonzept am kosteneffektivsten, da sie teure Fehler blockieren, die schwer zu beheben sind: Committen einer .env-Datei, Ändern eines Schemas ohne Migration. Die schwierigste Disziplin besteht darin, die Datei auf dem neuesten Stand zu halten. Eine AGENTS.md, die das Projekt des letzten Jahres beschreibt, lenkt Codex aktiv auf verlassene Konventionen – weit schlimmer als gar keine Datei zu haben, da der Fehler dann systematisch wird.
Wichtige Erkenntnisse
- Die initiale Einrichtung erfordert ein OpenAI-Konto und eine GitHub-Verbindung
- Die IDE-Erweiterung und die CLI werden in Minuten installiert
- AGENTS.md ist die wichtigste Datei für eine effektive Nutzung von Codex
- Sie enthält Konventionen, Befehle und Regeln, die spezifisch für Ihr Projekt sind
- AGENTS.md-Dateien in Unterordnern ermöglichen kontextbezogene Anweisungen