클로드 코드 플러그인 압축 파일 인증 — 헤더 도우미와 설치마다 묻는 명령

사내 저장소에 올린 플러그인 압축 파일을 여러 개 한꺼번에 설치했는데 하나만 빠졌다면, 그 플러그인에 인증용 명령이 붙어 있었을 수 있습니다. 그런 플러그인은 따로 한 번씩 설치해야 합니다.

비공개 마켓플레이스 글에서 깃 기반 마켓플레이스는 사용자 기기의 깃 인증을 따른다고 정리했는데, 압축 파일 출처는 사정이 다릅니다. 깃 없이 웹으로 파일을 내려받기 때문에, 인증이 필요하면 다운로드 요청에 헤더를 붙여야 합니다. 마켓플레이스 호스팅 문서에는 고정 헤더와, 매번 명령을 실행해 헤더를 만드는 헤더 도우미를 어디에 두고 어떻게 쓰는지가 자세히 나와 있습니다.

짧게 정리하면

• 헤더나 헤더 도우미는 마켓플레이스의 주소 출처나 플러그인 항목에 둘 수 있고, 둘 곳에 따라 헤더가 붙는 다운로드와 명령이 실행되는 시점이 다릅니다.
• 플러그인 항목에 둔 명령은 사용자가 그 플러그인 하나를 설치하거나 갱신할 때마다 명령과 주소를 보고 수락해야 실행됩니다.
• 여러 개 한꺼번에 설치, 추천, 의존성, 백그라운드 자동 갱신에서는 명령을 실행하지 않고 그 플러그인을 거절하거나 오류 탭에 올립니다.

클로드 코드 공식 문서의 마켓플레이스 호스팅 쪽 중 압축 파일 다운로드 인증 절을 처음부터 끝까지 대조했습니다. 필드와 환경 변수 이름은 본문 표기 원칙에 따라 우리말로 풀어 적었습니다.

어디에 두느냐가 동작을 가른다

헤더를 둘 수 있는 곳은 두 군데입니다. 하나는 마켓플레이스를 등록할 때 쓴 주소 출처이고, 다른 하나는 마켓플레이스 파일 안 플러그인 항목입니다. 항목에 두는 방식은 2.1.238판부터입니다. 값이 오래 유지되는 고정 헤더라면 헤더 칸을, 저장소가 요청할 때마다 새로 발급하는 짧은 토큰이라면 헤더 도우미 명령을 씁니다. 헤더 도우미도 2.1.238판 이상이 필요합니다.

마켓플레이스 호스팅 문서 기준, 헤더를 두는 곳별 동작

두는 곳	헤더가 붙는 다운로드	헤더 도우미가 실행되는 때
마켓플레이스 주소 출처	마켓플레이스 주소와 같은 출처(방식·호스트·포트가 같은 곳)의 압축 파일	마켓플레이스 파일을 받을 때마다, 그 출처의 압축 파일을 받을 때마다, 한 번 실행 결과를 최대 60초 재사용
플러그인 항목	그 항목의 다운로드만	그 플러그인 하나를 따로 설치·갱신하면서 사용자가 명령을 수락했을 때만

두 곳에 같은 이름의 헤더가 있으면 항목 쪽 값을 보냅니다. 한 곳 안에서는 명령이 출력한 헤더가 헤더 칸의 같은 이름을 덮어씁니다. 항목에 헤더 도우미를 넣으려면 그 항목에 엄격 모드 끄기를 함께 적어야 한다는 조건도 문서에 있습니다.

헤더 도우미 명령의 조건

명령 문자열은 인쇄 가능한 아스키 문자로 500자까지이고, 공백 네 개 이상이 이어지면 안 됩니다. 실행하면 헤더 이름과 문자열 값으로 된 객체 하나를 표준 출력에 찍고, 10초 안에 정상 종료해야 합니다. 셸은 유닉스 계열에서 기본 셸, 윈도우에서 명령 프롬프트이고, 작업 폴더는 사용자의 클로드 설정 폴더입니다. 그래서 상대 경로를 쓰면 프로젝트가 아니라 설정 폴더 기준으로 풀리니 절대 경로나 실행 경로의 명령을 써야 합니다.

자격 증명처럼 보이는 환경 변수는 명령에 넘어가지 않습니다. 명령이 마켓플레이스 파일의 항목이나 프로젝트 설정 파일에 들어 있으면, 클로드 코드는 이름이 자격 증명처럼 보이는 변수를 전부 빼고 실행합니다. 문서는 앤트로픽 API 키 변수도, 내 저장소 토큰 같은 이름의 변수도 빠진다고 예를 들고, 명령이 자격 증명을 파일이나 자격 증명 저장소에서 읽게 만들라고 안내합니다. 사용자 설정, 시작 시 넘긴 설정, 관리 설정에 둔 명령에는 이 제거가 적용되지 않습니다. 환경 변수로 토큰을 넘기는 스크립트를 그대로 가져다 쓰면 항목 쪽에서는 빈 토큰으로 실패합니다.

대신 클로드 코드가 넣어 주는 변수가 있습니다. 주소 출처의 명령에는 마켓플레이스 주소와 이름이, 항목의 명령에는 플러그인 이름과 압축 파일 주소가 들어갑니다. 주소로 마켓플레이스를 처음 추가한 직후의 첫 요청에서는 이름이 아직 없어서 이름 변수가 비어 있습니다.

명령이 실행되지 않거나 헤더가 빠지는 경우도 정리돼 있습니다. 명령이 실패하거나 10초를 넘기거나 올바른 객체를 찍지 않으면 해당 다운로드가 일어나지 않습니다. 마켓플레이스 주소가 보안 웹 주소가 아니면 주소 출처의 명령은 돌지 않습니다. 다운로드가 다른 출처로 전환되면 그 요청에는 어떤 헤더도 붙지 않습니다. 항목의 헤더에서 호스트, 쿠키 같은 경로·신원 헤더는 빠지고 인증 헤더는 남습니다. 관리 설정의 명령 출처 차단이 켜져 있으면 헤더 도우미도 막히고, 관리 훅만 허용 설정도 명령 출처 차단을 명시적으로 거짓으로 두지 않는 한 막습니다. 단 관리 설정이 직접 선언한 마켓플레이스의 명령은 돕니다. 이 조건은 조직 플러그인 관리 글의 통제 표와 이어집니다.

명령은 매번 수락해야 돈다

플러그인 항목에 둔 명령은 사용자가 그 플러그인 하나를 설치하거나 갱신할 때마다 수락해야 합니다. 플러그인 관리 창의 해당 플러그인 화면이나 셸의 설치·갱신 명령에서 클로드 코드가 명령과 압축 파일 주소를 보여 주고, 수락한 뒤에만 실행합니다. 보여 준 뒤에 명령이나 주소가 바뀌었다면 설치를 거부하는데, 쿼리 문자열만 바뀐 건 변경으로 치지 않습니다. 비대화형 셸에서는 확인 옵션으로 수락하거나, 앞선 결과에서 받은 지문을 넘겨 그 명령만 수락할 수 있습니다.

마켓플레이스 호스팅 문서 기준, 명령을 묻지 않고 거절하는 경우

상황	결과
여러 개 한꺼번에 설치, 플러그인 추천으로 설치, 다른 플러그인의 의존성으로 설치	명령 있는 플러그인만 거절하고 그 플러그인 화면으로 안내, 나머지는 설치, 그 플러그인에 의존하는 플러그인은 설치 실패
백그라운드 자동 갱신, 한 번도 받은 적 없는 플러그인의 세션 시작	오류 탭에 올려 사용자가 직접 설치·갱신하도록 함

첫째 줄의 의존성 경우는 플러그인 의존성 글에서 본 규칙과 맞물립니다. 인증 명령이 붙은 플러그인에 다른 플러그인이 의존한다면, 사용자는 인증 명령이 붙은 쪽을 먼저 따로 설치해야 합니다. 반면 주소 출처의 명령은 사용자 설정·시작 시 넘긴 설정·기기의 관리 설정에 있으면 백그라운드 갱신 중에도 묻지 않고 돌고, 프로젝트 설정에 있으면 그 폴더 자체의 작업 공간 신뢰를 받은 뒤에만, 서버 관리 설정이면 대화형 세션에서 보안 승인 창을 통과한 뒤에만 돕니다. 명령줄 한 번 실행이나 개발 도구 모음 세션, 상위 폴더에 준 신뢰는 폴더 신뢰로 치지 않습니다. 플러그인 보안 글에서 다룬 압축 파일 지문 검사와 함께 쓰면 받는 파일의 무결성까지 확인할 수 있습니다.

자주 묻는 질문

헤더 칸에 토큰을 그냥 적으면 안 되나요

고정 헤더는 적을 수 있지만, 문서는 저장소가 요청할 때마다 새로 발급하는 짧은 값이라면 헤더 도우미를 쓰라고 안내합니다. 마켓플레이스 파일은 여러 사람이 받는 파일이라는 점도 고려해야 합니다.

명령이 작업 폴더의 스크립트를 못 찾습니다

작업 폴더가 프로젝트가 아니라 클로드 설정 폴더라서, 상대 경로는 그 기준으로 풀립니다. 절대 경로나 실행 경로에 있는 명령을 쓰세요.

추가 폴더 옵션으로 불러온 설정의 명령은 도나요

추가 폴더 옵션으로 지정한 폴더의 설정에 든 명령은 무시되고, 그 파일의 고정 헤더만 보냅니다.

자동 갱신이 켜져 있는데 새 판이 안 들어옵니다

항목에 헤더 도우미가 있는 플러그인은 백그라운드 자동 갱신에서 명령을 돌리지 않고 오류 탭에 올립니다. 그 플러그인 화면에서 직접 갱신하면서 명령을 수락해야 합니다.

헤더 도우미는 편하지만, 사용자 기기에서 명령을 실행한다는 점에서는 훅이나 명령 출처 플러그인과 같은 무게로 봐야 합니다. 운영하는 쪽이라면 인증이 필요한 플러그인을 가능한 한 적게 두고, 사용자 안내 문서에 「이 플러그인은 따로 설치해야 한다」는 한 줄을 넣어 두는 것만으로도 문의가 꽤 줄 것 같습니다.

확인한 곳: 클로드 코드 공식 문서의 마켓플레이스 호스팅과 유지 중 압축 파일 다운로드 인증(두는 곳, 항목에 넣기, 명령 작성 조건, 실행이 건너뛰어지는 경우, 수락 방식, 묻지 않고 거절하는 경우, 주소 출처 명령이 도는 때). 2026년 9월 28일 기준입니다.