안녕하세요 novice-22입니다.
이번 글은 Claude Console을 처음 세팅한 과정을 정리한 글입니다. claude.ai와 Console의 차이부터 시작해서 크레딧 설정, 워크스페이스와 API 키 발급에 대해 작성하였습니다.

1. claude.ai와 Console

1-1 둘의 차이

Max·Team 플랜에는 매달 API 크레딧이 포함되는데, 이 크레딧은 Console에서만 쓸 수 있다.

항목	claude.ai	Claude Console
대상	사용자 (직접 대화, 작업)	개발자 (내 프로그램에 Claude 연결)
결제	월정액 구독	종량제 (선불 크레딧)
사용처	웹/앱 채팅, Claude Code	API 호출, 스크립트, 에이전트, 외부 도구

두 결제는 섞이지 않는다. 같은 계정이어도 claude.ai 조직과 Console 조직은 서로 다른 조직이다.

2. 크레딧

2-1 월 API 크레딧 연결

Max 5x는 월 $100, Max 20x는 월 $200이 들어온다. claude.ai → Settings → Billing → API credits의 Link organization에서 크레딧을 받을 Console 조직을 고른다. 연결은 한 번만 가능하고 직접 바꿀 수 없다.

구분	대상
적용됨	Claude API, Console Playground, Agent SDK, API 키로 실행한`claude -p`
적용 안 됨	대화형 Claude Code, claude.ai 추가 사용량

크레딧은 이월되지 않고 결제 주기마다 만료된다.

2-2 결제 수단과 한도

Console은 선불이라 결제 수단을 등록하지 않고 자동 충전을 꺼두면 크레딧이 떨어져도 요청만 멈춘다. 지출 및 결제 화면에 결제 수단 없음이 보이면 된다.

월 지출 한도는 0으로 설정할 수 없고, 크레딧 사용분도 한도에 포함될 수 있다. $1처럼 너무 낮게 두면 크레딧이 남아 있어도 API가 멈추니 쓸 만큼(예: $50) 잡아둔다.

출처

Monthly API credits for Max and Team plans

3. 워크스페이스

설정 → 워크스페이스 → 워크스페이스 만들기에서 용도별 워크스페이스를 만든다. 예시로 security-research를 만들었다. 지역은 현재 미국만 선택할 수 있다.

조직마다 있는 Default 워크스페이스는 지울 수 없다. 키를 만들 때 범위를 전용 워크스페이스로 지정하면 되니 그대로 둔다.

4. API 키

4-1 개인용 키

키 및 액세스 → API 키 → 키 생성. "ID 페더레이션" 안내가 뜨면 API 키로 계속하기를 누른다. ID 페더레이션은 클라우드/CI 환경용이다.

항목	값
이름	`local-dev`
만료	30~90일
연결된 계정	본인
범위	`security-research`

키는 생성할 때 한 번만 보이니 바로 저장한다. 만료 연장은 안 돼서 새 키로 교체하는 방식으로 관리한다.

4-2 서비스 계정 키

외부 앱(Hermes Agent 등)에 넣을 키는 서비스 계정으로 발급한다. 요청 기록이 앱 이름으로 분리되고, 유출되면 그 계정만 끄면 된다. 개인 계정 키는 일부 도구에서 anthropic-workspace-id is required 오류가 날 수 있다.

키 및 액세스 → 서비스 계정 → 서비스 계정 만들기 (이름 hermes, 역할 개발자)
API 키 생성 시 연결된 계정을 서비스 계정으로 변경, 범위는 전용 워크스페이스

연결된 계정의 기본값이 본인이라, 바꾸지 않으면 개인 키가 만들어진다.

4-3 테스트

read -s ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-5-5","max_tokens":50,"messages":[{"role":"user","content":"안녕"}]}'

read -s로 받으면 키가 셸 기록에 남지 않는다.

4-4 주의할 점

평소 쓰는 Claude Code가 있는 환경에는 ANTHROPIC_API_KEY를 전역 환경변수로 넣지 않는다. 구독 대신 API 크레딧으로 과금된다. 키는 .env에 두고 .gitignore에 추가한다.

5. 마무리

claude.ai와 Console은 같은 계정이어도 조직과 결제가 따로라서, 크레딧 연결부터 조직 단위로 챙겨야 했다. 키는 용도별로 나누고 앱에 넣을 키는 서비스 계정으로 발급해두면 관리가 편하다. 월 API 크레딧은 이월되지 않으니 결제 주기 안에 쓰는 게 이득이다.

Claude Console(API) 설정 방법