DeepSeek Harness 튜토리얼: 가장 인기 있는 오픈 소스 AI 에이전트 시작하기

플러그인 지원, 웹 검색, 비전, DeepSeek 모델, Gemini, ModLens, 서드파티 모델, 에이전틱 워크플로를 갖춘 오픈 소스 AI 코딩 에이전트 DeepSeek Harness의 설정과 테스트 방법을 알아보세요.

업데이트됨 2026년 8월 20일 · 10분 읽다

AI로 탐색하기

ChatGPT Claude Perplexity

DeepSeek Harness는 현재 가장 많이 회자되는 오픈 소스 AI 에이전트 중 하나이며, 대부분의 코딩 도우미와는 매우 다른 접근을 취합니다. 바로 모든 것이 플러그인이라는 점이죠.

이 가이드에서는 처음부터 DeepSeek Harness를 설정하고, 메인 모델로 DeepSeek, 최신 정보용 DeepSeek 내장 웹 검색, 이미지 이해를 위한 Gemini와 ModLens를 사용해 실용적인 에이전트 환경을 구축하겠습니다. 그런 다음 Harness Web UI를 실행하여 코딩, 웹 검색, 비전, 서드파티 모델 기능을 테스트해 보겠습니다.

에이전트가 어떻게 계획하고, 도구를 호출하며, 스스로 행동하는지 처음이라면, AI Agent Fundamentals 스킬 트랙에서 핵심 개념을 먼저 학습해 보세요.

DeepSeek Harness란?

DeepSeek Harness는 DeepSeek AI가 개발한 오픈 소스 AI 에이전트 프레임워크로, 에이전트 동작을 더 세밀하게 제어하고 싶은 개발자를 위해 설계되었습니다.

사용자를 고정된 코딩 도우미나 워크플로에 가두는 대신, Harness는 “모든 것이 플러그인”이라는 접근을 따릅니다. 모델, 도구, 인터페이스, 에이전트 행동 모두 원하는 방식에 따라 추가, 제거, 교체할 수 있습니다.

이 용어가 정확히 무엇을 의미하는지 아직 확신이 서지 않는다면, “에이전트 하니스란 무엇인가?”라는 질문에 답하는 우리의 가이드를 읽어 보시길 권합니다.

DeepSeek Harness가 인기인 이유

DeepSeek Harness는 매우 빠르게 주목을 받았고, 이 글을 게시하는 시점 기준 GitHub 스타 160,000개 이상과 포크 18,000개를 기록했습니다.

큰 이유 중 하나는 개발자들이 DeepSeek뿐 아니라 다양한 모델에서 강력한 결과를 얻을 수 있다고 평가하기 때문입니다. 특히 코딩 및 장기 에이전트 작업에서 Qwen3.8-27b 같은 모델을 성공적으로 사용하는 사례가 Reddit에서 자주 공유됩니다.

또 다른 이유는 자율성과 유연성입니다. 사용자들은 Harness가 다단계 작업을 계속 수행하고, 오류에서 복구하며, 긴 컨텍스트를 관리하고, 지속적인 개입 없이도 진행할 수 있다고 보고합니다. 플러그인 기반 설계 덕분에 모델을 교체하고, 도구를 추가하며, 하나의 고정된 구성에 묶이지 않고 에이전트 워크플로를 쉽게 커스터마이즈할 수 있습니다.

만약 경쟁 도구들과 비교 중이라면, Claude Code 대안 가이드에서 주요 7가지 옵션을 나란히 비교해 보세요.

DeepSeek Harness의 주요 기능

주요 기능은 다음과 같습니다.

플러그인 기반 아키텍처: 에이전트의 대부분을 플러그인으로 확장하거나 교체할 수 있어 구성을 쉽게 맞춤화할 수 있습니다.
로컬 Web UI: dsh web을 실행하면 브라우저 기반 인터페이스에서 모델, 세션, 워크스페이스, 설정, 에이전트를 관리할 수 있습니다.
Python SDK: deepseek-harness-sdk를 통해 Python 애플리케이션, 스크립트, 테스트, 자동화 워크플로에서 직접 Harness 에이전트를 실행할 수 있습니다.
다양한 모델 제공자: DeepSeek 모델로 제한되지 않습니다. OpenAI, Anthropic 같은 제공자를 사용할 수 있고, 호환 엔드포인트를 직접 연결할 수도 있습니다.
툴 호출: 에이전트가 텍스트 생성뿐 아니라 도구를 호출해 작업을 수행할 수 있습니다.
파일 및 터미널 도구: 파일 읽기, 검색, 편집 도구와 함께 Linux/macOS용 Bash, Windows용 PowerShell을 제공합니다.
내장 웹 검색: DeepSeek의 웹 검색 제공자가 기본 구성에 포함되어 있으며 모델과 동일한 DeepSeek API 키를 사용합니다.
코드 모드: 코드 기반 실행 모드를 통해 도구를 노출하여, 에이전트가 도구 호출의 결합과 실행을 더 세밀하게 제어할 수 있습니다.
Trajectory: Trajectory 보기에서 모델 응답, 도구 호출, 중첩 도구 활동, 타이밍, 토큰 사용량 등 에이전트의 단계를 단계별로 점검할 수 있습니다.
에이전트 프리셋: 각기 다른 도구와 프롬프트를 갖춘 에이전트를 만들어 여러 세션에서 사용할 수 있습니다.
세션 통계: 턴 수, 스텝 수, 모델 시간, 도구 시간, 첫 토큰까지의 시간, 디코딩 시간 등 유용한 정보를 추적합니다.
서브에이전트: 메인 에이전트가 작업의 일부를 하위 에이전트에 위임할 수 있어 복잡한 워크플로에 유용합니다.
커뮤니티 플러그인: 서드파티 플러그인을 통해 기본 모델에 없는 기능을 추가할 수 있습니다. 본 가이드에서는 ModLens로 비전 지원을 추가했습니다.
MIT 라이선스: DeepSeek Harness는 오픈 소스이며 관대한 MIT 라이선스로 배포됩니다.

핵심 장점은 단 하나의 모델, 하나의 도구 세트, 하나의 에이전트 유형에 묶이지 않는다는 것입니다. 기본 구성에서 시작해 다양한 워크플로를 실험하며 구성 요소를 점진적으로 추가하거나 교체할 수 있습니다.

DeepSeek Harness는 어떻게 설정하나요?

먼저 DeepSeek Harness를 설치하고, 가이드의 나머지에 필요한 모든 것을 준비하겠습니다. Node.js, DeepSeek Harness, pnpm을 설치한 뒤 API 키를 추가하겠습니다.

Node.js 설치

DeepSeek Harness는 Node.js 위에서 실행됩니다. 이후 비전 기능에 ModLens를 사용할 예정이므로 Node.js 22.19 이상을 권장합니다.

Ubuntu 또는 Debian에서는 다음으로 Node.js를 설치할 수 있습니다.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

설치가 끝나면 Node.js와 npm이 동작하는지 확인하세요:

node --version
npm --version

제 환경에서는 다음과 같이 표시되었습니다:

v24.19.0
11.17.0

정확히 같은 버전일 필요는 없습니다. 최신 버전의 Node.js를 사용 중이라면 문제없이 진행할 수 있습니다.

DeepSeek Harness 설치

이제 DeepSeek Harness 자체를 설치하겠습니다.

공식 빠른 시작은 npx 사용을 권장하지만, 이 가이드 전반에서 dsh 명령을 간편하게 쓰기 위해 전역 설치를 선호합니다.

다음을 실행하세요:

npm install -g @deepseek-ai/dsh

설치가 올바르게 되었는지 확인합니다:

dsh --version

이 가이드를 테스트했을 당시 사용한 버전은 다음과 같았습니다:

0.1.0-rc.7

pnpm 설치

pnpm도 필요합니다. DeepSeek Harness는 플러그인을 추가/제거할 때 이를 사용합니다. 전역으로 설치하세요:

npm install -g pnpm

API 키 설정

이 튜토리얼에는 API 키가 두 개만 필요합니다:

DeepSeek API 키: DeepSeek 모델과 내장 웹 검색에 사용됩니다.
Gemini API 키: ModLens가 이미지 이해에 사용합니다.

코딩과 웹 검색에는 DeepSeek 키만 있으면 되므로 지금 설정하고, ModLens로 비전을 추가할 때 Gemini 키를 나중에 추가하겠습니다.

DeepSeek을 사용하려면 DeepSeek 계정을 만들고, API 키를 생성하고, 계정에 크레딧을 추가해야 합니다. 본 가이드의 예시를 테스트하는 데에는 $2 정도면 충분하므로, 처음부터 큰 금액을 추가할 필요는 없습니다.

API 키를 받았으면 환경 변수에 추가하세요.

Linux 또는 macOS:

export DEEPSEEK_API_KEY="your_deepseek_api_key"

Windows PowerShell:

$env:DEEPSEEK_API_KEY="your_deepseek_api_key"

이 구성의 장점 중 하나는 별도의 웹 검색 API가 필요 없다는 점입니다. DeepSeek Harness에는 이미 DeepSeek의 웹 검색 제공자가 포함되어 있으며 동일한 DEEPSEEK_API_KEY를 사용합니다.

또한 Web UI 내부의 Settings → Models에서 나중에 DeepSeek API 키를 추가할 수도 있습니다.

DeepSeek Harness는 어떻게 시작하나요?

이제 구성이 끝났으니 DeepSeek Harness를 시작하고 Web UI를 열어봅시다. 기본적으로 포트 3080에서 브라우저 인터페이스를 시작하는 dsh web만 실행하면 됩니다.

브라우저에서 http://127.0.0.1:3080 주소를 열면 UI를 볼 수 있습니다.

여기에서 새 워크스페이스를 만들거나 기존 워크스페이스를 선택하고, 새 세션을 시작한 뒤 사용할 DeepSeek 모델을 선택하세요.

세션이 준비되면 코딩, 웹 검색, 비전, 서드파티 모델 지원을 테스트할 수 있습니다.

코딩에 DeepSeek Harness 사용하기

이제 DeepSeek Harness가 실행 중이므로 구성의 주요 기능을 테스트해 보겠습니다. 간단한 코딩 작업부터 시작하죠:

Create a simple Python calculator with a command-line interface.

DeepSeek Harness는 파일과 터미널을 직접 다룰 수 있어, Python 파일을 생성하고 코드를 편집하며 워크스페이스 내에서 명령을 실행할 수 있습니다.

작업이 완료되면 생성된 파일과 실행 방법 안내를 확인할 수 있습니다.

Harness에 구동되는 DeepSeek 모델을 더 잘 활용하려면, DeepSeek V4 API 튜토리얼에서 V4 추론 모드와 Python API 파라미터를 살펴보세요.

웹 검색에 DeepSeek Harness 사용하기

다음으로 웹 검색을 테스트해 봅시다. DeepSeek Harness에는 이미 DeepSeek의 웹 검색 제공자가 포함되어 있으므로 추가 설정이 필요 없습니다.

다음과 같은 프롬프트를 시도해 보세요:

Search the web for the latest open-source AI model releases and summarize the top three as of August 18, 2026.

에이전트가 웹을 검색한 뒤 출처를 포함한 요약을 반환할 것입니다.

작동 중일 때 Trajectory 탭을 열어 보세요. SUBTOOL: web_search 같은 도구 호출을 확인할 수 있습니다.

이는 에이전트가 모델의 기존 지식에만 의존하지 않고 실제로 웹 검색 도구를 사용하고 있음을 보여줍니다. 기본적으로 이 검색은 deepseek-official 제공자가 처리하며, 앞서 구성한 DEEPSEEK_API_KEY를 그대로 사용합니다.

비전 작업에 DeepSeek 사용하기

Harness의 DeepSeek 채팅 모델은 텍스트 전용이라 업로드한 이미지를 자체적으로 이해하지는 못합니다. 비전 지원을 추가하려면 ModLens를 사용합니다. 이는 DeepSeek과 비전 모델 사이의 브리지 역할을 합니다.

ModLens 플러그인 설치

이미지를 업로드하면 ModLens가 비전 모델로 이미지를 처리하고 유용한 시각 정보를 추출한 뒤, 그 정보를 DeepSeek으로 전달하여 이미지에 대해 추론할 수 있게 합니다.

먼저 web 프로필에 ModLens 플러그인을 설치합니다:

dsh plugin --profile web add @liustack/modlens@3.20.0

설치가 완료되면 ModLens는 modlens_read_image 도구를 추가하고, ``DeepSeek-V4-Flash (modlens vision)` 같은 모델 옵션을 생성합니다.

이러한 모델 변형을 통해 DeepSeek을 주요 추론 모델로 유지하면서 이미지를 업로드할 수 있습니다.

비전 백엔드 등록

본 가이드에서는 Gemini API를 비전 백엔드로 사용하므로 Gemini API 키가 필요합니다. Gemini API Free Tier로 시작할 수 있습니다. Google은 Free Tier 한도 내에서 지원되는 Gemini 모델에 대한 무료 액세스를 제공하므로, 본 가이드의 비전 구성을 테스트하기 위해 결제 정보를 추가할 필요는 없습니다.

키를 발급받았다면 환경 변수에 추가하세요.

Linux 또는 macOS:

export GEMINI_API_KEY="your_gemini_api_key"

Windows PowerShell:

$env:GEMINI_API_KEY="your_gemini_api_key"

ModLens CLI 설치 및 구성

다음으로 ModLens CLI를 설치합니다:

npm install -g @liustack/modlens

그런 다음 Gemini API 키로 구성합니다.

Linux 또는 macOS:

modlens config set gemini-api.apiKey "$GEMINI_API_KEY"
modlens config set provider gemini-api

Windows PowerShell:

modlens config set gemini-api.apiKey "$env:GEMINI_API_KEY"
modlens config set provider gemini-api

마지막으로 정상 동작을 확인합니다:

modlens doctor

gemini-api가 제공자로 선택되어 있고 준비 완료 상태로 표시되어야 합니다.

ModLens와 함께 DeepSeek Harness 테스트

이제 이미지 이해를 테스트해 봅시다.

모델 선택기에서 이름에 (modlens vision)이 포함된 모델 중 하나를 선택하세요. 예: DeepSeek-V4-Flash (modlens vision).

이미지를 붙여 넣거나 업로드한 뒤 다음과 같이 물어보세요: Explain what is shown in this image.

위 예시처럼 이제 DeepSeek이 업로드한 이미지를 설명하고 이에 대해 추론할 수 있습니다.

백그라운드에서는 ModLens가 이미지를 Gemini로 보내 시각적 이해를 수행하고, 추출된 정보를 DeepSeek에 전달합니다. 즉, 비전 부분에만 Gemini를 사용하면서도 주요 추론 모델은 계속 DeepSeek으로 둘 수 있습니다.

서드파티 모델과 함께 DeepSeek Harness 사용하기

마지막으로 다른 제공자의 모델을 시도해 보겠습니다. Settings → Models를 엽니다.

여기에서 OpenAI와 Anthropic 같은 제공자를 추가하거나, 본인의 API 자격 증명으로 지원되는 다른 모델 제공자를 구성할 수 있습니다.

셀프 호스팅 모델이나 다른 호환 엔드포인트를 연결하고 싶다면 커스텀 제공자를 추가할 수도 있습니다. 이때 제공자 ID, 기본 URL, API 유형, 자격 증명, 모델 이름 등의 세부 정보를 구성할 수 있습니다.

제공자를 추가했다면 세션으로 돌아가 모델 선택기에서 새 모델을 선택하세요.

예를 들어 다음 프롬프트를 시도해 보세요:

Create a Python command-line to-do app that lets users add, list, complete, and delete tasks, with tasks saved locally in a JSON file.

위 예시는 서드파티 Kimi-K3 모델을 사용해 코딩 작업을 완료한 것으로, DeepSeek Harness가 DeepSeek 모델에만 국한되지 않음을 보여줍니다.

구성된 모델 간 전환은 모델 선택기에서 바로 할 수 있으며, Harness 서버를 재시작하지 않아도 다음 요청부터 적용됩니다.

마무리 생각

DeepSeek Harness를 테스트해 본 결과, 개인 워크플로에서는 여전히 Pi Coding Agent와 OpenCode를 선호합니다.

DeepSeek Harness는 플러그인 기반 생태계를 중심으로 구축되었다는 점에서 Pi Coding Agent와 매우 유사합니다. 필요에 따라 다양한 확장 기능을 설치해 코딩 에이전트의 역량을 보강할 수 있습니다. 그 유연성은 유용하지만, 제 테스트에서는 DeepSeek Harness를 둘러싼 과열된 관심을 완전히 납득하긴 어려웠습니다. 전반적인 경험은 이미 사용해 온 다른 코딩 에이전트와 비교했을 때 상당히 평범하게 느껴졌습니다.

몇 가지 답답한 문제도 겪었습니다. 때로는 에이전트가 이유를 알 수 없이 작업 중간에 멈추기도 했고, 다시 진행하려면 continue를 입력해야 했습니다. 플러그인 설치 및 구성도 또 다른 난관이었습니다. 이미 정확히 무엇을 해야 하는지 알고 있지 않다면 꽤 어렵고, 현재 문서화도 크게 도움이 되지 않습니다.

그럼에도 DeepSeek Harness는 아직 매우 초기 단계의 제품이므로 이러한 문제는 이해할 만합니다. 시간이 지나면서 경험, 문서, 플러그인 생태계가 크게 개선될 것으로 기대합니다. DeepSeek이 자사 모델과 특히 잘 맞는 하니스를 구축하고 있을 가능성도 있으며, 그것이 기대감을 높이는 이유 중 하나일 수 있습니다.

DeepSeek Harness란 무엇인가요?

DeepSeek Harness(dsh)는 DeepSeek AI가 공개한 MIT 라이선스의 오픈 소스 에이전트 프레임워크로, "모든 것이 플러그인"이라는 아이디어에 기반합니다. 모델, 도구, 인터페이스, 심지어 에이전트 루프까지 교체하거나 바꿔 끼울 수 있습니다. 브라우저 기반 Web UI와 헤드리스 모드로 로컬 코딩 에이전트로 실행되며, 특정 모델에 종속되지 않으므로 DeepSeek 자체 모델에 묶이지도 않습니다. 2026년 8월 개발자 프리뷰로 출시되어 빠르게 업데이트되고 있습니다.