AIREITERDeepSeek V4-Pro와 V4-Flash를 코딩 에이전트로 쓰기 위한 공식 하니스, DeepSeek Harness(DSH)가 2026년 8월 13일 npm 패키지 @deepseek-ai/dsh로 공개됐다. V4-Pro가 정식 출시(GA)된 날과 같다. 일반적인 DeepSeek API 키만 있으면 네 단계로 설치할 수 있고, 플러그인 시스템도 함께 제공된다. 다만 설치 전에 꼭 알아둘 점이 있다. 5월부터 PyPI에는 deepseek-harness라는 전혀 다른 Python 패키지가 올라와 있으며, 이쪽도 dsh 명령어를 제공한다. 둘은 같은 도구가 아니다.
DeepSeek Harness(DSH)는 무엇을 하는가
코딩 에이전트 하니스는 모델 주변에서 컨텍스트 선택, 도구 오류 처리, 재계획, 작업 완료 판정을 맡는 실행 계층이다. 모델이 같아도 하니스 설정에 따라 벤치마크 점수는 달라질 수 있다. DeepSeek가 에이전트 평가 결과를 낼 때 원시 모델 점수만 제시하지 않고 하니스 설정까지 공개하는 이유다.
익숙한 사례로는 Anthropic Claude 모델용 하니스인 Claude Code, 여러 제공업체 모델을 IDE에 연결하는 Cursor, VS Code 안에서 OpenAI 모델을 활용하는 GitHub Copilot이 있다. 모델에 하니스를 결합하면 단일 프롬프트에 답하는 수준을 넘어 파일을 수정하고, 명령을 실행하고, API를 호출하는 에이전트가 된다. DSH는 V4-Pro와 V4-Flash에서 그 역할을 맡는다.
DSH는 Sonnet과 Opus에 맞춰 설계된 Claude Code처럼, V4-Pro와 V4-Flash에 맞춰 DeepSeek가 만든 퍼스트파티 하니스다. 7월 31일 V4-Flash 베타 변경 로그에서 처음으로 이름이 공개됐다. 해당 항목은 에이전트 벤치마크에 "DeepSeek Harness minimal mode (to be released soon)"를 사용했으며, effort=max, top_p=0.95, temperature=1.0로 설정했다고 설명한다.
‘Minimal mode’는 벤치마크별 튜닝 대신 재현성을 확보하기 위해, 추론 노력은 최대로 두고 샘플링 파라미터는 고정한 간소화된 구성이다. 베타 관련 보고에서 언급된 플러그인 시스템까지 포함한 정식 제품은 공개 점수를 산출한 벤치마크 실행기보다 범위가 넓다.
V4-Pro와 V4-Flash는 모두 100만 토큰 컨텍스트 윈도우와 세 가지 추론 노력 설정을 지원한다. 단순 작업에는 low, 일반적인 에이전트 작업에는 high, 복잡한 작업에는 max를 쓰는 방식이다(공식 변경 로그 8월 13일 항목).
@deepseek-ai/dsh 설치하기
Node.js 18 이상이 필요하다. DeepSeek의 공식 Claude Code 연동 가이드가 요구하는 기준과 동일하다.
- Node 버전 확인:
node --version을 실행한다. 18 이상이 필요하며, macOS에서 없다면brew install node로 설치할 수 있다. - 전역 설치:
npm install -g @deepseek-ai/dsh. - 키 설정: DeepSeek 플랫폼에서 발급한 키로
export DEEPSEEK_API_KEY=<your key>를 실행한다. - 실행:
cd /path/to/my-project && dsh.
macOS에서 npm 패키지를 전역 설치할 때 권한 오류가 나는 일은 흔하다. npm이 권장하는 해결책은 사용자 쓰기 권한이 있는 전역 prefix를 설정하는 것이다(npm config set prefix ~/.npm-global). sudo로도 설치할 수 있지만, 이후 패키지 업데이트 과정에서 소유권 충돌이 생길 수 있다.
하니스 소프트웨어 자체의 별도 가격은 아직 발표되지 않았다. 다만 그 뒤에서 동작하는 모델 API 가격은 8월 16일 16:00 UTC부터 바뀐다. V4 계열은 피크·오프피크 요금제로 전환되며, 오프피크 요금은 피크의 절반이다(공식 변경 로그).
V4-Pro GA 벤치마크에서 확인되는 Harness
아래는 DeepSeek가 8월 13일 변경 로그 항목에서 공개한 공식 수치다. 모두 앞서 설명한 하니스 구성으로 산출됐다.
| 벤치마크 | V4-Pro GA | V4-Flash 베타 |
|---|---|---|
| Terminal Bench 2.1 | 87.9 | 82.7 |
| Cybergym | 83.3 | 76.7 |
| Toolathlon-Verified | 74.1 | 70.3 |
| DSBench-FullStack | 71.1 | 68.7 |
| DSBench-Hard | 67.2 | 59.6 |
| DeepSWE | 62.7 | 54.4 |
| NL2Repo | 61.5 | 54.2 |
| Agents' Last Exam | 25.7 | 25.2 |
| HLE (with tools) | 60.0 | — |
V4-Pro는 이들 벤치마크에서 Flash보다 0.5~8.3점 앞섰다. 차이가 가장 큰 항목은 DeepSWE(+8.3)와 NL2Repo(+7.3)다. 가장 눈에 띄는 수치는 Terminal Bench 2.1의 87.9다. r/LocalLLaMA의 독립적인 공개 하니스 재현 결과는 Flash 0731이 445회 시행에서 82.7을 기록했다고 보고했으며, 이는 설정 차이에 따른 오차 범위 안에서 DeepSeek의 주장과 일치한다. DSBench-FullStack과 DSBench-Hard는 내부 평가 세트이므로, 이 두 행은 DeepSeek 자체 측정치다.
공개된 모든 벤치마크는 max 노력 설정으로 실행됐다. 실제 운영에서는 단순 작업에 low, 일반적인 에이전트 작업에 high, 복잡한 작업에 max를 쓰라는 것이 DeepSeek의 가이드다.
@deepseek-ai/dsh와 pip install deepseek-harness는 다르다
이름은 거의 같지만, 몇 달 간격으로 나온 서로 무관한 두 패키지다.
@deepseek-ai/dsh (npm) | deepseek-harness (PyPI) | |
|---|---|---|
| 관리 주체 | DeepSeek(공식 scope) | 무관한 개인 개발자 Henry Zhang |
| 최초 출시 | 2026년 8월 13일 | 2026년 5월 9일 |
| 언어 | Node.js | Python |
| 정체 | 코딩 에이전트 하니스 | 프로토콜 어댑터 라이브러리 |
| 설치 | npm install -g @deepseek-ai/dsh | pip install deepseek-harness |
| 라이선스 | 아직 확인되지 않음 | MIT |
PyPI 프로젝트는 코딩 에이전트가 아니라 프로토콜 어댑터 라이브러리다. 작성자는 270회 이상의 테스트를 통해 V4 API 동작 16가지를 문서화했고, 이를 10개 규칙 계약으로 정리해 Python 라이브러리, dsh CLI, MCP 서버, Anthropic Skill의 네 가지 형식으로 배포했다. V4 기반 개발에서 특히 문제가 될 수 있는 세 가지 발견은 다음과 같다.
- 멀티턴 도구 루프에서는 assistant 메시지의
reasoning_content를 보존하지 않으면 HTTP 400이 반환된다. 두 모델 모두에서 3/3으로 재현됐다. /beta엔드포인트는v4-pro를 별도 안내 없이deepseek-reasoner로 다시 매핑한다.- 캐시 히트는 1,024토큰 접두사 이후 256토큰 단위로 나타난다. 한 5턴 루프는 95% 평형에 도달해 실질 입력 비용을 약 50배 줄였다.
혼동의 핵심은 두 패키지 모두 dsh 명령어를 제공한다는 점이다. pip로 설치했다면 어댑터 라이브러리이고, @deepseek-ai scope 아래에서 npm으로 설치했다면 하니스다.
DSH 없이 DeepSeek V4를 코딩 에이전트로 쓰는 방법
DSH 문서가 안정되기 전에 DeepSeek 기반 코딩 에이전트를 사용하고 싶다면, DeepSeek의 공식 연동 가이드가 지원하는 세 가지 경로를 참고하면 된다.
| 도구 | 설정 | DeepSeek 모델 | 적합한 용도 | |
|---|---|---|---|---|
| Claude Code | 환경 변수, Anthropic 호환 엔드포인트 | V4-Pro(주 모델), V4-Flash(서브에이전트) | max 노력 설정의 터미널 코딩 | |
| OpenCode | /connect 흐름에서 DeepSeek 제공업체 선택 | V4-Pro | 오픈소스, 대화형 제공업체 선택(v1.14.24+ 필요) | |
| OpenClaw | `curl -fsSL https://openclaw.ai/install.sh \ | bash` | V4-Pro 또는 V4-Flash | Skills와 채팅 연동을 갖춘 개인 비서 |
Claude Code 설정에서는 DeepSeek 모델을 Claude Code의 모델 슬롯에 다음과 같이 매핑한다.
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<your DeepSeek API key>
export ANTHROPIC_MODEL=deepseek-v4-pro
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_EFFORT_LEVEL=max매핑에서 주의할 부분이 하나 있다. claude-sonnet 요청은 Pro가 아니라 Flash로 연결된다. DeepSeek 문서는 Pro를 Opus 슬롯에, Flash를 Haiku 슬롯에 배정한다. 세 도구 모두 DeepSeek가 효과나 보안을 보장하지 않는 서드파티 연동으로 문서화돼 있다. 더 폭넓은 비교는 코딩 에이전트 LLM 비교와 V4-Pro GA API 가이드에서 확인할 수 있다.
FAQ
@deepseek-ai/dsh가 공식 DeepSeek Harness인가?
@deepseek-ai npm scope는 DeepSeek의 GitHub 조직과 일치하며, 출시일도 7월 31일 변경 로그에서 예고한 시점과 맞는다. 커뮤니티 게시물은 실제 설치가 가능하다고 확인한다. 다만 DeepSeek의 8월 13일 변경 로그는 V4-Pro GA를 문서화하면서도 하니스 이름을 직접 언급하지 않았고, npm은 패키지 페이지의 자동 검증을 차단한다.
DSH와 PyPI의 deepseek-harness는 무엇이 다른가?
관리자도 제품도 다르다. @deepseek-ai/dsh는 8월 13일 출시된 npm용 코딩 에이전트 하니스다. pip install deepseek-harness는 Henry Zhang이 만든 독립 Python 프로토콜 어댑터 라이브러리(MIT, 5월 9일)로, V4 API의 특이 동작을 다룬다. 두 패키지 모두 dsh 명령어를 제공한다.
DSH를 쓰려면 DeepSeek API 키가 필요한가?
그렇다. 하니스는 DeepSeek API를 통해 V4-Pro와 V4-Flash에서 실행되므로, 사용량은 토큰 기준으로 과금된다. npm 패키지 설치 자체는 무료이며 비용은 API 사용량에서 발생한다. V4 계열 가격은 8월 16일 16:00 UTC에 피크·오프피크 요금제로 바뀌며, 오프피크는 피크의 절반이다.
DSH는 Claude Code와 어떻게 다른가?
Claude Code는 이미 성숙한 문서와 기능을 갖춘 터미널 코딩 에이전트이며, Anthropic 호환 엔드포인트를 통해 DeepSeek에서도 실행할 수 있다. DSH의 핵심 제안은 모델별 최적화다. V4 프로토콜 동작에 맞게 설계된 하니스라는 점에서, 그 프로토콜에 맞춰 적용한 도구와 차별화된다. 벤치마크 구성 공개를 보면 이점은 충분히 가능성 있어 보이지만, DSH 문서와 커뮤니티 테스트가 따라오기 전까지 독립적인 실사용 검증은 이뤄지지 않았다.
AI 하니스와 AI 에이전트의 차이는 무엇인가?
하니스는 컨텍스트 관리, 도구 라우팅, 작업 오케스트레이션을 담당하는 인프라 계층이다. 에이전트는 그 하니스 안에서 모델이 실행되는 결합형 시스템으로, 여러 단계의 작업을 수행할 수 있다. 모든 에이전트에는 하니스가 필요하지만, 하나의 하니스가 여러 모델을 지원할 수도 있다. Claude Code, Cursor, Copilot, DSH는 모두 하니스이며, 이를 ‘에이전트’로 만드는 것은 그 안에서 구동되는 모델이다.
출시 현황: 공식 확인 내용과 커뮤니티 보고
이 글의 정보는 두 단계의 근거를 바탕으로 정리했다.
공식 확인(날짜가 명시된 DeepSeek API 변경 로그):
deepseek-v4-pro는 8월 13일 네이티브 OpenAI Responses API 지원 및 세 가지 추론 노력 수준과 함께 GA에 도달했다(변경 로그).- V4-Flash는 7월 31일 공개 베타에 진입했으며, 벤치마크는 "DeepSeek Harness minimal mode (to be released soon)"로 산출됐다.
- 공개된 V4-Pro GA 및 V4-Flash 베타 벤치마크 수치는 모두 이 변경 로그 항목에서 가져온 것이다.
- V4 계열 가격은 8월 16일 16:00 UTC에 피크·오프피크 요금제로 변경된다.
- Claude Code, OpenCode, OpenClaw 연동 가이드는 공식 문서다.
커뮤니티 보고(Reddit 게시물, 재현된 스크린샷):
@deepseek-ai/dsh는 설치 및 실행이 가능하다. u/Testx01은 8월 13일 12:56 UTC에 패키지 링크를 올렸고, u/Available_Yam_6267이 몇 분 뒤 뒤따랐다.@deepseek-ainpm scope는 DeepSeek의 GitHub 조직과 일치한다.- npm 패키지 페이지는 자동 가져오기를 차단하므로, 레지스트리를 통한 버전·라이선스·관리자 메타데이터는 확인되지 않았다.
"Deepseek harness is out on npm :)" — u/Testx01, r/DeepSeek, August 13
- 재현된 내부 베타 메시지에 따르면, 369명 규모의 베타 그룹은 8월 11일 최종 내부 빌드를 배포했으며, 플러그인 개발자에게 8월 13일 공개 베타 전까지 저장소에
#dsh태그를 붙이라고 안내했다. 출시 후에는 플러그인을 개별 계정으로 이전할 수 있게 된다고 전했다. - 커뮤니티 보도는 DeepSeek가 전담 하니스 팀을 구성하고 Agent Harness 제품 역할을 채용 중이라고 중국 기술 매체가 5월에 보도했다고 전했다.
DeepSeek가 자사 사이트에 정식 문서를 게시하기 전까지 DSH의 기능, CLI, 플러그인 관련 주장은 커뮤니티 확인 정보로 받아들이는 편이 안전하다.