SavePearlHarbor

Ультимативный гид по Codex CLI: от первой установки до воркфлоу

—

от автора

admin
Codex The Definitive Guide

Codex The Definitive Guide

Перед вами то самое руководство, которое можно прочитать самому или скормить ИИ, а он проведет вас за ручку. Всё: от npm install до CI/CD в продакшене, с готовыми конфигами, мнениями и паттернами.

Это длинный текст. Заварите себе кофе.

Краткая заметка о структуре. Гид разбит на одиннадцать частей:

  • Части 1–3 охватывают основы: что такое Codex, как его установить и как настроить.

  • Части 4–6 посвящены системам инструкций и безопасности: AGENTS.md, режимам одобрения и режиму управления.

  • Части 7 и 8 касаются расширяемости: MCP-серверы и навыки (skills).

  • Части 9–11 описывают продвинутое использование, хуки, модели и сравнение Codex с конкурентами.

Переходите к тому, что вам нужно сейчас. К остальному вернетесь позже.

Часть 1. Что такое Codex CLI на самом деле (и чем он не является)

Codex CLI — это терминальный кодинг-агент от OpenAI. Вы вводите инструкцию на естественном языке, а он читает вашу кодовую базу, пишет код, выполняет консольные команды и итерирует до тех пор, пока задача не будет выполнена. Он живет в вашем терминале. Никаких плагинов для IDE, вкладок браузера или оболочек на Electron.

Это была краткая презентация. А вот контекст:

Переход с TypeScript на Rust. Когда Codex CLI запустился в апреле 2025 года, это был проект на TypeScript. Процесс Node.js, который вызывал команды в терминале и передавал результаты через OpenAI API. Это работало. Но на больших репозиториях он тормозил, ел память как подросток пиццу и иногда зависал, когда параллельные операции с файлами сталкивались в цикле событий (event loop).

К середине 2025 года OpenAI начала полностью переписывать проект на Rust. Это не был частичный порт или попытка «переписать горячие участки». Это был полный перенос с нуля.

К середине 2025 года OpenAI начала полностью переписывать проект на Rust. Это не был частичный порт или попытка «переписать горячие участки». Это был полный перенос с нуля.

Начиная с версии v0.133.0 (выпущена в мае 2026 года), Codex CLI официально перешел в статус General Availability (GA). Кодовая база на 95,7% состоит из Rust. Теперь всё основное действие происходит в директории codex-rs. Старая директория codex-cli на TypeScript всё еще существует для npm-обертки и TypeScript SDK, но ядро, песочница, TUI, парсер конфигов — всё это Rust.

Что это дает вам? Во-первых, скорость: бинарный файл на Rust запускается за миллисекунды, а не секунды. Память: он потребляет лишь малую часть того, что требовала версия на Node.js. И песочница: система типов и гарантии безопасности памяти в Rust делают код песочницы (критически важный для безопасности) гораздо надежнее. Если вы пробовали Codex в середине 2025-го и он показался вам медленным на больших репозиториях, попробуйте снова. Теперь это совсем другой инструмент.

📈 Цифры на май 2026 (GA): 86 тысяч звезд на GitHub, около 13 тысяч форков, более 450 контрибьюторов, 4500+ коммитов в ветке main. Лицензия Apache 2.0. Эти показатели делают его одним из самых активно развиваемых Open Source инструментов для разработчиков в мире. Для сравнения: у VS Code около 180 тысяч звезд. Codex CLI в свой первый год растет быстрее, чем VS Code в свой первый год.

Codex Model Evolution: Benchmark Scores Over Time

Codex Model Evolution: Benchmark Scores Over Time

🛑 Чем он не является. Codex CLI — это не движок автодополнения. Он не сидит внутри вашего редактора, предлагая следующую строку, пока вы печатаете. Это территория GitHub Copilot. Codex ориентирован на задачи: вы даете ему работу, он ее выполняет, вы проверяете результат. Думайте о нем как о коллеге, который живет в вашем терминале, а не как о помощнике по набору текста.

Это также больше не одиночный продукт. OpenAI развернула целую экосистему: CLI (о котором мы говорим здесь), Codex App (десктопный GUI), расширение для IDE, Codex Cloud (удаленное выполнение в песочнице) и GitHub Action для CI/CD.

Этот гид сфокусирован на CLI, потому что именно там обитают продвинутые пользователи 💪🏼.

Майндсет пользователя: Для работы с агентами нужны три главных навыка: адаптивность, слабоумие и отвага. Агент иногда делает очень умные вещи, а иногда — очень странные. Будьте готовы направлять его, вовремя откатывать Git и не ждать безупречности с первого промпта.

Новинка (macOS, май 2026): Appshots. Десктопное приложение Codex теперь умеет захватывать активное окно (скриншот + текст) прямо в тред через хоткей ⌘⌘. CLI подхватывает такие треды, но создать Appshot из терминала нельзя — только через macOS-приложение.

Экосистема Codex

Экосистема Codex

Часть 2. Установка и первый запуск

Выберите удобный способ установки. Их несколько.

npm (рекомендуется для большинства):

npm install -g @openai/codex@latest

npm-пакет — это тонкая обертка, которая при первом запуске скачивает бинарный файл Rust под вашу платформу. Работает на macOS (Intel и Apple Silicon), Linux (x86_64 и ARM64) и Windows. Да, Windows теперь поддерживается полноценно, хотя песочница там всё еще в экспериментальном режиме. (Актуальная версия на май 2026: v0.134.0+. Проверить: codex --version.)

Homebrew (macOS):

brew install codex

Тот же бинарный файл, другой способ доставки. Homebrew берет на себя обновления через brew upgrade, что некоторые предпочитают вместо npm update -g. (Примечание: начиная с v0.133, рекомендуется использовать codex update для обновления внутренних компонентов).

Прямая загрузка бинарного файла:
Возьмите свежий релиз на github.com/openai/codex/releases. Полезно, если вы работаете в среде без npm и Homebrew или собираете Docker-образ и хотите избежать накладных расходов npm.

Аутентификация: два пути.
Вам нужно сообщить Codex, кто вы. Есть два варианта, и выбор важнее, чем кажется:

  • Аккаунт ChatGPT (доступно на бесплатном тарифе ограниченное время): запустите codex и пройдите через OAuth-авторизацию в браузере. Самый быстрый способ начать, дает доступ к GPT-5.3-Codex через подписку ChatGPT. Бесплатный тариф работает, но вы быстрее столкнетесь с лимитами.

  • API-ключ: установите переменную окружения OPENAI_API_KEY. Это то, что нужно для CI/CD, автоматизированных рабочих процессов или использования сторонних провайдеров моделей. Аутентификация по ключу дает более точный контроль над расходами и использованием.

export OPENAI_API_KEY="sk-..."

Ваша первая интерактивная сессия:

cd ~/projects/my-appcodex

И всё. Вы внутри. Загрузится TUI (терминальный интерфейс), и вы увидите поле ввода для ваших инструкций. Попробуйте что-то простое:
> Добавь эндпоинт проверки здоровья (health check) в это Laravel-приложение, который возвращает { status: "ok" }

Codex прочитает файлы проекта, поймет структуру, предложит изменения в виде diff и попросит вашего одобрения перед их применением. Этот этап одобрения очень важен. Мы разберем его в Части 5.

Несколько вещей, на которые стоит обратить внимание при первом запуске. Codex показывает план перед выполнением. Он сообщает, какие файлы читает. Он показывает diff перед записью. И он спрашивает разрешение перед выполнением консольных команд. Всё это настраивается, и всё это сделано потому, что выполнение произвольного кода на вашей машине должно быть осознанным процессом.

Полезные слэш-команды, которые стоит знать с первого дня:

  • /help — показать все доступные команды.

  • /review — запустить ревью последних изменений.

  • /skills — список доступных навыков (если включены).

  • /debug-config — показать активную конфигурацию и источники значений.

  • /compact — запустить сжатие контекста вручную. Начиная с v0.98.0, компакция также запускается автоматически при достижении auto_compact_limit.

  • /clear — очистить экран TUI, если он перегружен логами.

  • /statusline — настроить отображение информации в нижней строке (токены, модель, время).

  • Ctrl + G — открыть текущий промпт во внешнем редакторе (VS Code, Vim, Nano).

Настройка многострочного ввода (Multiline TUI).
По умолчанию Enter отправляет сообщение. Если вы хотите писать длинные блоки (аналог Heredoc прямо в TUI), добавьте это в ~/.codex/config.toml:

[tui]multiline_enter = true   # Enter делает перенос строки, а не отправку# Отправка теперь по Cmd + Enter (macOS) или Ctrl + Enter (Win/Linux)

Связка с внешним редактором:
Если промпт становится слишком сложным, нажмите Ctrl + G. Codex откроет ваш $EDITOR (или то, что указано в file_opener), позволит комфортно отредактировать текст и вернет его в TUI после сохранения и закрытия файла. Это лучший способ «скармливать» агенту куски документации или сложные структуры.

Про-совет по Heredoc (для скриптов): Для автоматизации используйте стандартный синтаксис оболочки через codex exec:

codex exec <<EOF Проведи рефакторинг этого метода: $(cat src/Main.js) EOF

Codex CLI нативно поддерживает стандартные потоки ввода (stdin), что позволяет «скармливать» ему огромные контексты без ограничений интерактивного интерфейса.

Вам не нужно их заучивать. Но знание того, что существует /debug-config, сэкономит вам час разочарований, когда конфиг поведет себя не так, как ожидалось. Поверьте мне.

Самообновление и управление фичами (v0.134.0+):

# Обновить CLI до последней версииcodex update# Управление экспериментальными функциямиcodex features list              # все флаги + статус (Experimental/Beta/Stable)codex features enable goals      # включить конкретную фичуcodex features disable memories  # выключить фичу

Раньше для обновления нужно было npm install -g @openai/codex@latest или brew upgrade. Теперь codex update делает это нативно.

Установка

Установка

Часть 3. Стек конфигурации

Большинство людей путаются здесь, и, честно говоря, я тоже путался поначалу. У Codex многослойная система конфигурации с шестью уровнями приоритета. Как только вы ее поймете, всё встанет на свои места. Пока не поймете — будете гадать, почему ваши правки в конфиге не работают.

Где живут настройки:

  • System: /etc/codex/config.toml (управляется админом, обычно в корпоративной среде).

  • User: ~/.codex/config.toml (ваши личные настройки по умолчанию; то, что вы будете править чаще всего).

  • Project: .codex/config.toml (фиксируется в репозитории; общие правила для команды).

  • Флаги CLI: переопределяют всё для конкретного вызова.

Порядок приоритета (от высшего к низшему): флаги CLI, затем переопределения профилей, затем конфиг проекта, пользовательский конфиг, системный конфиг и, наконец, встроенные значения по умолчанию.

Вот мой рабочий ~/.codex/config.toml, который я использую ежедневно и оттачивал на десятках проектов:

# ~/.codex/config.tomlmodel = "gpt-5.5"approval_policy = "on-request"sandbox_mode = "workspace-write"model_reasoning_effort = "high"model_personality = "concise"web_search = truefile_opener = "code"  # Открывает файлы в VS Codereview_model = "gpt-5.5"[features]skills = trueshell_snapshot = trueunified_exec = truerequest_rule = trueundo = truegoals = true       # автономный /goal режим (Experimental, v0.134.0+)memories = true    # память между сессиями (Experimental)[shell_environment_policy]policy = "exclude"exclude = ["AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"]

Разберем основные опции, так как в документации эта информация разбросана по разным страницам.

model устанавливает модель по умолчанию. gpt-5.5 — флагман с апреля 2026. gpt-5.3-codex по-прежнему доступен для API-воркфлоу. Подробнее о моделях в Части 10.

approval_policy контролирует, когда Codex спрашивает разрешение. Четыре варианта:

  • untrusted: спрашивает перед КАЖДЫМ действием. Чтение файлов, команды, запись. Раздражает, но максимально безопасно. Хорошо для первого знакомства с кодовой базой, которой вы еще не доверяете.

  • on-failure: Codex работает свободно, пока что-то не пойдет не так, тогда он спрашивает, что делать. Разумный компромисс для знакомых проектов.

  • on-request: запрашивает одобрение только тогда, когда сам Codex считает операцию рискованной. Мой выбор по умолчанию: убирает трение в рутине, но ловит опасные моменты.

  • never: отключает все запросы. Используйте только с жесткой песочницей, иначе пожалеете.

sandbox_mode контролирует доступ к файловой системе:

  • read-only: Codex может читать файлы, но не может писать или выполнять команды. Полезно для ревью.

  • workspace-write: позволяет писать внутри директории проекта и запускать команды, но не дает трогать файлы за пределами. Доступ к сети по умолчанию отключен. Золотая середина для работы.

  • danger-full-access: снимает все ограничения. Название говорит само за себе. Это опасно.

model_reasoning_effort определяет «глубину мысли» модели: low, medium, high. Для сложного рефакторинга или архитектурных решений ставьте high. Для простых правок low сэкономит токены и время. Я держу на high, потому что лучше подождать лишнюю секунду, чем получить поверхностный ответ.

model_personality формирует тон ответов. Мне нравится concise (кратко), так как мне не нужно объяснение того, как работает цикл for. Если вы учитесь или хотите подробных пояснений, оставьте по умолчанию.

review_model позволяет выбрать отдельную модель для задач ревью кода. Удобно, если хотите использовать более дешевую модель для проверки, оставляя дорогую для генерации.

Система приоритетов означает, что вы можете задать безопасные глобальные настройки, а затем переопределять их для конкретных проектов. Ваш личный конфиг — это страховка, а проектный конфиг — договоренность команды.

Политика переменных окружения (Shell environment policy). Тонкий, но мощный момент. По умолчанию Codex наследует всё ваше окружение. Все секреты, которые у вас прописаны, он видит. Вы можете это ограничить:

[shell_environment_policy]# Варианты: "inherit" (по умолчанию), "include_only", "exclude"policy = "exclude"exclude = ["AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "GITHUB_TOKEN", "NPM_TOKEN"]

Не игнорируйте это. Вы вряд ли хотите, чтобы ваш кодинг-агент случайно вывел AWS-ключи в лог отладки или, что еще хуже, включил их в коммит-сообщение, которое улетит в публичный репо. Я усвоил это на горьком опыте. Настройте исключения заранее.

Память между сессиями (Memories, v0.134.0+). Включите в [features]:

[features]memories = true

После включения Codex в фоне суммирует прошлые сессии и записывает их в ~/.codex/memories/. При старте новой сессии эти записи подгружаются как контекст.

Важно понимать разницу между двумя механизмами персистентности:

  • AGENTS.md — статичные правила, которые вы пишете вручную: стиль кода, архитектурные соглашения, команды для тестирования.

  • Memories — динамический слой, который Codex генерирует автоматически: что он узнал о вашем проекте, какие паттерны заметил.

Используйте их вместе. AGENTS.md — это устав, Memories — это живой конспект.

Система памяти Codex

Система памяти Codex

Ограничение: Memories недоступны в регионах EEA, UK и Швейцария (требования GDPR).

Часть 4. AGENTS.md и каскадная система правил

AGENTS.md — это сердце системы инструкций Codex. Это файл в формате Markdown, в котором вы описываете правила игры для вашего проекта. В отличие от системных промптов, которые вы «зашиваете» в API, AGENTS.md живет в вашем репозитории. Он фиксируется в Git. Ваша команда может его редактировать.

Почему это круто? Codex автоматически ищет AGENTS.md в текущей директории и всех родительских директориях. Это означает, что вы можете иметь:

  • ~/projects/AGENTS.md — правила для всех ваших проектов (например: «Всегда используй табуляцию, а не пробелы»).

  • ~/projects/my-app/AGENTS.md — правила для конкретного приложения (например: «Используй архитектуру портов и адаптеров»).

  • ~/projects/my-app/src/components/AGENTS.md — правила только для фронтенд-компонентов (например: «Только функциональные компоненты React с хуками»).

Codex объединяет эти правила перед началом работы. Если правила конфликтуют, побеждает то, которое находится ближе к редактируемому файлу.

Бойлерплейт для вашего AGENTS.md:
Чтобы не начинать с пустого листа, используйте эту структуру (проверено на десятках проектов):

# VisionКраткое описание проекта. Что мы строим? (Напр: "Быстрый API на Go для обработки платежей").# MandatesЖесткие запреты и обязательные правила.- Никогда не используй глобальные переменные.- Всегда используй интерфейсы для внешних зависимостей.# WorkflowКак мы работаем.- Сначала пиши тесты, потом реализацию (TDD).- Коммиты только в формате Conventional Commits.# DocumentationТребования к комментариям и документации.- Все публичные методы должны иметь JSDoc/Godoc.- Обновляй README.md при изменении API.

Я уже подробно разбирал это в руководстве по AGENTS.md.

Часть 5. Режимы одобрения и песочница

Безопасность — это то, где многие AI-агенты терпят неудачу. Они либо слишком ограничены (не могут запускать код), либо слишком опасны (могут случайно снести базу). Codex решает это через связку approval_policy и sandbox_mode.

Примеры комбинаций:

  • Разработка в потоке (мой выбор): approval_policy = "on-request" + sandbox_mode = "workspace-write". Достаточно безопасно, чтобы доверять, достаточно быстро, чтобы не выпадать из потока.

  • Только ревью кода: approval_policy = "untrusted" + sandbox_mode = "read-only". Codex может анализировать, но не может ничего менять.

  • Автоматизация CI/CD: approval_policy = "never" + sandbox_mode = "workspace-write". Человек не участвует, но песочница предотвращает «побег» за пределы проекта.

Permission Profiles (v0.134.0+). Начиная с версии 0.128.0, --full-auto заменён на более гибкую систему профилей. Профиль — это именованная комбинация sandbox_mode + approval_policy:

# Встроенные профили (с префиксом :)codex --profile :minimal      # только чтение, максимальная безопасностьcodex --profile :workspace    # workspace-write (бывший --full-auto)# Свой профиль в ~/.codex/config.toml[permissions.ci-runner]sandbox_mode = "workspace-write"approval_policy = "never"
codex --profile ci-runner     # использовать свой профиль

Зачем это лучше --full-auto? Вместо одного «всё разрешено», вы явно описываете что именно разрешено. Несколько профилей — для разных контекстов (локальная разработка, CI, ревью).

Умные одобрения (request_rule). Эта функция делает флаг --yolo ненужным для большинства. Включенная по умолчанию с v0.97.0, она позволяет Codex запоминать ваши решения в рамках сессии. Если вы один раз разрешили запись в src/, он не спросит снова для похожих операций. Также в v0.97.0 добавили «Allow and remember» для одобрений инструментов MCP, что сильно улучшает качество жизни.

# Разумный выбор на каждый деньcodex --ask-for-approval on-request --sandbox workspace-write# Готовый профиль доступа (актуальный способ, v0.134.0+)codex --profile :workspace# ⚠️ Устаревший вариант (--full-auto deprecated с v0.134.0):# codex --full-auto# Ядерный вариант (только для контейнеров и CI, пожалуйста)codex --yolo# но я работаю в нем по-умолчанию

Часть 6. Режим управления (Steer mode)

Черт возьми, эта штука изменила мой стиль работы.

Режим управления долго был экспериментальным, скрытым за флагом, который почти никто не включал. В v0.98.0 он стабилизировался и теперь включен по умолчанию. Идея проста, но последствия огромны: вы можете говорить с Codex прямо во время его работы.

Насыщенная неделя Codex CLI: Steer Mode, /fork и 7 релизов за 3 дня

До появления этого режима взаимодействие было строго пошаговым. Дали задачу, ждете (иногда минуты для сложных дел), проверяете результат, даете следующую порцию. Если вы видели, что агент свернул не туда на полпути (например, начал плодить отдельные файлы для каждой функции, а вы хотели сгруппировать их), у вас было два пути: ждать конца и отменять всё, либо прерывать и начинать заново. Оба варианта — трата времени.

Теперь у вас есть две клавиши, которые меняют всё:

  • Enter отправляет сообщение немедленно. Codex читает его «на лету» и корректирует подход, не теряя контекст. Сделанная работа остается.

  • Tab ставит инструкцию в очередь на следующий шаг. Полезно, когда хотите набросать следующую задачу, не прерывая текущую. Это как оставить записку самому себе в будущем.

Как и в случае с коллегой, вы можете направлять и взаимодействовать с GPT-5.3-Codex в процессе работы, не теряя контекста.

Как и в случае с коллегой, вы можете направлять и взаимодействовать с GPT-5.3-Codex в процессе работы, не теряя контекста.

Практический пример: Вы просите Codex отрефакторить большой модуль авторизации в вашем Laravel-приложении. Он начинает создавать файлы, тесты, обновлять провайдеры. В середине вы замечаете, что он хранит API-токены в сессии (что плохо масштабируется). С включенным Steer Mode вы жмете Enter и пишете: «Используй Laravel Sanctum с токенами в базе вместо сессий». Codex считывает это, меняет подход для остальных файлов и продолжает. То, что было написано правильно, остается нетронутым. То, что он собирался писать, будет исправлено.

Другой пример: вы просите настроить эндпоинт. Пока он работает, вы вспоминаете про лимиты. Жмете Enter: «Добавь еще ограничение частоты запросов, 100 в минуту на IP». Codex вплетет это в текущую задачу без перезапуска.

Steer mode делает Codex больше похожим на парное программирование с очень быстрым напарником. Я писал о первом релизе в статье «Codex CLI’s Busy Week», но стабильная версия в v0.98.0 работает заметно плавнее.

Когда жать Enter, а когда Tab? Моя ментальная модель: используйте Enter, когда нужно изменить то, что Codex делает ПРЯМО СЕЙЧАС. Корректировка срочная и важная. Используйте Tab, когда текущая работа идет нормально, но вы уже знаете, что попросите следующим шагом. Enter — это как похлопать коллегу по плечу в разгар фразы. Tab — это дописать пункт в общий список дел.

⚠️ Нюанс: Steer mode работает лучше всего, когда правки конкретны и понятны. Туманные фразы вроде «сделай лучше» или «это не совсем то» могут запутать модель. Точные указания вроде «используй Collection вместо массива для кэша» работают отлично. Чем точнее ваше руление, тем меньше контекста тратит Codex на догадки.

Часть 7. Интеграция MCP (Model Context Protocol)

MCP позволяет Codex общаться с внешними инструментами и сервисами через стандартизованный интерфейс. Если вы читали мой гид «Codex MCP Configuration: Using Env Vars the Right Way», вы знаете основы. Вот полная картина, включая паттерны, которые я нашел после написания той статьи.

Два типа транспорта:

  • STDIO серверы запускаются как локальные процессы. Codex создает их и общается через stdin/stdout. Подойдет для большинства локальных штук: доступ к файлам, БД, Git, Jira.

  • Streamable HTTP серверы работают удаленно через HTTP. Полезно для общих командных сервисов или облачных инструментов, которым нужно сохранять состояние между сессиями.

Добавление сервера MCP (через CLI):

codex mcp add filesystem -- npx -y @anthropic/mcp-filesystem /path/to/allowed/dir

Это автоматически запишет настройки в конфиг. Быстро и удобно для разовых добавлений.

Добавление через конфиг:

Никогда не зашивайте секреты в код и не используйте интерполяцию переменных. Передавайте их документированным способом.

# ~/.codex/config.toml[mcp_servers.cloudflare-docs]command = "npx"args = ["mcp-remote", "https://docs.mcp.cloudflare.com/mcp"]enabled = true[mcp_servers.microsoft-docs]command = "npx"args = ["-y", "mcp-remote", "https://learn.microsoft.com/api/mcp"]enabled = false[mcp_servers.firecrawl]startup_timeout_sec = 30command = "npx"args = ["-y", "firecrawl-mcp"]env_vars = ["FIRECRAWL_API_KEY"]enabled = true[mcp_servers.github]command = "docker"args = [  "run","-i","--rm",  "-e","GITHUB_TOKEN",  "-e","GITHUB_TOOLSETS",  "ghcr.io/github/github-mcp-server",  "stdio"]env_vars = ["GITHUB_TOKEN", "GITHUB_TOOLSETS"][mcp_servers.shadcn]command = "npx"args = ["shadcn@latest", "mcp"][mcp_servers.zai-mcp]startup_timeout_sec = 30type = "stdio"command = "npx"args = ["-y", "@z_ai/mcp-server"]env_vars = ["Z_AI_API_KEY"][mcp_servers.zai-mcp.env]Z_AI_MODE = "ZAI" # Альтернативный способ задания переменных окружения.

Фильтрация инструментов. Некоторые серверы вываливают десятки инструментов. Сервер GitHub может предложить 30+ операций, но вам нужно только создавать PR и читать тикеты. Используйте белые и черные списки:

[mcp_servers.github]# ...enabled_tools = ["get_file_contents", "issue_read"]# Или запретите конкретные опасные штуки:# disabled_tools = ["create_pull_request"]

Аутентификация OAuth. Для серверов, требующих OAuth:

codex mcp login my-server-name

Это откроет браузер, проведет авторизацию и надежно сохранит токен в системной связке ключей.

Codex как MCP-сервер. Трюк, который многие упускают: сам Codex может работать как сервер MCP. Это позволяет другим агентам использовать Codex как субагента в сложных процессах:

Вызывайте Codex как MCP-сервер для построения многоагентных воркфлоу

developers.openai.com

codex app-server

Честно говоря, это самое интересное для команд, строящих системы оркестрации. Можно иметь агента-планировщика, который декомпозирует задачу и делегирует подзадачи разным инстансам Codex через MCP. Каждый инстанс работает в своей песочнице, а оркестратор собирает результат.

Список проверенных серверов можно найти в GitHub MCP Registry.

Быстрый и безопасный способ разработки с AI: GitHub MCP Registry централизует поиск серверов…

github.com

Часть 8. Навыки (Skills): учим Codex новым трюкам

Я написал две статьи о навыках («Codex Skills Are Just Markdown, and That’s the Point» и «Codex Skills That Behave Like Reliable CLI Tools»), поэтому здесь кратко о главном и почему это круче, чем кажется.

Навыки Codex — это просто Markdown, и в этом вся фишка (пример с Jira)

Избавьтесь от раздутого AGENTS.md и ускорьтесь…

Что это такое. Навыки — это файлы Markdown, которые дают Codex специализированные знания для конкретных задач. Они основаны на открытом стандарте agentskills.io. Это значит, что навыки, написанные для Codex, также будут работать в Claude Code и других инструментах, поддерживающих стандарт.

Зачем они нужны. Ваш AGENTS.md всегда загружен. Каждый токен в нем «отъедает» место в контекстном окне на каждом ходу, вне зависимости от того, нужны эти инструкции сейчас или нет. Если в AGENTS.md прописаны правила миграции Laravel, они тратят ресурсы, даже когда вы правите Blade-компонент. Навыки решают это через прогрессивное раскрытие: Codex загружает только имя и описание при старте (всего пара токенов). Полный текст инструкций подгружается только при активации навыка — либо вами явно, либо автоматически.

Навыки используют прогрессивное раскрытие: Codex видит только название и описание при старте; полные инструкции загружаются только в момент активации.

Навыки используют прогрессивное раскрытие: Codex видит только название и описание при старте; полные инструкции загружаются только в момент активации.

Формат SKILL.md:

---name: laravel-migrationsdescription: Безопасная работа с миграциями БД в Laravel, включая откаты, изменение колонок и миграцию данных.---## Когда использовать этот навыкПри работе с моделями Eloquent, миграциями или изменениями схемы БД.## Инструкции1. Всегда запускай `php artisan migrate:status` перед созданием новых миграций.2. Проверяй сгенерированный файл на корректность перед запуском.3. Никогда не меняй миграцию, которая уже была запущена. Создавай новую.4. Для изменения колонок используй пакет `doctrine/dbal` и `$table->type()->change()`.5. Всегда проверяй миграции через `php artisan migrate --pretend` перед применением.## Частые ошибки- Не редактируй миграции, уже примененные в продакшене.- Следи за ограничениями внешних ключей при удалении/переименовании колонок.- Используй `rollback --step=1` для отката последней пачки, а не `migrate:reset`.

YAML-заголовок — единственная обязательная часть. name — для явного вызова, description — для автоматического подбора.

Где хранить навыки (порядок поиска):

  • Repo: .agents/skills/ в вашем проекте (специфичные для проекта).

  • User: $HOME/.agents/skills/ (ваша личная библиотека).

  • Admin: /etc/codex/skills/ (на всю компанию). С v0.76.0+ поддерживаются admin-scoped skills — их нельзя переопределить на уровне проекта.

  • System: в комплекте с Codex (встроенные).

Также появились always-on skills — навыки, которые загружаются всегда без явной активации. Полезно для команды, где нужно гарантированно применять определённые практики (например, security checklist).

Активация. Навыки включаются двумя способами:

  • Явно: введите /skills для просмотра или используйте префикс $ (например, $laravel-migrations исправь миграцию).

  • Неявно: Codex сам подберет навык по описанию, если увидит подходящую задачу в вашем промпте.

Встроенные навыки. Есть два мета-навыка: $skill-creator поможет создать навык интерактивно, а $skill-installer установит их из папок или репозиториев.

Не забудьте включить их в конфиге:

[features]skills = true

Навыки всё еще под флагом. Скоро это изменится, но пока добавьте эту строку.

Начиная с v0.97.0, Codex видит обновления навыков в реальном времени. Правите SKILL.md — и Codex тут же подхватывает изменения без перезапуска сессии. Мелочь, но итерации ускоряет в разы.

Начиная с v0.97.0, Codex видит обновления навыков в реальном времени. Правите SKILL.md — и Codex тут же подхватывает изменения без перезапуска сессии. Мелочь, но итерации ускоряет в разы.

Часть 9. Продвинутые паттерны, которые не афишируют

Вот паттерны, которые я использую каждый день и которых нет в README. Выстрадано пробами и ошибками, чтением исходников и тредов в комьюнити.

Неинтерактивный режим для CI/CD:

codex exec "Запусти тесты и исправь все упавшие"

Команда exec запускает Codex без TUI. Он выполняет задачу и выходит со статус-кодом. Идеально для пайплайнов, крон-задач и любой автоматизации. Совмещайте с --full-auto для полной автономности:

codex exec --profile :workspace "Обнови все устаревшие API-вызовы на эндпоинты v3"  # ⚠️ --full-auto deprecated

GitHub Action:

# .github/workflows/codex-review.ymlname: Codex code reviewon: [pull_request]jobs:  review:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4        with:          fetch-depth: 0      - uses: openai/codex-action@main        with:          task: "Проведи ревью этого PR на предмет багов, проблем безопасности и стиля. Фокусируйся только на измененных файлах."        env:          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Это запускает Codex как автоматического ревьюера на каждый PR. fetch-depth: 0 нужен, чтобы Codex видел всю историю Git для контекста.

Возобновление сессии: Codex сохраняет состояние. Если сессия закрылась случайно, сел ноутбук или вы хотите продолжить задачу утром:

# Возобновить последнюю сессиюcodex resume --last# Возобновить конкретную сессию по IDcodex resume <session-id>

Сохраняется весь контекст: прочитанные файлы, принятые решения. Это как продолжить разговор ровно там, где остановились.

Ревью кода через /review: Внутри интерактивной сессии введите /review. Codex проанализирует изменения и найдет то, что пропускают линтеры. Я делаю это перед каждым PR.

Мульти-директории: Работаете в монорепозитории, где фронт и бэк в разных папках? (Фантастически полезно при создании v2 версии или копировании фич из другого репо).

codex --cd apps/frontend --add-dir ../backend --add-dir ../shared

Флаг --cd задает рабочую область (где можно писать), --add-dir дает права на чтение дополнительных папок.

Визуальный ввод: Codex умеет читать изображения.

codex -i screenshot.png "Эта ошибка вылезла в браузере. Исправь её."codex -i design-mockup.png "Реализуй этот дизайн на Tailwind и Blade-компонентах."

Я постоянно использую это для отладки CSS. Закинуть скриншот кривой верстки быстрее, чем описывать проблему словами.

Облачное выполнение: Для долгих задач, чтобы не занимать терминал:

codex cloud exec "Отрефактори модуль авторизации на токены Sanctum"

Задача запустится в облачной песочнице OpenAI, вы получите уведомление по завершении. Никакого риска для вашей машины.

Отладка конфига: Команда /debug-config покажет, какие файлы конфигурации загружены и какие значения сейчас активны.

Режим планирования (Plan mode): Включен по умолчанию с v0.94.0. Codex показывает структурированный план: что прочтет, что изменит, что запустит. Вы можете одобрить, дополнить или отклонить план. Это решает проблему «я попросил поправить опечатку, а Codex переписал полпроекта».

Функция отмены (Undo): Если включить undo = true в [features], Codex будет трекать изменения. Сделал что-то не то? Пишем /undo. Он откатывает последнюю пачку правок. Это работает на уровне операций, а не отдельных файлов.

Автономный режим /goal (v0.134.0, 30 апреля 2026). Это не просто фича — это сдвиг модели работы. Вместо «один промпт — один ответ» Codex получает долгосрочную цель и работает до её достижения (или до бюджетного лимита).

Включить:

codex features enable goals# или в ~/.codex/config.toml:[features]goals = true

Подкоманды:

/goal <objective>  — поставить цель (с конкретным definition of done)/goal              — статус: время, токены, состояние (pursuing/paused/achieved)/goal pause        — пауза (текущий ход доделывает)/goal resume       — продолжить/goal clear        — снять цель

Как это работает под капотом: State Machine с Persistence слоем. На каждый шаг Codex инжектирует goals/continuation.md — системный промпт с установкой «не принимай косвенные сигналы успеха». Если тесты позеленели, но метрика не достигнута — это не success. Только вы управляете жизненным циклом цели; модель не может сама пометить её как выполненную.

Когда использовать:

  • Оптимизация с измеримой метрикой (/goal Reduce P95 latency below 150ms)

  • Написание тестов для модуля (/goal Make all tests in /src/api pass)

  • Рефакторинг с конкретными constraints

Когда НЕ использовать:

  • Размытые цели («сделай код лучше») — агент уйдет в бесконечный цикл

  • Прод-окружение без жесткого permission profile

  • Задачи без автоматической обратной связи (тестов, метрик)

Про-паттерн: Связка Roadmap + Goal.

Автономный режим Goals

Автономный режим Goals

Вместо того чтобы скармливать агенту гигантский промпт, сделайте так:

  1. Создайте в корне файл ROADMAP.md с задачами (чек-боксами [ ]).

  2. Запустите цель: /goal Реализуй задачи из ROADMAP.md по одной. После каждой успешной задачи отмечай её галочкой [x] в файле и делай git commit.

  3. Идите пить кофе. Это самый надежный способ «one-shot» реализации небольших проектов.

Главная грабля — непредсказуемость токенов. Одна и та же задача может стоить 80k токенов, а может — 400k. Разброс ×3–5 без видимой причины. Совет: не оставляйте /goal без присмотра. Проверяйте статус раз в 15–20 минут.

Дополнительная команда /side открывает эфемерный боковой тред, не сбивая текущую цель: /side Есть ли очевидный риск в этом плане?. Escape — вернуться к основному.

Хуки (Hooks): Превращаем Codex в Enterprise-инструмент

Это то, что превращает Codex из «умного чата» в надежный инструмент. Хуки позволяют выполнять скрипты в критических точках жизненного цикла агента. Если вы планируете выпускать Codex в «дикую природу» (CI/CD или автономные задачи), хуки — ваша первая и последняя линия обороны.

1. Устройство и Философия

Хук — это не просто скрипт. В Codex CLI это трехслойная структура:
Событие (напр. PreToolUse) → Matcher (regex для выбора инструмента) → Handler (ваш скрипт).

Пример базовой структуры в .codex/hooks.json (или в основном конфиге):

{  "hooks": {    "PreToolUse": [      {        "matcher": "^Bash$",        "hooks": [          {            "type": "command",            "command": "bash $(git rev-parse --show-toplevel)/.codex/hooks/block-destructive.sh",            "statusMessage": "Checking command safety"          }        ]      }    ]  }}

Когда событие срабатывает, Codex передает вашему скрипту на stdin жирный JSON-объект. Там всё: session_id, cwd, model, и — самое важное — tool_input (параметры команды, которую агент хочет запустить).

А вот и пример того самого «боевого» скрипта block-destructive.sh, который спасает ваши нервы и репозиторий:

#!/usr/bin/env bash# Читаем JSON от CodexINPUT="$(cat)"# Выдергиваем команду через jqCMD="$(echo "$INPUT" | jq -r '.tool_input.command // ""')"# Список запрещенкиif echo "$CMD" | grep -E 'rm -rf /|git push --force|git reset --hard|DROP TABLE'; then  echo "Blocked dangerous command: $CMD" >&2  # Магический код 2 заставляет Codex отступить  exit 2fiexit 0

Важный момент по философии: Хуки — это local workflow guardrails, а не абсолютная песочница безопасности. Они защищают вас от глупостей и случайных rm -rf, но для настоящей изоляции используйте sandbox_mode.

2. Жизненный цикл (Где вешать капканы?)

  • SessionStart & UserPromptSubmit (Впрыск контекста):Паттерн «Hindsight»: при старте сессии хук прогревает ваш memory-backend, а при каждом промпте — инжектит релевантный контекст прямо в запрос. Здесь же можно блокировать промпты, содержащие секреты или ключи API.

  • PreToolUse (Главный вышибала):Самый мощный инструмент. Перехватывает Bash, apply_patch и MCP calls. Вы можете проанализировать команду и сказать «Deny», если агент решил почистить базу в 4 утра.

  • PostToolUse (Аудит и Сжатие):Здесь мы ловим результат выполнения. Мой любимый лайфхак: если линтер выдал 500 строк ошибок, хук может обрезать их до топ-10, чтобы не забивать context window мусором.

  • Stop (Финальный Quality Gate):Перед тем как агент скажет «Я всё», срабатывает этот хук. Прогоните тесты. Если они красные — заставьте агента продолжать работу. Это превращает /goal в по-настоящему автономную машину.

3. Где подсмотреть идеи (Repositories to steal from)

Не изобретайте велосипед. Вот три репозитория, из которых стоит «заимствовать» лучшие практики (но помните: аудируйте чужой код перед запуском!):

  1. oway/claw-hooks: Мастер-класс по парсингу команд. Ребята не просто ищут строку «rm», а используют AST-анализ, чтобы находить опасные действия, спрятанные за sudo, eval или сложным экранировании. Плюс отличная реализация транкации вывода.

  2. disler/claude-code-hooks-mastery: Хотя в названии Claude Code, паттерны жизненного цикла там идеальные. Отсюда стоит забрать идею логирования всех событий в jsonl файлы для последующего разбора «полетов».

  3. mksglu/context-mode: Если ваш контекст постоянно «пухнет», смотрите сюда. Фокус на защите context window и продвинутом сессионном трекинге.

4. Ограничения и Гравитация

  • Асинхронность: Пока async: true в конфигах парсится, но фактически игнорируется. Все хуки — блокирующие.

  • Exit Code 2: Это «Магический код». Если ваш скрипт упал с exit 2 — Codex блокирует действие. Если с любым другим non-zero кодом — Codex может посчитать это ошибкой самого хука и проигнорировать решение. Безопаснее возвращать структурированный JSON с permissionDecision: "deny".

  • Subagents: Сейчас контекст сабагентов в хуках передается грязновато. Трудно отличить, вызвал ли команду основной агент или его «помощник».

5. Мой «Стартовый набор»

Я обычно начинаю проект с такого набора в .codex/hooks/:

  • pre_tool_use_policy.py — блокировка деструктивного Bash.

  • user_prompt_guard.py — защита от утечки .env и PII.

  • stop_quality_gate.py — обязательный прогон тестов перед финишем.

Про-совет: В hooks.json всегда используйте полные пути через $(git rev-parse --show-toplevel). Codex — штука хитрая, если запустить его из папки src/components, относительные пути к хукам в корне проекта отвалятся.

Часть 10. Линейка моделей

Ситуация с моделями меняется стремительно. Если вы всё еще ищете codex-mini-latest или o4-mini, забудьте — это имена из эры TypeScript. Они, скорее всего, уже не работают.

Вот актуальный расклад (с учетом апдейтов на май 2026 года):

GPT-5.5 (Новый флагман). Текущий стандарт и самая мощная агентная модель в мире. Она заменила GPT-5.3-Codex в сложных архитектурных задачах и имеет встроенную поддержку «Computer Use». Если вы делаете масштабный рефакторинг — берите её.

GPT-5.4-Mini (Скорость и экономия). Пришла на смену 5.1-Mini. Заметно поумнела, стоит копейки, идеальна для простых правок, рутины и в качестве субагента при оркестрации.

GPT-5.3-Codex-Spark (Для работы «на лету»). Экспериментальная модель, созданная специально для почти мгновенных ответов в интерактивных сессиях.

И вот что взрывало мозг еще в феврале (и до сих пор впечатляет): GPT-5.3-Codex — первая модель, которая активно помогала создавать саму себя. OpenAI использовала ранние версии Codex для разработки, тестирования и отладки 5.3 во время обучения. Я писал об этой «странной петле» в статье «Inside GPT-5.3 Codex: The Model That Helped Create Itself». Дуглас Хофштадтер был бы горд.

Внутри GPT-5.3-Codex: модель, которая помогла создать себя

Самообучающаяся модель OpenAI, подколы Anthropic на Super Bowl…
pub.towardsai.net

GPT-5.3-Codex — первая модель, которая стала инструментом для создания самой себя.

Эволюция моделей:

  • Апрель 2025: codex-mini-latest (модель запуска, ныне не актуальна)

  • Сентябрь 2025: GPT-5-Codex (первый крупный апгрейд)

  • Декабрь 2025: GPT-5.2-Codex (всё еще доступна для API-воркфлоу)

  • Февраль 2026: GPT-5.3-Codex (бывший дефолт, SOTA-бенчмарки своего времени)

  • Май 2026: Семейство GPT-5.5, GPT-5.4-Mini и Spark.

Сторонние провайдеры. Здесь проявляется открытость Codex. Вы не привязаны только к OpenAI. Можно настроить альтернативы:

[model_providers.anthropic]name = "Anthropic"base_url = "https://api.anthropic.com/v1"env_key = "ANTHROPIC_API_KEY"[model_providers.openrouter]name = "OpenRouter"base_url = "https://openrouter.ai/api/v1"env_key = "OPENROUTER_API_KEY"[model_providers.ollama]name = "Ollama (local)"base_url = "http://localhost:11434/v1"

Поддерживаются OpenRouter, Anthropic, Azure OpenAI, Google Gemini, Ollama, Mistral, DeepSeek, Groq и xAI. Для локальных моделей флаг --oss оптимизирует промпты для моделей без поддержки формата function-calling от OpenAI:

# Локальная модель через Ollamacodex --model ollama/deepseek-coder-v2 --oss# Claude через OpenRoutercodex --model openrouter/anthropic/claude-sonnet

(Но на практике — зачем? Я предпочитаю OpenAI. Хотя каждому своё.)

Вопрос цены. GPT-5.3-Codex — самая дорогая. Плотный рабочий день может обойтись в $5–15 через API. Мой подход: GPT-5.5 для сложного (архитектура, дебаг), а GPT-5.4-Mini — для рутины (переименования, бойлерплейт). Модели можно переключать прямо в сессии флагом --model или через настройки проекта.

Флаг --oss. Когда вы используете локальные модели через Ollama, они часто не поддерживают формат функций OpenAI. Флаг --oss говорит Codex использовать другую стратегию промптинга. Она не идеальна, локальные модели слабее в агентских задачах, чем 5.3-Codex, но для простых правок они работают отлично, и данные не покидают вашу машину.

Часть 11. Codex CLI против конкурентов

Я использую Codex CLI ежедневно. Также я использую Claude Code. Я много работал в Cursor, Aider и GitHub Copilot. Вот мое честное, не спонсируемое мнение.

Codex CLI vs Claude Code.
Все спрашивают об этом. Ответ сложнее, чем кажется. Оба терминальные агенты. Оба великолепны.

  • Codex — Open Source (Apache 2.0). Claude Code — проприетарный. Это важно, если вам нужен аудит того, что запускается на машине, или работа в закрытом контуре.

  • Codex поддерживает множество провайдеров «из коробки». Claude Code привязан к Anthropic. Если хотите сегодня 5.3-Codex, а завтра Claude Sonnet — Codex ваш выбор.

  • У Codex есть система навыков (Skills). У Claude Code есть аналогичная концепция, но реализация Codex следует открытому стандарту agentskills.io, что делает навыки переносимыми.

  • С другой стороны, Claude Code лучше рассуждает благодаря контекстному окну Claude в 200 тысяч токенов. На гигантских кодовых базах у Claude есть преимущество. Также система хуков (PreToolUse и др.) там сейчас более зрелая.

Мой совет: используйте оба. Я беру Codex за гибкость и навыки, а Claude Code — для глубоких задач, требующих огромного контекста.

Codex CLI vs Cursor.
Разные философии. Cursor — это IDE-first; он «вшивает» AI в процесс редактирования. Codex — это terminal-first; он работает рядом с любым редактором (Vim, Emacs, Helix, Zed). Если вы живете в VS Code — Cursor крут. Если вы живете в терминале — Codex идеален.

Codex CLI vs Aider.
Оба CLI-агенты. Aider существует дольше и имеет крутую интеграцию с Git через модель «архитектор-редактор». Codex — это большая экосистема (облако, десктоп, GitHub Action), навыки и поддержка OpenAI. Aider лаконичнее и сфокусирован на цикле правки файлов. Codex масштабнее и амбициознее.

Codex CLI vs GitHub Copilot.
Разные задачи. Copilot — это автодополнение строк (на уровне нажатий клавиш). Codex — это агент (на уровне выполнения задач). Они дополняют друг друга. Я использую Copilot для мелочей (дописать сигнатуру функции), а Codex — для крупных дел (реализовать фичу, отрефакторить модуль).

Куда Codex движется дальше?

Темп разработки дикий. Семь релизов за три дня — это реальность. Перенос на Rust дал скорость, Steer mode — сотрудничество, навыки — расширяемость, MCP — совместимость. GPT-5.3-Codex принес сырую мощь, которую бенчмарки еще не видели.

OpenAI отгрузила восемь потрясающих вещей за 72 часа

Десктопное приложение Codex, интеграция с Apple Xcode, навыки, автоматизации…
pub.towardsai.net

Что дальше? Ясности мало, но траектория очевидна. Лучшая поддержка Windows. Глубокая интеграция MCP с новыми встроенными серверами. Больше встроенных навыков. Улучшенная оркестрация через режим MCP-сервера. И если петля самосовершенствования моделей сохранится, GPT-5.4-Codex будет чем-то запредельным.

OpenAI Codex Ecosystem

OpenAI Codex Ecosystem

Самое важное: Codex CLI — это по-настоящему открытый проект. Вы можете использовать его полностью офлайн через локальную Ollama, и данные не покинут вашу сеть. Вы можете форкнуть его, изменить поведение песочницы и законтрибьютить обратно. В мире закрытых «черных ящиков», которые шпионят за вашим кодом, эта открытость имеет значение.

Я начал писать о Codex, потому что не мог найти нужного руководства. Спустя десять статей, кажется, это именно тот гид, который я пытался написать с самого начала. Собрал всё воедино, чтобы можно было просто дать ссылку, а не говорить: «ну, прочти статьи 3, 5 и 7 в таком-то порядке».

Идите и создайте что-нибудь. И когда найдете рабочий паттерн — напишите об этом. Экосистема живет, когда мы делимся знаниями.

И напоследок. Если вы пришли из моих старых статей и термины изменились — так и есть. Старых названий режимов одобрения (suggest, auto-edit) больше нет. Старых имен моделей (codex-mini-latest, o4-mini) больше нет. Кодовая база на TypeScript — история. Этот гид обновлён до версии v0.134.0 (май 2026). Если заметите, что что-то устарело — пишите в комментариях, я поправлю.

Я пишу о Codex CLI, Claude Code и инструментах, которые меняют работу разработчика. Если гид сэкономил вам время — подписывайтесь.

ссылка на оригинал статьи https://habr.com/ru/articles/1040296/