Папка .codex/ — полный разбор

Детальный гид по конфигурации Codex: различия между .codex/, AGENTS.md и .agents/, уровни доверия, правила, хуки, MCP-серверы, навыки и плагины.

Это AI-перевод статьи, сделанный каналом Про AI: Лучшие Статьи и Исследования.

Папка .codex/ — полный разбор

.codex/ folder explained Автор: Alex Fazio Оригинальный текст:

Если вы пытаетесь разобраться в конфигурации Codex, папка .codex/ — первое место, куда стоит заглянуть. И именно здесь обычно начинается путаница.

.codex/ — это собственная директория конфигурации Codex. Но это не вся модель. Codex также формируется файлами инструкций вроде AGENTS.md, конфигурацией репозитория и пользователя, многоразовыми навыками и пользовательскими агентами, а также границей доверия, которая определяет, загружаются ли вообще настройки, предоставленные репозиторием.

Один и тот же базовый агент может работать через CLI, десктопное приложение или расширение для IDE. Эти интерфейсы используют одну и ту же внутреннюю многоуровневую архитектуру. Как только вы видите все элементы, настройка становится гораздо проще для понимания.

Некоторые конфигурации также включают .agents/. Эту папку лучше понимать как смежный кросс-агентный слой, а не как вторую директорию конфигурации Codex. Поэтому данный гид сосредоточен на .codex/ и рассматривает .agents/ как контекст, который может вам понадобиться, а может и нет.

Короткий ответ

Если вы запомните только одно различие, запомните это:

• AGENTS.md говорит Codex, как работать в проекте или директории
• .codex/ хранит конфигурацию, специфичную для Codex: правила, пользовательские агенты, хуки и локальное состояние
• Проектная .codex/ — это репозиторная конфигурация Codex, предназначенная для совместного использования; пользовательская ~/.codex/ — ваш персональный домашний каталог Codex для всех репозиториев
• .agents/ хранит многоразовые навыки и файлы плагин-маркетплейса в общем формате, чтобы они оставались переносимыми между Codex и другими совместимыми агентами, например Claude Code или OpenCode
• Доверие определяет, учитывается ли вообще конфигурация .codex/, предоставленная репозиторием

Разделение между .codex/ и .agents/ — намеренное.

На уровне репозитория обе директории защищены песочницей и могут быть закоммичены в систему контроля версий для командного использования. Пользовательские директории вроде ~/.codex/ и ~/.agents/ являются персональными и не должны коммититься. Директория .codex/ читается только Codex; директория .agents/ также может читаться другими совместимыми агентами, поддерживающими тот же общий формат.

Практичная ментальная модель: инструкции говорят Codex, что вы хотите, конфигурация и правила определяют, что Codex может делать без запроса, и доверие определяет, учитывается ли вообще конфигурация из репозитория.

Правило размещения, которое покрывает большинство случаев:

• Если это инструкции о том, как Codex должен работать — поместите в AGENTS.md
• Если это конфигурация или политика, специфичная для Codex — поместите в .codex/
• Если это должно следовать за пользователем по репозиториям — поместите в ~/.codex/
• Если это должно оставаться переносимым между разными агентами — поместите в .agents/

Не держите обе директории просто для полноты. Держите обе, только когда вам нужны оба типа содержимого:

• Используйте AGENTS.md, когда хотите дать Codex рабочие инструкции
• Используйте .codex/, когда хотите конфигурацию, ограничители, правила, агенты, хуки или управляемые приложением файлы проекта, специфичные для Codex
• Используйте .agents/, когда также хотите переносимые навыки или записи маркетплейса плагинов, которые должны быть применимы за пределами Codex

Многим небольшим проектам достаточно AGENTS.md и, возможно, .codex/. Команды обычно добавляют .agents/, когда хотят многоразовые рабочие процессы, не привязанные только к Codex.

Два контекста .codex/

Именно здесь люди чаще всего путаются: «папка .codex/» может означать два разных расположения с двумя разными задачами.

Хорошее правило:

• Всё, что путешествует с репозиторием, принадлежит проектной .codex/
• Всё, что следует за вами по репозиториям, принадлежит пользовательской ~/.codex/

Это также согласуется с доверием и приоритетом. Пользовательская ~/.codex/ — базовый слой. Проектная .codex/ — слой, специфичный для репозитория, который Codex загружает только для доверенных проектов.

Несколько конкретных примеров:

• Общая политика песочницы или утверждения для данной кодовой базы принадлежит проектной .codex/config.toml
• Ваша персональная аутентификация, история, кэши или глобальные настройки по умолчанию принадлежат пользовательской ~/.codex/
• Агент-ревьюер, который должна использовать вся команда в данном репозитории, принадлежит проектной .codex/agents/
• Персональный агент или правило, которое вы хотите иметь доступным повсюду, принадлежит пользовательской ~/.codex/agents/ или ~/.codex/rules/

Типичная структура в репозитории и домашнем каталоге

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

Это форма, которую принимает модель, когда вы размещаете основные директории рядом.

Как элементы сочетаются друг с другом

Когда папки видны, следующий вопрос — что каждая из них на самом деле контролирует. Если вы задаётесь вопросом «это инструкции, конфигурация или общий навык?», вот карта.

Где размещается AGENTS.md

Когда папки понятны, следующая путаница обычно в том, принадлежит ли что-то AGENTS.md или .codex/. Разделение простое: если .codex/ — это конфигурация, AGENTS.md — это инструкции.

Codex читает файлы AGENTS.md перед выполнением работы и поддерживает многоуровневость, так что глобальные значения по умолчанию и локальные проектные указания могут комбинироваться:

• Глобальный контекст: в домашнем каталоге Codex (по умолчанию ~/.codex) Codex читает AGENTS.override.md, если он существует; иначе читает AGENTS.md, при этом первый непустой файл выигрывает на этом уровне
• Контекст репозитория: вы можете добавить AGENTS.md в корень репозитория и дополнительные файлы AGENTS.md в поддиректории для локальных правил; если в директории существует AGENTS.override.md, он переопределяет AGENTS.md там
• Лимиты загрузки: Codex конкатенирует найденные документы с инструкциями с пустыми строками, пока не достигнет настроенного лимита в байтах projectdocmax_bytes, который по умолчанию составляет 32 КиБ

Существует также механизм фолбэка для организаций, которые уже используют другое имя файла. С помощью projectdocfallbackfilenames вы можете указать Codex рассматривать файлы вроде TEAMGUIDE.md как источники инструкций.

Codex может сгенерировать стартовый AGENTS.md через CLI-команду /init. Это отправная точка. Рассматривайте её как каркас (scaffolding) для дальнейшей доработки.

Наиболее полезные файлы AGENTS.md обычно охватывают:

• Как запускать проект: команды для сборки, тестирования и линтинга (среди прочих)
• Ключевые директории и границы ответственности
• Ограничения и правила «не делать», которые не обеспечиваются другими средствами
• Ссылки на более глубокую документацию, плейбуки для ревью или шаблоны планирования вместо вложения всего в файл

Держите AGENTS.md достаточно коротким, чтобы человек мог его поддерживать. Конкретные инструкции стареют хорошо. Длинная описательная политика обычно нет.

Что принадлежит .codex/

Когда границы ясны, следующее решение — размещение: что принадлежит .codex/, а не AGENTS.md или .agents/? Самый простой способ думать о .codex/ — как о директории конфигурации Codex на уровне репозитория. Команды используют проектную .codex/ для общей проектной конфигурации, общих правил, проектных пользовательских агентов и управляемых приложением проектных файлов. На пользовательском уровне ~/.codex/ хранит персональные настройки по умолчанию и состояние: аутентификацию, историю, логи, кэши, состояние плагинов и устаревшие файлы промптов. Она стоит рядом с AGENTS.md, который предоставляет инструкции, и рядом с .agents/, которая является кросс-агентной общей директорией для навыков и маркетплейсов плагинов.

Далее полезный способ чтения .codex/ — от общих элементов наружу: сначала части, которые трогает большинство команд, затем слои расширений поверх.

Основные элементы .codex/, которые команды используют первыми

Это путь, который большинство конфигураций реально используют: слои конфигурации, config.toml, правила, проектные агенты и управляемые приложением файлы.

Слои конфигурации и границы доверия

Конфигурация Codex использует несколько слоёв, а не один файл. Как минимум вы имеете дело с:

• Пользовательским слоем в ~/.codex/config.toml
• Необязательными проектными слоями в файлах .codex/config.toml внутри репозитория, загружаемых от корня репозитория к текущему рабочему каталогу, при этом ближайший файл выигрывает
• Необязательным системным слоем вроде управляемого файла конфигурации (managed_config.toml, то есть файла конфигурации, обеспечиваемого системой или организацией) на поддерживаемых платформах

Codex разрешает значения по приоритету, то есть решает, какой слой выигрывает, когда одна и та же настройка определена в нескольких местах: управляемые слои и слои сессии с более высоким приоритетом берут верх над пользовательскими значениями по умолчанию. Порядок приоритета: управляемые MDM-предпочтения на macOS (настройки организации на управляемых Mac), системная управляемая конфигурация, переопределения сессии или CLI (временные переопределения на один запуск) и пользовательская конфигурация. Проектные файлы .codex/config.toml загружаются для доверенных проектов и встраиваются в эту иерархию. Значения, не установленные ни в одном слое, возвращаются к жёстко заданным значениям по умолчанию.

Доверие — это граница, которая имеет значение. Codex загружает проектную конфигурацию .codex/ только когда проект является доверенным; недоверенные проекты пропускают эти слои. Репозитории являются недоверенным вводом, пока вы явно не доверите им.

В текущей конфигурации Codex доверие проекта может быть записано явно через projects.<path>.trust_level, со значениями вроде "trusted" и "untrusted".

.codex/config.toml и ограничители среды выполнения

AGENTS.md говорит, как Codex должен работать. config.toml устанавливает ограничители вокруг этой работы.

Codex хранит пользовательскую конфигурацию в ~/.codex/config.toml и проектные переопределения в .codex/config.toml, при этом проектная конфигурация применяется только для доверенных проектов.

Две настройки доминируют в модели безопасности:

• Режим песочницы: что агент технически может делать, включая область файловой системы и сетевой доступ
• Политика утверждения: когда Codex должен остановиться и спросить перед выполнением действий

По умолчанию сетевой доступ выключен, а песочница с правом записи в рабочую область (режим, позволяющий Codex писать в рабочее пространство, защищая при этом определённые пути) предназначена для ограничения действий активным рабочим пространством.

Codex также предоставляет конфигурацию веб-поиска с тремя режимами: кэшированный, живой или отключённый. Кэшированный режим использует индекс, поддерживаемый OpenAI; живой режим загружает свежие страницы. Это различие важно, потому что навигация по вебу создаёт риск prompt injection (инъекции в промпт) от ненадёжного контента — вредоносные инструкции могут быть спрятаны внутри загруженных страниц.

Одна деталь, которая часто влияет на реальные проекты: в режиме записи в рабочую область некоторые окружения сохраняют .git/ и .codex/ доступными только для чтения, даже когда остальная часть рабочей области доступна для записи. Это может вынуждать утверждения для операций вроде git commit, которым нужно пересечь границу песочницы. Если вы хотите, чтобы Codex пропускал, блокировал или запрашивал подтверждение для определённых команд вне песочницы, правила — это механизм для этого.

Codex хранит локальное состояние под CODEX_HOME, который по умолчанию указывает на ~/.codex. Типичные файлы там включают auth.json при включённом файловом хранении учётных данных, history.jsonl при включённом сохранении истории, а также другие логи или кэши.

Если вы хотите отдельную автоматизированную идентичность с другой конфигурацией, инструкциями и локальным состоянием, вы можете направить CODEX_HOME в другое место, включая локальную для репозитория директорию .codex. Codex тогда будет разрешать источники инструкций относительно этого расположения.

Правила

Правила контролируют, какие команды Codex может выполнять за пределами песочницы. Они экспериментальные. Они используют небольшой язык правил на основе Starlark — Python-подобного языка конфигурации, реализованного в starlark-rust. Правила могут сопоставлять префиксы команд и назначать решения вроде "prompt".

Codex сканирует директории rules/ в расположениях team-config при запуске. Когда вы интерактивно добавляете команду в утверждённый список, Codex записывает это решение в файл правил пользовательского слоя, ~/.codex/rules/default.rules, чтобы последующие запуски могли пропускать тот же запрос.

Вот ценность правил: они превращают безопасность команд в политику, а не привычку.

Субагенты и состояние проекта, генерируемое приложением

Codex также поддерживает рабочие процессы с субагентами. Он может порождать параллельных специализированных агентов и затем консолидировать их вывод. Он делает это только когда вы явно запрашиваете, и это более затратно по токенам (tokens), чем работа с одним агентом.

Codex поставляется со встроенными агентами, такими как explorer и awaiter.

Вы можете определять пользовательских агентов как отдельные TOML-файлы в:

• ~/.codex/agents/ для персональных агентов
• .codex/agents/ для проектных агентов

Глобальные лимиты выполнения субагентов настраиваются в секции [agents] в конфигурации. Значения по умолчанию включают agents.maxthreads = 6 и agents.maxdepth = 1, с предупреждением, что более глубокая рекурсия может существенно увеличить стоимость и непредсказуемость.

Файл пользовательского агента должен включать description, а отдельные файлы агентов, обнаруженные в директории agents/, также должны включать developer_instructions. name является необязательным и по умолчанию берётся из имени файла. Файлы агентов также могут переопределять настройки, которые иначе помещаются в конфигурацию, включая модель, reasoning effort (усилие рассуждения), режим песочницы, MCP-серверы и конфигурацию навыков.

Десктопное приложение добавляет ещё одно проектное использование .codex/: локальные окружения. Это специфично для десктопного приложения Codex и не применяется к общему CLI. Вы настраиваете это в UI настроек приложения. Там вы определяете скрипты настройки, которые запускаются автоматически при создании worktree (рабочего дерева) — свежей рабочей копии репозитория — для нового потока. Вы также можете определять действия вроде запуска dev-сервера или тестов из UI приложения. Приложение хранит свою сгенерированную конфигурацию локального окружения внутри папки .codex в корне проекта, и вы можете закоммитить эту конфигурацию в Git для совместного использования.

Разделение проект/пользователь проявляется здесь снова. Проектная .codex/ хранит общее определение настройки. Фактические worktree живут централизованно под $CODEX_HOME/worktrees/, который по умолчанию указывает на ~/.codex/worktrees/, в домашнем каталоге Codex пользователя. Эти worktree работают в другой директории от локального проекта и наследуют только файлы, зафиксированные в Git. Поэтому скрипты настройки, сконфигурированные через локальные окружения, — это то, что устанавливает зависимости, собирает артефакты или восстанавливает любое другое состояние, исключённое .gitignore. Скрипты настройки также поддерживают платформо-специфичные варианты для macOS, Windows и Linux.

Codex управляет файлами локальных окружений под проектной .codex/. Приложение создаёт и обновляет эти файлы через свой UI настроек. OpenAI в настоящее время не документирует имя файла или публичный синтаксис для этой функции, предназначенной для ручного редактирования, поэтому поддерживаемый способ управления — через приложение, а не прямым редактированием файлов .codex/. Вы по-прежнему можете закоммитить сгенерированные файлы, если хотите общую настройку и действия.

Облачные рабочие процессы Codex часто полагаются на подключённые репозитории и интеграции, такие как GitHub, Slack и Linear. Навыки также могут объявлять зависимости от инструментов, включая MCP-серверы, через необязательные метаданные, чтобы UI мог более чётко направлять настройку.

До этого момента вы имеете часть .codex/, которую большинство команд использует ежедневно. Далее следует слой расширений.

Расширенные возможности .codex/

Остальная часть .codex/ — это слой расширений и интеграции. Он нужен только когда вы хотите внешние инструменты, автоматизацию жизненного цикла или устаревшие командные поверхности. Большинство команд могут сначала понять основную модель .codex/ и вернуться к этому позже.

Конфигурация MCP-серверов

MCP — основной механизм расширения. Codex действует как клиент Model Context Protocol (MCP). MCP-серверы расширяют возможности Codex, предоставляя внешние инструменты, источники данных и интеграции: доступ к файловой системе, GitHub, базы данных, автоматизация браузера или сервисы документации. Конфигурация MCP живёт в config.toml как на пользовательском уровне (~/.codex/config.toml), так и на проектном уровне (.codex/config.toml, загружается только для доверенных проектов).

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

Каждый сервер объявляется в секции [mcp_servers.<server-name>]. Большинству команд достаточно следить за четырьмя вещами.

Для удалённого сервера вы обычно заменяете command на url и необязательные заголовки аутентификации или переменные окружения с bearer-токеном.

Если не хотите редактировать TOML вручную, команды codex mcp list, codex mcp add, codex mcp get и codex mcp remove управляют записями пользовательского уровня в ~/.codex/config.toml. Проектные серверы обычно понятнее при прямом редактировании в проектной .codex/config.toml.

TOML-файлы пользовательских агентов также могут включать собственные таблицы [mcp_servers], что полезно, когда одному специализированному агенту нужен инструмент, который остальная часть Codex видеть не должна. Сам Codex тоже может работать как MCP-сервер через codex mcp-server.

Поскольку CLI, десктопное приложение и расширение для IDE читают один и тот же config.toml, конфигурацию MCP-сервера нужно выполнить только один раз.

Хуки

Хуки отличаются. Они позволяют внедрять пользовательские скрипты в цикл Codex: планирование, запуск инструментов, наблюдение за результатами и продолжение. Они дополняют плагины: плагины упаковывают многоразовые возможности, а хуки позволяют обеспечивать политики, добавлять логирование или настраивать поведение в определённых точках жизненного цикла.

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

Хуки в настоящее время отключены на Windows и выключены по умолчанию. Чтобы их включить, добавьте в config.toml: [features] codex_hooks = true

Codex ищет hooks.json рядом с активными слоями конфигурации, обычно ~/.codex/hooks.json и <repo>/.codex/hooks.json. Файлы хуков организуют обработчики по событию, сопоставителю и команде. Основные события: SessionStart, PreToolUse, PostToolUse, UserPromptSubmit и Stop.

Типичные случаи использования включают:

• Логирование и аналитика
• Сканирование промптов на наличие секретов
• Ограничители вокруг shell-команд
• Валидация или обратная связь после выполнения
• Принудительный дополнительный проход перед остановкой Codex

Хуки могут влиять на поведение, возвращая JSON Codex, например, чтобы запретить команду или внедрить дополнительное руководство. Они являются полезными ограничителями, но не идеальной границей обеспечения. Решительная модель иногда может обойти их косвенно.

Worktree и $CODEX_HOME/worktrees/

Если вы используете десктопное приложение, worktree имеют большое значение. Приложение использует git worktree для запуска нескольких потоков и автоматизаций параллельно, не мешая вашему локальному чекауту. Git worktree — это просто второй чекаут того же репозитория: у него свои файлы на диске, но он разделяет базовую git-историю и метаданные веток с основным репозиторием.

Это функция приложения. Если вы используете только CLI, этот раздел — в основном контекст, а не то, что нужно настраивать напрямую.

Опять же, разделение контекстов имеет значение:

• Проектная .codex/ хранит сгенерированную приложением конфигурацию локального окружения, которая говорит приложению Codex, как настраивать новые worktree
• Пользовательская ~/.codex/worktrees/ хранит управляемые приложением копии чекаутов

Когда вы запускаете новый поток в worktree, Codex создаёт отдельный чекаут от выбранной ветки, может применить незакоммиченные изменения из исходного чекаута и часто использует состояние detached HEAD — worktree привязано к конкретному коммиту, а не к имени ветки, — чтобы избежать конфликтов чекаута при нескольких рабочих копиях.

Есть два основных режима worktree: управляемые Codex worktree — лёгкий режим по умолчанию для отдельных потоков, и постоянные worktree — долгоживущая версия, которую вы сохраняете намеренно.

Приложение может передавать работу между локальным чекаутом и worktree. Автоматизации также могут работать либо в локальном проекте, либо в выделенных фоновых worktree. Для git-репозиториев режим worktree обычно безопаснее, потому что он изолирует изменения автоматизации от активной разработки.

Worktree наследуют доверие от основного репозитория, а не требуют отдельного решения о доверии. Поскольку worktree начинает только с файлов, существующих в Git, он может не содержать зависимостей или артефактов сборки. Вот тут вступают локальные окружения: они позволяют приложению Codex автоматически запускать сохранённые скрипты настройки проекта при создании нового worktree.

Устаревшие пользовательские промпты как команды

Codex раньше поддерживал пользовательские промпты, превращающие Markdown-файлы в многоразовые slash-команды, но эта функция теперь устарела в пользу навыков.

Устаревшие пользовательские промпты хранятся в ~/.codex/prompts/ и могут вызываться как /prompts:<name> в CLI и расширении IDE. Они поддерживают блоки метаданных YAML frontmatter и подстановку заполнителей: $ARGUMENTS, $1..$9 и KEY=value.

Для практического использования сегодня:

• Используйте навыки для общих структурированных рабочих процессов и для процессов, которые Codex должен вызывать неявно
• Используйте пользовательские промпты только для устаревших рабочих процессов или лёгких персональных ярлыков

Дополнение: Когда .agents/ нужна рядом с .codex/

До сих пор фокус был на .codex/, потому что это специфичная для Codex часть конфигурации. .agents/ появляется в картине, когда вам также нужен кросс-агентный общий слой в том же репозитории или домашнем каталоге. Вы добавляете .agents/ рядом с .codex/, когда конфигурации, специфичной для Codex, недостаточно самой по себе, и вам также нужны переносимые навыки или записи маркетплейса плагинов, которые понимают другие агенты.

.codex/ — это конфигурация, специфичная для Codex. .agents/ — это кросс-агентная общая директория, которую распознают несколько кодинг-агентов. Она существует и на уровне репозитория (.agents/ в корне репозитория), и на пользовательском уровне ($HOME/.agents/ или ~/.agents/). Codex рассматривает её как первоклассную директорию: загрузчик навыков, система маркетплейса плагинов и песочница напрямую ссылаются на неё.

Навыки

Навыки — это многоразовые пакеты рабочих процессов. Каждый навык живёт в собственной директории с обязательным файлом SKILL.md, содержащим YAML frontmatter (метаданные в начале файла между строками ---) плюс сами инструкции. Необязательные директории scripts/, references/, assets/ и agents/openai.yaml добавляют вспомогательные скрипты, справочные материалы, изображения и более богатые метаданные.

Для большинства читателей ключевые поля frontmatter просты:

• description обязателен и управляет сопоставлением навыков
• name необязателен и по умолчанию берётся из имени директории
• необязательные метаданные могут предоставить более краткие описания или пометить навык как внутренний

Codex может вызывать навыки тремя способами:

• Явно, например, через $-упоминание навыка
• Неявно, когда обнаруживает команды или чтение файлов внутри директории навыка
• По описанию, когда задача чётко соответствует описанию навыка

Для текущих конфигураций рассматривайте .agents/skills/ как основное расположение в репозитории и ~/.agents/skills/ как персональное. Более старые ссылки могут упоминать .codex/skills.

Codex обнаруживает навыки репозитория, проходя от текущего рабочего каталога до корня проекта и ища .agents/skills/. Он также загружает навыки пользовательского уровня из ~/.agents/skills/, плюс корни навыков от администратора, системных и предоставленных плагинами. Символические ссылки поддерживаются, потому что CLI навыков часто устанавливает таким образом.

Конкретные навыки можно включить или отключить в config.toml по имени или пути. Codex также защищает .agents/ тем же режимом песочницы, что и .git/ и .codex/.

Файл .agents/plugins/marketplace.json регистрирует плагины для обнаружения. Codex читает файлы маркетплейса из официального курируемого источника, маркетплейса на уровне репозитория и персонального маркетплейса пользователя.

CLI навыков, вызываемый через npx skills, управляет общей директорией навыков и реестром. Он рассматривает .agents/skills/ как общую проектную директорию для многих агентов, включая Codex. Проектные установки отслеживаются в skills-lock.json; глобальные установки отслеживаются в ~/.agents/.skill-lock.json.

Разделение остаётся чистым: конфигурация, специфичная для Codex — config.toml, правила, определения агентов, хуки и файлы, управляемые приложением — остаётся в .codex/; общие переносимые навыки и файлы маркетплейса идут в .agents/.

Где размещаются плагины

Плагины имеют смысл только когда видны и .codex/, и .agents/, потому что они являются точкой, где дистрибуция пересекает границу между ними.

Плагины нужны, когда вы хотите упаковать и распространять навыки, интеграции приложения или настройку MCP как одну устанавливаемую единицу.

Плагины располагаются поверх .codex/ и .agents/, а не живут чисто внутри одной из сторон. Манифест живёт в .codex-plugin/plugin.json, обнаружение обычно происходит через .agents/plugins/marketplace.json, кэши установленных плагинов хранятся под ~/.codex/plugins/cache/, а состояние вкл/выкл хранится в ~/.codex/config.toml.

Плагин — это устанавливаемый пакет, упаковывающий навыки, интеграции приложения и конфигурации MCP-серверов в одну распространяемую единицу. Навыки — формат разработки рабочих процессов. Плагины — формат дистрибуции.

Только .codex-plugin/plugin.json обязателен. Минимальный манифест именует плагин, объявляет его версию и описание и указывает на включённые навыки или необязательную конфигурацию приложения и MCP.

Codex обнаруживает плагины из трёх маркетплейсов: официальный курируемый каталог, .agents/plugins/marketplace.json репозитория и ~/.agents/plugins/marketplace.json пользователя.

Когда плагин установлен, Codex кэширует его под ~/.codex/plugins/cache/ и загружает из кэшированной копии. Плагины можно устанавливать через каталог плагинов приложения или из CLI через /plugins. Для локальной разработки встроенный навык $plugin-creator может сгенерировать каркас манифеста и записи маркетплейса.

Плагины можно использовать по описанию — вы просите нужный результат — или явно через @-упоминание.

Плагины стоят выше нижнеуровневых элементов в этом гиде. Навыки остаются форматом разработки многоразовых рабочих процессов. MCP-серверы остаются слоем подключения инструментов. Правила по-прежнему применяются к командам, вызываемым через плагины. AGENTS.md по-прежнему предоставляет проектные инструкции; он дополняет плагины, а не упаковывается внутрь них.

Если вы хотите построить плагин вручную, путь прост: создайте папку плагина, добавьте .codex-plugin/plugin.json, поместите включённые навыки под skills/, необязательно добавьте конфигурацию приложения или MCP, затем зарегистрируйте плагин в файле маркетплейса.

Полный список ссылок на исходный код и документацию см. в [оригинальной статье](https://x.com/alxfazio/status/2038304800857579877).

Подпишитесь на канал и каждый день читайте лучшие материалы про AI переведенные на русский!

Нашли интересную статью для перевода? Пришлите нашему боту: @ailongreadsbot