# Миграция 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. |
| Решение для тупика? | Подключить API-шлюз как `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`, но нет триггера на изменение файла конфигурации).
- **Стили вывода (outputStyle)** — концепция стилей вывода в 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 CLI | Вердикт миграции |
| :---: | :--- | :--- | :--- |
| 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 | Переносится, требует пересборки |
| 5 | `.claude/agents/` (Markdown) | `.codex/agents/*.toml` файлы | Пересобирается в TOML |
| 6 | `settings.json` (JSON) | `config.toml` + профили (TOML) | Пересобирается в TOML |
| 7 | `permissions.allow/ask/deny` | `approval_policy` + `sandbox_mode` | Переосмысливается |
| 8 | Hooks (`PreToolUse`, `Stop`, …) | `[[hooks.*]]` в `config.toml` | Пересобирается в 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 Opus и Sonnet внутри песочницы 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 на текущем репозитории, не нужно переносить всю конфигурацию вручную. Достаточно открыть терминал Codex и выполнить `/import`. Глубокая настройка требуется только при переходе на 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)

Откройте терминал в корне вашего проекта и запустите встроенную команду импорта:

```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. Бинарные файлы серверов остаются прежними; меняется лишь синтаксис декларации с 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 или Sonnet внутри среды Codex, настройте кастомный 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-` на стороне клиента.

Создайте файл профиля в `~/.codex/claude.config.toml`:

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

Запуск Codex с нужной конфигурацией выполняется командой:

```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"` |
| Субагенты не выполняют действий | Отсутствует файл TOML или агент не вызван явно | Создайте `.codex/agents/NAME.toml`; Codex запускает агентов только по прямому вызову |
| Хуки не срабатывают | Ошибка в имени события или некорректный regex | Проверьте синтаксис события и регулярное выражение `matcher` в `[[hooks.*]]` |
| Разрешённые ранее команды блокируются | Песочница 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/` и подключаются через флаг `--profile`. Это избавляет от необходимости перезаписывать глобальные параметры.

Конфигурация для изолированного запуска в CI:

```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?**  
> Запустите `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`.