/reload-plugins를 실행할 때마다 Claude Code가 적용하는 규칙을 제공합니다. Claude에게 이 페이지를 읽고 설정을 진단하도록 요청할 수도 있습니다.
다음 경우는 다른 페이지에서 다룹니다:
- 설치, 활성화, 비활성화 및 업데이트 단계: 플러그인 설치 및 관리 참조
- 특정 오류 메시지가 있는 경우: 플러그인 문제 해결 참조
- 끈 플러그인이 여전히 로드됨: 플러그인이 활성화된 위치 찾기
- 업데이트가 아무것도 변경하지 않음: 버전 및 업데이트
~/.claude/plugins/아래의 파일을 보고 있음: 디스크에서 플러그인 찾기--plugin-dir플러그인이 로드되지 않았거나 같은 이름의 플러그인이 대신 로드됨: 이름 충돌
플러그인이 도달한 단계 확인
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 Errors 탭에 Plugin "<name>" not cached at <path>가 표시되고, claude plugin list는 같은 줄에 — run /plugin to refresh를 추가합니다. 수정 방법은 Plugin "<name>" not cached at <path>를 참조합니다.
플러그인이 어디에서 왔는지 찾기
모든 플러그인에는<name>@<origin> 형식의 id가 있으며, 이는 설정 파일과 claude plugin list --json에서 볼 수 있습니다. @ 뒤의 부분은 Claude Code가 플러그인을 찾은 위치를 알려줍니다:
마켓플레이스 플러그인의 경우
<name>은 marketplace.json의 항목 이름입니다. @inline 및 @skills-dir의 경우 플러그인의 매니페스트에서 name입니다.
이 표의 원본 이름은 예약되어 있으므로 마켓플레이스는 inline, skills-dir 또는 synced로 명명될 수 없습니다.
항목 이름 및 매니페스트 이름
마켓플레이스 플러그인에는 두 개의 이름이 있으며 다를 수 있습니다:marketplace.json의 항목 이름: 설치 및 활성화 키입니다.enabledPlugins에 작성하는 것, 캐시 디렉토리의 이름이 지정되는 것,claude plugin list가 표시하는 것입니다- 매니페스트의
name: 플러그인의 구성 요소가 네임스페이스되는 것, 이름 충돌이 비교하는 것입니다
저장소를 통해 공유된 플러그인
저장소를 통해 플러그인을 공유하려면.claude/settings.json의 enabledPlugins 아래에 나열하거나 .claude/skills/ 아래에 배치합니다. Claude Code는 프로젝트의 .claude/plugins/ 디렉토리를 스캔하지 않습니다.
클라우드 세션은 저장소가 extraKnownMarketplaces 아래에 나열하는 마켓플레이스를 추가하지 않습니다. 이는 작업 영역 신뢰 대화 상자가 필요하기 때문이며, 클라우드 세션은 절대 표시하지 않습니다.
프로젝트 범위 기술 디렉토리 플러그인은 세션의 기본 작업 디렉토리의 .claude/skills/에서만 로드되며, 해당 폴더에 대한 작업 영역 신뢰 대화 상자를 수락한 후에만 로드됩니다. 일반 기술 및 명령이 하는 방식으로 저장소 루트까지 부모 디렉토리를 검색하지 않습니다. 하위 디렉토리에서 시작하면 저장소 루트의 플러그인이 로드되지 않습니다. 대신 저장소 루트에서 시작하거나, v2.1.246 이상에서 /cd로 세션을 이동합니다.
프로젝트 범위 플러그인은 저장소에 체크인되고 이를 복제하는 모든 협력자에게 도달합니다. 해당 콘텐츠는 사용자가 아닌 저장소에서 오기 때문에 .claude/settings.json의 프로젝트 허용 규칙에 적용되는 것과 동일한 신뢰 확인 후에만 로드됩니다. 부모 폴더를 신뢰하거나 -p로 실행하는 것으로는 충분하지 않습니다. 코드를 실행하는 구성 요소는 추가로 제한됩니다:
- 선언하는 MCP 서버는 프로젝트
.mcp.json과 동일한 서버별 승인을 거칩니다 - MCP 번들로 선언하는 MCP 서버,
.mcpb또는.dxt파일, 또는 플러그인 디렉토리 외부의 파일에서 선언하는 MCP 서버는 건너뜁니다. 인라인으로 선언하거나 플러그인 디렉토리 내의.mcp.json에서 선언합니다 - 백그라운드 모니터는 로드되지 않습니다
--plugin-dir 및 기술 디렉토리 플러그인을 작성하는 방법은 플러그인 생성을 참조합니다.
claude.ai에서 동기화된 플러그인
claude.ai 계정에 대해 켜는 플러그인도 마켓플레이스에서 설치한 플러그인과 함께 Claude Code에 로드됩니다. 여기에는 조직이 구성원에 대해 켜는 플러그인이 포함됩니다. 이러한 각 플러그인은 마켓플레이스 없이<name>@synced로 로드되며 설치 기록이 없습니다.
터미널 세션에서 동기화된 플러그인의 기술, 에이전트, 훅, MCP 서버 및 LSP 서버는 모두 마켓플레이스 플러그인을 설치한 것과 동일한 신뢰로 로드됩니다.
Cowork가 로드하는 구성 요소는 claude.com의 claude.ai 및 Cowork의 플러그인을 참조합니다.
동기화된 플러그인은 Cowork 세션 및 claude.ai 계정으로 로그인하는 터미널 세션에 로드됩니다:
- 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 <name>@synced를 실행하고 세션의/pluginInstalled 탭은 모두 사용자 수준enabledPlugins에"<name>@synced": false를 저장합니다. 모든 환경의 프로젝트에서 플러그인을 유지하려면 프로젝트의 커밋된.claude/settings.json에서 동일한 키를 설정합니다 - 머신의 모든 동기화된 플러그인: 사용자 설정에서
syncClaudeAiPlugins를false로 설정하거나 조직이 관리 설정에서 설정합니다. Claude Code는 다운로드를 중지하고 다음 번 시작할 때 이미 동기화한 플러그인을~/.claude/plugins/.trash/로 이동하고 더 이상 로드하지 않습니다. 조직이 claude.ai에서 기술을 끄면 플러그인도 동기화를 중지합니다 - 조직이 필수로 요구하는 플러그인: 조직이 claude.ai에서 필수로 표시한 플러그인은 이전에 비활성화했더라도 로드됩니다.
claude plugin disable은Plugin "<name>@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로 표시합니다
플러그인이 활성화된 위치 찾기
6개의 소스 중 어느 곳에서나enabledPlugins 항목을 설정할 수 있습니다. 표는 가장 낮은 우선 순위에서 가장 높은 우선 순위로 나열하고 각각이 누구에게 적용되는지 나열합니다. 설정 파일 자체는 설정 파일 및 영향을 미치는 사람을 참조합니다.
이러한 소스는 키별로 병합됩니다. 각 플러그인 id에 대해 적용되는 값은 id를 언급하는 가장 높은 우선 순위 소스의 값입니다. id를 언급하지 않는 소스는 낮은 우선 순위 소스의 값을 유효하게 유지합니다.
사용자 설정에서 비활성화되었지만 여전히 로드됨
~/.claude/settings.json에서 플러그인을 false로 설정했는데 여전히 로드되면 더 높은 우선 순위 소스의 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.
프로젝트 활성화 플러그인을 머신에서 거부하려면 프로젝트 파일보다 우선 순위가 높은 .claude/settings.local.json에서 id를 false로 설정합니다.
프로젝트 설정에서 활성화되었지만 설치되지 않음
플러그인의 유일한true가 프로젝트의 .claude/settings.json에 있을 때 Claude Code는 상대 경로 소스가 있거나 시드 디렉토리가 이미 보유하지 않는 한 설치되지 않은 머신에 플러그인을 가져오지 않습니다. 대신 /plugin Errors 탭은 Plugin "<name>" is enabled in project settings but isn't installed here를 표시합니다.
상대 경로 플러그인은 마켓플레이스 자체에서 로드되기 때문에 설치 기록이 필요하지 않습니다.
Claude Code는 다음 소스 중 하나가 이를 true로 설정할 때만 외부 소스가 있는 플러그인을 가져옵니다:
- 사용자 설정
- git이 추적하지 않는
.claude/settings.local.json --settings플래그- 관리 설정
디스크에서 플러그인 찾기
Claude Code는 플러그인 파일과 상태 기록을 하나의 플러그인 루트 아래에 유지하며, 이는CLAUDE_CODE_PLUGIN_CACHE_DIR을 설정하지 않는 한 ~/.claude/plugins입니다. 표의 모든 경로는 해당 루트에 상대적입니다.
${CLAUDE_PLUGIN_ROOT}는 버전 디렉토리를 가리키기 때문에 플러그인의 루트 경로는 모든 버전과 함께 변경됩니다. 플러그인의 내구성 있는 파일을 ${CLAUDE_PLUGIN_DATA} 대신에 유지합니다.
제자리 및 복사된 플러그인
Claude Code는 일부 플러그인을 보관 위치에서 제자리로 로드하고 나머지는 원본에 따라 캐시에 복사합니다:--plugin-dir및 기술 디렉토리 플러그인: 디렉토리는 제자리로 로드되며 절대 복사되지 않습니다.--plugin-url아카이브 또는--plugin-dir.zip은 먼저 세션 임시 디렉토리로 추출됩니다- 로컬 디렉토리에서 추가한 마켓플레이스의 상대 경로 플러그인: 플러그인은 마켓플레이스 폴더 내의 경로에서 제자리로 로드됩니다. 소스 디렉토리에 대한 편집은 다음 세션 시작 또는
/reload-plugins에서 적용되며 버전을 증가시킬 필요가 없습니다. 플러그인의 훅 프로세스 및 MCP 및 LSP 서버는 소스 디렉토리를 가리키는CLAUDE_PLUGIN_ROOT를 수신합니다. Node.js 패키지 종속성은 종속성 설치가 실행되는 경우를 참조합니다 - 링크 모드의
command소스 플러그인: 명령이 인쇄한 디렉토리는 캐시 항목의 링크를 통해 제자리로 로드됩니다 - 다른 모든 마켓플레이스 플러그인: Claude Code는 플러그인을 설치 시
cache/<marketplace>/<plugin>/<version>/에 복사하고 해당 복사본을 로드합니다. 플러그인 디렉토리 외부의 파일은 복사되지 않으므로 복사된 플러그인 내의 스크립트가 플러그인 루트 위의 경로를 읽을 때 (예:../shared), 찾지 못합니다
플러그인 디렉토리를 벗어나는 경로
플러그인이 제자리에서 로드되든 캐시된 복사본에서 로드되든 Claude Code는 자신의 디렉토리 외부에 구성 요소를 선언하도록 허용하지 않습니다. 플러그인 루트 외부로 해결되는 구성 요소 경로를 거부합니다. 경로가plugin.json에 선언되든 마켓플레이스 항목에 선언되든:
- 작성된 대로 플러그인 외부를 가리키는 경로, 예:
../shared-utils - 플러그인 외부로 이어지는 심볼릭 링크, 하나의 마켓플레이스 내 플러그인 간 링크 제외
- macOS 및 Linux에서 경로에 백슬래시가 포함된 경로, 경로가 플러그인 내에 머물더라도. 백슬래시 경로로 선언된 구성 요소는 Windows에서만 로드되므로
./commands/deploy.md와 같이 정방향 슬래시로 구성 요소 경로를 작성합니다
path escapes plugin directory 오류로 나타나고 플러그인은 해당 구성 요소 없이 로드됩니다.
이전 버전의 정리
플러그인을 업데이트하거나 제거할 때 Claude Code는 이전 버전 디렉토리에.orphaned_at 마커를 씁니다. 14일 후 백그라운드 정리에서 해당 디렉토리를 제거하므로 이미 이전 버전을 로드한 세션은 계속 실행됩니다.
installed_plugins.json이 최소한 하나의 설치를 기록하는 동안에만 스윕이 실행됩니다. 마지막 플러그인을 제거한 후 고아 디렉토리는 다른 플러그인을 설치할 때까지 유지됩니다.
Node.js 패키지 종속성
Claude Code가 플러그인을 캐시에 복사할 때 플러그인의 Node.js 패키지 종속성도 거기에 설치하므로 플러그인의 훅과 MCP 서버가 로드할 수 있습니다. 이 섹션은 플러그인이 자신의package.json에 선언하는 npm 및 Bun 패키지를 다룹니다. 다른 플러그인에 의존하는 플러그인은 플러그인 종속성 버전을 참조합니다.
종속성 설치가 실행되는 경우
Claude Code는 생성할 때마다 복사된 버전 디렉토리 내에서 설치를 실행합니다:- 플러그인을 설치할 때
- Claude Code가 플러그인을 새 버전으로 업데이트할 때
- 새 머신과 같이 활성화된 플러그인이 아직 캐시되지 않았을 때 세션 시작 시
${CLAUDE_PLUGIN_DATA}로 설치합니다.
설치는 플러그인의 루트 디렉토리에 package.json과 지원되는 잠금 파일이 모두 포함될 때만 실행됩니다. 잠금 파일은 Claude Code가 실행하는 명령을 결정합니다:
플러그인에 이러한 잠금 파일이 두 개 이상 포함되어 있으면 Claude Code는 첫 번째 일치를 사용하며 순서대로 확인합니다:
bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json.
Claude Code는 Yarn 및 pnpm 잠금 파일과 Bun 잠금 파일 옆의 bunfig.toml에 대한 설치를 건너뜁니다:
- 플러그인에
yarn.lock또는pnpm-lock.yaml만 있으면 npm 잠금 파일로 바꿉니다 bunfig.toml이 Bun 잠금 파일과 같은 디렉토리에 있으면bunfig.toml을 제거하거나 Bun 잠금 파일을 npm 잠금 파일로 바꿉니다
package-lock.json을 제외하기 때문에 npm-shrinkwrap.json을 사용합니다.
종속성 설치의 제한
Claude Code는 이 종속성 설치를 제한하여 설치 중에 플러그인 또는 패키지의 코드가 실행되지 않도록 하고 실행 시간을 제한합니다:- 고정 해결: Bun 및 npm은 잠금 파일이 고정한 것을 정확히 설치하고
package.json과 잠금 파일이 불일치할 때 버전을 다시 해결하는 대신 실패합니다 - 라이프사이클 스크립트 없음:
--ignore-scripts는preinstall,install,postinstall스크립트가 실행되지 않도록 하므로 해당 스크립트에서 네이티브 모듈을 빌드하는 종속성은 다운로드되지만 이 설치 중에 컴파일되지 않습니다 - 60초 타임아웃: Claude Code는 더 오래 실행되는 설치를 중지하고 실패로 처리합니다
종속성 설치가 실패하거나 건너뛰어질 때
실패하거나 건너뛴 설치는 플러그인을 절대 차단하지 않으며 각 경우는 다른 신호를 남깁니다:- 실패한 설치 또는 Yarn 또는 pnpm 잠금 파일 또는
bunfig.toml때문에 건너뛴 설치는claude --debug출력에 경고로 나타납니다 package.json이 있고 잠금 파일이 없는 플러그인은 로그 항목 없이 건너뜁니다- 시간 초과된 설치는 캐시된 복사본에 부분
node_modules트리를 남길 수 있습니다
버전 및 업데이트
플러그인의 작성자가 새 커밋을 푸시했고claude plugin update가 <name> is already at the latest version (<version>).를 인쇄하면 Claude Code가 플러그인에 대해 계산하는 버전은 변경되지 않으므로 디스크에서 아무것도 변경되지 않습니다.
Claude Code는 설치하는 모든 플러그인에 대해 버전을 계산하고 그 버전이 업데이트를 감지하는 방법입니다. claude plugin update 및 백그라운드 자동 업데이트는 버전을 다시 계산하고 installed_plugins.json이 기록한 것과 일치할 때 플러그인을 건너뜁니다.
버전은 플러그인의 캐시 디렉토리의 이름도 지정합니다.
"version"을 고정하는 매니페스트는 계산된 버전이 커밋 전체에서 동일하게 유지되는 한 가지 방법입니다. Claude Code가 버전을 계산하는 방법을 참조합니다.
로컬 디렉토리 마켓플레이스에서 제자리로 로드된 플러그인은 버전 문자열이 무엇이든 모든 세션 시작에서 현재 소스 파일을 로드합니다. claude.ai에서 호스팅되는 마켓플레이스의 플러그인의 경우 claude.ai가 플러그인에 대해 기록하는 버전이 버전이고 매니페스트의 version은 읽지 않습니다.
Claude Code가 버전을 계산하는 방법
추가한 소스의 마켓플레이스의 경우 Claude Code는 플러그인의 마켓플레이스 항목의source 유형으로 규칙을 선택합니다. 마켓플레이스 참조는 소스 유형을 나열합니다. 해당 목록의 command 제외 모든 소스 유형에 대해:
- 플러그인의 매니페스트의
version필드가 먼저 옵니다 - 그 다음 플러그인의 마켓플레이스 항목의
version필드 - 둘 다 설정되지 않으면 버전은 소스 유형에서 옵니다:
Claude Code는 설치 경로를 둘러싼 저장소 (예: git 관리
~/.claude)에서 버전을 가져오지 않습니다.
command 소스의 경우 Claude Code는 항상 명령이 생성한 것에서 버전을 파생합니다: 자체적으로 12자 해시 또는 매니페스트가 하나를 설정할 때 <manifest version>-<hash>. 마켓플레이스 항목의 version은 명령 소스에 대해 무시됩니다. 해시가 포함하는 것은 복사 모드 및 링크 모드를 참조합니다.
매니페스트가 먼저 오기 때문에 "version": "1.0.0"을 고정하는 매니페스트는 작성자가 문자열을 변경할 때까지 모든 사용자를 캐시된 복사본에 유지하며, 푸시하는 커밋이 몇 개이든 상관없습니다. 사용자가 커밋을 추적하도록 하려면 매니페스트와 항목 모두에서 version을 생략합니다. 마켓플레이스 호스팅은 어떤 선택이 어떤 릴리스 설정에 맞는지 다룹니다.
Claude Code가 설치 전에 마켓플레이스를 새로 고칠 때
플러그인을 설치할 때 Claude Code는 마켓플레이스 카탈로그의 로컬 복사본에서 조회합니다. 세션에서/plugin install을 실행하거나 셸에서 claude plugin install을 실행하고 마켓플레이스 없이 또는 마켓플레이스와 함께 플러그인의 이름을 지정할 수 있습니다. 표는 이러한 조합 중 어느 것이 로컬 복사본을 새로 고치는지 보여줍니다.
name@marketplace 설치 전의 새로 고침은 마켓플레이스의 자동 업데이트 설정이나 DISABLE_AUTOUPDATER에 의존하지 않습니다.
새로 고침이 실패하면 설치는 캐시된 카탈로그에서 진행되고 claude plugin install은 marketplace not refreshed를 보고합니다.
Claude Code는 다음 경우에 name@marketplace 설치 전의 새로 고침을 건너뜁니다:
- 마켓플레이스가 로컬
file또는directory소스에서 추가되었거나settings소스를 사용하여 설정에서 인라인으로 정의됨 - 시드 디렉토리가 마켓플레이스를 제공함
- Claude Code가 지난 30초 내에 마켓플레이스를 새로 고침
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC을 설정함- 관리 설정이 마켓플레이스를 차단하며, 이 경우 Claude Code도 설치를 거부합니다
자동 업데이트가 실행될 때
대화형 세션에서 첫 번째 메시지를 보낸 후 Claude Code는 최대 10분의 무작위 지연을 기다립니다. 그 다음 자동 업데이트가 켜진 모든 마켓플레이스를 새로 고치고 디스크에서 설치된 플러그인을 업데이트합니다. 실행 중인 세션은 로드한 버전을 유지하고Plugin updated: <name> · Run /reload-plugins to apply가 표시됩니다. 다시 로드하든 안 하든 새 버전은 다음 시작 시 로드됩니다.
어떤 마켓플레이스 및 플러그인이 자동 업데이트되는지
마켓플레이스가 자동 업데이트되는지는 설정된 첫 번째를 따릅니다:- 설정 파일의
extraKnownMarketplaces항목의autoUpdate known_marketplaces.json항목의autoUpdate,/pluginMarketplaces 아래의 Enable auto-update 토글이 씁니다. 설정 파일이extraKnownMarketplaces아래에서 마켓플레이스를 선언할 때 토글은 해당 설정 항목에도autoUpdate를 씁니다- 기본값: Anthropic의 공식 마켓플레이스 (예:
claude-plugins-official)의 경우 켜짐,knowledge-work-plugins및first-party-plugins의 경우 꺼짐, claude.ai에서 추가한 마켓플레이스의 경우 켜짐, 다른 모든 마켓플레이스의 경우 꺼짐
DISABLE_UPDATES=1, DISABLE_AUTOUPDATER=1, 또는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1을 설정하면 전체 패스가 꺼지고 FORCE_AUTOUPDATE_PLUGINS=1도 설정하지 않는 한 Enable auto-update 토글이 숨겨집니다. 환경 변수 참조는 각 변수의 더 넓은 효과를 다룹니다.
자동 업데이트는 또한 마켓플레이스 항목이 headersHelper를 선언하는 플러그인을 건너뜁니다. 명령 대신 거부하는 설치 및 업데이트는 이러한 플러그인이 /plugin Errors 탭에 나타나는 경우와 거기에서 업데이트하는 방법을 설명합니다.
복사된 플러그인이 세션 중에 업데이트될 때 훅 명령, 모니터, MCP 서버 및 LSP 서버는 이전 버전의 경로를 계속 사용합니다. /reload-plugins를 실행하여 훅, MCP 서버 및 LSP 서버를 새 경로로 전환합니다. 모니터는 세션 재시작이 필요합니다.
명령 소스가 다시 실행될 때
command 소스가 있는 플러그인은 자동 업데이트 패스를 기다리지 않습니다. 인쇄된 디렉토리는 명령이 실행된 시점의 도구 상태를 반영하므로 Claude Code는 수락한 명령을 다시 실행합니다:
- 플러그인을 설치하거나 업데이트할 때마다
- 세션당 한 번씩 활성화된 각 명령 소스 플러그인에 대해 백그라운드에서 세션이 시작된 직후. 이 실행은 마켓플레이스의 자동 업데이트 설정이나
DISABLE_AUTOUPDATER에 의존하지 않습니다 - 시작 시 또는
/reload-plugins에서 활성화된 플러그인의 설치된 버전이 플러그인 캐시에서 누락되었을 때
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC을 설정할 때 Claude Code는 두 백그라운드 실행을 건너뜁니다. 명시적 설치 및 업데이트는 해당 변수가 설정되어 있어도 명령을 실행합니다.
명령의 해시된 출력이 변경되면 Claude Code는 결과를 새 버전으로 설치하고 실행 중인 대화형 세션에서 다시 로드하며 /reload-plugins가 전환하는 동일한 구성 요소를 전환합니다. 플러그인이 다시 로드되었다는 알림이 표시됩니다.
제자리에서 다시 로드하면 세션의 프롬프트 캐시가 무효화되면 Claude Code는 대신 /reload-plugins를 실행하도록 프롬프트하며, 캐시 비용에 대해 경고하고 --force로 다시 실행할 때 적용합니다.
이름 충돌
다른 원본의 활성화된 플러그인이 매니페스트 이름을 공유할 때 이 순서는 어느 것이 로드되는지 결정하며, 가장 높은 우선 순위에서 가장 낮은 우선 순위로:- id가 관리 설정
enabledPlugins에 나타나는 플러그인,true또는false로. 매니페스트 이름이 id의 이름 부분과 일치하는--plugin-dir복사본은 로드되지 않으며--plugin-dir copy of "<name>" ignored: plugin is locked by managed settings가 표시됩니다 - 활성화된
--plugin-dir,--plugin-url, 또는CLAUDE_CODE_PLUGIN_DIRS플러그인. 같은 이름의 설치된 마켓플레이스 플러그인 또는 기술 디렉토리 플러그인을 대체합니다:- 설치된 마켓플레이스 플러그인: 조용히 대체됨.
claude plugin list는 여전히 마켓플레이스 행을 활성화된 것으로 표시합니다. 설정을 반영하기 때문입니다.--debug로 시작할 때 Claude Code가~/.claude/debug/아래에 쓰는 로그만Plugin "<name>" from --plugin-dir overrides installed version을 기록합니다 - 기술 디렉토리 플러그인:
/pluginErrors 탭 행으로 대체되며Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence를 읽습니다
- 설치된 마켓플레이스 플러그인: 조용히 대체됨.
- 설치된 마켓플레이스 플러그인. 같은 이름의 기술 디렉토리 플러그인은 동일한
Not loaded행을 가지며 설치된 플러그인의 이름을 지정합니다 - 기술 디렉토리 플러그인. 이 둘 사이에서
~/.claude/skills/아래의 복사본이 로드되고 프로젝트의.claude/skills/복사본이 삭제되며 어떤 경로가 이를 섀도우했는지 말하는 행이 있습니다 - claude.ai에서 동기화된 플러그인. 다른 원본의 활성화된 플러그인이 이름과 일치할 때 Claude Code는 해당 플러그인을 로드하고 동기화된 복사본을 로드되지 않은 것으로 보고합니다. claude.ai 복사본을 대신 사용하려면 자신의 복사본을 비활성화합니다
hello-plugin이라는 --plugin-dir 플러그인은 해당 플러그인의 매니페스트도 "name": "hello-plugin"을 말할 때 hello@example-marketplace를 대체합니다.
세션 전용 플러그인이 로드되지 않도록 유지
--plugin-dir 플러그인이 아무것도 섀도우하지 않도록 하거나 부모 프로세스가 플래그를 전달할 때 하나를 끄려면 설정 파일에서 id를 false로 설정합니다. 매니페스트 이름이 hello-plugin인 플러그인의 경우 항목은 "enabledPlugins": {"hello-plugin@inline": false}입니다. 비활성화된 세션 전용 플러그인은 섀도우하지 않으므로 마켓플레이스 또는 기술 디렉토리 복사본이 대신 로드됩니다.
다음 단계
- 플러그인 설치 및 관리: 설치, 활성화, 비활성화 및 업데이트 단계 자체
- 플러그인 문제 해결: 이를 생성하는 단계별 오류 메시지
- 플러그인 명령 참조: 이 페이지에서 명명된 플래그 및 명령
- 조직의 플러그인 관리: 플러그인을 강제 활성화하거나 차단하는 관리 설정