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

DeepSeek은 2026년 8월 13일 특이한 것을 출시했습니다. 모델이 아니라 모델을 실행하는 기계였습니다. DeepSeek Harness (dsh)는 이 회사의 공식 오픈소스 에이전트 하네스입니다. 이는 대규모 언어 모델을 세션 루프, 도구 실행, 권한 확인 및 로컬 웹 UI를 갖춘 작동하는 코딩 에이전트로 전환하는 소프트웨어 레이어입니다. DeepSeek V4-Pro가 API에 출시된 같은 날 출시되었으며, VentureBeat는 이를 Claude Code의 오픈소스 경쟁자로 보도했습니다.

개발자 커뮤니티는 빠르게 반응했습니다. 8월 20일 현재, 출시 1주일 만에 deepseek-harness 저장소는 약 169,000개의 별과 18,100개의 포크를 기록했습니다. 7일 만에 이러한 숫자는 코드 자체보다는 개발자들의 요구를 더 잘 보여줍니다. 개발자들은 검사하고, 수정하고, 어떤 모델에도 연결할 수 있는 에이전트 하네스를 원합니다.

버튼

DeepSeek Harness는 실제 무엇인가요?

하네스는 모델 주변의 모든 것을 의미합니다. 모델은 토큰을 예측합니다. 하네스는 모델이 무엇을 보는지, 어떤 도구를 호출할 수 있는지, 파일 편집 및 셸 명령이 어떻게 승인되는지, 그리고 다단계 세션이 어떻게 유지되는지를 결정합니다. Claude Code, Codex CLI, Gemini CLI는 모두 해당 벤더의 모델을 감싸는 하네스입니다. 이 두 가지가 어떻게 비교되는지 배경 지식이 필요하다면, Claude Code vs Codex CLI에서 다루었습니다.

DeepSeek Harness는 이 범주에 속하는 DeepSeek의 제품이며, 다음과 같은 세 가지 특징이 있습니다.

공식적입니다. DeepSeek AI의 자체 프로젝트이며, 그들의 API를 감싸는 커뮤니티 래퍼가 아닙니다.
오픈소스입니다. MIT 라이선스를 따르며, 저장소의 THIRD_PARTY_NOTICES 파일에 타사 종속성이 문서화되어 있습니다. 코드베이스를 신뢰하는 에이전트 루프를 읽을 수 있습니다.
개발자 미리보기입니다. README는 다음과 같이 경고합니다. "호환성을 깨는 변경 사항이 있을 것입니다." 이 말을 액면 그대로 받아들이십시오. 이것이 실제 의미하는 바는 아래에서 더 자세히 설명합니다.

출시 시점 또한 중요합니다. dsh는 DeepSeek V4-Pro가 API에 출시됨과 동시에 등장했으므로, 하네스와 그 주력 기본 모델이 한 쌍으로 출시되었습니다. 모델 측면을 평가하고 있다면, DeepSeek V4-Pro API 사용 가이드에서 엔드포인트, 모델 ID 및 요청 예시를 확인할 수 있습니다.

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

여기서 dsh는 모든 주류 코딩 에이전트와 차별화됩니다. 대부분의 하네스는 모놀리식입니다. 에이전트 루프, 모델 클라이언트, 도구 정의 및 세션 저장소가 하나의 애플리케이션으로 제공됩니다. 이를 구성하고, 때로는 확장할 수 있지만, 핵심 부분을 교체할 수는 없습니다.

dsh는 이를 뒤집습니다. 그 설계 원칙은 "모든 것이 플러그인"이며, Cordis라는 프레임워크를 기반으로 합니다. 이 프레임워크의 설계는 "시공간 구성 가능성을 위한 프로그래밍 패러다임"이라는 논문에 설명되어 있습니다. 학술적인 제목을 벗겨내면 실용적인 주장은 다음과 같습니다. 일반적으로 함께 고정되어 있는 에이전트의 구성 요소들이 dsh에서는 교체 가능한 모듈이라는 것입니다. 여기에는 다음이 포함됩니다.

모델 어댑터. LLM API와 통신하는 레이어가 플러그인입니다. 이를 교체하면 dsh는 다른 백엔드를 구동합니다.
도구 레지스트리. 에이전트가 호출할 수 있는 도구 세트(파일 편집, 셸, 검색)는 하드코딩되지 않고 플러그인에 의해 등록됩니다.
세션 로그. 세션이 기록되고 재생되는 방식이 플러그인 가능합니다.
에이전트 루프 자체. 핵심적인 결정-행동-관찰 주기조차도 교체할 수 있는 플러그인입니다.

이것이 왜 중요할까요? 2026년에는 하네스 레이어에서 실제 실험이 이루어지고 있기 때문입니다. 팀은 다양한 컨텍스트 관리 전략, 다양한 권한 모델, 다양한 저장소를 위한 다양한 도구 세트를 시도하고 싶어 합니다. 모놀리식 에이전트로는 벤더가 아이디어를 출시할 때까지 기다려야 하지만, dsh로는 플러그인을 작성할 수 있습니다.

트레이드오프도 마찬가지로 현실적입니다. 모든 것이 교체 가능한 시스템은 파손될 수 있는 표면적이 더 넓으며, 호환성을 깨는 변경 사항을 약속하는 개발자 미리보기는 그 과정에서 플러그인을 파손시킬 것입니다. 이것이 dsh가 요구하는 베팅입니다. 지금은 유연성, 나중에는 안정성입니다.

빠른 시작: 처음부터 실행 중인 에이전트까지

설치 경로는 하나의 명령으로 가능합니다.

npx @deepseek-ai/dsh web

이것은 `http://127.0.0.1:3080`에서 로컬 웹 UI를 시작하고 브라우저를 엽니다 (`--no-open`을 전달하면 열지 않습니다). 전역 설치나 계정 생성이 게이트 역할을 하지 않습니다.

소스에서 빌드하려면 저장소 경로도 작동합니다. 저장소를 복제한 다음 `pnpm install`, `pnpm run build`, `pnpm dsh web`을 실행합니다.

여기서부터 첫 실행 흐름은 세 단계로 이루어집니다.

설정에서 DeepSeek API 키를 구성합니다. 키는 `$DSH_HOME/.credentials.yaml`에 저장되며, 주 설정 파일과는 별도로 보관됩니다. 주 설정 파일은 키에 대한 참조만 포함합니다.
작업 공간을 선택합니다. "작업 공간 선택"을 클릭하고 dsh를 시작한 프로젝트 디렉토리를 추가한 다음 선택합니다. 이 단계는 선택 사항이 아닙니다. 작업 공간이 선택될 때까지 세션 컴포저를 사용할 수 없습니다. dsh는 아무것도 실행하기 전에 "내가 어떤 파일을 고려하도록 허용됩니까?"에 대한 명시적인 답변을 원합니다.
작업을 실행하고 작업을 승인합니다. 웹 UI는 "활성 권한 정책에 따라 승인이 필요한" 작업 전에 묻습니다. 파일 쓰기 및 셸 명령은 자동으로 실행되지 않고 프롬프트로 표시됩니다.

웹 UI는 단 하나의 진입점일 뿐입니다. 내부적으로 dsh는 **프로필**을 부팅합니다. `dsh web`은 `dsh --profile web`의 약어이며, 프로필은 `$DSH_HOME/profiles/` 아래에 있습니다. 단일 새 세션을 실행하고 결과를 출력한 다음 종료하는 헤드리스 모드(`dsh --profile headless "job"`)도 있는데, 이는 스크립트 및 CI에 필요한 형태입니다. `dsh plugin` 서브커맨드는 프로필 디렉터리에서 pnpm으로 전달하여 프로필의 플러그인을 관리하며, `--dump-config` 및 `--dump-default-config`와 같은 런처 플래그는 부팅하지 않고 구성된 구성 트리를 출력합니다. 전체 목록은 CLI README에 있습니다.

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

DeepSeek 모델은 기본값이며, V4-Pro는 주요 페어링입니다. 비용 측면에서 알아두어야 할 점은 DeepSeek이 비수기 할인을 영구화하여 하루 종일 토큰을 소모하는 에이전트를 실행하는 경제성을 변화시켰다는 것입니다. 자세한 내용은 DeepSeek V4-Pro 가격 인하에 대한 게시물과 공식 참조는 api-docs.deepseek.com에서 확인할 수 있습니다.

그러나 모델 어댑터는 플러그인이며, dsh는 이를 적극 활용합니다. 기본값 외에 두 가지 경로가 있습니다.

카탈로그 제공업체. Anthropic, OpenAI, Bedrock, Vertex 및 Azure에 대한 내장 제공업체 항목이 있으며, 각기 제공업체별 자격 증명 처리가 가능합니다.
사용자 지정 제공업체. 모든 OpenAI 호환 엔드포인트는 `$DSH_HOME/settings.yaml`에 기본 URL, 키에 대한 환경 변수 및 모델 목록으로 등록할 수 있습니다. 이는 클라우드 API뿐만 아니라 로컬 런타임 및 게이트웨이도 포함합니다.

모델을 선택하면 새 세션의 기본값이 되며, 모든 세션은 시작된 모델을 기록하므로 프로젝트 중간에 전환해도 기록이 혼란스럽지 않습니다. 제공업체 가이드는 구성 형식을 문서화합니다. 이 섹션은 의도적으로 짧게 유지했습니다. 사용자 지정 엔드포인트에 대한 정확한 YAML을 포함한 전체 연습은 DeepSeek Harness에서 모든 모델을 실행하는 방법에 있습니다.

플러그인 생태계, 출시 1주차

플러그인은 `dsh-plugin` GitHub 토픽을 통해 발견되며, 커뮤니티는 GitHub Discussions 및 Discord 서버를 통해 소통합니다. 출시 1주일 후, 생태계는 이미 수요의 형태를 보여줍니다.

데스크톱 래퍼. deepseek-harness-desktop (Tauri) 및 dsh_desktop (Windows)과 같은 프로젝트는 웹 UI를 네이티브 앱으로 패키징합니다. 이들은 DeepSeek의 공식 릴리스가 아닌 커뮤니티 프로젝트이므로, API 키를 건드리는 모든 타사 래퍼에 적용하는 것과 동일한 검토를 적용하십시오.
기능 플러그인. dsh-context 및 dsh-vision-router와 같은 커뮤니티 저장소는 세션이 볼 수 있는 것과 라우팅을 확장합니다. 동일한 주의 사항: 커뮤니티에서 빌드되었습니다.
MCP 지원. dsh는 이 글을 쓰는 시점에는 핵심에 기본 Model Context Protocol 지원을 제공하지 않습니다. 존재하는 것은 커뮤니티 플러그인인 dsh-mcp-manager로, MCP를 위한 설정 페이지를 추가합니다. 원격 HTTP 또는 로컬 stdio 서버, OAuth 또는 정적 토큰 인증, `mcp____*` 이름으로 등록된 도구, 그리고 작업 공간의 `.dsh` 디렉토리 내 프로젝트별 서버 구성이 포함됩니다.

마지막 요점은 쉽게 오해할 수 있으므로 강조할 가치가 있습니다. dsh가 "MCP를 지원한다"는 게시물을 읽었다면, 정확한 버전은 다음과 같습니다. 커뮤니티가 플러그인으로 MCP 지원을 구축했으며, 이는 모든 것이 플러그인 아키텍처인 이유입니다. 핵심은 나중에 이를 흡수할 수도 있습니다. 아직은 아닙니다.

API 워크플로우가 적합한 곳

에이전트 하네스는 결국 API 호출을 실행하는 기계입니다. 모델 API를 구동하고, 사용자가 연결하는 모든 프로젝트 내의 API를 구동합니다. dsh가 백엔드에 대해 코드를 작성할 때, 코드베이스에서 스크랩할 수 있는 엔드포인트에 대한 이해를 바탕으로 작동합니다. API의 실제 동작이 사양과 일치하지 않으면 에이전트는 잘못된 계약에 대해 자신 있게 코딩하고, 런타임에 문제를 발견하게 됩니다.

해결책은 지루하지만 효과적입니다. 에이전트가 API 표면을 건드리기 전에 확인하십시오. Apidog는 해당 레이어를 다룹니다. OpenAPI 사양을 설계하거나 가져오고, 실제 엔드포인트를 사양에 대해 테스트하고, 모의 서버를 가동하여 백엔드가 변경 중일 때도 에이전트가 안정적이고 사양에 맞는 응답을 기반으로 개발할 수 있도록 합니다. 검증된 모의 환경에서 반복하는 에이전트는 오래된 코드에서 추측하는 에이전트보다 훨씬 적은 환각적인 통합을 생성합니다.

직접적인 통합 경로도 있습니다. Apidog MCP 서버는 MCP를 통해 API 사양을 AI 도구에 노출합니다. dsh에서는 위에서 설명한 커뮤니티 dsh-mcp-manager 플러그인을 통해 작동합니다. 플러그인을 설치하고 Apidog MCP 서버를 등록하면, 세션이 추론하는 대신 실제 사양을 쿼리할 수 있습니다. 에이전트가 직접 트리거할 수 있는 CLI 기반 테스트 실행을 포함하여 전체 루프를 DeepSeek Harness에서 Apidog CLI 사용하기에서 안내합니다. 실험하기 전에 API 측면을 준비하고 싶다면, 먼저 Apidog를 다운로드하고 사양을 가져오십시오. 에이전트 오류의 가장 큰 원인을 제거하는 5분짜리 설정입니다.

지금 시도해야 할까요, 아니면 기다려야 할까요?

솔직한 대답은 무엇에 사용할지에 따라 달라집니다.

다음 경우에 지금 시도하십시오:

에이전트 하네스가 내부적으로 어떻게 작동하는지 이해하고 싶습니다. dsh는 가장 검사 가능한 주요 하네스이며, 실제 에이전트 루프를 읽는 것이 어떤 블로그 게시물보다 더 많은 것을 가르쳐줍니다.
모델 유연성이 필요합니다. 팀이 다른 작업에 다른 모델을 사용하거나 자체 호스팅하는 경우, 플러그인 가능한 모델 어댑터는 모놀리식 에이전트가 제공할 수 없는 기능입니다.
도구를 구축합니다. 플러그인 생태계는 일주일밖에 되지 않았습니다. 이렇게 많은 관심을 받는 저장소에서 초기 플러그인 작성자는 엄청난 가시성을 얻습니다.
이미 DeepSeek의 API를 사용 중이며 V4-Pro에 대한 1자 에이전트 경험을 원합니다.

다음 경우에 기다리십시오:

안정적인 일상용 드라이버가 필요합니다. "호환성을 깨는 변경 사항이 있을 것입니다"는 마케팅의 겸손이 아니라 약속입니다. 구성, 플러그인, 그리고 습관이 버전 간에 모두 깨질 수 있습니다.
조직에서 검증되고 지원되는 도구가 필요합니다. 커뮤니티 플러그인이 자격 증명을 처리하는 개발자 미리보기는 지원 계약이 있는 GA 제품과는 다른 위험 프로필을 가집니다.
성숙한 하네스의 완성도를 원합니다. Claude Code는 인체 공학 면에서 오랜 선두를 달리고 있으며, 일주일 된 미리보기는 아직 모든 면에서 이를 따라잡지 못할 것입니다.

대부분의 실무 개발자에게 실용적인 방법은 두 가지 모두입니다. 프로덕션 작업에는 현재 에이전트를 유지하고, 사이드 프로젝트에서 dsh를 실행하며, 미리보기 레이블이 사라지기 전에 자신만의 의견을 형성하십시오. 주요 질문이 기존 제품과 어떻게 비교되는지라면, DeepSeek Harness vs Claude Code에서 나란히 비교했습니다.

자주 묻는 질문

DeepSeek Harness는 무료인가요?

하네스 자체는 MIT 라이선스에 따라 무료이며 오픈소스입니다. 비용이 드는 것은 그 뒤에 있는 모델입니다. DeepSeek 플랫폼(또는 구성한 제공업체)에서의 API 사용은 해당 제공업체에 의해 정상적으로 청구됩니다. 어댑터 레이어가 플러그인 가능하므로, dsh를 로컬 호스팅 모델에 연결하고 토큰당 비용을 전혀 지불하지 않을 수도 있습니다. 설정 방법은 DeepSeek Harness에서 모든 모델 실행을 참조하십시오.

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

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

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

권한 모델과 사용자의 판단에 따라 안전합니다. 웹 UI는 세션이 실행되기 전에 작업 공간을 선택하도록 요구하며, 활성 권한 정책에 따라 승인이 필요한 작업 전에 프롬프트를 표시합니다. 하지만, 이것은 개발자 미리보기이며, 커뮤니티 플러그인(데스크톱 래퍼 포함)은 API 키를 처리할 수 있는 타사 코드입니다. 설치하는 것을 검토하고, 미리보기를 잘못된 편집으로 손상될 수 있는 저장소에서는 멀리하십시오.

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

모델은 추론 엔진이고, 하네스는 모델이 행동할 수 있도록 하는 모든 것입니다. 세션 관리, 도구 호출, 파일 접근, 권한 프롬프트 및 컨텍스트 어셈블리가 모두 하네스에 있습니다. 동일한 모델을 사용하는 두 에이전트가 하네스가 다르기 때문에 완전히 다르게 행동할 수 있으며, 이것이 대부분의 코딩 에이전트 경쟁이 현재 하네스 레이어에서 발생하는 이유입니다.