Claude Code를 타사 모델(DeepSeek, OpenAI, Gemini)과 연동하기 위한 구성 키트 공유

실용적 조언

Claude Code에서 타사 모델을 쓰려면 모델 이름 매핑뿐만 아니라 에이전트 실행 방식을 설명하는 시스템 프롬프트 주입이 병행되어야 한다.
DeepSeek 사용 시 V4 모델의 추론 모드 충돌을 피하기 위해 레거시 모델 이름을 우선적으로 고려하라.

섹션별 상세

Claude Code의 기술(Skill) 파일에 정의된 모델 프론트매터가 타사 모델에서 해석되지 않는 문제가 발생했다. 작성자는 모델 이름을 각 제공업체에 맞게 매핑하는 로직을 구현하여 라우팅 문제를 해결했다. 하지만 단순 매핑 이후에도 추론 블록의 라운드트립 실패나 OpenAI가 거부하는 배열 스키마 등 추가적인 호환성 장벽이 확인됐다.

타사 모델들이 Claude Code의 서브에이전트 생성 명령을 이해하지 못하는 현상이 관찰됐다. 이를 해결하기 위해 SessionStart 훅을 도입하여 모델에게 현재 사용 가능한 에이전트 목록과 실행 방법을 사전에 브리핑하는 방식을 채택했다. 이 과정을 통해 모델이 도구 부재를 환각(Hallucination)하는 빈도를 줄이고 에이전트 오케스트레이션의 안정성을 확보했다.

DeepSeek V4 모델의 경우 특정 추론 모드가 활성화되면서 Claude Code의 기존 대화 구조와 충돌하는 사례가 보고됐다. 작성자는 ASGI 미들웨어 계층을 추가하여 LiteLLM에 요청이 전달되기 전 데이터를 패치하는 방식으로 대응했다. 현재 DeepSeek, GPT-5 제품군, Gemini 2.5 Pro에서 엔드투엔드 작동이 확인되었으나 모델별 품질 차이는 여전히 존재한다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — Anthropic에서 제안한 개방형 표준으로, AI 모델이 로컬 데이터나 외부 도구와 안전하게 상호작용할 수 있도록 연결하는 프로토콜이다. Claude Code와 같은 에이전트가 파일 시스템이나 데이터베이스에 접근할 때 핵심적인 인터페이스 역할을 수행한다.
라이트LLM(LiteLLM): — 서로 다른 LLM 제공업체의 API를 OpenAI 표준 형식으로 변환해주는 프록시 라이브러리이다. 이를 통해 코드 수정 없이 다양한 모델(DeepSeek, Gemini 등)을 기존 OpenAI 호환 워크플로에 통합할 수 있다.
추론 블록(Thinking Block): — 모델이 최종 답변을 내놓기 전 내부적으로 수행하는 추론 과정을 담은 텍스트 블록이다. DeepSeek-R1과 같은 모델에서 주로 나타나며, 대화 턴 사이에서 이 데이터가 유실되면 에이전트의 연속성이 깨질 수 있다.
프론트매터(Frontmatter): — 파일의 최상단에 위치하는 메타데이터 블록으로, 주로 YAML 형식을 사용한다. Claude Code에서는 특정 기술(Skill)이 어떤 모델을 사용해야 하는지 등의 라우팅 정보를 정의하는 데 활용된다.

언급된 도구

LiteLLM추천

다양한 LLM API를 OpenAI 표준으로 변환하는 프록시

Claude Code중립

Anthropic의 CLI 기반 AI 코딩 에이전트

DeepSeek추천

연동 테스트에 사용된 주요 타사 모델 제공처

언급된 리소스

GitHubclaude-code-provider-kit GitHub