SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

DeepSeek Harness 설치 오류와 버전 고정 방법

최신 DeepSeek Harness도 아직 prerelease입니다. 정확한 dsh 버전을 고정하고 npx 캐시를 삭제한 뒤, 실제로 실행 중인 npm과 Node.js 버전을 확인하는 방법을 설명합니다.

DeepSeek Harness 설치의 실제 의미

DeepSeek Harness 설치는 한 개의 명령인 npx @deepseek-ai/dsh web뿐이다. 설치 프로그램은 없으며, 구성할 서비스도 없다. 사용자가 겪는 대부분의 문제는 실제 설치 문제가 아니다. 버전 확인 문제다. 즉, @deepseek-ai/dsh npx가 현재 실행하기로 결정한 빌드가 무엇인지, 그리고 사용 중인 Node.js 버전에서 실행할 수 있는지를 확인해야 한다. 실행이 시작되면 기본 바인딩은 localhost다. --host와 --port이 리스너 설정을 재정의하며, 설정된 경우 출력되는 주소에는 --public-url가 사용된다. 기본 바인딩과 Web UI가 127.0.0.1:3080에서만 응답하는 이유는 이 페이지에서 다루는 문제와 별개다.

이하의 내용은 두 가지 사실을 바탕으로 한다. 첫째, 27 October 2026 기준으로 npm에 게시된 @deepseek-ai/dsh의 모든 버전은 prerelease였다. 대부분은 release candidate(-rc.N)이며, 30 August 2026부터는 alpha 빌드(-alpha.N)도 제공되었다. latest 태그는 release candidate를 가리킨다. 6 November 2026 기준으로 해당 버전은 0.2.2-rc.1다. 둘째, 프로젝트 README에는 이 harness가 developer preview 상태이며 빠르게 변경되고 호환성을 깨는 변경이 발생할 수 있다고 명시되어 있다. 지난주에 작동한 flag가 이번 주에는 사라질 수 있다. 이 harness를 기반으로 무엇인가를 구축하기 전에 버전을 고정해야 한다.

먼저 몇 가지 용어를 설명한다. dsh는 DeepSeek Harness 명령줄 도구다. Node.js는 이 도구에 필요한 JavaScript 런타임이다. npx는 npm(node package manager)에 포함된 package runner이며, 패키지를 영구적으로 설치하는 대신 필요할 때 가져온다. 이 문장에서 harness라는 용어가 익숙하지 않다면 agent harness는 model을 둘러싸는 프로그램이다. 이 프로그램은 loop, tool, permission, session state를 관리한다. 따라서 사용자가 선택하지 않은 버전 번호 하나만으로도 agent의 동작 방식이 달라질 수 있다.

dsh에는 어떤 Node.js 버전이 필요한가?

2026년 10월 10일, 저장소 버전이 0.2.1-alpha.2였을 때 루트 package.json에는 "engines": {"node": "^22.19.0 || >=24.0.0"}이 선언되어 있었다. 이 값은 더 이상 요구 사항이 아니다. 2026년 10월 27일에 확인했을 때 저장소 버전이 0.2.1-rc.3이었으며, 루트 package.json에는 "engines": {"node": ">=24.9.0"}가 선언되어 있었고 CLI의 자체 소스 package.json에도 이제 같은 값이 선언되어 있다. 2026년 10월 15일에 작성된 프로젝트 결정 사항에는 Node 22 설치를 업그레이드해야 하며 Node 24.0도 충분하지 않다고 되어 있다. 진입점이 import.meta.main에 의존하지만 24.0에는 이 기능이 없기 때문이다. 따라서 Node 24.9.0 이상이 필요하다. Node 20과 Node 22는 사용할 수 없으며, 24.9.0 이전의 모든 Node 24 릴리스도 사용할 수 없다. 2026년 10월 27일에 확인했을 때 0.2.1-rc.2의 릴리스 태그, 그 태그가 가리키던 빌드 latest, 0.2.1-rc.3에는 여전히 이전 범위가 지정되어 있었다. 따라서 새로운 최소 버전은 그 이후에 적용되었다. 그래도 24.9.0을 기준으로 계획해야 한다. 현재 프로젝트가 선언한 범위가 그렇기 때문이다.

무엇보다 먼저 현재 설치된 버전을 확인한다.

node -v
npm -v

여기서 많은 사용자가 의외라고 느끼는 부분이 있다. 2026년 10월 27일 기준으로 공개된 @deepseek-ai/dsh 패키지는 0.2.1-rc.4까지의 38개 버전 중 어느 버전에서도 자체 engines 필드를 포함하지 않았다. 모노레포 루트에는 해당 필드가 선언되어 있지만, 그 루트 파일은 npm에 게시되지 않는다. CLI의 소스 package.json에는 2026년 10월 15일자 커밋에서 해당 필드가 추가되었지만, 2026년 10월 27일에 확인한 게시 빌드에는 어느 것도 그 필드를 포함하지 않았다. 따라서 해당 빌드에서는 npm이 확인할 dsh 전용 Node 요구 사항이 없었다. 2026년 11월 6일 기준으로 공개된 0.2.2-rc.1 패키지에는 "engines": {"node": ">=24.9.0"}이 선언되어 있다. npm은 engines을 engine-strict을 설정하지 않는 한 권고 사항으로만 처리하므로, 기본 설정에서는 최대한 경고만 표시된다. 지원되지 않는 Node에서 설치 자체는 성공한 것처럼 보이지만, 실제 실패는 나중에 로드된 코드가 런타임에 없는 구문이나 API에 접근할 때 발생한다. 어떤 모듈이 먼저 로드되는지에 따라 처음 실패하는 줄이 달라지므로, 검색할 수 있는 하나의 고정된 오류 문자열은 없다. 충돌 메시지 자체보다 node -v을 확인한다.

Node가 너무 오래된 경우 VPS에서는 nvm(node version manager)이 시스템 Node를 그대로 둔 채 홈 디렉터리에 설치하므로 가장 변경 범위가 작은 해결 방법이다.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

이제 node -v은 v24.로 시작하는 버전을 출력해야 한다. 셸이 여전히 이전 버전을 보고하면 which node을 실행한다. ~/.nvm 외부의 경로가 표시되는 데에는 일반적으로 두 가지 원인이 있다. nvm 셸 함수가 로드되지 않았을 수 있으므로 새 로그인 셸을 열고 다시 시도한다. 또는 nvm을 source하는 줄 이후에 셸 프로필의 다른 줄이 PATH을 변경하여 다른 Node를 앞에 배치했을 수 있으므로, 해당 줄을 nvm 관련 줄보다 위로 옮긴다. Node 24는 2026년 10월 10일에 활성 LTS(long term support) 계열이었으며 2026년 10월 20일에 유지 관리 단계로 전환되었다. 2026년 10월 29일 기준 최신 릴리스는 24.22.2로, 24.9.0 최소 버전보다 훨씬 높다. >=24.9.0 범위에서도 허용하는 Node 26은 2026년 10월 28일에 버전 26.13.0으로 활성 LTS에 들어갔다. 둘 중 어느 버전이든 최소 요구 사항을 충족하며, 둘 다 아래에서 설명하는 range-cache 수정 사항이 포함된 npm 버전을 함께 제공한다. 공식 Node 26 Linux 바이너리에는 libatomic도 필요하므로 배포판에 따라 별도로 설치해야 할 수 있다.

npx가 매일 다른 버전을 실행하는 이유

npx @deepseek-ai/dsh web에는 버전이 지정되어 있지 않다. 현재 디렉터리의 프로젝트에 @deepseek-ai/dsh가 이미 설치되어 있으면 해당 복사본을 실행한다. 그렇지 않으면 npx는 레지스트리에서 latest 태그가 가리키는 버전을 요청한다. 이 태그는 자주 변경된다. 0.1.0-rc.8는 0.1.0-rc.7보다 이틀 뒤인 19 August 2026에 출시되었다. 10 October 2026에는 latest가 0.2.0-rc.2을 가리켰고, 27 October 2026에는 0.2.1-rc.2을 가리켰다. 태그가 변경될 때마다 메모에 적어 둔 명령은 별도 확인 메시지나 변경 로그 없이 다른 코드를 실행하기 시작한다.

명령줄에서 변경되는 각 요소를 확인할 수 있다.

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags는 현재 latest가 가리키는 대상을 보여 준다. 10 October 2026에는 latest와 next가 모두 0.2.0-rc.2을 가리켰고, 세 번째 태그인 alpha은 전날 게시된 0.2.1-alpha.2을 가리켰다. 27 October 2026에는 latest가 0.2.1-rc.2을, next이 전날 게시된 0.2.1-rc.4를, alpha이 0.2.1-alpha.5를 가리켰다. 6 November 2026 현재 latest는 0.2.2-rc.1을 가리킨다. 4 November 2026에는 next이 0.2.1-rc.5을, alpha가 0.2.2-alpha.3을 가리켰다. latest 태그는 여전히 prerelease를 선택한다. versions 목록은 중간에 빠진 항목이 있어 더 주의해서 봐야 한다. 10 October 2026에는 0.0.1-rc.1부터 0.2.1-alpha.2까지 31개 버전이 있었고, 27 October 2026에는 38개로 늘어났으며 모두 여전히 prerelease였다. 0.0.1 계열은 -rc.2에서 -rc.5으로 건너뛰고, 0.1.0 계열은 -rc.3에서 -rc.6으로 건너뛴다. alpha 빌드는 0.1.2-alpha.2와 0.1.3-alpha.2에서 시작하며, 0.1.4은 아예 없다. 게시된 목록에는 일부 숫자가 빠져 있고 alpha 빌드와 release candidate가 같은 목록에 섞여 있다. 배포 스크립트에서 다음 -rc.N을 추측하면 실패하므로, 숫자를 순서대로 세지 말고 목록을 확인해야 한다.

npx가 이전 버전을 계속 실행하는 이유

이는 반대되는 문제 제기이며, package spec, 로컬 설치 상태, 실제로 실행하는 npm에 따라 둘 다 발생할 수 있다.

npx는 tarball cache와 별도로 자체 package directory를 유지한다. 이 디렉터리는 npm cache 안의 _npx라는 폴더다. 경로를 출력하고 내용을 확인한다.

npm config get cache
ls "$(npm config get cache)/_npx"

npm 10.9.3은 프로젝트 설치 영역 밖에서 bare package name이 지정되면 이미 registry를 확인한다. npm 11.2.0에서는 version range의 cache freshness 확인 방식이 변경되었다. spec이 bare name이고 현재 프로젝트에 해당 package가 설치되어 있지 않으면, npx는 preferOnline: true로 manifest를 가져온다. 그런 다음 registry가 반환한 값과 resolved tarball이 일치하는 경우에만 _npx의 cached copy를 재사용한다. bare name은 여전히 registry 확인 없이 현재 프로젝트에 설치된 버전과 일치한다. version range의 경우 npm 10.9.3은 일치하는 cached version을 허용한다. npm 11.2.0 이상은 해당 range가 더 새로운 버전으로 resolve되는지 확인한다.

어떤 동작이 적용되는지는 실제로 실행하는 npm이 결정한다. npm install -g npm로 npm을 별도로 업그레이드하지 않았다면, 실행 중인 npm은 Node release에 포함된 버전이다.

  • Node 20.20.2에는 npm 10.8.2가 포함되어 있다.
  • Node 22.19.0에는 npm 10.9.3이 포함되어 있다.
  • 2026년 10월 27일 기준 최신 Node 22 release인 Node 22.23.4에는 npm 10.9.9가 포함되어 있다.
  • harness의 현재 최소 지원 버전인 Node 24.9.0에는 npm 11.6.0이 포함되어 있다.
  • Node 24.19.0에는 npm 11.17.0이 포함되어 있다.
  • 2026년 10월 29일 기준 최신 Node 24 release인 Node 24.22.2에는 npm 11.19.1이 포함되어 있다.
  • 2026년 10월 29일 기준 최신 Node 26 release인 Node 26.13.0에는 npm 11.20.0이 포함되어 있다.

따라서 Node 22 전체 계열에는 11.2.0보다 오래된 npm이 포함되어 있다. harness는 2026년 10월 중순까지 Node 22를 지원했으며 현재는 지원하지 않는다. 그러나 그 시점 이전에 dsh를 실행한 서버에는 여전히 Node 22가 설치되어 있을 수 있다. Node 22.19.0에 포함된 npm 10.9.3은 프로젝트 설치 영역 밖에서 bare npx @deepseek-ai/dsh web를 registry와 다시 확인한다. 따라서 오래된 _npx 항목만으로는 이전 release candidate가 사용되는 이유를 설명할 수 없다. 현재 harness가 허용하는 모든 Node release는 24.9.0 이상이며, npm 11.6.0 이상을 포함한다. 이 버전에는 range cache 수정 사항도 포함되어 있다. 그래도 프로젝트에 설치된 package가 우선될 수 있다. tool에 실제로 어떤 항목을 사용하는지 확인하도록 요청한다.

npx @deepseek-ai/dsh --version

npx cache 지우기

npm 11.2.0 이상에는 이를 위한 전용 subcommand가 있다.

npm cache npx ls
npm cache npx rm --force

--force 없이 실행하면 npm은 전체 삭제를 거부하고 Please use --force to remove entire npx cache을 출력한다. 모든 항목이 아니라 key로 하나의 항목만 삭제하려면 먼저 npm cache npx ls을 사용한다.

npm 10에는 이러한 subcommand가 없으므로 디렉터리를 직접 삭제한다.

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force는 이 문제를 해결하지 못한다. 이 명령은 tarball store인 _cacache을 지우지만 _npx는 그대로 둔다. 이러한 분리가 있었기 때문에 npm은 나중에 npm cache npx subcommand를 추가했다. _npx을 지워도 영구적으로 잃는 데이터는 없다. 이 디렉터리에는 downloaded package가 저장되며, harness state는 $DSH_HOME 아래에 별도로 저장된다. 여기에는 profiles/<name>, sessions, storages, .credentials.yaml이 포함되며, 이 상태는 변경되지 않는다.

정확한 릴리스 후보를 어떻게 고정합니까?

-rc.N 부분을 포함한 전체 버전 문자열을 지정합니다.

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

이 페이지의 예제에서는 0.1.0-rc.7을 사용합니다. 실제로 테스트한 빌드로 바꾸십시오. 2026년 10월 27일 기준으로 latest 태그는 0.2.1-rc.2를 가리켰습니다.

--yes은 대화형 프롬프트 없이 npx의 패키지 설치 확인을 승인합니다.

정확한 버전을 지정하면 dsh 패키지 버전은 고정되지만, 오프라인 시작까지 보장되지는 않습니다. npx는 입력한 사양 문자열을 기준으로 캐시 디렉터리를 정하고, 해당 디렉터리에 이미 설치된 정확한 버전을 재사용할 수 있습니다. 그러나 일치하는 로컬 설치가 없으면 앞의 로컬 트리 확인 단계에서 preferOnline: true로 매니페스트를 가져온 후 _npx를 검사합니다. 로컬 프로젝트에 일치하는 정확한 버전이 설치되어 있으면 이 매니페스트 조회를 피할 수 있습니다. 프로젝트 외부에서 dsh를 설치하는 bare name을 실행해도 매니페스트를 조회하며, npm 10.9.3에서도 동일합니다.

전역 설치도 같은 방식으로 버전을 고정하며, 짧은 명령을 사용할 수 있습니다.

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

@deepseek-ai/dsh@^0.1.0에 일치하는 버전을 찾을 수 없음

2026년 10월 27일 기준으로 일반적인 caret 또는 tilde 범위는 이 패키지와 일치하지 않았습니다. npm install -g @deepseek-ai/dsh@^0.1.0은 오류 코드 ETARGET과 다음 줄 No matching version found for @deepseek-ai/dsh@^0.1.0.을 반환했습니다. 레지스트리에는 문제가 없습니다. 이는 semver 규칙에 따른 결과입니다. 버전 범위 자체의 비교자 중 하나가 동일한 major, minor, patch 번호의 prerelease를 지정하지 않으면 버전 범위는 prerelease 버전과 일치하지 않습니다. 2026년 10월 27일 기준으로 이 패키지가 게시한 모든 빌드는 prerelease였으며, -rc.N 또는 -alpha.N 중 하나였습니다. 그런데 ^0.1.0에는 prerelease가 지정되어 있지 않으므로 어떤 빌드와도 일치하지 않았습니다. 정확한 버전을 지정하십시오.

이 규칙은 양방향으로 적용됩니다. 일반적인 범위는 새 릴리스 후보로 자동 이동하지 않지만, prerelease를 지정한 범위는 이동할 수 있습니다. ^0.1.0-rc.7는 >=0.1.0-rc.7 <0.2.0-0을 의미하므로 0.1.0-rc.8을 허용하고 최종 0.1.0도 허용하지만, 번호가 다른 0.1.1-rc.1은 제외합니다. 이는 정확한 버전과 변경되는 태그 사이의 반고정 상태이며, 사용자가 아무것도 변경하지 않아도 실행되는 버전이 달라질 수 있습니다. 테스트한 빌드만 사용하려면 정확한 버전을 지정하십시오.

npx를 사용해야 합니까, 아니면 dsh를 전역으로 설치해야 합니까?

처음 살펴볼 때는 npx를 사용하십시오. 패키지가 캐시 디렉터리에 저장되므로 나중에 어떻게 삭제하는지 알 수 있기 때문입니다. 재부팅 후에도 계속 작동해야 하는 도구라면 VPS에서 계속 실행 중인 코딩 에이전트와 같이 고정된 버전으로 전역 설치를 진행하십시오.

두 방식을 모두 사용한 환경에서는 서로 충돌할 수 있으므로 두 상태를 비교해야 합니다.

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh 전역 설치를 성공적으로 마쳤음에도 명령어를 찾을 수 없다면, 대부분 npm의 전역 bin 디렉터리가 PATH에 포함되지 않았기 때문입니다. npm prefix -g을 실행하여 루트 경로를 확인하십시오. 바이너리는 해당 경로 아래의 bin 폴더에 위치합니다.

보안 관련 참고 사항입니다. npx는 새로운 패키지를 해석할 때마다 레지스트리에서 코드를 가져와 실행합니다. 이는 서버 환경에서 이론적인 위험을 넘어 실질적인 노출 경로가 될 수 있습니다. 버전 고정은 이에 대한 대응책의 일부입니다. 나머지 내용은 npm 공급망 공격이 서버에 도달하는 방식에서 확인할 수 있습니다.

재현성에서 developer preview가 의미하는 것

0.1.0-rc.6은 2026년 8월 13일에 공개되었고 0.1.0-rc.7은 2026년 8월 17일에 공개되었다. 두 버전 사이에는 4일밖에 없었다. 이후에도 출시 속도는 느려지지 않았다. 2026년 8월 19일부터 10월 9일 사이에 24개 버전이 추가로 공개되었으며, 여기에는 9월 28일의 0.2.0-rc.1과 다음 날의 0.2.0-rc.2이 포함된다. 2026년 10월 14일부터 26일 사이에도 7개가 더 출시되었고, 최신 버전은 0.2.1-rc.4였다. 이 속도라면 한 달 전에 작성한 지침이 더 이상 존재하지 않는 명령줄을 설명할 수 있다. 이 페이지도 예외가 아니다. 작성하는 모든 버전 관련 기록에 날짜를 적어야 한다. 자신의 메모에도 날짜를 포함해야 한다.

preview 환경을 안정적으로 운영하려면 두 가지 습관이 필요하다. 모든 명령과 스크립트에 정확한 버전을 고정해야 한다. 그러면 서버를 다시 구축할 때 동일한 dsh 릴리스를 선택할 수 있다. 그러나 이것만으로는 종속성을 재현할 수 없다. 공개된 0.2.2-rc.1 패키지는 js-yaml: ^4.3.2 및 commander: ^15.0.0과 같은 범위를 사용하며 npm shrinkwrap 없이 제공된다. 종속성을 반복 가능하게 설치하려면 dsh를 로컬 프로젝트에 두고 커밋된 package-lock.json과 함께 관리해야 한다. 그런 다음 npm ci으로 다시 구축한다. 이후에는 어떤 가이드가 아니라 고정한 빌드의 도움말 출력을 확인해야 한다.

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

재현성의 나머지 절반은 프로필이다. dsh --profile <name>은 $DSH_HOME/profiles/<name>에 저장된 프로필로 시작하며, web 및 headless 프로필은 처음 사용할 때 제공된 템플릿에서 자동으로 생성된다. 프로필 패치에는 모델 및 엔드포인트 설정을 저장할 수 있다. 그러나 저장된 API 키는 $DSH_HOME/.credentials.yaml에 저장되고, 설정에는 자격 증명 참조가 유지된다. 따라서 고정된 버전과 작동하는 구성은 별도로 올바르게 준비해야 한다. 홈 수준 패치와 명령줄 패치는 프로필 설정을 재정의할 수 있다. 기본 제공 번들은 현재 실행 중인 dsh 설치에서 확인된다. 따라서 고정한 버전을 변경하면 해당 번들도 함께 변경된다. 외부 플러그인은 다르게 동작한다. 플러그인은 프로필 디렉터리에 저장되며 dsh plugin --profile <name> add <package>은 인수를 pnpm으로 전달해 플러그인을 설치한다. 따라서 PATH에 pnpm이 있어야 하며, 없으면 dsh가 이를 명확하게 알린다. 추가한 각 플러그인은 에이전트와 동일한 권한으로 실행된다. 그러므로 설치하기 전에 플러그인이 접근할 수 있는 항목을 확인하는 것이 좋다. 프로필의 자체 package.json이 이러한 플러그인을 선언한다. 해당 pnpm-lock.yaml을 보존하고 pnpm install --frozen-lockfile을 사용해 플러그인의 종속성 버전도 재현해야 한다.

이러한 분리는 서버에서 Python 도구를 격리된 환경에 보관하는 방법을 사용해 본 경우 익숙할 것이다. 도구와 도구에 추가하는 항목을 서로 다른 위치에서 고정하기 때문이다. harness가 시작되면 다음 질문은 대개 버전이 아니라 네트워킹에 관한 것이다. 이때 원격 VPS에서 dsh Web UI에 접속하기와 VPS에 DeepSeek Harness 설치하기의 자세한 안내가 이어진다.

실제로 보게 되는 인수 오류

이 오류는 CLI 자체의 파서에서 발생하며, 각각 정확한 문제를 나타낸다. 메시지 문구는 대부분 빌드 간에 유지되지만 완전히 동일하지는 않으므로, 아래 메시지는 2026년 10월 6일에 0.2.0-rc.2을 기준으로 확인했다.

오류: --profile <name>이 필요합니다

하위 명령과 프로필 없이 npx @deepseek-ai/dsh을 실행했다. 인수 없이 실행하는 명령은 프로필을 시작하므로 이름이 필요하다. dsh web는 --profile 없이도 동작한다. 파서가 인수 없이 입력된 첫 번째 단어를 프로필 이름으로 해석하기 때문이다. 따라서 제공된 web 프로필을 대신 시작한다.

오류: --patch에는 경로가 필요합니다

--patch 뒤에 아무 값도 지정하지 않았다. 이 플래그는 반복해서 사용할 수 있으며, 사용할 때마다 파일 경로 하나를 지정해야 한다.

오류: --dump-config와 --dump-default-config는 함께 사용할 수 없습니다

둘 중 하나를 선택한다. 2026년 10월 6일에 0.2.0-rc.2이 가리킨 빌드 latest에서는 세 번째 플래그도 메시지에 포함되어 error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive로 표시된다. 프로필 항목과 패치의 JSON Schema를 출력하는 --dump-config-schema가 나머지 두 플래그에 추가되었기 때문이다. --dump-default-config는 제공된 번들 계층을 출력하며 --patch을 허용하지 않는다. --dump-config는 프로필에 대해 조합된 설정을 출력한다. 세 명령 모두 하니스를 시작하지는 않지만, 스키마 수집 과정에서 플러그인 모듈을 가져오고 getter와 지연 빌더를 호출할 수 있다. 신뢰할 수 있는 플러그인만 검사하고 스크립트에서는 외부 타임아웃을 적용한다.

오류: 전달할 pnpm 인수가 필요합니다(예: add <package>)

dsh plugin --profile <name>에 전달할 인수를 지정하지 않았다. 이 하위 명령은 프로필이 없으면 프로필을 초기화한 다음 명령줄의 나머지 내용을 pnpm에 전달하므로 add @scope/dsh-plugin-example와 같은 인수가 필요하다.

FAQ

DeepSeek Harness에는 어떤 Node.js 버전이 필요합니까?

Node.js 24.9.0 이상이 필요합니다. 2026년 10월 27일에 확인했을 때 저장소 버전은 0.2.1-rc.3이었고, 루트의 package.json에는 >=24.9.0이 선언되어 있었습니다. 2026년 10월 10일에는 ^22.19.0 || >=24.0.0이 선언되어 있었지만, 2026년 10월 15일자 프로젝트 결정 메모에서 Node 22를 지원 대상에서 제외하고 최소 요구 버전을 24.0보다 높은 수준으로 올렸습니다. Node 20과 Node 22는 작동하지 않으며, 24.9.0보다 오래된 Node 24 릴리스도 작동하지 않습니다. 2026년 10월 27일 기준으로 게시된 npm 빌드에는 자체 engines 필드가 없었습니다. 따라서 npm은 dsh 자체의 Node 요구 사항을 기준으로 경고하거나 차단할 수 없었고, 지원되지 않는 런타임은 이후 단계에서 대신 실패했습니다. 2026년 11월 6일에 확인한 게시된 0.2.2-rc.1 패키지는 이제 engines.node에 >=24.9.0을 선언합니다. npm은 기본적으로 경고하며, engine-strict이 활성화된 경우 호환되지 않는 런타임을 거부합니다. 먼저 node -v를 확인하십시오. 최소 요구 버전을 충족하는 모든 Node 릴리스에는 npm 11 이상이 포함되어 있으며, 여기에는 npm 11.2.0에서 도입된 npx range-cache 수정 사항도 포함됩니다.

npx가 캐시된 dsh 대신 최신 dsh를 사용하도록 강제하려면 어떻게 합니까?

npm 10.9.3과 최신 npm은 일반 패키지 이름에 대해 이미 레지스트리를 다시 확인합니다. 단, 현재 디렉터리가 dsh가 설치된 프로젝트이면 npx는 해당 로컬 복사본을 실행합니다. 레지스트리의 latest 태그를 명시적으로 요청하려면 npx @deepseek-ai/dsh@latest --version를 사용하십시오. npm 11.2.0에서 변경된 것은 일반 이름이 아니라 버전 범위의 최신성 확인 방식입니다. npm 11.2.0 이상에서는 npm cache npx rm --force로 npx 캐시를 지우고, npm 10에서는 rm -rf "$(npm config get cache)/_npx"로 해당 폴더를 삭제하십시오. 그런 다음 npx @deepseek-ai/dsh --version로 확인하십시오. npm cache clean --force은 다른 디렉터리를 지우므로 이 문제를 해결하지 못합니다.

@deepseek-ai/dsh@^0.1.0 설치가 실패하는 이유는 무엇입니까?

2026년 10월 27일 기준으로 npm은 ETARGET 오류 코드를 반환했으며, No matching version found for @deepseek-ai/dsh@^0.1.0.라는 줄이 표시되었습니다. 당시 게시된 모든 빌드는 0.2.0-rc.2 또는 0.2.1-alpha.2와 같은 prerelease였습니다. semver 범위는 범위 자체가 동일한 major, minor, patch 번호의 prerelease를 명시하지 않는 한 prerelease 버전과 일치하지 않습니다. 접미사를 포함한 정확한 버전 문자열을 설치하십시오. 존재하는 버전을 확인하려면 npm view @deepseek-ai/dsh versions --json를 실행하십시오. 버전 시퀀스에는 공백이 있기 때문입니다.

dsh를 전역으로 설치해야 합니까, 아니면 npx로 실행해야 합니까?

첫 실행에는 npx가 적합합니다. 패키지가 캐시 디렉터리에 유지되기 때문입니다. 또한 harness는 지속적인 프로필 상태를 생성합니다. 계속 작동해야 하는 용도에는 npm install -g @deepseek-ai/dsh@0.1.0-rc.7과 같은 버전 고정 전역 설치가 적합합니다. 버전은 직접 변경할 때만 바뀌기 때문입니다. 전역 설치 후 dsh 명령을 찾을 수 없다면 npm의 전역 bin 디렉터리가 PATH에 없다는 뜻입니다. npm prefix -g는 해당 디렉터리가 속한 root를 출력합니다.

DeepSeek Harness는 기반으로 삼을 만큼 안정적입니까?

프로젝트 자체의 설명에 따르면 아직 그렇지 않습니다. README에는 프로젝트가 developer preview 단계에 있고, 빠르게 반복 개발 중이며, 호환성을 깨는 변경 사항이 발생할 수 있다고 명시되어 있습니다. 0.1.0-rc.6과 0.1.0-rc.7 release candidate는 2026년 8월에 4일 간격으로 게시되었습니다. 0.2.0-rc.1과 0.2.0-rc.2는 2026년 9월에 하루 간격으로 게시되었고, 0.2.1-rc.1과 0.2.1-rc.2는 2026년 10월 같은 날 게시되었습니다. 지원되는 Node 범위도 2026년 10월에 변경되었습니다. 정확한 버전을 고정하고, 어떤 가이드가 아니라 해당 고정 빌드의 --help을 읽으십시오. 직접 작성한 메모에는 날짜를 기록하십시오. 그래야 메모가 얼마나 오래되었는지 확인할 수 있습니다.

이 글이 도움이 되었나요?