DeepSeek Harness: npx 실패와 포트 3080 고치기

또 다른 빠른 시작이 아닙니다

npx 빠른 시작은 npx @deepseek-ai/dsh web가 결국 URL을 찍는다고 가정합니다. 이 글은 첫 실행 트래픽의 다른 절반용입니다. 터미널이 멈추거나, 3080이 응답하지 않거나, UI는 뜨는데 채팅마다 API 오류로 죽습니다. 검색 가능한 목록인 문제 해결과 함께 쓰고, 여기에서는 확인 순서를 설명합니다. 변수 세 개를 한꺼번에 흔들지 않으려면요.

정확한 플래그는 업스트림 몫입니다. README와 이 페이지가 어긋나면 README가 이깁니다.

사다리 1 — DSH를 건드리기 전에 Node를 증명

업스트림 프리뷰는 Node.js ^22.19.0 또는 >=24.0.0을 요구합니다. npx를 칠 같은 셸에서 node -v와 npm -v. 다른 창의 nvm/fnm은 세지 않습니다.

엔진이 틀린 증상: 패키지 가져오기는 시작되다 engines 검사에서 실패하거나, node 자체가 없음. PATH를 고치고 터미널을 다시 연 뒤 재시도하세요. “멈춘 npx 안에서 Node를 올리는” 일은 하지 마세요.

사다리 2 — @deepseek-ai/dsh를 가져올 수 있게

첫 실행은 큰 의존성 트리를 내려받습니다. 실패는 타임아웃, 404, 아주 오래된 rc 캐시처럼 보입니다.

1. 스코프 확인: @deepseek-ai/dsh — 오타는 반나절을 날립니다.
2. 사내 미러가 뒤처지면 --registry=https://registry.npmjs.org로 재시도.
3. 네트워크와 스코프 오타를 배제한 뒤에야 독성 npx 캐시를 지웁니다.

터미널은 열어 두세요. 다운로드 중에 죽이면 반쯤 쓰인 캐시를 디버깅하게 됩니다.

사다리 3 — 포트 3080은 로컬 소켓 문제

Web UI는 흔히 http://127.0.0.1:3080/에 바인딩합니다. 다른 프로세스가 3080을 잡고 있으면 프로세스는 떠도 브라우저에 DSH가 안 보입니다.

• 점유자를 찾으세요(OS에 따라 netstat / lsof / 리소스 모니터).
• 멈추거나, 업스트림이 문서화한 포트 플래그로 시작하세요(커뮤니티는 dsh web에 --port를 자주 씁니다).
• 첫 테스트는 localhost에 두세요. 0.0.0.0 바인딩은 편의 팁이 아니라 보안 결정입니다.

터미널은 건강한데 페이지가 하얗다면 깨끗한 브라우저 프로필을 쓰세요 — 확장 기능이 로컬 스크립트를 막을 수 있습니다.

사다리 4 — UI는 있는데 채팅이 죽음(키와 자격 증명)

로컬 UI는 보통 제어면이지 오프라인 가중치가 아닙니다. DeepSeek 경유 호출에는 플랫폼 API 키가 필요합니다. 모델 id, 할당량, 붙여 넣을 때 생긴 공백을 확인하세요.

헤드리스/CLI 경로는 $DSH_HOME/.credentials.yaml(흔히 ~/.dsh/.credentials.yaml)를 읽을 수 있습니다. Unix에서 권한이 너무 열려 있으면 런타임이 파일을 거부합니다 — chmod 600이 흔한 수정입니다. 이 독립 사이트는 키를 발급하지 않습니다.

사다리 5 — 플러그인이 등장할 때 pnpm 부재

npx로 띄웠어도 dsh plugin add는 자주 pnpm을 호출합니다. 전역 pnpm이 없으면 “UI는 됐는데 설치 실패”로 보입니다. pnpm을 설치하고 bin을 PATH에 넣은 뒤 add를 재시도하세요 — 플러그인 가이드.

하지 말 것

• 포트를 잡는 동안 첫 워크스페이스를 홈 전체로 두지 마세요.
• 3080이 아직 불안정한데 커뮤니티 플러그인을 세 개 쌓지 마세요.
• 지난주 블로그를 CLI 법으로 취급하지 마세요 — 평가 시 프리뷰 버전을 고정하세요.

다음에 갈 곳

1. 건강한 설치 이야기: npx 빠른 시작.
2. OS 한 줄: 설치.
3. 증상별 목록: 문제 해결.
4. 돌아간 뒤에는 패키지 바다에 빠지기 전에 모드를 고르세요.