# Migration de Claude Code vers Codex : comment transférer CLAUDE.md, MCP, les skills, les commandes slash et les paramètres

> Guide complet pour migrer de Claude Code vers OpenAI Codex CLI : transfert de CLAUDE.md vers AGENTS.md, configuration de MCP, gestion des droits d'accès, des hooks et préservation des modèles Claude.

Codex est livré avec un importateur en une seule commande qui transfère automatiquement la majeure partie de la configuration de Claude Code. Le défi réside dans les détails : certains éléments de configuration doivent être assemblés manuellement, et un point ne se transfère pas directement — il ne s'agit pas du fichier de configuration lui-même, mais des modèles Anthropic.

Transférer l'ensemble quasi complet des paramètres de Claude Code vers Codex prend environ 20 minutes. Voici les repères essentiels pour un démarrage rapide.

---

## 1. Ce qui est transféré, ce qui ne l'est pas — verdict rapide

### 1.1. Diagnostic express : tableau de compatibilité des surfaces

| Question | Solution / Réponse |
| :--- | :--- |
| Peut-on transférer la majeure partie de la configuration ? | **Oui.** 9 des 12 surfaces sont transférées ou restructurées sans problèmes majeurs. |
| Le chemin le plus rapide ? | `codex` → `/import` (Codex 0.140+), puis ajuster manuellement 3 points. |
| Ce qui est transféré automatiquement ? | Fichiers de mémoire, serveurs MCP, skills, slash-commands, endpoints personnalisés. |
| Ce qui nécessite un ajustement manuel ? | Modèle de droits d'accès, format des hooks, wrappers de sous-agents. |
| Le seul cul-de-sac ? | Les modèles Anthropic Claude. Codex vanilla fonctionne uniquement avec les modèles OpenAI. |
| Solution pour le cul-de-sac ? | Ajouter un gateway comme `model_provider` et continuer à utiliser Claude au sein de Codex. |

> 📌 **Versions de l'environnement :** Ce guide a été testé sur Codex CLI 0.142.5 (1er juillet 2026) et Claude Code 2.1.178. Si vous utilisez une version antérieure de Codex, mettez-la impérativement à jour, car la commande `/import` a été introduite dans la version 0.140.0.

### 1.2. Composants de migration automatiques et manuels

**Ce qui peut être transféré sans obstacle :**
- Instructions du repository et préférences personnelles (contenu de `CLAUDE.md`).
- **Serveurs MCP** — la commande et les arguments sont transférés littéralement.
- **Skills** — ils suivent la convention Agent Skills commune aux deux outils.
- Slash-commands et prompts réutilisables.
- Endpoints API personnalisés et clés d'autorisation.

**Ce qui nécessite un contournement ou une reconstruction manuelle :**
- La liste blanche des permissions (`permission allowlist`) de Claude Code — Codex utilise une sandbox à deux niveaux.
- L'événement hook `ConfigChange` (Codex dispose de `PreCompact`/`PostCompact`, mais n'a pas de trigger sur la modification du fichier de configuration).
- **Output styles** — la notion de styles de sortie est absente dans Codex.
- **Modèles Anthropic** — Codex standard ne supporte que les modèles OpenAI ; un gateway-provider est nécessaire pour Claude.

---

## 2. Carte complète : les 12 configurations de Claude Code et leurs équivalents dans Codex

### 2.1. Matrice comparative synthétique des surfaces de configuration

La plupart des paramètres sont transférés sans perte, car les deux outils résolvent les mêmes défis d'ingénierie en utilisant différents formats de sérialisation : Claude Code repose sur JSON (`settings.json`, `.mcp.json`) et Markdown (`CLAUDE.md`, `.claude/agents/*.md`), tandis que Codex utilise un unique fichier TOML (`~/.codex/config.toml`) et `AGENTS.md`.

| N° | Surface Claude Code | Équivalent Codex | Verdict de migration |
| :---: | :--- | :--- | :--- |
| 1 | `CLAUDE.md` (mémoire) | `AGENTS.md` (ou nom de fichier alternatif) | Transférable |
| 2 | `.mcp.json` (JSON) | `[mcp_servers.*]` dans `config.toml` | Transférable, avec reformattage |
| 3 | `.claude/skills/` | Skills Codex (`[[skills.config]]`) | Transférable |
| 4 | `.claude/commands/` | Slash-commands / prompts Codex | Transférable, nécessite restructuration |
| 5 | `.claude/agents/` (Markdown) | Fichiers `.codex/agents/*.toml` | Restructuré |
| 6 | `settings.json` (JSON) | `config.toml` + profils (TOML) | Restructuré |
| 7 | `permissions.allow/ask/deny` | `approval_policy` + `sandbox_mode` | Non transférable directement |
| 8 | Hooks (`PreToolUse`, `Stop`, …) | `[[hooks.*]]` dans `config.toml` | Restructuré |
| 9 | Hook `ConfigChange` | Pas d'équivalent | Pas d'équivalent |
| 10 | Endpoint `ANTHROPIC_BASE_URL` | `[model_providers.*]` | Transférable |
| 11 | `outputStyle` | Pas d'équivalent | Pas d'équivalent |
| 12 | Modèles Anthropic Claude | Uniquement modèles OpenAI par défaut | Cul-de-sac (résolu via gateway) |

### 2.2. Différences architecturales clés : JSON vs TOML

Les lignes 9 et 11 de la matrice sont cosmétiques : `outputStyle` impacte peu la performance, et `ConfigChange` n'est requis que par une niche de développeurs utilisant des configurations de session dynamiques.

Le principal obstacle reste généralement la ligne 12 (modèles Anthropic). Cependant, la connexion d'un gateway via la section `[model_providers]` permet de conserver sans effort les capacités intellectuelles habituelles de Claude au sein de l'environnement Codex.

---

## 3. Quand migrer, quand rester sur Claude Code

### 3.1. Scénarios et critères techniques pour passer à Codex

La migration vers Codex est justifiée si vos workflows sont centrés sur les tâches autonomes et l'isolation du système de fichiers :
- **Automatisation CI/CD :** Besoin de lancer des agents non-interactifs avec des restrictions strictes « read-only » ou « workspace-write ».
- **Standardisation d'équipe :** Nécessité d'avoir un unique fichier `config.toml` commité avec des profils prêts pour différents niveaux de risque, plutôt que des fragments `.claude/settings.local.json`.
- **Nouveaux modèles OpenAI Codex :** Accès requis aux modèles `gpt-5.5` et `gpt-5.4` comme outil principal de génération de code.

### 3.2. Cas où il est judicieux de rester sur Claude Code

Restez sur Claude Code si votre pipeline présente ces caractéristiques :
- **Dépendance à des hooks spécifiques :** Utilisation de triggers `ConfigChange` ou de styles de formatage `outputStyle`.
- **Format dialogique d'interaction :** Tout le travail est structuré comme une longue conversation interactive. La nature conversationnelle de Claude Code est mieux optimisée pour cela que le cycle batch « tâche → vérification » de Codex.
- **Allowlist fine des droits :** Si une liste blanche multi-niveaux avec regex pour chaque appel système est configurée, passer aux politiques de sandbox plus grossières de Codex nécessitera une révision complète du modèle de sécurité.

> 💡 **Règle d'arrêt :** Si votre objectif est de tester la qualité de la génération de code de Codex sur le repository actuel, il n'est pas nécessaire de migrer toute la configuration. Il suffit de lancer la commande `/import` dans le terminal Codex. Une configuration manuelle détaillée n'est requise que pour ceux qui prévoient de faire de Codex leur outil de travail principal.

---

## 4. Prérequis système avant de commencer

### 4.1. Vérification des versions CLI, du projet et des droits d'accès

Avant de modifier la configuration, assurez-vous que quatre conditions obligatoires sont remplies :
1. **Codex CLI version 0.140.0 ou supérieure.** Vérifiez la version avec la commande `codex --version`.
2. **Projet Claude Code sauvegardé :** Le dossier `.claude/` et le fichier `CLAUDE.md` doivent rester intacts jusqu'à la vérification complète de la migration.
3. **Clé API du provider :** Une clé OpenAI active ou une clé de gateway (par ex., ofox.ai) est nécessaire pour travailler avec Claude.
4. **Droits d'écriture dans le home directory :** Codex lit les paramètres globaux depuis `~/.codex/config.toml` à chaque lancement.

### 4.2. Itinéraire de migration : pipeline étape par étape

Le processus général de transition comprend six étapes séquentielles :

```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. Migration étape par étape de la configuration

### 5.1. Étape 1 : Lancer l'importateur automatique (/import)

Lancez Codex dans le dossier racine de votre projet et exécutez la commande interne d'importation :

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

La commande `/import` effectue un transfert sélectif des paramètres, des instructions système et des dernières sessions. À l'issue, un fichier initial `~/.codex/config.toml`, un `AGENTS.md` de projet seront générés, ainsi qu'un rapport sur les paramètres ignorés.

### 5.2. Étape 2 : Instructions — passage de CLAUDE.md à AGENTS.md

Codex recherche automatiquement `AGENTS.md`. Pour maintenir la compatibilité ou continuer à lire l'ancien fichier sans le renommer, ajoutez des chemins de secours à la configuration :

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

Le contenu des instructions ne nécessite aucune édition : les règles de style de code, les commandes de build et les tests sont chargés dans le contexte système de l'agent sans modification.

### 5.3. Étape 3 : Serveurs MCP — conversion de JSON à TOML

Les deux plateformes utilisent le standard Model Context Protocol. Seul le syntaxe de description change : la configuration de `.mcp.json` est transférée dans des tables TOML.

Entrée initiale dans `.mcp.json` :

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

Entrée équivalente dans `~/.codex/config.toml` :

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

Si le serveur exige des variables d'environnement, spécifiez-les inline : `env = { GITHUB_TOKEN = "..." }`. Les processus STDIO locaux ainsi que les serveurs SSE/HTTP distants sont supportés.

### 5.4. Étape 4 : Sous-agents — configuration dans .codex/agents/

Claude Code stocke les agents sous forme de fichiers Markdown dans `.claude/agents/`. Codex utilise le format TOML, où chaque sous-agent est décrit dans un fichier séparé dans le dossier `~/.codex/agents/` ou `.codex/agents/` :

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

Les sous-agents dans Codex sont actifs par défaut et invoqués sur demande explicite de l'utilisateur ou de l'agent principal.

### 5.5. Étape 5 : Modèle de droits d'accès — configuration sandbox et approval

Les concepts de sécurité des outils diffèrent sensiblement : au lieu d'une liste granulaire de règles glob (`permissions.allow`), Codex utilise des paramètres d'isolation du système de fichiers (`sandbox_mode`) et de confirmation des actions (`approval_policy`).

| Scénario Claude Code | Objectif | Paramétrage Codex (`~/.codex/config.toml`) |
| :--- | :--- | :--- |
| `allow: ["Bash(npm run test *)"]` | Exécution automatique de commandes sûres | `sandbox_mode = "workspace-write"`<br>`approval_policy = "on-request"` |
| `ask: ["Bash(python *)"]` | Demande de confirmation avant exécution | `approval_policy = "on-request"` |
| `deny: ["Read(./.env)"]` | Blocage d'accès hors du répertoire | `sandbox_mode = "workspace-write"` |
| `Plan mode` | Mode analyse sans modification | `sandbox_mode = "read-only"` |
| `--dangerously-skip-permissions` | Autonomie totale | `approval_policy = "never"`<br>`sandbox_mode = "danger-full-access"` |

Configuration équilibrée pour le développement quotidien :

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

### 5.6. Étape 6 : Hooks — transfert des événements de cycle de vie

Les hooks dans Codex sont activés par défaut et couvrent les événements système clés : `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` et `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"
```

> ⚠️ **Attention :** L'événement `ConfigChange` n'est pas supporté par Codex. Toute logique réagissant à la modification des fichiers de configuration « à la volée » doit être déplacée dans des scripts pré-session.

---

## 6. Cul-de-sac de la migration : modèles Claude dans Codex et comment les conserver

### 6.1. Architecture gateway model_provider pour les modèles Anthropic

Codex est optimisé pour l'écosystème OpenAI (`gpt-5.5`, `gpt-5.4`) et n'a pas de switch direct vers les modèles Anthropic. Si vous avez besoin de Claude Opus ou Claude Sonnet pour résoudre des tâches architecturales, utilisez une connexion via un API-gateway compatible.

Ajoutez la définition du provider dans `~/.codex/config.toml` :

```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. Configuration wire_api=responses et choix du profil claude

Lors de la configuration du gateway, deux paramètres sont critiques :
1. `wire_api = "responses"` : le support du protocole `chat` obsolète a été supprimé de Codex en février 2026.
2. `requires_openai_auth = false` : désactive la validation du préfixe `sk-` côté client.

Créez un profil pour lancer Claude dans `~/.codex/claude.config.toml` :

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

Le lancement de l'agent avec ce profil se fait via la commande :

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

---

## 7. Erreurs courantes lors de la migration et solutions

### 7.1. Matrice de diagnostic et dépannage

| Symptôme | Cause racine | Solution d'ingénierie |
| :--- | :--- | :--- |
| Codex ignore `CLAUDE.md` | Par défaut, `AGENTS.md` est attendu | Renommez le fichier ou ajoutez `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]` |
| Le provider custom retourne une erreur `401` | Le client attend un token OpenAI avec préfixe `sk-` | Ajoutez la directive `requires_openai_auth = false` dans la section `[model_providers.*]` |
| Erreur de lancement `chat wire API deprecated` | Le protocole `chat` est obsolète et supprimé | Spécifiez le paramètre `wire_api = "responses"` |
| Les sous-agents n'exécutent pas d'actions | Fichier de description absent ou agent non invoqué explicitement | Créez `.codex/agents/NAME.toml` ; Codex active les agents uniquement sur commande directe |
| Les hooks ne se déclenchent pas | Erreur dans le nom de l'événement ou regex incorrect | Vérifiez la syntaxe de l'événement et l'expression `matcher` dans `[[hooks.*]]` |
| Une commande de l'allowlist est bloquée | La sandbox Codex est plus stricte que les règles ponctuelles | Étendez `sandbox_mode` ou définissez `approval_policy = "on-request"` |

### 7.2. Vérification des dossiers de confiance et validation de la configuration

Si le fichier `.codex/config.toml` dans le projet est totalement ignoré, assurez-vous que le repository est ajouté à la liste des dossiers de confiance. Pour des raisons de sécurité, Codex ne charge les configurations locales que pour les chemins vérifiés et bloque les tentatives des fichiers projet de redéfinir l'autorisation globale ou les clés de provider.

---

## 8. Migration pour une équipe

### 8.1. Centralisation config.toml vs .local.json individuels

Dans l'environnement Claude Code, les équipes étaient contraintes de maintenir deux niveaux : un fichier commun `.claude/settings.json` dans le repository et des fichiers locaux de chaque développeur `.claude/settings.local.json`. Codex simplifie cette architecture :

| Aspect d'interaction | Claude Code | OpenAI Codex CLI |
| :--- | :--- | :--- |
| Configuration d'équipe partagée | `.claude/settings.json` (commité) | `.codex/config.toml` (commité dans le repo) |
| Préférences personnelles | `.claude/settings.local.json` | Fichiers de profil personnels dans `~/.codex/` |
| Instructions de base du projet | `CLAUDE.md` | `AGENTS.md` |
| Granularité des niveaux de risque | `permission allowlist` | Flags `--profile strict` ou `--profile fast` |

### 8.2. Gateway API unique et facturation partagée de l'équipe

L'utilisation d'un gateway unique via `model_provider` optimise les coûts d'équipe :
- L'administrateur ajoute les paramètres du gateway dans le fichier `.codex/config.toml` commité.
- Chaque ingénieur obtient une clé personnelle via le gestionnaire de secrets corporate (`OFOX_API_KEY`).
- Toute l'équipe utilise un point de routage unique avec facturation partagée, indépendamment du fait que le développeur travaille avec `openai/gpt-5.5` ou `anthropic/claude-opus-4.8`.

---

## 9. Niveau avancé : profils pour CI, travail local et review

### 9.1. Configuration de profils de sécurité spécialisés

Les profils dans Codex sont stockés comme des fichiers séparés dans le dossier `~/.codex/` et activés via le flag `--profile`. Cela élimine le besoin de modifier les fichiers de configuration globaux.

Exemple de configuration pour un audit automatisé en CI/CD :

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

### 9.2. Scénarios pratiques : audit isolé en CI et développement local

Le lancement de la commande `codex --profile ci` garantit que l'agent pourra examiner le code et générer des rapports, mais n'aura techniquement pas la possibilité d'apporter des modifications non autorisées aux fichiers ou d'envoyer des données à l'extérieur.

Pour le développement quotidien, utilisez un profil local avec `sandbox_mode = "workspace-write"`, et pour l'analyse architecturale complexe — `codex --profile claude`, qui active Claude Opus sans changer les paramètres globaux du système.

---

## 10. Foire Aux Questions (FAQ)

### 10.1. Compatibilité des modèles et des fichiers de configuration

> ❓ **Peut-on utiliser les modèles Claude originaux dans Codex CLI ?**  
> Codex standard fonctionne uniquement avec les modèles OpenAI. Cependant, vous pouvez connecter n'importe quel modèle Anthropic (par exemple, `anthropic/claude-opus-4.8`) en enregistrant un API-gateway compatible OpenAI dans la section `[model_providers]` et en le spécifiant dans un profil.

> ❓ **Codex CLI lit-il le fichier de mémoire CLAUDE.md ?**  
> Par défaut, Codex recherche `AGENTS.md`. Pour maintenir la compatibilité sans dupliquer l'information, ajoutez à `~/.codex/config.toml` la ligne `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]`.

> ❓ **Comment importer rapidement des paramètres prêts depuis Claude Code ?**  
> Lancez `codex` dans le dossier du projet et exécutez la commande `/import`. L'importateur intégré transférera les instructions, les serveurs MCP et les commandes contextuelles, et formulera une liste des points nécessitant une attention manuelle.

> ❓ **Y a-t-il des différences entre les fichiers AGENTS.md et CLAUDE.md ?**  
> Leur fonctionnalité est identique. `AGENTS.md` est un standard inter-outils ouvert pour les agents AI, tandis que `CLAUDE.md` est le format interne de Claude Code. Le contenu des deux fichiers est interprété de manière identique.

### 10.2. Nuances techniques des hooks, MCP et sous-agents

> ❓ **Codex CLI supporte-t-il les cycles de vie des hooks comme Claude Code ?**  
> Oui, les hooks sont activés par défaut. Les événements `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` et `PostCompact` sont supportés. Le seul hook sans équivalent direct est `ConfigChange`.

> ❓ **Claude Code et Codex peuvent-ils utiliser simultanément les mêmes serveurs MCP ?**  
> Oui. La mécanique du protocole MCP est identique. Seule la forme d'enregistrement change : au lieu de la structure JSON dans `.mcp.json`, les paramètres sont déclarés comme des tables TOML dans `config.toml`.

> ❓ **Faut-il réécrire le code des sous-agents lors de la migration ?**  
> Non, les instructions système elles-mêmes sont transférées sans modification. Il faut seulement changer le wrapper : déplacer le texte des fichiers Markdown `.claude/agents/*.md` vers le paramètre `developer_instructions` des fichiers correspondants `.codex/agents/*.toml`.