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

> ANTHROPIC_BASE_URL만 넣으면 Claude Code는 claude.ai 로그인을 계속 씁니다. /status와 curl로 원인을 가리고, 게이트웨이라면 2.1.299 이상인지 확인하세요.

- Source: https://www.aifreeapi.com/ko/posts/claude-code-anthropic-base-url-not-working
- Language: ko
- Published: 2026-10-15
- Updated: 2026-10-15
- Publisher: AI Free API (https://www.aifreeapi.com)

`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`로 설치했다면 이 수정이 적용되지 않은 상태입니다.

| 보이는 증상 | 막힌 단계 | 먼저 할 일 |
| --- | --- | --- |
| 변수를 넣었는데 claude.ai 로그인 화면이 뜸 | 자격 증명이 세션에 없음 | `ANTHROPIC_AUTH_TOKEN`을 셸 또는 `~/.claude/settings.json`에 설정 |
| `/status`에 `Anthropic base URL` 줄이 없음 | 변수가 세션에 닿지 않음 | 실행 위치와 settings 파일 `env` 확인 |
| `401` 인증 실패 | 자격 증명이 게이트웨이가 읽지 않는 헤더로 감 | 자격 증명 변수를 다른 쪽으로 교체 |
| `ConnectionRefused`, `ENOTFOUND` | 주소나 네트워크 경로 | URL 철자, VPN, 방화벽 확인 |
| `HTTP 200`인데 malformed response, `404` | URL 형태가 틀렸거나 HTML 페이지가 응답 | 끝의 `/v1` 제거, 게이트웨이 라우트 확인 |
| `400` + `Extra inputs are not permitted` | 게이트웨이가 Claude Code의 필드를 거부 | `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |
| 터미널은 되는데 VS Code·데스크톱 앱은 안 됨 | 그 화면이 변수를 다른 곳에서 읽음 | VS Code는 `claudeCode.environmentVariables`, 데스크톱 앱은 별도 설정 |
| 업데이트 직후부터 실패 | 특정 버전의 동작 변화 | 버전 확인 후 2.1.299 이상 또는 알려진 해결책 적용 |

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

Claude Code를 실행한 뒤 `/status`를 입력하면 **Status** 탭이 열립니다. [Anthropic의 LLM 게이트웨이 연결 문서](https://code.claude.com/docs/en/llm-gateway-connect#check-for-an-existing-configuration)에 따르면 확인할 줄은 두 개입니다.

- `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·자격 증명·게이트웨이에 있습니다.

```bash
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에서는 같은 요청을 이렇게 보냅니다.

```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 결과 | 의미 | 다음 단계 |
| --- | --- | --- |
| `{"id":"msg_`로 시작하는 JSON | 주소와 자격 증명 모두 정상 | Claude Code 쪽 전달 문제를 확인 |
| 알 수 없는 모델이라는 오류 | 인증은 통과함. 모델 이름만 거부됨 | URL과 자격 증명은 맞음. Claude Code 쪽 확인 |
| `401` | 자격 증명이 거부됨 | 다른 자격 증명 변수로 바꿔 다시 export |
| 연결 거부, 호스트를 찾을 수 없음 | 아무것도 응답하지 않음 | URL 철자, VPN, 방화벽 확인 |
| HTML 페이지, `404` | API가 아닌 응답 | URL 끝 `/v1` 여부와 게이트웨이 라우트 확인 |

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

![/status의 Anthropic base URL 줄, Auth token·API key 줄, curl 응답 순서로 막힌 단계를 찾는 흐름도. 각 단계에서 없음이면 변수 전달 문제나 자격 증명 문제로, curl 결과가 msg_·401·연결 실패면 각각 Claude Code 쪽 확인, 변수 교체, URL·네트워크 확인으로 이어진다](https://www.aifreeapi.com/posts/ko/claude-code-anthropic-base-url-not-working/img/status-curl-flow.webp)

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

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

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

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 연동 문서](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration)는 이 충돌이 `openrouter/auto` 같은 모델을 찾을 수 없다는 오류로 나타나기도 한다고 적고 있습니다. 모델 오류처럼 보여도 실제 원인은 남아 있는 로그인일 수 있으니 `/logout` 후 `claude`를 다시 실행해 보세요.

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

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

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

| 변수 | 보내는 헤더 | 쓰는 경우 |
| --- | --- | --- |
| `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer <키>` | 게이트웨이 담당자가 "bearer token" 또는 "Authorization 헤더"라고 안내한 경우, 모를 때 |
| `ANTHROPIC_API_KEY` | `x-api-key: <키>` | "API key" 또는 "x-api-key"라고 안내한 경우 |
| `apiKeyHelper` | 두 헤더 모두 | 키가 주기적으로 바뀌거나 볼트에서 가져오는 경우 |

게이트웨이가 읽지 않는 헤더에 키가 실리면 키 자체는 맞아도 `401`이 납니다. [헤더 대응 설명](https://code.claude.com/docs/en/llm-gateway-connect#how-the-credential-variable-maps-to-a-header)대로 다른 변수로 옮겨 다시 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한 값과 다르다면, 같은 변수를 다른 곳에서도 설정했을 가능성이 높습니다. [공식 문서](https://code.claude.com/docs/en/llm-gateway-connect#set-in-a-settings-file)의 규칙은 분명합니다. 셸 export와 settings 파일의 `env` 블록이 같은 변수를 설정하면 **settings 파일 값이 적용됩니다.** Ollama 문서도 Claude 설정이 셸 변수를 덮어쓸 수 있다고 적고 있습니다. 셸에서 방금 export한 값이 이긴다고 생각하기 쉽지만 실제 순서는 반대입니다.

```json
{
  "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)`을 열고 다음을 추가합니다.

```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을 아예 읽지 않습니다. [데스크톱 앱 설정 설명](https://code.claude.com/docs/en/llm-gateway-connect#desktop-app)에 따르면 관리자가 배포한 서드파티 추론 설정을 쓰거나, 직접 설정하려면 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에는 **루트 주소만** 넣습니다.

| 연결 대상 | 문서에 적힌 base URL |
| --- | --- |
| OpenRouter | `https://openrouter.ai/api` |
| Ollama (로컬) | `http://localhost:11434` |
| Ollama 클라우드 | `https://ollama.com` |

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

연결 단계의 오류는 [트러블슈팅 표](https://code.claude.com/docs/en/llm-gateway-connect#troubleshoot-gateway-errors) 기준으로 이렇게 나뉩니다.

- `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 형식으로 보내는 필드를 받아들이지 않는 것입니다. 게이트웨이가 요청을 업스트림에 그대로 넘기고, 업스트림이 모르는 필드를 거부할 때 생깁니다. 오류 문구로 구분합니다.

| 오류 문구 | 원인 | 조치 |
| --- | --- | --- |
| `context_management`, `Extra inputs are not permitted` 등 모르는 필드 | 출시 전 기능 필드를 거부 | `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |
| 세션 제목, 메모리 불러오기, 프롬프트 훅만 실패 | 구조화 출력 필드를 거부 | `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1`(2.1.288 이상) |
| `thinking`, `adaptive` 포함(예: `Input tag 'adaptive' found`) | 상위 모델 빌드가 adaptive reasoning을 지원하지 않음 | 게이트웨이의 상위 모델 업그레이드. Opus 4.6·Sonnet 4.6은 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |
| `ContextWindowExceededError`, `prompt token count of N exceeds the limit of M` | 게이트웨이가 컨텍스트 초과 오류를 자기 문구로 바꿔 Claude Code가 자동 압축을 하지 못함 | `/compact`로 복구, `CLAUDE_CODE_AUTO_COMPACT_WINDOW`를 게이트웨이 한도로 설정 |

`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에서 끊긴다면 [변경 내역](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)이 안내하는 대로 `/autocompact 200k`를 실행합니다.

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

- [#95087](https://github.com/anthropics/claude-code/issues/95087): 커스텀 base URL에서 세션의 첫 요청에 `tool_addition` 블록(베타 `mid-conversation-tool-changes`)이 실려, 엄격한 Anthropic 호환 서버가 400으로 거부한다는 보고입니다. 보통은 Claude Code가 이 블록을 빼고 조용히 다시 보내 겉으로는 문제가 없지만, 2026년 10월 13일 댓글은 2.1.296에서 재전송이 일어나지 않아 대화를 더 이어갈 수 없었다고 적고 있습니다.
- [#101897](https://github.com/anthropics/claude-code/issues/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이 안 보일 때: 증상별 해결법](/ko/posts/claude-code-fable-5-1-not-available)에서 다룹니다.

## 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 항목](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)에는 `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 근처에서 멈추던 경우입니다.

![2.1.292, 2.1.296, 2.1.299, 2.1.300 버전 타임라인. stable 채널과 Homebrew claude-code는 2.1.292에 머물러 수정이 없고, latest 채널은 2.1.300으로 수정이 포함되며, 아래에 2.1.299에서 고친 게이트웨이 문제 네 가지가 카드로 정리되어 있다](https://www.aifreeapi.com/posts/ko/claude-code-anthropic-base-url-not-working/img/version-2-1-299-channels.webp)

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

| 설치 방식 | 받는 버전(2026년 10월 15일 기준) | 2.1.299 수정 |
| --- | --- | --- |
| 기본 `latest` 채널, `claude update` | 2.1.300 | 포함 |
| `stable` 채널 | 2.1.292 | 미포함 |
| Homebrew `claude-code` | stable 추적 | 미포함 |
| Homebrew `claude-code@latest` | latest 추적 | 포함(수동 업데이트 필요) |

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

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

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

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

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

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

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

**Claude가 아닌 모델은 지원 범위 밖입니다.** [Anthropic의 LLM 게이트웨이 문서](https://code.claude.com/docs/en/llm-gateway)에 따르면 Anthropic은 어떤 게이트웨이를 통해서든 Claude Code를 Claude가 아닌 모델에 연결하는 것을 지원하지 않습니다. DeepSeek, GLM, Kimi, Qwen이나 로컬 모델을 연결해 생기는 도구 호출 실패, 형식 오류는 Anthropic이 고쳐 줄 문제가 아닙니다. OpenRouter도 Claude Code는 Anthropic 1P 제공자에서만 동작을 보장한다고 밝히고 있습니다. [Ollama 문서](https://docs.ollama.com/integrations/claude-code)는 도구를 지원하는 모델을 고르라고 하며, 호스팅 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년 기준 의미와 해결 방법](/ko/posts/claude-529-overloaded-error)과 [Claude API 500 오류: 무작정 재시도하기 전에 request_id를 남기세요](/ko/posts/claude-api-error-500)에서 각각 다룹니다. Codex에 외부 모델을 연결하는 비슷한 작업은 [Codex에 외부 모델 API를 연결할 때 확인할 네 가지 경계](/ko/posts/codex-third-party-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 설정 설명](https://code.claude.com/docs/en/llm-gateway-connect#github-actions)에 있습니다.