# Міграція Claude Code → Codex: як перенести CLAUDE.md, MCP, skills, slash-команди та налаштування

> Повний посібник із міграції з Claude Code на OpenAI Codex CLI: перенесення CLAUDE.md в AGENTS.md, конфігурація MCP, налаштування прав доступу, хуків та збереження моделей Claude.

Codex постачається з однокомандним імпортером, який самостійно переносить більшу частину налаштувань Claude Code. Основне завдання полягає в деталях: частину конфігурації доводиться збирати вручну, а один пункт взагалі не переноситься прямо — і це не файл конфігурації, а самі моделі Anthropic.

Перенести майже весь набір налаштувань Claude Code в Codex можна приблизно за 20 хвилин. Нижче наведено базові орієнтири для швидкого старту.

---

## 1. Що переноситься, а що ні — швидкий вердикт

### 1.1. Експрес-діагностика: таблиця сумісності поверхонь

| Питання | Рішення / Відповідь |
| :--- | :--- |
| Чи можна перенести більшу частину конфігурації? | **Так.** 9 із 12 поверхонь переносяться або перебудовуються без серйозних проблем. |
| Найшвидший шлях? | `codex` → `/import` (Codex 0.140+), потім вручну доопрацювати 3 пункти. |
| Що переноситься автоматично? | Файли пам’яті, MCP-сервери, skills, slash-команди, кастомні ендпоінти. |
| Що потребує ручного доопрацювання? | Модель прав доступу, формат хуків, обгортки субагентів. |
| Єдиний глухий кут? | Моделі Anthropic Claude. Ванільний Codex працює лише з моделями OpenAI. |
| Рішення для глухого кута? | Додати гейтвей як `model_provider` і продовжувати використовувати Claude всередині Codex. |

> 📌 **Версії оточення:** Гайд протестовано на Codex CLI 0.142.5 (1 липня 2026 року) та Claude Code 2.1.178. Якщо у вас старіша версія Codex — обов'язково оновіться, оскільки команда `/import` з'явилася у версії 0.140.0.

### 1.2. Автоматичні та ручні компоненти міграції

**Що можна перенести безперешкодно:**
- Інструкції для репозиторію та особисті налаштування (вміст `CLAUDE.md`).
- **MCP-сервери** — команда та аргументи переносяться дослівно.
- **Skills** — вони дотримуються загальної для обох інструментів конвенції Agent Skills.
- Slash-команди та багаторазові промпти.
- Кастомні API-ендпоінти та ключі авторизації.

**Що потребує обхідного шляху або ручної перебудови:**
- Поопераційний список дозволів (`permission allowlist`) Claude Code — у Codex використовується дворівнева пісочниця.
- Подія хука `ConfigChange` (у Codex є `PreCompact`/`PostCompact`, але немає тригера на зміну файлу конфігурації).
- **Output styles** — концепція стилів виводу в Codex відсутня.
- **Моделі Anthropic** — стандартний Codex підтримує лише моделі OpenAI, для Claude необхідний шлюз-провайдер.

---

## 2. Повна карта: всі 12 конфігурацій Claude Code та їхні аналоги в Codex

### 2.1. Зведена порівняльна матриця конфігураційних поверхонь

Більшість параметрів переноситься без втрат, оскільки обидва інструменти розв'язують однакові інженерні задачі, використовуючи різні формати серіалізації: Claude Code спирається на JSON (`settings.json`, `.mcp.json`) та Markdown (`CLAUDE.md`, `.claude/agents/*.md`), а Codex — на єдиний TOML-файл (`~/.codex/config.toml`) та `AGENTS.md`.

| № | Поверхня Claude Code | Аналог у Codex | Вердикт міграції |
| :---: | :--- | :--- | :--- |
| 1 | `CLAUDE.md` (пам’ять) | `AGENTS.md` (або резервне ім’я файлу) | Переноситься |
| 2 | `.mcp.json` (JSON) | `[mcp_servers.*]` у `config.toml` | Переноситься, з переформатуванням |
| 3 | `.claude/skills/` | Codex skills (`[[skills.config]]`) | Переноситься |
| 4 | `.claude/commands/` | Slash-команди / prompts Codex | Переноситься, потребує перебудови |
| 5 | `.claude/agents/` (Markdown) | `.codex/agents/*.toml` файли | Перебудовується |
| 6 | `settings.json` (JSON) | `config.toml` + профілі (TOML) | Перебудовується |
| 7 | `permissions.allow/ask/deny` | `approval_policy` + `sandbox_mode` | Не переноситься напряму |
| 8 | Hooks (`PreToolUse`, `Stop`, …) | `[[hooks.*]]` у `config.toml` | Перебудовується |
| 9 | Хук `ConfigChange` | Немає аналога | Аналога немає |
| 10 | Ендпоінт `ANTHROPIC_BASE_URL` | `[model_providers.*]` | Переноситься |
| 11 | `outputStyle` | Немає аналога | Аналога немає |
| 12 | Моделі Anthropic Claude | Лише моделі OpenAI за замовчуванням | Глухий кут (вирішується через шлюз) |

### 2.2. Ключові архітектурні відмінності: JSON проти TOML

Рядки 9 та 11 матриці мають косметичний характер: `outputStyle` практично не впливає на продуктивність, а `ConfigChange` потрібен лише вузькому колу розробників із динамічними сесійними конфігураціями. 

Головним бар'єром зазвичай стає рядок 12 (моделі Anthropic). Проте підключення шлюзу через секцію `[model_providers]` дозволяє безперешкодно зберегти звичні інтелектуальні можливості Claude всередині середовища Codex.

---

## 3. Коли мігрувати, а коли залишатися на Claude Code

### 3.1. Сценарії та технічні критерії для переходу на Codex

Міграція на Codex є виправданою, якщо ваші робочі процеси зосереджені навколо автономних задач та ізоляції файлової системи:
- **Автоматизація в CI/CD:** Потрібно запускати агентів неінтерактивно з жорсткими обмеженнями «read-only» або «workspace-write».
- **Командна стандартизація:** Необхідно мати єдиний закомічений файл `config.toml` із готовими профілями під різні рівні ризику замість фрагментованих `.claude/settings.local.json`.
- **Нові моделі OpenAI Codex:** Потрібен доступ до моделей `gpt-5.5` та `gpt-5.4` як основного інструмента генерації коду.

### 3.2. Випадки, коли доцільно залишитися на Claude Code

Залишайтеся на Claude Code, якщо ваш пайплайн має такі характеристики:
- **Залежність від специфічних хуків:** Використовуються тригери `ConfigChange` або стилі форматування `outputStyle`.
- **Діалоговий формат взаємодії:** Вся робота будується як довга інтерактивна бесіда. Розмовна природа Claude Code оптимізована для цього краще, ніж пакетний цикл «завдання → верифікація» Codex.
- **Тонкий allowlist прав:** Якщо налаштовано багаторівневий список дозволів із регулярними виразами на кожен системний виклик, перехід на грубші політики пісочниці Codex вимагатиме перегляду всієї моделі безпеки.

> 💡 **Правило зупинки:** Якщо ваша мета — протестувати якість кодогенерації Codex на поточному репозиторії, не обов'язково переносити конфігурацію повністю. Достатньо запустити команду `/import` у терміналі Codex. Докладне ручне налаштування потрібне лише тим, хто планує зробити Codex основним робочим інструментом.

---

## 4. Системні вимоги перед початком

### 4.1. Перевірка версій CLI, проєкту та прав доступу

Перед редагуванням конфігурації переконайтеся у виконанні чотирьох обов'язкових умов:
1. **Codex CLI версії 0.140.0 або новішої.** Перевірте версію за допомогою команди `codex --version`.
2. **Збережений проєкт Claude Code:** Каталог `.claude/` та файл `CLAUDE.md` мають залишатися недоторканими до повної верифікації міграції.
3. **API-ключ провайдера:** Потрібен активний ключ OpenAI або ключ шлюзу (наприклад, ofox.ai) для роботи з Claude.
4. **Права на запис у домашній каталог:** Codex зчитує глобальні параметри з `~/.codex/config.toml` при кожному запуску.

### 4.2. Маршрут міграції: покроковий конвеєр переходу

Загальний процес переходу складається з шести послідовних етапів:

```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. Покрокове перенесення конфігурації

### 5.1. Крок 1: Запуск автоматичного імпортера (/import)

Запустіть Codex у кореневій папці вашого проєкту та виконайте внутрішню команду імпорту:

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

Команда `/import` виконує селективне перенесення налаштувань, системних інструкцій та останніх сесій. У результаті буде сформовано початковий файл `~/.codex/config.toml`, проєктний `AGENTS.md` та згенеровано звіт про пропущені параметри.

### 5.2. Крок 2: Інструкції — перехід з CLAUDE.md на AGENTS.md

Codex автоматично шукає `AGENTS.md`. Щоб зберегти сумісність або продовжувати читати старий файл без перейменування, додайте резервні шляхи до конфігурації:

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

Зміст інструкцій не потребує редагування: правила кодстайлу, команди збірки та тести завантажуються в системний контекст агента без змін.

### 5.3. Крок 3: MCP-сервери — конвертація з JSON у TOML

Обидві платформи використовують стандарт Model Context Protocol. Змінюється лише синтаксис опису: конфігурація з `.mcp.json` переноситься в таблиці TOML.

Початковий запис у `.mcp.json`:

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

Еквівалентний запис у `~/.codex/config.toml`:

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

Якщо сервер вимагає змінних оточення, вкажіть їх inline: `env = { GITHUB_TOKEN = "..." }`. Підтримуються як локальні процеси STDIO, так і віддалені SSE/HTTP-сервери.

### 5.4. Крок 4: Субагенти — конфігурація в .codex/agents/

Claude Code зберігає агентів у вигляді Markdown-файлів у `.claude/agents/`. Codex використовує формат TOML, де кожен субагент описується окремим файлом у каталозі `~/.codex/agents/` або `.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.
"""
```

Субагенти в Codex активні за замовчуванням та викликаються за явним запитом користувача або головного агента.

### 5.5. Крок 5: Модель прав доступу — налаштування sandbox та approval

Концепції безпеки інструментів суттєво відрізняються: замість гранулярного списку правил glob (`permissions.allow`) Codex використовує параметри ізоляції файлової системи (`sandbox_mode`) та підтвердження дій (`approval_policy`).

| Сценарій у Claude Code | Призначення | Налаштування в Codex (`~/.codex/config.toml`) |
| :--- | :--- | :--- |
| `allow: ["Bash(npm run test *)"]` | Автоматичне виконання безпечних команд | `sandbox_mode = "workspace-write"`<br>`approval_policy = "on-request"` |
| `ask: ["Bash(python *)"]` | Запит підтвердження перед виконанням | `approval_policy = "on-request"` |
| `deny: ["Read(./.env)"]` | Блокування доступу за межі каталогу | `sandbox_mode = "workspace-write"` |
| `Plan mode` | Режим аналізу без внесення змін | `sandbox_mode = "read-only"` |
| `--dangerously-skip-permissions` | Повна автономність | `approval_policy = "never"`<br>`sandbox_mode = "danger-full-access"` |

Збалансований конфіг для повсякденної розробки:

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

### 5.6. Крок 6: Хуки — перенесення подій життєвого циклу

Хуки в Codex активовані за замовчуванням та покривають ключові системні події: `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` і `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"
```

> ⚠️ **Зверніть увагу:** Подія `ConfigChange` не підтримується Codex. Будь-яку логіку, що реагувала на модифікацію файлів конфігурації «на льоту», слід перенести у скрипти перед запуском сесії.

---

## 6. Тупик міграції: моделі Claude в Codex і як їх зберегти

### 6.1. Архітектура шлюзу model_provider для моделей Anthropic

Codex оптимізований для екосистеми OpenAI (`gpt-5.5`, `gpt-5.4`) і не має прямого перемикача на моделі Anthropic. Якщо для вирішення архітектурних завдань вам потрібен Claude Opus або Claude Sonnet, використовується підключення через сумісний API-шлюз.

Додайте визначення провайдера в `~/.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. Налаштування wire_api=responses та вибір профілю claude

Під час налаштування шлюзу критично врахувати два параметри:
1. `wire_api = "responses"`: підтримку застарілого протоколу `chat` було видалено з Codex у лютому 2026 року.
2. `requires_openai_auth = false`: вимикає валідацію префікса `sk-` на стороні клієнта.

Створіть профіль для запуску Claude в `~/.codex/claude.config.toml`:

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

Запуск агента з цим профілем здійснюється командою:

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

---

## 7. Часті помилки при міграції та їхні рішення

### 7.1. Матриця діагностики та усунення несправностей

| Симптом | Першопричина | Інженерне рішення |
| :--- | :--- | :--- |
| Codex ігнорує `CLAUDE.md` | За замовчуванням очікується `AGENTS.md` | Перейменуйте файл або додайте `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]` |
| Кастомний провайдер повертає помилку `401` | Клієнт очікує токен OpenAI з префіксом `sk-` | Додайте директиву `requires_openai_auth = false` у секцію `[model_providers.*]` |
| Помилка запуску `chat wire API deprecated` | Протокол `chat` застарів і видалений | Вкажіть параметр `wire_api = "responses"` |
| Субагенти не виконують дії | Відсутній файл опису або агент не викликаний явно | Створіть `.codex/agents/NAME.toml`; Codex активує агентів лише за прямою командою |
| Хуки не спрацьовують | Помилка в назві події або некоректний regex-шаблон | Перевірте синтаксис події та вираз `matcher` у `[[hooks.*]]` |
| Команда з allowlist блокується | Пісочниця Codex суворіша за точкові правила | Розширте `sandbox_mode` або встановіть `approval_policy = "on-request"` |

### 7.2. Перевірка довірених директорій та валідація конфігурації

Якщо файл `.codex/config.toml` у проєкті повністю ігнорується, переконайтеся, що репозиторій додано до списку довірених. Codex з міркувань безпеки завантажує локальні конфігурації лише для перевірених шляхів і блокує спроби проєктних файлів перевизначити глобальну авторизацію чи ключі провайдерів.

---

## 8. Міграція для команди

### 8.1. Централізація config.toml проти індивідуальних .local.json

У середовищі Claude Code команди змушені були підтримувати два рівні: спільний файл `.claude/settings.json` у репозиторії та локальні файли кожного розробника `.claude/settings.local.json`. Codex спрощує цю схему:

| Аспект взаємодії | Claude Code | OpenAI Codex CLI |
| :--- | :--- | :--- |
| Спільна командна конфігурація | `.claude/settings.json` (комітиться) | `.codex/config.toml` (комітиться у репозиторій) |
| Персональні налаштування | `.claude/settings.local.json` | Особисті файли профілів у `~/.codex/` |
| Базові інструкції проєкту | `CLAUDE.md` | `AGENTS.md` |
| Грануляція рівнів ризику | `permission allowlist` | Прапорці `--profile strict` або `--profile fast` |

### 8.2. Єдиний шлюз API та спільний білінг команди

Використання єдиного шлюзу через `model_provider` оптимізує командні витрати:
- Адміністратор додає параметри шлюзу в закомічений файл `.codex/config.toml`.
- Кожен інженер отримує персональний ключ через корпоративний менеджер секретів (`OFOX_API_KEY`).
- Вся команда використовує єдину точку маршрутизації зі спільним білінгом, незалежно від того, чи працює розробник із `openai/gpt-5.5`, чи з `anthropic/claude-opus-4.8`.

---

## 9. Просунутий рівень: профілі для CI, локальної роботи та ревью

### 9.1. Налаштування спеціалізованих профілів безпеки

Профілі в Codex зберігаються як окремі файли в каталозі `~/.codex/` та активуються через прапорець `--profile`. Це усуває потребу змінювати глобальні файли конфігурації.

Приклад конфігурації для автоматичного аудиту в CI/CD:

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

### 9.2. Практичні сценарії: ізольований аудит у CI та локальна розробка

Запуск команди `codex --profile ci` гарантує, що агент зможе переглядати код та формувати звіти, але не матиме технічної змоги внести несанкціоновані зміни у файли чи відправити дані назовні.

Для щоденної розробки використовується локальний профіль із `sandbox_mode = "workspace-write"`, а для складного архітектурного аналізу — `codex --profile claude`, що активує Claude Opus без зміни глобальних налаштувань системи.

---

## 10. Відповіді на часті запитання (FAQ)

### 10.1. Сумісність моделей та конфігураційних файлів

> ❓ **Чи можна використовувати оригінальні моделі Claude в Codex CLI?**  
> Стандартний Codex працює лише з моделями OpenAI. Проте ви можете підключити будь-яку модель Anthropic (наприклад, `anthropic/claude-opus-4.8`), зареєструвавши OpenAI-сумісний API-шлюз у секції `[model_providers]` та вказавши його у профілі.

> ❓ **Чи читає Codex CLI файл пам’яті CLAUDE.md?**  
> За замовчуванням Codex шукає `AGENTS.md`. Щоб зберегти сумісність без дублювання інформації, додайте до `~/.codex/config.toml` рядок `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]`.

> ❓ **Як швидко імпортувати готові налаштування з Claude Code?**  
> Запустіть `codex` у каталозі проєкту та виконайте команду `/import`. Вбудований імпортер перенесе інструкції, MCP-сервери та контекстні команди, а також сформує перелік пунктів, що потребують ручної уваги.

> ❓ **Чи є відмінності між файлами AGENTS.md та CLAUDE.md?**  
> Їхня функціональність ідентична. `AGENTS.md` є відкритим міжінструментальним стандартом для AI-агентів, тоді як `CLAUDE.md` — внутрішнім форматом Claude Code. Вміст обох файлів інтерпретується однаково.

### 10.2. Технічні нюанси хуків, MCP та субагентів

> ❓ **Чи підтримує Codex CLI життєві цикли хуків, як у Claude Code?**  
> Так, хуки увімкнені за замовчуванням. Підтримуються події `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact` і `PostCompact`. Єдиний хук без прямого аналога — `ConfigChange`.

> ❓ **Чи можуть Claude Code і Codex одночасно використовувати ті самі MCP-сервери?**  
> Так. Механіка протоколу MCP однакова. Змінюється лише форма запису: замість JSON-структури у `.mcp.json` параметри оголошуються як таблиці TOML у `config.toml`.

> ❓ **Чи потрібно переписувати код субагентів під час міграції?**  
> Ні, самі системні інструкції переносяться без змін. Потрібно лише змінити обгортку: перенести текст із Markdown-файлів `.claude/agents/*.md` у параметр `developer_instructions` відповідних файлів `.codex/agents/*.toml`.