AX-Copilot/docs/claude-code-docs-main/09_환경변수.md

환경 변수

Claude Code가 인증, API 접근, 동작, 런타임 옵션을 설정하기 위해 읽는 환경 변수.

Claude Code는 시작 시 환경 변수를 읽습니다. 설정 파일을 수정하지 않고 인증 설정, 커스텀 API 엔드포인트, 런타임 동작 튜닝, 활성 기능 제어가 가능합니다.

인증

변수	설명
ANTHROPIC_API_KEY	Anthropic API 직접 인증용 API 키. 설정 시 OAuth 대신 이 키를 사용합니다. export ANTHROPIC_API_KEY="sk-ant-..."
ANTHROPIC_AUTH_TOKEN	대안 인증 토큰. ANTHROPIC_API_KEY가 적용되지 않는 컨텍스트에서 사용합니다.
ANTHROPIC_BASE_URL	Anthropic API 기본 URL 재정의. 프록시, 스테이징 환경, 호환 서드파티 엔드포인트를 가리킬 때 유용합니다.
CLAUDE_CODE_API_BASE_URL	Claude Code 전용 API 기본 URL 재정의. 설정 시 ANTHROPIC_BASE_URL보다 우선합니다.
ANTHROPIC_BEDROCK_BASE_URL	AWS Bedrock API 접근용 기본 URL. Bedrock 엔드포인트를 통해 라우팅할 때 설정합니다.
ANTHROPIC_VERTEX_PROJECT_ID	Vertex AI 접근용 Google Cloud 프로젝트 ID. Google Cloud의 Vertex AI 플랫폼을 통해 Claude Code를 사용할 때 필요합니다.
CLAUDE_CODE_USE_BEDROCK	1 또는 true로 설정해 AWS Bedrock을 API 공급자로 사용합니다.
CLAUDE_CODE_USE_FOUNDRY	1 또는 true로 설정해 Anthropic Foundry를 API 공급자로 사용합니다.
CLAUDE_CODE_OAUTH_TOKEN	OAuth 액세스 토큰을 직접 사용해 대화형 로그인 흐름을 우회합니다. 자동화 환경에 유용합니다.

설정 경로

변수	기본값	설명
CLAUDE_CONFIG_DIR	~/.claude	Claude Code가 설정, 설정값, 트랜스크립트를 저장하는 디렉토리 재정의. export CLAUDE_CONFIG_DIR="/opt/claude-config"
CLAUDE_CODE_MANAGED_SETTINGS_PATH	-	Managed 설정 파일 경로 재정의. 기본 플랫폼 경로가 적절하지 않은 엔터프라이즈 환경에 유용합니다.

모델 선택

변수	설명
ANTHROPIC_MODEL	사용할 기본 모델. 설정 파일의 model 설정과 명시적 --model 플래그에 의해 재정의됩니다.
CLAUDE_CODE_SUBAGENT_MODEL	메인 에이전트가 생성하는 서브에이전트 작업에 사용할 모델. 설정하지 않으면 서브에이전트는 메인 세션과 동일한 모델을 사용합니다.
CLAUDE_CODE_AUTO_MODE_MODEL	자동 모드에서 사용할 모델. 지정하지 않으면 메인 세션 모델을 기본으로 합니다.

동작 토글

변수	설명
CLAUDE_CODE_REMOTE	1 또는 true로 설정해 원격/컨테이너 모드 활성화. 비대화형 환경에 맞게 동작을 조정합니다 — API 타임아웃 연장(120s vs 300s), 대화형 프롬프트 억제, 출력 형식 조정.
CLAUDE_CODE_SIMPLE	1 또는 true로 설정해(또는 --bare 전달) bare 모드로 실행. 훅, LSP 통합, 플러그인 동기화, 스킬 디렉토리 워크, 어트리뷰션, 백그라운드 프리페치, 키체인/자격증명 읽기를 모두 건너뜁니다. 경량 스크립트 사용에 유용합니다.
DISABLE_AUTO_COMPACT	1 또는 true로 설정해 자동 컨텍스트 컴팩션 비활성화. 설정 시 모델의 컨텍스트 한계에 근접해도 대화 컨텍스트를 컴팩트하지 않습니다.
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS	1 또는 true로 설정해 백그라운드 작업 실행 비활성화.
CLAUDE_CODE_DISABLE_THINKING	1 또는 true로 설정해 모든 API 호출의 확장 thinking을 비활성화합니다.
CLAUDE_CODE_DISABLE_AUTO_MEMORY	1 또는 true로 설정해 자동 메모리 비활성화. Claude가 자동 메모리 디렉토리를 읽거나 쓰지 않습니다.
CLAUDE_CODE_DISABLE_CLAUDE_MDS	1 또는 true로 설정해 모든 CLAUDE.md 메모리 파일 로딩을 완전 비활성화합니다.
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	1 또는 true로 설정해 분석, 원격 측정, 기타 비필수 네트워크 요청을 억제합니다.
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR	1 또는 true로 설정해 각 Bash 커맨드 후 원래 프로젝트 루트로 작업 디렉토리를 재설정합니다.

리소스 제한

변수	설명
CLAUDE_CODE_MAX_OUTPUT_TOKENS	API 응답당 최대 출력 토큰 수 재정의. export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096
CLAUDE_CODE_MAX_CONTEXT_TOKENS	최대 컨텍스트 윈도우 크기 재정의.
BASH_MAX_OUTPUT_LENGTH	Bash 커맨드 출력에서 캡처되는 최대 문자 수. export BASH_MAX_OUTPUT_LENGTH=50000
API_TIMEOUT_MS	API 요청 타임아웃을 밀리초 단위로 재정의. 기본 300,000ms(5분), 원격 모드에서는 120,000ms(2분). export API_TIMEOUT_MS=60000

원격 측정 및 관찰 가능성

변수	설명
CLAUDE_CODE_ENABLE_TELEMETRY	1 또는 true로 설정해 트레이스, 메트릭, 로그의 OpenTelemetry 내보내기 활성화. 추가 OTEL 설정이 필요합니다. export CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_JSONL_TRANSCRIPT	Claude Code가 세션 JSONL 트랜스크립트를 쓸 파일 경로. export CLAUDE_CODE_JSONL_TRANSCRIPT="/tmp/session.jsonl"

Node.js 런타임

변수	설명
NODE_OPTIONS	런타임에 전달되는 표준 Node.js 옵션. Claude Code는 --max-old-space-size 같은 플래그를 감지하기 위해 이것을 읽습니다. ⚠️ 코드 실행 플래그를 포함하는 값으로 설정하지 마세요.

호스트 플랫폼 재정의

변수	설명
CLAUDE_CODE_HOST_PLATFORM	분석용 보고 호스트 플랫폼 재정의. "win32", "darwin", "linux" 허용. export CLAUDE_CODE_HOST_PLATFORM=darwin

클라우드 제공업체 리전 재정의

Vertex AI에서 모델별 리전 재정의를 지원합니다:

모델 프리픽스	환경 변수
claude-haiku-4-5	VERTEX_REGION_CLAUDE_HAIKU_4_5
claude-3-5-sonnet	VERTEX_REGION_CLAUDE_3_5_SONNET
claude-sonnet-4-6	VERTEX_REGION_CLAUDE_4_6_SONNET
claude-opus-4	VERTEX_REGION_CLAUDE_4_0_OPUS

기본 Vertex 리전은 CLOUD_ML_REGION으로 제어됩니다(기본값: us-east5).

AWS 자격 증명

Bedrock 접근을 위해 표준 AWS 자격 증명 환경 변수를 지원합니다:

변수	설명
AWS_REGION	Bedrock API 호출용 AWS 리전. AWS_DEFAULT_REGION으로 폴백, 없으면 us-east-1
AWS_DEFAULT_REGION	AWS_REGION이 설정되지 않은 경우 폴백 AWS 리전

모든 세션에 환경 변수 설정

셸 프로파일 대신 설정 파일의 env 필드를 사용해 모든 Claude Code 세션에 적용되는 환경 변수를 설정할 수 있습니다:

{
  "env": {
    "DISABLE_AUTO_COMPACT": "1",
    "BASH_MAX_OUTPUT_LENGTH": "30000"
  }
}