Плагины (Plugins): пакетная установка и распространение возможностей
📚 Навигация по серии: Предыдущая статья [22 · Умения агента (Agent Skills)] научила вас создавать «руководства по эксплуатации» для Codex — модули Skill, определяющие пошаговую работу. Но в процессе настройки вы неизбежно заметите неудобство: умения, конфигурации MCP и интеграции с приложениями настраиваются по отдельности. В этой главе мы научимся объединять их в плагины (Plugins) для пакетной установки, отключения и дистрибуции. В следующей главе [24 · Правила и хуки (Hooks)] мы разберем автоматический запуск процессов по событиям.
Коллеги, сегодня мы разберем функцию, которая на первый взгляд кажется избыточной, но на практике является необходимой, — плагины.
Многие при первом знакомстве думают: «Это просто те же斜杠-команды в новой обертке. Разве команда /review из главы 12 не работает так же?». На самом деле разница принципиальна. 斜杠-команды вы вызываете вручную. Модули Skill работают автономно: Codex анализирует задачу, сопоставляет ее с описанием доступных умений, автоматически загружает нужное и при этом практически не расходует контекст в режиме ожидания.
Вся рутина с ручным переносом настроек происходила из-за отсутствия пакетной упаковки. В апреле 2025 года я настраивал в одном из проектов связку для генерации схем баз данных: создавал умения (Skills) и прописывал подключение сервера MCP. Вся процедура заняла два часа. Спустя две недели мне потребовалось перенести эту связку в новый репозиторий. Я копировал файлы вручную, но упустил из виду переменные среды в конфигурационном файле .mcp.json. В итоге сервер баз данных не запустился, и я потратил еще полчаса на отладку. При ручном копировании легко упустить важную деталь.
Плагины решают эту проблему: они упаковывают умения, коннекторы API и серверы MCP в единый распространяемый пакет для установки одной командой. Вы один раз собираете решение, и оно без проблем переносится в другие проекты и на компьютеры коллег.
После прочтения этой статьи вы получите:
- Что именно упаковывает плагин и как выбрать правильный формат (Skill vs Plugin)
- Способы навигации по каталогу плагинов в десктопном приложении и CLI
- Как добавить маркетплейс, установить плагин через CLI и вызвать его по символу
@ - Структура папок пакета плагина (манифест
.codex-plugin/plugin.jsonи каталоги компонентов) для самостоятельной сборки - Границы безопасности: правила подтверждения прав доступа для сторонних плагинов и фоновых хуков
01 Что упаковывает плагин
Начнем с определения: плагин представляет собой изолированную папку, объединяющую повторно используемые компоненты — умения (Skills), интеграции (Apps) и серверы MCP — в единый пакет для совместного запуска, отключения и дистрибуции.
Зачем это нужно? При локальной ручной настройке возникают три проблемы: сложность переноса в новые проекты, отсутствие удобных каналов обмена с коллегами и сложность обновления. Скопировать папку skills/ недостаточно, нужно перенести и куски файлов настроек. Плагин решает это по принципу «всё в одной коробке».
Аналогия: покупка готового комплекта мебели ИКЕА. Если вы хотите собрать рабочий кабинет, вы можете искать по отдельности стол, стул, лампу и полки, выверяя размеры и цвета. Или вы заказываете готовый комплект, где все элементы идеально подобраны и упакованы в одну коробку. Плагин — это такой готовый комплект возможностей.
Разработчики выделили три типа компонентов, которые упаковываются в плагин:
| Компонент | Назначение | Способ использования |
|---|---|---|
| Skills (умения) | Пошаговые текстовые инструкции; загружаются по требованию | Автоматически по смыслу или явно по символу @ |
| Apps (интеграции) | Коннекторы к GitHub, Slack, Google Drive; дают доступ к API | Требуют авторизации в аккаунте ChatGPT при первом вызове |
| Серверы MCP | Подключение сторонних баз знаний и утилит | Требуют настройки портов или передачи токенов доступа |
Плагин объединяет умения (глава 22), серверы MCP (глава 20) и коннекторы внешних приложений ChatGPT в единый распространяемый дистрибутив.
Как выбрать правильный формат работы? Руководствуйтесь правилом: для локальных тестов в рамках одного репозитория достаточно использовать умения (Skills). Для дистрибуции кода в команде, версионирования и объединения MCP с коннекторами API собирайте плагин (Plugin).
Сравнение форматов:
| Параметр | Умение Skill (локально) | Плагин Plugin |
|---|---|---|
| Назначение | Локальная работа, простые тесты в одном репозитории | Совместная работа, пакетная интеграция MCP и API, версии |
| Содержимое | Текстовый файл инструкции | Умения, коннекторы, серверы и хуки в одном пакете |
| Распространение | Копирование файлов вручную | Публикация в каталоге или репозитории для установки одной командой |
| Поддержка версий | Отсутствует | Полноценная поддержка версионирования (поле version) |
💡 Резюме одной фразой: Codex плагин — это пакетная сборка умений, приложений и серверов MCP. Для себя пишите Skills; для совместной работы и версионирования собирайте плагины.
02 Преимущества пакетной упаковки
Мы выяснили структуру плагина. Но почему стоит собирать плагин вместо обычного копирования папок?
Разница заметна в трех сценариях:
1. Перенос между проектами. Как отмечалось выше, при ручном копировании легко упустить переменные окружения в конфигурациях. Установка плагина гарантирует перенос всех связанных конфигураций без ошибок.
2. Совместная работа. Попытки переслать коллеге архив с папками ведут к ошибкам настройки путей. Публикация плагина в корпоративном маркетплейсе решает эту проблему: коллега устанавливает пакет одной командой с гарантированным результатом.
3. Версионирование и менеджмент. Манифест плагина поддерживает указание версии (version). Вы можете управлять поведением установленных плагинов (отключать или настраивать уровни согласования инструментов) в общем файле конфигурации пользователя, не изменяя файлы плагина.
Аналогия: установка профиля конфигурации на рабочий телефон. Администратор не настраивает почту, VPN и сертификаты на каждом телефоне сотрудника вручную — он присылает один файл профиля. При его установке все параметры прописываются автоматически, а при удалении профиля телефон возвращается в исходное состояние. Плагин — это такой конфигурационный профиль для Codex.
Сравнение подходов наглядно иллюстрирует разницу:
| Задача | ❌ Ручное копирование | ✅ Плагин |
|---|---|---|
| Перенос в новый проект | Ручное копирование файлов; риск потерять переменные и конфиги | Установка одной командой из репозитория |
| Передача коллегам | Объяснение структуры папок и правил ручной правки config.toml | Установка по ссылке из общего маркетплейса |
| Обновление версий | Требует ручного оповещения и замены файлов на ПК коллег | Контроль версий, централизованное обновление и отключение |
Для одного разработчика выгода от создания плагинов невелика. Но в командной разработке при подключении внешних API и серверов MCP упаковка в плагин экономит время на развертывание среды для каждого нового сотрудника.
💡 Резюме одной фразой: преимущества плагина раскрываются при масштабировании разработки — простой перенос, версионирование и централизованная дистрибуция в команде заменяют ручную работу.
03 Каталог плагинов: встроенный магазин приложений
Откуда загружать готовые плагины? В Codex встроен каталог плагинов (Plugin Directory), разделенный на три группы:
Аналогия: разделы в магазине мобильных приложений. У вас есть выбор редакции (проверенные приложения от авторов платформы), приложения вашей семьи (доступные по корпоративной подписке) и ваши собственные установленные разработки.
В Codex каталог разделен аналогично:
| Раздел | Содержимое |
|---|---|
| Curated by OpenAI (Выбор редакции) | Проверенные плагины, доступные всем пользователям |
| Shared with you (Поделились с вами) | Плагины, опубликованные коллегами в вашем рабочем пространстве |
| Created by you (Созданные вами) | Плагины вашей собственной разработки |
Каталог доступен как в десктопном интерфейсе, так и в терминале:
В десктопном приложении: откройте вкладку Plugins для поиска и установки.
В CLI-терминале: запустите сессию и введите команду (обратите внимание на множественное число):
codex
/pluginsВ интерфейсе TUI плагины сгруппированы по маркетплейсам. Выберите нужный плагин, изучите описание и нажмите Install plugin для установки. Клавиша Space позволяет временно отключить плагин без его удаления.
Способы вызова плагина после установки:
- Обычный запрос. Опишите задачу («найди непрочитанные письма в Gmail»), и Codex сам выберет нужный плагин для интеграции;
- Явный вызов по символу
@. Укажите имя плагина или его конкретное умение в чате, чтобы исключить неверное сопоставление (например,@gmail-plugin).
Явный вызов по символу @ аналогичен вызову умений из главы 22.
💡 Резюме одной фразой: каталог плагинов является встроенным магазином приложений в Codex. Для навигации используйте вкладку настроек или команду
/pluginsв CLI. Вызов осуществляется через обычный промпт или символ@.
04 Контроль прав доступа и данных при установке
Установка плагина не означает автоматическую выдачу разрешений. Все правила согласования песочницы и запросы доступа по-прежнему применяются к инструментам плагина.
Компоненты плагина активируются с разной степенью контроля:
| Компонент | Поведение после установки |
|---|---|
| Skills | Доступны к использованию мгновенно без подтверждений |
| Apps | При первом вызове потребуют авторизации в аккаунте ChatGPT |
| MCP servers | Могут потребовать настройки портов или передачи ключей доступа |
Умения Skills начинают работать сразу, коннекторы Apps требуют OAuth-авторизации, а серверы MCP могут потребовать настройки в файле конфигурации.
Помните о безопасности данных: при передаче информации коннекторами плагина сторонним службам (GitHub, Slack, Drive) действуют соглашения о конфиденциальности этих внешних систем. Оценивайте важность передаваемой информации.
Аналогия: предоставление доступов приложению умного дома. Вы установили программу (плагин активен), но для вывода картинки с камеры вам нужно ввести пароль от аккаунта облака камеры (авторизация OAuth), а для связи с термостатом — прописать порты роутера (настройка MCP). Каждый шаг контролируется пользователем отдельно.
Управление установленными плагинами:
- Удаление: откройте карточку плагина в каталоге и выберите Uninstall plugin. Учтите, что удаление плагина из Codex не аннулирует выданные права OAuth в вашем аккаунте ChatGPT (их нужно отключать в настройках профиля ChatGPT вручную);
- Отключение: пропишите флаг
enabled = falseв конфигурационном файле~/.codex/config.tomlпользователя:
[plugins."gmail@openai-curated"]
enabled = falseКлюч формируется по схеме имя_плагина@имя_маркетплейса. В CLI переключение активности выполняется клавишей Space.
💡 Резюме одной фразой: установка плагина не обходит правила безопасности песочницы. Умения работают сразу, приложения требуют OAuth, а серверы MCP — настройки. Отключение плагина прописывается в
config.toml(enabled = false).
05 Практика: добавление маркетплейса, установка и вызов плагина
Пройдем шаги настройки в терминале: добавление репозитория маркетплейса → установка плагина → вызов.
Добавление маркетплейсов выполняется через консольные команды управления codex plugin marketplace (это команды терминала, а не чата):
Шаг 1. Добавляем маркетплейс
Зарегистрируйте репозиторий (укажите адрес вашего GitHub-репозитория):
codex plugin marketplace add owner/repoСистема поддерживает указание конкретных веток и путей:
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-rootВ качестве источника можно передавать адрес Git, SSH или путь к локальной папке. Флаг --sparse экономит трафик при сканировании репозитория.
Шаг 2. Проверяем список маркетплейсов
codex plugin marketplace listОжидаемый результат: в списке зарегистрированных источников отобразится добавленный адрес.
Другие команды управления маркетплейсами:
codex plugin marketplace upgrade # Обновление всех источников
codex plugin marketplace remove marketplace-name # Удаление источникаШаг 3. Установка плагина
Запустите сессию и откройте каталог:
codex
/pluginsОжидаемый результат: перейдите во вкладку добавленного маркетплейса, выберите плагин и нажмите Install plugin.
Шаг 4. Вызов плагина в новой сессии
Закройте текущий чат и откройте новую сессию (системное требование для применения плагинов). Отправьте запрос с явным вызовом по символу @:
@имя_плагинаОжидаемый результат: Codex запустит выполнение связанной с плагином логики (при наличии коннекторов выполните авторизацию по запросу на экране).
Если плагин не отвечает, проверьте, что вы открыли новую сессию после установки и прошли авторизацию коннекторов.
💡 Резюме одной фразой: регистрация маркетплейса выполняется через
codex plugin marketplace addв консоли, установка — через команду/pluginsв чате, вызов — строго в новой сессии через символ@.
06 Архитектура пакета плагина
Если вы захотите упаковать собственные наработки в плагин, вам нужно понимать его внутреннее устройство.
Для быстрого создания структуры плагина используйте встроенного помощника:
@plugin-creatorОн создаст файл манифеста .codex-plugin/plugin.json и настроит структуру папок для локальной отладки.
Манифест plugin.json содержит основные метаданные:
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}Ключ name задает системное имя плагина в формате kebab-case (например, my-first-plugin). Ключи skills, mcpServers, apps и hooks указывают пути к каталогам соответствующих компонентов относительно корня плагина.
Сводная таблица размещения файлов:
| Добавляемый компонент | Каталог размещения | Ключ в манифесте |
|---|---|---|
| Умение Skill | skills/[имя]/SKILL.md | skills |
| Хук жизненного цикла | hooks/hooks.json | hooks (по умолчанию можно опустить) |
| Конфигурация MCP | .mcp.json в корне плагина | mcpServers |
| Коннектор App | .app.json в корне плагина | apps |
| Графика и ресурсы | ./assets/ | Ссылки в ключе interface |
Структура папок готового плагина:
my-first-plugin/
├── .codex-plugin/
│ └── plugin.json ← Манифест (только этот файл хранится в папке)
├── skills/
│ └── hello/
│ └── SKILL.md
├── .mcp.json ← Конфигурация MCP в корне
├── .app.json ← Описание интеграции в корне
└── hooks/
└── hooks.json⚠️ Критически важное правило размещения файлов: папка
.codex-plugin/должна содержать только файл манифестаplugin.json. Каталоги умений, хуков и ресурсов должны располагаться в корне папки плагина. Смешивание файлов приведет к ошибкам загрузки компонентов.
Если ваши хуки размещены по умолчанию в hooks/hooks.json, вы можете не указывать ключ hooks в манифесте — Codex найдет их автоматически. Для публикации плагинов в общий доступ манифест расширяется параметрами описания авторов (author), лицензий (license) и ссылок на графику в ключе interface.
Структура плагина повторяет логику локальных умений и серверов MCP. Плагин просто объединяет эти файлы в одной папке для удобства переноса.
💡 Резюме одной фразой: плагин состоит из манифеста в папке
.codex-plugin/plugin.json(имя пишется в kebab-case) и каталогов компонентов в корне. Внутри.codex-plugin/должен лежать только файлplugin.json. Помощник@plugin-creatorавтоматизирует сборку шаблона.
07 Контроль безопасности: хуки требуют личного согласования
Пакетная установка плагина не означает автоматического одобрения всех скрытых в нем действий.
Плагины могут содержать фоновые сценарии автоматизации — хуки (Hooks), запускаемые по системным событиям (например, перед коммитом кода). В Codex реализовано жесткое правило безопасности: фоновые хуки плагинов отключены по умолчанию.
Установка или включение плагина не дает прав на запуск его хуков. Хуки плагинов относятся к категории неконтролируемых (non-managed) и автоматически пропускаются Codex до тех пор, пока пользователь лично не изучит их логику и не подтвердит доверие.
При первом срабатывании хука плагина Codex заблокирует выполнение задачи и выведет запрос на одобрение. Вы должны изучить код хука перед запуском. Подробнее работа хуков будет описана в главе 24.
Аналогия: подключение неизвестной умной колонки к домашней сети. Вы можете включить ее в розетку (плагин установлен, умения доступны), но для передачи аудиопотока в облако (запуск хука) вам нужно явно подтвердить разрешение на телефоне. Без этого колонка останется изолированной.
Правила проверки безопасности перед установкой сторонних плагинов:
| Проверка | Действие |
|---|---|
| Репутация источника | Доверяйте плагинам Curated и разработкам коллег. Относитесь с осторожностью к неизвестным Git-репозиториям |
| Содержимое пакета | Проверяйте описание на предмет наличия коннекторов API, MCP и фоновых хуков |
| Аудит хуков | При появлении системного запроса на доверие к хукам внимательно изучите логику выполнения перед одобрением |
Используйте встроенные механизмы защиты: изоляцию рабочих групп в ChatGPT, ручное подтверждение доверия к хукам и общие правила песочницы. Самостоятельно контролируйте источники загрузки плагинов. На момент релиза публикация плагинов в общем доступе находится на этапе тестирования, поэтому основными источниками служат репозитории маркетплейсов вашей команды.
💡 Резюме одной фразой: плагины переносят настройки MCP, API и хуков. В целях безопасности хуки плагина требуют личного подтверждения доверия со стороны пользователя перед запуском. Проверяйте сторонний код перед одобрением.
08 Итоги
Мы разобрали архитектуру плагинов в Codex, правила их установки, настройки безопасности и структуру манифестов для сборки собственных пакетов.
Повторим ключевые выводы:
| Задача | Инструмент | Ключевой нюанс |
|---|---|---|
| Понимание плагина | Объединение Skills, Apps и MCP в единый пакет | Skill для локальной отладки, плагин — для дистрибуции и версионирования |
| Поиск плагинов | Магазин плагинов | Разделы: Curated, Shared (коллеги), Created (собственные) |
| Установка | CLI / TUI / Настройки приложения | В консоли маркетплейс добавляется через codex plugin marketplace add |
| Вызов | Промпт или символ @ | Запуск строго в новой сессии после установки; коннекторы требуют OAuth |
| Отключение | Файл config.toml | Строка enabled = false в секции плагина с перезапуском сессии |
| Сборка плагина | Манифест и структура папок | В папке .codex-plugin хранится только plugin.json. Шаблон создается через @plugin-creator |
| Безопасность | Проверка прав доступа | Фоновые хуки не запускаются автоматически и требуют подтверждения |
Схема взаимодействия компонентов:
Схема показывает путь работы: сверху — процесс добавления маркетплейса, установки плагина и запуска в новой сессии. Снизу — состав пакета плагина (умения, коннекторы, серверы и хуки) с уровнями подтверждения прав доступа к ним.
Теперь вы умеете: выбирать правильный формат интеграции (Skill vs Plugin), осуществлять навигацию по каталогу плагинов и подключать маркетплейсы через CLI, вызывать плагины в сессиях, настраивать структуру каталогов плагина для самостоятельной сборки и контролировать доступы к фоновым хукам. Использование плагинов автоматизирует развертывание окружения разработки для всей команды.
Учитывайте особенности путей: манифест хранится в .codex-plugin/plugin.json, а сами файлы компонентов — в корневой директории плагина. Это исключит ошибки при сборке.
В следующей статье — [24 · Правила и хуки (Hooks)]. Мы упоминали хуки плагинов, требующие подтверждения. В следующей главе мы детально разберем их устройство: как настроить автоматический запуск скриптов проверки перед коммитами или при открытии сессий, переведя контроль за соблюдением стандартов разработки в автоматический режим.