●Claude Code●공식 자료●기타
환경 변수 레퍼런스
Claude Code API 키, 프록시, 모델 설정 등 동작 제어 전체 환경 변수 레퍼런스
환경 변수
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의 리전을 재정의한다 |