Claude Code ANTHROPIC_BASE_URL 안 될 때: 증상별 진단과 2.1.299 수정

ANTHROPIC_BASE_URL은 요청을 보낼 주소만 바꿉니다. 게이트웨이용 자격 증명(ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY)이 함께 설정되지 않으면 Claude Code는 저장된 claude.ai 로그인을 계속 쓰거나 로그인 화면을 띄웁니다. "설정했는데 안 된다"는 경우의 상당수가 여기서 시작합니다.

원인을 빨리 가르려면 두 가지를 먼저 확인하세요. Claude Code 안에서 /status를 실행해 Anthropic base URL 줄과 Auth token/API key 줄이 보이는지 확인하고, 같은 셸에서 curl로 게이트웨이에 1토큰 요청을 보냅니다. curl은 성공하는데 Claude Code만 실패하면 설정이 세션에 전달되지 않은 문제이고, curl부터 실패하면 URL·자격 증명·게이트웨이 쪽 문제입니다.

버전도 확인해야 합니다. 게이트웨이 경로와 관련된 수정 네 가지가 2.1.299에 들어갔는데, 2026년 10월 15일 기준 npm의 stable 채널은 아직 2.1.292입니다. stable 채널이나 Homebrew claude-code로 설치했다면 이 수정이 적용되지 않은 상태입니다.

/status 두 줄과 curl 한 번으로 막힌 단계 찾기

Claude Code를 실행한 뒤 /status를 입력하면 Status 탭이 열립니다. Anthropic의 LLM 게이트웨이 연결 문서에 따르면 확인할 줄은 두 개입니다.

• Anthropic base URL: 게이트웨이 주소가 설정됐을 때만 나타납니다. 이 줄이 없으면 ANTHROPIC_BASE_URL이 이 세션에 전달되지 않은 것입니다.
• Auth token 또는 API key: ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper 중 하나가 표시되면 게이트웨이 자격 증명이 활성 상태입니다. 대신 claude.ai 계정이 적힌 Login method 줄이 보이면 자격 증명이 세션에 닿지 않은 것입니다.

그다음 변수를 export한 같은 셸에서 게이트웨이로 직접 요청을 보냅니다. Claude Code를 거치지 않으므로, 여기서 실패하면 문제는 Claude Code 설정이 아니라 URL·자격 증명·게이트웨이에 있습니다.

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Windows PowerShell에서는 같은 요청을 이렇게 보냅니다.

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

게이트웨이가 x-api-key 헤더를 쓴다면 Authorization 줄을 x-api-key: $ANTHROPIC_API_KEY로 바꿉니다. 모델 이름은 아무것이나 넣어도 됩니다. 결과는 이렇게 읽습니다.

curl이 성공한 상태에서 같은 셸로 claude를 실행해 메시지를 하나 보내고, /status에 게이트웨이 주소와 방금 설정한 변수가 보이면 연결은 완료된 것입니다.

계속 claude.ai 로그인을 요구할 때: 주소는 자격 증명이 아닙니다

curl은 성공하는데 Claude Code가 로그인 화면을 띄우는 경우, CLI 자신에게 자격 증명이 없다는 뜻입니다. 접속 가능한 base URL은 자격 증명이 아닙니다. Anthropic의 게이트웨이 개요는 ANTHROPIC_BASE_URL만 설정하고 게이트웨이 자격 증명을 넣지 않으면 요청은 게이트웨이를 거치지만 저장된 claude.ai 로그인이 그대로 활성 자격 증명으로 남고, 구독 사용 한도와 과금도 그 계정 기준으로 적용된다고 설명합니다. 구독 한도를 피하려고 게이트웨이로 옮겼는데 5시간·주간 한도에 계속 걸린다면 이 경우부터 의심하세요.

확인할 순서는 다음과 같습니다.

1. 자격 증명 변수가 있는지: 게이트웨이 키를 ANTHROPIC_AUTH_TOKEN에 넣습니다. 어떤 종류인지 모르면 이 변수부터 씁니다.
2. 프로젝트 설정 파일에만 넣지 않았는지: 대화형 세션에서는 프로젝트의 .claude/settings.json이나 .claude/settings.local.json에 있는 env 블록이 첫 실행 마법사와 폴더 신뢰 확인을 마친 뒤에야 적용됩니다. 그래서 처음 실행할 때는 로그인 화면이 먼저 뜹니다. 셸 export, ~/.claude/settings.json의 env, 관리 설정 중 한 곳에 ANTHROPIC_AUTH_TOKEN을 두세요. 커밋되는 프로젝트 .claude/settings.json에는 자격 증명을 넣지 않습니다.
3. ANTHROPIC_API_KEY를 한 번 거부하지 않았는지: 이 변수는 대화형 모드에서 처음 한 번 승인을 받아야 하고, 예전에 거부한 키는 다시 묻지 않고 조용히 무시됩니다. /config에서 Use custom API key를 켜면 됩니다.
4. 로그인과 변수가 함께 활성인지: 시작할 때 자격 증명 출처 두 개를 언급하며 auth may not work as expected로 끝나는 경고가 나오면(구버전은 Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set) 저장된 로그인과 게이트웨이 변수가 동시에 있는 상태입니다. 게이트웨이를 쓸 거라면 /logout으로 저장된 로그인을 지웁니다.

OpenRouter의 Claude Code 연동 문서는 이 충돌이 openrouter/auto 같은 모델을 찾을 수 없다는 오류로 나타나기도 한다고 적고 있습니다. 모델 오류처럼 보여도 실제 원인은 남아 있는 로그인일 수 있으니 /logout 후 claude를 다시 실행해 보세요.

반대로 게이트웨이를 그만 쓰고 claude.ai 로그인으로 돌아가는 중에 Invalid code나 403이 난다면 Claude Code 로그인 오류 해결: Invalid code, 403, 500 구분하기를 참고하세요.

401 인증 실패: 자격 증명이 다른 헤더로 가고 있습니다

curl이나 Claude Code가 401을 받으면 대부분 자격 증명 변수를 잘못 고른 경우입니다. 두 변수는 키를 서로 다른 HTTP 헤더에 실어 보냅니다.

게이트웨이가 읽지 않는 헤더에 키가 실리면 키 자체는 맞아도 401이 납니다. 헤더 대응 설명대로 다른 변수로 옮겨 다시 export한 뒤 curl을 반복하세요. 둘 다 401이면 키가 폐기됐거나 그 게이트웨이가 발급한 키가 아닌 것이므로 게이트웨이에서 다시 발급받아야 합니다.

변수를 바꿨는데도 실패한다면 다음 두 가지를 봅니다.

• 진짜 Anthropic 키가 남아 있음: 셸 프로필에 실제 ANTHROPIC_API_KEY가 남아 있으면 그 값이 x-api-key로 함께 나갑니다. OpenRouter와 Ollama 문서가 모두 ANTHROPIC_API_KEY=""처럼 명시적으로 빈 값을 넣으라고 하는 이유입니다. 이 경우는 /logout으로 해결되지 않으니 프로필에서 지워야 합니다.
• 변수 전개 순서: ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"처럼 다른 변수를 참조하면 프로필을 읽는 순간 값이 정해집니다. 참조하는 키가 프로필 뒤쪽이나 다른 파일, 나중에 실행되는 시크릿 관리 도구에서 정의되면 ANTHROPIC_AUTH_TOKEN은 빈 문자열이 되고 모든 요청이 인증에 실패합니다. echo ${#ANTHROPIC_AUTH_TOKEN}로 길이가 0이 아닌지 확인하세요.

지정한 주소를 안 쓸 때: settings 파일 env가 셸보다 우선

/status의 Anthropic base URL이 내가 export한 값과 다르다면, 같은 변수를 다른 곳에서도 설정했을 가능성이 높습니다. 공식 문서의 규칙은 분명합니다. 셸 export와 settings 파일의 env 블록이 같은 변수를 설정하면 settings 파일 값이 적용됩니다. Ollama 문서도 Claude 설정이 셸 변수를 덮어쓸 수 있다고 적고 있습니다. 셸에서 방금 export한 값이 이긴다고 생각하기 쉽지만 실제 순서는 반대입니다.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

~/.claude/settings.json(Windows는 %USERPROFILE%\.claude\settings.json)과 프로젝트의 .claude/settings.local.json을 열어 예전 게이트웨이 주소가 남아 있지 않은지 확인하세요. 주소를 바꿀 때는 셸과 settings 파일 중 한 곳에서만 관리하는 편이 헷갈리지 않습니다.

변수가 아예 닿지 않는 경우도 있습니다.

• 셸 export는 그 터미널에서만 유효합니다. 그 터미널에서 실행한 프로그램만 값을 물려받습니다. Dock이나 시작 메뉴로 연 편집기는 값을 보지 못합니다. 새 터미널에서도 쓰려면 ~/.zshrc, ~/.bashrc, PowerShell $PROFILE에 같은 줄을 넣고 터미널을 새로 엽니다.
• 백그라운드 에이전트에는 셸에서만 export한 값이 안정적으로 전달되지 않습니다. 백그라운드 에이전트까지 항상 게이트웨이를 거쳐야 한다면 settings 파일의 env 블록을 씁니다.
• 프로젝트 .env 파일은 읽지 않습니다. OpenRouter 문서에 따르면 네이티브 설치판 Claude Code는 일반 .env 파일을 읽지 않습니다.

VS Code나 Claude 데스크톱 앱에서만 안 될 때

터미널의 claude는 정상인데 다른 화면에서만 실패한다면, 그 화면이 설정을 다른 곳에서 읽기 때문입니다.

VS Code 확장은 claudeCode.environmentVariables에 변수를 넣어야 합니다. 명령 팔레트에서 Preferences: Open User Settings (JSON)을 열고 다음을 추가합니다.

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}

확장은 실행 전에 이 설정에서 자격 증명을 확인합니다. ~/.claude/settings.json의 값은 확장이 띄우는 프로세스에는 전달되지만 확장 자체의 로그인 확인에는 쓰이지 않습니다. 그래서 settings.json만 채워 두면 VS Code에서는 로그인 화면이 뜰 수 있습니다.

Claude 데스크톱 앱은 ANTHROPIC_BASE_URL과 settings.json을 아예 읽지 않습니다. 데스크톱 앱 설정 설명에 따르면 관리자가 배포한 서드파티 추론 설정을 쓰거나, 직접 설정하려면 Help → Troubleshooting → Enable Developer Mode로 개발자 메뉴를 켠 뒤 Developer → Configure Third-Party Inference에서 게이트웨이 주소를 입력합니다. 관리자 배포 설정이 있으면 이 양식은 읽기 전용입니다. 앱이 Gateway was unreachable을 표시하면 시작할 때 설정된 주소에 닿지 못한 것이므로 위의 curl로 주소와 네트워크를 확인합니다.

URL 형태와 연결 오류: base URL 끝에 /v1을 붙이지 마세요

Claude Code는 ANTHROPIC_BASE_URL 뒤에 /v1/messages를 붙여 요청합니다. 공식 확인용 curl도 $ANTHROPIC_BASE_URL/v1/messages로 보냅니다. 그래서 base URL에는 루트 주소만 넣습니다.

이미 /v1로 끝나는 주소를 넣으면 요청 경로가 /v1/v1/messages가 된다고 보는 것이 자연스럽습니다. 이 경우 어떤 오류가 나는지는 게이트웨이마다 다르며, 404나 HTML 페이지가 흔한 형태입니다. OpenRouter도 https://openrouter.ai/api/v1이 아니라 OpenRouter 문서에 적힌 https://openrouter.ai/api를 넣습니다.

연결 단계의 오류는 트러블슈팅 표 기준으로 이렇게 나뉩니다.

• Connection refused — a firewall or proxy may be blocking it (ConnectionRefused) 또는 Can't reach the API server — check your internet or DNS (ENOTFOUND): 그 주소에서 아무것도 응답하지 않거나 호스트 이름이 해석되지 않습니다. Claude Code는 재시도하느라 잠시 멈춘 뒤에 이 오류를 보여 주지만 curl은 같은 원인으로 바로 실패하므로 curl로 확인하는 편이 빠릅니다. 주소 오타, VPN, 방화벽을 확인합니다.
• API returned an empty or malformed response (HTTP 200): 게이트웨이나 중간 HTTP 프록시가 API 응답이 아닌 HTML 오류 페이지나 로그인 페이지를 돌려준 경우입니다. URL 경로와 게이트웨이 라우트를 확인합니다.
• HTML 본문의 403 Forbidden인데 게이트웨이 로그에는 요청이 없음: 게이트웨이 앞의 웹 방화벽(WAF)이나 리버스 프록시가 요청 본문을 차단한 것입니다. Claude Code 프롬프트에는 XML 형식 태그와 소스 코드가 들어 있어 크로스 사이트 스크립팅 규칙에 걸리기 쉽고, 짧은 curl은 통과해도 실제 세션은 막힙니다. /v1/messages 경로를 본문 검사에서 제외해야 하며, AWS WAF라면 CrossSiteScripting_Body 관리형 규칙이 해당합니다.
• curl은 되는데 SSL certificate verification failed, Self-signed certificate detected: 회사의 TLS 검사 프록시 뒤에서 흔합니다. Claude Code 런타임이 curl과 같은 인증 기관을 신뢰하지 않는 것이므로 NODE_EXTRA_CA_CERTS에 CA 번들 경로를 지정합니다.

400 오류: 게이트웨이가 Claude Code가 보내는 필드를 거부할 때

연결과 인증은 통과했는데 대화 중에 400이 나는 경우, 게이트웨이나 그 뒤의 모델 서버가 Claude Code가 Anthropic 형식으로 보내는 필드를 받아들이지 않는 것입니다. 게이트웨이가 요청을 업스트림에 그대로 넘기고, 업스트림이 모르는 필드를 거부할 때 생깁니다. 오류 문구로 구분합니다.

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1은 대부분의 출시 전 필드를 빼지만 MCP 도구 검색 같은 기능도 함께 꺼집니다. 이 변수로 막히지 않는 일부 기능은 해당 CLAUDE_CODE_USE_* 제공자 변수를 설정해야 합니다.

컨텍스트 한도 관련해서는 두 가지를 더 알아 두면 좋습니다.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW는 200000처럼 정수만 받습니다. 200k라고 쓰면 200으로 읽혀 최솟값 100,000으로 맞춰집니다. 또 최솟값이 100,000이라서 게이트웨이 한도가 그보다 작으면 이 변수로는 맞출 수 없고 /compact로 복구해야 합니다. 출력 한도에 걸린다면 CLAUDE_CODE_MAX_OUTPUT_TOKENS도 게이트웨이 모델 한도 아래로 낮춥니다.
• 2.1.285부터 커스텀 ANTHROPIC_BASE_URL 뒤의 세션은 1M 컨텍스트를 지원하는 모델(Opus 4.7 이상, Sonnet 5 이상, Fable)에서 1M 창을 씁니다. 게이트웨이가 200K에서 끊긴다면 변경 내역이 안내하는 대로 /autocompact 200k를 실행합니다.

GitHub에는 아직 해결되지 않은 보고도 두 건 있습니다. Anthropic이 확인한 내용은 아니며, 각 보고자의 환경에서 관찰된 것입니다.

• #95087: 커스텀 base URL에서 세션의 첫 요청에 tool_addition 블록(베타 mid-conversation-tool-changes)이 실려, 엄격한 Anthropic 호환 서버가 400으로 거부한다는 보고입니다. 보통은 Claude Code가 이 블록을 빼고 조용히 다시 보내 겉으로는 문제가 없지만, 2026년 10월 13일 댓글은 2.1.296에서 재전송이 일어나지 않아 대화를 더 이어갈 수 없었다고 적고 있습니다.
• #101897 (2026년 10월 13일): 2.1.269에서 2.1.296으로 업데이트한 뒤 자체 호스팅 모델에서 OpenAI 형식의 maximum context length 400 오류가 나고 압축으로도 복구되지 않았다는 보고입니다. 보고자는 2.1.269로 되돌려 피했습니다. 공식 해결 경로는 위 표의 /compact와 CLAUDE_CODE_AUTO_COMPACT_WINDOW입니다.

/model 목록에 게이트웨이 모델이 보이지 않는 것은 오류가 아니라 Claude Code 기본 목록에 없는 이름이기 때문입니다. CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1을 설정하면 시작할 때 게이트웨이에서 모델 목록을 받아 옵니다. 모델이 목록에 없는 다른 경우는 Claude Code에서 Fable 5.1이 안 보일 때: 증상별 해결법에서 다룹니다.

2.1.299에서 고친 게이트웨이 문제와 stable 채널 2.1.292

2.1.299는 npm에 2026년 10월 14일 09:23(한국 시간)에 올라왔고, 같은 날 23:27에 2.1.300이 이어서 배포됐습니다. CHANGELOG의 2.1.299 항목에는 ANTHROPIC_BASE_URL 사용자와 관련된 수정이 네 가지 있습니다.

1. 기능 플래그, 시작, fast mode, 프로필, 피드백 요청이 Anthropic으로 갈 때 서드파티 게이트웨이용 API 키를 싣고 가던 문제를 고쳤습니다. Anthropic API 키는 계속 전송됩니다.
2. 관리 설정 파일이 ANTHROPIC_BASE_URL을 지정한 경우, Anthropic으로 가는 서버 관리 설정 요청에 게이트웨이 API 키가 실리던 문제를 고쳤습니다.
3. 커스텀 ANTHROPIC_BASE_URL을 거치는 스트림이 데이터 없이 180초가 지나면 끊기던 문제를 고쳐, 이제 300초까지 기다립니다.
4. 게이트웨이 전용 모델 이름을 쓰는 세션이 200K 토큰 근처에서 요청을 보내지 않고 Prompt is too long · automatic compaction failed로 끝나던 문제를 고쳤습니다.

1번과 2번은 게이트웨이 키를 쓰는 모든 사용자에게 해당합니다. 그 키가 Anthropic 쪽 요청에 실렸을 때 화면에 어떤 오류가 보였는지는 변경 내역에 적혀 있지 않으니, 특정 오류 문구를 기준으로 판단하기보다 버전을 기준으로 판단하세요. 3번은 로컬 모델이나 느린 게이트웨이에서 긴 응답이 중간에 끊기던 경우, 4번은 deepseek-...나 제공자 접두어가 붙은 것처럼 Claude Code가 모르는 모델 이름을 쓰다가 200K 근처에서 멈추던 경우입니다.

claude --version으로 버전을 확인합니다. 문제는 설치 채널입니다.

설치 문서에 따르면 stable 채널은 보통 약 1주 전 버전을 쓰고 큰 회귀가 있는 릴리스는 건너뜁니다. 따라서 stable 사용자는 stable이 2.1.299 이상으로 올라가거나 직접 채널을 바꿀 때까지 위 수정을 받지 못합니다. stable이 언제 2.1.299 이상이 될지는 공개되어 있지 않습니다. Homebrew, WinGet, apt 설치는 자동 업데이트가 되지 않으므로 직접 업데이트해야 합니다. 특정 버전을 설치하려면 다음과 같이 실행합니다.

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.299

네트워크 제한 때문에 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1을 설정했다면 자동 업데이트도 꺼져 있습니다. 이 경우 2.1.299 같은 수정은 직접 설치해야 들어옵니다. 내 버전 이후 무엇이 바뀌었는지 찾거나 이전 버전으로 되돌리는 방법은 Claude Code 업데이트 내역: 내 버전 이후 변경 찾기와 롤백을 참고하세요.

그 외 게이트웨이 관련 변경으로는 2.1.290에서 beta 헤더를 400이 아닌 상태 코드로 거부하는 프록시·게이트웨이 뒤에서 요청이 실패하던 문제가 고쳐졌습니다.

300초 이상 응답이 없는 느린 모델은 2.1.299 이후에도 끊길 수 있습니다. 환경 변수 문서에 따르면 직접 Anthropic API가 아닌 제공자에서는 데이터가 오지 않으면 스트림을 중단하는 5분 유휴 타임아웃이 기본으로 켜져 있고, API_FORCE_IDLE_TIMEOUT=0으로 끌 수 있습니다. 다만 별도의 스트림 감시 기능은 이 값과 관계없이 동작합니다. 요청 단위 타임아웃 API_TIMEOUT_MS의 기본값은 600000(10분)입니다.

설정이 맞아도 안 되는 경우: Claude가 아닌 모델과 꺼지는 기능

위의 확인을 모두 통과했는데도 특정 기능이 안 된다면 설정 오류가 아니라 이 경로의 한계일 수 있습니다. 여기서는 더 고칠 것이 없고 경로를 바꿀지 판단해야 합니다.

Claude가 아닌 모델은 지원 범위 밖입니다. Anthropic의 LLM 게이트웨이 문서에 따르면 Anthropic은 어떤 게이트웨이를 통해서든 Claude Code를 Claude가 아닌 모델에 연결하는 것을 지원하지 않습니다. DeepSeek, GLM, Kimi, Qwen이나 로컬 모델을 연결해 생기는 도구 호출 실패, 형식 오류는 Anthropic이 고쳐 줄 문제가 아닙니다. OpenRouter도 Claude Code는 Anthropic 1P 제공자에서만 동작을 보장한다고 밝히고 있습니다. Ollama 문서는 도구를 지원하는 모델을 고르라고 하며, 호스팅 WebSearch와 고급 도구 제어는 완전히 지원되지 않고 큰 저장소에는 64k 이상 컨텍스트를 권합니다.

게이트웨이를 쓰면 설계상 꺼지는 기능이 있습니다.

• MCP 도구 검색: ANTHROPIC_BASE_URL이 Anthropic이 아닌 호스트를 가리키면 기본으로 꺼집니다. 게이트웨이가 tool_reference 블록을 전달한다면 ENABLE_TOOL_SEARCH=true로 켤 수 있습니다.
• Remote Control: 2.1.196부터 api.anthropic.com이 아닌 호스트를 가리키면 꺼지고, 게이트웨이 자격 증명이 활성일 때도 쓸 수 없습니다.
• 음성 입력: 게이트웨이 자격 증명이 활성이면 쓸 수 없습니다.
• /fast: fast mode 확인 요청은 ANTHROPIC_BASE_URL을 따르지 않고 api.anthropic.com으로 직접 갑니다. 직접 연결이 막힌 네트워크에서는 Fast mode unavailable due to network connectivity issues가 나옵니다.

이런 기능이 꼭 필요하다면 게이트웨이 변수를 해제하고 claude.ai 로그인으로 돌아가는 수밖에 없습니다. Remote Control은 자격 증명과 ANTHROPIC_BASE_URL을 모두 해제해야 합니다.

오류 코드가 529나 500이라면 그 응답이 Anthropic에서 왔는지 게이트웨이가 만든 것인지부터 구분해야 합니다. Claude 529 overloaded_error란? 2026년 기준 의미와 해결 방법과 Claude API 500 오류: 무작정 재시도하기 전에 request_id를 남기세요에서 각각 다룹니다. Codex에 외부 모델을 연결하는 비슷한 작업은 Codex에 외부 모델 API를 연결할 때 확인할 네 가지 경계를 참고하세요.

ANTHROPIC_BASE_URL 설정에 관한 자주 묻는 질문

ANTHROPIC_BASE_URL만 바꾸면 Claude Code 구독 한도를 쓰지 않나요?

아닙니다. 자격 증명 변수 없이 ANTHROPIC_BASE_URL만 설정하면 요청은 게이트웨이로 가지만 저장된 claude.ai 로그인이 활성 자격 증명으로 남아 구독 한도와 과금이 그대로 적용됩니다. ANTHROPIC_AUTH_TOKEN이나 ANTHROPIC_API_KEY가 활성일 때만 요청이 게이트웨이 자격 증명으로 나가며, 그 비용은 게이트웨이가 전달하는 자격 증명의 소유자에게 토큰 단위로 청구됩니다. /status에서 Login method 줄 대신 Auth token 또는 API key 줄이 보이는지 확인하세요.

LiteLLM이나 사내 게이트웨이도 같은 순서로 확인하나요?

네. Anthropic 형식(/v1/messages)을 제공하는 게이트웨이라면 제품과 관계없이 /status 두 줄 → curl → 오류 문구 순서가 같습니다. 게이트웨이가 키를 어느 헤더에서 읽는지(Authorization: Bearer 또는 x-api-key)는 게이트웨이 담당자나 설정에서 확인해 자격 증명 변수를 고르세요.

2.1.299로 올려야 하는 사람은 누구인가요?

ANTHROPIC_BASE_URL과 게이트웨이 키를 함께 쓰는 사람, 데이터 없이 180초 뒤 스트림이 끊기던 사람, 게이트웨이 전용 모델 이름으로 200K 근처에서 Prompt is too long · automatic compaction failed를 본 사람입니다. 2026년 10월 15일 기준 stable 채널은 2.1.292이므로, stable이나 Homebrew claude-code를 쓰고 있다면 직접 2.1.299 이상을 설치해야 이 수정이 들어옵니다.

GitHub Actions에서 게이트웨이를 쓰려면 어디에 넣나요?

claude-code-action은 워크플로 env의 ANTHROPIC_BASE_URL과 ANTHROPIC_CUSTOM_HEADERS를 읽습니다. 게이트웨이 키는 anthropic_api_key 입력으로 넘기면 x-api-key로 전송되고, bearer 방식 게이트웨이라면 env에 ANTHROPIC_AUTH_TOKEN도 넣어야 합니다. 자세한 예시는 GitHub Actions 설정 설명에 있습니다.