CH 03 · 설치와 실행
본장 목표
이 장은 dsh를 0부터 실행하는 전 과정을 다룹니다. 먼저 Node.js를 확인/설치하고, 그다음 원커맨드로 Web UI를 띄우고, 최초 설정(모델 키 + 작업 폴더)을 마친 뒤, 첫 번째 실제 작업을 보냅니다. 여기까지 마치면 정식으로 합류한 것입니다.
실습 전: 두 가지만 있으면 됩니다
- Node.js — dsh는 Node 위에서 동작하며, 이것이 유일한 환경 의존성입니다. 데이터베이스도 필요 없고, Java 설정도 필요 없습니다.
- DeepSeek API Key 하나 — dsh 자체는 무료 오픈소스지만, 모델 호출에는 비용이 발생합니다. DeepSeek 오픈 플랫폼에 접속해 회원가입 후 로그인하고, 왼쪽 사이드바의 "API Keys" → 생성(Create)을 눌러 만들어 복사해 두십시오. Key는 한 번만 전체가 표시되며,
sk-접두사가 붙은 긴 문자열 형식입니다. 페이지를 닫기 전에 안전한 곳에 보관하십시오.
1단계: 로컬 Node.js 확인
터미널을 엽니다(Windows에서는 Win + R을 누르고 cmd를 입력한 뒤 Enter), 그리고 다음과 같이 입력합니다.
node --version
npm --version버전 번호가 보이면 준비가 된 것입니다. dsh의 Node 버전 요구사항은 공식적으로 ^22.19 || >=24입니다. 풀어 말하면, Node 22.x 계열 중 22.19 이상, 또는 Node 24 이상입니다. 다시 말해, 22.19 미만의 구버전 22.x와 Node 23 같은 홀수 버전은 지원되지 않으며, 설치를 끝내도 실행에 실패합니다.
저처럼 이미 Node가 깔려 있고 버전도 기준을 충족한다면, 3단계로 바로 건너뛰십시오.
2단계: Node.js가 없다면? 먼저 설치(Windows)
Node.js 공식 사이트에 접속해 LTS 버전의 Windows 설치 파일(.msi, 64비트)을 내려받고, 더블 클릭한 뒤 "다음"을 끝까지 누릅니다. 기본 설정이면 npm도 함께 설치되고 시스템 PATH에도 등록됩니다.
설치 후에는 반드시 터미널을 다시 열고 다시 확인하십시오. "분명 설치했는데 명령을 찾을 수 없다"라는 문제 대부분은 환경 변수가 갱신되지 않아서입니다.
node --version
npm --version3단계: npm을 국내 미러로 전환(선택이지만 강력 추천)
중국 본토에서 npm 패키지를 직접 끌어오면 속도가 느리거나 타임아웃이 나는 경우가 많습니다. 타오바오 미러로 바꾸면 훨씬 나아집니다.
npm config set registry https://registry.npmmirror.com
npm config get registryhttps://registry.npmmirror.com이 출력되면 적용된 것입니다.
4단계: dsh 설치 및 실행
이 자습서는 전역 npm 설치 방식을 사용합니다. 한 줄 명령으로 설치하면
dsh명령이 어디서든 사용할 수 있고, 호출 시마다 다시 내려받을 필요도 없어 초심자에게 가장 쉽습니다.
전역 패키지를 설치합니다.
npm install -g @deepseek-ai/dsh설치 후 버전을 확인합니다.
dsh --version그다음 Web UI를 실행합니다.
dsh web최초 실행 시 1~2분 정도 의존성을 내려받으며, 터미널에 로그가 줄줄이 흘러나옵니다. 정상입니다. 다음과 비슷한 메시지가 보이면 실행에 성공한 것입니다.
dsh web: http://127.0.0.1:3080
dsh web: opening the default browser; pass --no-open to disable
최신 버전으로 업데이트 하려면(전역 설치는 자동 업데이트되지 않으므로 수동으로).
npm install -g @deepseek-ai/dsh@latest5단계: Web UI 열기
최초로 dsh web을 실행하면 브라우저가 자동으로 인터페이스를 엽니다. 자동으로 열리지 않는다면, 브라우저를 직접 열고 다음 주소로 접속하십시오.
http://127.0.0.1:3080이 주소는 로컬 루프백 주소이며, 이 컴퓨터에서만 작동하고 외부 네트워크로 노출되지 않습니다.
처음 열면 베타 안내 팝업이 뜹니다. DeepSeek Harness 0.1은 여전히 개발자 대상 시험 버전이며 계속 빠르게 반복 업데이트될 예정입니다. 계속(Continue) 을 눌러 메인 인터페이스로 진입하십시오.
6단계: 최초 설정(Key + 작업 폴더)
6.1 API Key 입력
앞 단계에서 계속 을 클릭하면 dsh가 바로 "API Key 추가하여 시작하기" 안내를 띄웁니다. sk- 접두사로 시작하는 Key를 입력란에 붙여넣고 저장 후 계속(Save and Continue) 을 누르십시오. (나중에 Key를 바꾸거나 모델을 바꾸려면, 좌하단의 설정(Settings) 버튼 → 모델(Models) 로 가시면 됩니다.)
Key는 로컬의
C:\Users\<사용자 이름>\.dsh\.credentials.yaml에만 기록되며, UI에는 평문이 절대 표시되지 않습니다. 스크린샷에 담아 공유하지 마십시오.
6.2 작업 폴더 선택
Key 입력을 마치면 메인 인터페이스로 들어갑니다. 작업 폴더 선택(Choose workspace) 드롭다운을 눌러 Agent가 작업할 폴더(예: 본인 프로젝트 폴더)를 선택하십시오. 작업 폴더를 선택하기 전에는 하단 입력란이 계속 "작업 폴더를 선택하여 시작" 상태로 머뭅니다. 이는 의도된 동작입니다. Agent에게 어디서 작업해야 할지 알려 주지 않으면 Agent는 감히 움직이지 않습니다.
6.3 모델과 권한 선택(첫 작업 전송 전에 설정)
작업 폴더를 고르면 우하단에 모델 선택 팝업이 뜨며, DeepSeek 모델 세 가지가 보입니다.
| Model ID | 포지셔닝 |
|---|---|
deepseek-v4-pro | 플래그십 — 가장 강력하지만 비용도 가장 큼 |
deepseek-v4-flash | 빠르고 가성비가 뛰어남 |
deepseek-v4-flash-vision-exp | 멀티모달 비전 버전: 이미지를 읽고, 스크린샷을 보고, 차트를 분석할 수 있음. 순수 텍스트는 flash와 동급, 멀티모달 역량은 압도적 |
deepseek-v4-flash-vision-exp는 DeepSeek V4 제품군의 첫 비전 모델(실험판, API는 2026년 8월 21일 출시, 가중치는 8월 31일 오픈소스 공개)입니다. 이미지를 읽고, 스크린샷을 보고, 차트를 분석할 수 있으며, 일반적인 텍스트 작업도 그대로 수행합니다. 본 서적의 모든 데모는 이 모델을 사용합니다. 패널에서 선택하고 추론 강도(reasoning effort)를 지정(기본 High면 충분)한 다음 저장하면 즉시 적용되며, 재시작은 필요 없습니다.
입력란 왼쪽에는 권한 선택기 도 있습니다(스크린샷에서 Workspace Write로 표시되어 있음). 이 설정은 Agent가 본 컴퓨터에서 무엇을 만질 수 있는지를 결정합니다. 지금은 기본값 그대로 두십시오. 세 가지 권한 등급별 차이점과 추론 강도 선택 방법은 인터페이스를 함께 살펴보는 CH 04에서 자세히 다룹니다.
7단계: 첫 작업 실행
새 세션을 만들고 한 문장을 입력합니다. 예를 들면 이렇게.
DeepSeek harness 저장소를 요약하고 주요 모듈을 파악해 주세요.
그러면 Agent가 파일을 읽고, 명령을 실행하고, 계획을 유지하면서 작업을 시작하며, 모든 도구 호출이 인터페이스에 펼쳐집니다. 스크린샷의 전체 실행 체인은 컨텍스트 주입 → 사고(Think) → Pwsh → 읽기(Read)입니다. 민감한 작업은 현재 권한 정책에 따라 승인 대화상자가 뜹니다. 인터페이스 좌상단에 대화(Conversation) / 궤적(Trajectory) 두 탭이 있고, 궤적은 CH 02에서 언급한 그 Trajectory이며, 뒤에서 다루겠습니다.
작업이 끝나면 완전한 요약이 나옵니다. 이번 제 결과를 인용하면 제목은 "DeepSeek Harness 저장소 요약"이었고, 한 줄 포지셔닝은 "모든 것은 플러그인(Everything is a plugin) AI Agent 런타임 프레임워크 / 워크벤치, Cordis 기반"이었으며, 저장소의 packages/apps/docs 디렉터리 구조와 dsh-* 패키지 계열의 주요 모듈도 함께 짚어 주었습니다.
이 단계를 통과하면 정식으로 합류한 것입니다.
고급 사용법
포트 변경(3080이 점유 중인 경우): 실행 시 dsh web 대신 다음 명령을 사용하십시오.
dsh web --port 8080그다음 http://127.0.0.1:8080에 접속합니다.
일회성 명령행 작업(headless):
dsh --profile headless "Run the tests in the current directory and summarize the results"결과를 출력하고 종료하며, 스크립트와 CI에 적합합니다. 전체 headless 플레이북(여러 진입점, CLI 파라미터, 실제 실습)은 CH 05에서 다룹니다.
실제 적용 중인 구성 트리 보기(문제 해결에 매우 유용).
dsh web --dump-config자주 만나는 문제 해결
| 증상 | 해결 방법 |
|---|---|
node가 내부 또는 외부 명령이 아님 | Node가 제대로 설치되지 않았거나 터미널을 다시 열지 않은 상태입니다. PowerShell을 다시 열고 재시도 |
| Node 버전 ... 은(는) 지원되지 않음 | 22.19 미만이거나 Node 23입니다. 22.19 이상 / 24로 업그레이드 |
| 최초 설치가 멈추거나 내려받기 실패 | 네트워크 문제. npmmirror 레지스트리를 먼저 설정하고 재시도 |
| 3080 포트 점유 | 포트 변경: dsh web --port 8080 |
| 페이지가 열리지 않음 | 실행 명령을 친 터미널이 여전히 열려 있는지 확인. 주소는 http://127.0.0.1:3080 |
MISSING_CREDENTIAL 보고 | 저장된 API Key가 없음(설정 → 모델에서 추가) 또는 창을 다시 열지 않은 상태 |
UNKNOWN_MODEL 보고 | 설정되지 않은 모델을 선택했습니다. 사용자 정의 제공자 항목에 모델 ID 추가 |
| 네이티브 컴파일 오류(예: node-pty) | Windows에서 Visual Studio Build Tools(C++ 구성 요소 포함) 설치 |
안전 알림: API Key는 곧 지갑입니다. 단체 채팅방에 스크린샷을 올리거나 Git 저장소에 커밋하지 마십시오. 유출이 의심되면 플랫폼에서 폐기 후 재생성하십시오. 기존 Key는 즉시 무효화됩니다.
이 장에서 배운 것
아래 항목들을 스스로 완수할 수 있으면 합격입니다.
- [ ]
node --version으로 Node가 22.19 이상 / 24 이상인지 확인한다(기준 미달이면 1단계처럼 설치) - [ ]
npm install -g @deepseek-ai/dsh로 dsh를 설치하고,dsh web으로 실행해http://127.0.0.1:3080을 연다 - [ ] 최초 설정을 마친다: 설정 → 모델에 API Key 입력, 작업 폴더 선택
- [ ] 첫 번째 실제 작업을 성공적으로 보내고 Agent가 일하는 모습을 본다