조직의 플러그인 관리

기준일: 2026-10-23
공식 기준: Manage Claude Code plugins for your organization

개요

managed settings로 조직 모든 기기에서 Claude Code가 설치·허용할 플러그인을 정합니다. 사용자는 덮어쓸 수 없습니다. server-managed settings(claude.ai 관리 콘솔) 또는 MDM·managed-settings.json 파일(endpoint-managed)로 전달하며, 이 페이지의 대부분 제어는 managed settings에서만 효과가 있습니다. 관리자용이며 Claude Code를 다룹니다.

다른 페이지:

• 본인용 설치: Install plugins
• claude.ai·Cowork 플러그인 제어: claude.com의 Manage plugins for your organization
• claude.ai, Cowork, Claude Code에 한 플러그인을 함께 롤아웃: Choose a rollout route
• claude.ai 관리 설정의 Organization settings > Plugins & skills는 구성원 claude.ai 계정에 플러그인을 켜며 Claude Code에는 synced plugins로 도달합니다. 이 페이지의 키는 설정하지 않습니다

구성 순서: 필수화 → 컨테이너·CI seed → 설치 제한 → 업데이트 정책 → 감사. 모든 정책 키는 제어 매트릭스.

핵심 개념

개념	설명
extraKnownMarketplaces	각 기기에 마켓플레이스 등록 (additionalMarketplaces 별칭)
enabledPlugins	plugin-name@marketplace-name을 설치·활성화. true는 강제, false는 모든 scope 차단+목록에서 숨김
strictKnownMarketplaces	마켓 소스 allowlist (allowedMarketplaces 별칭). []는 공식 마켓 포함 전부 차단
blockedMarketplaces	마켓 소스 blocklist. allowlist보다 먼저 검사
disableSideloadFlags	--plugin-dir 등 sideload 플래그 거부
CLAUDE_CODE_PLUGIN_SEED_DIR	컨테이너/CI용 읽기 전용 seed 디렉터리
pluginSuggestionMarketplaces	설치 제안에 나올 수 있는 마켓

상세

사전 설치와 필수화

마켓플레이스는 git 저장소, URL, 로컬 경로에서 가져오는 플러그인 카탈로그입니다. 기기에 등록하면 거기서 플러그인을 설치할 수 있습니다. 한 대규모 기기군에는 managed settings에 두 키를 함께 설정합니다. extraKnownMarketplaces가 마켓을 등록하고 enabledPlugins가 그 마켓에서 설치·활성화할 플러그인을 지정합니다.

전달 방식 선택

• Server-managed settings: Organization settings > Claude Code > Managed settings에 플러그인 키를 JSON으로. Claude 조직의 Owner 역할 필요. cloud 세션은 플러그인 설치 전에 이 설정을 가져옴
• MDM 정책: macOS는 최상위 키가 설정 키인 plist, Windows는 전체 JSON 문서를 문자열로 레지스트리 값에 저장. plist domain과 레지스트리 키는 Where each mechanism stores the policy
• Managed settings 파일: 플랫폼 시스템 경로에 managed-settings.json. 옆의 managed-settings.d/ drop-in 디렉터리에 파일 추가 가능. 병합 규칙은 Split a file-based policy across teams

Claude for Teams/Enterprise 조직이고 기기가 모두 MDM 아래가 아니면 server-managed settings를 쓰세요. 아니면 MDM 정책이나 파일. 비교는 Choose between server-managed and endpoint-managed settings.

기기에 적용되는 managed 소스

기본적으로 기기에서는 세 소스 중 하나만 적용됩니다. 정책 키를 전달하는 첫 소스를 씁니다 (순서: server-managed → MDM → 파일). server-managed가 관련 없는 정책 키 하나라도 전달하면 그 기기에서 MDM·파일의 플러그인 키는 무시됩니다(모든 소스에서 읽는 키 제외). 모든 소스를 적용하려면 managedSourcesBehavior를 "merge"로. 두 모드에서 모든 소스로 읽는 키는 How Claude Code combines managed sources.

마켓플레이스와 플러그인 필수화

extraKnownMarketplaces에 마켓의 marketplace.json name을 키로 추가하고, enabledPlugins에 plugin-name@marketplace-name으로 각 플러그인을 추가합니다. 마켓 항목은 github 등 타입을 명명하는 source 필드를 가진 source 객체를 가집니다. 조직 마켓플레이스를 등록하고 플러그인 둘을 강제 활성화하는 예:

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  }
}

설정이 도착하면 사용자의 다음 세션 시작에 마켓을 등록하고 플러그인 둘을 설치합니다. /plugin에 보이며, 사용자가 자기 scope에서 비활성화해도 managed settings가 모든 scope보다 우선하므로 계속 로드됩니다. 모든 scope에서 막고 마켓 목록에서 숨기려면 managed enabledPlugins에서 false로 설정하세요.

• autoUpdate: true는 마켓과 플러그인을 백그라운드로 갱신, false는 끔. 업데이트 정책
• source: github는 여러 소스 타입 중 하나. git 소스는 GitLab/내부 호스트용 url, url 소스는 호스팅된 marketplace.json 주소. 모든 형태는 marketplace reference

비공개 git 저장소 마켓이면 사용자에게 읽기 권한이 있어야 합니다. git 기반 마켓 clone은 사용자 기기의 git으로 저장된 자격 증명과 프롬프트 없이 실행됩니다. git 호스트 계정이 없는 사용자는 seed를 쓰세요.

managed 항목은 다른 소스의 같은 이름 마켓 항목이나 --plugin-dir 사본도 덮어씁니다.

• 마켓플레이스: managed 마켓 항목이 같은 이름의 낮은 우선순위 항목을 대체. 두 항목의 필드는 병합되지 않음
• --plugin-dir 사본: 한 세션용 로컬 디렉터리 로드. 이름이 managed enabledPlugins의 플러그인과 같을 때는 Name conflicts

Anthropic 공식 마켓 claude-plugins-official은 enabledPlugins가 그 플러그인 하나를 true로 두면 extraKnownMarketplaces 항목이 필요 없습니다. name@claude-plugins-official 항목이 이 키들이 적용되는 곳 어디서든 마켓을 스스로 선언합니다. 그 플러그인을 하나도 켜지 않으면서 모든 기기에 등록하려면 공식 마켓과 자체 마켓 허용처럼 명시 항목을 주세요.

저장소별 필수화

전체 기기군이 아니라 한 저장소 기여자만 대상으로 하려면 그 저장소 .claude/settings.json에 extraKnownMarketplaces와 enabledPlugins를 둡니다. extraKnownMarketplaces 항목은 기여자가 신뢰한 폴더에서만 적용되고 신뢰하지 않은 폴더에서는 메시지 없이 무시됩니다.

• 인터랙티브 세션: 기여자가 그 폴더의 workspace 신뢰 대화상자를 수락한 뒤에만 마켓 등록
• 비대화 -p 실행: 사용자가 이미 인터랙티브로 신뢰를 수락한 폴더나 ~/.claude.json에 hasTrustDialogAccepted를 설정한 폴더에서만 적용

마켓이 상대 경로로 나열한 플러그인은 저장소 extraKnownMarketplaces 항목이 적용된 뒤 마켓 사본에서 로드됩니다. 마켓 항목이 플러그인 자체 GitHub 저장소 같은 외부 소스를 가리키면 저장소 settings만으로는 설치되지 않습니다. 기여자가 claude plugin install <name>@<marketplace> --scope project를 실행하기 전까지 Plugin "<name>" is enabled in project settings but isn't installed가 보입니다 (Install plugins). 상대 경로의 로컬 directory/file 소스는 저장소의 main checkout 기준으로 해석되어, git worktree에서 실행해도 모든 worktree가 같은 마켓 위치를 공유합니다. 의존성이 있는 번들 롤아웃은 번들 플러그인을 enabledPlugins에 두세요 (Plugin dependencies).

각 surface가 플러그인 키를 적용하는 때

Desktop 앱과 IDE 확장은 Install a plugin.

Surface	Managed extraKnownMarketplaces, enabledPlugins	저장소 .claude/settings.json
터미널, 인터랙티브	설정을 받은 모든 기기에서 세션 시작 시 적용	extraKnownMarketplaces는 신뢰 후, enabledPlugins는 세션 시작 시
-p, CI	세션 시작 시 적용, 설치는 백그라운드	extraKnownMarketplaces는 신뢰된 폴더만, enabledPlugins는 적용
Cloud 세션	Anthropic 호스팅 환경은 server-managed settings만 세션에 도달하고 세션이 플러그인 설치 전에 대기. MDM·파일은 사용자 기기에 머묾. 자체 호스팅은 Where and when a policy applies	Install a plugin의 Cloud session 탭

-p/CI 실행은 마켓과 플러그인이 백그라운드로 설치되어 첫 턴에는 플러그인이 없을 수 있습니다. CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1로 첫 쿼리 전에 설치를 기다리게 하세요.

롤아웃 확인

• 한 기기: Claude Code를 시작해 /plugin. 마켓과 플러그인이 나열됨
• CI: claude -p에 --output-format stream-json --verbose. init 이벤트의 plugins 아래 로드된 플러그인이 나열됨

컨테이너와 CI seed

런타임에 clone할 수 없는 컨테이너 이미지와 CI 러너는 빌드 시 플러그인 디렉터리를 미리 채우고 CLAUDE_CODE_PLUGIN_SEED_DIR로 가리킵니다. Claude Code는 시작 시 seed의 마켓을 등록하고 clone 없이 seed에서 플러그인 캐시를 제자리 로드합니다. git 호스트 계정이 없는 사용자에게도 쓸 수 있습니다.

CI/CD에서는 비공개 저장소의 플러그인을 설치하기 전에 git credential helper를 구성하세요. GitHub Actions는 마켓 저장소 읽기 권한 토큰을 GH_TOKEN으로 export한 뒤 gh auth setup-git. 기본 workflow 토큰은 workflow 자체 저장소에만 접근하므로 다른 저장소의 비공개 마켓은 personal access token이나 app token이 필요합니다.

1. 빌드 시 seed에 설치: CLAUDE_CODE_PLUGIN_CACHE_DIR을 seed 경로로 설정하면 ~/.claude/plugins 대신 거기에 설치됩니다.

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/your-marketplace
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install code-formatter@your-marketplace

seed는 ~/.claude/plugins와 같은 구조입니다: known_marketplaces.json, marketplaces/<name>/, cache/<marketplace>/<plugin>/<version>/. 빌드한 경로와 다른 경로에 마운트해도 됩니다.

2. 런타임을 seed로 지정: 컨테이너 환경에 CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed. 여러 seed는 Unix는 :, Windows는 ;로 구분하며, 해당 마켓이나 플러그인 캐시를 가진 첫 seed를 씁니다.

3. 플러그인 활성화: seed의 플러그인은 스스로 활성화되지 않습니다. 로드할 seed 플러그인마다 managed settings나 저장소 .claude/settings.json에 enabledPlugins를 설정하세요.

검증: 이미지에서 claude -p에 --output-format stream-json --verbose. init 이벤트 plugins 목록에서 로드된 각 플러그인의 path가 seed 아래여야 합니다 (예: /opt/claude-seed/cache/your-marketplace/code-formatter/1.0.0).

seed 마켓플레이스 규칙:

• 읽기 전용: Claude Code는 seed에 쓰지 않고 seed 마켓의 autoUpdate를 끔
• seed 항목 우선: 시작할 때마다 seed에 선언된 마켓이 같은 이름의 사용자 항목을 덮어씀. 사용자는 마켓을 지우는 대신 claude plugin disable로 seed 플러그인을 거부
• update·remove 실패: seed 마켓에 대한 claude plugin marketplace update <name>와 --scope 없는 remove는 seed 디렉터리를 명시한 메시지로 실패
• 정책은 계속 적용: allowlist와 blocklist가 seed 마켓의 기록된 소스도 검사. seed를 만든 소스를 허용하세요

외부 git 접근이 없는 기기군은 seed와 공유 마운트의 directory/file 마켓 소스를 함께 쓰고 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1도 설정하세요 (플러그인 auto-update도 꺼짐). 프록시가 있으면 Proxy configuration.

사용자 설치 제한

managed strictKnownMarketplaces allowlist와 blockedMarketplaces blocklist가 플러그인이 올 수 있는 마켓 소스를 정합니다. 마켓 소스는 Claude Code가 가져오는 git 저장소, URL, 로컬 경로입니다. 두 목록 모두 플러그인이 속한 마켓의 소스에 맞추며, 마켓 안의 플러그인 항목에 맞추지 않습니다. 공식 마켓과 자체 마켓을 허용하는 흔한 잠금은 공식 마켓플레이스와 자체 마켓 허용이며, disableSideloadFlags와 함께 써서 로컬 디렉터리·URL 로드도 막으세요.

두 목록은 다운로드 전과 세션 시작 시 적용됩니다.

• 다운로드 전: 사용자가 마켓을 추가할 때와 모든 설치·업데이트·갱신·auto-update 때
• 세션 시작 시: 이미 설치된 플러그인에도 다시 적용되어 마켓 소스가 더 이상 맞지 않으면 로드되지 않음. /plugin이 Marketplace "<name>" is not in the allowed marketplace list 또는 Marketplace "<name>" is blocked by enterprise policy로 표시

설정 위치별 적용:

• claude.ai 관리 콘솔: server-managed settings를 읽는 세션에서 Claude Code가 두 목록을 강제. claude.ai도 조직의 누군가가 claude.ai의 git 저장소에서, 또는 Claude Desktop 앱 Code 탭 밖의 Customize에서 새 마켓을 추가할 때 검사 (구성원이 자기 계정에 추가하는 것, Organization settings > Plugins에서 조직 전체에 추가하는 것 모두). allowlist가 허용하지 않거나 blocklist에 있는 저장소는 거부. 목록 설정 전에 추가된 마켓은 다시 검사하지 않고 업로드된 플러그인도 검사하지 않음
• managed settings 파일, OS 수준 정책, 기타 managed 소스: Claude Code가 그 소스를 읽는 곳에서 두 목록 강제. claude.ai는 읽지 않음

allowlist가 설정됐거나 blocklist가 skills-dir 외의 소스를 이름으로 지목하면 Claude Code가 마켓을 찾지 못하는 플러그인은 로드되지 않으며 /plugin이 not-found 대신 정책 오류를 보여줍니다. 흔한 경우는 아무도 등록하지 않은 마켓의 오래된 enabledPlugins 항목입니다.

제어 매트릭스

키	강제하는 것	하지 못하는 것
strictKnownMarketplaces	마켓 소스 allowlist. []는 공식 마켓 포함 모든 소스 차단. 별칭 allowedMarketplaces	마켓 등록, 허용된 마켓 안의 항목 제한, --plugin-dir 차단은 못 함
blockedMarketplaces	마켓 소스 blocklist, allowlist보다 먼저 검사	맞지 않는 소스로 이미 등록된 마켓은 차단 못 함
syncClaudeAiPlugins	false로 설정하면 Claude Code가 각 사용자 계정의 claude.ai에서 sync된 플러그인을 다운로드·로드하지 않음. Claude Code v2.1.273 이상	sync된 플러그인 하나만 끄지 못함. 그것은 enabledPlugins에 "<name>@synced": false
enabledPlugins	true는 강제 활성화, false는 모든 scope 차단+플러그인 숨김	마켓이 등록·허용되지 않은 플러그인은 설치 못 함
disableSideloadFlags	--plugin-dir, --plugin-url, --agents, Agent SDK plugins 옵션, 비-SDK --mcp-config를 시작 시 거부하고 CLAUDE_CODE_PLUGIN_DIRS 변수의 폴더도 같게 거부	.mcp.json, claude mcp add, SDK 제공 서버는 제한 못 함. allowedMcpServers와 함께 사용
disableCommandPluginSources	command 소스(기기에서 명령을 실행해 플러그인 디렉터리를 만드는 소스) 플러그인의 설치·업데이트·로드 차단. 미설정이면 allowManagedHooksOnly 값을 따름	다른 소스 타입은 영향 없음
allowManagedHooksOnly	실행되는 hook 제한. allowManagedHooksOnly	사용자가 직접 켠 플러그인의 hook을 신뢰하지는 않음
strictPluginOnlyCustomization	플러그인, managed settings, Claude Code 내장이 아닌 skill, agent, hook, MCP 서버 차단. skills-directory 플러그인도 로드 중단. true면 네 타입 전부, skills, agents, hooks, mcp 배열(예 ["skills", "hooks"])이면 일부	사용자가 설치하는 플러그인은 제한하지 않음. strictKnownMarketplaces와 함께 사용
pluginSuggestionMarketplaces	플러그인이 설치 제안으로 나올 수 있는 마켓. 플러그인 추천	내장 tip은 영향 없음
pluginTrustMessage	플러그인 설치 전 /plugin이 보여주는 신뢰 경고에 텍스트 추가	경고 자체 문구는 못 바꿈
allowedChannelPlugins	channel 메시지를 push할 수 있는 플러그인의 기본 목록 대체. channelsEnabled: true 필요	Restrict which channel plugins can run
CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1	인터랙티브 터미널 세션의 공식 마켓 자동 등록 중단	이미 등록된 마켓은 제거 안 함. 변수 없이도 allowlist/blocklist가 같은 자동 등록을 게이트. 설정한 채 한 번 시작한 기기는 해제해도 자동 등록 재개 안 됨
allowManagedModsOnly	조직 것으로 인정되지 않는 설치된 mod의 hook 실행 중단	mod가 든 플러그인의 설치 자체는 못 막음. 그것은 이 표의 마켓 키

표의 모든 키는 enabledPlugins, syncClaudeAiPlugins, CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL, allowManagedModsOnly를 제외하고 managed setting입니다.

• enabledPlugins: 어느 scope에서나 설정 가능, managed settings가 잠금
• syncClaudeAiPlugins: 사용자도 자기 user/local settings에 설정 가능. settings reference의 scope
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: managed env 블록으로 전달하는 환경 변수 (전체 기기군 업데이트 끄기)
• allowManagedModsOnly: 내장 플러그인의 옵션이며 managed settings의 pluginConfigs 아래 설정. Stop user-installed mods from loading

각 settings 키는 settings reference에 항목이 있습니다.

마켓 키 별칭

strictKnownMarketplaces는 allowedMarketplaces, extraKnownMarketplaces는 additionalMarketplaces로도 쓸 수 있습니다.

• 버전: 별칭은 Claude Code v2.1.232 이상 필요. 이전 클라이언트는 무시. 혼합 기기군이 읽는 파일에서는 정식 이름을 유지
• 두 철자 모두 설정: 정식 키 값이 적용

strictKnownMarketplaces allowlist

다음 source 객체의 목록으로 설정합니다. 대부분 정확히 일치하고 hostPattern·pathPattern은 정규식, github owner 와일드카드는 owner로 일치합니다.

• github: { "source": "github", "repo": "your-org/approved-plugins" }, 선택적 ref, path
• github owner 와일드카드: { "source": "github", "repo": "your-org/*" }는 그 owner의 모든 저장소. *는 저장소 이름 전체여야 함. */plugins, your-org/tools-*는 잘못된 항목으로 무시되어 아무것도 안 맞음. Claude Code v2.1.223 이상
• git: { "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }, 선택적 ref, path
• url: { "source": "url", "url": "https://plugins.example.com/marketplace.json" }, 선택적 headers
• file, directory: { "source": "file", "path": "/opt/marketplace/marketplace.json" } 또는 { "source": "directory", "path": "/opt/marketplace/plugins" }, 절대 경로
• hostPattern: { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }. github, git, url 소스의 호스트에 일치. 호스트 이름 어디에나 맞으므로 ^, $로 고정. github 소스는 항상 github.com으로 취급. 개발자가 자기 마켓을 만드는 GitHub Enterprise Server나 GitLab 호스트에 사용. 예는 GHES 페이지
• pathPattern: { "source": "pathPattern", "pathPattern": "^/opt/approved/" }. file, directory 소스의 path에 일치. 경로 어디에나 맞으므로 디렉터리 접두사는 ^로 시작. ".*"는 모든 로컬 경로 허용
• skills-dir: { "source": "skills-dir" }는 어떤 마켓에도 맞지 않음. skills-directory 플러그인 로드 유지

항목 일치 방식

url 항목은 url 값으로 일치하며 headers는 비교하지 않습니다. github, git 항목은 repo/url, ref, path가 모두 일치하거나 양쪽 모두 없어야 합니다.

• ref 없는 항목은 ref: "main"인 소스를 덮지 않음
• your-org/your-marketplace 항목은 같은 저장소를 clone하는 git URL을 덮지 않음
• 끝 슬래시, .git 접미사, https:// 대신 ssh://는 다른 값. 마켓을 여러 URL로 clone할 수 있으면 hostPattern 항목을 권장

owner 와일드카드 항목은 ref 규칙을 그대로 따르고 항목이 고정하지 않는 한 저장소 안의 모든 path에 맞습니다. allowlist의 와일드카드 일치는 대소문자를 구분합니다.

skills-directory 플러그인 로드 유지

skills-directory 플러그인은 ~/.claude/skills/나 프로젝트 .claude/skills/ 아래, .claude-plugin/plugin.json이 있는 폴더의 플러그인입니다. { "source": "skills-dir" } 항목 없이 allowlist를 설정하면 로드되지 않습니다. strictPluginOnlyCustomization으로 어떤 customization 타입이든 잠그면 항목 유무와 관계없이 로드되지 않습니다. allowlist는 매니페스트 없는 SKILL.md인 일반 skill에는 적용되지 않습니다.

claude.ai에서 호스팅되는 마켓

allowlist와 blocklist는 claude.ai에서 호스팅되는 마켓을 호스트로 일치시킵니다. 허용/차단하려면 strictKnownMarketplaces 또는 blockedMarketplaces에 claude.ai에 맞는 hostPattern 항목을 추가합니다. allowlist에서는 조직의 claude.ai 마켓과 claude.ai 기본 마켓은 허용하지만 구성원 자신의 claude.ai 업로드로 된 마켓이나 scope를 밝히지 않은 마켓은 허용하지 않습니다. Claude Code v2.1.273 이상.

모든 소스 잠금

빈 allowlist []는 공식 마켓 포함 모든 마켓 소스를 잠급니다. 이 잠금은 마켓이 아니라 각 사용자 계정에서 내려받는 claude.ai에서 sync된 플러그인을 덮지 않습니다. 함께 막으려면 managed settings에서 syncClaudeAiPlugins를 false로 하거나 claude.ai에서 조직의 Skills를 끄세요.

blocklist: blockedMarketplaces

strictKnownMarketplaces와 같은 source 객체를 받고 먼저 검사되므로 두 목록에 모두 있는 소스는 차단됩니다. blocklist 일치는 allowlist보다 넓습니다.

• git URL이 정규화되어 한 github.com 저장소의 git@/https:// 형태, .git 접미사, 끝 슬래시가 모두 같은 항목에 맞음
• github 항목은 동등한 git URL도 차단하고 그 반대도 마찬가지
• owner/* 항목은 owner 비교가 대소문자 무시
• ref나 path가 없는 항목은 맞는 저장소의 모든 ref와 path를 차단

한 GitHub owner 아래 모든 저장소를 차단하는 항목:

{
  "blockedMarketplaces": [
    { "source": "github", "repo": "untrusted-org/*" }
  ]
}

blockedMarketplaces의 url 항목은 사용자가 Claude Code가 가져오는 대신 clone하는 https:// 저장소 URL(bare github.com, gitlab.com 저장소 URL 등)을 추가할 때도 적용됩니다. 항목이 이름을 지목하면 그 URL을 추가할 수 없습니다. .git 접미사와 사용자가 # 뒤에 붙인 ref는 무시하고 일치합니다. Claude Code v2.1.232 이상.

여기의 { "source": "skills-dir" } 항목은 ~/.claude/skills/와 프로젝트 .claude/skills/ 모두의 skills-directory 플러그인 로드를 막습니다. 이 항목만 담은 blocklist는 활성 제한으로 치지 않으므로 마켓을 찾지 못하는 플러그인의 로드를 막지 않습니다.

공식 마켓플레이스와 자체 마켓 허용

두 마켓을 허용하고 등록하고, 플러그인 둘을 강제 활성화하고, --plugin-dir를 거부하는 managed settings 정책:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "your-org/*" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
    },
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" }
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  },
  "disableSideloadFlags": true
}

이 정책의 기기에서 목록 밖 소스(예: /plugin marketplace add https://example.com/other-marketplace.git)를 추가하면 is blocked by enterprise policy와 허용된 소스 목록이 담긴 메시지로 실패합니다. claude --plugin-dir ./x는 disableSideloadFlags를 명시한 메시지로 종료됩니다. 이 allowlist에서 { "source": "skills-dir" }를 빼면 skills-directory 플러그인이 로드되지 않습니다.

allowlist나 공식 마켓의 자체 등록에 의존하지 말고 이 정책처럼 두 마켓을 명시적 extraKnownMarketplaces 항목으로 등록하세요.

• allowlist는 아무것도 등록하지 않음: extraKnownMarketplaces 항목이 등록하며 그 항목도 allowlist를 통과해야 함. allowlist에 맞지 않는 소스의 managed 마켓은 등록을 거부
• 공식 마켓은 인터랙티브 터미널 세션에서만 스스로 등록: 거기서도 allowlist가 허용할 때만. -p 실행이나 cloud 세션에 붙은 터미널은 등록하지 않음
• 차단 시도는 기억됨: 기기가 공식 마켓을 막는 정책([] 잠금 등) 아래 돌았다면 Claude Code가 차단 시도를 기록해 정책이 바뀐 뒤에도 재시도하지 않음. 그 기기는 위 정책 같은 extraKnownMarketplaces 항목, 그 플러그인 하나의 enabledPlugins 항목, 수동 /plugin marketplace add로만 다시 등록됨

업데이트 정책

마켓별, 전체 기기군, 또는 release channel로 사용자 그룹별로 정합니다.

마켓별 auto-update 켜기/끄기

플러그인 auto-update는 켜진 마켓에 대해 시작 후 백그라운드로 실행됩니다. 기본으로 켜진 마켓은 When auto-update runs. 기기군 전체를 정하려면 managed extraKnownMarketplaces 항목에 "autoUpdate": true 또는 false.

• managed 항목이 필드를 설정하면 사용자의 /plugin 토글을 Auto-update for '<name>' is set by로 시작하는 오류로 거부
• 비워 두면 사용자 토글이 유지됨

전체 기기군 업데이트 끄기

모든 마켓의 플러그인 auto-update를 끄려면 managed env 블록에 DISABLE_AUTOUPDATER를 설정합니다. 같은 변수가 Claude Code 자체 업데이트도 멈춥니다.

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Claude Code 자체 업데이트는 멈추되 플러그인 auto-update는 유지하려면 같은 블록에 "FORCE_AUTOUPDATE_PLUGINS": "1"을 추가하세요. 플러그인 auto-update를 멈추는 다른 환경 변수도 같게 동작합니다. DISABLE_AUTOUPDATER는 command 소스 플러그인을 덮지 않습니다. Claude Code는 활성화된 각 command 소스 플러그인의 명령을 세션마다 다시 실행해 출력이 바뀌었으면 설치합니다. 그 실행을 멈추는 것은 When a command source re-runs.

사용자 그룹에 release channel 할당

stable과 early-access channel을 운영하려면 같은 플러그인의 서로 다른 ref를 가리키는 마켓 둘을 호스팅하고, 그룹마다 별도 endpoint-managed settings나 gateway 정책으로 자기 마켓을 줍니다. 관리 콘솔의 server-managed settings는 조직 모든 사용자에게 적용되므로 그룹별로 다르게 할당할 수 없습니다.

• 각 그룹 기기에 별도 endpoint-managed settings(파일이나 MDM 프로필) 배포. 조직 전체 소스가 있는 기기에서 그룹별 파일/프로필이 적용되는지는 How Claude Code combines managed sources
• 그룹마다 Claude apps gateway 정책 하나. gateway는 match 규칙이 맞는 첫 정책을 적용하므로 각 사용자가 자기 그룹 정책에 닿게 정렬. 그 정책의 extraKnownMarketplaces 맵은 다른 정책과 병합되지 않으니 channel 마켓만이 아니라 그룹이 필요한 모든 마켓을 나열

stable 그룹이 받는 구성:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": { "source": "github", "repo": "your-org/stable-tools" }
    }
  }
}

early-access 그룹은 latest-tools를 받습니다. 마켓 둘 구성은 Run release channels.

플러그인 추천

마켓 소유자가 항목에 relevance 신호를 붙이면 프로젝트가 맞을 때 Claude Code가 플러그인을 제안합니다. 제안은 마켓이 사용자 기기에 등록돼 있고, managed settings의 pluginSuggestionMarketplaces에 이름이 있고, 같은 정책에 소스가 선언되어 있을 때만 나옵니다. 소스는 마켓의 extraKnownMarketplaces 항목이나 allowlist 항목으로 선언합니다. 공식 마켓은 이름만 필요합니다. Enable suggestions in managed settings.

감사와 검토

OpenTelemetry 이벤트와 Analytics API로 기기군이 설치하고 실행하는 것을 알 수 있습니다. 플러그인이 기기에서 실행할 수 있는 것과 신뢰 tier별 허용은 마켓을 승인하기 전에 Plugin security를 읽으세요.

OpenTelemetry 이벤트

claude_code.plugin_installed는 각 설치를, claude_code.plugin_loaded는 세션 시작 시 활성화된 각 플러그인을 기록합니다. OTEL_LOG_TOOL_DETAILS=1을 설정하지 않으면 두 이벤트 모두 서드파티 플러그인과 마켓 이름을 가리거나 생략합니다 (Redacted plugin names in your backend). 필드 목록은 Plugin installed event, Plugin loaded event.

Analytics API

Enterprise 플랜에서 GET /v1/organizations/analytics/plugins는 Claude Code와 Cowork 전반의 플러그인별·일별 설치·호출 수를 반환하며 사용자나 RBAC 그룹으로 묶을 수 있습니다. 이름 없이 Anthropic에 도달한 플러그인 활동은 third-party 집계 행 하나로 나옵니다. endpoint reference와 필요한 키는 Access data programmatically.

managed settings가 강제하지 못하는 것

보안 검토에서 나오는 다음 요청은 현재 settings 스키마에 전용 키가 없습니다. 가장 가까운 제어:

• 사용자/그룹별 대상: 모든 플러그인 키는 설정을 받는 모든 사용자에게 적용. server-managed settings는 조직당 구성 하나. 그룹별 정책은 별도 endpoint-managed settings나 gateway 정책 (사용자 그룹에 release channel 할당)
• 허용된 마켓 안의 항목 제한: allowlist는 마켓 소스에 맞춤. 허용된 마켓의 플러그인 하나를 막으려면 managed enabledPlugins에서 false
• /plugin 숨기기: 명령을 끄는 키 없음. 가장 가까운 조합은 내 마켓만 지목한 allowlist + 제공할 플러그인의 managed enabledPlugins 항목 + disableSideloadFlags
• allowlist로 --plugin-dir 게이트: allowlist는 --plugin-dir를 덮지 않음. disableSideloadFlags가 덮음
• claude.ai 플러그인 토글을 이 키들로 강제: Organization settings > Plugins & skills는 이 페이지의 키를 설정하지 않음. 거기서 구성원과 조직이 켠 것은 자체 제어를 가진 synced plugins로 CLI에 도달

정책 문제 해결

• managed 파일 파싱 실패: managed-settings.json이 유효한 JSON이 아니면 Claude Code가 시작을 거부하고 파일을 지목한 오류를 출력. 파싱되지만 항목 하나가 잘못된 파일은 나머지 정책을 유지 (Invalid entries in managed settings)
• managed 소스 미로드: /status에서 Setting sources 줄의 Enterprise managed settings를 찾음. 없으면 소스가 로드되지 않은 것
• 사용자가 blocked by enterprise policy 보고: 메시지가 마켓이나 소스를 지목. allowlist면 허용 소스도 나열. 사용자용 항목은 Troubleshoot plugins
• 사용자가 ~/.claude/settings.json에서 비활성한 플러그인이 여전히 로드: managed enabledPlugins 강제 활성화 같은 다른 settings 소스가 다시 켠 것. /plugin과 claude plugin list가 해당 settings 소스와 함께 Disabled in ~/.claude/settings.json but still loads를 표시

체크리스트

• 전달 방식(server-managed / MDM / 파일)과 적용되는 managed 소스 확인
• extraKnownMarketplaces + enabledPlugins로 롤아웃, /plugin이나 init 이벤트로 확인
• 제한은 strictKnownMarketplaces(또는 blockedMarketplaces) + disableSideloadFlags, skills-dir 항목 여부 결정
• 컨테이너/CI는 CLAUDE_CODE_PLUGIN_SEED_DIR seed + enabledPlugins
• 업데이트 정책(autoUpdate, DISABLE_AUTOUPDATER) 결정
• OpenTelemetry/Analytics API로 감사

함께 보기

• Marketplace reference: extraKnownMarketplaces, strictKnownMarketplaces, blockedMarketplaces가 받는 source 값
• Host and maintain a marketplace
• Plugin security and trust
• Manage mods for your organization
• Server-managed settings
• Troubleshoot plugins: 정책이 막을 때 사용자가 보는 메시지

기준일

• 문서 작성·동기화 기준일: 2026-10-23 (v2.1.309 반영)
• 원문: https://code.claude.com/docs/en/plugins/org