인증 설정

읽는 시간: 5분 | 난이도: 초급자

Claude Code를 사용하기 위해 API 키를 안전하게 설정하는 방법을 안내합니다.

이 가이드에서는 Claude Code의 인증 설정을 안내합니다. API 키를 안전하게 관리하고 보안 모범 사례를 따르는 것이 중요합니다.

1. API 키 가져오기

Claude Code를 사용하려면 Anthropic API 키가 필요합니다.

Anthropic 계정 생성

1. Anthropic Console 방문
2. Sign Up 클릭
3. 이메일 주소 또는 GitHub로 계정 생성
4. 이메일 확인

API 키 생성

1. 콘솔에서 API Keys 섹션으로 이동
2. Create Key 버튼 클릭
3. 키 이름 입력 (예: claude-code-dev, claude-code-prod)
4. Create Key 클릭

중요: API 키는 생성 시 한 번만 표시됩니다. 안전한 곳에 저장하세요.

# API 키 예시
sk-ant-api03-XXXXXXXXXXXXX

2. 환경 변수에 API 키 설정

가장 권장되는 방법은 환경 변수를 사용하는 것입니다.

방법 1: 쉘 프로파일에 설정 (권장)

zsh 사용자 (macOS 기본):

echo 'export ANTHROPIC_API_KEY="sk-ant-api03-XXXXXXXXXXXXX"' >> ~/.zshrc
source ~/.zshrc

bash 사용자:

echo 'export ANTHROPIC_API_KEY="sk-ant-api03-XXXXXXXXXXXXX"' >> ~/.bashrc
source ~/.bashrc

fish 사용자:

echo 'set -x ANTHROPIC_API_KEY "sk-ant-api03-XXXXXXXXXXXXX"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

방법 2: .env 파일 사용

프로젝트별로 API 키를 관리하려면 .env 파일을 사용하세요:

# 프로젝트 루트 디렉토리에서
echo "ANTHROPIC_API_KEY=sk-ant-api03-XXXXXXXXXXXXX" > .env

# .gitignore에 추가
echo ".env" >> .gitignore

.env 파일 예시:

# .env
ANTHROPIC_API_KEY=sk-ant-api03-XXXXXXXXXXXXX
CLAUDE_LOG_LEVEL=info

방법 3: Claude Code 설정 파일

Claude Code 전용 설정 파일을 사용할 수도 있습니다:

# 설정 디렉토리 생성
mkdir -p ~/.claude

# 설정 파일 생성
echo "ANTHROPIC_API_KEY=sk-ant-api03-XXXXXXXXXXXXX" > ~/.claude/.env
chmod 600 ~/.claude/.env

3. API 키 확인

설정이 제대로 되었는지 확인하세요:

# 환경 변수 확인
echo $ANTHROPIC_API_KEY

# 또는
env | grep ANTHROPIC_API_KEY

정상적으로 설정되었다면 API 키가 표시됩니다:

$ echo $ANTHROPIC_API_KEY
sk-ant-api03-XXXXXXXXXXXXX

4. Claude Code 인증 테스트

Claude Code가 API 키를 인식하는지 확인하세요:

# Claude Code 실행
claude-code

# Claude Code 내에서 테스트
> 환경을 확인해줘

정상적으로 인증되었다면 다음과 같은 메시지가 표시됩니다:

API authentication successful
Model: claude-sonnet-4-6
Environment: development

5. 여러 API 키 관리

개발/프로덕션 환경을 분리하여 관리할 수 있습니다.

프로젝트별 설정

# 개발 환경
export ANTHROPIC_API_KEY_DEV="sk-ant-api03-DEV-KEY"
export ANTHROPIC_API_KEY_PROD="sk-ant-api03-PROD-KEY"

# 프로젝트에서 사용
export ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY_DEV

조건부 설정

zsh/bash:

# ~/.zshrc 또는 ~/.bashrc
if [ -f .env.dev ]; then
  export $(cat .env.dev | xargs)
elif [ -f .env.prod ]; then
  export $(cat .env.prod | xargs)
fi

fish:

# ~/.config/fish/config.fish
if test -f .env.dev
    set -gx (cat .env.dev | string split '=')
else if test -f .env.prod
    set -gx (cat .env.prod | string split '=')
end

6. 보안 모범 사례

1. API 키를 절대 커밋하지 마세요

# .gitignore에 반드시 추가
.env
.env.local
.env.*.local
*.key
claude-config.json

2. 권한 제한

# .env 파일 권한 제한
chmod 600 .env

# 설정 디렉토리 권한 제한
chmod 700 ~/.claude

3. 주기적으로 키 교체

• 개발 키: 30-90일마다 교체
• 프로덕션 키: 60-180일마다 교체
• 키가 노출되었다고 의심되면 즉시 교체

4. 사용량 모니터링

# Claude Code에서 사용량 확인
> 사용량을 확인해줘

또는 Anthropic Console에서 Usage 대시보드를 확인하세요.

5. IP 제한 설정 (프로덕션)

프로덕션 환경에서는 IP 제한을 설정하세요:

1. Anthropic Console 방문
2. API Keys > 키 선택
3. IP Restrictions 설정
4. 허용할 IP 주소 또는 CIDR 블록 추가

7. 문제 해결

인증 오류

문제: API 키가 유효하지 않음

Error: Invalid API key

해결:

# API 키 재확인
echo $ANTHROPIC_API_KEY

# 공백이나 특수문자 확인
# 키가 sk-ant-api03-으로 시작하는지 확인

# 콘솔에서 키 재생성

환경 변수 로드 오류

문제: 환경 변수가 로드되지 않음

해결:

# 쉘 프로파일 재로드
source ~/.zshrc  # zsh 사용자
source ~/.bashrc # bash 사용자

# 또는 새 터미널 세션 시작

권한 오류

문제: 설정 파일 읽기 권한 없음

해결:

# 권한 수정
chmod 644 ~/.zshrc
chmod 600 .env

8. 고급 설정

프록시 설정

프록시 서버가 필요한 환경에서:

# HTTP 프록시
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 또는 Claude Code 전용
export CLAUDE_HTTP_PROXY=http://proxy.company.com:8080
export CLAUDE_HTTPS_PROXY=http://proxy.company.com:8080

사용자 정의 엔드포인트

엔터프라이즈 환경에서 사용자 정의 엔드포인트를 사용할 수 있습니다:

export ANTHROPIC_BASE_URL="https://api.your-company.com/v1"

속도 제한 설정

API 속도 제한을 조정할 수 있습니다:

export CLAUDE_MAX_REQUESTS_PER_MINUTE=60
export CLAUDE_MAX_TOKENS_PER_MINUTE=90000

9. CI/CD 환경 설정

GitHub Actions

# .github/workflows/claude-code.yml
name: Claude Code CI

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Claude Code
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code
          claude-code "테스트를 실행해줘"

GitLab CI

# .gitlab-ci.yml
stages:
  - test

claude-code:
  stage: test
  script:
    - npm install -g @anthropic-ai/claude-code
    - claude-code "테스트를 실행해줘"
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

Docker

# Dockerfile
FROM node:18-alpine

# Claude Code 설치
RUN npm install -g @anthropic-ai/claude-code

# API 키 설정 (런타임에 전달)
ENV ANTHROPIC_API_KEY=""

WORKDIR /app
CMD ["claude-code"]

# docker-compose.yml
version: '3.8'
services:
  claude-code:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - .:/app

10. 다음 단계

인증 설정이 완료되었습니다. 이제 Claude Code를 사용할 준비가 되었습니다.

1. 빠른 시작

• 빠른 시작 가이드에서 첫 번째 프로젝트를 만들어보세요.

2. 핵심 개념 학습

• 핵심 개념 가이드에서 Claude Code의 기능을 자세히 알아보세요.

3. 일상 워크플로우

• 일상 워크플로우 가이드에서 실전 사용법을 배우세요.

인증 설정에 문제가 있나요?

• 공식 문서를 참조하세요.
• 공식 포럼에서 도움을 받으세요.
• GitHub Issues로 문제를 신고하세요.