# Codex Schnellstart

> ⚡ **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](/docs/getting-started/one-click-install). 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, [registrieren Sie sich zunächst und wählen Sie einen Tarif](https://qcode.cc/pricing).

---

## Voraussetzungen

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

| Anforderung | Version | Prüfen mit |
|-------------|---------|-------------|
| Node.js | v22 oder höher | `node --version` |
| npm | v10 oder höher | `npm --version` |
| Git | Beliebige Version | `git --version` |
| Betriebssystem | macOS / Linux / Windows (WSL) | - |
| QCode.cc-Key | API-Key, der mit `cr_` beginnt | [Dashboard](https://qcode.cc/dashboard) |

> **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)

```bash
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)

```bash
brew install --cask codex
```

### Option C: Aus dem Quellcode bauen

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

Überprüfen Sie die Installation:

```bash
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

```bash
mkdir -p ~/.codex
```

### 2.2 config.toml schreiben

Erstellen Sie `~/.codex/config.toml`:

```toml
model_provider = "crs"
model = "gpt-6-sol"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"

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

Konfigurationsreferenz:

| Feld | Beschreibung |
|-------|-------------|
| `model_provider` | Verwendet den benutzerdefinierten Anbieter `crs` |
| `model` | Standardmodell, empfohlen wird `gpt-6-sol`; siehe „Verfügbare Modelle“ unten |
| `model_reasoning_effort` | Reasoning-Tiefe. Optionen: `low` / `medium` / `high` |
| `base_url` | Asien-Pazifik-Endpunkt von QCode.cc |
| `wire_api` | API-Protokoll, auf `responses` gesetzt |
| `env_key` | Name der Umgebungsvariable für den API-Key |

### 2.3 auth.json erstellen

Erstellen Sie `~/.codex/auth.json`:

```json
{
  "OPENAI_API_KEY": "cr_your_key_here"
}
```

> Ersetzen Sie `cr_your_key_here` durch den API-Key aus Ihrem [QCode.cc-Dashboard](https://qcode.cc/dashboard).

### 2.4 Umgebungsvariablen setzen

Als Alternative zu `auth.json` (nutzen Sie eine der beiden Methoden):

```bash
# Temporary (current terminal session only)
export CRS_OAI_KEY="cr_your_key_here"

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

# Permanent (Zsh users)
echo 'export CRS_OAI_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](https://qcode.cc/dashboard).

---
## Schritt 3: Einrichtung überprüfen

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

```bash
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](#faq).

---

## Schritt 4: Ihre erste echte Aufgabe

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

```bash
cd /path/to/your/project
```

### Beispiel 1: Projektstruktur analysieren

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

### Beispiel 2: Code generieren

```bash
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

```bash
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.

---

## Drei Berechtigungsmodi

Codex bietet drei Berechtigungsmodi zur Steuerung des Automatisierungsgrads:

### suggest (Vorschlagsmodus)

```bash
codex --suggest "Refactor the auth module"
```

- Analysiert und schlägt nur vor -- **ändert keine Dateien**
- Sie müssen die vorgeschlagenen Änderungen manuell übernehmen
- Am besten geeignet für: Code-Studium, Bewertung von Ansätzen

### auto-edit (Auto-Edit-Modus)

```bash
codex --auto-edit "Add error handling"
```

- **Bearbeitet Dateien automatisch**, fragt aber vor der Ausführung von Befehlen nach einer Bestätigung
- Am besten geeignet für: tägliche Entwicklung (empfohlener Standardmodus)

### Vollautomatisch (`--sandbox workspace-write`)

```bash
codex --sandbox workspace-write "Run tests and fix all failures"
```

- Bearbeitet Dateien automatisch + führt Befehle aus, **keine Bestätigung erforderlich**
- Alle Operationen laufen in der Sandbox und beeinflussen Ihr System nicht
- Am besten geeignet für: CI/CD-Integration, Batch-Aufgaben

> Sie können den Standardmodus auch in `config.toml` festlegen: `approval_mode = "auto-edit"`

---

## Befehlsreferenz

| Befehl | Beschreibung |
|---------|-------------|
| `codex "your instruction"` | Codex mit einer Aufgabe starten |
| `codex --model gpt-6-sol` | Ein Modell angeben |
| `codex --sandbox workspace-write "instruction"` | Vollautomatischer Modus |
| `codex --suggest "instruction"` | Nur Vorschläge, keine Ausführung |
| `codex --auto-edit "instruction"` | Auto-Edit, Befehle erfordern Bestätigung |
| `codex --version` | Version anzeigen |
| `codex --help` | Hilfe anzeigen |

### Verfügbare Modelle

Die folgenden Modelle sind über QCode.cc verfügbar:

| Modell | Beschreibung | Empfohlen für |
|-------|-------------|-----------------|
| `gpt-6-sol` | Flaggschiff, 1,05M Kontext | Allgemein / komplexe Aufgaben (empfohlen ★) |
| `gpt-6.1-sol` | GPT-6 Sol Update (2026-09-29), 1,05M Kontext | Allgemein / komplexe Aufgaben, günstigere Cache-Eingabe |
| `gpt-6-luna` | Schnell, geringe Kosten | Leichtgewichtige Aufgaben |
| `gpt-6-astra` | Stärkstes Niveau, Premium-Preis | Höchste Leistungsfähigkeit |
| `gpt-5.6-terra` | GPT-5.6 Flaggschiff | Coding / komplexe Aufgaben |
| `gpt-5.6-sol` | GPT-5.6 Flaggschiff-Familie | Hochleistungs-Fähigkeit |

---

## 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:

```markdown
# 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](/docs/usage/agents-md).
## Codex mit Claude Code verwenden

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

```bash
# 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](/docs/getting-started/codex-vs-claude-code).

---

## Nächste Schritte

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

- [AGENTS.md-Konfigurationsleitfaden](/docs/usage/agents-md) -- Passen Sie das Projektverhalten von Codex an
- [Codex vs. Claude Code: Ein ausführlicher Vergleich](/docs/getting-started/codex-vs-claude-code) -- Verstehen Sie die Unterschiede und erfahren Sie, wie Sie beide kombinieren
- [Codex-Integrationskonfiguration](/docs/ide/codex) -- Vollständige Konfigurationsreferenz (einschließlich detaillierter Schritte für Windows und mehrere Betriebssysteme)
- [CLI-Tipps & Tricks](/docs/usage/cli-tips) -- 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**:

```bash
# 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. Stellen Sie sicher, dass die Umgebungsvariable `CRS_OAI_KEY` gesetzt ist: `echo $CRS_OAI_KEY`
3. Prüfen Sie, ob der Key nicht abgelaufen ist: Schauen Sie im [QCode.cc Dashboard](https://qcode.cc/dashboard) nach
4. Prüfen Sie, ob `env_key` in `config.toml` korrekt geschrieben ist

### 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 primäre Endpunkt nicht verfügbar ist, versuchen Sie einen Ausweichendpunkt:
   - Backup-Endpunkt: `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](/docs/ide/codex).