DeepSeek Harness란 무엇인가? OpenCode 및 Pi와의 비교와 10분 만에 시작하는 방법

DeepSeek의 오픈소스 에이전트 하네스(agent harness)를 위한 실용 가이드입니다. 이 글을 통해 '하네스'라는 단어의 의미가 무엇인지, DeepSeek Harness가 OpenCode 및 Pi와 어떻게 다른지, 그리고 이를 설치하고 유용한 플러그인을 추가하며 첫 번째 플러그인을 작성하는 방법을 배울 수 있습니다.

언어 모델은 한 가지 일만 합니다. 텍스트를 입력받아 텍스트를 출력할 뿐입니다. 파일 열기, 테스트 실행, 웹 검색, 또는 어제 무엇을 요청했는지 기억하는 것은 할 수 없습니다. '내 프로젝트에서 작동하는 AI 에이전트'처럼 보이는 모든 것은 모델 주변에 감싸진 다른 무언가입니다.

그 무언가를 **하네스(harness)**라고 부릅니다.

2026년 8월, DeepSeek은 자체 DeepSeek Harness를 오픈소스로 공개했습니다 (줄여서 dsh). 이의 슬로건은

• 프롬프트를 구성합니다(It builds the prompt). 사용자의 메시지, 지금까지의 대화 내용, 프로젝트 지침, 그리고 사용할 수 있는 도구 목록을 수집하여 모델에 전송합니다.
• 모델에게 도구를 제공합니다(It gives the model tools). 파일 읽기, 파일 편집, 셸 명령어 실행, 웹 검색 등이 가능합니다. 만약 특정 도구가 harness에 포함되어 있지 않다면, 모델은 해당 도구를 사용할 수 없습니다.
• 규칙을 강제합니다(It enforces the rules). 어떤 명령이 사용자의 승인이 필요한지, 무엇이 샌드박스(sandbox) 내에서 실행되는지, 무엇이 완전히 차단되는지를 규정합니다.
• 루프를 실행합니다(It runs the loop). 모델이 도구를 요청하면, harness가 이를 실행하고 그 결과가 다시 모델로 전달되며, 이 과정은 작업이 완료될 때까지 반복됩니다.
• 메모리를 관리합니다(It manages memory). 모델의 제한된 컨텍스트 윈도우(context window)에 무엇을 유지할지 결정하고, 나중에 검사할 수 있는 세션 로그에 모든 것을 기록합니다.
• 인터페이스를 제공합니다(It gives you an interface). 터미널, 브라우저 탭, IDE 패널 또는 스크립트를 위한 API가 될 수 있습니다.

이 루프의 한 순환 과정은 다음과 같습니다:

1. 사용자: “왜 이 테스트가 실패하나요?”
2. harness는 사용자의 메시지와 도구 목록을 모델에 전송합니다.
3. 모델이 답변합니다: “npm test를 실행하세요.”
4. harness는 자체 규칙을 확인하고 명령을 실행하며, 그 결과를 기록합니다.
5. 결과가 다시 모델로 전달되고, 이제 모델은 실패 원인을 설명합니다.

모델은 사용자의 디스크에 직접 접근하지 않습니다. 모든 행동은 harness를 거쳐 이루어집니다.

이것이 바로 harness가 모델만큼 중요한 이유입니다. 동일한 모델을 두 개의 다른 harness에 넣으면 완전히 다른 제품 두 개가 나옵니다: 서로 다른 도구, 서로 다른 안전 동작 방식, 서로 다른 메모리 관리, 서로 다른 속도 때문입니다. 사람들은 점점 이 레이어(layer)를 조정하는 작업을 “harness 엔지니어링”이라고 부르고 있습니다.

DeepSeek Harness, OpenCode, 그리고 Pi

세 가지 도구 모두 같은 영역에 위치하지만, 각기 다른 사용자를 위해 구축되었습니다. 여기서는 각각의 문서와 README를 기반으로 어떻게 자신을 설명하는지 보여드립니다.

OpenCode: 완성된 코딩 에이전트

OpenCode: 완성된 코딩 에이전트

OpenCode는 오픈 소스 AI 코딩 에이전트입니다. 터미널 인터페이스, 데스크톱 앱 또는 IDE 확장 프로그램 형태로 제공됩니다. Build(편집 및 실행에 대한 전체 접근 권한)와 Plan(분석용으로 제한됨)이라는 두 가지 주요 에이전트와 하위 에이전트를 함께 제공합니다. Tab 키를 사용하여 기본 에이전트 간을 전환할 수 있습니다. 또한, skills 시스템, MCP 서버, 그리고 JavaScript 또는 TypeScript로 작성되어 이벤트에 연결되는 plugins도 가지고 있습니다.

OpenCode는 자체적인 하네스(harness)를 포함하고 있지만, 사용자가 그것에 대해 생각할 일은 거의 없습니다. 이는 사용자가 열고 사용하는 코드를 편집하기 위한 세련된 도구로 구축되었습니다.

Pi: 가장 작은 하네스

Pi는 이 단어를 의도적으로 사용합니다. README에는 “Pi는 자신만의 에이전트를 만들 수 있는 최소한의 확장 가능한 에이전트 하네스입니다.”라고 적혀 있습니다. Pi는

– 주요 특징 (Mainly a…)

• OpenCode: 코딩 에이전트 제품(coding agent product)
• Pi: 최소한의 하네스(minimal harness)
• DeepSeek Harness: 완전한 기본 설정이 갖춰진 하네스(harness with a full default setup)
  – 인터페이스 (Interface)
• OpenCode: 터미널, 데스크톱 앱, IDE 확장 기능
• Pi: 터미널, 인쇄/JSON, RPC, TypeScript SDK
• DeepSeek Harness: 브라우저 UI, 헤드리스 CLI(headless CLI), Python SDK
  – 기본 제공 기능 (Out of the box)
• OpenCode: 빌드 및 계획 에이전트(Build and Plan agents), 서브 에이전트(sub-agents), 권한(permissions), 스킬(skills), MCP
• Pi: 소수의 기본 설정, 서브 에이전트나 플랜 모드는 없음
• DeepSeek Harness: 파일, 셸(shell), 웹 가져오기(web fetch), 서브 에이전트, 계획 모드(plan mode), 할 일 목록(to-dos), 스킬
  – 확장 방법 (How you extend it)
• OpenCode: 이벤트에 연결되는 JS/TS 플러그인, 사용자 정의 도구(custom tools), 스킬, MCP 서버
• Pi: TypeScript 확장 기능, 스킬, 프롬프트 템플릿, 테마, 패키지
• DeepSeek Harness: 코어 루프를 포함하여 모든 것을 위한 플러그인
  – 설치 (Install)
• OpenCode: 설치 스크립트, npm, Homebrew 등
• Pi: 설치 스크립트 또는 npm
• DeepSeek Harness: npx @deepseek-ai/dsh web
  – 라이선스 (License)
• 세 가지 모두: MIT

어떤 것을 선택해야 할까요?

• OpenCode: 작업이 “오늘 터미널에서 이 저장소(repository)를 수정하는 것”이라면. 세 가지 중 가장 완성도 높은 일일 코딩 도구입니다.
• Pi: 가능한 가장 작은 루프를 원하고 나머지를 직접 구축하기를 선호한다면.
• DeepSeek Harness: 이미 구성 요소들이 갖춰진 하네스를 원하며, 런타임 자체를 변경하는 것에 관심이 있다면.

이들은 상호 배타적이지 않습니다. 심지어 스킬을 공유할 수도 있으며, 이는 아래에서 더 자세히 다룹니다.

인기도(Popularity) 측면으로 보면: 2026년 10월 초 GitHub에 따르면 DeepSeek Harness는 약 245,000개의 스타를 기록했고, OpenCode가 212,000개, Pi가 113,000개를 기록했습니다. Cursor와 Claude Code는 OpenCode와 같은 그룹에 속합니다. 이들은 조립하는 하네스가 아니라 완성된 코딩 에이전트입니다.

10분 만에 설정하기

다음이 필요합니다:

10분 만에 설정하기

다음이 필요합니다:

• Node.js 22.19 이상 (24+도 작동함). Node 18과 20은 거부됩니다. node -v로 확인하세요.
• platform.deepseek.com에서 DeepSeek API 키. 모델 제공업체가 사용량을 청구합니다.
• 편집해도 괜찮은 프로젝트 폴더. 처음 사용할 때는 복사본을 사용하세요.

1. 시작하기

프로젝트 폴더에서:

cd /path/to/your/project
export DEEPSEEK_API_KEY=sk-your-key-here
npx @deepseek-ai/dsh web

브라우저가 http://127.0.0.1:3080을 엽니다. web 뒤에 두 개의 플래그가 붙습니다: --no-open은 브라우저 열기를 건너뛰고, --port 3081은 포트를 변경합니다.

URL에 ?token=...이 포함되어 있다면 공유하지 마세요. 그 토큰은 이 세션의 로그인 정보입니다.

2. UI에서 키 추가하기 (환경 변수로 설정하지 않은 경우)

**설정(Settings) → 모델(Models)**을 열고, 키를 붙여넣은 후 저장합니다. 재시작할 필요가 없습니다. 이 키는 ~/.dsh/.credentials.yaml에 저장되며 사용자에게 다시 표시되지 않습니다.

이 하네스는 다음 순서로 키를 찾습니다: 환경 변수, ~/.dsh/.credentials.yaml, 시작한 폴더의 .env 파일, 그리고 ~/.dsh/.env. 아무것도 찾지 못하면 요청은 MISSING_CREDENTIAL 오류와 함께 실패합니다.

기본 제공업체는 모델 deepseek-v4-flash를 사용하는 deepseek-official입니다.

3. 작업 공간을 선택하고 질문하기

새 세션에는 작업 공간이 없으며, 작업 공간을 선택할 때까지 메시지 상자는 비활성화된 상태로 유지됩니다. **작업 공간 선택(Choose workspace)**을 클릭하고 프로젝트 폴더를 추가한 다음, 선택하고 다음과 같이 시도해 보세요:

Summarize this repository and identify its main packages.

이제 작동하는 에이전트를 갖게 되었습니다.

다른 모델을 원하나요?

같은 설정 페이지에 **모델 제공업체 추가(Add model provider)**가 있습니다. 내장된 제공업체에는 Anthropic, OpenAI, Kimi, GLM이 포함됩니다. 회사 게이트웨이나 자체 호스팅 서버는 세 가지 프로토콜 중 하나를 사용하면 사용자 지정 제공업체로 작동합니다: OpenAI Chat Completions, OpenAI Responses, 또는 Anthropic Messages. 모델 구성(Configure models)을 참조하세요.

질문 하나, 브라우저 없이

질문 하나, 브라우저 없이

npx @deepseek-ai/dsh --profile headless "summarize this workspace"

이 명령어는 하나의 작업을 수행하고, 답변을 출력한 다음 종료합니다. 스크립트에서 유용합니다.

세션이 할 수 있는 일들

기본적으로(Out of the box), 세션은 파일을 읽고 편집하며, 프로젝트를 검색하고, 셸 명령어를 실행하며, 공개 웹 페이지를 가져오고, 하위 에이전트에게 서브 태스크를 위임하며, 할 일 목록을 유지하고, 확신하지 못할 때 사용자에게 질문을 던질 수 있습니다. 승인 정책에 따라 위험한 단계가 있을 경우 사전에 사용자에게 요청합니다.

다음 세부 사항들이 초기에 도움이 됩니다:

• 각 셸 명령어는 독립적으로 시작됩니다. cd 명령은 이전 상태를 유지하지 않습니다. 대신 에이전트는 작업 디렉터리(working directory)를 전달합니다. 긴 작업은 백그라운드에서 실행될 수 있습니다.
• 웹 가져오기는 공개 주소만 접근할 수 있습니다. localhost와 사설 호스트는 거부됩니다.
• 프로젝트 지침이 자동으로 로드됩니다. 리포지토리에 AGENTS.md 또는 CLAUDE.md 파일이 있다면, harness가 이를 읽습니다(최대 65,536 바이트).
• 추적 보기(trace view)가 있습니다. 답변이 잘못되었다고 생각되면, 프롬프트를 다시 작성하기 전에 트레이스를 열어보세요. 모델이 무엇을 보았는지, 각 도구 호출(tool call), 그 결과, 그리고 타이밍까지 보여줍니다.

좋은 첫 실습 과제는 코드 리뷰입니다:

Review the uncommitted diff. Group findings by severity.
For each one, name the file and the failure mode.
Do not edit files.

트레이스에서는 diff를 위한 셸 호출, 몇 개의 파일 읽기 작업, 그리고 답변이 순서대로 보이는 것을 확인할 수 있습니다.

설치할 만한 플러그인들

모든 것이 플러그인이기 때문에, 플러그인 생태계가 방대합니다. GitHub에서 dsh-plugin 토픽을 검색하면 수천 개의 리포지토리가 나타나지만, 그중 많은 것은 DeepSeek Harness와 관련이 없습니다. 따라서 여기는 실제적이고 설치 가능하며 유용한 커뮤니티 플러그인 목록입니다. 제가 이들을 선정한 이유는 각각 명확한 설치 단계를 선언하고 있으며, 표준 dsh plugin add 명령어와 작동하고, 지난 몇 주 동안 업데이트된 게시된 npm 패키지를 가지고 있기 때문입니다.

모든 플러그인 설치 방법

가장 쉬운 방법은 웹 UI를 이용하는 것입니다. 플러그인 추가(Add plugin) 마법사를 열고, 플러그인 이름을 입력한 다음 설치(Install) 버튼을 클릭합니다.

또는 명령줄을 사용합니다:

아래 목록의 명령어들은 dsh plugin ... 형식으로 작성되었습니다. 이는 CLI를 전역적으로 설치했을 경우(npm install -g @deepseek-ai/dsh) 작동합니다. 만약 npx만 사용한다면, 대신 npx @deepseek-ai/dsh plugin ...을 작성해야 합니다.

이 명령어는 경로에 pnpm이 필요합니다. pnpm이 ERR_PNPM_ADDING_TO_ROOT 오류를 표시하면, 패키지 이름 앞에 -w를 추가하십시오. 플러그인이 나타나지 않으면 dsh web을 다시 시작해야 합니다. 왜냐하면 실행 중인 세션은 플러그인을 시작했을 때의 상태를 유지하기 때문입니다.

시작 목록 (The starter list)

1. dshmarket: UI 내장 플러그인 스토어. 이 플러그인은 **설정(Settings) → 플러그인 마켓(Plugin Market)**을 추가하여, 사용자가 커뮤니티 플러그인을 한 번의 클릭으로 탐색하고, 검색하고, 설치할 수 있게 하며 테마를 전환할 수도 있습니다. dsh web 0.1.0-rc.6 이상이 필요합니다.

dsh plugin --profile web add dshmarket

2. dsh-context: 컨텍스트 창을 채우는 내용을 확인하세요. 세션별 컨텍스트 크기, 구성 및 추세 대시보드, 토큰 및 비용 차트가 포함된 세션 간 개요, 그리고 /context 슬래시 명령어를 제공합니다. 세션이 길어지고 답변의 질이 떨어질 때 유용합니다.

dsh plugin --profile web add dsh-context

3. dsh-usage-stats: 지출 내역을 파악하세요. 제공업체 잔액, 구독 할당량, 일별/제공업체별/모델별 토큰 사용량, 예상 비용, 그리고 CSV 또는 JSON 내보내기 기능을 제공합니다. README에 따르면 자격 증명(credentials)은 서버 측에 유지되며 브라우저로 절대 전송되지 않습니다.

dsh plugin --profile web add "@ychris12138/[email protected]"