DeepSeek Harness 사용법: 설치, 설정, 첫 에이전트 실행까지
명령어 하나로 끝내는 답: Node.js가 설치되어 있다면, 아래 명령으로 DeepSeek Harness를 웹 UI와 함께 시작할 수 있습니다.
npx @deepseek-ai/dsh web서버는 http://127.0.0.1:3080에서 시작되고 브라우저가 자동으로 열립니다. 그다음은 Settings → Models에서 API 키를 붙여넣고, Choose workspace로 프로젝트 폴더를 지정한 뒤, 첫 작업을 시키면 됩니다. 전체 루프는 이게 전부입니다. 이 가이드의 나머지는 각 단계를 좀 더 자세히, 그리고 네 가지 런타임 모드와 플러그인 생태계를 다룹니다 — 사실 이 프로젝트가 공개 2주 만에 GitHub 스타 196k를 넘긴 진짜 이유는 플러그인 쪽에 있습니다.
이 가이드의 모든 명령어와 설정은 2026년 8월 26일 기준으로 확인한 공식 README, deepseek.com/harness, 개발자 문서에서 가져온 것입니다. DeepSeek Harness는 developer preview 단계이며, 팀 스스로 breaking change가 계속 발생할 것이라고 명시적으로 경고하고 있습니다 — 아래 내용이 실제와 맞지 않게 되면 이 글을 포함한 어떤 튜토리얼보다 저장소 README (opens in a new tab)를 신뢰하세요.
DeepSeek Harness는 정확히 무엇인가
DeepSeek Harness(dsh)는 2026년 8월 13일 MIT 라이선스로 공개된 DeepSeek의 오픈소스 에이전트 프레임워크입니다. 설계 슬로건은 "Everything is a Plugin"이고, 이건 말 그대로의 의미입니다. 모델, 도구, 스킬, 세션, 샌드박스, 스토리지, 에이전트 루프, 스케줄링, 심지어 UI까지 전부 오픈소스 플러그인 런타임인 Cordis (opens in a new tab) 위에서 돌아가는 플러그인입니다. 프레임워크 소스를 건드리지 않고 설정만으로 이 중 무엇이든 교체하거나 재조합할 수 있습니다.
이 아키텍처에서 두 가지 실용적인 결론이 따라옵니다.
- 기본 상태로도 코딩 에이전트입니다 — 파일 편집, 셸, 검색, 워크플로 플래닝이 기본(Standard) 모드에 포함되어 있어서, Claude Code나 OpenCode를 쓰듯이 그대로 쓸 수 있습니다.
- 동시에 나만의 에이전트를 만드는 섀시이기도 합니다 — 다른 샌드박스, 다른 모델 라우터, 다른 루프가 필요하면 애플리케이션을 포크하는 대신 해당 플러그인 하나만 교체하면 됩니다.
모델이 본 모든 것은 append-only 세션 로그에 기록됩니다. 시스템 프롬프트, 추론 과정, 도구 호출과 결과, 서브에이전트 스케줄링, 모든 컨텍스트 주입까지 전부입니다. 이상하게 동작한 에이전트를 디버깅하려는데 정작 그 에이전트가 무엇을 봤는지에 대한 기록이 없어서 막막했던 경험이 있다면, 이 기능 하나만으로도 이 프로젝트가 초기에 빠르게 주목받은 이유를 상당 부분 설명할 수 있습니다.
- DeepSeek Harness 사용법: 설치, 설정, 첫 에이전트 실행까지
- Runcell Science: Claude Science를 대체할 오픈소스 AI 연구 워크스페이스
- 맥 잠자기 방지: 맥북 닫아도 Codex와 Claude Code 계속 실행하기
- OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot: 2026년에 어떤 AI 에이전트 스택을 선택해야 할까?
- Claude Code로 Jupyter 노트북을 분석하는 방법 | Data Science 실무 가이드와 한계
- Claude Code 루틴 사용법: AI 에이전트 cron 작업과 자동 트리거
- Claude Code Desktop에서 Bypass permissions 켜는 법
- Google의 A2A 프로토콜을 사용한 두 개의 Python 에이전트 빌드하기 - 단계별 튜토리얼
- 2025년 파이썬에서 가장 성장하는 상위 10개 데이터 시각화 라이브러리
1단계 — 설치
사전 조건: Node.js. 공식 퀵스타트는 PATH에 node/npx가 동작하는 것 외에는 아무것도 전제하지 않습니다.
방법 A — npm(처음 써본다면 이쪽을 권장):
npx @deepseek-ai/dsh webnpx는 첫 실행 때 패키지를 내려받기 때문에, 첫 기동은 이후보다 눈에 띄게 오래 걸립니다. 브라우저 창 없이 서버만 띄우고 싶다면(예: 원격 머신) --no-open을 붙이세요.
npx @deepseek-ai/dsh web --no-open방법 B — 소스에서 빌드(플러그인을 만들거나 main 브랜치를 추적하려면):
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web어느 쪽을 골라야 할까요?
| 상황 | 선택 | 이유 |
|---|---|---|
| 한번 써보기, 일반적인 사용 | npx | 설정이 전혀 필요 없고 항상 배포된 빌드를 받아옴 |
| 플러그인 작성 또는 수정 | 소스 | 개발 대상이 되는 워크스페이스가 필요함 |
| breaking change 대비 버전 고정 | npx @deepseek-ai/dsh@<version> | developer preview는 변화가 빠름. 버전을 고정해야 동작하던 환경이 계속 동작함 |
| 벤치마크 / CI | 소스 + Minimal 모드 | 재현 가능한 빌드에 도구 두 개짜리 최소 런타임(아래 모드 설명 참고)을 조합 |
2단계 — 모델 연결하기
웹 UI는 모델이 하나도 설정되지 않은 상태로 시작합니다. 실제로 쓸 수 있게 만들려면:
- Settings → Models를 엽니다.
- platform.deepseek.com (opens in a new tab)에서 발급받은 자격 증명을 붙여넣습니다(또는 지원되는 다른 프로바이더 — 모델 설정 페이지에서 대체 프로바이더를 다룹니다).
- 저장합니다. 공식 문서에 따르면 서버를 재시작하지 않아도 모델 경로가 즉시 사용 가능해집니다.
다른 모든 것과 마찬가지로 모델도 플러그인이기 때문에, 프로바이더 선택은 설치 시점의 결정이 아니라 설정상의 결정입니다. 지금은 한 벤더로 표준화하되 나중에 경로를 바꿀 여지를 남겨두고 싶은 팀이라면 이 점이 중요합니다 — harness 아키텍처의 핵심은 경로 변경이 설정 편집 한 번으로 끝난다는 것입니다.
3단계 — 워크스페이스 지정하고 첫 작업 실행하기
- 웹 UI에서 Choose workspace를 클릭하고 프로젝트 디렉터리를 추가합니다.
- 세션을 시작합니다.
- 무언가를 수정하게 두기 전에, 먼저 읽기 전용 작업을 시켜보세요. 공식 퀵스타트가 제안하는 예시가 적당합니다.
"Summarize this repository and identify its main packages"
이 에이전트는 파일 조작, 명령 실행, 작업 위임, 워크플로 플래닝을 지원하며, 실행 전에 승인 프롬프트를 띄웁니다. 첫 세션은 캘리브레이션 런이라고 생각하세요. 파괴적인 권한을 주기 전에, 에이전트가 올바른 워크스페이스를 읽고 있는지, 승인 프롬프트가 제대로 뜨는지, 세션 로그가 일어난 일을 제대로 기록하는지를 확인하는 단계입니다. 이건 모든 터미널 에이전트에 대해 저희가 권하는 것과 동일한 원칙입니다(Codex에서의 같은 절차는 Codex 사용법을 참고하세요).
네 가지 런타임 모드, 그리고 각각이 맞는 상황
DeepSeek Harness에는 네 개의 런타임 프리셋이 있습니다. 대부분의 튜토리얼이 건너뛰는 결정이 바로 이 표입니다.
| 모드 | 무엇인가 | 언제 쓰나 |
|---|---|---|
| Standard | 완전한 코딩 에이전트: 파일 편집, 셸, 검색, 워크플로 | 기본값. 일상적인 코딩 에이전트 작업 |
| Code | Standard에 더해, 다단계 작업을 위한 모델 생성 TypeScript 오케스트레이션 | 도구 호출을 하나씩 쌓는 대신 모델이 작업을 프로그래밍적으로 조합하길 원하는 긴 다단계 리팩터링이나 파이프라인 |
| Minimal | 도구는 단 두 개: bash와 editor | 모델을 공정하게 벤치마크하거나, 플러그인 노이즈 없이 버그를 재현할 때 |
| Creator | 런타임 인스펙션과 플러그인 실험 기능 추가 | 플러그인 개발, 런타임이 실제로 무엇을 하는지 들여다볼 때 |
쓸모 있는 멘탈 모델 하나: Standard는 에이전트를 쓰기 위한 것, Creator는 에이전트를 바꾸기 위한 것, Minimal은 모델을 측정하기 위한 것. DeepSeek 모델이 내 워크로드에 충분히 좋은지 평가하는 중이라면 Minimal 모드가 정직한 테스트 방법입니다 — harness가 거들어주기를 멈추고 모델 그 자체가 드러납니다.
플러그인: 진짜 레버리지가 있는 곳
플러그인 생태계는 저희가 추적해온 어떤 비슷한 에이전트 프레임워크보다도 빠르게 성장하고 있습니다. 2026년 8월 26일 기준으로 GitHub의 dsh-plugin 토픽 (opens in a new tab)에는 11,944개의 공개 저장소가 올라와 있습니다 — 공개 2주 만입니다.
현재 스타 수 기준으로, 알아둘 만한 스타터 팩입니다.
| 플러그인 | 스타 | 하는 일 |
|---|---|---|
| awesome-dsh-plugin (opens in a new tab) | 12.8k | 큐레이션된 인덱스 — 생태계를 둘러보려면 여기서 시작 |
| open-design | 91.6k | AI 디자인: 프로토타이핑, 랜딩 페이지, 대시보드, HTML/PDF/PPTX 내보내기 |
| ruflo | 69.4k | 적응형 메모리와 RAG를 갖춘 멀티 에이전트 스웜 조율 |
| DeepSeek-Reasonix | 35.2k | DeepSeek 모델에 맞춰 튜닝된 터미널 기반 코딩 에이전트 |
| OpenViking | 33.4k | 자기 진화형 컨텍스트 데이터베이스: 에이전트 메모리, 지식, 스킬 |
| distilly | 24k | 전문 지식을 재사용 가능한 에이전트 스킬로 변환 |
| WeKnora | 20.7k | 문서 → 질의 가능한 RAG 지식 베이스 |
| dsh-desktop | 20.4k | DSH 생태계용 데스크톱 앱 |
탐색 규칙: 플러그인은 GitHub에서 스스로 dsh-plugin 토픽을 붙이기 때문에, 지금으로서는 그 토픽 페이지가 사실상 패키지 인덱스에 가장 가깝습니다. 변동이 심할 거라고 예상하세요 — 생긴 지 2주 된 생태계에서 스타 수는 성숙도가 아니라 관심도를 측정할 뿐입니다. 중요한 곳에 연결하기 전에 해당 플러그인이 실제로 활발히 관리되고 있는지 이슈를 먼저 확인하세요.
공식 문서가 아직 다루지 않는 것들(솔직한 공백)
이건 developer preview이고, 문서는 군데군데 얇습니다. 이 글을 쓰는 시점 기준으로:
- 퀵스타트 페이지는 설치를 README로 넘깁니다 — 여기의 단계와 문서의 단계가 다르면 README가 정답입니다.
- 설정 파일 포맷이 충분히 문서화되어 있지 않습니다. 모델 설정은 웹 UI(Settings → Models)를 통해 이뤄집니다. 파일 기반의 재현 가능한 설정이 필요하다면 플러그인 소스나 CLI 모드용
apps/cliREADME를 직접 읽어야 할 겁니다. - harness 자체에는 가격 페이지가 없습니다 — 프레임워크는 MIT이고 무료입니다. 비용은 연결한 모델 API(DeepSeek 플랫폼 가격이든 다른 프로바이더든)에서만 발생합니다.
- breaking change는 가능성이 아니라 예고된 사실입니다. 이번 달에 오래 쓸 무언가를 이 위에 만든다면 버전을 고정하세요.
이 가이드에는 트러블슈팅 표를 일부러 넣지 않았습니다. 나온 지 2주 된 프리뷰의 실패 양상은 매주 바뀌고, 튜토리얼에서 낡은 에러 해결법을 복사해오는 건 예방하는 것보다 더 큰 피해를 만듭니다(OpenCode 생태계가 이미 겪은 교훈입니다). 에러를 만났을 때 쓸모 있는 경로는 저장소의 GitHub Discussions와 프로젝트 Discord입니다.
지금의 에이전트 지형에서 DeepSeek Harness의 위치
이걸 쓰기로 확정하기보다 여러 에이전트 중에 고르는 중이라면, 짧게 정리하면 이렇습니다.
- DeepSeek Harness는 재조합 가능성에 최적화되어 있습니다 — 어떤 부분이든 교체하고, 모든 걸 들여다볼 수 있고, MIT 라이선스 섀시입니다.
- Claude Code / Codex류 제품은 완성도 높고 의견이 뚜렷한 엔드투엔드 경험에 최적화되어 있습니다. 그 영역은 2026년 AI 코딩 도구 총정리에서 다루고, 더 넓은 시장은 Best Vibe Coding Tools에서 다룹니다.
- Hermes Agent 같은 런타임 중심 프레임워크는 "런타임을 직접 소유한다"는 비슷한 영역에 있습니다 — Hermes Agent vs OpenClaw의 아키텍처 비교가 여기에도 거의 그대로 적용되며, dsh는 확실히 런타임 쪽에 서 있습니다.
- DeepSeek이라는 회사와 그 모델들에 대한 배경은 DeepSeek vs 다른 중국 LLM을 참고하세요.
한 가지 짚어둘 경계가 있습니다. DeepSeek Harness는 범용 코딩 에이전트입니다. 일상 업무가 저장소가 아니라 Jupyter 노트북과 데이터프레임이라면, 저장소용 에이전트를 .ipynb JSON에 들이대는 것보다 커널 상태를 직접 다루는 notebook 네이티브 에이전트가 더 잘 맞습니다 — RunCell (opens in a new tab)이 바로 그 문제를 위해 만들어졌고, repo 에이전트와 notebook 에이전트의 차이는 Jupyter AI RunCell에서 다룹니다.
FAQ
Related Guides
- Codex 사용법
- Oh My OpenCode와 OpenCode: 설치, 설정, 문제 해결
- 2026년 최고의 AI 코딩 도구
- 최고의 Vibe Coding 도구
- Hermes Agent vs OpenClaw
- DeepSeek vs 다른 중국 LLM