Claude Code 환경 변수
Claude Code의 모든 환경 변수가 하는 일, 설정 위치, 그리고 claudeCode.environmentVariables를 통해 VS Code 패널까지 전달되는 방식을 정리했습니다.
Claude Code는 거의 전부 환경 변수로 구성됩니다. 인증, API 엔드포인트, 모델, 재시도와 타임아웃 동작, 그리고 프록시와 게이트웨이를 위한 모든 호환성 스위치가 환경 변수입니다. 명령줄 플래그도 아니고, 구성 마법사의 입력 항목도 아닙니다. Claude Code 설정이 기대한 대로 동작하지 않는다면, 이 페이지가 점검 목록입니다. 어떤 변수인지, 어느 파일인지, 어떤 우선순위 규칙인지 확인하세요.
claudeCode.environmentVariables란
claudeCode.environmentVariables는 환경 변수를 Claude Code 확장 패널에 전달하는 VS Code 설정입니다. VS Code 사용자 settings.json에 저장되는 { "name": ..., "value": ... } 쌍의 단순한 배열입니다:
1 "claudeCode.environmentVariables": [2 { "name": "ANTHROPIC_BASE_URL", "value": "https://www.codebyai.net/api/agent" },3 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-proj-xxxx" }4 ]
이 배열을 수정하기 전에 알아두면 좋은 네 가지 속성이 있습니다. 네 가지 모두 사람들을 당황하게 만듭니다:
| 속성 | 결과 |
|---|---|
| 맵이 아니라 객체의 배열입니다 | "KEY": "value"는 조용히 무시되며, 패널은 변수 없이 시작됩니다 |
| 머신 범위로 적용됩니다 | 현재 폴더뿐 아니라 그 컴퓨터의 모든 VS Code 창에 영향을 줍니다 |
| 관련 없는 변수와 배열을 공유합니다 | 프록시 설정이나 NODE_EXTRA_CA_CERTS가 같은 배열에 있습니다. 덮어쓰면 사라집니다 |
| 에이전트가 생성될 때 한 번만 읽힙니다 | 개발자: 창 다시 로드 (또는 VS Code 재시작) 전까지는 수정해도 아무 효과가 없습니다 |
셸의 export가 확장 패널에 닿지 않는 이유
claude CLI는 자신을 실행한 프로세스의 환경을 상속하므로, ~/.zshrc의 export ANTHROPIC_BASE_URL=...가 동작합니다. 확장은 다릅니다. 확장은 VS Code 창 프로세스에서 에이전트 프로세스를 생성하므로, 패널은 VS Code가 시작될 때의 데스크톱/로그인 환경을 봅니다. export를 입력한 셸은 절대 보지 못합니다.
이것이 가장 흔한 Claude Code 오설정의 원인입니다. 터미널은 동작하는데 확장 패널은 계속 기본 엔드포인트와 통신합니다. 그 터미널에서 VS Code를 실행하거나(그러면 변수를 상속하지만 모든 창이 그 경로로 라우팅됩니다), 확장 자체의 우회 수단인 claudeCode.environmentVariables를 설정하세요.
패널이 실제로 보는 값 확인하기
다음은 확장이 주입할 이름들을 출력하며, 자격 증명처럼 보이는 값은 마스킹합니다:
1 # macOS2 S="$HOME/Library/Application Support/Code/User/settings.json"3 # Linux: S="$HOME/.config/Code/User/settings.json"4 # Windows: S="$APPDATA/Code/User/settings.json"5 6 jq -r '.["claudeCode.environmentVariables"] // [] | .[] | "\(.name)"' "$S"
출력이 없다면 패널이 VS Code 프로세스 환경을 상속한다는 뜻이며, 변수는 다른 곳에서 와야 합니다.
변수를 설정할 수 있는 세 곳
| 지정 위치 | 적용 대상 | 지속성 |
|---|---|---|
셸 export (~/.zshrc, ~/.bashrc, Windows 환경 변수) | 셸에서 시작한 claude CLI | 예, 셸 세션 단위 |
settings.json의 env 블록 (~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json) | CLI, VS Code 확장, Agent SDK | 예, 설정 범위 단위 |
claudeCode.environmentVariables | VS Code 확장 패널만 | 예, 머신 전체 |
settings.json의 범위는 구분해 둘 가치가 있습니다:
| 파일 | 범위 |
|---|---|
~/.claude/settings.json | 모든 프로젝트에서의 나 |
.claude/settings.json | 프로젝트의 모든 사람 (커밋하세요) |
.claude/settings.local.json | 이 프로젝트에서의 나만 (git 무시됨) |
| 관리형 설정 | 조직의 모든 사람 |
1 {2 "env": {3 "ANTHROPIC_BASE_URL": "https://www.codebyai.net/api/agent",4 "API_TIMEOUT_MS": "600000"5 }6 }
우선순위 규칙
- 환경 변수는 동등한
settings.json필드보다 우선합니다 (예를 들어ANTHROPIC_MODEL이model보다 우선). - 명령줄의
--model과 세션 내부의/model은ANTHROPIC_MODEL보다 우선합니다. - 대화형 모드에서
ANTHROPIC_API_KEY는 대화형 구독 로그인보다 우선합니다.-p(print) 모드에서는 항상 API 키가 사용됩니다. - 변수는 프로세스 시작 시 읽힙니다. 세션 도중에 다시 로드하는 것은 없습니다.
claude를 재시작하거나 VS Code에서 개발자: 창 다시 로드를 실행하세요.
Claude Code를 Code By AI로 연결하기
Code By AI는 Anthropic 호환 엔드포인트를 제공하므로, 관련된 변수는 엔드포인트와 그에 딸린 토큰뿐입니다. Claude Code를 시작하는 방식에 맞는 위치를 선택하세요.
터미널 / CLI
1 # ~/.zshrc or ~/.bashrc2 export ANTHROPIC_BASE_URL="https://www.codebyai.net/api/agent"3 export ANTHROPIC_AUTH_TOKEN="sk-proj-xxxx"4 export API_TIMEOUT_MS=6000005 export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
VS Code 확장
1 "claudeCode.environmentVariables": [2 { "name": "ANTHROPIC_BASE_URL", "value": "https://www.codebyai.net/api/agent" },3 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-proj-xxxx" },4 { "name": "API_TIMEOUT_MS", "value": "600000" },5 { "name": "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "value": "1" }6 ],
창을 다시 로드한 다음 패널 헤더에 게이트웨이 엔드포인트가 표시되는지 확인하세요. Windows 명령줄에 해당하는 값까지 포함한 단계별 안내는 Claude Code 구성에 있습니다.
ANTHROPIC_AUTH_TOKEN은 Authorization: Bearer <value>로 전송되며, 이것이 Code By AI 게이트웨이가 기대하는 방식입니다. 반면 ANTHROPIC_API_KEY는 X-Api-Key로 전송됩니다. 둘 중 하나만 사용하세요. 둘 다 쓰면 의도하지 않은 쪽이 이길 수 있습니다.
변수 레퍼런스
인증
| 변수 | 용도 |
|---|---|
ANTHROPIC_API_KEY | X-Api-Key 헤더로 전송되는 API 키. -p 모드에서는 항상 사용됩니다 |
ANTHROPIC_AUTH_TOKEN | Bearer 접두사가 붙는 사용자 지정 Authorization 헤더 값 |
CLAUDE_CODE_OAUTH_TOKEN | Claude.ai 인증용 OAuth 액세스 토큰. SDK와 자동화 환경용입니다 |
CLAUDE_CODE_OAUTH_REFRESH_TOKEN | claude auth login이 브라우저 없이 교환하는 리프레시 토큰 |
CLAUDE_CODE_OAUTH_SCOPES | 리프레시 토큰이 발급된 공백 구분 스코프 |
엔드포인트와 제공자 라우팅
| 변수 | 용도 |
|---|---|
ANTHROPIC_BASE_URL | API 엔드포인트를 재정의합니다 (프록시 또는 게이트웨이). 자사가 아닌 호스트를 사용하면 ENABLE_TOOL_SEARCH=true가 아닌 한 MCP 도구 검색이 비활성화됩니다 |
CLAUDE_CODE_USE_BEDROCK / _VERTEX / _FOUNDRY | Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry를 통해 라우팅합니다 |
ANTHROPIC_BEDROCK_BASE_URL / ANTHROPIC_VERTEX_BASE_URL / ANTHROPIC_FOUNDRY_BASE_URL | 제공자별 엔드포인트를 재정의합니다 |
HTTP_PROXY / HTTPS_PROXY / NO_PROXY | 네트워크 연결용 아웃바운드 프록시 |
CLAUDE_CODE_SKIP_BEDROCK_AUTH 및 유사 변수 | LLM 게이트웨이가 요청에 직접 서명할 때 제공자 인증을 건너뜁니다 |
모델 선택
| 변수 | 용도 |
|---|---|
ANTHROPIC_MODEL | 사용할 모델. --model과 /model이 우선합니다 |
ANTHROPIC_DEFAULT_SONNET_MODEL / _HAIKU_ / _OPUS_ | 티어별 기본 모델 ID를 고정합니다 |
ANTHROPIC_CUSTOM_MODEL_OPTION / _NAME / _DESCRIPTION | /model 선택 목록에 사용자 지정 항목을 추가합니다 |
CLAUDE_CODE_SUBAGENT_MODEL | 서브에이전트가 사용하는 모델 |
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY | 1로 설정하면 게이트웨이의 /v1/models에서 /model 목록을 채웁니다 |
MAX_THINKING_TOKENS | 확장 사고 예산. 0은 Anthropic API에서 사고를 비활성화합니다 |
CLAUDE_CODE_MAX_OUTPUT_TOKENS | 요청당 최대 출력 토큰 수 |
타임아웃과 재시도
| 변수 | 기본값 | 용도 |
|---|---|---|
API_TIMEOUT_MS | 600000 | API 요청 타임아웃 (밀리초) |
BASH_DEFAULT_TIMEOUT_MS | 120000 | 장시간 실행되는 Bash 명령의 기본 타임아웃 |
BASH_MAX_TIMEOUT_MS | 600000 | 모델이 Bash에 설정할 수 있는 최대 타임아웃 |
CLAUDE_CODE_MAX_RETRIES | 10 | 실패한 API 요청의 재시도 횟수 |
프록시와 게이트웨이 호환성
타사 엔드포인트가 아예 동작할지를 결정하는 변수들입니다:
| 변수 | 용도 |
|---|---|
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | 1이면 자동 업데이터, 피드백 명령, 오류 보고, 텔레메트리를 한 번에 끕니다 |
CLAUDE_CODE_ATTRIBUTION_HEADER | 0이면 시스템 프롬프트에서 어트리뷰션 블록을 제거하여, 게이트웨이 뒤에서 프롬프트 캐시 적중률을 높입니다 |
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS | 1이면 프록시가 거부할 수 있는 anthropic-beta 헤더를 제거합니다 |
CLAUDE_CODE_DISABLE_THINKING | thinking 파라미터를 완전히 생략합니다 |
ENABLE_TOOL_SEARCH | true / false / auto: 사용자 지정 ANTHROPIC_BASE_URL에서 MCP 지연 도구 로딩을 제어합니다 |
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK | 스트리밍 중간 실패 시 도구 호출을 비스트리밍으로 다시 실행하지 않도록 합니다 |
DISABLE_PROMPT_CACHING | 프롬프트 캐싱을 끕니다 (디버깅 전용 — 비용이 올라갑니다) |
진단과 경로
| 변수 | 용도 |
|---|---|
DEBUG | 1 (또는 true, yes, on)이면 디버그 모드를 켭니다. --debug와 같습니다 |
CLAUDE_CODE_DEBUG_LOG_LEVEL | 최소 로그 레벨: verbose, debug, info, warn, error |
CLAUDE_CONFIG_DIR | 구성 디렉토리를 재정의합니다. 기본값은 ~/.claude |
CLAUDE_CODE_SIMPLE | 1이면 최소 시스템 프롬프트와 Bash 및 파일 도구만으로 실행합니다 |
문제 해결
변수가 무시되는 것 같습니다. 먼저 지정 위치를 확인하세요. 셸 export는 VS Code 확장 패널에 보이지 않고, claudeCode.environmentVariables는 CLI에 보이지 않습니다. 그다음 재시작을 확인하세요. 환경 변수는 프로세스 시작 시 한 번만 읽힙니다.
엔드포인트를 바꾼 뒤 401 또는 invalid api key가 발생합니다. ANTHROPIC_API_KEY와 ANTHROPIC_AUTH_TOKEN은 서로 다른 헤더로 전송됩니다. 같은 범위에 남아 있는 ANTHROPIC_API_KEY가 -p 모드에서 우선하므로, 토큰으로 인증할 때는 이를 제거하세요.
프록시를 거치면 모든 요청이 실패합니다. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 추가하세요. 일부 프록시는 Claude Code가 기본으로 보내는 베타 헤더를 거부합니다.
긴 생성에서 요청이 타임아웃됩니다. 재시도하기보다 API_TIMEOUT_MS를 올리세요 (기본값은 10분입니다). 타임아웃은 넉넉한 편이지만 큰 diff는 이를 넘길 수 있습니다.
게이트웨이에서 /model 선택 목록이 비어 있습니다. CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1을 설정하여 게이트웨이의 /v1/models로 목록을 채우거나, ANTHROPIC_MODEL로 모델을 직접 지정하세요.
게이트웨이 뒤에서 프롬프트 캐시 적중률이 낮습니다. CLAUDE_CODE_ATTRIBUTION_HEADER=0을 설정하세요. 어트리뷰션 블록은 세션마다 달라져서 캐시된 프리픽스를 무효화합니다.
자주 묻는 질문
Claude Code는 어디에서 환경 변수를 읽나요?
자신이 시작된 프로세스 환경과 해당 settings.json 파일들의 env 블록을 병합하여 읽습니다. 같은 동작을 둘 다 정의하면 환경 변수가 우선합니다. VS Code 확장 패널은 별도의 프로세스 트리이므로 대신 claudeCode.environmentVariables가 필요합니다.
변수를 변경한 후 재시작해야 하나요?
네. Claude Code는 시작할 때 구성을 읽습니다. CLI는 claude를 재시작하고, 확장은 VS Code에서 개발자: 창 다시 로드를 실행하세요.
ANTHROPIC_API_KEY와 ANTHROPIC_AUTH_TOKEN 중 무엇이 우선하나요?
-p 모드에서는 ANTHROPIC_API_KEY이며, 대화형 구독 로그인도 덮어씁니다. 베어러 토큰으로 인증하는 게이트웨이를 거친다면 모호함을 없애기 위해 ANTHROPIC_API_KEY를 해제하세요.
변수를 바꾸지 않고 다른 모델을 사용할 수 있나요?
네. 실행 시의 --model과 세션 내부의 /model 모두 ANTHROPIC_MODEL보다 우선합니다. 변수는 기본값을 정하고, 플래그는 변수를 덮어씁니다.
Claude Code, Codex, Gemini 모두 Code By AI의 동일한 엔드포인트와 동일한 키로 동작하며, 공식 API 가격의 1/6입니다. 가격 비교 보기 또는 충전하고 키 발급받기.