DeepSeek Harness: 1017을 붙여 쓰는 에이전트 하네스

DeepSeek Harness(dsh)는 DeepSeek AI가 MIT 라이선스로 공개한 에이전트 하네스예요. 모델 자체가 아니라, 대화 세션과 파일 접근, 셸 실행, 검색, 플러그인을 묶어 모델이 실제 작업을 이어가게 하는 프로그램입니다. '모든 것이 플러그인' 구조라 필요한 기능만 켜고 끌 수 있어요.

개발자 프리뷰 단계라 호환성이 깨지는 변경이 예고되어 있어요. 업무에 쓰려면 버전을 고정하고, 업데이트 전에 릴리스 노트를 확인하는 편이 안전합니다.

Node.js 22.19 이상이나 24 이상이 필요해요. npx @deepseek-ai/dsh web을 실행하면 기본 주소 http://127.0.0.1:3080에서 웹 UI가 열리고, 로컬 실행이면 브라우저도 함께 열립니다. 서버만 띄우려면 --no-open을 붙여요.

소스에서 실행하려면 저장소를 받아 pnpm install, pnpm run build, pnpm dsh web 순서로 진행합니다. 첫 실행 뒤에는 설정과 자격 증명이 $DSH_HOME 아래에 저장되므로, 백업²과 삭제 범위를 그 폴더 기준으로 정하세요.

웹 UI의 Settings → Models에서 DeepSeek 카드에 API 키를 넣으면 deepseek-flash를 쓸 수 있어요. 키는 다시 읽을 수 없고 $DSH_HOME/.credentials.yaml에 저장되며, 설정에는 참조만 남습니다.

다른 제공자나 사내 게이트웨이³는 Add model provider의 Custom model API로 추가해요. 제공자 ID, Base URL, API 프로토콜(OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 중 하나), 모델 ID를 넣고, 필요하면 Fetch available models로 목록을 가져옵니다. 제공자 ID는 나중에 바꿀 수 없으니 처음에 정확히 정하세요.

vLLM이나 llama.cpp 서버처럼 OpenAI 호환 API를 제공하는 로컬 서버도 Custom model API로 연결할 수 있어요. 이때 Base URL, 모델 ID, 문맥 창과 최대 출력 토큰⁴을 서버 설정과 같게 적어야 해요. 하네스가 긴 대화를 압축하거나 도구 결과를 넣을 때 실제 서버 한도를 넘기면 요청이 실패합니다.

로컬 모델의 도구 호출⁵ 신뢰도는 모델과 런타임⁶에 따라 달라요. 작은 모델은 도구 스키마를 어기거나 같은 호출을 반복할 수 있으므로, 파일 읽기와 셸 실행 권한을 좁히고 짧은 작업부터 시험하세요. 1017을 로컬에서 붙이려면 vLLM 같은 서버 경로가 필요하고, 메인라인 llama.cpp는 아직 이 구조를 읽지 못합니다.

DeepSeek는 1017을 dsh 0.2.1-rc.1 이상에 맞춰 최적화했다고 안내해요. 0.2.1-rc.2에는 Search·Fetch API를 웹 검색 설정에서 켜는 기능도 들어갔어요. 이 검색 도구는 2026년 11월 1일까지 무료이고, 그 뒤에는 성공한 요청마다 요금이 붙습니다.

모델을 바꿀 때는 세션에 기록된 모델이 그대로 유지된다는 점도 알아두세요. 이미 요청을 보낸 세션은 새 기본 모델로 자동 전환되지 않으므로, 새 세션을 열어 비교해야 합니다.

프리뷰 버전은 설정 파일 구조와 플러그인 API가 바뀔 수 있어요. $DSH_HOME/profiles/web/cordis.patch.yml을 백업하고, 사용 중인 플러그인과 모델 설정을 기록한 뒤 업데이트하세요. 자동 업데이트보다 태그를 고정하는 편이 재현에 유리합니다.

셸과 파일 접근 권한은 기본값을 그대로 두지 말고 작업 폴더와 허용 명령을 좁히세요. 하네스는 편의를 위해 권한을 넓게 잡을 수 있으므로, 중요한 저장소에서는 샌드박스⁷와 승인 절차를 먼저 확인해야 합니다.