Создание плагинов

Эта страница предназначена для авторов плагинов. Если вы хотите просматривать, устанавливать и использовать плагины в ChatGPT Work в веб-версии либо в ChatGPT Work или Codex в настольном приложении ChatGPT, см. раздел Плагины. Если вы всё ещё дорабатываете один репозиторий или один личный рабочий процесс, начните с локального навыка. Создавайте плагин, когда хотите предоставить этот рабочий процесс командам, включить в пакет коннекторы или конфигурацию MCP, добавить хуки жизненного цикла либо опубликовать стабильный пакет.

Плагин может включать навыки, приложение на основе MCP или и то и другое. Если вашему плагину необходимо подключаться к сервису или предоставлять инструменты через сервер MCP, см. раздел Создание приложения.

Полные общедоступные примеры можно найти в плагинах Figma, Notion и Build web apps.

Создание плагина с помощью `@plugin-creator`

Для максимально быстрой настройки используйте встроенный навык @plugin-creator.

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

Локальное создание и тестирование плагина, связанного с приложением в режиме разработки на основе сервера MCP

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

Сначала включите режим разработчика в ChatGPT:

Откройте ChatGPT.
Откройте Настройки.
Выберите Безопасность и вход.
Включите Режим разработчика.

Затем создайте приложение в режиме разработчика:

Откройте Настройки → Плагины или страницу плагинов.
Нажмите кнопку с плюсом.
Заполните форму в модальном окне, чтобы создать приложение в режиме разработчика для вашего сервера MCP.
После того как ChatGPT создаст его, скопируйте идентификатор приложения из URL в браузере. Он начинается с plugin_asdk_app.

Передайте этот идентификатор plugin_asdk_app... в @plugin-creator в чате ChatGPT Work или в $plugin-creator в Codex. Например, для ChatGPT Work:

  Запрос для Plugin Creator

@plugin-creator create a Codex plugin for my ChatGPT app.
Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.
Include a personal marketplace entry so I can test it locally.

Навык plugin-creator создаст папку плагина, обязательный файл .codex-plugin/plugin.json и подключение приложения ChatGPT. Если вы попросите его создать запись в личном маркетплейсе, плагин появится в вашем локальном источнике в каталоге плагинов для тестирования.

После того как навык plugin-creator создаст плагин:

Проверьте .app.json и убедитесь, что он указывает на правильный идентификатор plugin_asdk_app....
Проверьте .codex-plugin/plugin.json и убедитесь, что его поле apps указывает на ./.app.json.
Добавьте все включаемые в пакет навыки в skills/, если вместе с приложением плагин должен содержать повторяемые рабочие процессы.
Если навык создал запись в личном маркетплейсе, обновите ChatGPT, установите плагин из своего локального источника в каталоге плагинов, а затем протестируйте его в новом чате.

Формат манифеста и структуру файлов см. в разделах Структура плагина и Правила путей.

Создание собственного курируемого списка плагинов

Маркетплейс — это JSON-каталог плагинов. @plugin-creator может создать такой каталог для одного плагина, после чего вы можете добавлять новые записи в тот же маркетплейс, формируя собственный курируемый список для репозитория, команды или личного рабочего процесса.

В ChatGPT Work или Codex в настольном приложении ChatGPT каждый маркетплейс отображается как доступный для выбора источник в каталоге плагинов. Используйте $REPO_ROOT/.agents/plugins/marketplace.json для списка на уровне репозитория или ~/.agents/plugins/marketplace.json для личного списка. Добавьте по одной записи для каждого плагина в plugins[], задайте в каждом source.path путь к папке плагина с префиксом ./ относительно корня маркетплейса и установите для interface.displayName название, которое приложение должно отображать в списке выбора маркетплейса. Затем перезапустите настольное приложение ChatGPT. После этого откройте каталог плагинов, выберите свой маркетплейс и просматривайте или устанавливайте плагины из этого курируемого списка.

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

Пользовательский локальный маркетплейс в каталоге плагинов

Добавление маркетплейса через CLI

Используйте codex plugin marketplace add, чтобы добавить и отслеживать источник маркетплейса, не редактируя config.toml вручную. Эти команды предназначены для разработки плагинов и настройки каталогов. Для установки и тестирования локального плагина используйте настольное приложение ChatGPT.

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

Источниками маркетплейсов могут служить сокращённые ссылки GitHub (owner/repo или owner/repo@ref), URL Git по HTTP или HTTPS, URL Git по SSH либо локальные корневые каталоги маркетплейсов. Используйте --ref, чтобы закрепить ссылку Git, и указывайте --sparse PATH повторно, чтобы использовать разреженное извлечение для репозиториев маркетплейсов на основе Git. --sparse допустим только для источников маркетплейсов Git.

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

codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-name

codex plugin marketplace list выводит каждый маркетплейс, который учитывает Codex, и корневой путь, из которого он разрешается, включая локальные маркетплейсы по умолчанию и настроенные снимки маркетплейсов.

Создание плагина вручную

Начните с минимального плагина, содержащего один навык.

Создайте папку плагина с манифестом по пути .codex-plugin/plugin.json.

mkdir -p my-first-plugin/.codex-plugin

my-first-plugin/.codex-plugin/plugin.json

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

Используйте стабильный name плагина в kebab-case. Codex использует его как идентификатор плагина и пространство имён компонентов.

Добавьте навык в skills/<skill-name>/SKILL.md.

mkdir -p my-first-plugin/skills/hello

my-first-plugin/skills/hello/SKILL.md

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

Добавьте плагин в маркетплейс. Используйте @plugin-creator, чтобы создать маркетплейс, или следуйте инструкциям в разделе Создание собственного курируемого списка плагинов, чтобы вручную подключить плагин к Codex.

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

Установка локального плагина вручную

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

Репозиторий

Добавьте файл маркетплейса по пути `$REPO_ROOT/.agents/plugins/marketplace.json`
и храните плагины в `$REPO_ROOT/plugins/`.

**Пример маркетплейса репозитория**

Шаг 1. Скопируйте папку плагина в `$REPO_ROOT/plugins/my-plugin`.

mkdir -p ./plugins
cp -R /absolute/path/to/my-plugin ./plugins/my-plugin

Шаг 2. Добавьте или обновите `$REPO_ROOT/.agents/plugins/marketplace.json` так,
чтобы `source.path` указывал на каталог этого плагина относительным путём с префиксом `./`:

{
  "name": "local-repo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Шаг 3. Перезапустите настольное приложение ChatGPT и убедитесь, что плагин появился.

Личный

Добавьте файл маркетплейса по пути `~/.agents/plugins/marketplace.json` и храните
плагины в `~/.codex/plugins/`.

**Пример личного маркетплейса**

Шаг 1. Скопируйте папку плагина в `~/.codex/plugins/my-plugin`.

mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin

Шаг 2. Добавьте или обновите `~/.agents/plugins/marketplace.json` так, чтобы
`source.path` в записи плагина указывал на этот каталог.

Шаг 3. Перезапустите настольное приложение ChatGPT и убедитесь, что плагин появился.

Файл маркетплейса указывает на расположение плагина, поэтому эти каталоги — лишь примеры, а не обязательные требования. Codex разрешает source.path относительно корня маркетплейса, а не относительно папки .agents/plugins/. Формат файла см. в разделе Метаданные маркетплейса.

После изменения плагина обновите каталог плагина, на который указывает запись маркетплейса, и перезапустите настольное приложение ChatGPT, чтобы локальная установка получила новые файлы.

Предоставление локального плагина участникам рабочего пространства

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

Откройте Плагины в настольном приложении ChatGPT.
Перейдите в раздел Созданные вами и откройте страницу сведений о плагине.
Выберите Поделиться.
Добавьте участников или группы рабочего пространства либо скопируйте ссылку для предоставления доступа.
Выберите, кому предоставить доступ, а затем отправьте приглашение или ссылку.

Пользователи, которым вы предоставили доступ, найдут плагин в разделе Доступные вам каталога плагинов. Предоставление рабочему пространству доступа к локальному плагину не публикует его в общедоступном каталоге плагинов. Общие плагины остаются в пределах вашего рабочего пространства и организации; учётные записи, которые не выполнили вход в это рабочее пространство, не могут получить к ним доступ. Используйте группы, если одна и та же команда или роль должна иметь одинаковый доступ к плагину. Используйте маркетплейс для распространения через репозиторий или CLI, а общий доступ в рабочем пространстве — когда хотите, чтобы выбранные коллеги установили плагин из настольного приложения ChatGPT.

Администраторы рабочего пространства могут отключить общий доступ к плагинам с помощью централизованно управляемых требований, добавив features.plugin_sharing = false в requirements.toml:

features.plugin_sharing = false

Метаданные маркетплейса

Если вы поддерживаете маркетплейс репозитория, определите его в $REPO_ROOT/.agents/plugins/marketplace.json. Для личного маркетплейса используйте ~/.agents/plugins/marketplace.json. Файл маркетплейса управляет порядком плагинов и политиками установки в настольном приложении ChatGPT. На этапе тестирования он может представлять один плагин или курируемый список плагинов, которые приложение должно отображать вместе под одним названием маркетплейса. Прежде чем добавлять плагин в маркетплейс, убедитесь, что его version, метаданные издателя и текст для интерфейса установки готовы к просмотру другими разработчиками.

{
  "name": "local-example-plugins",
  "interface": {
    "displayName": "Local Example Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    },
    {
      "name": "research-helper",
      "source": {
        "source": "local",
        "path": "./plugins/research-helper"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Используйте name верхнего уровня для идентификации маркетплейса.
Используйте interface.displayName для названия маркетплейса, отображаемого в настольном приложении ChatGPT.
Добавьте по одному объекту для каждого плагина в plugins, чтобы сформировать курируемый список, который приложение отображает под названием этого маркетплейса.
Укажите в source.path каждой записи плагина каталог плагина, который должен загружать Codex. При установке из репозитория он часто находится в ./plugins/. Для персональных установок обычно используется шаблон ./.codex/plugins/<plugin-name>.
Путь source.path должен быть относительным к корню маркетплейса, начинаться с ./ и находиться внутри этого корня.
Для локальных записей source также может быть обычной строкой пути, например "./plugins/my-plugin".
Всегда включайте policy.installation, policy.authentication и category в каждую запись плагина.
Используйте такие значения policy.installation, как AVAILABLE, INSTALLED_BY_DEFAULT или NOT_AVAILABLE.
Используйте policy.authentication, чтобы определить, когда выполняется аутентификация: при установке или при первом использовании.

Маркетплейс определяет, откуда Codex загружает плагин. Локальный source.path может указывать на другое место, если ваш плагин находится за пределами этих примерных каталогов. Файл маркетплейса может находиться в репозитории, где вы разрабатываете плагин, или в отдельном репозитории маркетплейса, а один файл маркетплейса может указывать на один или несколько плагинов.

Записи маркетплейса также могут указывать на источники плагинов в Git. Используйте "source": "url", если плагин находится в корне репозитория, или "source": "git-subdir", если плагин находится в подкаталоге:

{
  "name": "remote-helper",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/codex-plugins.git",
    "path": "./plugins/remote-helper",
    "ref": "main"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

Записи с источниками в Git могут использовать селекторы ref или sha. Если Codex не удаётся разрешить источник записи маркетплейса, он пропускает эту запись плагина, не прерывая обработку всего маркетплейса.

Записи маркетплейса также позволяют установить плагин из реестра пакетов JavaScript:

{
  "name": "npm-helper",
  "source": {
    "source": "npm",
    "package": "@example/codex-plugin",
    "version": "^1.2.0",
    "registry": "https://registry.npmjs.org"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

package является обязательным и может включать область реестра. version является необязательным и принимает версии пакетов, теги дистрибутивов и диапазоны версий, но не селекторы путей или URL. registry является необязательным и должен быть HTTPS URL без встроенных учётных данных, строки запроса или фрагмента. Codex скачивает пакет без запуска скриптов жизненного цикла. CLI npm должен быть установлен, а аутентификация в реестре выполняется на основе его конфигурации.

Как настольное приложение ChatGPT использует маркетплейсы

Маркетплейс плагинов — это каталог плагинов в формате JSON, который настольное приложение ChatGPT может читать и использовать для установки.

Приложение может читать файлы маркетплейсов из следующих источников:

курируемый маркетплейс, на основе которого работает официальный каталог плагинов
маркетплейс репозитория в $REPO_ROOT/.agents/plugins/marketplace.json
маркетплейс с поддержкой устаревшего формата в $REPO_ROOT/.claude-plugin/marketplace.json
персональный маркетплейс в ~/.agents/plugins/marketplace.json

Вы можете установить любой плагин, доступный через маркетплейс. Приложение устанавливает плагины в ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. Для локальных плагинов $VERSION имеет значение local, и приложение загружает установленную копию из этого пути кеша, а не непосредственно из записи маркетплейса.

Каждый плагин можно включать или отключать отдельно. Приложение хранит состояние включения или отключения каждого плагина в ~/.codex/config.toml.

Упаковка и распространение плагинов

Структура плагина

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

my-plugin/
├── .codex-plugin/
│   └── plugin.json       # Required: plugin manifest
├── skills/
│   └── my-skill/
│       └── SKILL.md      # Optional: skill instructions
├── hooks/
│   └── hooks.json        # Optional: lifecycle hooks
├── .app.json             # Optional: app or connector mappings
├── .mcp.json             # Optional: MCP server configuration
└── assets/               # Optional: icons, logos, screenshots

В .codex-plugin/ должен находиться только plugin.json. Храните skills/, hooks/, assets/, .mcp.json и .app.json в корне плагина.

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

Идентифицирует плагин.
Указывает на встроенные компоненты, такие как навыки, коннекторы, серверы MCP или обработчики.
Предоставляет метаданные для интерфейсов установки, такие как описания, значки и юридические ссылки.

Ниже приведён полный пример манифеста:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Bundle reusable skills and connectors.",
  "author": {
    "name": "Your team",
    "email": "team@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/plugins/my-plugin",
  "repository": "https://github.com/example/my-plugin",
  "license": "MIT",
  "keywords": ["research", "crm"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "hooks": "./hooks/hooks.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Reusable skills and connectors",
    "longDescription": "Distribute skills and connectors together.",
    "developerName": "Your team",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "websiteURL": "https://example.com",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": [
      "Use My Plugin to summarize new CRM notes.",
      "Use My Plugin to triage new customer follow-ups."
    ],
    "brandColor": "#10A37F",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": ["./assets/screenshot-1.png"]
  }
}

.codex-plugin/plugin.json — обязательная точка входа. Остальные поля манифеста необязательны, но часто используются в опубликованных плагинах.

Поля манифеста

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

name, version и description идентифицируют плагин.
author, homepage, repository, license и keywords предоставляют метаданные издателя и обнаружения.
skills, mcpServers, apps и hooks указывают на встроенные компоненты относительно корня плагина.
interface определяет, как интерфейсы установки представляют плагин.

Используйте объект interface для метаданных интерфейсов установки:

displayName, shortDescription и longDescription определяют название и текст описания.
developerName, category и capabilities добавляют метаданные издателя и возможностей.
websiteURL, privacyPolicyURL и termsOfServiceURL предоставляют внешние ссылки.
defaultPrompt, brandColor, composerIcon, logo и screenshots определяют начальные запросы и визуальное представление.

Правила для путей

Пути в манифесте должны быть относительными к корню плагина и начинаться с ./.
По возможности храните визуальные ресурсы, такие как composerIcon, logo и screenshots, в ./assets/.
Используйте skills для каталогов встроенных навыков, apps для .app.json, mcpServers для .mcp.json и hooks для обработчиков жизненного цикла.
Включённые плагины могут содержать обработчики жизненного цикла наряду с навыками, серверами MCP и коннекторами.
Если ваш плагин хранит обработчики в ./hooks/hooks.json, запись hooks в .codex-plugin/plugin.json не нужна: Codex автоматически проверяет этот файл по умолчанию.

Встроенные серверы MCP и обработчики жизненного цикла

mcpServers может указывать на файл .mcp.json, содержащий либо непосредственную карту серверов, либо объект-обёртку mcp_servers.

Непосредственная карта серверов:

{
  "docs": {
    "command": "docs-mcp",
    "args": ["--stdio"]
  }
}

Карта серверов в обёртке:

{
  "mcp_servers": {
    "docs": {
      "command": "docs-mcp",
      "args": ["--stdio"]
    }
  }
}

После установки пользователи могут включать или отключать встроенный сервер MCP и настраивать политику подтверждения инструментов через конфигурацию Codex, не редактируя плагин. Используйте plugins.<plugin>.mcp_servers.<server> для политики сервера MCP в области плагина:

[plugins."my-plugin".mcp_servers.docs]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["search"]

[plugins."my-plugin".mcp_servers.docs.tools.search]
approval_mode = "approve"

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

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

Файл обработчиков плагина по умолчанию — hooks/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${PLUGIN_ROOT}/hooks/session_start.py",
            "statusMessage": "Loading plugin context"
          }
        ]
      }
    ]
  }
}

Если вы определите hooks в .codex-plugin/plugin.json, Codex будет использовать эту запись манифеста вместо стандартного hooks/hooks.json. Поле манифеста может содержать один путь, массив путей, встроенный объект обработчиков или массив встроенных объектов обработчиков.

{
  "name": "repo-policy",
  "hooks": ["./hooks/session.json", "./hooks/tools.json"]
}

Пути обработчиков подчиняются тем же правилам путей манифеста, что и skills, apps и mcpServers: они должны начинаться с ./, разрешаться относительно корня плагина и оставаться внутри корня плагина.

Команды обработчиков плагина получают специальные переменные среды Codex PLUGIN_ROOT и PLUGIN_DATA. PLUGIN_ROOT указывает на корень установленного плагина, а PLUGIN_DATA — на доступный для записи каталог данных плагина. Codex также задаёт CLAUDE_PLUGIN_ROOT и CLAUDE_PLUGIN_DATA для совместимости с существующими обработчиками плагинов.

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

Публикация официальных общедоступных плагинов

Чтобы опубликовать плагин для общего доступа, отправьте его через портал подачи плагинов. Полный процесс проверки и публикации описан в разделе Отправка плагинов.

Недавние запросы

Рекомендуемые запросы

Навигация по документации

Создание плагина с помощью `@plugin-creator`

Локальное создание и тестирование плагина, связанного с приложением в режиме разработки на основе сервера MCP

Создание собственного курируемого списка плагинов

Добавление маркетплейса через CLI

Создание плагина вручную

Установка локального плагина вручную

Репозиторий

Личный

Предоставление локального плагина участникам рабочего пространства

Метаданные маркетплейса

Как настольное приложение ChatGPT использует маркетплейсы

Упаковка и распространение плагинов

Структура плагина

Поля манифеста

Правила для путей

Встроенные серверы MCP и обработчики жизненного цикла

Публикация официальных общедоступных плагинов

Создание плагина с помощью @plugin-creator

Локальное создание и тестирование плагина, связанного с приложением в режиме разработки на основе сервера MCP

Создание собственного курируемого списка плагинов

Добавление маркетплейса через CLI

Создание плагина вручную

Установка локального плагина вручную

Репозиторий

Личный

Предоставление локального плагина участникам рабочего пространства

Метаданные маркетплейса

Как настольное приложение ChatGPT использует маркетплейсы

Упаковка и распространение плагинов

Структура плагина

Поля манифеста

Правила для путей

Встроенные серверы MCP и обработчики жизненного цикла

Публикация официальных общедоступных плагинов

Создание плагина с помощью `@plugin-creator`