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

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

업데이트됨 2026년 8월 21일 · 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는 “모든 것이 플러그인” 접근 방식을 따릅니다. 모델, 도구, 인터페이스, 에이전트 동작까지 프레임워크 사용 목적에 맞춰 추가, 제거, 교체할 수 있습니다.

여전히 이 용어가 100% 와닿지 않으신다면, “에이전트 하니스란 무엇인가?”라는 질문에 답하는 가이드를 읽어 보시길 권합니다.

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가 pnpm을 사용합니다. 전역으로 설치하세요:

npm install -g pnpm

API 키 설정

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

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

우선 코딩과 웹 검색에만 필요하므로 지금은 DeepSeek 키만 설정하고, 이후 ModLens로 비전을 추가할 때 Gemini 키를 더하겠습니다.

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 모델을 더 잘 활용하려면, Python에서 V4 추론 모드와 API 파라미터를 다루는 DeepSeek V4 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를 사용하겠습니다. 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 모델에만 제한되지 않음을 보여줍니다.

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

마무리 생각

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월 개발자 프리뷰로 출시되어 빠르게 업데이트되고 있습니다.