[Claude Code] archive 소스로 플러그인을 zip으로 설치해요

[Claude Code] archive 소스로 플러그인을 zip으로 설치해요

Claude Code 플러그인을 zip 하나로 설치해요. 받는 머신에 git이나 npm이 없어도 됩니다. 2.1.224 changelog에 올라온 archive 플러그인 소스 얘기예요.

01. 정적 파일 서버에 zip만 올려두면 돼요

기존 플러그인 소스는 github, url, git-subdir, npm처럼 대부분 git이나 패키지 매니저를 거치는 방식이었어요. archive는 HTTPS로 zip을 받아오는 게 전부예요.

공식 문서에는 S3 버킷, Artifactory generic 저장소, nginx 같은 정적 파일 서버나 아티팩트 저장소 어디든 올려두면 된다고 나와 있어요. marketplace.json의 플러그인 항목에 이렇게 적어요.

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

배포하는 쪽은 아티팩트 서버에 zip을 올리는 것으로 끝나고, 받는 쪽은 git 자격증명이나 npm 레지스트리 설정을 거치지 않아요.

02. sha256을 박으면 파일이 바뀐 순간 설치를 거부해요

문서 기준으로, source 안에 sha256 필드를 넣으면 다운로드한 파일의 다이제스트를 매번 검증해요. 64자 hex 문자열이고 대소문자는 가리지 않아요.

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

값이 안 맞으면 설치를 멈추고 Plugin archive integrity check failed 오류를 내요. 같은 URL에 새 zip을 덮어쓰는 운영 방식이라면 핀을 박아두는 쪽이 사고를 덜 냅니다.

업데이트 쪽에는 문서에 적힌 함정이 하나 더 있어요. sha256이 버전 역할을 하는 건 plugin.json에도 마켓플레이스 항목에도 version이 없을 때뿐이에요. version을 선언해뒀다면 zip과 다이제스트를 바꿔도 version을 안 올리는 한 사용자는 캐시된 예전 사본을 그대로 씁니다.

03. 최상위 두 겹까지만 열어보고 http:// URL은 거부해요

zip은 두 가지 모양을 다 받아요. .claude-plugin/ 폴더가 압축 최상단에 있어도 되고, 최상위 폴더 하나 안에 들어 있어도 돼요. 문서에는 그보다 더 깊이 들어간 플러그인은 설치가 실패한다고 적혀 있어요.

URL 쪽 제약도 같이 확인해두는 게 좋아요. 문서에 적힌 조건은 네 가지예요.

• 256 MiB를 넘는 아카이브는 거부해요
• http:// URL은 받지 않아요
• loopback·link-local·클라우드 메타데이터 호스트로 향하는 주소는 막혀요
• 리다이렉트가 걸리면 매 홉이 같은 조건을 만족해야 다운로드가 진행돼요

사내 아티팩트 서버 주소를 그대로 옮겨 적었다가 마지막 항목에서 막히는 경우가 나올 수 있어요.

04. 버전이 낮으면 마켓플레이스가 통째로 안 열려요

archive는 Claude Code v2.1.224 이상에서만 동작해요. 문제는 그 아래 버전의 반응이 서로 다르다는 점이에요.

v2.1.120부터 v2.1.223까지는 해당 플러그인 설치만 실패하면서 "This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again."이라는 안내가 떠요. 더 낮은 버전에서는 archive 항목이 하나라도 들어간 마켓플레이스 파일 자체가 로드되지 않아요. 팀에 배포하는 마켓플레이스라면 다른 플러그인까지 같이 안 보이게 되는 셈이에요.

하나 더, Team·Enterprise 플랜의 조직 설정으로 마켓플레이스를 배포할 때는 archive와 npm 소스를 쓸 수 없어요. 이 경로에서 지원하는 건 github, url, git-subdir와 마켓플레이스 저장소 안을 가리키는 상대 경로예요.

출처: Claude Code Docs — Create and distribute a plugin marketplace, Claude Code CHANGELOG 2.1.224

이 글은 공식 발표 내용을 정리한 것이고, Anthropic으로부터 어떤 형식의 협찬도 받지 않았습니다.