Initial commit to new repository

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

@@ -0,0 +1,111 @@
+# 환경 변수
+
+> 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 세션에 적용되는 환경 변수를 설정할 수 있습니다:
+
+```json
+{
+  "env": {
+    "DISABLE_AUTO_COMPACT": "1",
+    "BASH_MAX_OUTPUT_LENGTH": "30000"
+  }
+}
+```