Claude Code 설정 시 제3자 API 중계 서비스 모델을 찾을 수 없는 문제를 해결하는 3가지 방법

작성자 주: Claude Code를 제3자 API 중계 서비스에 연결할 때 발생하는 '모델을 찾을 수 없음' 오류에 대한 완벽 해결책입니다. Base URL의 올바른 표기법, settings.json 설정 방법, 최신 모델명 대조표를 정리해 드립니다.

국내에서 Claude Code를 사용할 때 가장 자주 마주치는 오류는 바로 이것입니다:

There's an issue with the selected model (claude-sonnet-4-6). It may not exist or you may not have access to it. Run /model to pick a different model.

이 오류는 보통 다음 두 가지 상황에서 발생해요:

공식 API 키를 사용 중이지만 모델명을 잘못 입력한 경우 (간단히 /model을 입력해 다시 선택하면 해결됩니다)
제3자 API 중계 서비스를 사용 중인데, Base URL 설정이 올바르지 않아 모델 라우팅에 실패한 경우

이번 포스팅에서는 두 번째 상황에 대한 완벽한 해결책을 다룹니다. APIYI(apiyi.com)를 예로 들어 환경 변수 및 settings.json 설정 방법, 그리고 최신 Claude 모델명 대조표까지 모두 알려드릴게요.

핵심 가치: 이 글을 읽고 나면 Claude Code를 제3자 API 중계 서비스에 올바르게 연결하여 '모델을 찾을 수 없음' 오류를 해결하고, 국내 네트워크 환경에서도 Claude Code의 모든 기능을 안정적으로 사용할 수 있게 됩니다.

1. 문제 진단: 모델명 오류인가, Base URL 문제인가

설정을 변경하기 전에, 30초만 투자해서 어떤 문제인지 먼저 파악해 보세요:

증상	가능한 원인	해결 방향
`Run /model to pick a different model` 오류 메시지	모델명이 존재하지 않거나 권한 없음	`/model` 실행 후 다시 선택
정확한 모델명을 입력해도 계속 오류 발생	Base URL 설정 문제	ANTHROPIC_BASE_URL 확인
API 키 인증 실패	키가 유효하지 않거나 설정되지 않음	API 키 재설정
네트워크 타임아웃 / 연결 거부	중계 서비스 주소 오기입	Base URL 형식 확인
모든 모델에서 오류 발생	중계 서비스가 Anthropic 형식을 지원하지 않음	Anthropic 네이티브 프로토콜 지원 여부 확인

만약 공식 Anthropic API 키를 사용 중이고 anthropic.com에 정상적으로 접속 가능하다면, Claude Code에서 /model 명령어를 실행해 모델을 전환하기만 하면 됩니다. 별도의 설정은 필요 없어요.

하지만 제3자 API 중계 서비스(예: apiyi.com)를 사용 중이라면, 아래의 설정 가이드를 따라주세요.

🎯 팁: Claude Code 연결 시 APIYI(apiyi.com) 플랫폼을 추천합니다. Anthropic 네이티브 형식을 완벽히 지원하며, claude-opus-4-6, claude-sonnet-4-6 등 최신 모델 시리즈를 국내 네트워크에서도 안정적으로 호출할 수 있습니다.

2. 제3자 중계 API를 Claude Code에 연결하기 위한 핵심 설정

2.1 Base URL 올바른 형식: /v1 제거하기

이 단계는 가장 중요한 과정이자, 가장 실수하기 쉬운 부분이에요.

Claude Code는 Base URL에 대해 특별한 처리 로직을 가지고 있습니다. 사용자가 설정한 Base URL 뒤에 자동으로 /v1/messages를 추가하기 때문인데요. 따라서 다음과 같이 설정해야 합니다.

❌ 잘못된 작성 예시: ANTHROPIC_BASE_URL=https://api.apiyi.com/v1
- 실제 요청 경로: https://api.apiyi.com/v1/v1/messages (/v1이 중복됨)
- 결과: 라우팅 엔드포인트를 찾지 못해 모델 호출 오류 발생
✅ 올바른 작성 예시: ANTHROPIC_BASE_URL=https://api.apiyi.com
- 실제 요청 경로: https://api.apiyi.com/v1/messages
- 결과: Anthropic 네이티브 인터페이스에 정상적으로 연결됨

📌 요약하자면: ANTHROPIC_BASE_URL을 설정할 때는 도메인의 루트 경로만 입력하고, 뒤에 /v1 접미사를 붙이지 마세요. Claude Code가 알아서 전체 경로를 완성해 줍니다.

2.2 API 키 가져오기

APIYI 백엔드에 로그인하여 토큰을 가져오세요: APIYI 토큰 관리 페이지 (api.apiyi.com/token)

토큰 선택 가이드:

토큰 유형	권장 시나리오	할인 혜택
기본 토큰	일반적인 상황, 즉시 사용 가능	표준 가격
ClaudeCode 그룹 토큰	Claude Code 전용 사용	12% 할인 (88% 적용)

새 토큰을 생성할 때 ClaudeCode 그룹을 선택하면 12% 할인 혜택을 받을 수 있어, 장기적으로 사용 비용을 더 낮출 수 있습니다.

3. 두 가지 설정 방식 상세 안내

방식 1: 환경 변수 설정 (임시 테스트 권장)

터미널에서 다음 명령어를 실행하면 즉시 적용됩니다 (현재 세션에서만 유효):

# 제3자 API 중계 서비스 Base URL 설정 (주의: 끝에 /v1을 붙이지 마세요)
export ANTHROPIC_BASE_URL="https://api.apiyi.com"

# API 키 설정 (본인의 실제 키로 교체하세요)
export ANTHROPIC_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

# Claude Code 실행
claude

설정이 제대로 되었는지 확인하기:

# 현재 환경 변수 출력
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY

# 다음과 같이 출력되어야 합니다:
# https://api.apiyi.com
# sk-xxxxxx...

장단점:

✅ 빠르고 간편하며 파일을 수정할 필요가 없음
✅ 다른 세션의 설정에 영향을 주지 않음
❌ 터미널을 새로 열 때마다 다시 설정해야 함 (.zshrc 또는 .bashrc에 작성하지 않는 한)

영구 적용 방법 (Shell 설정 파일에 작성):

# zsh 사용자 (macOS 기본)
echo 'export ANTHROPIC_BASE_URL="https://api.apiyi.com"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-본인의키"' >> ~/.zshrc
source ~/.zshrc

# bash 사용자
echo 'export ANTHROPIC_BASE_URL="https://api.apiyi.com"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-본인의키"' >> ~/.bashrc
source ~/.bashrc

방식 2: settings.json 설정 (장기 사용 권장)

~/.claude/settings.json 파일을 편집합니다 (모든 프로젝트에 적용되는 전역 설정):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.apiyi.com",
    "ANTHROPIC_API_KEY": "sk-본인의API키"
  }
}

🎯 추천 방법: ~/.claude/settings.json을 사용해 전역 설정을 하면 한 번의 설정으로 영구 적용되어 매번 환경 변수를 설정할 필요가 없습니다. APIYI(apiyi.com)에서 API 키를 발급받고, ClaudeCode 그룹 토큰을 선택하면 12% 할인 혜택을 누릴 수 있어요.

파일이 없다면 수동으로 생성하세요:

# .claude 디렉토리 생성 (없는 경우)
mkdir -p ~/.claude

# settings.json 생성
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.apiyi.com",
    "ANTHROPIC_API_KEY": "sk-본인의키로교체"
  }
}
EOF

설정 우선순위 (높은 순서대로):

우선순위	설정 출처	설명
1 (최고)	환경 변수	터미널에서 직접 export 한 값
2	`.claude/settings.local.json`	프로젝트 로컬 설정 (git에 제외됨)
3	`.claude/settings.json`	프로젝트 공유 설정
4 (최저)	`~/.claude/settings.json`	전역 사용자 설정

동일한 설정 항목이 있을 경우, 높은 우선순위가 낮은 우선순위를 덮어씁니다. 프로젝트 디렉토리에 별도의 settings.json이 있다면 이 우선순위 관계를 꼭 기억해 두세요.

4. Claude Code 지원 최신 모델 명칭

다음은 2026년 최신 Claude 모델 명칭입니다. 대소문자와 숫자를 정확하게 입력해야 합니다.

표준 추론 모델

모델 이름	시리즈	성능 위치	활용 시나리오
`claude-opus-4-6`	Claude 4.6	최강 성능	복잡한 코드, 심층 분석, 대용량 문서 처리
`claude-sonnet-4-6`	Claude 4.6	성능과 속도의 균형	일상적인 프로그래밍, 코드 리뷰, 문서 작성
`claude-haiku-4-5-20251001`	Claude 4.5	초고속 응답	간단한 질의응답, 코드 완성, 빠른 작업

강화된 추론 모델 (사고 모드)

모델 이름 뒤에 -thinking 접미사를 붙이면 확장 사고 모드가 활성화됩니다. 모델이 답변하기 전에 심층적인 추론 과정을 거칩니다.

모델 이름	베이스 모델	특징
`claude-opus-4-6-thinking`	claude-opus-4-6	최강의 추론 능력, 수학/논리/복잡한 의사결정에 적합
`claude-sonnet-4-6-thinking`	claude-sonnet-4-6	추론과 속도의 균형, 일상적인 사용 시 최우선 선택
`claude-haiku-4-5-20251001-thinking`	claude-haiku-4-5-20251001	경량급 추론

💡 모델 선택 가이드: 일상적인 Claude Code 사용에는 코딩 품질과 응답 속도 사이의 균형이 가장 뛰어난 claude-sonnet-4-6을 추천합니다. 복잡한 아키텍처 설계나 해결하기 어려운 버그를 디버깅할 때는 claude-opus-4-6 또는 claude-sonnet-4-6-thinking으로 전환해 보세요.

5. Claude Code에서 모델 전환하기

Base URL과 API 키를 설정한 후, 모델을 전환하는 방법은 두 가지가 있습니다.

5.1 /model 명령어 사용하기 (가장 간단한 방법)

Claude Code 대화창에서 직접 입력하세요:

/model

Claude Code에서 모델 선택 목록이 나타납니다. 만약 제3자 API 중계 서비스를 사용 중이라면 목록에 모든 모델이 자동으로 표시되지 않을 수 있는데, 이럴 때는 모델 이름을 직접 입력해야 합니다.

5.2 settings.json에서 기본 모델 지정하기

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.apiyi.com",
    "ANTHROPIC_API_KEY": "sk-여러분의APIKey",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6"
  }
}

ANTHROPIC_DEFAULT_*_MODEL 환경 변수를 통해 각 모델 등급별로 정확한 모델 이름을 지정할 수 있습니다. 이를 통해 Claude Code가 내장된 기본 이름을 사용하여 중계 서비스의 모델명과 일치하지 않는 문제를 방지할 수 있습니다.

🎯 전체 설정 예시: 위 설정은 ~/.claude/settings.json에 저장하는 것을 권장하며, APIYI(apiyi.com)의 ClaudeCode 그룹 토큰을 ANTHROPIC_API_KEY로 사용하세요.

6. 자주 발생하는 오류 및 해결 방법 FAQ

Q1: ANTHROPIC_BASE_URL 설정 후 Claude Code가 아예 실행되지 않아요.

JSON 형식이 올바른지 확인해 보세요. 흔히 발생하는 실수는 다음과 같습니다:

마지막 키-값 쌍 뒤에 쉼표가 붙음 (JSON은 마지막 쉼표를 허용하지 않습니다)
따옴표를 영문 따옴표("")가 아닌 한국어/중국어 전각 따옴표(“”)로 사용함

# JSON 형식 검증하기
cat ~/.claude/settings.json | python3 -m json.tool

출력이 정상적으로 나오면 형식이 맞는 것이고, 오류가 발생하면 문법적인 문제가 있는 것입니다.

Q2: Invalid API key 오류가 뜨는데, 제 키는 확실히 맞거든요?

다음 원인들을 확인해 보세요:

키 앞뒤에 공백이 있는 경우 → 복사할 때 불필요한 공백이 포함되지 않았는지 확인하세요.
키가 만료되었거나 비활성화된 경우 → api.apiyi.com/token에 로그인하여 다시 생성하세요.
환경 변수 우선순위 문제 → 시스템에 기존의 ANTHROPIC_API_KEY 환경 변수가 남아 있을 수 있습니다.

# 여러 소스의 환경 변수가 있는지 확인
env | grep ANTHROPIC

Q3: 모델 호출은 되는데 결과 품질이 너무 낮거나 형식이 이상해요.

원인: API 중계 서비스가 Anthropic 형식을 완벽하게 지원하지 않을 수 있습니다. 특히 시스템 프롬프트(system prompt) 처리 부분에서 문제가 생길 수 있습니다.

검증 방법: curl을 사용하여 중계 서비스가 정상적인 응답을 반환하는지 직접 테스트해 보세요.

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-여러분의Key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Say hello"}]
  }'

정상적인 응답에는 content 필드와 실제 텍스트 출력이 포함되어야 합니다. 응답이 비정상적이라면 중계 서비스 자체에 문제가 있는 것입니다.

🎯 빠른 확인: APIYI(apiyi.com)는 Anthropic 네이티브 형식을 완벽하게 지원하므로 위 curl 테스트가 정상적으로 작동합니다. 다른 중계 서비스를 테스트 중이라면 이 명령어로 호환성을 빠르게 검증해 보세요.

Q4: Windows 시스템에서는 환경 변수를 어떻게 설정하나요?

Windows 사용자는 더 간단하고 확실한 settings.json 방식을 추천합니다:

// C:\Users\사용자이름\.claude\settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.apiyi.com",
    "ANTHROPIC_API_KEY": "sk-여러분의APIKey"
  }
}

PowerShell에서 임시 환경 변수를 설정하려면 다음과 같이 입력하세요:

$env:ANTHROPIC_BASE_URL = "https://api.apiyi.com"
$env:ANTHROPIC_API_KEY = "sk-여러분의APIKey"
claude

Q5: 프로젝트마다 다른 API 설정을 사용하고 싶어요.

프로젝트 루트 디렉토리에 .claude/settings.json을 생성하세요. 이 파일은 전역 설정보다 우선순위가 높습니다.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.apiyi.com",
    "ANTHROPIC_API_KEY": "sk-프로젝트전용Key"
  }
}

주의: 이 파일에 키가 포함되어 있다면, 실수로 코드 저장소에 제출되지 않도록 .gitignore에 추가하는 것이 좋습니다. 기본적으로 git이 추적하지 않는 .claude/settings.local.json(로컬 전용 설정)을 사용하는 것이 더 안전합니다.

7. 설정 확인 체크리스트

설정을 마친 후, 다음 단계에 따라 확인해 보세요.

# 1단계: 환경 변수 적용 여부 확인
echo "Base URL: $ANTHROPIC_BASE_URL"
echo "API Key: ${ANTHROPIC_API_KEY:0:10}..."

# 2단계: API 연결 테스트
curl -s https://api.apiyi.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" | head -c 200

# 3단계: Claude Code 실행 및 테스트
claude --version
claude

Claude Code 대화창에서 /status를 입력하여 현재 연결 상태를 확인하고, Base URL과 모델 설정이 올바른지 체크하세요.

🎯 설정 완료 후: 간단한 메시지를 보내 Claude Code가 정상적으로 응답하는지 테스트해 보는 것을 추천합니다. APIYI(apiyi.com) 플랫폼은 잔액 조회를 지원하므로, 관리 페이지에서 Claude Code의 토큰 사용량을 실시간으로 모니터링하며 비용을 효율적으로 관리할 수 있습니다.

요약

Claude Code를 타사 API 중계 서비스에 연결할 때 '모델을 찾을 수 없음' 오류가 발생하는 원인의 90%는 Base URL 형식이 잘못되었기 때문입니다. 핵심 원칙은 다음과 같습니다.

Base URL에 /v1을 붙이지 마세요: https://api.apiyi.com으로 입력하면 Claude Code가 자동으로 뒤에 /v1/messages를 추가합니다.
모델명을 정확하게 입력하세요: claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5-20251001과 같은 전체 이름을 사용해야 합니다.
settings.json 설정을 추천합니다: ~/.claude/settings.json에 작성하면 영구적으로 적용되어 매번 환경 변수를 설정할 필요가 없습니다.
Claude Code 전용 토큰: APIYI 관리 페이지에서 ClaudeCode 그룹을 선택하면 12% 할인 혜택을 받을 수 있습니다.

공식 Anthropic API 키만 사용하고 네트워크 연결에 문제가 없다면, Claude Code에서 바로 /model 명령어를 실행해 모델을 선택하면 됩니다. 별도의 설정은 필요하지 않습니다.

🎯 API 키 발급: APIYI(apiyi.com)에 접속하여 계정을 생성하고, 토큰 관리 페이지(api.apiyi.com/token)에서 ClaudeCode 그룹 토큰을 만드세요. 플랫폼은 종량제 방식을 지원하며 최소 소비 금액 제한 없이 실제 토큰 사용량에 따라 결제되므로 개인 및 팀 단위 사용에 적합합니다.

본 아티클은 APIYI 기술 팀에서 Claude Code v2.x 실측 데이터를 바탕으로 작성했습니다. 설정 관련 문의 사항은 APIYI 고객센터(help.apiyi.com)를 방문해 주세요.

Claude Code 설정 시 제3자 API 중계 서비스 모델을 찾을 수 없는 문제를 해결하는 3가지 방법

1. 문제 진단: 모델명 오류인가, Base URL 문제인가

2. 제3자 중계 API를 Claude Code에 연결하기 위한 핵심 설정

2.1 Base URL 올바른 형식: /v1 제거하기

2.2 API 키 가져오기

3. 두 가지 설정 방식 상세 안내

방식 1: 환경 변수 설정 (임시 테스트 권장)

방식 2: settings.json 설정 (장기 사용 권장)

4. Claude Code 지원 최신 모델 명칭

표준 추론 모델

강화된 추론 모델 (사고 모드)

5. Claude Code에서 모델 전환하기

5.1 /model 명령어 사용하기 (가장 간단한 방법)

5.2 settings.json에서 기본 모델 지정하기

6. 자주 발생하는 오류 및 해결 방법 FAQ

7. 설정 확인 체크리스트

요약

OpenClaw의 Claude API 연동을 위한 5단계 전체 설정: Anthropic Messages 형식으로 도구 호출 오류 해결

Google AI Studio 무료 할당량은 얼마인가요? 한도 도달 시 3가지 해결 방법

揭秘 OpenClaw 使用量最高的模型：Kimi K2.5 接入指南与 8 折优惠方案

Claude API 100만 토큰 컨텍스트 창 구현을 위한 전체 설정 가이드 및 5가지 주요 실전 시나리오

OpenClaw에서 Claude API 호출 시 발생하는 invalid beta flag 오류를 해결하는 5가지 방법

3단계 OpenCode API 중계소 연동 설정, 400+ AI 모델 자유 전환 잠금 해제

1. 문제 진단: 모델명 오류인가, Base URL 문제인가

2. 제3자 중계 API를 Claude Code에 연결하기 위한 핵심 설정

2.1 Base URL 올바른 형식: /v1 제거하기

2.2 API 키 가져오기

3. 두 가지 설정 방식 상세 안내

방식 1: 환경 변수 설정 (임시 테스트 권장)

방식 2: settings.json 설정 (장기 사용 권장)

4. Claude Code 지원 최신 모델 명칭

표준 추론 모델

강화된 추론 모델 (사고 모드)

5. Claude Code에서 모델 전환하기

5.1 /model 명령어 사용하기 (가장 간단한 방법)

5.2 settings.json에서 기본 모델 지정하기

6. 자주 발생하는 오류 및 해결 방법 FAQ

7. 설정 확인 체크리스트

요약

Similar Posts