Rihpig

Posted on Aug 20 Originally published at apidog.com

DeepSeek Harness (dsh)란? 오픈소스 Claude 코드 대항마 총정리

DeepSeek은 2026년 8월 13일 모델이 아니라 모델을 실행하는 기계를 출시했습니다. DeepSeek Harness(dsh)는 DeepSeek의 공식 오픈소스 에이전트 하네스로, 대규모 언어 모델(LLM)을 세션 루프, 도구 실행, 권한 확인, 로컬 웹 UI를 갖춘 코딩 에이전트로 연결합니다. DeepSeek V4-Pro가 API에 출시된 날 함께 공개됐으며, VentureBeat는 이를 Claude Code의 오픈소스 경쟁자로 보도했습니다.

지금 Apidog를 사용해 보세요

개발자 커뮤니티는 빠르게 반응했습니다. 8월 20일 기준, 출시 1주일 만에 deepseek-harness 저장소는 약 169,000개의 스타와 18,100개의 포크를 기록했습니다. 이 수치는 코드 자체보다, 개발자가 직접 검사하고 수정하며 여러 모델에 연결할 수 있는 에이전트 하네스를 원한다는 점을 보여줍니다.

DeepSeek Harness는 무엇인가요?

모델은 다음 토큰을 예측합니다. 반면 하네스는 모델이 실제로 작업할 수 있게 만드는 실행 환경입니다.

하네스는 다음을 제어합니다.

모델에 전달할 컨텍스트
호출 가능한 도구(파일 편집, 셸, 검색 등)
파일 쓰기와 명령 실행에 대한 승인 방식
다단계 세션의 상태 유지 및 기록
모델 응답을 도구 실행 결과와 다시 연결하는 에이전트 루프

Claude Code, Codex CLI, Gemini CLI도 각각 벤더 모델 위에서 동작하는 하네스입니다. 개념적 차이가 궁금하다면 Claude Code vs Codex CLI를 참고할 수 있습니다.

DeepSeek Harness의 핵심 특징은 세 가지입니다.

공식 프로젝트입니다. DeepSeek AI가 직접 개발하며, 단순한 커뮤니티 API 래퍼가 아닙니다.
MIT 라이선스 오픈소스입니다. THIRD_PARTY_NOTICES 파일에서 타사 종속성을 확인할 수 있고, 에이전트 루프 구현도 직접 읽고 검토할 수 있습니다.
개발자 미리보기입니다. README는 호환성을 깨는 변경 사항이 있을 수 있다고 명시합니다. 프로덕션 표준 도구로 즉시 채택하기보다, 격리된 프로젝트에서 먼저 검증하는 편이 좋습니다.

dsh는 DeepSeek V4-Pro API 출시와 동시에 공개됐습니다. V4-Pro의 엔드포인트, 모델 ID, 요청 형식은 DeepSeek V4-Pro API 사용 가이드에서 확인할 수 있습니다.

아키텍처: 모든 것이 플러그인입니다

대부분의 코딩 에이전트 하네스는 모놀리식 구조입니다. 에이전트 루프, 모델 클라이언트, 도구 정의, 세션 저장소가 하나의 애플리케이션에 결합됩니다. 설정값을 바꾸거나 일부 확장은 가능하지만, 핵심 구성 요소를 교체하기는 어렵습니다.

dsh는 다른 접근을 택합니다. 설계 원칙은 “모든 것이 플러그인”이며, Cordis 프레임워크를 기반으로 합니다.

실무적으로는 일반적으로 묶여 있는 에이전트 구성 요소를 교체 가능한 모듈로 분리했다는 뜻입니다.

구성 요소	dsh에서의 역할
모델 어댑터	DeepSeek, OpenAI 호환 API 등 LLM 백엔드와 통신
도구 레지스트리	파일 편집, 셸 실행, 검색 등 사용 가능한 도구 등록
세션 로그	세션 기록과 재생 방식 관리
에이전트 루프	결정 → 행동 → 관찰 흐름 제어

이 구조는 다음과 같은 경우에 특히 유용합니다.

모델별로 다른 작업을 할당해야 하는 팀
저장소마다 다른 권한 정책을 적용해야 하는 팀
컨텍스트 압축 또는 세션 관리 방식을 실험하려는 팀
내부 도구를 에이전트 도구로 연결하려는 개발자

예를 들어, “읽기 전용 분석”과 “파일 수정 가능한 구현 작업”에 서로 다른 도구 세트와 권한 정책을 적용하는 플러그인을 만들 수 있습니다.

다만 트레이드오프도 분명합니다. 교체 가능한 부분이 많을수록 깨질 수 있는 표면적도 넓어집니다. 개발자 미리보기 단계에서는 플러그인 API, 설정, 워크플로우가 버전 업데이트로 변경될 수 있으므로 플러그인 버전과 설정을 함께 관리해야 합니다.

빠른 시작: 로컬 에이전트 실행하기

가장 빠른 설치 방법은 다음 명령입니다.

npx @deepseek-ai/dsh web

명령을 실행하면 로컬 웹 UI가 시작됩니다.

http://127.0.0.1:3080

브라우저 자동 열기를 막으려면 --no-open을 추가합니다.

npx @deepseek-ai/dsh web --no-open

전역 설치나 별도 계정 생성은 필수가 아닙니다.

소스에서 실행하기

저장소를 직접 빌드하려면 다음 순서로 실행합니다.

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

pnpm install
pnpm run build
pnpm dsh web

첫 실행 체크리스트

웹 UI가 열리면 아래 순서로 설정합니다.

DeepSeek API 키를 설정합니다.

자격 증명은 $DSH_HOME/.credentials.yaml에 저장됩니다. 기본 설정 파일에는 키 자체가 아니라 키 참조만 포함됩니다.
작업 공간을 선택합니다.

UI에서 작업 공간을 추가하고 선택합니다. 작업 공간을 선택하기 전에는 세션 컴포저를 사용할 수 없습니다.
작업을 실행하고 권한 요청을 검토합니다.

활성 권한 정책에 따라 파일 쓰기나 셸 명령 실행 전에 승인 프롬프트가 표시됩니다.

처음에는 권한이 제한된 테스트 저장소에서 실행하는 것이 좋습니다. 예를 들어, 실제 서비스 저장소 대신 샘플 프로젝트를 준비해 다음과 같은 작업으로 동작을 확인할 수 있습니다.

현재 프로젝트 구조를 요약해 줘.

그다음 읽기 전용 작업이 기대대로 작동하는지 확인한 후에 파일 변경 작업을 요청합니다.

README에 로컬 실행 방법을 추가해 줘. 변경 전 diff를 먼저 보여 줘.

웹 UI 외 실행 모드

dsh web은 다음 명령의 축약형입니다.

dsh --profile web

프로필은 $DSH_HOME/profiles/ 아래에 위치합니다.

자동화나 CI에서는 헤드리스 프로필을 사용할 수 있습니다.

dsh --profile headless "프로젝트의 테스트 실패 원인을 분석해 줘"

이 모드는 단일 세션을 실행하고 결과를 출력한 뒤 종료하므로 스크립트와 CI 작업에 적합합니다.

구성과 플러그인을 점검할 때는 다음 명령도 유용합니다.

# 현재 구성 트리 출력
dsh --dump-config

# 기본 구성 출력
dsh --dump-default-config

# 프로필 플러그인 관리
dsh plugin

전체 CLI 옵션은 CLI README에서 확인할 수 있습니다.

어떤 모델을 실행할 수 있나요?

DeepSeek 모델이 기본값이며, V4-Pro가 주요 페어링입니다. 에이전트는 반복적으로 모델 호출을 수행하므로 토큰 비용도 고려해야 합니다. DeepSeek의 가격 정책 관련 정보는 DeepSeek V4-Pro 가격 인하와 공식 API 문서에서 확인할 수 있습니다.

하지만 dsh의 모델 어댑터는 플러그인 구조이므로 DeepSeek 모델에만 묶이지 않습니다.

내장 제공업체

카탈로그에서 다음 제공업체 항목을 사용할 수 있습니다.

Anthropic
OpenAI
Amazon Bedrock
Google Vertex AI
Azure

각 제공업체는 자체 자격 증명 처리를 지원합니다.

OpenAI 호환 엔드포인트 추가하기

OpenAI 호환 API라면 $DSH_HOME/settings.yaml에 다음 정보를 등록할 수 있습니다.

기본 URL
API 키를 읽을 환경 변수
사용할 모델 목록

이 방식은 클라우드 API뿐 아니라 로컬 런타임과 내부 게이트웨이에도 적용할 수 있습니다.

모델을 선택하면 이후 새 세션의 기본값으로 사용됩니다. 또한 각 세션은 시작 시 사용한 모델을 기록하므로, 프로젝트 진행 중 모델을 바꿔도 세션 이력을 구분할 수 있습니다.

정확한 설정 형식은 제공업체 가이드를 참고하세요. 사용자 지정 엔드포인트용 YAML 예시는 DeepSeek Harness에서 모든 모델을 실행하는 방법에서 확인할 수 있습니다.

플러그인 생태계: 설치 전 검토가 필수입니다

플러그인은 dsh-plugin GitHub 토픽에서 찾을 수 있습니다. 커뮤니티 논의는 GitHub Discussions와 Discord 서버에서 이뤄집니다.

출시 초기 생태계에서 확인할 수 있는 유형은 다음과 같습니다.

데스크톱 래퍼

deepseek-harness-desktop(Tauri), dsh_desktop(Windows) 같은 프로젝트가 웹 UI를 네이티브 앱 형태로 패키징합니다.
기능 플러그인

dsh-context, dsh-vision-router 등은 세션 컨텍스트나 라우팅 기능을 확장합니다.
MCP 관련 플러그인

작성 시점 기준으로 dsh 코어는 기본 Model Context Protocol(MCP) 지원을 제공하지 않습니다. 대신 커뮤니티 플러그인인 dsh-mcp-manager가 MCP 설정 페이지와 서버 연결 기능을 제공합니다.

MCP 플러그인으로 가능한 작업에는 다음이 포함됩니다.

원격 HTTP MCP 서버 연결
로컬 stdio MCP 서버 연결
OAuth 또는 정적 토큰 인증
mcp____* 이름으로 도구 등록
작업 공간 .dsh 디렉터리의 프로젝트별 서버 설정

여기서 중요한 구분이 있습니다.

“dsh가 MCP를 지원한다”는 표현은 현재 시점에서는 “커뮤니티 플러그인을 통해 MCP를 연결할 수 있다”는 의미입니다.

코어 기능과 커뮤니티 플러그인을 같은 수준의 안정성으로 간주하면 안 됩니다. 특히 API 키나 OAuth 토큰을 처리하는 플러그인은 설치 전에 소스, 유지보수 상태, 권한 범위를 검토하세요.

API 워크플로우에 적용하는 방법

에이전트 하네스는 결국 API 호출을 수행하는 실행 환경입니다. 모델 API를 호출할 뿐 아니라, 에이전트가 작업하는 코드베이스 안의 API 계약도 해석합니다.

문제는 코드베이스의 엔드포인트 정보가 실제 API 동작과 다를 수 있다는 점입니다. 오래된 문서, 누락된 스키마, 변경된 응답 형식이 있으면 에이전트는 잘못된 계약을 기반으로 코드를 작성할 수 있습니다.

따라서 에이전트에게 API 관련 구현을 맡기기 전에 API 표면을 먼저 검증하는 편이 좋습니다.

Apidog를 사용하면 다음 흐름을 구성할 수 있습니다.

OpenAPI 사양을 설계하거나 가져옵니다.
실제 엔드포인트를 사양과 비교해 테스트합니다.
백엔드 변경 중에도 사용할 수 있는 모의 서버를 구성합니다.
검증된 사양과 모의 응답을 기준으로 에이전트 작업을 진행합니다.

이렇게 하면 에이전트가 오래된 코드나 추측에 의존하는 대신, 명시적인 API 계약을 기반으로 구현할 수 있습니다.

MCP를 통해 API 사양 연결하기

Apidog MCP 서버는 MCP를 통해 API 사양을 AI 도구에 노출합니다.

dsh에서는 앞서 언급한 커뮤니티 dsh-mcp-manager 플러그인을 통해 연결할 수 있습니다.

실행 순서는 다음과 같습니다.

dsh-mcp-manager 플러그인을 설치합니다.
Apidog MCP 서버를 등록합니다.
프로젝트별 MCP 구성을 .dsh 디렉터리에 저장합니다.
에이전트가 추측 대신 실제 API 사양을 조회하도록 작업을 요청합니다.
CLI 기반 테스트를 실행해 생성된 구현을 검증합니다.

예를 들어 에이전트에게 다음처럼 요청할 수 있습니다.

등록된 API 사양을 확인한 뒤, POST /users 엔드포인트용 TypeScript 클라이언트를 구현해 줘.
응답 스키마와 오류 코드를 사양 기준으로 처리하고, 테스트 실행 명령도 제안해 줘.

에이전트가 직접 실행할 수 있는 CLI 테스트까지 포함한 흐름은 DeepSeek Harness에서 Apidog CLI 사용하기에서 확인할 수 있습니다. 시작하기 전에 Apidog를 다운로드하고 API 사양을 가져오면 됩니다.

지금 시도해야 할까요?

용도에 따라 판단하는 것이 가장 현실적입니다.

지금 시도하기 좋은 경우

에이전트 하네스의 내부 구조를 직접 이해하고 싶다.
작업별로 서로 다른 모델을 선택해야 한다.
자체 호스팅 모델 또는 OpenAI 호환 엔드포인트를 사용한다.
에이전트용 도구나 플러그인을 직접 만들고 싶다.
이미 DeepSeek API를 사용하고 있으며 V4-Pro 기반 에이전트 경험을 원한다.

기다리는 편이 좋은 경우

안정적인 일상 업무용 도구가 필요하다.
지원 계약과 검증된 배포 경로가 필요하다.
커뮤니티 플러그인이 자격 증명을 처리하는 환경을 허용하기 어렵다.
성숙한 제품 수준의 UX와 호환성을 기대한다.

실무적인 접근은 병행 운영입니다. 프로덕션 작업에는 현재 검증된 에이전트를 유지하고, 사이드 프로젝트나 격리된 샌드박스에서 dsh를 테스트하세요. 기존 도구와의 차이가 궁금하다면 DeepSeek Harness vs Claude Code를 참고할 수 있습니다.

자주 묻는 질문

DeepSeek Harness는 무료인가요?

하네스 자체는 MIT 라이선스 기반의 무료 오픈소스입니다. 다만 연결한 모델 API 사용량은 해당 제공업체의 과금 정책을 따릅니다.

모델 어댑터가 플러그인 구조이므로 로컬 호스팅 모델에 연결할 수도 있습니다. 설정 방법은 DeepSeek Harness에서 모든 모델 실행을 참고하세요.

dsh는 DeepSeek 모델에서만 작동하나요?

아니요. DeepSeek 모델이 기본값이지만, 모델 어댑터는 플러그인입니다. Anthropic, OpenAI, Bedrock, Vertex, Azure를 포함하는 제공업체 항목을 사용할 수 있으며, OpenAI 호환 엔드포인트도 $DSH_HOME/settings.yaml을 통해 추가할 수 있습니다.

DeepSeek Harness를 내 코드베이스에서 실행해도 안전한가요?

권한 정책과 설치한 플러그인에 따라 다릅니다.

웹 UI는 작업 공간 선택을 요구하고, 활성 권한 정책에 따라 파일 쓰기와 셸 명령 전에 승인 요청을 표시합니다. 하지만 개발자 미리보기이며, 데스크톱 래퍼를 포함한 커뮤니티 플러그인은 API 키를 처리할 수 있는 타사 코드입니다.

다음 원칙을 권장합니다.

처음에는 테스트 저장소에서 실행합니다.
설치 전 플러그인 소스와 유지보수 상태를 검토합니다.
API 키와 OAuth 토큰의 저장 위치를 확인합니다.
중요한 브랜치나 복구가 어려운 저장소에서는 직접 실행하지 않습니다.
파일 변경 전 diff 확인을 요청합니다.

하네스는 모델과 어떻게 다른가요?

모델은 추론 엔진이고, 하네스는 모델이 실제로 행동하게 만드는 실행 계층입니다.

하네스는 세션 관리, 도구 호출, 파일 접근, 권한 프롬프트, 컨텍스트 조립을 담당합니다. 따라서 같은 모델을 사용해도 하네스의 도구 구성, 권한 정책, 컨텍스트 전략이 다르면 에이전트의 동작 결과도 크게 달라질 수 있습니다.

DEV Community