> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Справочник по загрузке плагинов
> Отследите, откуда Claude Code загружает каждый плагин, какой файл параметров решает, загружается ли он, и почему обновление ничего не изменило.
Используйте эту страницу, когда плагин не загрузился, загрузилась другая копия, чем вы ожидали, или плагин не подхватил обновление, и вы хотите увидеть, какой источник, область параметров или файл на диске это решил. На ней приведены правила, которые Claude Code применяет при запуске сеанса и каждый раз при запуске `/reload-plugins`. Вы также можете попросить Claude прочитать эту страницу и диагностировать вашу конфигурацию.
Эти случаи рассмотрены на других страницах:
* **Шаги установки, включения, отключения и обновления**: см. [Установка и управление плагинами](/docs/ru/plugins/install)
* **У вас есть конкретное сообщение об ошибке**: см. [Устранение неполадок плагинов](/docs/ru/plugins/troubleshooting)
Начните с раздела [Проверьте, на каком этапе находится плагин](#check-which-stage-a-plugin-reached) для трёх этапов, через которые проходит установленный плагин, или перейдите в раздел, соответствующий тому, что вы видите:
* Плагин, который вы отключили, всё ещё загружается: [Найдите, где плагин включен](#find-where-a-plugin-is-enabled)
* Обновление ничего не изменило: [Версии и обновления](#versions-and-updates)
* Вы смотрите на файлы в `~/.claude/plugins/`: [Найдите плагины на диске](#find-plugins-on-disk)
* Плагин `--plugin-dir` не загрузился, или вместо него загрузился плагин с тем же именем: [Конфликты имён](#name-conflicts)
Проверьте, на каком этапе находится плагин
Запись `enabledPlugins` становится плагином, который вы можете использовать, в несколько этапов: ваши параметры объявляют его, Claude Code загружает его на диск, и работающий сеанс загружает его. Когда плагин ведёт себя не так, как предполагает файл параметров, проверьте, на каком этапе он находится:
* **Объявлен в параметрах**: `enabledPlugins` указывает, какие плагины должны быть включены, а `extraKnownMarketplaces` указывает, какие маркетплейсы должны существовать. Когда вы запускаете `claude plugin marketplace add`, Claude Code записывает маркетплейс в `extraKnownMarketplaces` в ваши пользовательские параметры, а также на диск
* **Загружен на диск в `~/.claude/plugins/`**: записи о том, что Claude Code загрузил, и сами загруженные файлы:
* `known_marketplaces.json` записывает каждый маркетплейс, который Claude Code загрузил, с его `source`, `installLocation`, `lastUpdated` и `autoUpdate`. На одного пользователя приходится один `known_marketplaces.json`, поэтому маркетплейс, который вы добавляете в одном проекте, доступен в каждом проекте
* `installed_plugins.json` записывает каждую установку с её `scope`, `installPath` и `version`
* `cache/` содержит файлы плагинов
* **Загружен в работающем сеансе**: набор плагинов, который Claude Code загрузил при запуске или при последнем `/reload-plugins`. Изменения параметров или диска не достигают этого уровня до тех пор, пока вы не запустите `/reload-plugins` или не начнёте новый сеанс. Вот почему `claude plugin update` заканчивается на `Restart to apply changes.` и фоновые обновления предлагают вам `Run /reload-plugins to apply`
Плагины и маркетплейсы, которых нет на диске при запуске сеанса
Плагины загружаются при запуске сеанса из `installed_plugins.json` и кэша без использования сети. После запуска сеанса Claude Code проверяет объявленные маркетплейсы в фоновом режиме:
* **Маркетплейс, который параметры объявляют, но `known_marketplaces.json` не содержит**: Claude Code клонирует его, затем перезагружает плагины и загружает включённые плагины, которые ещё не кэшированы
* **Объявленный маркетплейс, чей источник изменился в параметрах**: Claude Code повторно загружает его из нового источника и показывает `Plugins changed. Run /reload-plugins to activate.`
Включённый плагин, который ни один путь не загрузил и у которого нет пригодного для использования каталога кэша, показывает `Plugin "" not cached at ` на вкладке `/plugin` **Errors**, и `claude plugin list` добавляет `— run /plugin to refresh` на ту же строку. Для исправления см. [`Plugin "" not cached at `](/docs/ru/plugins/troubleshooting#plugin-not-cached-at).
Найдите, откуда пришёл плагин
Каждый плагин имеет идентификатор вида `@`, который вы видите в файлах параметров и в `claude plugin list --json`. Часть после `@` говорит вам, где Claude Code нашёл плагин:
| ID заканчивается на | Как плагин туда попал | Как вы его включаете или отключаете |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@` | Вы установили его из маркетплейса, который добавили | `"@": true` или `false` под `enabledPlugins` в файле параметров |
| `@inline` | Вы запустили Claude Code с `--plugin-dir` или `--plugin-url`, установили [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/ru/env-vars#variables), или приложение Agent SDK передало опцию `plugins`. Он загружается только для этого сеанса | Включен для сеанса, если только манифест не устанавливает `defaultEnabled: false` или файл параметров не устанавливает `"@inline": false` |
| `@skills-dir` | Вы сохранили каталог плагина, который имеет `.claude-plugin/plugin.json` в `~/.claude/skills/` или в `.claude/skills/` проекта | `defaultEnabled` манифеста, если только файл параметров не устанавливает `"@skills-dir"` в `true` или `false` |
| `@synced` | Вы или ваша организация включили его для вашей учётной записи claude.ai, и Claude Code [загрузил его](#synced-plugins) | Включен, если только манифест не устанавливает `defaultEnabled: false` или файл параметров не устанавливает `"@synced": false`. Плагин, который ваша организация отмечает как обязательный, загружается в любом случае |
Для плагина маркетплейса `` — это имя записи в `marketplace.json`; для `@inline` и `@skills-dir` это `name` в манифесте плагина.
Имена источников в этой таблице зарезервированы, поэтому ни один маркетплейс не может быть назван `inline`, `skills-dir` или `synced`.
Имя записи и имя манифеста
Плагин маркетплейса имеет два имени, и они могут отличаться:
* **Имя записи в `marketplace.json`**: ключ установки и включения. Это то, что вы пишете в `enabledPlugins`, по чему назван каталог кэша, и что показывает `claude plugin list`
* **`name` в манифесте**: то, под чем пространства имён компонентов плагина, и что сравнивают [конфликты имён](#name-conflicts)
Плагины, общие через репозиторий
Чтобы поделиться плагином через репозиторий, перечислите его под `enabledPlugins` в `.claude/settings.json` или поместите его в `.claude/skills/`. Claude Code не сканирует каталог `.claude/plugins/` проекта.
Облачный сеанс не добавляет маркетплейсы, которые репозиторий перечисляет под [`extraKnownMarketplaces`](/docs/ru/settings-reference#extraknownmarketplaces), потому что это требует диалога доверия рабочей области, который облачный сеанс никогда не показывает.
Плагин каталога навыков с областью проекта загружается только из `.claude/skills/` [основного рабочего каталога](/docs/ru/permissions#working-directories) сеанса и только после того, как вы примете [диалог доверия рабочей области](/docs/ru/permissions#what-runs-before-you-trust-a-folder) для этого каталога. Он не [ищет родительские каталоги вверх до корня репозитория](/docs/ru/skills#discovery-from-parent-and-nested-directories) так, как это делают обычные навыки и команды. Если вы запустите из подкаталога, плагин в корне репозитория не загрузится. Запустите из корня репозитория вместо этого, или [переместите сеанс туда с помощью `/cd`](/docs/ru/permissions#move-the-session-to-another-directory) на v2.1.246 или позже.
Плагин с областью проекта проверяется в репозиторий и достигает каждого сотрудника, который его клонирует. Поскольку это содержимое поступает из репозитория, а не от вас, оно загружается только после той же проверки доверия, которая применяется к правилам разрешения проекта в `.claude/settings.json`. Доверие к родительской папке или запуск с `-p` недостаточно. Компоненты, которые выполняют код, имеют дополнительные ограничения:
* MCP серверы, которые он объявляет, проходят через [то же одобрение для каждого сервера](/docs/ru/mcp), что и проект `.mcp.json`
* MCP серверы, которые он объявляет как [MCP пакет](/docs/ru/plugins/manifest-reference#mcpservers), файл `.mcpb` или `.dxt`, или из файла вне каталога плагина, пропускаются. Объявляйте их встроенными или в `.mcp.json` внутри каталога плагина
* [Фоновые мониторы](/docs/ru/plugins/components#monitors) не загружаются
Плагины с областью пользователя не имеют этих ограничений.
О том, как писать плагины `--plugin-dir` и каталога навыков, см. [Создание плагинов](/docs/ru/plugins/create).
Плагины, синхронизированные с claude.ai
Плагин, который вы включаете для своей учётной записи claude.ai, также загружается в Claude Code рядом с плагинами, которые вы устанавливаете из маркетплейсов. Это включает плагины, которые ваша организация включает для своих членов. Каждый из этих плагинов загружается как `@synced`, без маркетплейса и без [записи об установке](#check-which-stage-a-plugin-reached).
В сеансах терминала навыки, агенты, hooks, MCP серверы и LSP серверы синхронизированного плагина все загружаются с тем же доверием, что и плагин маркетплейса, который вы установили.
О компонентах, которые загружает Cowork, см. [Плагины на claude.ai и в Cowork](https://claude.com/docs/plugins/overview) на claude.com.
Синхронизированные плагины загружаются в сеансах Cowork и в сеансах терминала, где вы входите с помощью своей учётной записи claude.ai:
* **[Cowork](https://claude.com/product/cowork)**: Claude Code загружает их в собственную среду сеанса при запуске сеанса
* **Сеансы терминала**: каждый раз, когда вы запускаете Claude Code, он синхронизируется один раз в фоновом режиме, загружая новые и обновлённые плагины и удаляя те, которые вы или ваша организация отключили. Синхронизация в сеансах терминала требует Claude Code v2.1.273 или позже
Время синхронизации в сеансах терминала
Поскольку синхронизация терминала выполняется в фоновом режиме, она может завершиться после запуска вашего сеанса. Когда она добавляет, обновляет или удаляет синхронизированный плагин в интерактивном сеансе, вы видите `Plugins changed. Run /reload-plugins to activate.` Запустите `/reload-plugins`, чтобы загрузить изменение в этом сеансе, или оставьте его на следующий раз, когда вы запустите Claude Code.
Если вы включите плагин на claude.ai во время работы сеанса, плагин загрузится в следующий раз, когда вы запустите Claude Code.
Требования входа для синхронизации терминала
В вашем терминале плагины синхронизируются только в сеансах, где вы входите с помощью своей учётной записи claude.ai.
Если вы вошли в более ранней версии Claude Code, этот вход не охватывает плагины до тех пор, пока Claude Code не обновит его в фоновом режиме. Чтобы получить доступ раньше, запустите `/login` снова. Синхронизация плагинов затем начнётся в следующий раз, когда вы запустите Claude Code.
Контролируйте, какие синхронизированные плагины загружаются
Вы можете отключить синхронизированные плагины по одному, кроме плагина, который требует ваша организация, или отключить все синхронизированные плагины на машине:
* **Один плагин**: `claude plugin disable @synced` в вашей оболочке и вкладка `/plugin` **Installed** в сеансе оба сохраняют `"@synced": false` в вашем пользовательском уровне [`enabledPlugins`](/docs/ru/settings-reference#enabledplugins). Чтобы держать плагин вне проекта в каждой среде, установите тот же ключ в коммитированный `.claude/settings.json` проекта
* **Все синхронизированные плагины на машине**: установите [`syncClaudeAiPlugins`](/docs/ru/settings-reference#syncclaudeaiplugins) в `false` в ваших пользовательских параметрах, или ваша организация устанавливает это в [управляемых параметрах](/docs/ru/managed-settings). Claude Code прекращает загрузку, и в следующий раз, когда вы его запустите, он перемещает плагины, которые он уже синхронизировал, в `~/.claude/plugins/.trash/` и больше их не загружает. Если ваша организация отключит Skills на claude.ai, плагины также перестанут синхронизироваться
* **Плагин, который требует ваша организация**: плагин, который ваша организация отмечает как обязательный на claude.ai, загружается даже если вы его отключили ранее. `claude plugin disable` отказывает ему с `Plugin "@synced" is required by your organization and can't be disabled here. Contact your admin to change it.`, и `claude plugin list` отмечает его `required by your org`
О удалении плагина на claude.ai см. [Управление установленными плагинами](/docs/ru/plugins/install#manage-installed-plugins).
Найдите, где плагин включен
Вы можете установить запись `enabledPlugins` в любом из шести источников. Таблица перечисляет их от самого низкого приоритета к самому высокому и указывает, к кому применяется каждый. Для самих файлов параметров см. [Файлы параметров и кто они затрагивают](/docs/ru/settings#where-settings-live).
| Источник | Где вы его устанавливаете | Достигает |
| :---------- | :------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--add-dir` | `.claude/settings.json` или `.claude/settings.local.json` в каталоге, который вы передаёте с `--add-dir` | Только этот сеанс. Только значение `true` имеет эффект, и каждый другой источник его переопределяет |
| `user` | `~/.claude/settings.json` | Вас, в каждом проекте |
| `project` | `.claude/settings.json` | Каждого, кто клонирует репозиторий |
| `local` | `.claude/settings.local.json` | Вас, только в этом репозитории |
| `flag` | Значение `--settings`, которое вы передаёте при запуске | Только этот сеанс |
| `managed` | [Управляемые параметры](/docs/ru/managed-settings) | Каждого пользователя, который охватывает политика. `true` принудительно включает и `false` блокирует, и ни один другой источник их не переопределяет |
Эти источники объединяются ключ за ключом. Для каждого идентификатора плагина применяемое значение — это значение из источника с наивысшим приоритетом, который упоминает идентификатор. Источник, который не упоминает идентификатор, оставляет значение из источника с более низким приоритетом в силе.
Отключено в пользовательских параметрах, но всё ещё загружается
Если вы установили плагин в `false` в `~/.claude/settings.json` и он всё ещё загружается, `true` в источнике с более высоким приоритетом его переопределяет. Строка плагина в `claude plugin list` и в `/plugin` показывает `Disabled in ~/.claude/settings.json but still loads — project settings enable it, which overrides your user setting`. Сообщение называет источник, который вас переопределил: `project`, `project, gitignored` для `.claude/settings.local.json`, `cli flag`, или `managed`.
Чтобы отказаться от плагина, включённого проектом, на вашей машине, установите идентификатор в `false` в `.claude/settings.local.json`, который имеет более высокий приоритет, чем файл проекта.
Включено в параметрах проекта, но не установлено
Когда единственный `true` плагина находится в `.claude/settings.json` проекта, Claude Code не загружает его на машину, где он не установлен, если только его запись маркетплейса не имеет [источника с относительным путём](/docs/ru/plugins/marketplace-reference#plugin-sources) или [каталог семян](/docs/ru/plugins/org#seed-containers-and-ci) уже его содержит. Вместо этого вкладка `/plugin` **Errors** показывает `Plugin "" is enabled in project settings but isn't installed here`.
Плагин с относительным путём не нуждается в записи об установке, потому что он загружается из самого маркетплейса.
Claude Code загружает плагин с внешним источником только когда один из этих источников устанавливает его в `true`:
* Ваши пользовательские параметры
* `.claude/settings.local.json`, который git не отслеживает
* Флаг `--settings`
* Управляемые параметры
Найдите плагины на диске
Claude Code хранит файлы плагинов и записи состояния в одном корне плагинов, который является `~/.claude/plugins`, если вы не установили [`CLAUDE_CODE_PLUGIN_CACHE_DIR`](/docs/ru/env-vars). Каждый путь в таблице относителен к этому корню.
| Путь | Что он содержит |
| :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cache////` | Один каталог на установленную версию плагина маркетплейса. `` — это имя записи маркетплейса и `` — это [разрешённая версия](#versions-and-updates). `${CLAUDE_PLUGIN_ROOT}` указывает на этот каталог |
| `data//` | Постоянный каталог плагина, открытый как `${CLAUDE_PLUGIN_DATA}`. О том, как формируется ``, см. [Переменные пути и постоянные данные](/docs/ru/plugins/components#path-variables-and-persistent-data). Claude Code создаёт его, когда компонент плагина впервые его использует, и сохраняет его при обновлениях. Claude Code удаляет его, когда вы удаляете плагин из его последней области, если вы не передаёте `--keep-data` |
| `marketplaces//` | Клон или загрузка маркетплейса, добавленного с GitHub, другого хоста Git или URL. Маркетплейс, добавленный из локального источника `file` или `directory`, не имеет копии здесь, и его `installLocation` в `known_marketplaces.json` — это путь, который вы дали |
| `synced/` | Плагины, которые Claude Code [синхронизировал с вашей учётной записью claude.ai](#synced-plugins) |
| `.trash/` | Плагины, которые синхронизация claude.ai удалила, например, после того как вы отключили один на claude.ai или прекратили синхронизацию |
| `installed_plugins.json` и `known_marketplaces.json` | Записи о том, что Claude Code установил и какие маркетплейсы он загрузил, описанные в разделе [Проверьте, на каком этапе находится плагин](#check-which-stage-a-plugin-reached). [Маркетплейс, размещённый на claude.ai](/docs/ru/plugins/install#add-from-claude-ai), записывается в `known_marketplaces_claudeai.json` вместо этого |
| `flagged-plugins.json` | Плагины, которые Claude Code удалил, потому что их маркетплейс их исключил. Они появляются в разделе **Flagged** в `/plugin`; см. [Размещение маркетплейса](/docs/ru/plugins/host-marketplace) |
Поскольку `${CLAUDE_PLUGIN_ROOT}` указывает на каталог версии, путь корня плагина изменяется с каждой версией. Сохраняйте постоянные файлы плагина в `${CLAUDE_PLUGIN_DATA}` вместо этого.
Плагины на месте и скопированные плагины
Claude Code загружает некоторые плагины на месте из того места, где вы их храните, и копирует остальные в кэш, в соответствии с их источником:
* **Плагины `--plugin-dir` и каталога навыков**: каталог загружается на месте и никогда не копируется. Архив `--plugin-url` или `.zip` `--plugin-dir` сначала извлекается во временный каталог сеанса
* **Плагины с относительным путём в маркетплейсе, который вы добавили из локального каталога**: плагин загружается на месте из его пути внутри папки маркетплейса. Ваши правки в исходный каталог вступают в силу при следующем запуске сеанса или `/reload-plugins`, и вам не нужно увеличивать версию. Процессы hooks плагина и серверы MCP и LSP получают `CLAUDE_PLUGIN_ROOT`, который указывает на исходный каталог. О его зависимостях пакета Node.js см. [Когда запускается установка зависимостей](#when-the-dependency-install-runs)
* **Плагины источника `command` в [режиме ссылки](/docs/ru/plugins/marketplace-reference#command-plugin-source)**: каталог, который напечатала команда, загружается на месте через ссылки в записи кэша
* **Каждый другой плагин маркетплейса**: Claude Code копирует плагин в `cache////` при установке и загружает эту копию. Файлы вне каталога плагина не копируются, поэтому когда скрипт внутри скопированного плагина читает путь выше корня плагина, такой как `../shared`, он их не находит
Пути, которые выходят за пределы каталога плагина
Загружается ли плагин на месте или из кэшированной копии, Claude Code не позволяет ему объявлять компоненты вне его собственного каталога. Он отклоняет путь компонента, который разрешается вне корня плагина, независимо от того, объявлен ли путь в `plugin.json` или в записи маркетплейса:
* **Путь, который указывает вне плагина в написанном виде**, такой как `../shared-utils`
* **Символическая ссылка, которая ведёт вне плагина**, кроме [ссылок между плагинами в одном маркетплейсе](/docs/ru/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)
* **На macOS и Linux, путь, который содержит обратную косую черту где-либо в нём**, даже когда путь остаётся внутри плагина. Компоненты, объявленные с путями обратной косой черты, поэтому загружаются только на Windows, поэтому пишите пути компонентов с прямыми косыми чертами, такие как `./commands/deploy.md`
Отклонённый путь появляется как ошибка [`path escapes plugin directory`](/docs/ru/errors#path-escapes-plugin-directory), и плагин загружается без этого компонента.
Очистка предыдущих версий
Когда вы обновляете или удаляете плагин, Claude Code записывает маркер `.orphaned_at` в каталог предыдущей версии. Он удаляет этот каталог в фоновой очистке через 14 дней, поэтому сеанс, который уже загрузил старую версию, продолжает работать.
Очистка выполняется только пока `installed_plugins.json` записывает по крайней мере одну установку. После удаления последнего плагина осиротелые каталоги остаются до тех пор, пока вы не установите другой.
Зависимости пакета Node.js
Когда Claude Code копирует плагин в кэш, он также устанавливает зависимости пакета Node.js плагина там, поэтому hooks и MCP серверы плагина могут их загружать.
Этот раздел охватывает пакеты npm и Bun, которые плагин объявляет в своём собственном `package.json`. О плагинах, которые зависят от других плагинов, см. [версии зависимостей плагина](/docs/ru/plugins/dependencies).
Когда запускается установка зависимостей
Claude Code запускает установку внутри скопированного каталога версии каждый раз, когда создаёт один:
* Когда вы устанавливаете плагин
* Когда Claude Code обновляет плагин до новой версии
* При запуске сеанса, когда включённый плагин ещё не кэширован, например, на новой машине
Для плагина с относительным путём [загруженного на месте](#in-place-and-copied-plugins) из маркетплейса локального каталога Claude Code не устанавливает зависимости в исходный каталог. Установите их там сами, или из hook в [`${CLAUDE_PLUGIN_DATA}`](/docs/ru/plugins/components#path-variables-and-persistent-data).
Установка запускается только когда каталог корня плагина содержит как `package.json`, так и поддерживаемый файл блокировки. Файл блокировки решает, какую команду запускает Claude Code:
| Файл блокировки | Команда |
| :-------------------------------------------- | :----------------------------------------------- |
| `bun.lock` или `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
| `npm-shrinkwrap.json` или `package-lock.json` | `npm ci --ignore-scripts` |
Если плагин содержит более одного из этих файлов блокировки, Claude Code использует первое совпадение, проверяя по порядку: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`.
Claude Code пропускает установку для файлов блокировки Yarn и pnpm и для `bunfig.toml` рядом с файлом блокировки Bun:
* Если ваш плагин имеет только `yarn.lock` или `pnpm-lock.yaml`, замените его файлом блокировки npm
* Если `bunfig.toml` находится в том же каталоге, что и файл блокировки Bun, удалите `bunfig.toml`, или замените файл блокировки Bun файлом блокировки npm
Включите файл блокировки npm, чтобы достичь большинства пользователей. Claude Code запускает менеджер пакетов файла блокировки из PATH пользователя и не пытается использовать другой файл блокировки вместо этого, если этот менеджер пакетов отсутствует.
Для плагина, распространяемого через источник npm, используйте `npm-shrinkwrap.json`, потому что npm исключает `package-lock.json` из опубликованных пакетов.
Ограничения на установку зависимостей
Claude Code ограничивает эту установку зависимостей так, чтобы никакой код из плагина или его пакетов не выполнялся во время неё, и ограничивает, как долго она может выполняться:
* **Замороженное разрешение**: Bun и npm устанавливают ровно то, что файл блокировки закрепляет, и отказывают, а не переразрешают версии, когда `package.json` и файл блокировки не согласны
* **Нет скриптов жизненного цикла**: `--ignore-scripts` предотвращает запуск скриптов `preinstall`, `install` и `postinstall`, поэтому зависимости, которые собирают собственные модули в этих скриптах, загружаются, но не компилируются во время этой установки
* **Тайм-аут 60 секунд**: Claude Code останавливает установку, которая выполняется дольше, и рассматривает её как неудачную
Claude Code загружает плагин источника npm перед этой установкой зависимостей, и ни один из собственных скриптов установки пакета не запускается во время загрузки. См. [источник плагина npm](/docs/ru/plugins/marketplace-reference#npm-plugin-source).
Вы не можете отключить автоматическую установку. Ни один параметр или переменная окружения её не отключает.
В ограниченных сетях см. [требования доступа в сеть](/docs/ru/network-config#network-access-requirements) для хостов, которые нужно разрешить.
Когда установка зависимостей не удаётся или пропускается
Неудачная или пропущенная установка никогда не блокирует плагин, и каждый случай оставляет другой знак:
* Неудачная установка, или одна пропущенная из-за файла блокировки Yarn или pnpm или `bunfig.toml`, появляется как предупреждение в выводе `claude --debug`
* Плагин с `package.json` и без файла блокировки пропускается без записи в журнал
* Истёкшая по времени установка может оставить частичное дерево `node_modules` в кэшированной копии
Когда автоматическая установка не может предоставить зависимость, установите её из hook в [каталог постоянных данных](/docs/ru/plugins/components#path-variables-and-persistent-data). Это включает пакеты, которым нужны их скрипты жизненного цикла для сборки, зависимости Python и плагины, заблокированные Yarn или pnpm.
Версии и обновления
Если автор плагина отправил новые коммиты и `claude plugin update` печатает ` is already at the latest version ().`, версия, которую Claude Code вычисляет для плагина, не изменяется, поэтому ничего не изменяется на диске.
Claude Code вычисляет версию для каждого плагина, который он устанавливает, и эта версия — это то, как он обнаруживает обновление. `claude plugin update` и фоновое автоматическое обновление вычисляют версию снова и пропускают плагин, когда она совпадает с тем, что записывает `installed_plugins.json`.
Версия также называет каталог кэша плагина.
Манифест, который закрепляет `"version"`, — это один способ, которым вычисленная версия остаётся неизменной при коммитах. См. [Как Claude Code вычисляет версию](#how-claude-code-computes-the-version) для порядка разрешения.
Плагин [загруженный на месте](#in-place-and-copied-plugins) из маркетплейса локального каталога загружает свои текущие исходные файлы при каждом запуске сеанса, независимо от того, что говорит его строка версии. Для плагина из [маркетплейса, размещённого на claude.ai](/docs/ru/plugins/install#add-from-claude-ai), версия, которую claude.ai записывает для плагина, — это его версия, и `version` манифеста не читается.
Как Claude Code вычисляет версию
Для маркетплейса, который вы добавили по источнику, Claude Code выбирает правило по типу `source` записи маркетплейса плагина. [Справочник маркетплейса](/docs/ru/plugins/marketplace-reference#plugin-sources) перечисляет типы источников. Для каждого типа источника в этом списке, кроме `command`:
1. Поле `version` в манифесте плагина идёт первым
2. Затем поле `version` в записи маркетплейса плагина
3. Когда ни один не установлен, версия поступает из типа источника:
| Тип источника | Версия, когда поле `version` не установлено |
| :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `github`, `url` или `git-subdir` | SHA коммита источника, сокращённый до 12 символов. Версия `git-subdir` также содержит хэш пути подкаталога |
| `archive` | Дайджест SHA-256, сокращённый до 12 символов: закрепление `sha256` в записи маркетплейса, или дайджест загруженного файла, когда нет закрепления |
| Относительный путь внутри маркетплейса, размещённого на Git | SHA коммита установленного каталога |
| Локальный каталог, когда ни каталог плагина, ни его маркетплейс не являются репозиторием git | `unknown` |
| `npm` | `unknown` |
Claude Code не берёт версию из репозитория, который охватывает путь установки, такого как управляемый git `~/.claude`.
Для источника `command` Claude Code всегда выводит версию из того, что произвела команда: 12-символьный хэш сам по себе, или `-`, когда манифест устанавливает один. `version` записи маркетплейса игнорируется для источников команд. О том, что охватывает хэш, см. [Режим копирования и режим ссылки](/docs/ru/plugins/marketplace-reference#copy-mode-and-link-mode).
Поскольку манифест идёт первым, манифест, который закрепляет `"version": "1.0.0"`, держит каждого пользователя на кэшированной копии до тех пор, пока его автор не изменит строку, сколько бы коммитов они ни отправили. Чтобы позволить пользователям отслеживать коммиты вместо этого, оставьте `version` вне манифеста и записи. [Размещение маркетплейса](/docs/ru/plugins/host-marketplace) охватывает, какой выбор подходит для какой установки выпуска.
Когда Claude Code обновляет маркетплейс перед установкой
Когда вы устанавливаете плагин, Claude Code ищет его в своей локальной копии каталога маркетплейса. Вы можете запустить `/plugin install` в сеансе или `claude plugin install` в вашей оболочке и назвать плагин с его маркетплейсом или без. Таблица показывает, какие из этих комбинаций обновляют локальную копию.
| Имя плагина | Команда | Что Claude Code обновляет |
| :----------------- | :-------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| `name@marketplace` | `/plugin install` или `claude plugin install` | Названный маркетплейс перед поиском |
| `name` один | `/plugin install` | Только маркетплейсы, у которых автоматическое обновление включено, и только после того, как поиск не найдёт |
| `name` один | `claude plugin install` | Ничего. Он читает кэшированные каталоги без обновления |
Обновление перед установкой `name@marketplace` не зависит от параметра автоматического обновления маркетплейса или от `DISABLE_AUTOUPDATER`.
Когда обновление не удаётся, установка продолжается из кэшированного каталога и `claude plugin install` сообщает `marketplace not refreshed`.
Claude Code пропускает обновление перед установкой `name@marketplace`, когда:
* Маркетплейс был добавлен из локального источника `file` или `directory`, или определён встроенным в параметрах с источником [`settings`](/docs/ru/settings-reference#extraknownmarketplaces)
* [Каталог семян](/docs/ru/env-vars) предоставляет маркетплейс
* Claude Code обновил маркетплейс в течение последних 30 секунд
* Вы установили `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`
* [Управляемые параметры](/docs/ru/plugins/org#restrict-what-users-can-install) блокируют маркетплейс, в этом случае Claude Code также отказывает в установке
Когда запускается автоматическое обновление
В интерактивном сеансе, после того как вы отправите своё первое сообщение, Claude Code ждёт случайную задержку до десяти минут. Затем он обновляет каждый маркетплейс с включённым автоматическим обновлением и обновляет плагины, установленные из них, на диске.
Работающий сеанс сохраняет версии, которые он загрузил, и вы видите `Plugin updated: · Run /reload-plugins to apply`. Загружаете ли вы или нет, новые версии загружаются при следующем запуске.
Какие маркетплейсы и плагины автоматически обновляются
Автоматическое обновление маркетплейса следует первому из этих, что установлено:
1. **`autoUpdate` на его записи `extraKnownMarketplaces`** в файле параметров
2. **`autoUpdate` на его записи `known_marketplaces.json`**, которую переключатель **Enable auto-update** под `/plugin` **Marketplaces** пишет. Когда файл параметров также объявляет маркетплейс под `extraKnownMarketplaces`, переключатель пишет `autoUpdate` в эту запись параметров также
3. **По умолчанию**: включено для официальных маркетплейсов Anthropic, таких как `claude-plugins-official`, отключено для `knowledge-work-plugins` и `first-party-plugins`, включено для [маркетплейсов, добавленных с claude.ai](/docs/ru/plugins/install#add-from-claude-ai), и отключено для каждого другого маркетплейса
Если вы установите `DISABLE_UPDATES=1`, `DISABLE_AUTOUPDATER=1` или `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, весь проход отключен и переключатель **Enable auto-update** скрыт, если вы также не установите `FORCE_AUTOUPDATE_PLUGINS=1`. [Справочник переменных окружения](/docs/ru/env-vars) охватывает более широкий эффект каждой переменной.
Автоматическое обновление также пропускает плагин, чья запись маркетплейса объявляет `headersHelper`. [Установки и обновления, которые отказывают команде вместо запроса](/docs/ru/plugins/host-marketplace#installs-and-updates-that-refuse-the-command-instead-of-asking) объясняют, когда такой плагин появляется на вкладке `/plugin` **Errors** и как вы его обновляете оттуда.
Когда скопированный плагин обновляется в середине сеанса, команды hooks, мониторы, MCP серверы и LSP серверы продолжают использовать путь предыдущей версии. Запустите `/reload-plugins`, чтобы переключить hooks, MCP серверы и LSP серверы на новый путь. Мониторы требуют перезагрузки сеанса.
Когда источник команды повторно запускается
Плагины с источником `command` не ждут [прохода автоматического обновления](#when-auto-update-runs). Напечатанный каталог отражает состояние инструмента в момент запуска команды, поэтому Claude Code запускает [команду, которую вы приняли](/docs/ru/plugins/host-marketplace#change-the-command-of-a-command-source), снова в эти моменты:
* Каждый раз, когда вы устанавливаете или обновляете плагин
* Один раз за сеанс для каждого включённого плагина с источником команды, в фоновом режиме, вскоре после запуска сеанса. Этот запуск не зависит от параметра автоматического обновления маркетплейса или от `DISABLE_AUTOUPDATER`
* При запуске или на `/reload-plugins`, когда установленная версия включённого плагина отсутствует в кэше плагина
Claude Code пропускает два фоновых запуска, когда вы установили [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ru/env-vars). Явные установки и обновления всё ещё запускают команду с этой переменной установленной.
Когда хэшированный вывод команды изменился, Claude Code устанавливает результат как новую версию и перезагружает его в работающем интерактивном сеансе, переключая [те же компоненты, которые переключает `/reload-plugins`](/docs/ru/plugins/cli-reference#reload-plugins). Вы видите уведомление о том, что плагин был перезагружен.
Если перезагрузка на месте сделает кэш подсказок сеанса недействительным, Claude Code вместо этого предлагает вам запустить `/reload-plugins`, который [предупреждает о стоимости кэша и применяется при повторном запуске с `--force`](/docs/ru/prompt-caching#enabling-or-disabling-a-plugin).
Конфликты имён
Когда включённые плагины из разных источников имеют одно имя манифеста, этот порядок решает, какой загружается, от наивысшего приоритета к самому низкому:
1. Плагин, чей идентификатор появляется в управляемых параметрах `enabledPlugins`, как `true` или `false`. Копия `--plugin-dir`, чьё имя манифеста совпадает с частью имени идентификатора, не загружается, и вы видите `--plugin-dir copy of "" ignored: plugin is locked by managed settings`
2. Включённый плагин `--plugin-dir`, `--plugin-url` или `CLAUDE_CODE_PLUGIN_DIRS`. Он заменяет установленный плагин маркетплейса с тем же именем или плагин каталога навыков:
* **Установленный плагин маркетплейса**: заменён молча. `claude plugin list` всё ещё показывает строку маркетплейса как включённую, потому что эта строка отражает ваши параметры. Только журнал, который Claude Code пишет в `~/.claude/debug/`, когда вы запускаете с `--debug`, записывает `Plugin "" from --plugin-dir overrides installed version`
* **Плагин каталога навыков**: заменён строкой вкладки `/plugin` **Errors**, которая читает `Not loaded — the name "" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence`
3. Установленный плагин маркетплейса. Плагин каталога навыков с тем же именем получает ту же строку `Not loaded`, называя установленный плагин
4. Плагин каталога навыков. Между двумя из них копия под `~/.claude/skills/` загружается и копия проекта `.claude/skills/` отбрасывается, со строкой, которая говорит, какой путь её затенил
5. Плагин [синхронизированный с claude.ai](#synced-plugins). Когда включённый плагин из любого другого источника совпадает с его именем, Claude Code загружает этот плагин и сообщает о синхронизированной копии как не загруженной. Чтобы использовать копию claude.ai вместо этого, отключите свою собственную копию
Поскольку порядок сравнивает имена манифестов, плагин `--plugin-dir` с именем `hello-plugin` заменяет `hello@example-marketplace`, когда манифест этого плагина также говорит `"name": "hello-plugin"`.
Держите плагин только для сеанса от загрузки
Чтобы плагин `--plugin-dir` не затенял ничего, или чтобы отключить его, когда родительский процесс передаёт флаг для вас, установите его идентификатор в `false` в любом файле параметров. Для плагина, чьё имя манифеста — `hello-plugin`, запись — `"enabledPlugins": {"hello-plugin@inline": false}`. Отключённый плагин только для сеанса не затеняет, поэтому вместо этого загружается копия маркетплейса или каталога навыков.
Следующие шаги
* [Установка и управление плагинами](/docs/ru/plugins/install): сами шаги установки, включения, отключения и обновления
* [Устранение неполадок плагинов](/docs/ru/plugins/troubleshooting): сообщения об ошибках по этапам, которые их производят
* [Справочник команд плагинов](/docs/ru/plugins/cli-reference): флаги и команды, названные на этой странице
* [Управление плагинами для вашей организации](/docs/ru/plugins/org): управляемые параметры, которые принудительно включают или блокируют плагины