Claude Code 환경 변수 완전 가이드: AWS Bedrock 호환성 오류를 해결하는 단 1개의 설정

저자 주: Claude Code의 60개 이상 환경 변수 역할과 설정 방법을 자세히 알아봅니다. 특히 AWS Bedrock 등에서 발생하는 anthropic-beta 헤더 오류를 해결하기 위한 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 설정에 집중해 보겠습니다.

Claude Code를 사용하여 AWS Bedrock, Google Vertex AI 또는 기타 제3자 대규모 언어 모델(LLM) 게이트웨이에 연결할 때, "Unexpected value(s) for the anthropic-beta header"라는 오류를 한 번쯤 겪어보셨을 겁니다. 이 문제의 근본 원인은 Claude Code가 기본적으로 Anthropic API 전용 실험적 Beta 헤더를 전송하기 때문인데, AWS Bedrock과 같은 제3자 플랫폼은 이 헤더를 인식하지 못해 오류가 발생합니다.

해결 방법은 단 한 줄의 설정으로 충분합니다: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

하지만 Claude Code의 환경 변수는 이외에도 매우 다양합니다. 공식 문서에는 인증 설정, 모델 선택, 성능 최적화, 기능 스위치 등 60개 이상의 환경 변수가 나열되어 있습니다. 이 글에서는 이러한 환경 변수들을 체계적으로 정리하여, Claude Code 사용 중 발생하는 다양한 설정 문제를 신속하게 해결할 수 있도록 도와드리겠습니다.

핵심 가치: 이 글을 읽고 나면 Claude Code 환경 변수의 전체 체계를 파악하여 AWS Bedrock/Vertex AI 호환성 문제를 신속하게 해결하고, 환경 변수를 통해 Claude Code의 사용 경험과 비용을 최적화하는 방법을 배우게 됩니다.

Claude Code 환경 변수 핵심 요점

Claude Code의 60개 이상 환경 변수는 크게 6가지 범주로 나눌 수 있습니다. 다음은 가장 주의 깊게 살펴봐야 할 핵심 변수들입니다.

Claude Code 환경 변수 설정의 두 가지 방법

방법 1: Shell 환경 변수 (임시 적용)

터미널에서 설정 후 Claude Code를 실행하며, 현재 세션에서만 유효합니다.

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_API_KEY="your-api-key"
claude

방법 2: settings.json 설정 (영구 적용)

~/.claude/settings.json 파일의 env 필드에 구성하면 실행 시마다 자동으로 로드됩니다.

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_API_KEY": "your-api-key"
  }
}

🎯 추천 방식: API 키나 플랫폼 호환성 수정과 같이 장기적으로 적용해야 하는 설정은 settings.json 방식을 사용하는 것이 좋습니다. 매번 수동으로 export할 필요가 없으니까요. 만약 APIYI(apiyi.com)와 같은 제3자 플랫폼의 API 키를 사용하신다면, 여기서 동일하게 설정하시면 됩니다.

Claude Code 환경 변수 중점 해설: AWS Bedrock 호환성 문제 해결하기

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 상세 설명

이 설정은 이번 가이드의 핵심입니다. AWS Bedrock, Google Vertex AI, LiteLLM 등 제3자 게이트웨이를 통해 Claude Code를 사용할 때, Claude Code는 요청 헤더에 Anthropic의 실험적 베타(Beta) 식별자를 자동으로 추가합니다. 예를 들면 다음과 같습니다:

anthropic-beta: prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20

이러한 베타 식별자는 Anthropic 직결 API 전용 기능이라서, AWS Bedrock 같은 제3자 플랫폼에서는 이를 인식하지 못하고 다음과 같은 오류를 반환하게 됩니다:

Error: Unexpected value(s) for the anthropic-beta header

해결 방법:

# 방법 1: Shell 명령어
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# 방법 2: settings.json 설정
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

이 값을 1로 설정하면 Claude Code가 더 이상 실험적 베타 헤더를 보내지 않으므로, 모든 제3자 플랫폼과 원활하게 호환됩니다.

알려진 문제 및 임시 해결책

GitHub Issues 기록에 따르면, 일부 Claude Code 버전(2.1.18 이후)에서 해당 환경 변수가 완전히 적용되지 않는 버그가 있습니다. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정했음에도 불구하고 advanced-tool-use-2025-11-20과 같은 새로운 베타 헤더가 여전히 전송되는 경우가 발생할 수 있습니다.

여전히 문제가 발생한다면 다음 추가 조치를 시도해 보세요:

• Claude Code 버전 다운그레이드: 2.1.68 등 안정성이 확인된 버전으로 되돌립니다.
• LiteLLM 게이트웨이 사용: LiteLLM은 anthropic_beta_headers_config.json 설정 파일을 통해 어떤 베타 헤더를 전달할지 세밀하게 제어할 수 있는 기능을 제공합니다.
• DISABLE_PROMPT_CACHING 함께 설정: 프롬프트 캐싱을 비활성화하면 prompt-caching-scope 관련 베타 헤더가 생성되는 것을 방지할 수 있습니다.

# 전체 호환성 설정
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

Claude Code 환경 변수 전체 카테고리 요약

1. 인증 및 API 설정

가장 기본적이면서 자주 사용되는 환경 변수들로, Claude Code가 API 서비스에 연결되는 방식을 제어합니다.

🎯 제3자 플랫폼 사용자 주의사항: APIYI(apiyi.com)와 같은 제3자 API 플랫폼을 사용할 때는 ANTHROPIC_API_KEY와 ANTHROPIC_BASE_URL을 동시에 설정해야 합니다. Claude Code는 Anthropic 구독 계정에 로그인되어 있더라도 환경 변수에 설정된 API 키를 우선적으로 사용합니다.

2. 모델 선택 및 설정

Claude Code가 사용할 모델과 모델의 동작 파라미터를 제어합니다.

3. 플랫폼 호환성 및 게이트웨이 설정

Claude Code와 다양한 클라우드 플랫폼 및 LLM 게이트웨이 간의 호환성 문제를 해결하기 위한 변수들입니다.

4. 기능 스위치

DISABLE_ 또는 CLAUDE_CODE_DISABLE_ 접두사가 붙은 변수를 통해 특정 기능을 끌 수 있습니다.

5. 컨텍스트 및 성능 관리

Claude Code가 컨텍스트 윈도우를 관리하고 리소스를 사용하는 방식을 제어합니다.

🎯 성능 최적화 팁: 긴 대화 중에 Claude Code가 컨텍스트를 너무 자주 압축한다고 느껴진다면, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE를 더 낮은 값(예: 50)으로 설정해 보세요. 압축이 더 일찍 트리거되어 정보 손실을 줄일 수 있습니다. APIYI(apiyi.com)를 통해 호출할 때도 이러한 환경 변수 설정이 모두 지원됩니다.

Claude Code 환경 변수 설정 가이드

초간단 예시: Claude Code를 제3자 API 플랫폼에 연결하기

# 터미널에서 환경 변수를 설정한 후 Claude Code를 실행하세요.
export ANTHROPIC_API_KEY="sk-your-api-key"
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com/v1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": []
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1",
    "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION": "us-east-1"
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_BASE_URL": "https://my-resource.services.ai.azure.com/anthropic",
    "ANTHROPIC_FOUNDRY_API_KEY": "your-foundry-key",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

팁: AWS Bedrock이나 Azure의 복잡한 설정이 번거롭다면, **APIYI(apiyi.com)**를 통해 Claude 전체 모델을 바로 사용해 보세요. API 키와 Base URL 두 가지만 설정하면 되므로 클라우드 플랫폼 인증이나 호환성 문제를 신경 쓸 필요가 없습니다.

자주 묻는 질문 (FAQ)

요약

Claude Code 환경 변수의 핵심 요점은 다음과 같습니다.

1. AWS Bedrock 오류 해결: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정하여 실험적 Beta 헤더를 비활성화하세요. 이 설정 한 줄로 「Unexpected value(s) for the anthropic-beta header」 오류를 해결할 수 있습니다.
2. 60개 이상의 환경 변수를 6대 카테고리로 분류: 인증 설정, 모델 선택, 플랫폼 호환성, 기능 스위치, 컨텍스트 관리, 기타 설정으로 나뉩니다.
3. 두 가지 설정 방식: Shell export(임시)와 settings.json(영구) 방식이 있으며, 설정을 유지하려면 settings.json에 작성하는 것을 추천합니다.
4. API 중계 서비스를 통한 간소화: APIYI(apiyi.com)와 같은 통합 API 플랫폼을 이용하면 ANTHROPIC_API_KEY와 ANTHROPIC_BASE_URL 두 가지 변수만 설정하면 됩니다. 복잡한 클라우드 플랫폼 인증이나 Beta 헤더 호환성 문제를 신경 쓸 필요가 없습니다.

AWS Bedrock이나 Vertex AI 설정 시 발생하는 각종 호환성 문제를 피하고 싶다면, APIYI(apiyi.com)를 통해 Claude Code를 빠르게 연결해 보시는 것을 추천합니다. 플랫폼에서 제공하는 무료 크레딧과 통합 인터페이스를 활용해 보세요.

📚 참고 자료

1. Claude Code 공식 문서 – 환경 변수: 전체 환경 변수 목록 및 설명

   • 링크: code.claude.com/docs/en/env-vars
   • 설명: 60개 이상의 모든 환경 변수에 대한 공식 레퍼런스입니다.

2. Claude Code 공식 문서 – 설정: 설정 범위 및 settings.json 규격

   • 링크: code.claude.com/docs/en/settings
   • 설명: Managed/User/Project/Local 4단계 설정 체계를 이해할 수 있습니다.

3. Claude Code 공식 문서 – Amazon Bedrock: AWS Bedrock 통합 가이드

   • 링크: code.claude.com/docs/en/amazon-bedrock
   • 설명: Bedrock 전용 설정 및 일반적인 문제 해결 방법을 다룹니다.

4. GitHub Issue #22893 – DISABLE_EXPERIMENTAL_BETAS 미적용 문제: 커뮤니티 버그 보고

   • 링크: github.com/anthropics/claude-code/issues/22893
   • 설명: 해당 환경 변수의 알려진 제한 사항과 임시 해결 방법을 확인할 수 있습니다.

5. LiteLLM – Claude Code Beta Headers 관리: 게이트웨이 계층의 Beta 헤더 필터링 방안

   • 링크: docs.litellm.ai/docs/tutorials/claude_code_beta_headers
   • 설명: LiteLLM 게이트웨이 사용 시 세밀한 Beta 헤더 제어 방법을 설명합니다.

작성자: APIYI 기술 팀
기술 교류: 댓글 창에서 Claude Code 설정 경험을 함께 공유해 주세요. 더 많은 사용 튜토리얼은 APIYI docs.apiyi.com 문서 센터에서 확인하실 수 있습니다.