Система плагинов для Codex CLI развивается стремительно: команда /plugins уже позволяет просматривать, устанавливать, включать и отключать плагины по категориям. Всё больше команд упаковывают свои внутренние инструменты в виде переиспользуемых плагинов Codex. Однако официальный Marketplace сейчас работает в режиме «строгой модерации» для самостоятельной публикации. Разработчикам нужно сначала разобраться со структурой манифеста и методами локальной отладки, а затем пройти процесс проверки, чтобы плагин стал доступен пользователям. В этой статье мы пошагово разберем весь путь: от создания «с нуля» и локального тестирования до дистрибуции через Git и прохождения официальной модерации, а также разберем типичные ошибки.
Из чего на самом деле состоит плагин Codex
По сути, плагин Codex — это способ упаковать различные возможности в единый модуль, который можно легко установить и распространять. Согласно официальной документации OpenAI, плагины могут включать в себя skills (описания переиспользуемых навыков), MCP-backed app (сервисы для подключения внешних инструментов), хуки жизненного цикла, а также опциональные расширения для браузера и шаблоны для фоновых задач. Все эти компоненты не обязательно должны присутствовать одновременно: легкий плагин, содержащий только skills, будет работать так же эффективно.
Понимание границ ответственности каждого компонента — залог правильного манифеста. В таблице ниже приведены пути размещения и назначение четырех ключевых компонентов плагина Codex:
| Компонент | Путь размещения | Назначение | Обязательно |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
Идентификация и метаданные плагина | Да |
| skills | skills/<skill-name>/SKILL.md |
Определение переиспользуемых инструкций | Нет |
| MCP servers | .mcp.json |
Конфигурация подключения внешних инструментов | Нет |
| hooks | hooks/hooks.json |
Объявление команд хуков жизненного цикла | Нет |
Важно отметить: если плагин — это просто файл SKILL.md для внутреннего использования в команде, проходить через полноценный процесс с манифестом не нужно. Достаточно просто положить файл в директорию .agents/skills/, и Codex автоматически его подхватит. Это распространенный промежуточный этап для многих команд при переходе от «внутренних скриптов» к «официальным плагинам».
Границы возможностей плагинов шире, чем кажется на первый взгляд. Помимо skills и MCP-backed app, документация упоминает возможность включения компонентов для расширений браузера и шаблонов периодических задач. Это значит, что плагин может обрабатывать как интерактивные запросы пользователя, так и автоматизированные сценарии, работающие в фоновом режиме. Выбор компонентов — это всегда баланс между удобством установки и стоимостью поддержки. Чем больше компонентов, тем функциональнее плагин, но тем сложнее подготовить материалы для проверки и тестовые сценарии. Перед отправкой на модерацию лучше четко определить, что именно нужно вашим пользователям, а не пытаться запихнуть всё подряд в один пакет.
Начинаем с plugin.json: подробный разбор манифеста плагина
plugin.json — это «паспорт» вашего плагина. Именно по нему Codex понимает, как распознать, загрузить и отобразить его в интерфейсе. Для минимально рабочего манифеста достаточно всего трех полей:
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}
Для поля name рекомендуется использовать стабильный формат kebab-case. Не меняйте этот идентификатор при обновлении версий, иначе маркетплейс не поймет, что это тот же самый плагин. Поле version должно соответствовать семантическому версионированию — маркетплейс опирается на него, чтобы предлагать пользователям обновления. Все пути, указанные в манифесте, должны быть относительными (начинаться с ./) и находиться строго внутри корневой директории плагина.
Помимо базовых полей, skills может указывать на массив директорий с навыками, а поля hooks, mcpServers и apps ссылаются на соответствующие конфигурационные файлы: hooks/hooks.json, .mcp.json и .app.json. Такая архитектура «ссылок на файлы» позволяет держать манифест лаконичным: описание навыков и настройки инструментов вынесены в отдельные файлы. Это упрощает командную работу, позволяя параллельно править разные компоненты без конфликтов.
Если вы планируете публиковать плагин в официальном маркетплейсе, нужно добавить метаданные для отображения. В таблице ниже перечислены ключевые поля, которые стоит заполнить перед релизом:
| Поле | Тип | Описание |
|---|---|---|
| author / repository | строка | Источник плагина (должен совпадать с подтвержденным профилем) |
| interface.displayName | строка | Имя плагина в списке маркетплейса |
| interface.category | строка | Категория плагина, влияет на навигацию пользователя |
| interface.capabilities | массив | Теги возможностей плагина |
| mcpServers / apps / hooks | объект | Ссылки на конфиги соответствующих компонентов |
Самая частая ошибка при написании манифеста — неправильные пути (например, использование абсолютных путей или пропуск ./). Из-за этого плагин может работать локально, но не проходить проверку при подаче на модерацию. Советую перед отправкой клонировать репозиторий в чистую папку и провести полный тест в условиях, максимально приближенных к реальной установке.
Локальный скаффолдинг и отладка: запускаем плагин
Писать манифест вручную — не самый эффективный путь. Официально есть встроенный навык $plugin-creator, который поможет создать каркас плагина прямо через диалог в Codex CLI:
codex "Используй $plugin-creator для создания плагина с именем infra-monitor"
Эта команда автоматически сгенерирует манифест, пример навыка и запись для локального маркетплейса, избавив вас от рутины. После этого плагин можно сразу устанавливать и тестировать локально, не дожидаясь публикации в удаленных репозиториях.
На этапе отладки, если ваш навык предполагает вызов разных больших языковых моделей для сравнительного анализа, единый API-шлюз поможет сэкономить кучу времени на переключении конфигураций. При проверке возможностей MCP-сервера плагина мы обычно направляем base_url на сервис-прокси API APIYI (apiyi.com). Один API-ключ позволяет переключаться между моделями прямо внутри плагина, что очень удобно для сравнения того, как разные модели справляются с одной и той же логикой:
from openai import OpenAI
client = OpenAI(
api_key="your-apiyi-key",
base_url="https://api.apiyi.com/v1"
)
🎯 Совет по отладке: В процессе разработки плагинов для Codex часто нужно проверять качество ответов MCP-сервера на разных моделях. Мы рекомендуем использовать платформу APIYI (apiyi.com) для централизованного управления вызовами моделей. Это избавит вас от необходимости получать отдельные ключи для каждой модели и поддерживать разную логику вызовов, позволяя сосредоточиться на самой функциональности плагина.
Помимо ручного создания записей в локальном маркетплейсе, можно объявить путь к плагину в ~/.agents/plugins/marketplace.json (для пользователя) или в .agents/plugins/marketplace.json в корне репозитория (для команды), установив поле source в значение local. Это позволит установить и проверить плагин без пуша в удаленный репозиторий.
Если ваш плагин включает MCP-backed приложение, требующее отладки в режиме разработчика ChatGPT, есть еще один путь: включите режим разработчика в настройках ChatGPT, создайте MCP-backed приложение, получите его ID и свяжите его через $plugin-creator. Это позволит проверять потоки данных между плагином и приложением в реальном диалоге — это гораздо ближе к тому, как все будет работать после релиза, поэтому рекомендую пройти этот сценарий перед подачей на проверку.
Регистрация в Git-маркете и распространение внутри команды
После того как плагин успешно прошел локальное тестирование, для распространения внутри команды не обязательно ждать официальной модерации — достаточно создать маркет-ресурс на базе Git-репозитория. Codex CLI предоставляет набор специальных команд для управления таким маркетом:
| Команда | Назначение |
|---|---|
codex plugin marketplace add owner/repo |
Добавить GitHub-репозиторий как маркет-ресурс |
codex plugin marketplace add owner/repo --ref v2.1.0 |
Зафиксировать конкретную ветку или тег для контроля поэтапного релиза |
codex plugin marketplace list |
Просмотреть список добавленных маркетов |
codex plugin marketplace upgrade |
Получить обновления из маркета |
codex plugin marketplace remove |
Удалить маркет-ресурс |
Для команд, работающих с крупными репозиториями, можно использовать параметр --sparse .agents/plugins, чтобы выгружать только директорию с плагинами, не клонируя весь репозиторий и не замедляя установку. Такая модель Git-маркета идеально подходит для внутренних корпоративных инструментов: не требуется публичная проверка, а для обновления плагина достаточно просто запушить новый тег — участникам команды останется лишь выполнить команду upgrade для синхронизации.
С практической точки зрения, у модели Git-маркета есть скрытое преимущество: она позволяет отвязать темп итераций плагина от общего цикла релизов команды. Бизнес-код может объединяться (merge) по несколько раз в день, но плагин как часть диалогового инструментария при слишком частых обновлениях может сбивать пользователей с толку. Рекомендую привязывать версии плагинов к фиксированным окнам релиза, например, объединяя изменения раз в неделю или две. Это обеспечит стабильный темп развития функционала, не заставляя коллег постоянно привыкать к новым способам взаимодействия.
Полный процесс подачи на модерацию в официальный Marketplace
На данный момент портал самообслуживания для официального Marketplace еще не полностью открыт — в документации OpenAI указано, что эта функция «скоро появится». Сейчас официальная подача для публичных пользователей проходит через процесс ручной модерации. Перед отправкой необходимо пройти верификацию личности: индивидуальные разработчики проходят individual verification, а компании — business verification. Модераторы сверяют данные заявителя с предоставленными документами.
Список материалов, необходимых для официальной подачи:
| Категория материалов | Конкретные требования |
|---|---|
| Базовая информация | Название, описание, логотип, категория, ссылки |
| MCP-сервер | Домен с доступом извне, CSP-политики, конфигурация аутентификации |
| Демо-аккаунт | Доступ без MFA или подтверждения по почте |
| Тестовые сценарии | Ровно 5 позитивных и 3 негативных сценария |
| Разметка инструментов | readOnlyHint, openWorldHint, destructiveHint должны соответствовать реальному поведению |
Процесс подачи разбит на несколько разделов: Info (информация для каталога), MCP (сервер и аутентификация), Skills (загрузка пакета навыков), Prompts (примеры промптов), Testing (тестовые сценарии), Global (доступные страны и регионы). В конце заполняется раздел Submit с примечаниями к релизу и подтверждением политик. После одобрения разработчик сам выбирает время публикации, и плагин появится в едином каталоге плагинов ChatGPT и Codex.
Если плагин включает MCP-backed приложение, потребуется дополнительная проверка прав на домен, чтобы убедиться, что домен развертывания MCP-сервера совпадает с доменом, заявленным в плагине. Команда модераторов будет пристально следить за тем, чтобы результаты работы инструментов не содержали лишних персональных данных или ключей доступа — это стоит предусмотреть при проектировании формата вывода данных, чтобы не вносить правки после отклонения заявки.
Управление версиями и типичные «подводные камни»
После запуска плагина детали управления версиями напрямую влияют на то, насколько комфортно пользователям будет обновляться. Маркетплейс использует поле version для проверки наличия обновлений, поэтому важно строго следовать семантическому версионированию: используйте патч-версии для исправления багов, минорные версии для новых функций и мажорные — только для критических изменений, нарушающих обратную совместимость.
Установленные плагины кэшируются по локальному пути ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. Если вы столкнулись с проблемой «плагин обновился, но поведение не изменилось», первым делом проверьте, обновился ли кэш до новой версии — это часто помогает найти причину быстрее, чем повторная отладка логики кода. В корпоративной среде также можно столкнуться с политикой белых списков, принудительно задаваемой через requirements.toml. MCP-сервер должен соответствовать требованиям по имени и идентификатору одновременно: любое несоответствие приведет к тому, что сервис будет молча отключен без явных сообщений об ошибках. Такие сценарии лучше сначала проверять в тестовой среде перед развертыванием в продакшене.
В таблице ниже собраны частые проблемы, о которых сообщают разработчики, и способы их решения:
| Распространенная проблема | Способ решения |
|---|---|
| Путь в manifest указан как абсолютный | Замените на относительный, начинающийся с ./ |
| Неявный вызов задействовал не тот плагин | Используйте явное указание через @plugin-name |
| Поведение после обновления не изменилось | Проверьте, обновилась ли локальная папка кэша плагина |
| MCP молча отключается в корпоративной среде | Сверьте имя и идентификатор в requirements.toml |
Перед официальной отправкой на проверку рекомендую прогнать плагин через сторонний инструмент codex-plugin-scanner. Он оценивает плагин по таким критериям, как возможность установки, состояние поддержки, безопасность MCP и источник публикации. Особенно это важно для плагинов, предназначенных корпоративным клиентам: лучше найти проблемы заранее, чем тратить время на доработку после отклонения модерацией.
Еще одна деталь, которую часто упускают — разница между явным вызовом и неявным обнаружением. Если плагин не указан явно, Codex автоматически подбирает наиболее подходящий навык на основе контекста. Если в одном рабочем пространстве установлено несколько похожих плагинов, такая неявная привязка может выбрать не тот, который вы ожидали. Приучите себя к использованию @plugin-name для явного объявления, особенно в общих рабочих пространствах — это сэкономит время на отладку конфликтов между плагинами.
Часто задаваемые вопросы по разработке плагинов для Codex
В чем разница между плагином и отдельным файлом SKILL.md?
SKILL.md — это компонент внутри плагина. При использовании отдельно он не требует манифеста: достаточно поместить его в директорию .agents/skills/, и он будет обнаружен автоматически. Плагин же объединяет навыки (skills), MCP-серверы, хуки и другие компоненты в единый пакет с идентификатором и версионированием, что идеально подходит для официального распространения и отслеживания обновлений.
Что делать, если на этапе разработки нужно сравнивать работу нескольких моделей?
Это частая задача при разработке плагинов, особенно если вы настраиваете промпт или выбираете подходящую модель. Вместо того чтобы регистрироваться у каждого провайдера и управлять множеством ключей, лучше использовать единый шлюз, такой как APIYI (apiyi.com). Это позволит проводить A/B-тестирование популярных моделей через один API-ключ, сосредоточившись на логике плагина, а не на администрировании аккаунтов.
Могут ли сосуществовать распространение через Git-маркет и официальный Marketplace?
Да. Многие команды сначала используют Git-маркет для внутренней проверки и ограниченного тестирования, а после достижения стабильности переходят к официальной процедуре публикации. Эти способы не конфликтуют друг с другом, а структура манифеста остается универсальной.
Сколько времени занимает проверка плагина?
Официальная документация пока не дает точных сроков, указывая лишь на то, что процесс проверки находится в стадии развития и масштабирования, а ускоренная обработка не предусмотрена. Рекомендую закладывать время на проверку как переменную неопределенности в графике проекта. Подготовьте все материалы заранее, чтобы избежать лишних итераций и переписок — это самый надежный способ ускорить релиз.
Заключение
Основная сложность при разработке плагинов для Codex заключается не столько в самом коде, сколько в понимании требований к манифесту и подготовке материалов для процесса модерации. Эти детали не так сложны, как кажутся, но из-за одной ошибки в пути или отсутствующего поля ваш плагин могут отправить на доработку. Рекомендую придерживаться следующего порядка действий: «проверка через локальный скаффолд → распространение в узком кругу через Git → отправка на официальную проверку». На каждом этапе закладывайте время на тестирование в реальных условиях. Если ваш плагин предполагает вызов модели или требует частого переключения между ними для тестов, сервис-прокси API от APIYI (apiyi.com) поможет сэкономить кучу времени на настройке окружения, позволяя сосредоточиться на оттачивании функционала самого плагина.
