Claude Code
게이트웨이의 Claude 모델로 코딩 작업 시작하기
환경 변수와 설정 파일에 게이트웨이 주소 및 모델을 지정하고, Messages API를 통한 호출과 연결 오류를 확인하는 방법을 안내합니다.
페이지 목차
시작 전 준비
설정을 마치면 Claude Code가 AI 게이트웨이를 거쳐 에셋의 Claude 모델을 호출합니다. Claude Code가 사용하는 Anthropic Messages API의 기본 URL을 게이트웨이 주소로 설정하고, 인증에는 AI 게이트웨이 API 키를 사용합니다. 사용할 Claude 모델은 에셋의 모델 코드로 지정합니다.
- AI 게이트웨이 API 키
현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.
- Claude 모델 코드
에셋에서 Messages를 지원하는 Claude 모델의 정확한 코드를 확인합니다.
- Claude Code
로컬 환경에 Claude Code를 설치합니다. 설치 방법은 공식 설치 안내 를 따릅니다.
Claude Code에 넣을 값은 아래 단계에 모두 있습니다. API 형식별 기본 URL과 인증 헤더 전체는 인증과 기본 URL에 정리돼 있습니다.
연결 설정
API 키는 Claude Code 실행 환경의 환경 변수로 전달합니다. 기본 URL과 모델은 환경 변수로 지정하거나 settings.json에 저장할 수 있습니다.
API 키 환경 변수 설정하기
실제 키를 명령어나 설정 파일에 직접 입력하지 마세요settings.json처럼 Claude Code가 읽는 설정 파일도 마찬가지입니다.실행 환경에서
ANTHROPIC_API_KEY환경 변수에 AI 게이트웨이 API 키를 설정합니다.claude명령을 실행하는 프로세스가 이 변수를 읽을 수 있어야 합니다. Claude Code는 이 값을x-api-key헤더로 보냅니다.대화형 세션에서는 Claude Code가 이 키를 사용할지 한 번 묻습니다. 사용자가 승인해야 키가 적용됩니다.
-p비대화형 실행에서는 Claude Code가 승인 없이 키를 사용합니다.ANTHROPIC_AUTH_TOKEN이 함께 설정되어 있으면 Claude Code가 그 값을 우선 사용하므로, 다른 용도의 값이 남아 있다면 해제합니다.기본 URL 지정하기
ANTHROPIC_BASE_URL에/v1을 붙이면 요청 경로가 잘못되어 호출이 실패합니다Claude Code가
/v1/messages경로를 조합하므로ANTHROPIC_BASE_URL은/v1없이 지정하세요.ANTHROPIC_BASE_URL환경 변수에는https://gw.letsur.ai를 지정합니다.
settings.json으로 설정하기
환경 변수 대신 ~/.claude/settings.json의 env 블록에 기본 URL과 기본 모델을 지정할 수 있습니다. 이때도 ANTHROPIC_API_KEY는 앞 단계에 따라 환경 변수로 설정합니다.
{
"env": {
"ANTHROPIC_BASE_URL": "https://gw.letsur.ai",
"ANTHROPIC_MODEL": "<MODEL_CODE>"
}
}셸 환경 변수와 env 블록에 같은 변수가 있으면 env 블록의 값이 적용됩니다. 프로젝트의 .claude/settings.json이나 .claude/settings.local.json에도 같은 변수가 있으면 그 값이 ~/.claude/settings.json보다 우선하므로, 기존 값이 이 가이드의 설정과 충돌하는지 확인합니다.
모델 선택
<MODEL_CODE> 자리에는 앞에서 확인한 에셋의 정확한 모델 코드를 넣습니다. 적용 범위에 맞는 방법을 고르세요.
- 기본 모델 지정: 실행 환경의
ANTHROPIC_MODEL환경 변수에 모델 코드를 넣습니다. settings.json의env블록에 넣어도 됩니다. - 이번 실행에만 지정: 실행할 때
--model옵션을 붙입니다.ANTHROPIC_MODEL과--model을 함께 지정하면--model의 값이 적용됩니다. - 대화 중에 바꾸기: 대화형 세션에서
/model <MODEL_CODE>명령을 실행합니다. 이 명령으로 고른 모델은 이후 세션의 기본 모델로 저장됩니다. - 백그라운드 작업 모델 고정:
ANTHROPIC_DEFAULT_HAIKU_MODEL환경 변수에 에셋에서 확인한 모델 코드를 넣습니다. 예전 변수인ANTHROPIC_SMALL_FAST_MODEL은 지원이 중단됐습니다.
claude --model "<MODEL_CODE>"연결 확인
다음 명령에 앞에서 선택한 모델 코드를 지정해 그 모델의 응답을 확인합니다. 환경 변수가 설정된 실행 환경에서 실행하세요.
claude --model "<MODEL_CODE>" -p "ping" --output-format text모델 응답이 출력되면 Claude Code가 게이트웨이를 거쳐 모델을 호출한 것입니다. 실제 작업에 사용할 도구 호출과 승인 동작은 코딩 작업 전에 별도로 확인합니다.
대화형 세션에서 /status를 실행하면 Status 탭에서 연결 상태를 확인할 수 있습니다. Anthropic base URL 줄에 게이트웨이 주소가 표시되고 API key 줄에 ANTHROPIC_API_KEY가 표시되면 Claude Code가 게이트웨이 주소와 AI 게이트웨이 API 키를 사용하고 있는 것입니다.
지원 범위와 제약
Claude Code는 Anthropic Messages API로 모델을 호출하므로 에셋에서 Messages를 지원하는 Claude 모델만 사용할 수 있습니다. 요청 필드와 응답 형식은 Messages 명세에서 확인합니다.
Claude Code 공식 문서에 따르면 ANTHROPIC_BASE_URL이 Anthropic이 아닌 주소를 가리키거나 API 키 환경 변수가 설정되어 있으면 Remote Control과 음성 입력을 사용할 수 없습니다. Claude Code는 인식하지 못하는 모델 코드의 컨텍스트 윈도를 200K 토큰으로 가정합니다.
문제 해결
| 증상 | 다음 행동 |
|---|---|
요청 경로가 /v1/v1/messages가 됩니다 | ANTHROPIC_BASE_URL에서 /v1을 제거합니다 |
401 응답이 반환됩니다 | ANTHROPIC_API_KEY의 키 값과 키 상태(비활성 또는 만료)를 확인합니다. ANTHROPIC_AUTH_TOKEN에 다른 값이 설정되어 있지 않은지도 봅니다 |
ANTHROPIC_API_KEY를 설정했는데 로그인 화면이 나타나거나 키가 사용되지 않습니다 | 대화형 세션에서 키 사용을 승인했는지 확인합니다. 이전에 거절했다면 /config에서 Use custom API key 옵션을 켭니다 |
| Claude Code가 모델을 찾지 못합니다 | ANTHROPIC_MODEL 또는 --model의 값이 에셋의 정확한 모델 코드와 일치하는지 확인합니다 |
그 밖의 오류는 오류 type별 대응에서 확인합니다.
설정 기준: Connect Claude Code to an LLM gateway , Claude Code gateway compatibility guide , Authentication , Environment variables , Settings files and precedence , Model configuration , CLI reference 의 기본 URL과 인증 환경 변수, 인증 헤더와 우선순위, 설정 파일 위치와 우선순위, 모델 지정 방법, -p와 /status 확인 방법, 사용자 지정 엔드포인트의 제약을 2026년 11월 13일에 확인했습니다. 이 확인에는 렛서 게이트웨이와의 실제 연동 시험이 포함되지 않습니다.