조직을 위한 Claude Code 플러그인 관리

​

플러그인 사전 설치 및 필수 설정

​

전달 메커니즘 선택

• 서버 관리 설정: 조직 설정 > Claude Code > 관리 설정에서 플러그인 키를 JSON으로 설정합니다. Claude 조직에서 소유자 역할이 필요합니다. 클라우드 세션은 플러그인을 설치하기 전에 이러한 설정을 가져옵니다.
• MDM 정책: macOS에서는 최상위 키가 설정 키인 plist를 전달합니다. Windows에서는 전체 JSON 문서를 레지스트리 값의 문자열로 저장합니다. plist 도메인과 레지스트리 키는 각 메커니즘이 정책을 저장하는 위치에 있습니다.
• 관리 설정 파일: 플랫폼의 시스템 경로에 managed-settings.json을 배치합니다. 옆의 managed-settings.d/ 드롭인 디렉터리에 파일을 추가할 수도 있습니다. 플랫폼별 파일 경로는 각 메커니즘이 정책을 저장하는 위치에 있으며, 드롭인 병합 규칙은 파일 기반 정책을 팀 간에 분할에 있습니다.

​

머신에 적용되는 관리 소스

​

마켓플레이스 및 해당 플러그인 필수 설정

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

• autoUpdate: true는 마켓플레이스와 해당 플러그인을 백그라운드에서 새로 고침 상태로 유지하고, false는 이를 끕니다. 업데이트 정책 설정을 참조합니다.
• source: github는 여러 소스 유형 중 하나입니다. git 소스는 GitLab 또는 내부 호스트의 url을 사용하고, url 소스는 호스팅된 marketplace.json의 주소를 사용합니다. 모든 소스 형태는 마켓플레이스 참조에 있습니다.

• 마켓플레이스: 관리 마켓플레이스 항목은 같은 이름의 낮은 우선순위 항목을 대체하며, 두 항목의 필드는 병합되지 않습니다.
• --plugin-dir 복사본: --plugin-dir은 한 세션 동안 로컬 디렉터리에서 플러그인을 로드합니다. 해당 복사본의 이름이 관리 enabledPlugins가 지정하는 플러그인과 일치할 때 발생하는 상황은 이름 충돌을 참조합니다.

​

저장소별 플러그인 필수 설정

• 대화형 세션: Claude Code는 기여자가 해당 폴더에 대한 작업 영역 신뢰 대화를 수락한 후에만 마켓플레이스를 등록합니다.
• 비대화형 -p 실행: 항목은 사용자가 이미 대화형으로 신뢰를 수락한 폴더 또는 ~/.claude.json에서 hasTrustDialogAccepted 플래그를 설정한 폴더에만 적용됩니다.

​

각 표면이 플러그인 키를 적용하는 시기

​

배포 확인

• 한 머신에서: Claude Code를 시작하고 /plugin을 실행합니다. 마켓플레이스와 플러그인이 나열됩니다.
• CI에서: --output-format stream-json --verbose와 함께 claude -p를 실행합니다. init 이벤트는 plugins 아래에 로드된 플러그인을 나열합니다.

​

컨테이너 및 CI 시드

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

• 읽기 전용: Claude Code는 시드에 절대 쓰지 않으며 시드 마켓플레이스에 대해 autoUpdate를 강제로 끕니다.
• 시드 항목이 우선: 각 시작 시 시드에서 선언된 마켓플레이스는 같은 이름의 사용자 항목을 덮어씁니다. 사용자는 마켓플레이스를 제거하는 대신 claude plugin disable로 시드 플러그인을 거부합니다.
• 업데이트 및 제거 실패: claude plugin marketplace update <name> 및 시드 마켓플레이스에서 --scope 없이 remove하면 시드 디렉토리의 이름을 지정하는 메시지와 함께 실패합니다.
• 정책이 여전히 적용됨: 허용 목록 및 차단 목록은 시드 마켓플레이스의 기록된 소스도 확인합니다. 시드를 빌드한 소스를 허용하세요.

​

사용자가 설치할 수 있는 것 제한

• 다운로드 전: 목록은 사용자가 마켓플레이스를 추가할 때 및 모든 설치, 업데이트, 새로 고침 및 자동 업데이트 시 적용됩니다.
• 세션 시작 시: 목록은 이미 설치된 플러그인에 다시 적용되므로 마켓플레이스 소스가 더 이상 일치하지 않는 설치된 플러그인은 로드되지 않습니다. /plugin은 Marketplace "<name>" is not in the allowed marketplace list 또는 Marketplace "<name>" is blocked by enterprise policy로 나열합니다.

• claude.ai 관리자 콘솔: Claude Code는 서버 관리 설정을 읽는 세션에서 두 목록을 적용합니다. claude.ai는 또한 조직의 누군가가 claude.ai에서 git 저장소에서 새 마켓플레이스를 추가하거나 Claude Desktop 앱의 Code 탭 외부에서 사용자 정의에서 추가할 때 확인합니다. 이는 멤버가 자신의 계정에 대해 추가하는 마켓플레이스 및 조직 설정 > 플러그인 아래에서 전체 조직에 대해 추가되는 마켓플레이스를 다룹니다. claude.ai는 허용 목록이 허용하지 않거나 차단 목록이 지정하는 저장소를 거부합니다. 목록을 설정하기 전에 어느 곳에서든 추가된 마켓플레이스를 다시 확인하지 않으며, 업로드된 플러그인을 확인하지 않습니다.
• 관리되는 설정 파일, OS 수준 정책 또는 기타 관리되는 소스: Claude Code는 해당 소스를 읽는 곳에서 두 목록을 적용합니다. claude.ai는 이를 읽지 않습니다.

​

제어 매트릭스

• enabledPlugins: 모든 범위에서 설정할 수 있으며 관리되는 설정이 이를 잠급니다.
• syncClaudeAiPlugins: 각 사용자는 자신의 사용자 또는 로컬 설정에서도 설정할 수 있습니다. 설정 참조에서 해당 범위를 참조하세요.
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: 이는 전체 플릿에 대해 업데이트 끄기 아래에 표시된 관리되는 env 블록을 통해 제공하는 환경 변수입니다.

​

마켓플레이스 키의 별칭

• 버전: 별칭은 Claude Code v2.1.232 이상이 필요하며, 이전 클라이언트는 이를 무시합니다. 혼합 플릿이 읽는 파일에서 정규 이름을 유지하세요.
• 두 철자 모두 설정: 파일이 두 철자를 모두 설정할 때 정규 키의 값이 적용됩니다.

​

strictKnownMarketplaces를 사용한 허용 목록

• github: { "source": "github", "repo": "your-org/approved-plugins" }, 선택적 ref 및 path 포함.
• github 소유자 와일드카드: { "source": "github", "repo": "your-org/*" }는 해당 소유자 아래의 모든 저장소와 일치합니다. *는 전체 저장소 이름을 나타내야 합니다. Claude Code는 */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 호스트에 hostPattern 항목을 사용하세요. GHES 페이지에 작동하는 예제가 있습니다.
• pathPattern: { "source": "pathPattern", "pathPattern": "^/opt/approved/" }, file 및 directory 소스의 path에 대해 일치합니다. 패턴은 경로의 어디든 일치하므로 디렉토리 접두사를 고정하려면 ^로 시작하세요. ".*"는 모든 로컬 경로를 허용합니다.
• skills-dir: { "source": "skills-dir" } 허용 목록이 설정되어 있는 동안 스킬 디렉토리 플러그인이 로드되도록 유지하고 마켓플레이스와 일치하지 않습니다.

​

항목이 일치하는 방법

• ref 없는 항목은 ref: "main"이 있는 소스를 다루지 않습니다.
• your-org/your-marketplace에 대한 항목은 같은 저장소를 복제하는 git URL을 다루지 않습니다.
• 후행 슬래시, .git 접미사 또는 https:// 대신 ssh://는 다른 값입니다. 마켓플레이스를 둘 이상의 URL로 복제할 수 있으면 hostPattern 항목을 선호하세요.

​

스킬 디렉토리 플러그인 로드 유지

​

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

​

모든 소스 잠금

​

blockedMarketplaces를 사용한 차단 목록

• Git URL은 정규화되므로 하나의 github.com 저장소의 git@ 및 https:// 형식, .git 접미사 및 후행 슬래시는 모두 같은 항목과 일치합니다.
• github 항목은 또한 동등한 git URL을 차단하고, 그 반대도 마찬가지입니다.
• owner/* 항목의 경우 소유자 비교는 대소문자를 구분하지 않습니다.
• ref 또는 path 없는 항목은 일치하는 저장소의 모든 ref 및 경로를 차단합니다.

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

​

공식 마켓플레이스 및 자신의 마켓플레이스 허용

{
  "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
}

• 허용 목록은 아무것도 등록하지 않습니다: extraKnownMarketplaces 항목이 등록하고, 자신이 허용 목록을 통과해야 합니다. Claude Code는 소스가 허용 목록과 일치하지 않는 관리되는 마켓플레이스를 등록하기를 거부합니다.
• 공식 마켓플레이스는 대화형 터미널 세션에서만 자신을 등록합니다: 거기서도 허용 목록이 이를 허용할 때만 등록합니다. -p 실행 또는 클라우드 세션에 연결된 터미널은 절대 등록하지 않습니다.
• 차단된 시도는 기억됩니다: 머신이 공식 마켓플레이스를 차단한 정책 아래에서 실행된 적이 있으면 Claude Code는 차단된 시도를 기록하고 정책이 변경된 후 재시도하지 않습니다. [] 잠금은 그러한 정책 중 하나입니다. 해당 머신은 이 정책의 항목과 같은 extraKnownMarketplaces 항목, 해당 플러그인 중 하나에 대한 enabledPlugins 항목 또는 수동 /plugin marketplace add를 통해서만 다시 등록합니다.

​

업데이트 정책 설정

​

마켓플레이스별 자동 업데이트 켜기 또는 끄기

• 관리되는 항목이 필드를 설정하면 Claude Code는 사용자의 /plugin 토글을 Auto-update for '<name>' is set by로 시작하는 오류로 거부합니다.
• 관리되는 항목이 필드를 설정하지 않으면 사용자의 토글이 유지됩니다.

​

전체 플릿에 대해 업데이트 끄기

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

​

사용자 그룹에 릴리스 채널 할당

• 각 그룹의 장치에 별도의 엔드포인트 관리 설정(예: 관리되는 설정 파일 또는 MDM 프로필)을 배포하세요. 조직 전체 소스도 있는 장치에 그룹별 파일 또는 프로필이 적용되는지 확인하려면 Claude Code가 관리되는 소스를 결합하는 방법을 참조하세요.
• 각 그룹에 대해 하나의 Claude 앱 게이트웨이 정책을 정의하세요. 게이트웨이는 일치 규칙이 사용자에게 맞는 첫 번째 정책을 적용하므로 각 사용자가 자신의 그룹의 정책에 도달하도록 정책을 정렬하세요. 해당 정책의 extraKnownMarketplaces 맵은 다른 정책의 것과 병합되지 않으므로 채널 마켓플레이스만이 아닌 그룹이 필요한 모든 마켓플레이스를 나열하세요.

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

​

플러그인 권장

​

감사 및 검토

​

OpenTelemetry 이벤트

​

Analytics API

​

관리되는 설정이 적용할 수 없는 것에 대해 계획

• 사용자별 또는 그룹별 타겟팅: 모든 플러그인 키는 설정을 받는 모든 사용자에게 적용됩니다. 서버 관리 설정은 조직별로 하나의 구성을 제공합니다. 그룹별 정책의 경우 사용자 그룹에 릴리스 채널 할당 아래처럼 별도의 엔드포인트 관리 설정 또는 게이트웨이 정책을 사용하세요.
• 허용된 마켓플레이스 내의 항목 제한: 허용 목록은 마켓플레이스 소스와 일치합니다. 허용된 마켓플레이스에서 하나의 플러그인을 차단하려면 관리되는 enabledPlugins에서 false로 설정하세요.
• /plugin 숨기기: 명령을 비활성화하는 키가 없습니다. 가장 가까운 동등은 자신의 마켓플레이스만 지정하는 허용 목록, 제공하는 플러그인에 대한 관리되는 enabledPlugins 항목 및 disableSideloadFlags를 결합합니다.
• 허용 목록을 통해 --plugin-dir 제어: 허용 목록은 --plugin-dir을 다루지 않습니다. disableSideloadFlags는 다룹니다.
• 이 키를 통해 claude.ai 플러그인 토글 적용: 조직 설정 > 플러그인 및 스킬은 이 페이지의 키를 설정하지 않습니다. 멤버 및 조직이 거기서 켜는 것은 CLI에 동기화된 플러그인으로 도달하며, 자신의 제어가 있습니다.

​

정책 문제 해결

• 관리되는 파일이 파싱되지 않음: managed-settings.json이 유효한 JSON이 아니면 Claude Code는 시작을 거부하고 파일의 이름을 지정하는 오류를 인쇄합니다. 파싱되지만 하나의 유효하지 않은 항목이 있는 파일은 나머지 정책을 유지합니다. 관리되는 설정의 유효하지 않은 항목을 참조하세요.
• 관리되는 소스가 로드되지 않음: /status를 실행하고 Setting sources 행에서 Enterprise managed settings를 찾으세요. 누락되면 소스가 로드되지 않았습니다.
• 사용자가 blocked by enterprise policy 보고: 메시지는 마켓플레이스 또는 해당 소스의 이름을 지정합니다. 허용 목록의 경우 허용된 소스도 나열합니다. 사용자 대면 항목은 플러그인 문제 해결에 있습니다.
• 사용자가 ~/.claude/settings.json에서 비활성화한 플러그인이 여전히 로드됨: 다른 설정 소스가 다시 활성화했습니다(예: 강제 활성화하는 관리되는 enabledPlugins 항목). /plugin 및 claude plugin list는 Disabled in ~/.claude/settings.json but still loads를 해당 설정 소스와 함께 표시합니다.

​

다음 단계

• 마켓플레이스 참조: extraKnownMarketplaces, strictKnownMarketplaces 및 blockedMarketplaces가 수락하는 source 값
• 마켓플레이스 호스팅 및 유지: 정책이 가리키는 마켓플레이스 실행
• 플러그인 보안 및 신뢰: 플러그인이 머신에서 할 수 있는 것 및 설치 전에 하나를 검토하는 방법
• 서버 관리 설정: claude.ai 관리자 콘솔에서 이 키를 제공
• 플러그인 문제 해결: 정책이 사용자를 차단할 때 사용자가 보는 메시지