환경 변수

Claude Code의 동작을 제어하는 환경 변수의 전체 레퍼런스.

Claude Code는 다음 환경 변수를 지원하여 동작을 제어한다. 셸에서 claude를 실행하기 전에 설정하거나, settings.json의 env 키에 구성하여 모든 세션에 적용하거나 팀 전체에 배포할 수 있다.

변수	용도
ANTHROPIC_API_KEY	X-Api-Key 헤더로 전송되는 API 키. 설정하면 로그인 상태여도 Claude Pro, Max, Team, Enterprise 구독 대신 이 키를 사용한다. 비대화형 모드(-p)에서는 키가 있으면 항상 사용된다. 대화형 모드에서는 구독을 대체하기 전에 한 번 승인을 요청한다. 구독을 대신 사용하려면 unset ANTHROPIC_API_KEY를 실행한다
ANTHROPIC_AUTH_TOKEN	Authorization 헤더의 사용자 지정 값 (설정한 값 앞에 Bearer 가 자동으로 붙는다)
ANTHROPIC_BASE_URL	프록시나 게이트웨이를 통해 요청을 라우팅하기 위한 API 엔드포인트 재정의. 퍼스트파티가 아닌 호스트로 설정하면 MCP 도구 검색이 기본적으로 비활성화된다. 프록시가 tool_reference 블록을 전달하는 경우 ENABLE_TOOL_SEARCH=true를 설정한다
ANTHROPIC_CUSTOM_HEADERS	요청에 추가할 사용자 지정 헤더 (Name: Value 형식, 여러 헤더는 줄바꿈으로 구분)
ANTHROPIC_CUSTOM_MODEL_OPTION	/model 선택기에 사용자 지정 항목으로 추가할 모델 ID. 빌트인 별칭을 대체하지 않고 비표준 또는 게이트웨이 전용 모델을 선택 가능하게 한다. 모델 설정 참고
ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION	/model 선택기에서 사용자 지정 모델 항목의 표시 설명. 설정하지 않으면 Custom model (<model-id>)가 기본값이다
ANTHROPIC_CUSTOM_MODEL_OPTION_NAME	/model 선택기에서 사용자 지정 모델 항목의 표시 이름. 설정하지 않으면 모델 ID가 기본값이다
ANTHROPIC_DEFAULT_HAIKU_MODEL	모델 설정 참고
ANTHROPIC_DEFAULT_OPUS_MODEL	모델 설정 참고
ANTHROPIC_DEFAULT_SONNET_MODEL	모델 설정 참고
ANTHROPIC_FOUNDRY_API_KEY	Microsoft Foundry 인증을 위한 API 키 (Microsoft Foundry 참고)
ANTHROPIC_FOUNDRY_BASE_URL	Foundry 리소스의 전체 베이스 URL (예: https://my-resource.services.ai.azure.com/anthropic). ANTHROPIC_FOUNDRY_RESOURCE의 대안 (Microsoft Foundry 참고)
ANTHROPIC_FOUNDRY_RESOURCE	Foundry 리소스 이름 (예: my-resource). ANTHROPIC_FOUNDRY_BASE_URL이 설정되지 않은 경우 필수 (Microsoft Foundry 참고)
ANTHROPIC_MODEL	사용할 모델 설정의 이름 (모델 설정 참고)
ANTHROPIC_SMALL_FAST_MODEL	[지원 중단] 백그라운드 작업용 Haiku급 모델의 이름
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION	Bedrock 사용 시 Haiku급 모델의 AWS 리전 재정의
AWS_BEARER_TOKEN_BEDROCK	Bedrock 인증을 위한 API 키 (Bedrock API 키 참고)
BASH_DEFAULT_TIMEOUT_MS	장시간 실행되는 bash 명령어의 기본 타임아웃
BASH_MAX_OUTPUT_LENGTH	bash 출력이 중간 잘림 처리되기 전 최대 문자 수
BASH_MAX_TIMEOUT_MS	모델이 장시간 실행 bash 명령어에 설정할 수 있는 최대 타임아웃
CLAUDECODE	Claude Code가 생성한 셸 환경(Bash 도구, tmux 세션)에서 1로 설정된다. 훅이나 상태 줄 명령어에서는 설정되지 않는다. 스크립트가 Claude Code가 생성한 셸 내부에서 실행 중인지 감지할 때 사용한다
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	자동 압축이 트리거되는 컨텍스트 용량 백분율(1-100)을 설정한다. 기본적으로 약 95% 용량에서 트리거된다. 50과 같은 낮은 값을 사용하면 더 일찍 압축한다. 기본 임계값보다 높은 값은 효과가 없다. 메인 대화와 서브에이전트 모두에 적용된다. 이 백분율은 상태 줄에서 사용 가능한 context_window.used_percentage 필드와 일치한다
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR	각 Bash 명령어 후 원래 작업 디렉토리로 복귀한다
CLAUDE_CODE_ACCOUNT_UUID	인증된 사용자의 계정 UUID. SDK 호출자가 계정 정보를 동기적으로 제공하여, 초기 텔레메트리 이벤트에 계정 메타데이터가 누락되는 레이스 컨디션을 방지한다. CLAUDE_CODE_USER_EMAIL과 CLAUDE_CODE_ORGANIZATION_UUID도 함께 설정해야 한다
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD	1로 설정하면 --add-dir로 지정된 디렉토리에서 CLAUDE.md 파일을 로드한다. 기본적으로 추가 디렉토리는 메모리 파일을 로드하지 않는다
CLAUDE_CODE_AUTO_COMPACT_WINDOW	자동 압축 계산에 사용되는 컨텍스트 용량(토큰)을 설정한다. 기본값은 모델의 컨텍스트 윈도우: 표준 모델 200K, 확장 컨텍스트 모델 1M. 1M 모델에서 500000과 같은 낮은 값을 사용하면 압축 목적으로 윈도우를 500K로 취급한다. 값은 모델의 실제 컨텍스트 윈도우로 제한된다. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE는 이 값의 백분율로 적용된다. 이 변수를 설정하면 압축 임계값이 상태 줄의 used_percentage(항상 모델의 전체 컨텍스트 윈도우 사용)와 분리된다
CLAUDE_CODE_API_KEY_HELPER_TTL_MS	자격 증명을 새로 고침하는 간격(밀리초) (apiKeyHelper 사용 시)
CLAUDE_CODE_CLIENT_CERT	mTLS 인증을 위한 클라이언트 인증서 파일 경로
CLAUDE_CODE_CLIENT_KEY	mTLS 인증을 위한 클라이언트 개인 키 파일 경로
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE	암호화된 CLAUDE_CODE_CLIENT_KEY의 패스프레이즈 (선택 사항)
CLAUDE_CODE_DISABLE_1M_CONTEXT	1로 설정하면 1M 컨텍스트 윈도우 지원을 비활성화한다. 설정하면 모델 선택기에서 1M 모델 변형을 사용할 수 없다. 규정 준수 요구 사항이 있는 엔터프라이즈 환경에 유용하다
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING	1로 설정하면 Opus 4.6과 Sonnet 4.6의 적응형 추론을 비활성화한다. 비활성화 시 MAX_THINKING_TOKENS로 제어되는 고정 사고 예산으로 전환된다
CLAUDE_CODE_DISABLE_AUTO_MEMORY	1로 설정하면 자동 메모리를 비활성화한다. 점진적 롤아웃 중 자동 메모리를 강제로 켜려면 0으로 설정한다. 비활성화하면 Claude가 자동 메모리 파일을 생성하거나 로드하지 않는다
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS	1로 설정하면 Claude의 시스템 프롬프트에서 빌트인 커밋 및 PR 워크플로우 지시사항을 제거한다. 자체 git 워크플로우 스킬을 사용할 때 유용하다. 설정 시 includeGitInstructions 설정보다 우선한다
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS	1로 설정하면 Bash 및 서브에이전트 도구의 run_in_background 매개변수, 자동 백그라운드 처리, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화한다
CLAUDE_CODE_DISABLE_CRON	1로 설정하면 예약 작업을 비활성화한다. /loop 스킬과 cron 도구를 사용할 수 없게 되고, 이미 예약된 작업(실행 중인 작업 포함)도 중지된다
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS	1로 설정하면 API 요청에서 Anthropic 전용 anthropic-beta 요청 헤더와 베타 도구 스키마 필드(defer_loading, eager_input_streaming 등)를 제거한다. 프록시 게이트웨이가 "Unexpected value(s) for the anthropic-beta header" 또는 "Extra inputs are not permitted" 오류로 요청을 거부할 때 사용한다. 표준 필드(name, description, input_schema, cache_control)는 유지된다
CLAUDE_CODE_DISABLE_FAST_MODE	1로 설정하면 고속 모드를 비활성화한다
CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY	1로 설정하면 "Claude의 성능은 어떤가요?" 세션 품질 설문 조사를 비활성화한다. DISABLE_TELEMETRY 또는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC이 설정되어 있어도 비활성화된다. 세션 품질 설문 조사 참고
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	DISABLE_AUTOUPDATER, DISABLE_FEEDBACK_COMMAND, DISABLE_ERROR_REPORTING, DISABLE_TELEMETRY를 모두 설정하는 것과 동일하다
CLAUDE_CODE_DISABLE_TERMINAL_TITLE	1로 설정하면 대화 컨텍스트에 기반한 자동 터미널 제목 업데이트를 비활성화한다
CLAUDE_CODE_EFFORT_LEVEL	지원되는 모델의 노력 수준을 설정한다. 값: low, medium, high, max (Opus 4.6 전용), auto (모델 기본값 사용). /effort 및 effortLevel 설정보다 우선한다. 노력 수준 조정 참고
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION	false로 설정하면 프롬프트 제안(/config의 "Prompt suggestions" 토글)을 비활성화한다. Claude가 응답한 후 프롬프트 입력에 표시되는 회색 예측 텍스트이다. 프롬프트 제안 참고
CLAUDE_CODE_ENABLE_TASKS	true로 설정하면 비대화형 모드(-p 플래그)에서 작업 추적 시스템을 활성화한다. 대화형 모드에서는 기본적으로 켜져 있다. 작업 목록 참고
CLAUDE_CODE_ENABLE_TELEMETRY	1로 설정하면 메트릭 및 로깅을 위한 OpenTelemetry 데이터 수집을 활성화한다. OTel 내보내기 설정 전에 필수이다. 모니터링 참고
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY	쿼리 루프가 유휴 상태가 된 후 자동으로 종료하기까지의 대기 시간(밀리초). SDK 모드를 사용하는 자동화 워크플로우 및 스크립트에 유용하다
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS	1로 설정하면 에이전트 팀을 활성화한다. 에이전트 팀은 실험적 기능이며 기본적으로 비활성화되어 있다
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS	파일 읽기의 기본 토큰 제한을 재정의한다. 대용량 파일을 전체 읽기해야 할 때 유용하다
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL	IDE 확장의 자동 설치를 건너뛴다
CLAUDE_CODE_MAX_OUTPUT_TOKENS	대부분의 요청에 대한 최대 출력 토큰 수를 설정한다. 기본값과 상한은 모델에 따라 다르다; 최대 출력 토큰 참고. 이 값을 늘리면 자동 압축이 트리거되기 전 사용 가능한 유효 컨텍스트 윈도우가 줄어든다
CLAUDE_CODE_NEW_INIT	true로 설정하면 /init이 대화형 설정 플로우를 실행한다. CLAUDE.md, 스킬, 훅을 포함하여 생성할 파일을 묻고, 코드베이스를 탐색한 후 작성한다. 이 변수 없이는 /init이 프롬프트 없이 자동으로 CLAUDE.md를 생성한다
CLAUDE_CODE_ORGANIZATION_UUID	인증된 사용자의 조직 UUID. SDK 호출자가 계정 정보를 동기적으로 제공할 때 사용한다. CLAUDE_CODE_ACCOUNT_UUID와 CLAUDE_CODE_USER_EMAIL도 함께 설정해야 한다
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS	동적 OpenTelemetry 헤더를 새로 고침하는 간격(밀리초, 기본값: 1740000 / 29분). 동적 헤더 참고
CLAUDE_CODE_PLAN_MODE_REQUIRED	에이전트 팀 팀원 중 계획 승인이 필요한 팀원에 자동 설정되는 true 값. 읽기 전용: 팀원을 생성할 때 Claude Code가 설정한다. 팀원의 계획 승인 요구 참고
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS	플러그인 설치 또는 업데이트 시 git 작업의 타임아웃(밀리초, 기본값: 120000). 대규모 리포지토리나 느린 네트워크 연결에서는 이 값을 늘린다. Git 작업 타임아웃 참고
CLAUDE_CODE_PLUGIN_SEED_DIR	하나 이상의 읽기 전용 플러그인 시드 디렉토리 경로. Unix에서는 :로, Windows에서는 ;로 구분한다. 컨테이너 이미지에 미리 채워진 플러그인 디렉토리를 번들링할 때 사용한다. Claude Code는 시작 시 이 디렉토리에서 마켓플레이스를 등록하고 재복제 없이 미리 캐시된 플러그인을 사용한다. 컨테이너용 플러그인 사전 배포 참고
CLAUDE_CODE_PROXY_RESOLVES_HOSTS	true로 설정하면 호출자 대신 프록시가 DNS 확인을 수행하도록 허용한다. 프록시가 호스트명 확인을 처리해야 하는 환경에서 옵트인한다
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS	SessionEnd 훅이 완료되기까지의 최대 시간(밀리초, 기본값: 1500). 세션 종료, /clear, 대화형 /resume을 통한 세션 전환에 적용된다. 개별 훅의 timeout 값도 이 예산으로 제한된다
CLAUDE_CODE_SHELL	자동 셸 감지를 재정의한다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용하다 (예: bash vs zsh)
CLAUDE_CODE_SHELL_PREFIX	모든 bash 명령어를 래핑할 명령어 접두사 (예: 로깅이나 감사용). 예시: /path/to/logger.sh는 /path/to/logger.sh <command>로 실행된다
CLAUDE_CODE_SIMPLE	1로 설정하면 최소한의 시스템 프롬프트와 Bash, 파일 읽기, 파일 편집 도구만으로 실행한다. MCP 도구, 첨부 파일, 훅, CLAUDE.md 파일을 비활성화한다
CLAUDE_CODE_SKIP_BEDROCK_AUTH	Bedrock의 AWS 인증을 건너뛴다 (예: LLM 게이트웨이 사용 시)
CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS	1로 설정하면 조직 상태 확인이 네트워크 오류로 실패할 때도 고속 모드를 허용한다. 회사 프록시가 상태 엔드포인트를 차단할 때 유용하다. API는 조직 수준 비활성화를 별도로 적용한다
CLAUDE_CODE_SKIP_FOUNDRY_AUTH	Microsoft Foundry의 Azure 인증을 건너뛴다 (예: LLM 게이트웨이 사용 시)
CLAUDE_CODE_SKIP_VERTEX_AUTH	Vertex의 Google 인증을 건너뛴다 (예: LLM 게이트웨이 사용 시)
CLAUDE_CODE_SUBAGENT_MODEL	모델 설정 참고
CLAUDE_CODE_TASK_LIST_ID	세션 간 작업 목록을 공유한다. 여러 Claude Code 인스턴스에서 동일한 ID를 설정하여 공유 작업 목록으로 협업한다. 작업 목록 참고
CLAUDE_CODE_TEAM_NAME	이 팀원이 속한 에이전트 팀의 이름. 에이전트 팀 멤버에 자동 설정된다
CLAUDE_CODE_TMPDIR	내부 임시 파일에 사용되는 임시 디렉토리를 재정의한다. Claude Code는 이 경로에 /claude/를 추가한다. 기본값: Unix/macOS에서 /tmp, Windows에서 os.tmpdir()
CLAUDE_CODE_USER_EMAIL	인증된 사용자의 이메일 주소. SDK 호출자가 계정 정보를 동기적으로 제공할 때 사용한다. CLAUDE_CODE_ACCOUNT_UUID와 CLAUDE_CODE_ORGANIZATION_UUID도 함께 설정해야 한다
CLAUDE_CODE_USE_BEDROCK	Bedrock을 사용한다
CLAUDE_CODE_USE_FOUNDRY	Microsoft Foundry를 사용한다
CLAUDE_CODE_USE_VERTEX	Vertex를 사용한다
CLAUDE_CONFIG_DIR	Claude Code가 설정 및 데이터 파일을 저장하는 위치를 사용자 지정한다
CLAUDE_ENV_FILE	Claude Code가 각 Bash 명령어 전에 소스하는 셸 스크립트 경로. virtualenv 또는 conda 활성화를 명령어 간 유지하는 데 사용한다. SessionStart 훅에 의해 동적으로 채워지기도 한다
DISABLE_AUTOUPDATER	1로 설정하면 자동 업데이트를 비활성화한다
DISABLE_COST_WARNINGS	1로 설정하면 비용 경고 메시지를 비활성화한다
DISABLE_ERROR_REPORTING	1로 설정하면 Sentry 오류 보고를 옵트아웃한다
DISABLE_FEEDBACK_COMMAND	1로 설정하면 /feedback 명령어를 비활성화한다. 이전 이름 DISABLE_BUG_COMMAND도 허용된다
DISABLE_INSTALLATION_CHECKS	1로 설정하면 설치 경고를 비활성화한다. 설치 위치를 수동으로 관리하는 경우에만 사용하며, 표준 설치의 문제를 가릴 수 있다
DISABLE_PROMPT_CACHING	1로 설정하면 모든 모델의 프롬프트 캐싱을 비활성화한다 (모델별 설정보다 우선)
DISABLE_PROMPT_CACHING_HAIKU	1로 설정하면 Haiku 모델의 프롬프트 캐싱을 비활성화한다
DISABLE_PROMPT_CACHING_OPUS	1로 설정하면 Opus 모델의 프롬프트 캐싱을 비활성화한다
DISABLE_PROMPT_CACHING_SONNET	1로 설정하면 Sonnet 모델의 프롬프트 캐싱을 비활성화한다
DISABLE_TELEMETRY	1로 설정하면 Statsig 텔레메트리를 옵트아웃한다 (Statsig 이벤트에는 코드, 파일 경로, bash 명령어 등 사용자 데이터가 포함되지 않는다)
ENABLE_CLAUDEAI_MCP_SERVERS	false로 설정하면 Claude Code에서 claude.ai MCP 서버를 비활성화한다. 로그인한 사용자에게 기본적으로 활성화되어 있다
ENABLE_TOOL_SEARCH	MCP 도구 검색을 제어한다. 미설정: 기본적으로 활성화되지만, ANTHROPIC_BASE_URL이 퍼스트파티가 아닌 호스트를 가리키면 비활성화된다. 값: true (프록시 포함 항상 활성), auto (컨텍스트 10%에서 활성화), auto:N (사용자 지정 임계값, 예: auto:5는 5%), false (비활성화)
FORCE_AUTOUPDATE_PLUGINS	true로 설정하면 DISABLE_AUTOUPDATER로 메인 자동 업데이터가 비활성화되어 있어도 플러그인 자동 업데이트를 강제한다
HTTP_PROXY	네트워크 연결을 위한 HTTP 프록시 서버를 지정한다
HTTPS_PROXY	네트워크 연결을 위한 HTTPS 프록시 서버를 지정한다
IS_DEMO	true로 설정하면 데모 모드를 활성화한다: UI에서 이메일과 조직을 숨기고, 온보딩을 건너뛰고, 내부 명령어를 숨긴다. 스트리밍이나 녹화 세션에 유용하다
MAX_MCP_OUTPUT_TOKENS	MCP 도구 응답에 허용되는 최대 토큰 수. 출력이 10,000 토큰을 초과하면 경고를 표시한다 (기본값: 25000)
MAX_THINKING_TOKENS	확장 사고 토큰 예산을 재정의한다. 상한은 모델의 최대 출력 토큰에서 1을 뺀 값이다. 0으로 설정하면 사고를 완전히 비활성화한다. 적응형 추론이 있는 모델(Opus 4.6, Sonnet 4.6)에서는 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING으로 적응형 추론이 비활성화되지 않는 한 예산이 무시된다
MCP_CLIENT_SECRET	사전 구성된 자격 증명이 필요한 MCP 서버의 OAuth 클라이언트 시크릿. --client-secret으로 서버를 추가할 때 대화형 프롬프트를 생략한다
MCP_OAUTH_CALLBACK_PORT	사전 구성된 자격 증명으로 MCP 서버를 추가할 때 --callback-port의 대안으로 사용하는 OAuth 리디렉트 콜백의 고정 포트
MCP_TIMEOUT	MCP 서버 시작 타임아웃(밀리초)
MCP_TOOL_TIMEOUT	MCP 도구 실행 타임아웃(밀리초)
NO_PROXY	프록시를 우회하여 직접 요청을 보낼 도메인 및 IP 목록
SLASH_COMMAND_TOOL_CHAR_BUDGET	스킬 도구에 표시되는 스킬 메타데이터의 문자 예산을 재정의한다. 예산은 컨텍스트 윈도우의 2%로 동적으로 조정되며, 폴백은 16,000자이다. 하위 호환성을 위해 이전 이름이 유지된다
USE_BUILTIN_RIPGREP	0으로 설정하면 Claude Code에 포함된 rg 대신 시스템에 설치된 rg를 사용한다
VERTEX_REGION_CLAUDE_3_5_HAIKU	Vertex AI 사용 시 Claude 3.5 Haiku의 리전을 재정의한다
VERTEX_REGION_CLAUDE_3_7_SONNET	Vertex AI 사용 시 Claude 3.7 Sonnet의 리전을 재정의한다
VERTEX_REGION_CLAUDE_4_0_OPUS	Vertex AI 사용 시 Claude 4.0 Opus의 리전을 재정의한다
VERTEX_REGION_CLAUDE_4_0_SONNET	Vertex AI 사용 시 Claude 4.0 Sonnet의 리전을 재정의한다
VERTEX_REGION_CLAUDE_4_1_OPUS	Vertex AI 사용 시 Claude 4.1 Opus의 리전을 재정의한다

같이 보기

• 설정: settings.json에서 환경 변수를 구성하여 모든 세션에 적용하는 방법
• CLI 레퍼런스: 실행 시 플래그
• 네트워크 설정: 프록시 및 TLS 설정