Плагины

Навыки, MCP-серверы и хуки удобно настраивать для себя. Но когда их надо раздать десятку разработчиков и держать одинаковыми, ручное копирование папок и кусков config.toml перестаёт работать. Плагин (plugin) — это упаковка: набор возможностей, который ставится и обновляется одной операцией. Плагины появились в Codex в марте 2026 года, и документация рекомендует именно их для распространения своих навыков и интеграций.

Что внутри плагина

Плагин может содержать:

• навыки — те же каталоги с SKILL.md, что и в уроке про навыки;
• MCP-серверы — подключения к внешним системам, с уже прописанной аутентификацией;
• расширения браузера — если сценарию нужны возможности браузера;
• хуки — команды на событиях жизненного цикла Codex, о них будет отдельный урок.

Каталог плагинов общий у ChatGPT и Codex: один и тот же публичный плагин виден и в чатах ChatGPT, и в Codex. Внутри Codex плагины работают в режиме Codex десктопного приложения ChatGPT и в CLI. IDE-расширение плагины не поддерживает — для установки откройте десктоп или CLI.

Установка и использование

В десктопном приложении — вкладка Plugins: поиск, карточка плагина, кнопка установки. Если плагину нужно подключение к сервису, он попросит авторизоваться при установке или при первом использовании.

В CLI каталог открывается командой:

/plugins

Плагины сгруппированы по маркетплейсам; в карточке видно, что входит в плагин, установленный плагин включается и выключается пробелом. Есть и команды для скриптов, например codex plugin list; точный набор подкоманд проверьте в codex plugin --help.

Два правила, на которых часто спотыкаются:

1. После установки начните новую сессию. Навыки и инструменты плагина появляются в новых чатах, а не в текущем.
2. Плагин не даёт новых прав. Когда возможность плагина выполняется в Codex, действуют песочница и политика одобрений хоста. Внешние сервисы проверяют доступ по своим правилам: установка плагина GitLab не откроет проект, к которому у вас нет доступа.

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

Маркетплейсы: свой каталог для команды

Маркетплейс — это JSON-каталог плагинов. Кроме общего каталога, Codex читает локальные:

• $REPO_ROOT/.agents/plugins/marketplace.json — каталог репозитория;
• ~/.agents/plugins/marketplace.json — личный каталог.

Для агентства с несколькими проектами удобна схема: отдельный репозиторий agent-plugins с маркетплейсом и папками плагинов. Подключить его можно одной командой:

codex plugin marketplace add https://git.example.com/dev/agent-plugins.git --ref main
codex plugin marketplace list
codex plugin marketplace upgrade

Источником может быть сокращение owner/repo для GitHub, HTTPS- или SSH-адрес Git либо локальная папка. --ref фиксирует ветку или тег, --sparse PATH позволяет забрать из большого репозитория только нужную папку.

Сам маркетплейс выглядит так:

{
  "name": "agency",
  "interface": {
    "displayName": "Плагины команды"
  },
  "plugins": [
    {
      "name": "web-dev",
      "source": {
        "source": "local",
        "path": "./plugins/web-dev"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

source.path указывается относительно корня маркетплейса и начинается с ./. Поля policy.installation, policy.authentication и category обязательны для каждой записи. Плагин можно взять и из Git ("source": "git-subdir" с url, path и ref), и из npm-реестра.

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

[plugins."web-dev@agency"]
enabled = true

Ключ строится как имя-плагина@имя-маркетплейса. Как и всё в проектном config.toml, это читается только для доверенных проектов.

Собираем свой плагин

Самый быстрый путь — встроенный навык $plugin-creator: он создаёт каркас и может сразу добавить запись в локальный маркетплейс для проверки. Но полезно понимать формат.

Актуальный формат — переносимый пакет Agent Plugins: файл plugin.json в корне плагина, навыки в skills/, MCP-серверы в mcp.json.

plugins/web-dev/
├── plugin.json
├── mcp.json
└── skills/
    ├── mr-description/
    │   └── SKILL.md
    └── e2e-triage/
        └── SKILL.md

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "web-dev",
  "version": "0.1.0",
  "description": "Навыки и инструменты веб-команды: описание MR, разбор упавших e2e, документация."
}

Навыки из skills/ подхватываются без отдельного поля в манифесте. MCP-серверы в переносимом формате обязательно указывают тип транспорта:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "docs": {
      "type": "streamable-http",
      "url": "https://developers.openai.com/mcp"
    }
  }
}

Настройки, специфичные для OpenAI, — внешний вид в каталоге, привязки зарегистрированных MCP-серверов, хуки — кладутся в объект extensions.com.openai того же plugin.json. Старый вариант с файлом .codex-plugin/plugin.json по-прежнему поддерживается как запасной, и именно его пока генерирует $plugin-creator. Полное описание полей — в руководстве по сборке плагинов, рабочие примеры — в github.com/openai/plugins.

Плагины из локального маркетплейса ставятся в кэш ~/.codex/plugins/cache/, и Codex читает установленную копию, а не папку в репозитории. Поменяли файлы плагина — обновите маркетплейс и перезапустите клиент.

Политика для MCP-серверов плагина

Команду запуска MCP-сервера из плагина вы не задаёте — её задаёт плагин. Но включение и одобрения остаются под вашим контролем:

[plugins."web-dev@agency".mcp_servers.docs]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["search", "fetch"]

Названия инструментов здесь условные: смотрите их в /mcp после установки.

Перед установкой чужого плагина

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

• состав — какие навыки, MCP-серверы и хуки внутри;
• хуки — Codex не запустит хуки плагина, пока вы не просмотрите и не подтвердите их в /hooks, но подтверждать стоит только то, что вы прочитали;
• MCP-серверы — куда они ходят и с какими правами;
• источник — фиксируйте --ref на теге, а не на плавающей ветке.

В управляемых рабочих пространствах ChatGPT администраторы решают, какие плагины доступны участникам, и могут ограничить маркетплейсы разрешёнными источниками. Об этом — в курсе для техдиров.