Claude Code 사용자 지정 API 연동 가이드: Base URL, 키, 모델 (2026)

Claude Code는 Anthropic이 제공하는 명령줄 코딩 도구로, 기본적으로 Anthropic 공식 API에 연결됩니다. 중국 내 팀은 실제 사용에서 접속 안정성, 통합 과금, 할당량 관리를 해결하기 위해 이를 자체 구축 또는 서드파티 게이트웨이로 향하게 하는 경우가 많습니다. 이른바 "사용자 지정 API 연동"은 본질적으로 세 가지만 바꾸는 일입니다. 요청이 어디로 가는지(Base URL), 어떤 자격 증명으로 인증하는지(Key), 어떤 모델을 호출하는지(모델 이름)입니다.

이 글은 설치, 환경 변수, 설정 파일, 모델 선택, 연결 검증, 팀 도입, 보안 순서로 재사용 가능한 연동 절차를 설명합니다. 명령은 macOS와 Linux를 기준으로 하며, Windows는 별도로 표시합니다.

안내: Claude와 Anthropic은 해당 권리자의 상표이며, 이 글은 기술 연동 설명만을 목적으로 하고 관련 업체와 소속 관계가 없습니다. Claude Code는 버전 업데이트가 빠르므로 환경 변수, 설정 항목, 메뉴 이름이 버전에 따라 달라질 수 있습니다. claude --help, 공식 문서, 사이트 내 연동 안내를 기준으로 확인하세요.

1. 연동 전에 확인할 세 가지

Claude Code는 Anthropic Messages 프로토콜을 사용하며 OpenAI의 Chat Completions 프로토콜이 아닙니다. 따라서 사용자 지정 API는 최소한 두 가지를 충족해야 합니다. Anthropic 호환 /v1/messages 진입점을 제공해야 하고, 모델 이름이 게이트웨이가 실제로 제공하는 이름과 일치해야 합니다. OpenAI 호환 진입점만 있는 게이트웨이는 Anthropic 호환 라우트를 함께 제공하지 않는 한 Claude Code에 그대로 입력할 수 없습니다.

시작 전에 세 가지를 준비하세요.

Base URL: 게이트웨이 루트 주소입니다. 예: https://ai.zhongshangqihang.com. /v1 포함 여부는 게이트웨이 구현에 따라 다르므로 사이트 내 연동 안내를 기준으로 합니다.
API Key: 콘솔에서 생성하고 할당량 상한과 유효 기간을 설정하세요. 장기간 무제한인 키를 테스트에 그대로 쓰지 마세요.
모델 이름: 콘솔이나 가격 페이지에서 복사하고 기억으로 직접 쓰지 마세요. 대소문자나 하이픈이 한 글자만 틀려도 모델이 존재하지 않는다는 오류가 날 수 있습니다.

아직 계정이 없다면 가입 페이지에서 시작해 낮은 할당량의 테스트 키를 먼저 만들 수 있습니다.

2. Claude Code 설치

Claude Code는 보통 npm으로 배포되며 다른 설치 방식도 제공됩니다. 가장 일반적인 절차는 다음과 같습니다.

Node.js가 설치되어 있는지 확인합니다. 유지 관리 중인 LTS 버전을 권장하며, 최소 버전은 공식 문서를 기준으로 합니다.
npm install -g @anthropic-ai/claude-code로 전역 설치합니다.
claude --version을 실행해 명령이 사용 가능한지 확인하고 버전 번호를 기록합니다.
테스트 프로젝트 디렉터리로 이동해 claude를 실행하고, 안내에 따라 테마, 디렉터리 신뢰 등 첫 설정을 완료합니다.
팀에 버전 관리 요구 사항이 있다면 버전을 고정하고 온보딩 문서에 적어 둡니다. 업그레이드 전에는 테스트 프로젝트에서 먼저 검증합니다.

node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude

사용자 지정 API를 쓸 때는 보통 Anthropic 계정 로그인이 필요하지 않지만, 로그인을 건너뛸 수 있는지는 버전과 설정 방식에 따라 다릅니다. 실행 후에도 로그인을 요구한다면 환경 변수가 Claude Code를 시작한 같은 셸에서 적용되었는지 먼저 확인하세요.

3. 환경 변수: BASE_URL과 AUTH_TOKEN

Claude Code는 두 가지 주요 인증 변수를 읽습니다.

ANTHROPIC_BASE_URL: 요청 루트 주소입니다.
ANTHROPIC_AUTH_TOKEN: Authorization: Bearer 형식으로 전송되며 게이트웨이 연동에서 흔히 사용됩니다.
ANTHROPIC_API_KEY: x-api-key 형식으로 전송되며 Anthropic 기본 인증 방식에 가깝습니다.

둘 중 하나만 선택하면 됩니다. 게이트웨이가 Bearer 인증을 쓴다면 ANTHROPIC_AUTH_TOKEN을, 기본 방식으로 인증한다면 ANTHROPIC_API_KEY를 사용하세요. 두 개를 동시에 설정하면 버전에 따라 우선순위가 달라 "분명히 맞게 입력했는데 401이 나는" 상황이 생기기 쉬우므로 하나만 남기는 것이 좋습니다.

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-여기에-키"
claude

~/.zshrc나 ~/.bashrc에 기록하면 설정이 오래 유지되며, 수정 후 source ~/.zshrc를 실행합니다. Windows PowerShell에서는 $env:ANTHROPIC_BASE_URL="..."을 사용하며 현재 창에만 적용됩니다. 영구 적용이 필요하면 시스템 환경 변수 화면이나 setx를 사용하고, 수정 후 터미널을 다시 여세요.

export를 프로젝트 스크립트에 넣어 커밋하지 마세요. 키가 Git 기록에 들어가면 파일을 삭제해도 기록이 삭제되는 것은 아닙니다.

4. settings.json: 설정을 파일로 고정

환경 변수는 임시 전환에 적합하고, 장기 사용에는 Claude Code의 설정 파일에 기록하는 것이 좋습니다. 일반적인 위치는 세 층입니다.

사용자 수준: ~/.claude/settings.json, 이 컴퓨터의 모든 프로젝트에 적용됩니다.
프로젝트 수준: .claude/settings.json, 저장소에 커밋할 수 있어 민감하지 않은 팀 공용 설정에 적합합니다.
로컬 프로젝트 수준: .claude/settings.local.json, 커밋하지 않으며 개인 재정의에 적합합니다.

예시:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-여기에-키"
  },
  "model": "claude-sonnet-4-5"
}

주의: settings.json의 키는 평문입니다. 개인 컴퓨터에서는 허용할 수 있지만 공유 장비, CI, 코드 저장소에서는 이렇게 하지 마세요. 프로젝트 수준 파일에는 Base URL과 모델 이름만 두고, 키는 환경 변수나 시크릿 관리 도구에 맡깁니다. 설정 우선순위는 대체로 기업 관리 설정, 명령줄 인수, 로컬 프로젝트, 프로젝트, 사용자 순으로 덮어쓰며, 구체적인 내용은 현재 버전 문서를 기준으로 합니다.

5. 모델 선택: 작업별 등급

Claude 모델은 보통 세 등급으로 나뉘며 적합한 작업이 다릅니다.

등급	대표 용도	장단점
Opus	복잡한 리팩터링, 파일 간 분석, 긴 체인의 Agent	성능이 높지만 비용이 더 들고 속도가 느릴 수 있음
Sonnet	일상 코딩, 버그 수정, 코드 리뷰	성능과 비용이 균형적이며 기본 등급으로 적합
Haiku	단순 완성, 포매팅, 대량의 작은 작업	빠르고 비용이 낮지만 복잡한 작업에는 부족할 수 있음

Claude Code에서는 ANTHROPIC_MODEL로 주 모델을 지정할 수 있고, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL로 등급별 매핑을 각각 재정의할 수 있습니다. 버전에 따라 지원 변수가 다를 수 있으므로 설정 전에 claude --help나 공식 문서를 확인하세요.

모델 이름은 게이트웨이의 모델 목록과 일치해야 합니다. 게이트웨이는 업스트림 모델에 자체 이름을 붙일 수 있으므로 공식 문서의 이름을 그대로 입력해도 맞지 않을 수 있습니다. 사용 가능한 모델과 과금 방식은 모델 가격 페이지를 참고하세요. 가격은 모델 버전과 업스트림 정책에 따라 조정됩니다.

6. 연결 검증: 먼저 curl, 다음 Claude Code

Claude Code를 거치지 않고 curl로 게이트웨이 자체가 통하는지 먼저 검증합니다.

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "OK만 답하세요"}]
  }'

게이트웨이가 Bearer 인증을 쓴다면 x-api-key를 Authorization: Bearer $ANTHROPIC_AUTH_TOKEN으로 바꾸세요. 200이 반환되고 내용이 정상이라면 Base URL, 키, 모델 세 항목 중 최소 한 조합이 사용 가능하다는 뜻입니다.

그다음 Claude Code로 돌아와 순서대로 확인합니다.

claude --version으로 클라이언트가 실행 가능한지 확인합니다.
프로젝트 디렉터리에서 claude doctor를 실행합니다(현재 버전이 제공하는 경우). 설치와 설정을 점검합니다.
claude를 시작하고 /status로 현재 모델과 계정 정보를 확인합니다.
위험도가 낮은 작업을 입력합니다. 예: "이 디렉터리의 구조를 설명하고 파일은 수정하지 마세요."
정상적으로 응답하는지, 401, 404, 모델 없음 등의 오류가 나오는지 관찰합니다.

자주 나타나는 현상 비교:

현상	우선 확인	처리
401	키, 변수 이름, 요청 헤더	키를 다시 복사하고 인증 변수를 하나만 유지
404	Base URL에 `/v1`이 더 있거나 빠짐	게이트웨이 문서에 따라 루트 주소 또는 호환 진입점으로 수정
model not found	모델 이름과 게이트웨이 목록 불일치	콘솔이나 가격 페이지에서 복사
요청 시간 초과	네트워크, DNS, 프록시	다른 네트워크에서 테스트하고 프록시가 헤더를 바꾸는지 확인
429	동시성 또는 할당량 제한	동시성을 낮추고 키의 한도 확인

7. 팀 도입: 1인 1키, 통합 진입점

팀에서 사용할 때는 하나의 키를 공유하지 않는 것이 좋습니다. 더 안전한 방법은 다음과 같습니다.

1인 1키로 운영하고 이름에 성명이나 용도를 포함하며, 퇴사 시 바로 비활성화합니다.
프로젝트나 환경별로 할당량 상한을 설정하고 운영과 테스트를 분리합니다.
통합 게이트웨이로 사용량, 모델 분포, 비정상 호출을 한곳에서 확인합니다.
기업 관리 설정으로 Base URL과 허용 모델을 배포해 구성원의 수동 설정 오류를 줄입니다.
연동 절차를 온보딩 문서로 작성하고 검증 명령과 흔한 오류를 포함합니다.
주간 또는 월간으로 사용량을 검토하고 비정상 키를 즉시 처리합니다.

회사에 구매와 규정 절차가 있다면 데이터 흐름을 먼저 확인하세요. 코드 조각은 게이트웨이와 그 업스트림 모델 서비스로 전송됩니다. 보관 여부, 보관 기간, 학습 사용 여부는 서비스 약관을 확인해야 하며 임의로 가정하지 마세요.

8. 보안 경계: 키, 코드, 데이터

마지막으로 몇 가지 기본 원칙입니다.

키를 Git, 이미지, 프런트엔드 코드, 스크린샷, 채팅 기록에 남기지 않습니다.
프로젝트에 .gitignore를 추가해 최소한 .env, .env.*, .claude/settings.local.json을 포함합니다.
유출이 의심되면 먼저 기존 키를 폐기한 뒤 사용량을 점검합니다. 비밀번호만 바꾸지 마세요.
키에 만료 시간을 설정하고 인사 변동 시 교체합니다.
공유 장비에서는 시크릿 관리 도구나 apiKeyHelper를 사용하고 settings.json에 평문으로 쓰지 않습니다.
신뢰할 수 있는 출처에서만 Claude Code를 설치하고, 업그레이드 전에 변경 사항을 확인합니다.

자주 묻는 질문

Claude Code는 반드시 Anthropic 계정에 로그인해야 하나요?

반드시 그렇지는 않습니다. 사용 가능한 Base URL과 인증 변수를 설정하면 클라이언트가 사용자 지정 API로 직접 연결할 수 있습니다. 다만 첫 실행 시 테마, 디렉터리 신뢰 등 안내가 여전히 나올 수 있습니다. 로그인 필요 여부는 버전과 설정에 따라 다르며, 문제가 생기면 환경 변수가 시작 셸에서 적용되는지 먼저 확인하세요.

ANTHROPIC_API_KEY와 ANTHROPIC_AUTH_TOKEN의 차이는 무엇인가요?

전자는 보통 x-api-key 요청 헤더로, 후자는 Authorization: Bearer로 전송됩니다. 어느 것을 쓸지는 게이트웨이의 인증 방식에 따라 다르며, 요청 헤더 충돌을 피하려면 하나만 설정하는 것이 좋습니다.

Base URL에는 루트 주소를 넣어야 하나요, /v1을 붙여야 하나요?

Claude Code에는 보통 루트 주소를 넣고 클라이언트가 /v1/messages를 조합합니다. 일부 게이트웨이는 호환 진입점을 직접 요구합니다. 판단 방법은 간단합니다. curl로 루트 주소에 /v1/messages를 붙여 요청해 통하면 루트 주소를 쓰고, 그렇지 않으면 게이트웨이 문서에 따라 조정하세요.

curl은 되는데 Claude Code에서 오류가 나는 이유는 무엇인가요?

흔한 원인은 셸 변수가 그래픽 인터페이스나 IDE 내장 터미널로 전달되지 않았거나, 인증 변수 두 개를 동시에 설정해 충돌한 경우입니다. Claude Code를 시작한 같은 터미널에서 echo $ANTHROPIC_BASE_URL을 실행해 확인하세요.

팀이 하나의 키를 공유해도 되나요?

기술적으로는 가능하지만 권장하지 않습니다. 공유 키는 구성원별 사용량을 구분할 수 없고 유출 시 책임자도 찾기 어렵습니다. 1인 1키에 할당량과 만료 시간을 붙이면 관리 비용이 오히려 낮습니다.

다음 단계

사용 가능한 게이트웨이 계정이 없다면 가입 페이지에서 시작해 낮은 할당량의 테스트 키를 만들고, 이 글의 curl과 Claude Code 두 단계로 검증하세요. 모델과 과금은 모델 가격 페이지를 참고하세요. 가격은 조정될 수 있으므로 페이지의 실시간 정보를 기준으로 합니다.