Claude Code에서 DeepSeek V4 Flash 및 Pro 사용: 설정과 모델 전환
APIMaster를 사용하여 Claude Code에서 DeepSeek를 설정합니다. Windows, macOS, Linux에서 settings.json을 구성하고, claude를 실행하고, /model로 모델을 선택한 뒤 대화를 시작하세요.
settings.json에서 APIMaster를 구성하고, claude를 실행한 다음, 대화 중에 /model MODEL_ID를 입력하면 DeepSeek를 사용할 수 있습니다. 여기서 다루는 사용 가능한 ID는 deepseek-v4-flash, deepseek-v4-pro입니다. Claude Code는 클라이언트이며, DeepSeek는 응답하는 모델입니다.
시작하기 전에
환경 점검과 Claude Code 설정을 완료하세요. 충분한 잔액이 있고 선택한 모델에 접근 가능한 APIMaster API 키를 발급받으세요.
claude --version
게이트웨이 베이스 URL은 https://apimaster.ai 이며, /v1 을 붙이지 않습니다. Claude Code가 /v1/messages를 직접 추가합니다.
1. 설정 디렉터리 열기
Windows
Win + R 을 누르고 다음 경로를 입력한 뒤 Enter를 누릅니다:
%USERPROFILE%\.claude
필요하다면 폴더를 새로 만드세요. settings.json 을 열거나 생성합니다. 파일 이름이 settings.json.txt가 되지 않도록 주의하세요.
macOS / Linux
macOS에서는 Finder에서 Command + Shift + G 를 누르고 다음을 입력합니다:
~/.claude
Linux에서는 파일 관리자나 편집기로 같은 디렉터리를 엽니다. 필요하다면 생성하세요:
mkdir -p ~/.claude
그 안에서 settings.json 을 열거나 생성합니다. Claude Code 설정 디렉터리를 커스텀으로 지정했다면 해당 디렉터리를 사용하세요.
2. settings.json 편집
Windows, macOS, Linux 모두 동일한 설정을 사용합니다. YOUR_APIMASTER_API_KEY를 본인의 APIMaster 키로 바꾸세요:
{
"model": "deepseek-v4-flash",
"env": {
"ANTHROPIC_BASE_URL": "https://apimaster.ai",
"ANTHROPIC_API_KEY": "YOUR_APIMASTER_API_KEY",
"ANTHROPIC_AUTH_TOKEN": "",
"CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
}
}
파일이 이미 존재한다면 백업한 뒤 이 필드들을 기존 JSON 객체와 env 객체에 병합하세요. 필요한 다른 설정은 그대로 유지합니다. 두 번째 JSON 객체를 덧붙이거나 env 키를 중복해서는 안 됩니다. JSON에는 주석이나 trailing comma를 사용할 수 없습니다.
일반 Claude Code 가이드는 토큰 인증 방식을 보여줍니다. 이 가이드는 저희 통합 테스트에서 검증한 API 키 인증 방식을 사용합니다. ANTHROPIC_API_KEY를 사용할 때는 ANTHROPIC_AUTH_TOKEN을 비워 두고, 다른 설정 파일이나 터미널에 있는 충돌하는 자격 증명은 제거하세요. 이 게이트웨이에는 APIMaster 키를 사용합니다.
model 필드는 시작 모델을 지정합니다. 실행 후 다른 모델을 선택할 수 있습니다. 이 사용자 설정 파일은 비공개로 유지하고, 실제 키를 공유 저장소에 커밋하지 마세요. 파일을 저장하고 Claude Code를 다시 시작하여 새 설정을 불러오세요.
3. Claude Code 시작
프로젝트 디렉터리에서 연 터미널에서 다음을 실행합니다:
claude
일반적인 첫 실행 프롬프트를 완료하고 프로젝트 신뢰 프롬프트를 확인하세요. 시작 모델은 deepseek-v4-flash 여야 합니다. 평소처럼 도구와 프로젝트 설정이 적용되는 일반적인 대화형 세션입니다.
4. 모델 선택 후 대화 시작
Claude Code 대화 내에서 다음 명령 중 하나를 입력하고 Enter를 누릅니다:
/model deepseek-v4-flash
/model deepseek-v4-pro
한 번에 한 줄씩 실행하며 원하는 모델을 선택하세요. Claude Code가 전환을 확인한 후 짧은 메시지를 보냅니다:
Reply with exactly OK.
정상적인 텍스트 응답이 오면 기본 연결이 확인된 것입니다. 이후 계속 대화하거나 프로젝트 작업을 요청할 수 있습니다. 같은 대화에서 다시 전환하려면 다른 /model MODEL_ID 명령을 입력하세요.
/model만 입력하면 모델 선택 UI가 열립니다. 커스텀 게이트웨이 ID는 기본 목록에 표시되지 않을 수 있습니다. 이 경우 위와 같이 전체 ID를 직접 입력하세요. 슬래시 명령은 PowerShell이나 Bash가 아니라 Claude Code 내부에서 사용하는 것입니다. 모델 이름은 DeepSeek 모델을 나타내며, Claude Sonnet이나 Opus가 아닙니다.
터미널 에서 실행할 때 모델을 선택할 수도 있습니다. 한 번에 한 명령씩 실행하세요:
claude --model deepseek-v4-flash
claude --model deepseek-v4-pro
이후 세션의 기본값을 명시적으로 지정하려면 settings.json의 model을 편집하세요. 실행 플래그, ANTHROPIC_MODEL 환경 변수, 프로젝트/관리 설정이 선택된 모델에 영향을 줄 수 있으므로, 시작 모델이 저장한 값과 다르다면 이들을 확인하세요.
문제 해결
| 증상 | 확인 사항 |
|---|---|
| 401 / 예상치 못한 로그인 프롬프트 | APIMaster 키, 베이스 URL, 충돌하는 인증 변수를 확인하고, 설정 편집 후 CLI를 재시작하세요. |
| 404 | /v1이나 /v1/messages 없이 https://apimaster.ai를 사용하세요. |
| 설정이 적용되지 않음 | 파일 위치, 유효한 JSON 여부, 터미널·프로젝트·관리 설정에 의한 재정의를 확인하세요. |
| 선택 UI에 모델이 없음 | 정확한 ID로 /model MODEL_ID를 입력하거나, claude --model MODEL_ID로 실행하세요. |
| 모델 사용 불가 / 403 | 철자, 키의 허용 모델, 계정 잔액, 현재 경로 가용성을 확인하세요. |
unrecognized_model |
저희 테스트에서 커스텀 ID로 관찰된 현상입니다. 실제 응답과 도구 결과를 확인하세요. 내장 Claude 기능의 기본 동작은 DeepSeek에 대해 검증되지 않았습니다. |
| 파일 또는 명령 권한 거부 | 일반적인 권한 프롬프트를 통해 의도한 작업을 검토하고 승인하세요. |
| 429 / 5xx / 응답 중단 | 지원 요청 시 오류 내용, 모델 ID, CLI 버전, UTC 시간, 요청 ID(있다면)를 보관하세요. |
검증 및 선택적 진단
기록된 통합 테스트: 2026-09-07 UTC, Claude Code 2.1.239, Linux. 여기 나열된 모든 모델이 예상된 텍스트를 반환했고, 도구를 통해 로컬 파일을 읽었습니다. 복잡한 코딩 작업은 해당 테스트 범위 밖이었습니다. Windows와 macOS는 기록된 실행에 포함되지 않았습니다.
이전 자동화 점검에서는 설정을 격리하기 위해 bare 모드를 사용했습니다. 일상적인 사용은 위의 settings.json과 대화형 단계를 따릅니다. Bare 모드와 --setting-sources ""는 일반적인 통합이나 저장된 설정을 건너뛰므로, 이 가이드의 일상 실행 명령에 추가해서는 안 됩니다.
저장된 설정으로 빠르게 비대화형 점검을 하려면:
claude --model deepseek-v4-flash -p "Reply with exactly OK."
도구 점검을 하려면 FILE_PROBE_739182가 포함된 probe.txt 파일을 만들고, 해당 디렉터리에서 Claude Code를 시작한 뒤, 도구를 사용해 파일을 읽고 정확한 내용을 반환하도록 요청하세요. 도구가 실제로 실행되는지 확인합니다.
이것은 범위가 한정된 통합 점검이며, 모든 Claude Code 기능, 장시간 세션 동작, 최대 컨텍스트를 보장하지 않습니다. Anthropic의 게이트웨이 문서는 Claude Code를 비(非) Claude 모델로 라우팅하는 것을 공식적으로 지원하지 않습니다. 이 가이드는 APIMaster의 통합을 설명합니다.
FAQ
Claude 구독이 이 요청 비용을 지불하나요?
아니요. 이 APIMaster 구성에서는 요청이 APIMaster 키와 잔액을 사용합니다.
모델을 전환한 후에도 대화를 이어갈 수 있나요?
네, 열려 있는 대화에서 모델 전환 명령을 사용하고, 다음 메시지를 보내기 전에 확인 메시지를 기다리세요. 모델 간 깔끔한 비교를 원한다면 claude --model MODEL_ID로 별도 세션을 시작하세요.