Claude Code는 모든 요청을 설정한 Anthropic 호환 API 엔드포인트를 통해 라우팅합니다. 하나의 환경 변수만 변경하면 Qwen, DeepSeek, GLM, MiniMax를 Claude Code의 전체 에이전틱 워크플로우(MCP 도구 호출, 파일 편집, bash 실행 포함)에서 실행할 수 있으며, 나머지 설정은 그대로 유지됩니다.
이 가이드에서는 라우팅 작동 방식, Novita AI 엔드포인트를 백엔드로 구성하는 방법, 라우팅된 설정에서 MCP 도구 호출이 흐르는 방식, Novita Agent Sandbox에서 안전하게 도구를 실행하는 방법을 다룹니다.
Claude Code 라우터란?
Claude Code 용어에서 '라우터’는 Claude Code가 요청을 보내는 Anthropic API 호환 엔드포인트입니다. 기본적으로 이 엔드포인트는 api.anthropic.com에 있는 Anthropic 자체 API입니다. ANTHROPIC_BASE_URL을 설정하면 동일한 API 형식을 수락하고 동일한 구조의 응답을 반환하는 다른 공급자로 요청을 리디렉션합니다.
이 점을 명확히 이해하는 것이 중요합니다. Claude Code는 구성된 엔드포인트 뒤에 어떤 공급자가 있는지 알지 못하며 신경 쓰지 않습니다. Anthropic 형식의 메시지 요청을 보내고 Anthropic 형식의 응답을 읽은 후 계속 진행합니다. 라우터(Novita AI, 자체 호스팅 프록시 또는 타사 집계 서비스)는 모델 선택, 추론 및 응답 형식을 투명하게 처리합니다.
라우터를 사용해야 하는 실질적인 세 가지 이유:
- 모델 접근: Qwen3-Coder, MiniMax M2.7, GLM-4.7과 같은 오픈 웨이트 모델은 Anthropic 엔드포인트에서 사용할 수 없습니다. Novita AI를 통해 라우팅하면 동일한 Claude Code 워크플로우 내에서 이 모든 모델에 액세스할 수 있습니다.
- 비용 관리: Novita와 같은 공급자를 통한 오픈 웨이트 모델은 일반적으로 Anthropic의 폐쇄형 모델보다 백만 토큰당 비용이 훨씬 저렴합니다. 모델이 수백 번의 도구 호출을 수행하는 대규모 에이전틱 세션에서 이 차이는 큰 비용 차이를 만듭니다.
- 전문화된 기능: 일부 오픈 웨이트 모델은 함수 호출 및 다단계 도구 사용에 특별히 훈련되어 있으며, 이는 Claude Code의 MCP 통합에 정확히 필요한 기능입니다. 일반 목적 모델 대신 도구 호출 정확도에 맞춰진 모델을 선택하면 복잡한 워크플로우에서 실패하거나 잘못된 형식의 도구 호출을 줄일 수 있습니다.
Claude Code 라우팅 작동 방식
세 가지 환경 변수가 라우팅을 제어합니다:
| 변수 | 용도 |
|---|---|
ANTHROPIC_BASE_URL |
API 엔드포인트입니다. 이를 변경하여 다른 공급자를 통해 라우팅합니다. |
ANTHROPIC_AUTH_TOKEN |
대상 엔드포인트에서 인증을 위한 API 키입니다. |
ANTHROPIC_MODEL |
사용할 모델 ID입니다. 대상 공급자의 명명 규칙과 일치해야 합니다. |
ANTHROPIC_BASE_URL이 설정되면 Claude Code는 모든 추론 요청을 https://api.anthropic.com 대신 해당 URL로 보냅니다. 대상 엔드포인트는 Anthropic의 메시지 API 형식(Claude 네이티브 모델이 사용하는 것과 동일한 요청 및 응답 구조)을 구현해야 합니다.
한 가지 중요한 세부 사항: Anthropic의 모델 별칭(sonnet, opus, haiku)은 Anthropic 자체 엔드포인트에서만 올바르게 확인됩니다. 타사 라우터를 사용할 때는 별칭 대신 공급자의 특정 모델 ID로 ANTHROPIC_MODEL을 설정하세요. sonnet과 같은 별칭을 Anthropic이 아닌 엔드포인트에 전달하면 실패하거나 예기치 않은 모델이 반환됩니다.
ANTHROPIC_SMALL_FAST_MODEL은 Claude Code의 내부 백그라운드 작업(요약, 컨텍스트 압축, 단계 간 경량 추론)을 위한 두 번째 모델 슬롯입니다. 이를 더 빠르고 저렴한 모델로 지정하면 기본 모델 응답 품질에 영향을 주지 않으면서 세션 비용을 낮출 수 있습니다.
Novita AI를 라우터로 설정하기
Novita AI의 Anthropic 호환 엔드포인트는 https://api.novita.ai/anthropic에 있습니다. Claude Code가 기본적으로 보내는 것과 동일한 요청 형식을 수락하며 코딩 특화 모델 및 도구 호출 최적화 변형을 포함한 다양한 오픈 웨이트 모델을 지원합니다.
1단계: Novita API 키 받기
- novita.ai에 가입하세요. 가입 시 무료 평가판 크레딧이 제공됩니다.
- 대시보드에서 키 관리를 엽니다.
- 새 키 만들기 를 클릭하고 키를 즉시 복사한 후(한 번만 표시됨) 안전하게 저장하세요.
2단계: 환경 구성
macOS / Linux:
export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-novita-api-key>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"
export ANTHROPIC_SMALL_FAST_MODEL="deepseek/deepseek-v4-flash"
Windows (PowerShell):
$env:ANTHROPIC_BASE_URL = "https://api.novita.ai/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "<your-novita-api-key>"
$env:ANTHROPIC_MODEL = "qwen/qwen3-coder-480b-a35b-instruct"
$env:ANTHROPIC_SMALL_FAST_MODEL = "deepseek/deepseek-v4-flash"
Windows (Command Prompt):
set ANTHROPIC_BASE_URL=https://api.novita.ai/anthropic
set ANTHROPIC_AUTH_TOKEN=<your-novita-api-key>
set ANTHROPIC_MODEL=qwen/qwen3-coder-480b-a35b-instruct
set ANTHROPIC_SMALL_FAST_MODEL=deepseek/deepseek-v4-flash
3단계: Claude Code 실행
claude .
Claude Code는 현재 디렉터리에서 시작되며 모든 추론을 Novita AI를 통해 라우팅합니다. MCP 도구, 파일 편집 및 bash 실행은 네이티브 Anthropic 설정과 동일하게 작동합니다.
Novita AI에서 사용 가능한 모델
| 모델 | Novita 모델 ID | 주요 강점 |
|---|---|---|
| Qwen3-Coder 480B | qwen/qwen3-coder-480b-a35b-instruct |
코드 생성, 긴 컨텍스트 추론 |
| MiniMax M2.7 | minimax/minimax-m2.7 |
에이전틱 도구 호출 정확도 |
| DeepSeek V4 Flash | deepseek/deepseek-v4-flash |
빠른 반복, 비용 효율성 |
| GLM-4.7 | zai-org/glm-4.7 |
코딩 및 다단계 에이전틱 작업 |
| Kimi K2 Instruct | moonshotai/kimi-k2-instruct |
도구 사용, 수학 중심 코드베이스 |
이러한 오픈 웨이트 모델은 최신 GPU 인프라에서 실행되지만 토큰당 비용은 일반적으로 훨씬 낮습니다. 장기 리팩터링 세션이나 자동화된 테스트 생성과 같이 Claude Code가 수십 번의 도구 호출을 수행하는 작업에서는 토큰당 비용 차이가 실질적으로 중요합니다.
구성을 최종 결정하기 전에 novita.ai/llm-api에서 최신 모델 목록과 확인된 ID를 확인하세요. 모델 가용성과 ID는 공급자가 제품을 추가하거나 업데이트함에 따라 변경될 수 있습니다.
MCP를 통한 도구 호출 라우팅
Claude Code의 도구 호출 계층은 MCP(모델 컨텍스트 프로토콜)입니다. claude mcp add로 MCP 서버를 추가하면 Claude Code는 세션 시작 시 해당 서버에 연결하여 노출된 도구를 로드합니다. 세션 중에 라우팅된 LLM은 언제 해당 도구를 호출할지, 어떤 인수를 전달할지, 결과에 따라 어떻게 행동할지 결정합니다.
라우팅 분할은 중요합니다. **LLM 백엔드 **(Novita AI 라우터)는 어떤 도구를 호출할지, 어떤 순서로, 어떤 인수를 사용할지 등 모든 추론을 처리합니다. MCP 서버 는 실행을 처리합니다. 도구 호출을 수신하고 기본 작업을 실행한 후 결과를 반환합니다. Claude Code는 이들 사이를 조정합니다.
실제로 이는 라우터의 도구 호출 지원 품질이 복잡한 다단계 작업이 얼마나 안정적으로 완료되는지를 결정한다는 것을 의미합니다. 잘못된 형식의 함수 호출 인수를 생성하거나 도구 오류 후 계속 진행하지 못하는 모델은 작업 중간에 멈춥니다. Qwen3-Coder 및 MiniMax M2.7과 같이 함수 호출 워크플로우에 특별히 미세 조정된 모델은 이러한 시퀀스를 더 일관되게 처리합니다.
라우팅된 설정에 MCP 서버 추가하기
# Local server (project scope) — Claude Code launches the process
claude mcp add my-server -- python my_server.py
# Remote HTTP server — connects to an already-running server
claude mcp add remote-server --transport http https://your-server.example.com/mcp
원격 HTTP 옵션은 독립적으로 실행되는 서버에 연결합니다. 이것이 Novita Agent Sandbox가 구축된 아키텍처입니다. MCP 서버는 계속 실행되며 도구 호출이 들어올 때 필요에 따라 샌드박스 인스턴스를 생성합니다.
Agent Sandbox에서 도구 실행하기
MCP 도구가 코드 실행, 파일 처리 또는 외부 시스템 호출과 관련된 경우 개발 머신이 아닌 격리된 환경에서 실행되기를 원할 것입니다. Novita의 Agent Sandbox는 관리형 클라우드 서비스로 이를 제공합니다.
Sandbox 인스턴스는 Claude Code가 코드 실행 도구를 트리거할 때 MCP 서버가 생성하는 단기 격리 컨테이너입니다. 각 컨테이너는 다음을 제공합니다:
- 격리된 파일 시스템: 호스트와 분리되어 세션 간 데이터 유출이 없습니다.
- 사전 설치된 환경: 일반적인 데이터 과학 및 스크립팅 패키지가 포함된 Python
- 빠른 시작: 200ms 미만의 콜드 스타트로 저지연 도구 호출 시퀀스에 적합
- 초당 과금: 활성 실행 시간에 대해서만 비용 지불
- 셸 및 Python 실행: 다국어 워크플로우를 위한 전체 명령줄 액세스
Sandbox를 사용한 라우팅된 Claude Code 설정의 데이터 흐름은 다음과 같습니다:
Claude Code
→ Novita LLM API(라우터)에 추론 요청 전송
→ 모델로부터 도구 호출 결정 수신
→ MCP 서버로 도구 호출 전달
→ MCP 서버가 Novita Sandbox 인스턴스 생성
→ Sandbox가 코드 실행 후 출력 반환
→ MCP 서버가 결과를 Claude Code에 반환
→ Novita LLM API가 결과에 대해 추론 후 다음 단계 결정
이러한 분리를 통해 신뢰할 수 없는 코드 실행을 격리하면서도 LLM 라우터가 다단계 추론을 위한 결과에 대한 전체 가시성을 확보할 수 있습니다.
MCP 도구 핸들러 내에서 Novita Sandbox를 사용하려면 SDK를 설치하세요:
pip install novita-sandbox
그런 다음 도구 구현 내에서 샌드박스 인스턴스를 생성하고 사용합니다:
from novita_sandbox.code_interpreter import Sandbox
def run_code_tool(code: str, api_key: str) -> dict:
sandbox = Sandbox.create(
template="code-interpreter-v1",
api_key=api_key,
domain="sandbox.novita.ai",
timeout=300,
)
result = sandbox.run_code(code, language="python")
sandbox.kill()
return {
"output": result.logs,
"error": result.error,
}
code-interpreter-v1 템플릿에는 pandas, numpy, matplotlib 및 기타 일반적으로 사용되는 패키지가 사전 설치되어 있어 대부분의 데이터 분석 및 스크립팅 작업이 추가 설정 단계 없이 실행됩니다.
도구 중심 워크플로우를 위한 모델 선택
모델 선택은 라우팅된 Claude Code 설정에서 두 가지에 영향을 미칩니다: 수행할 작업 결정을 위한 추론 품질과 올바른 실행을 위한 도구 호출 신뢰성입니다. 이 두 가지가 항상 상관관계가 있는 것은 아닙니다. 개방형 작업에서 추론을 잘하는 모델이 도구에 복잡한 인수 유형이 있을 때 일관되지 않은 함수 호출 스키마를 생성할 수 있습니다.
Qwen3-Coder 480B 는 Claude Code가 많은 파일을 읽고, 접근 방식을 계획하고, 다단계 편집 시퀀스를 실행해야 하는 장기 코딩 작업에서 우수한 성능을 보입니다. 긴 컨텍스트 처리 기능 덕분에 복잡한 작업 도중 이전 도구 결과를 놓칠 가능성이 적습니다.
MiniMax M2.7 은 에이전틱 정확도에 맞춰 조정되었습니다. 특히 잘못된 도구 호출을 최소화하고 각 단계가 이전 결과를 기반으로 하는 다중 턴 도구 시퀀스를 처리하도록 설계되었습니다. 여러 상호 의존적인 도구가 있는 MCP 설정에서 이러한 정확도는 필요한 복구 루프 수를 줄여줍니다.
DeepSeek V4 Flash 는 ANTHROPIC_SMALL_FAST_MODEL의 실용적인 선택입니다. 빠르고 저렴하며 Claude Code가 소형 모델에 오프로드하는 작업(세션 요약, 컨텍스트 압축)은 기본 코딩 작업과 동일한 추론 깊이가 필요하지 않습니다.
한 가지 실용적인 관찰: 많은 선택적 매개변수나 중첩 스키마가 있는 도구로 사용자 지정 MCP 서버를 구축하는 경우 장기 실행 세션에 배포하기 전에 대표적인 예제로 모델의 호출 정확도를 테스트하세요. 도구 호출 오류는 조기에 발견하면 덜 방해가 됩니다.
FAQ
Claude Code에서 Novita AI뿐만 아니라 다른 LLM 라우터를 사용할 수 있나요?
네. 기본 URL에서 Anthropic 메시지 API를 구현하는 모든 서비스가 작동합니다. 여기에는 Anthropic 형식으로 구성된 LiteLLM, 자체 호스팅 프록시 또는 기타 상용 라우터 서비스가 포함됩니다. ANTHROPIC_BASE_URL을 해당 엔드포인트로, ANTHROPIC_AUTH_TOKEN을 적절한 키로, ANTHROPIC_MODEL을 해당 엔드포인트가 인식하는 모델 ID로 설정하세요.
Anthropic이 아닌 공급자를 통해 라우팅할 때 MCP 도구가 작동하나요?
네. MCP는 API 수준이 아닌 Claude Code 계층에서 작동합니다. 라우터는 도구 사용에 대한 추론을 수행하는 모델에만 영향을 미칩니다. 모델이 Anthropic 메시지 형식의 함수 호출을 지원하는 한 MCP 도구는 공급자에 관계없이 동일하게 작동합니다.
Novita AI를 통해 라우팅할 때 sonnet 별칭이 작동하지 않는 이유는 무엇인가요?
Anthropic의 모델 별칭(sonnet, opus, haiku)은 Claude Code가 아닌 Anthropic의 엔드포인트에서 확인됩니다. 타사 공급자를 통해 라우팅할 때는 Anthropic의 별칭 확인이 개입되지 않습니다. 대신 공급자의 특정 모델 ID로 ANTHROPIC_MODEL을 설정하세요.
Anthropic 네이티브 모델로 다시 전환하려면 어떻게 해야 하나요?
현재 세션의 라우팅 변수를 해제합니다:
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_MODEL
unset ANTHROPIC_SMALL_FAST_MODEL
Claude Code는 다음 시작 시 설정 파일에 있는 내용이나 Anthropic API 기본값으로 대체됩니다.
타사 라우터를 사용하면 지연 시간 오버헤드가 발생하나요?
약간의 추가 네트워크 홉이 있습니다. 대화형 세션의 경우 일반적으로 눈에 띄지 않습니다. 지연 시간에 민감한 자동화 파이프라인의 경우 커밋하기 전에 공급자가 게시한 지연 시간 수치를 확인하세요. Novita AI는 LLM Metrics 콘솔을 통해 추론 지연 시간 및 처리량 메트릭을 게시합니다.
Agent Sandbox는 LLM 라우터와 별도의 API 키가 필요한가요?
아니요. Novita AI의 API 키는 LLM API와 Agent Sandbox 모두에서 작동합니다. ANTHROPIC_AUTH_TOKEN에 사용하는 동일한 키를 MCP 도구 구현에서 Sandbox.create()에 전달합니다.
추천 문서
- Claude MCP Add 명령어: Claude Code에서 MCP 서버 설치 방법
- Claude Code 기본 모델: 변경, 전환 및 올바른 모델 선택 방법
- Novita Sandbox와 mcp-use 라이브러리로 원격 코드 실행 MCP 서버 구축
출처 확인: 2026년 7월 16일: Claude Code 환경 변수 문서, Novita AI LLM API, Novita Agent Sandbox.
