Windows에서의 DeepSeek Harness: 데스크톱 앱 없이도 문제없다 — 공식 실행 방법

There is no official DeepSeek Harness desktop app for Windows, and you do not need one. DeepSeek Harness (dsh) — the open-source agent runtime DeepSeek released under an MIT license on 2026-08-13 — is a Node.js tool that runs a local web server you open in your browser, with a headless CLI for the terminal as the alternative. On Windows the whole setup is two commands: install Node.js 22.19 or newer (Node 24 LTS is the safer pick), then run npx @deepseek-ai/dsh web and open http://127.0.0.1:3080. Every "DeepSeek Harness Desktop" repository on GitHub is an unofficial community wrapper around that same two-command setup — useful to some people, but not required. It is also the harness DeepSeek uses to produce the agentic coding results it reports for DeepSeek V4 Pro and DeepSeek V4 Flash, which is why the two models keep showing up in any conversation about it.

"deepseek harness windows"를 검색했다면, 아마 그 래퍼 저장소들이 나열된 페이지를 보고 어떤 걸 설치해야 할지 고민하고 있을 것이다. 이 글은 검색 이면의 진짜 질문에 답한다: DeepSeek Harness가 실제로 무엇인지, 오늘날 Windows에서 공식적으로 실행하는 방법, 터미널 대안, 그리고 프리뷰 단계 도구를 실행할 때의 솔직한 한계점까지. 이 글은 방법 안내(how-to)이지 출시 알림이 아니다 — 출시와 유출 경위는 별도의 글에서 다룬다.

DeepSeek Harness란 무엇인가 (그리고 무엇이 아닌가)

DeepSeek Harness는 모델이 아니며, 모델을 벤치마킹하지도 않습니다. 이는 에이전트 런타임입니다: 모델을 도구, 파일, 셸, 인터넷에 연결하는 계층으로, 코드를 읽고, 변경 사항을 계획하고, 명령을 실행하며, 작업이 완료될 때까지 반복합니다. 이러한 아키텍처는 태그라인에 명시되어 있습니다: "모든 것이 플러그인입니다." 모델, 도구, 스킬, 세션, 샌드박스, 에이전트 루프 자체, 그리고 웹 UI까지도 시작 시 조합되는 플러그인으로, Koishi 챗봇 생태계의 기반이 되는 동일한 커널인 Cordis 메타 프레임워크 위에 구축됩니다. 기본 배포판에는 150개 이상의 플러그인이 포함됩니다.

또한 이것은 분명히 프리뷰입니다. dsh는 버전 0.1.0-rc.6에 있으며, README는 이를 개발자 프리뷰로 표시하고, 대문자로 "호환성을 깨뜨리는 변경 사항이 있을 것입니다."라고 경고합니다. 그 어떤 것도 채택 속도를 늦추지 못했습니다. 이 프로젝트는 2026-08-13에 공개된 후 처음 12시간 동안 약 50,000개의 GitHub 스타를 달성했으며, 2026-08-16 기준 약 126,000개를 기록했습니다. 이는 DeepSeek가 출시한 오픈소스 릴리스 중 가장 빠른 성장이었습니다.

간단히 답하면, 공식 Windows 경로는 두 가지 명령어입니다.

DeepSeek의 공식 README는 Windows 실행 경로를 한 줄로 안내합니다. Node.js를 설치한 후 다음 명령을 실행하세요: npx @deepseek-ai/dsh web. 구체적인 단계는 다음과 같습니다.

• Node.js 22.19+ 또는 Node 24를 설치하세요. 현재 dsh 릴리스는 Node 22.19 이상이 필요합니다. Windows에서는 Node 24 LTS가 더 안전한 선택이며, 그 이유는 단순합니다. 최신 Node 버전에는 dsh가 압축된 세션 로그를 읽는 데 사용하는 네이티브 zstd 압축 해제가 포함되어 있기 때문입니다. 설치를 확인하려면 node --version 명령을 PowerShell 또는 cmd에서 실행하세요.

• Run the harness. Either run it on the spot with npx @deepseek-ai/dsh web, or install it once with npm install -g @deepseek-ai/dsh and then run dsh web from any folder afterwards. The first run prints the URL and starts the Web UI at http://127.0.0.1:3080.

• 해당 주소를 브라우저에서 여십시오. Web UI는 로컬 웹 앱입니다. 그래서 데스크톱 앱이 없고, 브라우저가 데스크톱 앱입니다.

• 모델 키를 한 번만 추가하세요. 웹 UI에서 설정 → 모델을 열고 DeepSeek API 키를 붙여넣은 후 저장하세요. 서버 재시작 없이 즉시 적용됩니다. dsh는 시작한 폴더를 기본 파일 시스템 위치로 사용하며, UI의 작업 공간 선택 단계에서 모든 프로젝트 디렉터리를 가리킬 수 있습니다.

그것이 공식적인 전체 경로입니다. 머신에 이미 Node 22+가 설치되어 있다면, "아무것도 없는 상태"에서 "에이전트 실행"까지 걸리는 시간은 1분 미만입니다.

왜 모든 "DeepSeek Harness Desktop" 리포지토리는 래퍼인가

이 쿼리에 대한 1페이지 결과는 모두 커뮤니티 데스크톱 래퍼입니다. 즉, Node 런타임을 번들로 포함하고 프레임 창 안에서 공식 웹 UI를 실행하는 Electron, Tauri, WebView2 셸입니다. 이것들은 DeepSeek 제품이 아니며, 하네스 기능을 추가하지 않고 실행기를 추가합니다. 공통점은 다음과 같습니다:

그것들은 더블클릭으로 실행되며 명령줄을 전혀 사용하지 않는데, 이것이 바로 그들의 진짜 강점입니다.

이들은 서명되지 않았으므로 Windows SmartScreen이 설치 시 경고를 표시합니다. "More info → Run anyway"는 해당 절차의 일부입니다.

그들은 공식 프로젝트를 서로 다른 속도로 추적합니다: 일부는 0.1.0-rc.5를 고정하고, 일부는 0.1.0-rc.6을, 일부는 master를 따릅니다. 그래서 wrapper와 harness 버전은 시간이 지남에 따라 서로 어긋나게 됩니다.

• dsh가 항상 사용하는 동일한 로컬 데이터를 ~/.dsh에 저장하므로, 래퍼와 공식 CLI 사이를 전환해도 세션이 재설정되지 않습니다.

래퍼가 언제 가치가 있을까? "아이콘을 더블 클릭하고, 트레이를 보고, 터미널을 건드리지 않는" 것이 결정적 요인일 때이며, 제3자가 이제 프리뷰 단계 도구 앞에서 업데이트 및 보안 계층이 된다는 점을 받아들일 때다. 그렇지 않은 때는 언제인가? 공식 경로는 명령 두 개와 브라우저 탭이다 — 이미 Node가 있다면, 래퍼는 필요하지 않을 수도 있는 실행기를 제공하고, 그 대가로 자체 유지 관리 부담을 추가한다.

터미널 경로: 헤드리스 CLI 및 TUI 플러그인

브라우저가 작업 공간이 아니라면, dsh에는 두 가지 모드로 나뉘는 터미널 스토리도 있습니다.

Headless는 비대화형 프로필입니다: dsh --profile headless "summarize this repository"는 UI 없이 하나의 작업을 실행하고 결과를 출력한 후 종료합니다 — CI 친화적 모드입니다. Windows에서 이것은 또한 스크립트와 예약 작업이 사용해야 하는 모드입니다. 디스플레이나 로그인 세션이 필요 없기 때문입니다.

TUI는 Claude Code 스타일의 대화형 터미널 프론트 도어로, 핵심 패키지에 포함되지 않고 커뮤니티 플러그인 번들로 제공됩니다. dsh-tui 같은 패키지는 dsh plugin --profile tui add <package>로 프로필에 설치하고 dsh --profile tui로 실행합니다. 최소한 하나의 패키지에는 Windows .cmd 런처가 포함되어 있습니다. 시도하기 전에 알아둘 점: TUI는 입력과 출력 모두 실제 터미널이 필요합니다. 설정이 파이프나 리다이렉트를 사용하면 dsh는 거부하고 headless를 사용하라고 안내합니다.

네 가지 프리셋: 어떤 작업에 어떤 것을 쓸까?

dsh는 네 개의 내장 에이전트 프리셋을 제공하며, 이는 난이도 사다리가 아니라 서로 다른 네 가지 도구 표면입니다. 기본값은 ~/.dsh/settings.yaml의 agent-presets.default에서 설정합니다.

• 표준은 기본값입니다: 파일 편집, 셸, 파일 및 웹 검색, 스킬, 하위 에이전트, 계획 수립을 포함한 완전한 일상 에이전트입니다. 대부분의 Windows 사용자가 시작해야 하는 모드입니다.

• PTC(Code mode라고도 함)는 Standard가 가진 모든 기능을 유지하지만, 도구가 노출되는 방식을 변경합니다. 즉, 개별 도구 호출이 길게 이어지는 대신, 모델은 루프, 필터, 조건부 분기 등 다단계 작업을 구성하는 TypeScript 프로그램을 작성합니다. 복잡하거나 반복적이거나 다단계인 워크플로에 적합합니다.

• Minimal 프리셋은 의도적으로 에이전트를 지속형 셸과 파일 편집기라는 두 가지 도구로만 제한하며, 일상 업무가 아닌 평가와 벤치마킹을 목표로 합니다. 이것이 DeepSeek 자체 에이전트 점수가 실행되는 프리셋입니다.

• Creation (Cordis)은(는) 사용자 지정 프리셋을 만들기 위한 도구입니다. 런타임 검사, 인메모리 플러그인 실험, 프리셋 작성 안내가 포함되어 있습니다. 하네스 자체를 실험해 보기 위한 것입니다.

MCP와 궤적 재생: 이것을 굳이 실행할 가치가 있는 이유

dsh를 일반 채팅 클라이언트 대신 사용해야 하는 이유는 두 가지 기능 때문입니다. 첫째, Model Context Protocol (MCP) 클라이언트가 내장되어 있습니다. /mcp 명령어와 Settings MCP 탭을 통해 외부 MCP 서버를 하네스에 연결하므로, 다른 에이전트가 사용하는 것과 동일한 도구를 dsh에 연결할 수 있습니다. 둘째, 모든 실행은 추가 전용(append-only) 세션 로그에 기록되며, Trajectory 뷰에서 실행을 출처별로 검사하고, 재개하고, 포크하고, 검색하고, 재생할 수 있습니다. 이것이 에이전트를 디버깅할 때 최종 답변만 바라보는 것과 각 호출을 수행한 이유를 단계별로 살펴보는 것의 차이입니다.

공식적인 길이 틀린 답일 때

• 원클릭, 터미널 없는 방식이 필요합니다. 공식 설치 프로그램은 없습니다. 더블 클릭이 필수 조건이라면 커뮤니티 래퍼를 사용하게 되는데, 이는 서명되지 않은 것이므로 편리함과 서드파티 유지보수 부담 사이에서 저울질해야 합니다.

• 사용자의 Windows 컴퓨터가 오래되었거나 잠겨 있습니다. dsh에는 Node 22.19+(또는 Node 24)가 필요합니다. 관리되는 컴퓨터에서는 런타임 설치가 필요하며, 승인을 받지 못할 수도 있습니다.

• 프리뷰 버전이며, 깨질 수 있습니다. 0.1.0-rc.6은 곧 호환되지 않는 변경이 있을 것이라는 경고를 포함합니다. rc 빌드 사이에 플러그인과 프로필이 작동을 멈출 수 있습니다. 스크립트로 처리하는 모든 작업에는 버전을 고정하세요.

• 모델 비용은 당신이 부담합니다.dsh는 무료입니다. 모든 작업은 설정한 키로 토큰을 소모합니다. 에이전트 루프는 파일을 다시 읽고 재시도하며, 어려운 작업에서 장황한 모델은 오후 한나절에 놀라운 예산을 소모할 수 있습니다. 바로 이 지점에서 하네스 선택이 아니라 모델 선택이 비용을 좌우합니다.

• 정액제 구독이 토큰별 라우팅보다 더 나을 수 있습니다. 한 랩의 플랜 한도 내에서 이용한다면, 정액제 구독은 토큰별 경로보다 대개 더 저렴합니다. 라우팅은 모델을 혼합하거나 장애 조치가 필요할 때 유리합니다 — 기본적으로는 그렇지 않습니다.

하네스 뒤로 모델을 라우팅하세요.

기본 경로는 DeepSeek 자체 API입니다. Settings → Models에서 키를 붙여넣기만 하면 됩니다. 하지만 dsh는 OpenAI 호환 base URL도 허용합니다. 환경 변수에 DEEPSEEK_BASE_URL을 설정하거나 settings.yaml에서 LLM 공급자를 구성하면 되는데, 이는 하네스를 건드리지 않고도 하네스 뒤의 모델을 교체할 수 있다는 뜻입니다. 동일한 로컬 dsh 설치에서 복잡한 리팩터링에는 DeepSeek V4 Pro를, 저비용 기계적 편집에는 DeepSeek V4 Flash를 실행할 수 있습니다.

OrcaRouter가 차지하는 레이어가 바로 그것입니다. OpenAI 호환 기본 URL 하나, 200개 이상의 모델, 마크업 제로 — 공급업체 리스트 가격을 그대로 통과시키며 — 공급업체가 속도 제한을 걸거나 성능이 저하되면 자동으로 장애 조치(failover)됩니다. dsh를 거기에 연결하면 하네스는 사용자 머신에 그대로 남고, 모델 카탈로그는 구매가 아닌 라우팅 결정이 됩니다. 솔직히 인정할 두 가지가 있습니다: 우리는 dsh를 호스팅하지 않으며 — dsh는 사용자의 Windows 환경에서 로컬로 실행됩니다 — DeepSeek 자체 API 너머의 모델이 필요하다면 우리는 단지 모델 액세스 레이어일 뿐입니다. 그리고 플랜 상한 내에서 단일 대용량 모델을 사용하는 경우, 라우터와 무관하게 정액제 구독이 더 저렴한 선택인 경우가 많습니다.

간략 버전

Windows에서 DeepSeek Harness는 앱스토어 설치가 아닌 {{1}}명령어 두 개로 설정하는 방식{{/1}}입니다: {{2}}Node 22.19+ (또는 Node 24) 설치, 이어서 npx @deepseek-ai/dsh web 실행, 마지막으로 브라우저에서 http://127.0.0.1:3080에 접속{{/2}}. GitHub의 {{3}}"desktop"{{/3}} 저장소들은 동일한 로컬 서버를 감싸는 비공식 래퍼입니다. 터미널에서는 {{4}}헤드리스(headless){{/4}} 모드가 CI용 일회성 작업을 실행하고, {{5}}TUI{{/5}} 플러그인은 Claude Code 스타일의 인터페이스를 제공합니다. 네 가지 프리셋({{6}}Standard, PTC, Minimal, Creation{{/6}})이 도구 구성을 결정하며, {{7}}MCP{{/7}}와 {{8}}궤적 재생(trajectory replay){{/8}}이 이 도구를 실질적으로 유용하게 만듭니다. 이 도구는 {{9}}무료, 오픈소스, 프리뷰 단계{{/9}}입니다. 버전을 고정하고, 모델 비용을 모니터링하며, 모델을 하네스와 별도로 라우팅하세요.