환경 변수 기초
환경 변수는 시스템 전체 또는 프로세스별 설정을 저장하는 키-값 쌍입니다. Claude Code는 환경 변수를 통해 API 키, 설정 옵션, 프로젝트별 값을 관리합니다. 민감한 정보를 코드에서 분리하고, 환경별 설정을 쉽게 전환할 수 있습니다.
bash
# 환경 변수 설정 (macOS/Linux)
# 1. 일시적 설정 (현재 세션만)
export CLAUDE_API_KEY=sk-ant-xxxxx
export OPENAI_API_KEY=sk-xxxxx
# 2. 영구 설정 (bash/zsh)
echo 'export CLAUDE_API_KEY=sk-ant-xxxxx' >> ~/.zshrc
source ~/.zshrc
# 3. .env 파일 사용
# .env
CLAUDE_API_KEY=sk-ant-xxxxx
GITHUB_TOKEN=ghp_xxxxx
DB_CONNECTION=postgresql://localhost/mydb
# Claude Code 실행 시 로드
claude --env-file .envpowershell
# Windows 환경 변수 설정
# PowerShell (일시적)
$env:CLAUDE_API_KEY = "sk-ant-xxxxx"
# PowerShell (영구)
[Environment]::SetEnvironmentVariable("CLAUDE_API_KEY", "sk-ant-xxxxx", "User")
# CMD (일시적)
set CLAUDE_API_KEY=sk-ant-xxxxx- 코드 분리 - 민감한 정보를 코드에서 분리
- 환경별 관리 - dev/staging/prod 설정 전환
- .env 지원 - 파일 기반 환경 변수
- 우선순위 - 시스템 > .env > 기본값
API 키 관리
API 키는 외부 서비스 인증에 사용되는 민감한 정보입니다. Claude Code, GitHub, AWS 등 다양한 서비스의 API 키를 안전하게 관리하는 것이 중요합니다. 절대 Git에 커밋하지 말고, 환경 변수나 비밀 관리 도구를 사용하세요.
bash
# 주요 API 키 환경 변수
# Claude API (필수)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxx
# OpenAI (선택)
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxx
# GitHub
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# AWS
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# 데이터베이스
DATABASE_URL=postgresql://user:password@localhost:5432/dbbash
# .gitignore에 .env 추가 (중요!)
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
echo ".env.*.local" >> .gitignore
# .env.example 템플릿 생성 (팀 공유용)
cat > .env.example <<EOF
# Claude API Key (필수)
ANTHROPIC_API_KEY=your_api_key_here
# GitHub Token (선택)
GITHUB_TOKEN=your_github_token_here
# Database
DATABASE_URL=postgresql://localhost/mydb
EOF보안 주의: API 키가 Git에 커밋되면 즉시 무효화하고 새로 발급받으세요. GitHub은 자동으로 커밋된 키를 스캔하여 경고합니다.
설정 옵션
Claude Code는 다양한 환경 변수를 통해 동작을 커스터마이징할 수 있습니다. 로그 레벨, 타임아웃, 모델 선택 등을 환경 변수로 제어합니다.
bash
# Claude Code 설정 환경 변수
# 로그 레벨
CLAUDE_LOG_LEVEL=debug|info|warn|error
# 기본 모델
CLAUDE_MODEL=claude-sonnet-4-5|claude-opus-4-5|claude-haiku-4
# API 타임아웃 (초)
CLAUDE_TIMEOUT=60
# 최대 토큰 수
CLAUDE_MAX_TOKENS=4096
# 온도 (창의성)
CLAUDE_TEMPERATURE=0.7
# 재시도 횟수
CLAUDE_MAX_RETRIES=3
# 캐시 활성화
CLAUDE_CACHE_ENABLED=true
CLAUDE_CACHE_DIR=~/.claude/cachebash
# 프로젝트별 설정 예제
# .env
# 개발 환경
CLAUDE_LOG_LEVEL=debug
CLAUDE_MODEL=claude-haiku-4 # 빠른 응답
CLAUDE_TIMEOUT=30
# 프로덕션 환경 (.env.production)
CLAUDE_LOG_LEVEL=warn
CLAUDE_MODEL=claude-sonnet-4-5 # 높은 품질
CLAUDE_TIMEOUT=120
CLAUDE_MAX_RETRIES=5- 로그 제어 - 개발/운영 환경별 로그 레벨
- 모델 선택 - 속도/품질 균형 조절
- 타임아웃 - 응답 대기 시간 설정
- 캐시 관리 - 응답 캐싱으로 속도 향상
프로젝트별 설정
프로젝트마다 다른 설정이 필요할 수 있습니다. 프로젝트 루트에 .env 파일을 두면 해당 프로젝트에만 적용됩니다.
bash
# 프로젝트 구조
my-project/
├── .env # 프로젝트별 환경 변수
├── .env.example # 템플릿 (Git 포함)
├── .gitignore # .env 제외
└── .claude/
├── config.json # Claude Code 설정
└── mcp-servers.json # MCP 서버 설정
# .env
CLAUDE_MODEL=claude-sonnet-4-5
PROJECT_DB=postgresql://localhost/project_db
PROJECT_API_URL=https://api.project.com
FEATURE_FLAGS=enable_beta,enable_analytics
# .env.example (팀 공유용)
CLAUDE_MODEL=claude-sonnet-4-5
PROJECT_DB=postgresql://localhost/your_db_name
PROJECT_API_URL=https://api.yourproject.com
FEATURE_FLAGS=bash
# 환경별 설정 파일
# 개발 환경
.env.development
CLAUDE_LOG_LEVEL=debug
API_BASE_URL=http://localhost:3000
DATABASE_URL=postgresql://localhost/dev_db
# 스테이징 환경
.env.staging
CLAUDE_LOG_LEVEL=info
API_BASE_URL=https://staging-api.example.com
DATABASE_URL=postgresql://staging-db:5432/staging_db
# 프로덕션 환경
.env.production
CLAUDE_LOG_LEVEL=warn
API_BASE_URL=https://api.example.com
DATABASE_URL=postgresql://prod-db:5432/prod_db
# 환경별 실행
claude --env-file .env.development
claude --env-file .env.staging
claude --env-file .env.production- 프로젝트 격리 - 프로젝트별 독립 설정
- 환경 분리 - dev/staging/prod 구분
- 팀 협업 - .env.example로 공유
- 우선순위 - 프로젝트 > 글로벌
보안 고려사항
환경 변수에 민감한 정보를 저장할 때는 반드시 보안을 고려해야 합니다. Git 커밋 방지, 권한 설정, 암호화, 정기 교체 등이 필요합니다.
bash
# 보안 체크리스트
## 1. Git 커밋 방지
# .gitignore 확인
cat .gitignore | grep -E ".env"
# 이미 커밋된 .env 제거
git rm --cached .env
git commit -m "Remove .env from git"
git push
## 2. 파일 권한 설정 (macOS/Linux)
chmod 600 .env # 소유자만 읽기/쓰기
## 3. 비밀번호 교체 확인
# 3개월마다 API 키 교체 권장
## 4. 환경 변수 검증
claude validate-envbash
# 비밀 관리 도구 사용
## 1. macOS Keychain
# 저장
security add-generic-password \
-s "claude-api-key" \
-a "$(whoami)" \
-w "sk-ant-xxxxx"
# 읽기
export CLAUDE_API_KEY=$(security find-generic-password \
-s "claude-api-key" -w)
## 2. AWS Secrets Manager
export CLAUDE_API_KEY=$(aws secretsmanager get-secret-value \
--secret-id claude/api-key \
--query SecretString --output text)
## 3. HashiCorp Vault
export CLAUDE_API_KEY=$(vault kv get \
-field=api_key secret/claude)절대 금지: API 키를 코드, Git, 로그, 스크린샷, 슬랙 메시지에 포함하지 마세요. 한 번이라도 노출되면 즉시 무효화하고 재발급받으세요.
정기 교체: API 키는 최소 3개월마다 교체하세요. 자동화 스크립트로 정기 교체를 설정할 수 있습니다.
환경 변수 문제 해결
환경 변수가 제대로 로드되지 않거나 인식되지 않을 때 문제를 해결하는 방법입니다.
bash
# 일반적인 문제와 해결
## 문제 1: 환경 변수가 로드되지 않음
# 확인
echo $CLAUDE_API_KEY
# 원인: .env 파일 경로 오류
# 해결: 현재 디렉토리 확인
pwd
ls -la .env
## 문제 2: 설정이 적용되지 않음
# 확인
claude config --show-env
# 원인: 쉘 설정 파일 미적용
# 해결
source ~/.zshrc # zsh
source ~/.bashrc # bash
## 문제 3: 권한 오류
# 원인: .env 파일 권한 문제
# 해결
chmod 600 .env
## 문제 4: 특수 문자 포함
# 원인: 값에 공백이나 특수 문자
# 해결: 따옴표로 감싸기
API_KEY="value with spaces"bash
# 디버깅 도구
# 1. 모든 환경 변수 출력
env | grep CLAUDE
# 2. 특정 변수 확인
echo "CLAUDE_API_KEY: ${CLAUDE_API_KEY:0:20}..." # 앞 20자만
# 3. Claude Code 환경 정보
claude --debug config
# 4. .env 파일 파싱 테스트
cat .env | grep -v "^#" | grep "="- 경로 확인 - .env 파일 위치 검증
- 권한 문제 - 파일 접근 권한 설정
- 특수 문자 - 따옴표로 값 감싸기
- 디버그 모드 - 상세 로그로 원인 파악
환경 변수 우선순위: 시스템 환경 변수 > .env 파일 > 기본값 순서로 적용됩니다. 시스템 환경 변수가 가장 높은 우선순위를 가집니다.