# Migration von Claude Code zu Codex: Übertragung von CLAUDE.md, MCP, Skills, Slash-Befehlen und Einstellungen

> Umfassender Leitfaden zur Migration von Claude Code zu OpenAI Codex CLI: Übertragung von CLAUDE.md in AGENTS.md, Konfiguration von MCP, Einstellung von Zugriffsrechten, Hooks sowie Beibehaltung der Claude-Modelle.

Codex wird mit einem Ein-Befehl-Importer ausgeliefert, der den Großteil der Claude Code-Konfiguration eigenständig migriert. Die eigentliche Herausforderung liegt im Detail: Einige Konfigurationsaspekte müssen manuell nachgebaut werden, und ein Punkt lässt sich gar nicht direkt übertragen – und dabei handelt es sich nicht um eine Konfigurationsdatei, sondern um die Anthropic-Modelle selbst.

Die Übertragung des nahezu vollständigen Claude Code-Einstellungssets in Codex dauert etwa 20 Minuten. Im Folgenden finden Sie die grundlegenden Orientierungspunkte für einen schnellen Start.

---

## 1. Was migriert wird und was nicht – das schnelle Fazit

### 1.1. Express-Diagnose: Kompatibilitätstabelle der Schnittstellen

| Frage | Lösung / Antwort |
| :--- | :--- |
| Kann der Großteil der Konfiguration migriert werden? | **Ja.** 9 von 12 Schnittstellen lassen sich ohne schwerwiegende Probleme migrieren oder neu aufbauen. |
| Der schnellste Weg? | `codex` → `/import` (Codex 0.140+), danach manuelle Nachbearbeitung von 3 Punkten. |
| Was wird automatisch migriert? | Memory-Dateien, MCP-Server, Skills, Slash-Befehle, benutzerdefinierte Endpunkte. |
| Was erfordert manuelle Nacharbeit? | Das Berechtigungsmodell, das Hook-Format, Sub-Agent-Wrappers. |
| Die einzige Sackgasse? | Anthropic Claude Modelle. Vanilla Codex funktioniert nur mit OpenAI-Modellen. |
| Lösung für die Sackgasse? | Fügen Sie ein Gateway als `model_provider` hinzu und nutzen Sie Claude weiterhin innerhalb von Codex. |

> 📌 **Umgebungsversionen:** Dieser Leitfaden wurde mit Codex CLI 0.142.5 (Stand: 1. Juli 2026) und Claude Code 2.1.178 getestet. Wenn Sie eine ältere Codex-Version verwenden, aktualisieren Sie unbedingt, da der Befehl `/import` erst in Version 0.140.0 eingeführt wurde.

### 1.2. Automatische und manuelle Migrationskomponenten

**Was reibungslos migriert werden kann:**
- Anweisungen für das Repository und persönliche Einstellungen (Inhalt von `CLAUDE.md`).
- **MCP-Server** – Befehl und Argumente werden wortgetreu übernommen.
- **Skills** – Diese folgen der Agent-Skills-Konvention, die für beide Tools gemeinsam ist.
- Slash-Befehle und wiederverwendbare Prompts.
- Benutzerdefinierte API-Endpunkte und Autorisierungsschlüssel.

**Was einen Umweg oder manuellen Neuaufbau erfordert:**
- Die schrittweise Erlaubnisliste (`permission allowlist`) von Claude Code – Codex verwendet eine zweistufige Sandbox.
- Das Event-Hook `ConfigChange` (Codex bietet `PreCompact`/`PostCompact`, aber keinen Trigger bei Änderungen der Konfigurationsdatei).
- **Output styles** – Das Konzept der Ausgabestile fehlt in Codex.
- **Anthropic-Modelle** – Standard-Codex unterstützt nur OpenAI-Modelle; für Claude ist ein Gateway-Provider erforderlich.

---

## 2. Vollständige Karte: Alle 12 Claude Code-Konfigurationen und ihre Pendants in Codex

### 2.1. Zusammenfassende Vergleichsmatrix der Konfigurationsoberflächen

Die meisten Parameter gehen verlustfrei über, da beide Tools dieselben ingenieurtechnischen Aufgaben lösen, jedoch unterschiedliche Serialisierungsformate verwenden: Claude Code setzt auf JSON (`settings.json`, `.mcp.json`) und Markdown (`CLAUDE.md`, `.claude/agents/*.md`), während Codex auf eine einzelne TOML-Datei (`~/.codex/config.toml`) und `AGENTS.md` zurückgreift.

| Nr. | Claude Code Oberfläche | Analogon in Codex | Migrationsurteil |
| :---: | :--- | :--- | :--- |
| 1 | `CLAUDE.md` (Memory) | `AGENTS.md` (oder Dateiname-Fallback) | Migriert |
| 2 | `.mcp.json` (JSON) | `[mcp_servers.*]` in `config.toml` | Migriert, mit Neuformatierung |
| 3 | `.claude/skills/` | Codex Skills (`[[skills.config]]`) | Migriert |
| 4 | `.claude/commands/` | Codex Slash-Befehle / Prompts | Migriert, erfordert Neuaufbau |
| 5 | `.claude/agents/` (Markdown) | `.codex/agents/*.toml` Dateien | Neuaufbau |
| 6 | `settings.json` (JSON) | `config.toml` + Profile (TOML) | Neuaufbau |
| 7 | `permissions.allow/ask/deny` | `approval_policy` + `sandbox_mode` | Nicht direkt migriert |
| 8 | Hooks (`PreToolUse`, `Stop`, …) | `[[hooks.*]]` in `config.toml` | Neuaufbau |
| 9 | Hook `ConfigChange` | Kein Analogon | Kein Analogon vorhanden |
| 10 | Endpoint `ANTHROPIC_BASE_URL` | `[model_providers.*]` | Migriert |
| 11 | `outputStyle` | Kein Analogon | Kein Analogon vorhanden |
| 12 | Anthropic Claude Modelle | Nur OpenAI-Modelle standardmäßig | Sackgasse (gelöst über Gateway) |

### 2.2. Wichtige architektonische Unterschiede: JSON vs. TOML

Die Zeilen 9 und 11 der Matrix sind kosmetischer Natur: `outputStyle` hat praktisch keinen Einfluss auf die Leistung, und `ConfigChange` wird nur von einem kleinen Kreis von Entwicklern mit dynamischen Sitzungskonfigurationen benötigt.

Der Hauptbarriere stellt in der Regel Zeile 12 dar (Anthropic-Modelle). Allerdings ermöglicht die Verbindung eines Gateways über den Abschnitt `[model_providers]` die nahtlose Beibehaltung der gewohnten Intelligenz von Claude innerhalb der Codex-Umgebung.

---

## 3. Wann migrieren und wann bei Claude Code bleiben

### 3.1. Szenarien und technische Kriterien für den Wechsel zu Codex

Eine Migration zu Codex ist gerechtfertigt, wenn Ihre Workflows auf autonome Aufgaben und Dateisystemisolierung ausgerichtet sind:
- **Automatisierung in CI/CD:** Sie müssen Agenten nicht-interaktiv mit strengen „read-only“- oder „workspace-write“-Einschränkungen ausführen.
- **Teamstandardisierung:** Es ist notwendig, eine einzige committete `config.toml`-Datei mit fertigen Profilen für verschiedene Risikostufen anstelle fragmentierter `.claude/settings.local.json`-Dateien zu haben.
- **Neue OpenAI Codex Modelle:** Zugriff auf die Modelle `gpt-5.5` und `gpt-5.4` als primäres Tool für Codegenerierung ist erforderlich.

### 3.2. Fälle, in denen es sinnvoll ist, bei Claude Code zu bleiben

Bleiben Sie bei Claude Code, wenn Ihre Pipeline folgende Merkmale aufweist:
- **Abhängigkeit von spezifischen Hooks:** Verwendung der Trigger `ConfigChange` oder Formatierungsstile `outputStyle`.
- **Dialogbasierte Interaktion:** Die gesamte Arbeit basiert auf langen interaktiven Gesprächen. Die dialogorientierte Natur von Claude Code ist dafür besser optimiert als der Batch-Zyklus „Aufgabe → Verifizierung“ von Codex.
- **Feingranularer Allowlist:** Wenn eine mehrstufige Erlaubnisliste mit regulären Ausdrücken für jeden Systemaufruf konfiguriert ist, erfordert der Wechsel zu den groberen Sandbox-Richtlinien von Codex eine Überprüfung des gesamten Sicherheitsmodells.

> 💡 **Stopp-Regel:** Wenn Ihr Ziel darin besteht, die Qualität der Codegenerierung von Codex im aktuellen Repository zu testen, müssen Sie die Konfiguration nicht vollständig migrieren. Es reicht aus, den Befehl `/import` im Codex-Terminal auszuführen. Detaillierte manuelle Einstellungen sind nur für diejenigen erforderlich, die Codex zum primären Arbeitswerkzeug machen möchten.

---

## 4. Systemanforderungen vor dem Start

### 4.1. Überprüfung der CLI-, Projekt- und Berechtigungsversionen

Vergewissern Sie sich vor der Bearbeitung der Konfiguration, dass vier obligatorische Bedingungen erfüllt sind:
1. **Codex CLI Version 0.140.0 oder neuer.** Prüfen Sie die Version mit dem Befehl `codex --version`.
2. **Gesichertes Claude Code-Projekt:** Das Verzeichnis `.claude/` und die Datei `CLAUDE.md` müssen bis zur vollständigen Verifizierung der Migration unberührt bleiben.
3. **API-Schlüssel des Providers:** Ein aktiver OpenAI-Schlüssel oder ein Gateway-Schlüssel (z. B. ofox.ai) ist für die Arbeit mit Claude erforderlich.
4. **Schreibrechte im Home-Verzeichnis:** Codex liest globale Parameter bei jedem Start aus `~/.codex/config.toml`.

### 4.2. Migrationspfad: Schrittweiser Übergangsprozess

Der allgemeine Übergangsprozess besteht aus sechs sequenziellen Phasen:

```mermaid
flowchart LR
    A["Аудит CLAUDE.md + settings.json"] --> B["Запуск codex /import"]
    B --> C["Аналіз звіту конфліктів"]
    C --> D["Ручне налаштування прав та хуків"]
    D --> E["Додавання model_provider для Claude"]
    E --> F["Тест із read-only профілем"]
```

---

## 5. Schrittweise Konfigurationsmigration

### 5.1. Schritt 1: Starten des automatischen Importers (/import)

Starten Sie Codex im Wurzelverzeichnis Ihres Projekts und führen Sie den internen Importbefehl aus:

```bash
cd my-project
codex
# Всередині інтерактивної сесії Codex:
/import
```

Der Befehl `/import` führt eine selektive Übertragung von Einstellungen, Systemanweisungen und letzten Sitzungen durch. Das Ergebnis ist eine initiale `~/.codex/config.toml`-Datei, ein projektbezogenes `AGENTS.md` sowie ein Bericht über übersprungene Parameter.

### 5.2. Schritt 2: Anweisungen – Wechsel von CLAUDE.md zu AGENTS.md

Codex sucht automatisch nach `AGENTS.md`. Um die Kompatibilität zu erhalten oder die alte Datei ohne Umbenennung weiter einzulesen, fügen Sie Fallback-Pfade zur Konfiguration hinzu:

```toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]
project_doc_max_bytes = 32768
```

Der Inhalt der Anweisungen erfordert keine Bearbeitung: Coding-Stil-Regeln, Build-Befehle und Tests werden unverändert in den Systemkontext des Agenten geladen.

### 5.3. Schritt 3: MCP-Server – Konvertierung von JSON in TOML

Beide Plattformen nutzen das Model Context Protocol. Lediglich die Syntax der Beschreibung ändert sich: Die Konfiguration aus `.mcp.json` wird in TOML-Tabellen übertragen.

Ursprünglicher Eintrag in `.mcp.json`:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}
```

Äquivalenter Eintrag in `~/.codex/config.toml`:

```toml
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
```

Wenn der Server Umgebungsvariablen erfordert, geben Sie diese inline an: `env = { GITHUB_TOKEN = "..." }`. Sowohl lokale STDIO-Prozesse als auch entfernte SSE/HTTP-Server werden unterstützt.

### 5.4. Schritt 4: Sub-Agenten – Konfiguration in .codex/agents/

Claude Code speichert Agenten als Markdown-Dateien in `.claude/agents/`. Codex verwendet das TOML-Format, wobei jeder Sub-Agent durch eine separate Datei im Verzeichnis `~/.codex/agents/` oder `.codex/agents/` beschrieben wird:

```toml
# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews diffs for correctness and style"
developer_instructions = """
Review the diff for correctness and style. Cite file and line for each issue found.
"""
```

Sub-Agenten in Codex sind standardmäßig aktiv und werden auf explizite Anfrage des Benutzers oder des Hauptagenten aufgerufen.

### 5.5. Schritt 5: Berechtigungsmodell – Einstellung von Sandbox und Approval

Die Sicherheitskonzepte der Tools unterscheiden sich erheblich: Anstelle einer granulareren Glob-Regelliste (`permissions.allow`) verwendet Codex Parameter für die Dateisystemisolierung (`sandbox_mode`) und die Bestätigung von Aktionen (`approval_policy`).

| Szenario in Claude Code | Zweck | Einstellung in Codex (`~/.codex/config.toml`) |
| :--- | :--- | :--- |
| `allow: ["Bash(npm run test *)"]` | Automatische Ausführung sicherer Befehle | `sandbox_mode = "workspace-write"`<br>`approval_policy = "on-request"` |
| `ask: ["Bash(python *)"]` | Bestätigungsanfrage vor Ausführung | `approval_policy = "on-request"` |
| `deny: ["Read(./.env)"]` | Blockierung des Zugriffs außerhalb des Verzeichnisses | `sandbox_mode = "workspace-write"` |
| `Plan mode` | Analysemodus ohne Änderungen | `sandbox_mode = "read-only"` |
| `--dangerously-skip-permissions` | Volle Autonomie | `approval_policy = "never"`<br>`sandbox_mode = "danger-full-access"` |

Ausgewogene Konfiguration für die tägliche Entwicklung:

```toml
# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

### 5.6. Schritt 6: Hooks – Übertragung von Lifecycle-Ereignissen

Hooks in Codex sind standardmäßig aktiviert und decken wichtige Systemereignisse ab: `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` und `PostCompact`.

```toml
# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"
```

> ⚠️ **Hinweis:** Das Ereignis `ConfigChange` wird von Codex nicht unterstützt. Jede Logik, die auf Modifikationen von Konfigurationsdateien „on-the-fly“ reagierte, sollte in Skripte vor dem Sitzungsstart verschoben werden.

---

## 6. Migrations-Sackgasse: Claude-Modelle in Codex und wie sie erhalten bleiben

### 6.1. Architektur des model_provider-Gateways für Anthropic-Modelle

Codex ist auf das OpenAI-Ökosystem (`gpt-5.5`, `gpt-5.4`) optimiert und verfügt über keinen direkten Schalter für Anthropic-Modelle. Wenn Sie für architektonische Aufgaben Claude Opus oder Claude Sonnet benötigen, erfolgt die Verbindung über ein kompatibles API-Gateway.

Fügen Sie die Provider-Definition in `~/.codex/config.toml` hinzu:

```toml
# ~/.codex/config.toml
[model_providers.ofox]
name = "ofox.ai gateway"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"
requires_openai_auth = false
```

### 6.2. Einstellung von wire_api=responses und Auswahl des claude-Profils

Bei der Gateway-Konfiguration sind zwei Parameter kritisch zu beachten:
1. `wire_api = "responses"`: Die Unterstützung des veralteten `chat`-Protokolls wurde im Februar 2026 aus Codex entfernt.
2. `requires_openai_auth = false`: Deaktiviert die Validierung des Präfixes `sk-` auf Client-Seite.

Erstellen Sie ein Profil zum Starten von Claude in `~/.codex/claude.config.toml`:

```toml
# ~/.codex/claude.config.toml
model = "anthropic/claude-opus-4.8"
model_provider = "ofox"
```

Der Start des Agenten mit diesem Profil erfolgt über den Befehl:

```bash
codex --profile claude
```

---

## 7. Häufige Migrationsfehler und deren Lösungen

### 7.1. Diagnose- und Fehlerbehebungsmatrix

| Symptom | Ursache | Ingenieurtechnische Lösung |
| :--- | :--- | :--- |
| Codex ignoriert `CLAUDE.md` | Standardmäßig wird `AGENTS.md` erwartet | Benennen Sie die Datei um oder fügen Sie `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]` hinzu |
| Custom Provider gibt Fehler `401` zurück | Client erwartet ein OpenAI-Token mit Präfix `sk-` | Fügen Sie die Direktive `requires_openai_auth = false` im Abschnitt `[model_providers.*]` hinzu |
| Ausführungsfehler `chat wire API deprecated` | Protokoll `chat` ist veraltet und entfernt | Geben Sie den Parameter `wire_api = "responses"` an |
| Sub-Agenten führen keine Aktionen aus | Beschreibungsdatei fehlt oder Agent wird nicht explizit aufgerufen | Erstellen Sie `.codex/agents/NAME.toml`; Codex aktiviert Agenten nur per direktem Befehl |
| Hooks feuern nicht | Fehler im Ereignisnamen oder inkorrektes Regex-Muster | Überprüfen Sie die Ereignissyntax und den `matcher`-Ausdruck in `[[hooks.*]]` |
| Befehl aus Allowlist wird blockiert | Codex-Sandbox ist strenger als punktuelle Regeln | Erweitern Sie `sandbox_mode` oder setzen Sie `approval_policy = "on-request"` |

### 7.2. Überprüfung vertrauenswürdiger Verzeichnisse und Konfigurationsvalidierung

Wenn die Datei `.codex/config.toml` im Projekt vollständig ignoriert wird, stellen Sie sicher, dass das Repository zur Liste der vertrauenswürdigen Einträge hinzugefügt wurde. Aus Sicherheitsgründen lädt Codex lokale Konfigurationen nur für geprüfte Pfade und blockiert Versuche von Projektdateien, globale Autorisierungen oder Provider-Schlüssel zu überschreiben.

---

## 8. Migration für Teams

### 8.1. Zentralisierung von config.toml vs. individuelle .local.json

In der Claude Code-Umgebung waren Teams gezwungen, zwei Ebenen zu pflegen: eine gemeinsame Datei `.claude/settings.json` im Repository und lokale Dateien jedes Entwicklers `.claude/settings.local.json`. Codex vereinfacht dieses Schema:

| Aspekt der Zusammenarbeit | Claude Code | OpenAI Codex CLI |
| :--- | :--- | :--- |
| Gemeinsame Team-Konfiguration | `.claude/settings.json` (committet) | `.codex/config.toml` (committet ins Repository) |
| Persönliche Einstellungen | `.claude/settings.local.json` | Persönliche Profildateien in `~/.codex/` |
| Basis-Anweisungen des Projekts | `CLAUDE.md` | `AGENTS.md` |
| Granularität der Risikostufen | `permission allowlist` | Flags `--profile strict` oder `--profile fast` |

### 8.2. Einheitliches API-Gateway und gemeinsames Team-Billing

Die Nutzung eines einheitlichen Gateways über `model_provider` optimiert die Teamkosten:
- Der Administrator fügt Gateway-Parameter in die committete Datei `.codex/config.toml` ein.
- Jeder Ingenieur erhält einen persönlichen Schlüssel über den Corporate Secret Manager (`OFOX_API_KEY`).
- Das gesamte Team nutzt einen einzigen Routing-Punkt mit gemeinsamem Billing, unabhängig davon, ob der Entwickler mit `openai/gpt-5.5` oder `anthropic/claude-opus-4.8` arbeitet.

---

## 9. Fortgeschrittenes Niveau: Profile für CI, lokale Arbeit und Review

### 9.1. Einrichtung spezialisierter Sicherheitsprofile

Profile in Codex werden als separate Dateien im Verzeichnis `~/.codex/` gespeichert und über den Flag `--profile` aktiviert. Dies eliminiert die Notwendigkeit, globale Konfigurationsdateien zu ändern.

Beispielkonfiguration für automatisiertes Audit in CI/CD:

```toml
# ~/.codex/ci.config.toml
model = "gpt-5.5"
approval_policy = "never"
sandbox_mode = "read-only"
```

### 9.2. Praktische Szenarien: Isoliertes Audit in CI und lokale Entwicklung

Der Start des Befehls `codex --profile ci` garantiert, dass der Agent den Code prüfen und Berichte erstellen kann, aber technisch nicht in der Lage ist, nicht autorisierte Änderungen an Dateien vorzunehmen oder Daten nach außen zu senden.

Für die tägliche Entwicklung wird ein lokales Profil mit `sandbox_mode = "workspace-write"` verwendet, während für komplexe architektonische Analysen `codex --profile claude` genutzt wird, das Claude Opus aktiviert, ohne die globalen Systemeinstellungen zu ändern.

---

## 10. Häufig gestellte Fragen (FAQ)

### 10.1. Kompatibilität von Modellen und Konfigurationsdateien

> ❓ **Kann ich die originalen Claude-Modelle in Codex CLI verwenden?**  
> Standard-Codex funktioniert nur mit OpenAI-Modellen. Sie können jedoch jedes Anthropic-Modell (z. B. `anthropic/claude-opus-4.8`) anschließen, indem Sie einen OpenAI-kompatiblen API-Gateway im Abschnitt `[model_providers]` registrieren und ihn im Profil angeben.

> ❓ **Liest Codex CLI die Memory-Datei CLAUDE.md?**  
> Standardmäßig sucht Codex nach `AGENTS.md`. Um die Kompatibilität ohne Informationsduplizierung zu erhalten, fügen Sie in `~/.codex/config.toml` die Zeile `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]` hinzu.

> ❓ **Wie importiere ich schnell fertige Einstellungen aus Claude Code?**  
> Starten Sie `codex` im Projektverzeichnis und führen Sie den Befehl `/import` aus. Der eingebettete Importer überträgt Anweisungen, MCP-Server und Kontextbefehle und erstellt eine Liste der Punkte, die manuelle Aufmerksamkeit erfordern.

> ❓ **Gibt es Unterschiede zwischen den Dateien AGENTS.md und CLAUDE.md?**  
> Ihre Funktionalität ist identisch. `AGENTS.md` ist ein offener, toolübergreifender Standard für AI-Agenten, während `CLAUDE.md` ein internes Format von Claude Code ist. Der Inhalt beider Dateien wird gleich interpretiert.

### 10.2. Technische Nuancen von Hooks, MCP und Sub-Agenten

> ❓ **Unterstützt Codex CLI Hook-Lifecycle-Zyklen wie Claude Code?**  
> Ja, Hooks sind standardmäßig aktiviert. Unterstützte Ereignisse sind `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` und `PostCompact`. Der einzige Hook ohne direktes Pendant ist `ConfigChange`.

> ❓ **Können Claude Code und Codex gleichzeitig dieselben MCP-Server nutzen?**  
> Ja. Die Mechanik des MCP-Protokolls ist identisch. Lediglich die Darstellungsform ändert sich: Statt der JSON-Struktur in `.mcp.json` werden die Parameter als TOML-Tabellen in `config.toml` deklariert.

> ❓ **Muss ich den Code der Sub-Agenten während der Migration umschreiben?**  
> Nein, die Systemanweisungen selbst werden unverändert übertragen. Es muss lediglich der Wrapper geändert werden: Verschieben Sie den Text aus den Markdown-Dateien `.claude/agents/*.md` in den Parameter `developer_instructions` der entsprechenden `.codex/agents/*.toml`-Dateien.