Codex Schnellstart

Codex CLI in 5 Minuten installieren und konfigurieren -- KI-gestütztes Programmieren mit QCode.cc

Brauchen Sie einen API-Key? Registrieren →·Endpunkte & Base-URLs →

⚡ Empfohlen: Einrichtung mit einem Klick — curl -fsSL https://qcode.cc/install/codex.sh | bash (Windows: irm https://qcode.cc/install/codex.ps1 | iex) installiert die CLI, schreibt die Konfiguration unter ~/.codex und prüft die Verbindung. Siehe Einrichtungsskript mit einem Klick. Lesen Sie weiter, wenn Sie die Einrichtung manuell vornehmen möchten.

Wenn Sie bereits Claude Code verwenden, ist Codex CLI mit dieser Anleitung in 5 Minuten einsatzbereit. Beide Tools teilen sich das Kontingent Ihres QCode.cc-Tarifs und verwenden denselben API-Key. Nach der Einrichtung können Sie daher frei zwischen ihnen wechseln.

Wenn Sie noch kein QCode.cc-Konto haben, wählen Sie zunächst einen Tarif und holen Sie sich den Key (der Key wird bei jeder Option gleich verwendet).

Voraussetzungen¶

Stellen Sie vor dem Start sicher, dass Ihre Umgebung die folgenden Anforderungen erfüllt:

Hinweis: Die Sandbox von Codex auf Kernel-Ebene funktioniert unter Linux am besten. macOS und Windows WSL werden ebenfalls vollständig unterstützt, allerdings können einige Sandbox-Funktionen eingeschränkt sein.

Schritt 1: Codex CLI installieren¶

Wählen Sie eine der folgenden Installationsmethoden:

Option A: Globale Installation per npm (empfohlen)¶

npm install -g @openai/codex

# Users in China can speed this up with the Taobao mirror
npm install -g @openai/codex --registry=https://registry.npmmirror.com

Option B: Homebrew (macOS)¶

brew install --cask codex

Option C: Aus dem Quellcode bauen¶

git clone https://github.com/openai/codex.git
cd codex
cargo build --release
cp target/release/codex ~/.local/bin/

Überprüfen Sie die Installation:

codex --version
# should print a version (trust `codex --version` on this machine, not a stale number from the web)

Schritt 2: QCode.cc konfigurieren¶

2.1 Konfigurationsverzeichnis erstellen¶

mkdir -p ~/.codex

2.2 config.toml schreiben¶

Erstellen Sie ~/.codex/config.toml:

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true

Erläuterung der Felder:

2.3 auth.json erstellen¶

Erstellen Sie ~/.codex/auth.json:

{
  "OPENAI_API_KEY": "cr_your_key_here"
}

Ersetzen Sie cr_your_key_here durch den API-Key aus Ihrem QCode.cc-Dashboard.

2.4 Umgebungsvariablen setzen¶

Wenn Sie den Key stattdessen per Umgebungsvariable übergeben möchten, ersetzen Sie in [model_providers.qcode] die Zeile requires_openai_auth = true durch env_key = "QCODE_API_KEY" und exportieren Sie die Variable. Wählen Sie nur eine der beiden Varianten: Die offizielle Dokumentation legt fest, dass Codex env_key ignoriert, wenn requires_openai_auth = true gesetzt ist. Die vollständige Konfiguration für die Variante mit Umgebungsvariable:

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
env_key = "QCODE_API_KEY"

Setzen Sie anschließend die Umgebungsvariable:

# Temporary (current terminal session only)
export QCODE_API_KEY="cr_your_key_here"

# Permanent (Bash users)
echo 'export QCODE_API_KEY="cr_your_key_here"' >> ~/.bashrc
source ~/.bashrc

# Permanent (Zsh users)
echo 'export QCODE_API_KEY="cr_your_key_here"' >> ~/.zshrc
source ~/.zshrc

Tipp: Dies ist derselbe Key, den Sie für Claude Code verwenden. Wenn Sie bereits Claude Code nutzen, finden Sie den Key an derselben Stelle im Dashboard.

Schritt 3: Einrichtung überprüfen¶

Führen Sie eine einfache Aufgabe aus, um die Verbindung zu testen:

codex "print hello world"

Wenn Codex normal startet und eine Antwort zurückgibt, ist die Konfiguration erfolgreich.

Checkliste¶

• Codex startet ohne Fehlermeldungen
• API-Anfragen werden über QCode.cc geleitet (keine Netzwerk-Timeouts)
• Modellantworten funktionieren korrekt (versteht Ihre Anweisungen)

Bei Problemen wechseln Sie zum Abschnitt FAQ.

Schritt 4: Ihre erste echte Aufgabe¶

Probieren wir ein praktisches Szenario, um zu erleben, was Codex kann. Navigieren Sie in ein Projektverzeichnis:

cd /path/to/your/project

Beispiel 1: Projektstruktur analysieren¶

codex "Analyze this project's directory structure and tech stack, and give a brief overview"

Beispiel 2: Code generieren¶

codex "Create a utils/date-formatter.ts file with these features:
  1. Format a date as YYYY-MM-DD
  2. Calculate the number of days between two dates
  3. Determine whether a date is a business day
  4. Add complete JSDoc comments and unit tests for each function"

Beispiel 3: Stapelweise Änderungen¶

codex "Convert all .js files under src/ to .ts files and add type annotations"

Codex erledigt die Aufgabe autonom in einer Sandbox-Umgebung und stellt Ihnen anschließend eine Zusammenfassung der Änderungen zur Überprüfung bereit.

Berechtigungen und Sandbox¶

Codex steuert mit zwei Optionen, was es tun darf (--sandbox) und wann es bei Ihnen nachfragt (--ask-for-approval). Die folgenden Angaben stammen aus der offiziellen OpenAI-Dokumentation (Stand 2026-10-15).

Standard: Workspace beschreibbar, Genehmigung auf Anfrage¶

codex "Refaktoriere das Auth-Modul"

• In einem Git-Repository gilt dieses Preset ohne Optionen: Codex liest Dateien, bearbeitet sie und führt Befehle im Workspace aus und fragt vor Schreibzugriffen außerhalb davon oder Netzwerknutzung zuerst nach
• Geeignet für: die tägliche Entwicklung (empfohlene Standardeinstellung)

Nur lesen: ansehen, nichts ändern¶

codex --sandbox read-only --ask-for-approval on-request "Analysiere das Auth-Modul und schlage ein Refactoring vor"

• Schreibgeschützte Sandbox -- ändert keine Dateien
• Geeignet für: Code verstehen, Ansätze bewerten

Nicht-interaktiv und Automatisierung¶

codex exec --sandbox workspace-write "Führe die Tests aus und behebe alle Fehler"

• codex exec läuft nicht-interaktiv und gibt das Ergebnis auf der Standardausgabe aus (mit --json als JSONL)
• Die Sandbox ist auf den Workspace begrenzt und beeinflusst das System außerhalb nicht
• Geeignet für: CI/CD-Integration, Stapelaufgaben

Die Standardwerte lassen sich auch in der config.toml festlegen: approval_policy = "on-request" und sandbox_mode = "workspace-write". Die Schreibweisen --suggest, --auto-edit und approval_mode aus älteren Tutorials stehen nicht in der aktuellen offiziellen Optionsliste; im Zweifel gilt codex --help.

Befehlsreferenz¶

Verfügbare Modelle¶

Über QCode.cc stehen folgende Modelle zur Verfügung:

QCode bietet gpt-6-luna / gpt-5.6-luna derzeit nicht an. Bitte verwenden Sie ein anderes GPT-Modell. QCode rechnet pro Token ab, die Preise je Modell stehen auf qcode.cc/models.

Kein gpt-6.1-sol im /model-Menü? Mit der obigen Konfiguration zeigt das /model-Menü von Codex die im Client eingebaute Modellliste – sie hängt also von Ihrer Codex-Version ab: gpt-6.1-sol erscheint im Menü ab Codex 0.160.0. Aktualisieren Sie auf die neueste Version (npm install -g @openai/codex@latest, mit Homebrew brew upgrade --cask codex). Es geht auch ohne Update: model = "gpt-6.1-sol" in der config.toml (oder codex --model gpt-6.1-sol) ist vom Menü unabhängig. Umgekehrt kann gpt-6-luna im Menü auftauchen; QCode bietet dieses Modell derzeit nicht an, eine Auswahl führt zu einem Fehler.

Projektkonfiguration: AGENTS.md¶

Erstellen Sie eine AGENTS.md-Datei im Stammverzeichnis Ihres Projekts, um festzulegen, wie Codex sich in diesem Projekt verhalten soll -- ähnlich wie CLAUDE.md bei Claude Code:

# AGENTS.md

- Use TypeScript strict mode
- Code style follows ESLint + Prettier
- Test framework: Vitest
- Run `npm run lint && npm test` before committing
- Component files use PascalCase naming

Für detaillierte Konfigurationen siehe den AGENTS.md Konfigurationsleitfaden.

Codex mit Claude Code verwenden¶

Da beide Tools sich das Kontingent von QCode.cc teilen, empfiehlt es sich, sie gemeinsam einzusetzen:

# Terminal 1: Use Claude Code to analyze the problem
$ claude
> Where's the performance bottleneck? Help me analyze the approach.

# Terminal 2: Use Codex for batch execution
$ codex "Optimize all database queries under src/api/ according to this plan:
  1. Add query caching
  2. Fix N+1 queries
  3. Add index suggestion comments"

Weitere Kombinationsmuster finden Sie unter Codex vs. Claude Code: Ein ausführlicher Vergleich.

Nächste Schritte¶

Die Konfiguration ist abgeschlossen -- Sie können jetzt mit Codex loslegen. Empfohlene Lektüre:

• AGENTS.md-Konfigurationsleitfaden -- Passen Sie das Projektverhalten von Codex an
• Codex vs. Claude Code: Ein ausführlicher Vergleich -- Verstehen Sie die Unterschiede und erfahren Sie, wie Sie beide kombinieren
• Codex-Integrationskonfiguration -- Vollständige Konfigurationsreferenz (einschließlich detaillierter Schritte für Windows und mehrere Betriebssysteme)
• CLI-Tipps & Tricks -- Produktivitätstipps für KI-gestütztes Programmieren

FAQ¶

Q: Die Installation schlägt mit npm ERR! EACCES fehl¶

Ursache: Unzureichende Berechtigungen für das globale npm-Installationsverzeichnis.

Lösung:

# Option A: Use sudo (not recommended long-term)
sudo npm install -g @openai/codex

# Option B: Configure npm to use a user directory (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

Q: API key not found oder Authentifizierungsfehler¶

Schritte zur Fehlersuche:

1. Stellen Sie sicher, dass der Key in ~/.codex/auth.json mit cr_ beginnt
2. Bei der Variante mit Umgebungsvariable: Im Provider muss env_key = "QCODE_API_KEY" stehen (ohne requires_openai_auth = true) und die Variable exportiert sein: echo $QCODE_API_KEY
3. Prüfen Sie, ob der Key nicht abgelaufen ist: Schauen Sie im QCode.cc Dashboard nach
4. Prüfen Sie TOML-Syntax und Provider-Namen in config.toml

Q: Verbindungs-Timeout oder Netzwerkfehler¶

Schritte zur Fehlersuche:

1. Stellen Sie sicher, dass base_url auf https://api.qcode.cc/openai gesetzt ist
2. Testen Sie die Netzwerkverbindung: curl -I https://api.qcode.cc

3. Falls der aktuelle Zugangspunkt nicht verfügbar ist, versuchen Sie einen anderen:

4. Asien-Zugangspunkt: https://asia.qcode.cc/openai

Q: Ist der Codex-Key derselbe wie der Claude Code-Key?¶

Ja. Beide verwenden denselben QCode.cc API-Key mit gemeinsamem Kontingent. Sie benötigen keinen separaten Key.

Q: Funktioniert es unter Windows?¶

Ja, wir empfehlen jedoch die Verwendung von WSL (Windows Subsystem for Linux). Auch die native Windows-Unterstützung wird laufend verbessert. Detaillierte Schritte zur Einrichtung unter Windows finden Sie unter Codex-Integrationskonfiguration.

Enterprise →