Claude Code에 DeepSeek Flash/Pro 연결하기: 설정·검증·요금
Claude Code를 DeepSeek에 연결하고 Flash와 Pro를 선택하는 실전 안내서입니다. 안전한 Key 입력, 연결 검증, 도구 호환성, 오류 해결, DeepSeek와 BetterToken의 현재 요금을 다룹니다.
목차
Claude Code는 별도 proxy 없이 DeepSeek의 Anthropic 호환 endpoint에 직접 연결할 수 있습니다. 일반적인 coding 작업은 현재 공식 예시인 deepseek-flash[1m]으로 시작하세요. 어려운 architecture 결정, 대규모 refactor, 긴 장애 분석처럼 비용 증가가 정당한 경우에만 main agent를 deepseek-v4-pro로 바꾸고 Haiku와 subagent는 Flash에 두는 편이 좋습니다.
헷갈리기 쉬운 지점이 두 가지입니다. 현재 DeepSeek의 all-Flash 예시는 Opus에도 Flash를 명시해 automatic mapping을 덮어씁니다. 또 지원하지 않는 model name은 명확한 error 없이 deepseek-flash로 fallback합니다. 따라서 Claude Code가 정상 응답했다는 사실은 연결 성공을 뜻할 뿐, Pro 사용을 증명하지 않습니다.
설정 전에 model profile부터 고르기
2026년 9월 27일 기준 DeepSeek Claude Code 가이드는 비용을 우선한 all-Flash 구성을 제시합니다. 별도의 Anthropic API 호환 문서는 claude-opus로 시작하는 이름을 deepseek-v4-pro로, claude-sonnet과 claude-haiku를 deepseek-flash로 매핑한다고 설명합니다.
| Profile | Main model / Opus | Sonnet | Haiku·subagent | 적합한 작업 |
|---|---|---|---|---|
| 공식 default, 속도 우선 | deepseek-flash[1m] | deepseek-flash[1m] | deepseek-flash | 일상 개발, repository 읽기, 많은 소형 작업 |
| Main thread만 Pro | deepseek-v4-pro | deepseek-flash[1m] | deepseek-flash | 설계, 어려운 refactor, 중요한 원인 분석 |
| Claude 이름 자동 mapping | claude-opus* → deepseek-v4-pro | claude-sonnet* → deepseek-flash | claude-haiku* → deepseek-flash | Client가 어떤 Claude 이름을 보내는지 알 때만 |
명시한 환경 변수는 자동 mapping보다 우선합니다. ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-flash[1m]을 설정하면 Claude Code에서 Opus 경로를 선택해도 Flash로 전송됩니다.
1. Claude Code를 설치하고 local CLI부터 확인하기
Node.js 18 이상이 필요합니다. Windows에서는 Git for Windows도 설치합니다. Provider 설정 전에 version을 확인해 local install 문제와 API 연결 문제를 분리하세요.
npm install -g @anthropic-ai/claude-code
claude --version
IFS= read -rs ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-flash"
export CLAUDE_CODE_EFFORT_LEVEL="max"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW="786432"IFS= read -rs ANTHROPIC_AUTH_TOKEN은 terminal에서 API Key 입력을 기다리되 화면에 표시하지 않습니다. Key를 붙여 넣고 Enter를 누르면 다음 줄이 현재 shell에 export합니다. 실제 Key를 command, shell history, script, repository에 직접 쓰지 마세요.
PowerShell에서는 secret으로 읽어 현재 process에만 전달할 수 있습니다.
npm install -g @anthropic-ai/claude-code
claude --version
$secure = Read-Host -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
try {
$env:ANTHROPIC_AUTH_TOKEN = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
} finally {
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
}
$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-flash"
$env:CLAUDE_CODE_EFFORT_LEVEL="max"
$env:CLAUDE_CODE_AUTO_COMPACT_WINDOW="786432"이 변수들은 해당 terminal에서 시작한 Claude Code에 적용됩니다. 먼저 temporary session으로 확인한 뒤, non-secret 값만 보호된 profile에 저장하고 Key는 적절한 secret store에서 관리하세요.
2. 깊은 추론이 필요한 main thread만 Pro로 전환하기
현재 model·가격 페이지의 정확한 Pro ID는 deepseek-v4-pro, version은 DeepSeek-V4-Pro-0813입니다. 현재 Claude Code 페이지는 [1m]을 Flash 예시에만 보여 주고 deepseek-v4-pro[1m] 예시는 제공하지 않습니다. 따라서 suffix를 추측하지 말고 표에 나온 정확한 ID를 사용합니다.
export ANTHROPIC_MODEL="deepseek-v4-pro"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-flash"Main session과 Opus route는 Pro를 사용하고 Sonnet, Haiku, subagent는 Flash를 유지합니다. Repository 검색, file read, 작은 delegated edit는 call 수가 많아질 수 있으므로 깊은 추론이 필요하지 않은 부분까지 Pro로 보내면 비용만 늘어납니다.
[1m]이 뜻하는 것과 한계
DeepSeek의 현재 documentation은 [1m]을 별도 문장으로 정의하지 않습니다. 다만 main Flash와 Opus/Sonnet override에는 suffix를 붙이고, Haiku와 CLAUDE_CODE_SUBAGENT_MODEL에는 plain deepseek-flash를 사용하며, model table에는 1M context를 명시합니다. 이를 함께 보면 integration guide가 보여 준 model에 한해서 million-token context route를 요청하는 Claude Code notation으로 이해하는 것이 안전합니다. 별도 model, 별도 가격, 1M output을 뜻하지 않습니다.
다음 한계를 기억하세요.
- 공개된 maximum output은 384K이며 1M이 아닙니다.
CLAUDE_CODE_AUTO_COMPACT_WINDOW=786432은 context ceiling에 도달하기 전 compaction 여유를 둡니다.- 요금 model ID는
deepseek-flash와deepseek-v4-pro입니다. 현재 integration page가 보여 주지 않은 model에 suffix를 임의로 붙이지 마세요.
3. 긴 작업 전에 최소 검증하기
버려도 되는 project나 위험이 낮은 project에서 시작합니다.
test -n "${ANTHROPIC_AUTH_TOKEN:-}"
test "$ANTHROPIC_BASE_URL" = "https://api.deepseek.com/anthropic"
claude --version
cd /path/to/your/project
claude“package.json 또는 pyproject.toml을 읽고 사용 가능한 scripts를 나열하되 file은 수정하지 마세요”처럼 관찰 가능한 read-only 작업을 요청합니다. 정상 응답과 file-read tool call이 완료되고 401, 402, 429, connection, model error가 없다면 기본 검증은 성공입니다. 동기식 상호작용이므로 job ID나 polling은 없고 결과는 현재 session에 나타납니다.
Claude Code만 실패하면 공식 Anthropic SDK pattern으로 endpoint와 client를 분리해 검사하고 결과를 저장합니다.
python3 -m pip install anthropic
python3 - <<'PY'
import os
from pathlib import Path
import anthropic
client = anthropic.Anthropic(
base_url=os.environ["ANTHROPIC_BASE_URL"],
api_key=os.environ["ANTHROPIC_AUTH_TOKEN"],
)
message = client.messages.create(
model="deepseek-flash",
max_tokens=200,
messages=[{"role": "user", "content": "Reply with: endpoint OK"}],
)
text = "\n".join(block.text for block in message.content if block.type == "text")
Path("deepseek-smoke.txt").write_text(text, encoding="utf-8")
print("saved deepseek-smoke.txt")
PYdeepseek-smoke.txt가 생성되지만 Claude Code가 실패하면 환경 변수 충돌, 다른 settings file, 오래된 process를 확인하세요. SDK도 실패하면 Base URL, Key, 잔액, provider status부터 봅니다.
DeepSeek는 지원하지 않는 이름이 deepseek-flash로 fallback한다고 명시합니다. SDK check는 transport를 증명하고 read-only Claude Code task는 basic tool call도 확인하지만, 둘 다 model identity를 증명하지는 않습니다. Pro 품질이나 비용을 비교하기 전에 provider가 제공하는 request, usage, billing detail을 확인하세요. Model이 표시되지 않으면 정상 응답만으로 Pro 사용을 입증했다고 보지 마세요.
Tools, thinking, Web Search는 문서화된 범위에서만 호환된다
Anthropic Messages의 핵심 구조는 지원하지만 DeepSeek 동작이 Claude와 완전히 같아지는 것은 아닙니다. 호환성 표에서 Claude Code 사용자가 볼 항목은 다음과 같습니다.
| 기능 | 현재 상태 | 실무 영향 |
|---|---|---|
tools, tool_use, tool_result | 핵심 field 지원 | Local file·command tool에 필요한 protocol 기반이 있음 |
tool_choice | 지원하지만 disable_parallel_tool_use 무시 | 이 flag만으로 strict serial 실행을 보장할 수 없음 |
| Claude Code Web Search | Native support | 검색 결과 요약에 추가 LLM call과 token 비용 발생 |
Anthropic cache_control | 무시 | Directive만 보고 실제 cache hit를 판단할 수 없음 |
| Thinking | 지원; budget_tokens 무시, effort 사용 가능 | 예시는 CLAUDE_CODE_EFFORT_LEVEL=max; Claude budget field가 여기서 지출을 제어하지 않음 |
document·search_result input block | 미지원 | 의존하는 작업은 작은 sample로 먼저 검사 |
code_execution_tool_result·mcp_tool_use | 미지원 | Server-side code execution과 Anthropic 전용 MCP block은 동등하지 않음 |
tool_result.is_error | 무시 | Custom middleware는 실패 의미를 이 field 하나에만 의존하면 안 됨 |
DeepSeek 가이드는 API가 Claude Code Web Search를 제공한다고 설명합니다. Model이 검색을 결정하면 가져온 내용을 요약하는 추가 request가 생깁니다. 비용 계산에 검색, long context, tool loop, retry를 포함하세요.
증상별로 오류를 좁히기
| 증상 | 먼저 확인할 것 | 수정과 재검증 |
|---|---|---|
| 401 / authentication failure | 잘못된 Key, 공백, 현재 shell에 변수 없음 | Hidden input으로 다시 입력하고 Claude Code 재시작 후 동일한 read-only task 실행 |
| 402 / insufficient balance | DeepSeek 잔액 | 충전 후 같은 짧은 request 재실행 |
| 400 / 422 | Invalid field, model ID, body를 바꾸는 middleware | 공식 변수를 복원하고 custom Thinking+tools client는 모든 reasoning_content를 돌려보냄 |
| 429 | Request rate와 parallel session | Concurrency를 낮추고 backoff 후 retry |
| 500 / 503 | Provider 오류 또는 overload | 잠시 후 재시도하고 지속되면 발생 시각 기록 |
| 응답은 오지만 Pro 같지 않음 | Typo 또는 fallback | 정확한 deepseek-v4-pro를 쓰고 dashboard에서 model/billing 확인 |
| 설정 변경이 반영되지 않음 | 오래된 process 또는 다른 settings layer | 모든 process 종료, 새 terminal에서 변수 재설정 후 실행 |
| Web Search가 시작되지 않음 | Model이 검색이 필요 없다고 판단했을 수 있음 | 최신 Web 정보를 명시적으로 요청. 검색이 없다고 연결 실패는 아님 |
DeepSeek 오류 코드 문서는 401, 402, 429, 500, 503을 구분합니다. 한 번에 하나만 바꾸고 항상 같은 짧은 task로 재검증하세요.
2026년 9월 27일 확인한 DeepSeek·BetterToken 요금
아래 금액은 모두 USD / 100만 tokens입니다. DeepSeek는 peak/off-peak를 적용하고 BetterToken public catalog에는 같은 시간 구간이 없습니다. 대규모 실행 전에 DeepSeek 공식 가격과 유일한 BetterToken 가격 페이지를 다시 확인하세요.
DeepSeek 공식 가격
| Model ID / current version | 구간 | Cache miss input | Cache hit input | Output |
|---|---|---|---|---|
deepseek-flash / DeepSeek-V4.1-Flash | Off-peak | $0.15 | $0.003 | $0.60 |
deepseek-flash / DeepSeek-V4.1-Flash | Peak | $0.30 | $0.006 | $1.20 |
deepseek-v4-pro / DeepSeek-V4-Pro-0813 | Off-peak | $0.66 | $0.022 | $1.98 |
deepseek-v4-pro / DeepSeek-V4-Pro-0813 | Peak | $1.32 | $0.044 | $3.96 |
Peak는 월~금 01:00–04:00, 06:00–10:00 UTC이며 중국 법정 공휴일은 제외합니다. 그 밖은 off-peak입니다. 9월 10일 change log는 deepseek-flash가 V4.1 Flash를 호출하며 구형 deepseek-v4-flash 이름은 임시로 새 version에 route된다고 밝힙니다.
BetterToken public catalog
| BetterToken ID / 현재 대응 | Endpoint type | Input | Cache hit | Output |
|---|---|---|---|---|
deepseek-flash / 최신 Flash, 현재 V4.1 Flash | Anthropic, OpenAI | $0.132 | $0.00264 | $0.528 |
deepseek-pro / 최신 Pro, 현재 V4-Pro-0813 | OpenAI | $0.5808 | $0.01936 | $1.7424 |
deepseek-v4-pro-0813 / V4-Pro-0813 | Anthropic, OpenAI | $0.5896 | $0.0176 | $1.7644 |
deepseek-pro가 약간 저렴하지만 catalog에는 OpenAI만 표시됩니다. 이름이나 가격이 비슷하다고 Claude Code Anthropic Messages에 쓸 수 있는 것은 아닙니다. BetterToken Pro route는 Anthropic이 명시된 deepseek-v4-pro-0813을 확인해야 합니다.
Cache miss input 100만 tokens와 output 20만 tokens, 검색과 retry가 없는 예입니다.
- Flash: DeepSeek off-peak 약 $0.27, peak 약 $0.54, BetterToken catalog 약 $0.2376.
- Pro: DeepSeek off-peak 약 $1.056, peak 약 $2.112, BetterToken Anthropic 지원 Pro ID 약 $0.9425.
이는 2026년 9월 27일 snapshot이며 BetterToken이 언제나 더 저렴하다는 약속이 아닙니다. Context, tools, 검색, retry, 가격 변경이 최종 비용을 바꿉니다.
BetterToken route를 mapping 추측 없이 평가하기
BetterToken public catalog에서 deepseek-flash와 deepseek-v4-pro-0813은 Anthropic 지원으로 표시되지만 deepseek-pro는 OpenAI-only입니다. 이 정보는 가격 비교와 candidate ID 선정에는 충분하지만 Claude Code mapping이 확인됐다는 뜻은 아닙니다.
현재 BetterToken Claude Code guide는 /v1 없는 https://bettertoken.ai, authentication, 재시작, Claude/Kimi/GLM mapping을 설명합니다. DeepSeek 전용 profile은 제공하지 않습니다. 또한 Claude provider에서는 ANTHROPIC_MODEL과 ANTHROPIC_DEFAULT_*_MODEL을 수동 설정하지 말라고 안내합니다. Pricing catalog만 보고 DeepSeek mapping을 추측해 persistent 설정으로 만들지 마세요.
BetterToken의 current Setup 또는 새 documentation에 DeepSeek profile이 표시되면 그 exact model ID를 사용하고 앞의 read-only task와 SDK smoke test를 반복하세요. Pro는 Anthropic 지원이 명시된 deepseek-v4-pro-0813만 후보로 삼고, OpenAI-only deepseek-pro로 대체하지 마세요. 전용 mapping이 문서화되거나 account에서 확인되기 전에는 위의 direct DeepSeek endpoint가 알려진 설정입니다.
평가할 때는 현재 가격을 먼저 확인한 뒤 account와 API Key를 생성하세요.
작업에 맞는 route 선택하기
- 대부분의 coding: DeepSeek direct endpoint +
deepseek-flash[1m]. 현재 공식 default이며 반복 작업 비용을 낮추기 좋습니다. - 어렵고 가치가 큰 작업: Main thread와 Opus만
deepseek-v4-pro, Sonnet·Haiku·subagent는 Flash. 사용량 확대 전 fallback 여부를 확인하세요. - 하나의 잔액 또는 multi-provider routing: current Setup에 DeepSeek profile이 표시될 때만 BetterToken을 평가하세요.
supported_endpoint_types는 candidate filter로만 쓰고 actual mapping, exact ID, 당일 가격을 확인하세요. - Anthropic 전용 block 또는 Claude와의 behavior parity: Claude model을 사용하세요. Transport compatibility는 동일한 동작이나 완전한 tool parity를 보장하지 않습니다.
중요한 repository에 적용하기 전, CLI version 확인, Key 비노출, 정확한 Base URL, read-only task 성공, 그리고 이용 가능한 record로 model identity가 확인됐거나 확인 불가로 명시된 상태까지 검증하세요.
