Codex CLI nutzen: Schritt-für-Schritt-Anleitung

Um Codex CLI zu nutzen, installierst du es mit einem Befehl, startest codex in einem Projektordner, meldest dich mit deinem ChatGPT-Account an und beschreibst dann in normaler Sprache, was du ändern willst. Codex liest den Code, bearbeitet Dateien und führt Befehle in deinem Projekt aus und fragt nach, bevor es den Ordner verlässt oder aufs Netzwerk zugreift.

Das ist der Grundablauf. Diese Anleitung deckt den Rest ab: Freigabe- und Sandbox-Modi, eine AGENTS.md, config.toml, MCP-Server, die Befehle für jeden Tag, das Fortsetzen von Sessions und ein paar Gewohnheiten, die Codex zuverlässiger machen. Alles hier folgt der offiziellen Codex-Dokumentation von OpenAI mit Stand Oktober 2026.

Was Codex CLI ist

Codex CLI ist der Coding-Agent von OpenAI für das Terminal. Er läuft lokal, arbeitet in dem Ordner, in dem du ihn startest, und kann deine Tests, Linter und Git ausführen. Denselben Codex gibt es auch als IDE-Erweiterung, Desktop-App und Cloud-Version, alle mit derselben Anmeldung. Wenn du zwischen Agenten wählst, vergleichen Claude Code vs. Codex und Codex vs. Gemini CLI sie im Detail. Kurz gesagt ist Codex ein Coding-Agent und keine Autovervollständigung: Du gibst ihm eine Aufgabe, er plant sie und setzt sie um.

Schritt 1: Codex CLI installieren

OpenAI liefert für jede Plattform ein Installationsskript; außerdem gibt es das CLI über npm und Homebrew.

Zum Aktualisieren führst du das Skript erneut aus, startest codex update oder nutzt deinen Paketmanager (brew upgrade --cask codex). Prüfe, ob alles geklappt hat:

codex --version

Schritt 2: anmelden

Wechsle in ein Projekt und starte Codex:

cd mein-projekt
codex

Beim ersten Start fragt Codex, wie du dich anmelden willst:

• Sign in with ChatGPT: nutzt deinen ChatGPT-Tarif, die Nutzung zählt gegen dessen Limits. Das ist die übliche Wahl und die einzige, die auch Codex Cloud freischaltet.
• API-Key: nutzt einen OpenAI-API-Key und wird pro Token abgerechnet. Praktisch für CI oder wenn du nutzungsbasiert zahlen willst.

Das geht auch über die Shell. codex login öffnet die Anmeldung im Browser, codex login --device-auth gibt dir einen Gerätecode für einen entfernten oder Headless-Rechner, codex login status zeigt, ob du angemeldet bist, und codex logout löscht die gespeicherten Zugangsdaten. Um einen Key anzumelden, ohne ihn einzutippen, leitest du ihn per Pipe weiter: printenv OPENAI_API_KEY | codex login --with-api-key.

Zum Zeitpunkt dieses Artikels ist Codex in ChatGPT Free, Go, Plus, Pro, Business, Edu und Enterprise enthalten. Höhere Tarife bringen höhere Limits; die aktuellen Zahlen findest du auf OpenAIs Preisseite für Codex. Wo du gerade stehst, siehst du jederzeit mit /status oder /usage in einer Session.

Schritt 3: deine erste Aufgabe

Fang mit etwas Kleinem, aber Echtem an, damit du siehst, wie Codex arbeitet:

Erkläre, wie die Authentifizierung in diesem Projekt funktioniert, und
füge dann einen Test für das Zurücksetzen des Passworts hinzu. Führe
danach die Testsuite aus.

Codex liest die relevanten Dateien, sagt, was es vorhat, bearbeitet den Code und führt die Tests aus. Ein paar Dinge machen das angenehmer:

• Tippe @, um eine Datei zu suchen und an deinen Prompt zu hängen.
• Beginne eine Zeile mit !, um selbst einen Shell-Befehl auszuführen, zum Beispiel !git status.
• Während Codex arbeitet, fügst du mit Enter Anweisungen zum laufenden Turn hinzu, mit Tab stellst du eine Folgenachricht für danach in die Warteschlange.
• Drücke bei leerem Eingabefeld zweimal Esc, um deine vorige Nachricht zu bearbeiten und von dort weiterzumachen.
• /diff zeigt, was sich geändert hat, auch nicht getrackte Dateien.

Screenshots oder Design-Entwürfe hängst du mit codex --image pfad/zur/datei.png an oder fügst sie direkt in den Prompt ein.

Schritt 4: Freigabe- und Sandbox-Modi

Diesen Teil solltest du verstehen, bevor du Codex größere Aufgaben gibst. Codex kombiniert zwei Einstellungen: eine Sandbox, die technisch begrenzt, was Befehle tun können, und eine Freigaberichtlinie, die festlegt, wann Codex anhält und dich fragt.

In einer Session wechselt /permissions zwischen Auto und Read Only. In der workspace-write-Sandbox ist der Netzwerkzugriff standardmäßig aus; brauchen deine Tests ihn, schaltest du ihn in der config.toml ein (siehe unten).

Muss Codex in einen zweiten Ordner schreiben, etwa in eine gemeinsame Bibliothek neben deinem Projekt, nimm --add-dir, statt auf Vollzugriff umzuschalten. OpenAI warnt ausdrücklich davor, --dangerously-bypass-approvals-and-sandbox (Alias --yolo) außerhalb einer eigenen, isolierten VM zu verwenden.

Die Sandbox ist echte Isolation auf Betriebssystemebene: Seatbelt unter macOS, bubblewrap mit seccomp unter Linux und eine native Sandbox unter Windows. In WSL2 nutzt Codex die Linux-Sandbox. Was bei Agenten allgemein schiefgehen kann und wie du es eingrenzt, steht in Sicherheit von KI-Coding-Agenten.

Schritt 5: eine AGENTS.md schreiben

AGENTS.md ist eine Markdown-Datei mit Anweisungen, die Codex liest, bevor es loslegt. Hier steht, was du sonst in jedem Prompt wiederholen würdest: wie gebaut und getestet wird, Code-Stil, Ordner, die tabu sind.

Führe /init in einer Session aus, und Codex erzeugt eine erste Version. Eine gute Datei ist kurz und konkret:

# AGENTS.md

## Befehle
- Installieren: pnpm install
- Testen: pnpm test (ausführen, bevor eine Aufgabe als fertig gilt)
- Lint: pnpm lint

## Konventionen
- TypeScript im Strict Mode, kein any.
- Neue API-Routen kommen nach src/routes und brauchen einen Test.

## Nicht
- Keine Dateien in src/generated bearbeiten.
- Keine Abhängigkeiten hinzufügen, ohne zu fragen.

Codex sucht diese Dateien in fester Reihenfolge:

1. Global: ~/.codex/AGENTS.md (oder AGENTS.override.md, um sie vorübergehend zu ersetzen). Gedacht für deine persönlichen Vorlieben.
2. Projekt: Vom Git-Root bis zu deinem aktuellen Ordner nimmt Codex höchstens eine Datei pro Verzeichnis und prüft zuerst AGENTS.override.md, dann AGENTS.md.

Die Dateien werden vom Root abwärts zusammengefügt; Anweisungen aus einem Unterordner kommen also später und haben Vorrang vor den allgemeinen. Die Gesamtgröße ist standardmäßig auf 32 KiB begrenzt (project_doc_max_bytes), ein weiterer Grund, sie knapp zu halten. Weil AGENTS.md ein gemeinsames Format ist, lesen auch andere Agenten sie; CLAUDE.md und AGENTS.md erklärt, wie du einen Regelsatz für mehrere Tools pflegst.

Schritt 6: config.toml

Die Einstellungen von Codex liegen in TOML-Dateien:

• ~/.codex/config.toml für deine Benutzereinstellungen;
• .codex/config.toml in einem Projekt, die Codex erst lädt, wenn du das Projekt als vertrauenswürdig markiert hast.

Ein kleines Beispiel:

model_reasoning_effort = "medium"
web_search = "cached"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true

model legt das Standardmodell fest (mit /model in einer Session siehst du, was dein Account anbietet). model_reasoning_effort steuert, wie lange das Modell nachdenkt. web_search kann cached (Standard), live oder disabled sein; das Flag --search schaltet die Live-Suche für einen Lauf ein.

Die Einstellungen greifen in dieser Reihenfolge, die stärkste zuerst: Kommandozeilen-Flags und -c key=value, die Projektkonfiguration, ein benanntes Profil, das du mit --profile wählst, deine Benutzerkonfiguration und zuletzt die Systemkonfiguration. codex -c model_reasoning_effort="high" ändert den Effort also für einen Lauf, ohne deine Dateien anzufassen. Bist du unsicher, welcher Wert gewonnen hat, zeigt /debug-config die Ebenen.

Schritt 7: MCP-Server verbinden

Mit MCP nutzt Codex externe Werkzeuge: Dokumentationssuche, einen Browser, deinen Issue-Tracker, eine Datenbank. Einen Server fügst du mit einem Befehl hinzu:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Alles nach -- ist der Befehl, der den Server startet. Umgebungsvariablen übergibst du mit --env VAR=wert. Für einen entfernten Server nimmst du codex mcp add <name> --url https://..., und wenn er OAuth nutzt, meldest du dich mit codex mcp login <name> an. codex mcp list zeigt, was eingerichtet ist.

Dieselben Server kannst du auch von Hand in die config.toml schreiben:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

In einer Session listet /mcp die aktiven Server und ihre Tools. Wenn dir das Konzept neu ist, ist was ist ein MCP-Server ein guter Einstieg. Halte die Liste kurz: Jeder Server fügt dem Kontextfenster Tool-Beschreibungen hinzu.

Schritt 8: die Befehle, die du kennen solltest

Slash-Befehle funktionieren in einer Session:

Und ein paar Unterbefehle für die Shell:

Für Automatisierung solltest du dir codex exec merken. Es gibt das Ergebnis aus und beendet sich, akzeptiert --json für maschinenlesbare Ausgabe und --output-last-message, um die letzte Antwort in eine Datei zu schreiben. In CI kombinierst du es mit einer Sandbox, zum Beispiel codex exec --sandbox workspace-write "behebe die Lint-Fehler".

Schritt 9: Sessions fortsetzen und verzweigen

Codex speichert deine Unterhaltungen lokal, ein geschlossenes Terminal kostet dich also keine Arbeit:

• codex resume öffnet eine Auswahl früherer Sessions.
• codex resume --last springt direkt in die neueste aus dem aktuellen Ordner; mit --all suchst du über alle Ordner.
• codex fork (oder /fork in einer Session) kopiert eine Unterhaltung in eine neue, sodass du einen anderen Ansatz probieren kannst, ohne das Original zu verlieren.
• Für nicht interaktive Läufe setzt codex exec resume --last die letzte exec-Session fort.

Verzweigen lohnt sich, wenn Codex guten Kontext zu einem Problem aufgebaut hat und du zwei Lösungen vom selben Ausgangspunkt aus testen willst.

Tipps für bessere Ergebnisse

• Vorher und nachher committen. OpenAI rät selbst, vor und nach einer Aufgabe einen Git-Checkpoint zu setzen. Geht eine Änderung schief, ist git restore schneller als jede Diskussion mit dem Agenten.
• Sag, wie geprüft wird. „Führe pnpm test aus und behebe die Fehler“ bringt bessere Ergebnisse als „mach, dass es läuft“.
• Größere Änderungen planen. Nutze /plan für alles, was mehr als ein, zwei Dateien betrifft, und lies den Plan, bevor Codex bearbeitet.
• Eine Aufgabe pro Unterhaltung. Starte zwischen unabhängigen Aufgaben mit /new neu; alter Kontext kostet Tokens und verwirrt das Modell.
• Lange Sessions verdichten. /compact behält das Wichtige und wirft den Rest weg.
• Worktrees für paralleles Arbeiten. Zwei Agenten im selben Ordner überschreiben sich gegenseitig. Git-Worktrees geben jedem eine eigene Kopie.

Wenn ein Terminal nicht mehr reicht

Sobald Codex zu deinem Alltag gehört, willst du mehr als eine Session laufen lassen: eine behebt einen Bug, eine andere schreibt Tests, vielleicht springt ein zweiter Account ein, wenn der erste sein Limit erreicht. Da wird ein einzelnes Terminal unhandlich.

AgentVera ist eine Desktop-App für macOS, Windows und Linux, die Codex (und andere CLI-Agenten) in echten Terminals nebeneinander ausführt. Sie nutzt den Codex-Login, den du schon hast. Details findest du auf der Seite Codex in AgentVera.

• Workspace: ein Raster von Agenten pro Projekt, von 1×1 bis 5×4. Modell und Effort wählst du pro Agent; die Liste wird live aus Codex gelesen. Nach einem Neustart kehren die Agenten zu ihrer Unterhaltung zurück.
• Berechtigungen pro Agent: Statt dir Flags zu merken, wählst du im Dialog „New agent“ Ask, Auto oder Full access.
• Worktrees: Im Git-Panel erstellst du einen Worktree und startest mit einem Klick einen Agenten darin.
• Account-Wechsel: Jeder Codex-Account bekommt einen eigenen Home-Ordner, die verbleibenden Limits stehen in der Statusleiste, und in Pro und Team wechselt eine Account-Kette zum nächsten Account, wenn das 5-Stunden- oder Wochenlimit erreicht ist.
• MCP-Manager: MCP-Server einmal einrichten; sie werden bei jedem Start an Codex angebunden.
• Automatisches Code-Review: Lass einen anderen Agenten prüfen, was Codex geändert hat, bevor du mergst.

Raster, Worktrees, Code-Review und MCP-Manager gehören zum Free-Tarif. Lade AgentVera herunter und probiere es in deinem eigenen Repo aus.

Fazit

Installiere Codex, starte codex, melde dich mit ChatGPT an und beginne mit einer kleinen, echten Aufgabe. Bleib im Auto-Modus und schalte mit /permissions auf nur Lesen, wenn du nur Antworten willst. Schreib deine Projektregeln in die AGENTS.md, deine Standardwerte in die config.toml, und füge MCP-Server nur hinzu, wenn du sie brauchst. Committe vor und nach jeder Aufgabe und nutze codex resume, um dort weiterzumachen, wo du aufgehört hast. Wenn du auch den Agenten von Google ausprobieren willst, lies Gemini CLI nutzen.