# Migracja z Claude Code do Codex: przenoszenie pliku CLAUDE.md, MCP, umiejętności, komend slash i konfiguracji

> Kompletny przewodnik po migracji z Claude Code do OpenAI Codex CLI: konwersja pliku CLAUDE.md na AGENTS.md, konfiguracja MCP, ustawienia uprawnień dostępu, hooków oraz zachowanie modeli Claude.

Codex jest dostarczany z jednopoleceniowym importerem, który samodzielnie przenosi większość ustawień Claude Code. Kluczowe wyzwanie tkwi w szczegółach: część konfiguracji trzeba zestawić ręcznie, a jeden element nie jest przenoszony bezpośrednio – i nie chodzi o plik konfiguracyjny, lecz o same modele Anthropic.

Przeniesienie niemal całego zestawu ustawień Claude Code do Codexa zajmuje około 20 minut. Poniżej znajdziesz podstawowe wskazówki dotyczące szybkiego startu.

---

## 1. Co można przenieść, a co nie – szybka ocena

### 1.1. Ekspresowa diagnostyka: tabela kompatybilności warstw konfiguracji

| Pytanie | Rozwiązanie / Odpowiedź |
| :--- | :--- |
| Czy można przenieść większość konfiguracji? | **Tak.** 9 z 12 warstw jest przenoszonych lub przebudowywanych bez poważnych problemów. |
| Najszybsza ścieżka? | `codex` → `/import` (Codex 0.140+), następnie ręczne dopracowanie 3 punktów. |
| Co jest importowane automatycznie? | Pliki pamięci, serwery MCP, skills, komendy slash, niestandardowe endpointy API. |
| Co wymaga ręcznej korekty? | Model uprawnień, format hooków, obudowy subagentów. |
| Jedyne ślepe zaułek? | Modele Anthropic Claude. Vanilla Codex działa wyłącznie z modelami OpenAI. |
| Rozwiązanie dla ślepego zaułka? | Dodaj gateway jako `model_provider` i kontynuuj korzystanie z Claude wewnątrz środowiska Codex. |

> 📌 **Wersje środowiska:** Przewodnik przetestowano na Codex CLI 0.142.5 (1 lipca 2026) oraz Claude Code 2.1.178. Jeśli masz starszą wersję Codexa – koniecznie ją zaktualizuj, ponieważ komenda `/import` pojawiła się dopiero w wersji 0.140.0.

### 1.2. Automatyczne i ręczne komponenty migracji

**Co można przenieść bez przeszkód:**
- Instrukcje repozytorium i ustawienia osobiste (zawartość `CLAUDE.md`).
- **Serwery MCP** – komenda i argumenty są przenoszone dosłownie.
- **Skills** – przestrzegają wspólnej konwencji Agent Skills dla obu narzędzi.
- Komendy slash oraz wielokrotnego użytku prompty.
- Niestandardowe endpointy API i klucze autoryzacyjne.

**Co wymaga obejścia lub ręcznej przebudowy:**
- Lista pozwoleń operacyjnych (`permission allowlist`) Claude Code – w Codexie stosuje się dwupoziomową piaskownicę.
- Hook `ConfigChange` (w Codexie istnieją `PreCompact`/`PostCompact`, ale brak triggera na zmianę pliku konfiguracyjnego).
- **Output styles** – koncepcja stylów wyjściowych nie istnieje w Codexie.
- **Modele Anthropic** – standardowy Codex wspiera tylko modele OpenAI; dla Claude potrzebny jest provider-gateway.

---

## 2. Pełna mapa: wszystkie 12 warstw konfiguracji Claude Code i ich odpowiedniki w Codex

### 2.1. Zbiorcza macierz porównawcza warstw konfiguracji

Większość parametrów jest przenoszona bez strat, ponieważ oba narzędzia rozwiązują te same problemy inżynierskie, używając różnych formatów serializacji: Claude Code opiera się na JSON (`settings.json`, `.mcp.json`) oraz Markdown (`CLAUDE.md`, `.claude/agents/*.md`), podczas gdy Codex wykorzystuje pojedynczy plik TOML (`~/.codex/config.toml`) oraz `AGENTS.md`.

| № | Warstwa Claude Code | Odpowiednik w Codex | Werdykt migracji |
| :---: | :--- | :--- | :--- |
| 1 | `CLAUDE.md` (pamięć) | `AGENTS.md` (lub nazwa zastępcza pliku) | Przenoszone |
| 2 | `.mcp.json` (JSON) | `[mcp_servers.*]` w `config.toml` | Przenoszone, z reformatowaniem |
| 3 | `.claude/skills/` | Skills Codex (`[[skills.config]]`) | Przenoszone |
| 4 | `.claude/commands/` | Komendy slash / prompty Codex | Przenoszone, wymaga przebudowy |
| 5 | `.claude/agents/` (Markdown) | Pliki `.codex/agents/*.toml` | Przebudowywane |
| 6 | `settings.json` (JSON) | `config.toml` + profile (TOML) | Przebudowywane |
| 7 | `permissions.allow/ask/deny` | `approval_policy` + `sandbox_mode` | Nie przenoszone bezpośrednio |
| 8 | Hooks (`PreToolUse`, `Stop`, …) | `[[hooks.*]]` w `config.toml` | Przebudowywane |
| 9 | Hook `ConfigChange` | Brak odpowiednika | Brak odpowiednika |
| 10 | Endpoint `ANTHROPIC_BASE_URL` | `[model_providers.*]` | Przenoszone |
| 11 | `outputStyle` | Brak odpowiednika | Brak odpowiednika |
| 12 | Modele Anthropic Claude | Domyślnie tylko modele OpenAI | Ślepy zaułek (rozwiązywany przez gateway) |

### 2.2. Kluczowe różnice architektoniczne: JSON vs TOML

Wiersze 9 i 11 macierzy mają charakter kosmetyczny: `outputStyle` praktycznie nie wpływa na wydajność, a `ConfigChange` jest potrzebny jedynie wąskiej grupie deweloperów pracujących z dynamicznymi konfiguracjami sesji.

Główną barierą zazwyczaj staje się wiersz 12 (modele Anthropic). Jednak podłączenie gatewaya przez sekcję `[model_providers]` pozwala bezproblemowo zachować znane możliwości intelektualne Claude wewnątrz środowiska Codex.

---

## 3. Kiedy migrować, a kiedy pozostać przy Claude Code

### 3.1. Scenariusze i kryteria techniczne przejścia na Codex

Migracja na Codex jest uzasadniona, jeśli Twoje procesy robocze koncentrują się wokół zadań autonomicznych i izolacji systemu plików:
- **Automatyzacja w CI/CD:** Potrzebujesz uruchamiać agentów w trybie nieinteraktywnym ze sztywnymi ograniczeniami „read-only” lub „workspace-write”.
- **Standaryzacja zespołowa:** Musisz mieć jeden commitowany plik `config.toml` z gotowymi profilami dla różnych poziomów ryzyka, zamiast fragmentowanych `.claude/settings.local.json`.
- **Nowe modele OpenAI Codex:** Potrzebujesz dostępu do modeli `gpt-5.5` i `gpt-5.4` jako głównego narzędzia generowania kodu.

### 3.2. Przypadki, w których warto zostać przy Claude Code

Pozostań przy Claude Code, jeśli Twój pipeline charakteryzuje się następującymi cechami:
- **Zależność od specyficznych hooków:** Wykorzystujesz triggery `ConfigChange` lub style formatowania `outputStyle`.
- **Format dialogowy interakcji:** Cała praca opiera się na długich, interaktywnych rozmowach. Rozmowna natura Claude Code jest lepiej zoptymalizowana dla tego scenariusza niż pakietowy cykl „zadanie → weryfikacja” w Codexie.
- **Precyzyjna lista allowlist uprawnień:** Jeśli skonfigurowałeś wielopoziomową listę pozwoleń z wyrażeniami regularnymi dla każdego wywołania systemowego, przejście na grubsze polityki piaskownicy Codex będzie wymagało przeglądu całego modelu bezpieczeństwa.

> 💡 **Zasada zatrzymania:** Jeśli Twoim celem jest jedynie przetestowanie jakości generowania kodu przez Codex na bieżącym repozytorium, nie musisz przenosić całej konfiguracji. Wystarczy uruchomić komendę `/import` w terminalu Codex. Szczegółowa ręczna konfiguracja jest potrzebna tylko tym, którzy planują uczynić Codex swoim głównym narzędziem pracy.

---

## 4. Wymagania systemowe przed rozpoczęciem

### 4.1. Sprawdzenie wersji CLI, projektu i uprawnień

Przed edycją konfiguracji upewnij się, że spełnione są cztery obowiązkowe warunki:
1. **Codex CLI w wersji 0.140.0 lub nowszej.** Sprawdź wersję za pomocą komendy `codex --version`.
2. **Zachowany projekt Claude Code:** Katalog `.claude/` oraz plik `CLAUDE.md` muszą pozostać nietknięte do czasu pełnej weryfikacji migracji.
3. **Klucz API providera:** Potrzebny aktywny klucz OpenAI lub klucz gatewaya (np. ofox.ai) do pracy z Claude.
4. **Uprawnienia do zapisu w katalogu domowym:** Codex odczytuje globalne parametry z `~/.codex/config.toml` przy każdym uruchomieniu.

### 4.2. Trasa migracji: krok po kroku pipeline przejścia

Ogólny proces przejścia składa się z sześciu kolejnych etapów:

```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. Krok po kroku: przenoszenie konfiguracji

### 5.1. Krok 1: Uruchomienie automatycznego importera (/import)

Uruchom Codex w katalogu głównym swojego projektu i wykonaj wewnętrzną komendę importu:

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

Komenda `/import` wykonuje selektywne przeniesienie ustawień, instrukcji systemowych oraz ostatnich sesji. W wyniku zostanie utworzony początkowy plik `~/.codex/config.toml`, projektowy `AGENTS.md` oraz wygenerowany raport dotyczący pominiętych parametrów.

### 5.2. Krok 2: Instrukcje – przejście z CLAUDE.md na AGENTS.md

Codex automatycznie szuka pliku `AGENTS.md`. Aby zachować kompatybilność lub nadal czytać stary plik bez zmiany nazwy, dodaj ścieżki zastępcze do konfiguracji:

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

Treść instrukcji nie wymaga edycji: zasady stylu kodu, komendy buildu oraz testy są ładowane do kontekstu systemowego agenta bez zmian.

### 5.3. Krok 3: Serwery MCP – konwersja z JSON na TOML

Obie platformy wykorzystują standard Model Context Protocol. Zmienia się jedynie składnia opisu: konfiguracja z `.mcp.json` jest przenoszona do tabel TOML.

Oryginalny wpis w `.mcp.json`:

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

Równoważny wpis w `~/.codex/config.toml`:

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

Jeśli serwer wymaga zmiennych środowiskowych, wskaż je inline: `env = { GITHUB_TOKEN = "..." }`. Wspierane są zarówno lokalne procesy STDIO, jak i zdalne serwery SSE/HTTP.

### 5.4. Krok 4: Subagenci – konfiguracja w .codex/agents/

Claude Code przechowuje agentów w postaci plików Markdown w `.claude/agents/`. Codex wykorzystuje format TOML, gdzie każdy subagent jest opisany w osobnym pliku w katalogu `~/.codex/agents/` lub `.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.
"""
```

Subagenci w Codexie są aktywne domyślnie i wywoływane na wyraźne żądanie użytkownika lub głównego agenta.

### 5.5. Krok 5: Model uprawnień – konfiguracja sandbox i approval

Koncepty bezpieczeństwa narzędzi znacząco się różnią: zamiast granularnej listy reguł glob (`permissions.allow`) Codex wykorzystuje parametry izolacji systemu plików (`sandbox_mode`) oraz potwierdzania akcji (`approval_policy`).

| Scenariusz w Claude Code | Przeznaczenie | Ustawienia w Codex (`~/.codex/config.toml`) |
| :--- | :--- | :--- |
| `allow: ["Bash(npm run test *)"]` | Automatyczne wykonywanie bezpiecznych komend | `sandbox_mode = "workspace-write"`<br>`approval_policy = "on-request"` |
| `ask: ["Bash(python *)"]` | Prośba o potwierdzenie przed wykonaniem | `approval_policy = "on-request"` |
| `deny: ["Read(./.env)"]` | Blokowanie dostępu poza katalogiem | `sandbox_mode = "workspace-write"` |
| `Plan mode` | Tryb analizy bez wprowadzania zmian | `sandbox_mode = "read-only"` |
| `--dangerously-skip-permissions` | Pełna autonomia | `approval_policy = "never"`<br>`sandbox_mode = "danger-full-access"` |

Zbalansowana konfiguracja dla codziennej pracy deweloperskiej:

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

### 5.6. Krok 6: Hooki – przenoszenie zdarzeń cyklu życia

Hooki w Codexie są aktywne domyślnie i pokrywają kluczowe zdarzenia systemowe: `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` oraz `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"
```

> ⚠️ **Uwaga:** Zdarzenie `ConfigChange` nie jest wspierane przez Codex. Logikę reagującą na modyfikację plików konfiguracyjnych „w locie” należy przenieść do skryptów pre-run sesji.

---

## 6. Ślepy zaułek migracji: modele Claude w Codex i jak je zachować

### 6.1. Architektura gatewaya model_provider dla modeli Anthropic

Codex jest zoptymalizowany pod ekosystem OpenAI (`gpt-5.5`, `gpt-5.4`) i nie posiada bezpośredniego przełącznika na modele Anthropic. Jeśli do rozwiązywania zadań architektonicznych potrzebujesz Claude Opus lub Claude Sonnet, stosuje się połączenie przez kompatybilny gateway API.

Dodaj definicję providera w `~/.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. Konfiguracja wire_api=responses i wybór profilu claude

Podczas konfiguracji gatewaya krytyczne jest uwzględnienie dwóch parametrów:
1. `wire_api = "responses"`: wsparcie dla przestarzałego protokołu `chat` zostało usunięte z Codexa w lutym 2026 roku.
2. `requires_openai_auth = false`: wyłącza walidację prefiksu `sk-` po stronie klienta.

Utwórz profil do uruchamiania Claude w `~/.codex/claude.config.toml`:

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

Uruchomienie agenta z tym profilem odbywa się komendą:

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

---

## 7. Częste błędy przy migracji i ich rozwiązania

### 7.1. Macierz diagnostyki i usuwania usterek

| Objaw | Przyczyna źródłowa | Rozwiązanie inżynierskie |
| :--- | :--- | :--- |
| Codex ignoruje `CLAUDE.md` | Domyślnie oczekiwany jest `AGENTS.md` | Zmień nazwę pliku lub dodaj `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]` |
| Niestandardowy provider zwraca błąd `401` | Klient oczekuje tokenu OpenAI z prefiksem `sk-` | Dodaj dyrektywę `requires_openai_auth = false` do sekcji `[model_providers.*]` |
| Błąd uruchomienia `chat wire API deprecated` | Protokół `chat` jest przestarzały i usunięty | Ustaw parametr `wire_api = "responses"` |
| Subagenci nie wykonują akcji | Brak pliku opisu lub agent nie został wywołany jawnie | Utwórz `.codex/agents/NAME.toml`; Codex aktywuje agentów tylko na bezpośrednie polecenie |
| Hooki nie działają | Błąd w nazwie zdarzenia lub niepoprawny wzorzec regex | Sprawdź składnię zdarzenia oraz wyrażenie `matcher` w `[[hooks.*]]` |
| Komenda z allowlist jest blokowana | Piaskownica Codex jest surowsza niż punktowe reguły | Rozszerz `sandbox_mode` lub ustaw `approval_policy = "on-request"` |

### 7.2. Weryfikacja zaufanych katalogów i walidacja konfiguracji

Jeśli plik `.codex/config.toml` w projekcie jest całkowicie ignorowany, upewnij się, że repozytorium zostało dodane do listy zaufanych. Ze względów bezpieczeństwa Codex ładuje lokalne konfiguracje tylko dla zweryfikowanych ścieżek i blokuje próby nadpisania globalnej autoryzacji lub kluczy providera przez pliki projektowe.

---

## 8. Migracja dla zespołu

### 8.1. Centralizacja config.toml vs indywidualne .local.json

W środowisku Claude Code zespoły były zmuszone utrzymywać dwa poziomy: wspólny plik `.claude/settings.json` w repozytorium oraz lokalne pliki każdego dewelopera `.claude/settings.local.json`. Codex upraszcza tę strukturę:

| Aspekt współpracy | Claude Code | OpenAI Codex CLI |
| :--- | :--- | :--- |
| Wspólna konfiguracja zespołowa | `.claude/settings.json` (commitowany) | `.codex/config.toml` (commitowany do repozytorium) |
| Ustawienia osobiste | `.claude/settings.local.json` | Osobiste pliki profili w `~/.codex/` |
| Podstawowe instrukcje projektu | `CLAUDE.md` | `AGENTS.md` |
| Granulacja poziomów ryzyka | `permission allowlist` | Flagi `--profile strict` lub `--profile fast` |

### 8.2. Jedyny gateway API i wspólny billing zespołu

Wykorzystanie jednego gatewaya przez `model_provider` optymalizuje koszty zespołowe:
- Administrator dodaje parametry gatewaya do commitowanego pliku `.codex/config.toml`.
- Każdy inżynier otrzymuje osobisty klucz przez korporacyjny menedżer sekretów (`OFOX_API_KEY`).
- Cały zespół korzysta z jednego punktu routingu ze wspólnym billingiem, niezależnie od tego, czy deweloper pracuje z `openai/gpt-5.5`, czy z `anthropic/claude-opus-4.8`.

---

## 9. Poziom zaawansowany: profile dla CI, pracy lokalnej i code review

### 9.1. Konfiguracja wyspecjalizowanych profili bezpieczeństwa

Profile w Codexie są przechowywane jako osobne pliki w katalogu `~/.codex/` i aktywowane przez flagę `--profile`. Eliminuje to konieczność zmiany globalnych plików konfiguracyjnych.

Przykład konfiguracji dla automatycznego audytu w CI/CD:

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

### 9.2. Praktyczne scenariusze: izolowany audyt w CI i lokalna praca deweloperska

Uruchomienie komendy `codex --profile ci` gwarantuje, że agent będzie mógł przeglądać kod i generować raporty, ale nie będzie miał technicznej możliwości wprowadzania nieautoryzowanych zmian w plikach ani wysyłania danych na zewnątrz.

Do codziennej pracy deweloperskiej stosuje się profil lokalny z `sandbox_mode = "workspace-write"`, a do złożonej analizy architektonicznej – `codex --profile claude`, który aktywuje Claude Opus bez zmiany globalnych ustawień systemu.

---

## 10. Najczęściej zadawane pytania (FAQ)

### 10.1. Kompatybilność modeli i plików konfiguracyjnych

> ❓ **Czy można używać oryginalnych modeli Claude w Codex CLI?**  
> Standardowy Codex działa tylko z modelami OpenAI. Możesz jednak podłączyć dowolny model Anthropic (np. `anthropic/claude-opus-4.8`), rejestrując kompatybilny z OpenAI gateway API w sekcji `[model_providers]` i wskazując go w profilu.

> ❓ **Czy Codex CLI czyta plik pamięci CLAUDE.md?**  
> Domyślnie Codex szuka `AGENTS.md`. Aby zachować kompatybilność bez duplikowania informacji, dodaj do `~/.codex/config.toml` linię `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]`.

> ❓ **Jak szybko zaimportować gotowe ustawienia z Claude Code?**  
> Uruchom `codex` w katalogu projektu i wykonaj komendę `/import`. Wbudowany importer przeniesie instrukcje, serwery MCP oraz komendy kontekstowe, a także sformułuje listę punktów wymagających ręcznej uwagi.

> ❓ **Czy istnieją różnice między plikami AGENTS.md a CLAUDE.md?**  
> Ich funkcjonalność jest identyczna. `AGENTS.md` jest otwartym, międzyplatformowym standardem dla agentów AI, podczas gdy `CLAUDE.md` to wewnętrzny format Claude Code. Treść obu plików jest interpretowana tak samo.

### 10.2. Niuanse techniczne hooków, MCP i subagentów

> ❓ **Czy Codex CLI wspiera cykle życia hooków tak jak Claude Code?**  
> Tak, hooki są włączone domyślnie. Wspierane są zdarzenia `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` oraz `PostCompact`. Jedynym hookiem bez bezpośredniego odpowiednika jest `ConfigChange`.

> ❓ **Czy Claude Code i Codex mogą jednocześnie korzystać z tych samych serwerów MCP?**  
> Tak. Mechanika protokołu MCP jest taka sama. Zmienia się jedynie forma zapisu: zamiast struktury JSON w `.mcp.json` parametry są deklarowane jako tabele TOML w `config.toml`.

> ❓ **Czy podczas migracji trzeba przepisywać kod subagentów?**  
> Nie, same instrukcje systemowe są przenoszone bez zmian. Należy jedynie zmienić obudowę: przenieść tekst z plików Markdown `.claude/agents/*.md` do parametru `developer_instructions` w odpowiednich plikach `.codex/agents/*.toml`.