Claude Code는 JSON 설정 파일과 환경 변수에서 설정을 가져옵니다. Anthropic API 대신 게이트웨이를 통해 실행하려면 ANTHROPIC_BASE_URL과 토큰 변수가 필요하며, 보통 모델도 지정해야 합니다. 변수 자체는 간단합니다. 혼란스러운 점은 어디에 설정하느냐입니다. 같은 변수가 셸 프로필, 여러 settings.json 파일, VS Code 설정에 모두 들어갈 수 있기 때문입니다.
이 가이드에서는 먼저 작동하는 설정을 소개한 다음, 파일의 위치와 어떤 값이 우선 적용되는지, 그리고 흔히 발생하는 오류를 설명합니다. 2026년 10월 20일에 Anthropic 문서를 확인하고 Claude Code 2.1.304에서 AIHubMix를 사용해 테스트했습니다. 예시는 AIHubMix를 게이트웨이로 사용하지만, Anthropic 호환 엔드포인트라면 설정 방법은 같습니다.
핵심 요약
- 개인 설정 파일은
~/.claude/settings.json이며, Windows에서는%USERPROFILE%\.claude\settings.json입니다. - 게이트웨이를 사용하려면 해당 파일의
env블록에ANTHROPIC_BASE_URL(끝에/v1을 붙이지 않음)과ANTHROPIC_AUTH_TOKEN을 입력합니다. - 설정 파일의
env블록에 지정된 값은 셸에서 내보낸 같은 변수의 값을 덮어씁니다. - 토큰을 설정하면 Claude 구독으로 요청이 전송되지 않고, 게이트웨이에서 요금이 청구됩니다.
- VS Code 확장 프로그램에서는 자체
claudeCode.environmentVariables설정에도 같은 변수를 지정해야 합니다.
작동하는 AIHubMix 설정
- AIHubMix 콘솔에서 키를 만듭니다.
~/.claude/settings.json에 다음 내용을 입력합니다. 파일이 없으면 새로 만드세요.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"env": {
"ANTHROPIC_BASE_URL": "https://aihubmix.com",
"ANTHROPIC_AUTH_TOKEN": "sk-your-aihubmix-key"
},
"model": "claude-sonnet-5-5"
}
- 간단히 테스트해 보세요.
claude -p "1+1, output only the answer"
- 프로젝트에서
claude를 실행합니다. 로고 아래 헤더에Sonnet 5.5 · API Usage Billing와 비슷한 문구가 표시되고,/status를 입력하면Anthropic base URL줄에 게이트웨이가 표시됩니다.
두 가지 세부 사항이 중요합니다. Base URL은 루트 주소여야 합니다. Claude Code가 /v1/messages를 자동으로 추가하므로 URL이 /v1로 끝나면 모든 요청이 실패합니다. 또한 AIHubMix는 claude-sonnet-5-5와 같은 Anthropic 고유 모델 ID를 사용하므로, 별도의 설정 없이 sonnet, opus, haiku 단축 이름이 작동합니다.
$schema 줄은 선택 사항입니다. 이 줄을 사용하면 VS Code, Cursor 및 기타 편집기에서 입력하는 동안 파일의 오류를 표시할 수 있습니다.
대신 셸에서 같은 두 변수를 내보낼 수도 있지만, 설정 파일에 두는 편이 좋습니다. 모든 터미널과 IDE 확장 프로그램, 백그라운드 에이전트가 설정 파일을 읽기 때문입니다.
설정 파일 위치
| 범위 | 파일 | 적용 대상 |
|---|---|---|
| 사용자 | ~/.claude/settings.json | 모든 프로젝트에서 나에게 적용 |
| 프로젝트 | .claude/settings.json | git을 통해 저장소의 모든 사용자에게 적용 |
| 로컬 | .claude/settings.local.json | 이 저장소에서 나에게만 적용 |
| 관리형 | 조직에서 설정 | 배포된 모든 사용자에게 적용 |
프로젝트의 .claude/settings.json에는 토큰을 절대 넣지 마세요. 이 파일은 git에 커밋됩니다. 사용자 파일이나 .claude/settings.local.json을 사용하세요.
설정 파일은 올바른 JSON 형식이어야 합니다. // 주석이나 끝에 붙은 쉼표가 있으면 Claude Code가 토큰을 포함해 파일 전체를 무시하고, 게이트웨이 대신 로그인 화면이 표시됩니다.
홈 폴더에 있는 단일 파일 ~/.claude.json과 혼동하지 마세요. 이 파일에는 로그인 정보와 MCP 서버 등 Claude Code 자체 상태가 저장되며, 편집할 일은 거의 없습니다.
어떤 값이 우선 적용되나요?
여러 파일에서 같은 항목을 설정한 경우, Anthropic의 설정 우선순위가 적용됩니다. 우선순위가 높은 항목부터 나열하면 다음과 같습니다.
- 조직의 관리형 설정
- 해당 세션에만 적용되는 명령줄의
--settings .claude/settings.local.json.claude/settings.json~/.claude/settings.json
환경 변수에는 규칙이 하나 더 있습니다. 설정 파일의 env 블록에 지정된 변수는 셸에서 설정한 같은 변수를 덮어씁니다. 따라서 설정 파일에도 변수가 있으면 export ANTHROPIC_BASE_URL=...의 ~/.zshrc은 효과가 없습니다. 공급자 전환 도구는 보통 ~/.claude/settings.json을 수정하므로 셸 설정에 우선합니다.
Claude Code에서 /status를 입력하면 Setting sources 줄에 로드된 파일이 표시됩니다.
ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY
| 변수 | 전송 형식 | 참고 |
|---|---|---|
| ANTHROPIC_AUTH_TOKEN | Authorization: Bearer | 즉시 사용 |
| ANTHROPIC_API_KEY | x-api-key | 한 번 승인 요청 |
게이트웨이가 읽는 변수를 사용하세요. AIHubMix는 둘 다 지원하며, Claude Code 가이드에서는 더 간단한 선택지이기도 한 ANTHROPIC_AUTH_TOKEN을 사용합니다. 두 변수를 동시에 설정하지 마세요. Claude Code가 두 헤더를 모두 전송하며, AIHubMix는 x-api-key를 먼저 확인합니다. 테스트에서는 settings.json에 올바른 토큰이 있어도 셸에서 이전 ANTHROPIC_API_KEY가 내보내져 401 오류가 발생했습니다. env 블록은 그 안에 지정된 변수만 덮어쓰므로, 전환할 때는 셸 프로필에서 이전 키를 삭제하세요.
Claude 구독은 어떻게 될까요? Anthropic의 게이트웨이 가이드에 따르면 토큰 또는 API 키 변수를 설정하면 요청은 claude.ai 로그인 대신 해당 변수를 사용하고, 게이트웨이에서 토큰 단위로 요금이 청구됩니다. 로그인 정보는 저장된 채로 유지되며 변수를 삭제하면 다시 사용할 수 있습니다. 토큰 없이 ANTHROPIC_BASE_URL만 설정하면 구독을 계속 사용합니다.
모델 선택
Anthropic의 모델 설정 페이지에 나온 우선순위는 다음과 같습니다. 높은 순서부터 나열했습니다.
- 세션 중
/model <name>실행 - 시작 시
claude --model <name>실행 ANTHROPIC_MODEL변수- 설정 파일의
model키
/model을 실행하면 선택한 모델이 새 기본값으로 저장됩니다. 하지만 ANTHROPIC_MODEL이 설정되어 있으면 새 세션을 시작할 때마다 해당 모델이 다시 선택됩니다. 모델을 자주 바꾼다면 model 키를 설정하고 ANTHROPIC_MODEL은 지정하지 마세요. 어디에도 모델을 설정하지 않으면 Claude Code는 Opus 5.5를 사용합니다.
ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL은 각 단축 이름이 가리키는 모델을 변경합니다. 예를 들어 sonnet을 이전 버전에 계속 연결하는 등 단축 이름을 다른 모델에 지정하려는 경우에만 필요합니다.
AIHubMix는 같은 주소에서 다른 공급업체의 모델도 제공하지만, Anthropic은 Claude Code에서 Claude 이외의 모델을 지원하지 않으므로 일부 기능이 작동하지 않을 수 있습니다.
변경 사항 적용 시점
Claude Code는 설정 파일을 감시하므로 env 블록을 포함해 저장된 대부분의 수정 사항은 실행 중인 세션에 적용됩니다. model 키, 변수 삭제, 셸 내보내기 설정은 재시작해야 적용됩니다. 잘 모르겠다면 Claude Code를 재시작하세요.
VS Code 확장 프로그램
확장 프로그램도 같은 설정 파일을 읽지만 시작 전에 자체 claudeCode.environmentVariables 설정을 사용해 로그인 여부를 확인합니다. 그래서 CLI는 작동하는데 VS Code에서 로그인을 요청할 수 있습니다. 명령 팔레트에서 Preferences: Open User Settings (JSON)을 열고 다음을 추가하세요.
{
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://aihubmix.com" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-aihubmix-key" }
]
}
그런 다음 Developer: Reload Window를 실행합니다. 더 많은 옵션은 Anthropic의 VS Code 문서를 참조하세요. Claude Desktop 앱은 별개이므로 settings.json이나 이 환경 변수들을 읽지 않습니다.
그 밖에 유용한 변수
| 변수 | 설정할 때 |
|---|---|
| API_TIMEOUT_MS | 요청 시간이 길어 타임아웃이 발생할 때(기본값 10분) |
| CLAUDE_CODE_MAX_RETRIES | 오류를 더 빨리 표시하고 싶을 때 |
| HTTPS_PROXY | HTTP 프록시를 사용하는 환경일 때 |
| NODE_EXTRA_CA_CERTS | 프록시에서 자체 루트 인증서를 사용할 때 |
이 변수들은 모두 env 블록에 넣을 수 있습니다. 전체 목록은 Anthropic의 환경 변수 참조 문서에서 확인하세요.
흔한 오류와 의미
Not logged in · Please run /login, 또는 처음 실행할 때 로그인 화면이 표시됨
Claude Code에서 토큰을 찾지 못했습니다. 파일의 JSON 오류 때문에 파일을 건너뛰었는지, ANTHROPIC_AUTH_TOKEN이 누락되었는지, 토큰이 프로젝트 파일에만 있는지 확인하세요. 로그인 절차는 프로젝트 설정을 불러오기 전에 실행되므로 토큰을 ~/.claude/settings.json으로 옮기세요.
Invalid or malformed JSON
메시지에 표시된 파일에 주석, 끝에 붙은 쉼표 또는 다른 구문 오류가 있어 설정이 하나도 적용되지 않았습니다.
There's an issue with the selected model (...)
모델 ID가 잘못되었거나, Base URL이 /v1로 끝나 요청이 /v1/v1/messages로 전송된 경우입니다. 모델 ID가 맞아 보이면 URL부터 확인하세요.
API Error: 400 및 This model ID is incorrect
AIHubMix에 해당 ID의 모델이 없으며, 메시지에 전달받은 ID가 표시됩니다. 보통 오타가 원인입니다. AIHubMix 모델 목록에서 ID를 다시 복사하세요.
Failed to authenticate. API Error: 401 invalid key: ...
AIHubMix에서 키를 승인하지 않았습니다. 메시지 끝에는 전달받은 키의 마지막 6자가 표시되므로 토큰 끝부분과 비교하세요. PI_KEY는 실제 키 대신 자리표시자인 AIHUBMIX_API_KEY를 붙여 넣었다는 뜻입니다. 그 외의 경우에는 보통 셸에서 이전 ANTHROPIC_API_KEY가 전송된 것입니다. 대신 메시지에 this key is not enabled가 표시되면 AIHubMix 콘솔에서 키가 활성화되어 있고 크레딧이 남아 있는지 확인하세요.
auth may not work as expected
토큰 변수와 저장된 claude.ai 로그인이 모두 활성화되어 있습니다. 게이트웨이를 계속 사용하려면 /logout을 실행하고, 구독으로 돌아가려면 변수를 제거하세요.
Claude Code doesn't recognize the model ...
오류가 아니라 경고입니다. 요청은 계속 전송되지만 Claude Code는 컨텍스트 창이 200K 토큰이라고 가정합니다. ID가 최신 Claude 모델의 것이라면 claude update를 실행해 해결할 수 있습니다.
잘못된 키를 사용하면 멈춘 것처럼 보입니다
Claude Code는 실패한 요청을 최대 10회까지 다시 시도합니다. 항상 실패하는 키로 테스트했을 때 claude -p는 약 3분 동안 계속 재시도했습니다. 오류를 더 빨리 확인하려면 CLAUDE_CODE_MAX_RETRIES 값을 낮추세요.
Claude Code에서 Claude를 사용하고 다른 도구에서는 OpenAI, Google 및 다른 공급업체 모델을 사용하기 위해 하나의 키를 원한다면, AIHubMix는 https://aihubmix.com에서 Anthropic API를 제공합니다. 위 설정 파일만 있으면 Claude Code를 사용할 수 있습니다.
자주 묻는 질문
Claude Code의 settings.json은 어디에 있나요?
개인 파일은 ~/.claude/settings.json이며 Windows에서는 %USERPROFILE%.claude\settings.json입니다. 프로젝트에는 git으로 공유하는 .claude/settings.json과 본인만 사용할 수 있는 .claude/settings.local.json도 있을 수 있습니다. Claude Code는 설치할 때 이 파일들을 만들지 않습니다.
settings.json이 환경 변수를 덮어쓰나요?
네. 설정 파일의 env 블록에 지정된 값은 셸에서 내보낸 동일한 변수를 덮어씁니다. 오래된 ANTHROPIC_API_KEY처럼 파일에서 설정하지 않은 변수는 계속 셸의 값을 사용합니다.
ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY 중 어떤 것을 사용해야 하나요?
게이트웨이가 읽는 변수를 사용하세요. ANTHROPIC_AUTH_TOKEN은 Bearer 토큰을 전송하며 승인이 필요하지 않습니다. AIHubMix에서 문서로 안내하는 변수는 ANTHROPIC_AUTH_TOKEN입니다. 두 변수를 모두 설정하지 마세요. AIHubMix는 x-api-key를 먼저 읽으므로, 오래된 ANTHROPIC_API_KEY가 남아 있으면 401 오류가 발생합니다.
ANTHROPIC_BASE_URL은 /v1로 끝나야 하나요?
아니요. Claude Code가 자체적으로 /v1/messages를 추가합니다. AIHubMix에서는 https://aihubmix.com을 사용하세요.
settings.json을 수정한 후 Claude Code를 다시 시작해야 하나요?
env 변경을 비롯한 대부분의 수정 사항은 저장하면 적용됩니다. 모델 키와 셸 내보내기 값은 다시 시작해야 적용됩니다. 안전하게 적용하려면 재시작하는 것이 좋습니다.
CLI는 작동하는데 VS Code에서 로그인을 요청하는 이유는 무엇인가요?
확장 프로그램은 시작 전에 claudeCode.environmentVariables 설정을 사용해 로그인 여부를 확인하며, ~/.claude/settings.json의 값은 이 확인 과정에 반영되지 않습니다. 여기에 기본 URL과 토큰을 추가한 다음 창을 다시 로드하세요.
ANTHROPIC_BASE_URL을 설정하면 Claude 구독을 사용하나요?
토큰을 설정하지 않은 경우에만 사용합니다. ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY를 설정하면 요청에 해당 키가 사용되며, 게이트웨이는 토큰당 요금을 청구합니다.
출처
- 설정 파일 및 우선순위, Anthropic
- 환경 변수, Anthropic
- Claude Code를 LLM 게이트웨이에 연결하기, Anthropic
- 모델 구성, Anthropic
- Claude Code 통합 가이드, AIHubMix
