클로드코드 /setup-vertex — 구글 Vertex AI 연결 설정하기

회사가 구글 클라우드(GCP)를 쓰거나, 보안 정책상 GCP를 거쳐 모델을 호출해야 하는 경우가 있습니다. /setup-vertex는 이럴 때 클로드코드를 구글 Vertex AI에 연결해주는 설정 명령입니다.

정의 (뭐냐면)

/setup-vertex는 구글 Vertex AI(GCP의 AI 모델 운영 플랫폼) 연결을 설정하는 명령입니다. 이 환경을 쓰는 사용자에게만 해당되는 기능이에요.

Vertex AI란 구글 클라우드에서 여러 AI 모델을 불러 쓰게 해주는 서비스입니다. 회사가 GCP 환경을 쓴다면, 클로드코드가 모델을 직접 호출하는 대신 Vertex를 거쳐 동작하도록 맞출 수 있어요. 자격증명(클라우드 접속 권한 정보)과 프로젝트(project, GCP에서 자원을 묶는 단위) 설정이 필요해 고급 분류에 들어갑니다.

어떻게 쓰나 (난이도별)

기초 — Vertex 연결 설정

입력창에 이렇게 칩니다.

/setup-vertex

그러면 Vertex 인증과 프로젝트를 설정하는 절차가 시작됩니다. 안내에 따라 GCP 자격증명과 사용할 프로젝트를 지정하면 연결이 맞춰져요. 자격증명은 사람마다 다르므로, 회사에서 발급받은 본인 값을 그 자리에 넣으면 됩니다. 예를 들면 다음처럼 자리에 들어갈 항목을 채우는 식입니다.

GCP 프로젝트 ID: <사용할_프로젝트_ID>
리전: <사용할_리전_예: asia-northeast3>
서비스 계정 키 경로: <발급받은_키파일_경로>

흔한 함정

• 이 명령은 Vertex 환경을 쓰는 사용자에게만 해당됩니다. 개인 계정으로 일반 사용 중이라면 설정할 필요가 없어요.
• 자격증명과 서비스 계정 키는 비밀번호처럼 민감한 정보입니다. 위 예시의 <...> 부분은 자리표시자일 뿐, 실제 값은 회사 보안 절차에 따라 안전하게 다뤄야 하고 외부에 노출되지 않게 주의하세요.
• 프로젝트 ID와 리전을 잘못 넣으면 연결이 안 됩니다. 회사가 지정한 값을 정확히 확인하고 입력하세요.

실전 사례

데이터를 GCP 안에서만 처리해야 하고 인프라가 모두 구글 클라우드에 있는 팀에 잘 맞습니다. /setup-vertex로 환경에 맞춰 연결해두면, 회사 인프라 규칙을 지키면서 클로드코드를 그대로 쓸 수 있어요.

이렇게 더 씁니다

AWS 환경이라면 같은 방식으로 동작하는 /setup-bedrock이 따로 있습니다. 설정 전반을 다루는 /config와 함께 보면, 우리 팀 환경에 맞는 연결 상태를 점검하고 정돈하기 좋아요. 설정 전에 클라우드 담당자에게 프로젝트 ID와 자격증명을 미리 받아두면 한 번에 끝납니다.

정리

/setup-vertex는 클로드코드를 구글 Vertex AI에 연결하는 설정 명령입니다(해당 환경 사용자 한정). GCP 인프라 규칙에 맞춰 인증과 프로젝트를 맞추면, 정책을 지키면서 그대로 작업할 수 있어요. 자격증명은 자리표시자가 아닌 본인 값으로, 노출되지 않게 다루는 게 핵심입니다.

기준: Claude Code v2.1.154 (2026.05)