DeepSeek Harness 설치 오류 및 버전 문제 해결 방법

DeepSeek Harness 설치의 실체

DeepSeek Harness 설치는 npx @deepseek-ai/dsh web 명령어 하나로 이루어집니다. 별도의 설치 프로그램이나 설정해야 할 서비스는 없습니다. 사용자가 겪는 대부분의 문제는 설치 과정 자체가 아니라 버전 해결에서 발생합니다. 즉, npx가 오늘 어떤 버전의 @deepseek-ai/dsh 빌드를 실행하기로 결정했는지, 그리고 현재 설치된 Node.js 버전이 이를 실행할 수 있는지의 문제입니다.

아래의 모든 내용은 다음 두 가지 사실을 기반으로 합니다. 첫째, 지금까지 npm에 게시된 모든 @deepseek-ai/dsh 버전은 릴리스 후보(release candidate)이며, latest 태그는 그중 하나를 가리키고 있습니다. 2026년 8월 18일 기준으로 해당 버전은 2026년 8월 17일에 게시된 0.1.0-rc.7입니다. 둘째, 프로젝트 README에 따르면 이 하네스는 개발자 프리뷰(developer preview) 단계에 있으며, 빠르게 반복 개선되고 있어 호환성을 깨뜨리는 변경 사항이 발생할 수 있습니다. 지난주에 작동하던 플래그가 이번 주에는 사라질 수 있습니다. 이 도구 위에 무언가를 구축하기 전에 반드시 버전을 고정하십시오.

먼저 몇 가지 용어를 정의합니다. dsh는 DeepSeek Harness 명령줄 도구입니다. Node.js는 이 도구가 필요로 하는 JavaScript 런타임입니다. npx는 npm(node package manager)과 함께 제공되는 패키지 실행 도구로, 패키지를 영구적으로 설치하는 대신 필요할 때마다 가져와서 실행합니다.

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

저장소 루트의 package.json은 2026년 8월 18일 버전 0.1.0-rc.7 기준으로 "engines": {"node": "^22.19.0 || >=24.0.0"}을 명시합니다. 따라서 Node 22.19.0 이상(22 라인 내) 또는 Node 24 이상이 필요합니다. Node 20은 지원하지 않습니다.

다른 작업을 시작하기 전에 현재 버전을 확인하십시오.

node -v
npm -v

이 부분에서 많은 사용자가 당황합니다. 배포된 @deepseek-ai/dsh 패키지에는 자체적인 engines 필드가 없습니다. 모노레포 루트에만 선언되어 있으며, 해당 루트 파일은 npm에 배포되지 않습니다. 따라서 npm은 확인할 대상이 없으므로 EBADENGINE 경고를 출력하지 않으며, 설치를 거부하지도 않습니다. Node 20 환경에서 설치는 성공한 것처럼 보이지만, 이후 로드된 코드가 현재 런타임에서 지원하지 않는 문법이나 API를 호출할 때 실패가 발생합니다. 어떤 모듈이 먼저 로드되느냐에 따라 첫 번째 실패 지점이 달라지므로, 검색할 수 있는 단일 오류 문자열은 존재하지 않습니다. 충돌 메시지를 읽기보다 node -v을 확인하십시오.

사용 중인 Node 버전이 너무 낮다면, VPS에서 가장 영향이 적은 해결책은 nvm(node version manager)을 사용하는 것입니다. nvm은 홈 디렉터리 아래에 설치되므로 시스템 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.으로 시작하는 버전이 출력되어야 합니다. 만약 셸에서 여전히 이전 버전을 보고한다면 nvm 셸 함수가 로드되지 않은 것이므로, 새로운 로그인 셸을 열고 다시 시도하십시오. 2026년 8월 기준으로 Node 24.19.0이 활성 LTS(long term support) 릴리스이며, 아래에서 다룰 두 번째 이유 때문에 이 버전을 사용하는 것이 더 좋습니다.

npx가 매일 다른 버전을 실행하는 이유는 무엇입니까?

npx @deepseek-ai/dsh web는 버전을 명시하지 않으므로, npx는 latest 태그가 가리키는 버전을 레지스트리에 요청합니다. 해당 태그는 계속 변경됩니다. DeepSeek가 0.1.0-rc.8을 배포하면, 메모에 적어둔 명령어가 별도의 알림이나 변경 로그 없이 다른 코드를 실행하기 시작합니다.

명령줄에서 모든 가변 요소를 직접 확인할 수 있습니다.

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

dist-tags은 현재 latest이 무엇을 가리키는지 보여줍니다. 2026년 8월 18일 기준으로 latest와 next은 모두 0.1.0-rc.7을 가리키고 있었으므로, 전환할 수 있는 별도의 안정화 채널은 존재하지 않습니다. versions 목록은 중간에 누락된 부분이 있어 더 흥미롭습니다. 0.0.1-rc.1, 0.0.1-rc.2, 0.0.1-rc.5, 0.1.0-rc.2, 0.1.0-rc.3, 0.1.0-rc.6, 0.1.0-rc.7가 그 예입니다. 일부 릴리스 후보 버전이 배포되지 않았기 때문에 해당 시퀀스에서 숫자가 빠져 있습니다. 배포 스크립트에서 다음 -rc.N을 추측하면 실패할 가능성이 높으므로, 숫자를 세는 대신 목록을 직접 읽어야 합니다.

왜 npx는 계속 이전 버전을 실행합니까?

이는 앞선 불만 사항과 정반대되는 경우이며, 어떤 npm 버전을 실행하느냐에 따라 두 가지 상황 모두 발생할 수 있습니다.

npx는 npm 캐시 내부의 _npx이라는 폴더에 tarball 캐시와는 별도로 자체 패키지 디렉터리를 유지합니다. 해당 경로를 출력하여 확인해 보십시오.

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

수년간 npx는 패키지 이름만 지정된 경우 해당 위치에서 발견되는 모든 것을 재사용했으며, 레지스트리에 다시 확인을 요청하지 않았습니다. npm 11.2.0 버전에서 이 동작이 변경되었습니다. 사양이 단순 이름이나 버전 범위인 경우, 이제 npx는 매니페스트를 가져온 뒤 레지스트리가 반환한 결과와 해결된 tarball이 일치할 때만 캐시된 복사본을 재사용합니다.

어떤 동작이 수행되는지는 사용 중인 Node 릴리스에 의해 결정됩니다. Node는 특정 버전의 npm을 번들로 포함하기 때문입니다.

• Node 20.20.2는 npm 10.8.2를 포함합니다.
• Node 22.19.0은 npm 10.9.3을 포함합니다.
• Node 22.23.2(최신 22 릴리스)는 npm 10.9.8을 포함합니다.
• Node 24.19.0은 npm 11.17.0을 포함합니다.

따라서 공식적으로 지원되는 Node 22 라인 전체는 11.2.0보다 이전 버전의 npm을 제공합니다. Node 22에서 단순 npx @deepseek-ai/dsh web를 실행하면 몇 주 전에 캐시된 릴리스 후보(release candidate)를 계속 실행하게 됩니다. 반면 Node 24에서 동일한 명령을 실행하면 매번 다시 해결 과정을 거칩니다. 하나의 명령이 두 가지 방식으로 동작하지만, 그 어느 쪽도 사용자에게 경고를 보내지 않습니다. 도구에 직접 버전을 확인하십시오.

npx @deepseek-ai/dsh --version

npx 캐시 비우기

npm 11.2.0 이상 버전에는 전용 하위 명령이 있습니다.

npm cache npx ls
npm cache npx rm --force

--force 옵션 없이는 npm이 모든 것을 삭제하는 것을 거부하며 Please use --force to remove entire npx cache를 출력합니다. 모든 항목이 아닌 특정 키에 해당하는 항목만 삭제하려면 먼저 npm cache npx ls를 사용하십시오.

npm 10 버전에는 해당 하위 명령이 존재하지 않으므로 디렉터리를 직접 삭제해야 합니다.

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

npm cache clean --force은 이 상황에서 도움이 되지 않습니다. 이는 tarball 저장소인 _cacache만 비울 뿐, _npx은 그대로 둡니다. 이러한 분리 정책 때문에 이후 npm에 npm cache npx 하위 명령이 추가된 것입니다. _npx을 비우는 것은 영구적인 손실을 초래하지 않습니다. 이곳에는 다운로드된 패키지만 저장되며, 사용자의 하니스(harness) 상태는 $DSH_HOME/profiles/<name> 아래에 별도로 존재하여 영향을 받지 않기 때문입니다.

정확한 릴리스 후보(release candidate) 버전을 고정하려면 어떻게 해야 합니까?

-rc.N 부분을 포함한 전체 버전 문자열을 명시하십시오.

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

스크립트에서는 --yes 설정이 중요합니다. 이 설정이 없으면 npx는 이전에 본 적 없는 패키지를 설치하기 전에 사용자에게 확인을 요청하며, 응답이 올 때까지 무한정 대기하기 때문입니다.

정확한 버전을 지정하는 것은 속도 측면에서도 유리합니다. npx는 입력한 사양 문자열을 기준으로 캐시 디렉터리를 결정합니다. 정확한 버전이 입력되면 이미 설치된 패키지 ID와 비교한 뒤 레지스트리 통신 없이 즉시 실행합니다. npm 11.2.0 이상 버전에서는 패키지 이름만 입력할 경우 실행할 때마다 매니페스트를 가져오는 비용이 발생합니다.

전역 설치(global install) 시에도 동일한 방식으로 버전을 고정할 수 있으며, 이를 통해 짧은 명령어로 실행할 수 있습니다.

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

@deepseek-ai/dsh@^0.1.0에 대해 일치하는 버전을 찾을 수 없습니다

캐럿(caret)이나 틸드(tilde) 범위를 사용하면 이 패키지에서 오류가 발생합니다. npm install -g @deepseek-ai/dsh@^0.1.0는 오류 코드 ETARGET와 함께 No matching version found for @deepseek-ai/dsh@^0.1.0.이라는 메시지를 반환합니다. 레지스트리에는 문제가 없습니다. 이는 semver 규칙 때문입니다. 버전 범위 자체에 프리릴리스(prerelease)가 명시되지 않은 경우, 버전 범위는 프리릴리스 버전과 일치하지 않습니다. 이 패키지의 모든 게시된 빌드는 -rc.N이며, 이는 프리릴리스에 해당하므로 ^0.1.0은 아무것도 일치시키지 못합니다. 정확한 버전을 기입하십시오.

이 규칙에는 유용한 부수 효과가 있습니다. 범위 지정 방식으로는 새로운 릴리스 후보로 의도치 않게 버전이 변경될 수 없으므로, 버전 고정 상태가 모호해질 염려가 없습니다. 사용자는 항상 정확한 버전을 사용하거나, 아니면 변경되는 태그를 사용하거나 둘 중 하나를 선택하게 됩니다.

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

처음 살펴볼 때는 npx를 사용하십시오. 캐시 디렉터리 외에는 아무것도 남지 않으며, 이 디렉터리는 삭제 방법을 알고 있으므로 문제가 없습니다. 재부팅 후에도 계속 작동해야 하는 도구라면, 예를 들어 VPS에서 계속 실행 중인 코딩 에이전트와 같은 경우에는 고정된 버전으로 전역 설치를 수행하십시오.

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

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

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

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

개발자 프리뷰가 재현성에 의미하는 것

0.1.0-rc.6은 2026년 8월 13일에, 0.1.0-rc.7는 2026년 8월 17일에 릴리스되었습니다. 불과 4일 차이입니다. 이 정도 속도라면 한 달 전에 작성된 지침은 더 이상 존재하지 않는 명령행을 설명할 수 있으며, 이 페이지도 예외는 아닙니다. 본인의 메모를 포함하여 작성하는 모든 버전 관련 주장에는 날짜를 명시하십시오.

프리뷰 환경에서 살아남기 위해서는 두 가지 습관이 필요합니다. 모든 명령과 스크립트에 정확한 버전을 고정하여, 서버를 재구축할 때 동일한 환경(harness)이 생성되도록 하십시오. 그런 다음 가이드가 아닌, 고정된 빌드에서 출력되는 도움말을 직접 읽으십시오.

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 프로필은 처음 사용할 때 제공된 템플릿으로부터 스스로 생성됩니다. 해당 디렉터리는 또한 harness가 API 키, 모델 및 엔드포인트 설정을 읽어오는 곳이기도 하므로, 고정된 버전과 작동 가능한 구성은 각각 별도로 올바르게 설정해야 합니다. 내장 번들은 현재 실행 중인 dsh 설치본을 기준으로 해결되는데, 이는 고정된 버전을 변경하면 해당 번들도 함께 변경됨을 의미합니다. 외부 플러그인(out-of-tree plugins)은 다르게 동작합니다. 이들은 프로필 디렉터리에 위치하며, dsh plugin --profile <name> add <package>는 인수를 pnpm으로 전달하여 설치합니다. 따라서 pnpm이 PATH에 있어야 하며, 그렇지 않은 경우 dsh는 이를 명확하게 알립니다. 프로필 자체의 package.json이 해당 플러그인을 고정하므로, 완전한 고정은 파일 하나가 아닌 두 개를 모두 포함해야 합니다.

서버의 격리된 환경에서 Python 도구를 관리해 본 적이 있다면 이러한 분리 방식이 익숙할 것입니다. 도구 자체와 도구에 추가하는 항목은 서로 다른 곳에 고정됩니다. harness가 시작된 후에는 보통 버전보다는 네트워킹이 다음 문제가 되며, 이 지점부터는 원격 VPS에서 dsh 웹 UI에 접속하기와 VPS에 DeepSeek Harness 설치하기의 상세 가이드가 이어집니다.

실제로 마주하게 될 인자 오류

이 오류들은 CLI 자체 파서에서 발생하므로 릴리스 후보(release candidate) 라인 전반에서 안정적이며, 각 오류는 정확한 문제를 명시합니다.

error: --profile <name> is required

하위 명령이나 프로필 없이 npx @deepseek-ai/dsh를 실행했습니다. 기본 명령은 프로필을 부팅하므로 이름이 필요합니다. dsh web은 제공된 web 프로필을 자동으로 부팅해주기 때문에 --profile를 받지 않는 하위 명령입니다.

error: --patch needs a path

--patch 뒤에 아무것도 전달되지 않았습니다. 이 플래그는 반복 사용이 가능하며, 각 항목마다 하나의 파일 경로를 지정해야 합니다.

error: --dump-config and --dump-default-config are mutually exclusive

둘 중 하나를 선택하십시오. --dump-default-config은 제공된 번들 레이어를 출력하며 --patch을 허용하지 않습니다. --dump-config는 프로필에 대해 구성된 설정을 출력합니다. 두 명령 모두 하네스를 시작하지 않고 출력 후 종료하므로, 새로운 릴리스 후보에서 변경된 사항을 안전하게 확인하는 방법입니다.

error: plugin needs pnpm arguments to forward (e.g. add <package>)

dsh plugin --profile <name>에 전달할 인자가 주어지지 않았습니다. 이 하위 명령은 프로필이 없을 경우 초기화한 뒤 나머지 명령줄 인자를 pnpm으로 넘기므로, add @scope/dsh-plugin-example과 같은 인자가 필요합니다.

FAQ

DeepSeek Harness는 어떤 Node.js 버전이 필요한가요?

저장소의 루트 package.json에는 ^22.19.0 || >=24.0.0가 명시되어 있으며, 2026년 8월 18일 기준 버전은 0.1.0-rc.7입니다. 따라서 Node 22.19.0 이상(22 버전대) 또는 Node 24 이상이 필요합니다. Node 20에서는 동작하지 않습니다. 배포된 npm 패키지에는 별도의 engines 필드가 없으므로, npm이 경고를 보내거나 설치를 차단하지 않으며 런타임에 오류가 발생합니다. 먼저 node -v를 확인하십시오. Node 24는 npm 11을 포함하고 있어 npx 버전 재사용 문제를 해결하므로 더 나은 선택입니다.

npx가 캐시된 버전 대신 최신 dsh를 사용하도록 강제하려면 어떻게 하나요?

npm 11.2.0 이상에서는 npx @deepseek-ai/dsh이 실행될 때마다 레지스트리에서 패키지 이름을 다시 확인합니다. 모든 Node 22 릴리스에 포함된 npm 10에서는 그렇지 않습니다. npm 11의 경우 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 설치가 실패하는 이유는 무엇인가요?

npm은 No matching version found for @deepseek-ai/dsh@^0.1.0.라는 문구와 함께 ETARGET 오류 코드를 반환합니다. 배포된 모든 빌드는 0.1.0-rc.7과 같은 프리릴리스 버전이며, semver 범위는 범위 자체에 프리릴리스가 명시되지 않는 한 해당 버전을 매칭하지 않습니다. -rc.N 접미사를 포함한 정확한 버전 문자열을 설치하십시오. 릴리스 후보가 배포되지 않은 구간이 존재하므로, npm view @deepseek-ai/dsh versions --json를 실행하여 존재하는 버전을 확인하십시오.

dsh를 전역으로 설치해야 하나요, 아니면 npx로 실행해야 하나요?

npx는 캐시 디렉터리 외에 아무것도 남지 않으므로 처음 살펴볼 때 적합합니다. npm install -g @deepseek-ai/dsh@0.1.0-rc.7과 같이 버전을 고정한 전역 설치는 지속적인 작업이 필요한 경우에 적합합니다. 사용자가 직접 변경하기 전까지는 버전이 바뀌지 않기 때문입니다. 전역 설치 후 dsh 명령을 찾을 수 없다면 npm의 전역 bin 디렉터리가 PATH에 누락된 것이며, npm prefix -g를 실행하면 해당 디렉터리의 루트 경로를 확인할 수 있습니다.

DeepSeek Harness는 기반 시스템으로 사용할 만큼 안정적인가요?

아직은 그렇지 않습니다. README에 따르면 이 프로젝트는 개발자 프리뷰 단계이며, 빠르게 반복 수정되고 있고 호환성을 깨뜨리는 변경 사항이 발생할 예정입니다. 릴리스 후보 0.1.0-rc.6과 0.1.0-rc.7은 2026년 8월 4일 간격으로 배포되었습니다. 특정 버전을 고정하고, 가이드 문서가 아닌 해당 고정 빌드의 --help을 읽으십시오. 기록한 메모에 날짜를 기입하여 정보가 얼마나 오래되었는지 파악할 수 있도록 하십시오.