가이드

작성자 Matt Connor 2026-08-18 · 업데이트됨 2026-08-26

dsh 설정 방법: API 키 및 모델 엔드포인트 구성

Q: dsh는 DeepSeek API 키를 어디에 저장합니까?

$DSH_HOME/.credentials.yaml에 저장하며, DSH_HOME을 직접 설정하지 않았다면 기본 경로는 ~/.dsh/.credentials.yaml입니다. Models 페이지에서 키를 입력하면 해당 파일에 기록되고, 설정에는 참조값만 저장되므로 비밀 정보는 한 파일에만 존재합니다. stat -c '%a %n' ~/.dsh/.credentials.yaml 명령으로 파일 권한을 확인하고, 600보다 느슨하다면 600으로 변경하십시오. 사용자 지정 공급자를 사용하면 apiKeyEnv 환경 변수를 지정하여 파일 사용을 완전히 피할 수 있습니다.

Q: dsh가 DeepSeek API 대신 로컬 모델을 사용하게 하려면 어떻게 합니까?

기본 URL이 로컬 OpenAI 호환 엔드포인트인 사용자 지정 공급자를 추가하십시오. Ollama의 경우 http://127.0.0.1:11434/v1을 사용하며, api: openai-completions과 ollama list에서 정확히 복사한 모델명 id를 입력하십시오. Ollama는 API 키 값을 요구하지만 실제로는 무시하므로 비어 있지 않은 문자열이면 무엇이든 가능합니다. dsh 설정을 편집하기 전에 curl -s http://127.0.0.1:11434/v1/models로 엔드포인트 응답을 확인하십시오. 엔드포인트가 죽어 있는 경우와 설정이 잘못된 경우 발생하는 오류가 비슷하기 때문입니다.

Q: 변수를 설정했는데도 dsh가 MISSING_CREDENTIAL을 보고하는 이유는 무엇입니까?

dsh는 apiKeyEnv에 지정된 변수를 자신의 프로세스 환경에서 읽기 때문입니다. 셸에서 export한 변수는 systemd 서비스, 다른 사용자의 세션, 또는 변수를 export하기 전에 시작된 프로세스에는 전달되지 않습니다. 해당 값을 유닛용 EnvironmentFile 파일(권한 600)에 넣거나, dsh를 시작하는 동일한 셸에서 export하십시오. 실행 중인 프로세스가 실제로 어떤 값을 가지고 있는지 확인하려면 sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ을 사용하십시오.

Q: dsh는 어떤 Node.js 버전이 필요합니까?

Node.js 22.19 이상(22 버전대) 또는 24 이상이 필요합니다. Node 23은 지원 범위에 포함되지 않습니다. 다른 작업을 수행하기 전에 node -v을 실행하십시오. 지원되지 않는 런타임으로 인한 시작 실패는 설치가 깨진 것처럼 보여 사용자가 런타임 대신 패키지를 재설치하게 만들기 때문입니다.

dsh 설정 파일 저장 경로와 DeepSeek API 키 및 Ollama 로컬 엔드포인트 연결법을 설명합니다. Node.js 22.19 이상 버전 요구 사항과 데이터 보안을 위한 루프백 바인딩 및 보안 설정 정보를 확인하십시오.

dsh의 설정 저장 위치

dsh(DeepSeek Harness)는 $DSH_HOME 디렉터리 하나에 설정을 저장하며, 기본값은 ~/.dsh입니다. 웹 UI에서 설정한 모든 내용은 해당 위치에 일반 파일 형태로 기록됩니다. 이 디렉터리를 다른 서버로 복사하면 새 서버에서도 이전 서버와 동일하게 동작합니다.

사용자가 다루게 될 모든 항목은 다음 4개의 경로에 포함되어 있습니다.

~/.dsh/settings.yaml에는 직접 작성하거나 UI를 통해 생성한 설정이 저장되며, 여기에는 공급자 및 모델 라우팅 정보가 포함됩니다.
~/.dsh/.credentials.yaml에는 보안 정보가 저장됩니다. 설정 파일에는 자격 증명에 대한 참조만 기록되므로, 실제 키 값은 이 파일 내에 존재합니다.
~/.dsh/profiles/에는 명명된 프로필이 저장되며, ~/.dsh/storages/에는 저장된 세션이 위치합니다.
~/.dsh/cordis.patch.yml은 사용자가 직접 적용하는 패치 계층입니다. 모든 프로필의 내장 설정 위에 이 계층이 적용됩니다.

DeepSeek는 2026년 8월 17일에 MIT 라이선스를 적용한 개발자 프리뷰 버전으로 이 도구를 공개했으며, README에 따르면 향후 호환성을 깨뜨리는 변경 사항이 있을 예정입니다. 본 가이드의 필드명과 경로는 2026년 8월 기준 저장소 문서를 따릅니다. 프리뷰 버전은 릴리스마다 명칭이 변경될 수 있으므로, 본 가이드를 포함한 어떤 가이드의 설정을 복사하기 전에도 반드시 설치된 버전의 공식 문서와 대조하여 확인하십시오.

최소한의 초기 실행 요건

dsh는 Node.js 22.19 이상(22.x 버전대) 또는 24 이상이 필요합니다. Node 23은 이 범위에 포함되지 않습니다. 버전 불일치가 발생하면 시작 시 실패하며 오류 메시지가 패키지 손상처럼 보일 수 있으므로, 먼저 버전을 확인하십시오.

node -v
npx @deepseek-ai/dsh web

npx은 npm 레지스트리에서 패키지를 다운로드하고 http://127.0.0.1:3080에서 웹 UI를 시작합니다. 이 프로세스는 루프백 주소에 바인딩되므로, 방화벽에서 허용하더라도 다른 기기에서는 해당 포트에 접근할 수 없습니다. VPS를 사용하는 경우, 3080 포트를 인터넷에 개방하는 대신 SSH를 통해 포트 포워딩을 수행하십시오. 출력된 URL이 혼란스럽다면 dsh가 해당 주소에서 시작하는 이유를 참조하여 루프백 바인딩이 보호하는 범위와 그렇지 않은 범위를 확인하십시오.

ssh -N -L 3080:127.0.0.1:3080 you@your-server

노트북에서 http://127.0.0.1:3080을 열고 Settings 및 Models 메뉴로 이동하십시오. DeepSeek 카드에는 API 키 입력란이 하나 있습니다. platform.deepseek.com에서 발급받은 키를 붙여넣고 저장하십시오. 실행 중인 서버가 자격 증명을 저장하고 실시간으로 참조를 해결하므로, 재시작 없이 즉시 모델 경로를 사용할 수 있습니다. 원격 서버의 dsh 웹 UI에 접근하기에서는 터널링 및 리버스 프록시 설정을 다루며, VPS에 DeepSeek Harness 설치하기에서는 이 가이드가 전제로 하는 서버 준비 과정을 설명합니다.

저장 후 앱이 생성한 항목을 확인하십시오.

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

settings.yaml, .credentials.yaml 및 profiles/이 보여야 합니다. stat가 600 이외의 모드를 출력한다면 chmod 600 ~/.dsh/.credentials.yaml을 실행하십시오. 자격 증명 파일이 그룹이나 전체 사용자에게 읽기 권한으로 설정되어 있으면 서버 내의 다른 모든 계정이 귀하의 키를 탈취할 수 있습니다.

브라우저 없이 첫 실행을 하려면 다음 명령 하나면 충분합니다.

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

헤드리스 프로필은 단일 세션을 실행하고 최종 답변을 출력합니다.

환경 변수 또는 설정 파일

dsh에 키를 제공하는 방법은 두 가지가 있으며, 이 둘은 서로 호환되지 않습니다.

카탈로그 제공자(DeepSeek, Anthropic, OpenAI 및 기타 내장 목록에 포함된 제공자)는 Models 페이지를 통해 키를 입력받습니다. 값은 ~/.dsh/.credentials.yaml에 저장되며, 설정에는 해당 값에 대한 참조만 유지됩니다. Web UI는 키를 저장한 후에는 다시 표시하지 않습니다.

사용자 지정 제공자는 apiKeyEnv을 사용하여 환경 변수를 지정할 수 있습니다. 이는 ~/.dsh/settings.yaml에 대한 문서에서 제시하는 형식입니다.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

먼저 Web UI를 통해 제공자를 하나 추가한 다음, ~/.dsh/settings.yaml을 열어 해당 파일이 작성한 구조를 복사하십시오. 개발자 프리뷰 기간에는 중첩 구조가 변경될 가능성이 가장 높으며, 애플리케이션이 방금 작성한 파일은 항상 최신 상태를 유지합니다.

apiKeyEnv은 로그인 셸이 아닌 dsh 프로세스의 환경에서 읽어옵니다. 대화형 세션에서 export한 키는 systemd 유닛에서 볼 수 없으므로, 수동으로 dsh web를 입력할 때 작동하던 설정이 서비스 환경에서는 MISSING_CREDENTIAL 오류를 반환하게 됩니다. 유닛 전용 파일을 별도로 제공하십시오.

[Service]
EnvironmentFile=/etc/dsh/dsh.env

해당 파일의 권한은 600으로 유지하고, 서비스를 실행하는 사용자가 소유하도록 설정하십시오.

모델 선택 및 이름을 변경할 수 없는 ID

설정된 모든 공급자는 모델 선택기에 나타납니다. 모델을 선택하면 해당 모델이 새 세션의 기본값으로 지정됩니다. 기존 세션은 기록된 모델을 그대로 유지하므로, 모델을 전환해도 이전 대화 내용이 다시 작성되지는 않습니다.

공급자 ID는 영구적입니다. 요청, 저장된 세션, 모델 기본값 및 자격 증명 참조가 모두 이 ID를 가리키므로 이름 변경 버튼은 존재하지 않습니다. ID를 변경하려면 새 공급자를 생성하고 기존 공급자를 삭제해야 합니다. local-ollama 대신 test2와 같이 계속 사용할 수 있는 이름을 선택하십시오.

별도로 선언하지 않는 한 모델은 텍스트 전용으로 작동합니다. 이미지 지원을 선언하려면 모델 항목에 input: [text, image]을 추가하거나, 카탈로그에 설명되지 않은 모델에 대한 대체 설정으로 경로 수준에서 defaultInput을 설정하십시오. DeepSeek의 자체 chat-completions 경로는 텍스트 전용이며 다른 방식으로 구성할 수 없으므로, 해당 경로에 첨부된 이미지는 전송되기 전에 거부됩니다.

dsh를 로컬 엔드포인트로 지정하여 코드를 서버 내부에 유지하기

Ollama는 http://127.0.0.1:11434/v1에서 OpenAI 호환 API를 제공합니다. dsh는 커스텀 프로바이더를 통해 모든 OpenAI 호환 베이스 URL과 통신하므로, 중간 단계 없이 두 서비스를 직접 연결할 수 있습니다. 먼저 모델 서버를 설정하십시오. Ollama를 사용하여 VPS에 LLM 직접 호스팅하기 문서에서 설치 및 모델 풀(pull) 방법을 다룹니다.

dsh를 건드리기 전에 엔드포인트가 응답하는지 확인하십시오.

ollama list
curl -s http://127.0.0.1:11434/v1/models

ollama list는 풀링한 모든 모델의 정확한 태그를 출력합니다. 해당 문자열을 복사하십시오. curl은 동일한 모델 목록을 JSON 형식으로 반환합니다. 빈 목록이 출력된다면 Ollama가 실행 중이지만 풀링된 모델이 없는 상태입니다. Connection refused이 출력된다면 Ollama가 실행 중이지 않거나 11434 포트에서 대기 중이지 않은 것입니다.

이제 프로바이더를 추가하십시오. Ollama는 API 키 필드를 요구하지만 그 값은 무시하므로, 비어 있지 않은 문자열이면 무엇이든 작동합니다.

llm-pi-ai:
  providers:
    local-ollama:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      models:
        - id: <the exact tag printed by ollama list>

dsh 프로세스가 인식할 수 있도록 환경 변수를 내보내십시오(export).

sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.env

이 과정에서 발생하는 대부분의 실패는 다음 세 가지 경우에 해당합니다. MISSING_CREDENTIAL는 dsh가 apiKeyEnv에 지정된 변수를 읽을 수 없음을 의미하므로, 터미널 환경이 아닌 프로세스의 환경을 확인하십시오. UNKNOWN_MODEL는 id가 설정된 모델과 일치하지 않음을 의미하므로, 콜론 뒤의 태그를 포함하여 ollama list과 한 글자씩 비교하십시오. 사용 가능한 모델을 가져오는 도중 발생하는 401 오류는 모델 탐색 과정에서 발생하며, 이는 베이스 URL에 GET /models을 호출합니다. 해당 경로를 제공하지 않는 엔드포인트는 모델 이름을 직접 입력해야 합니다.

또 다른 함정은 베이스 URL입니다. /v1을 생략하면 요청이 Ollama가 처리하지 않는 경로로 전달되어 404 오류가 발생하고 모델이 실행되지 않습니다. 해당 접미사는 OpenAI 호환 인터페이스의 일부이지 장식이 아닙니다.

Ollama를 다른 머신에서 실행하는 경우 해당 머신의 주소가 베이스 URL이 되며, 프롬프트가 일반 HTTP를 통해 평문으로 네트워크를 통과하게 됩니다. 같은 호스트에서 실행하거나, TLS(전송 계층 보안) 및 인증을 적용하여 보호하십시오. 노출된 Ollama 엔드포인트 보안 설정하기를 참조하십시오.

모드별 데이터 외부 전송 범위

DeepSeek 키를 사용하면 모든 요청이 DeepSeek API로 전송됩니다. 해당 요청에는 프롬프트, 에이전트가 답변을 위해 읽은 파일 내용, 실행한 명령어의 출력 결과, 그리고 에이전트가 포함하기로 선택한 도구 결과가 포함됩니다. 에이전트가 파일을 열 때마다 소스 코드가 해당 페이로드에 포함됩니다. 이것이 호스팅 모델의 작동 방식이며, 에이전트를 시작할 디렉터리를 신중하게 선택해야 하는 이유입니다.

다른 카탈로그 제공업체나 기업용 게이트웨이를 사용하는 경우, 동일한 페이로드가 해당 업체로 전송됩니다. 기본 URL(base URL)을 통해 전송 위치를 정확히 확인할 수 있습니다.

로컬 엔드포인트를 사용하는 경우, 모델 요청은 127.0.0.1:11434로 전달되며 장치 내부에서 처리됩니다. 코드의 어떤 부분도 모델 제공업체로 전송되지 않습니다. 다만 세 가지 요소는 여전히 네트워크를 통과합니다. npx은 npm 레지스트리에서 패키지를 다운로드합니다. 에이전트가 실행하는 모든 도구는 연결된 MCP(Model Context Protocol) 서버를 포함하여 독자적으로 인터넷에 접근할 수 있으며, 이는 VPS에서 MCP 서버 실행하기에서 자세히 다룹니다. 플러그인도 같은 범주에 속합니다. 플러그인을 설치하면 작성자의 코드가 에이전트의 권한으로 실행되므로, 플러그인 설치 전 접근 범위 확인하기를 수행하는 것이 좋습니다. 또한 텔레메트리 기능을 켜는 경우에도 네트워크 통신이 발생합니다.

텔레메트리는 사용자가 동의하기 전까지 비활성화 상태입니다. DSH_TELEMETRY_MODE은 동의 설정 스위치이며, 값이 설정되지 않았거나 비어 있거나 인식할 수 없는 경우 DISABLED로 처리됩니다. 이 상태에서는 dsh가 OpenTelemetry(OTel) 공급자, 프로세서, 내보내기(exporter)를 구성하지 않으므로, 새로운 프로필은 어떠한 텔레메트리 네트워크 요청도 보내지 않습니다. FEEDBACK_ONLY은 피드백 기반 세션 로그 공유에 동의하는 설정입니다. FULL는 런처 보고를 허용합니다. 세션 피드는 세션 내용, 도구 데이터, 프롬프트, 작업 공간 경로를 내보낼 수 있으므로, FULL를 사용하는 것은 작업 내용을 DeepSeek으로 전송하는 것과 동일하게 간주해야 합니다.

모드 문자열 설정에 의존하지 않는 확실한 차단을 원한다면 DSH_TELEMETRY_DISABLED=1을 설정하십시오. 비어 있지 않은 모든 값은 강제적인 거부(opt-out)로 간주되며, 실행 시작 전에 읽히므로 프로젝트 코드 내에서 세션 도중 이를 다시 활성화할 수 없습니다. 기본 수집기 주소는 harness-telemetry.deepseeksvc.com이며, 방화벽 로그를 확인할 때 유용한 정보입니다.

설정을 신뢰하기보다 직접 검증하십시오. 작업이 실행 중일 때 해당 프로세스가 유지하고 있는 아웃바운드 연결 목록을 확인하십시오.

sudo ss -tnp | grep -i node

로컬 모델 모드에서는 11434에 대한 루프백 연결만 보여야 하며, 공용 주소로의 연결은 없어야 합니다. 그 외의 연결이 확인된다면 계속 진행하기 전에 해당 연결의 정체를 파악해야 합니다. 코딩 에이전트가 외부로 전송하는 데이터에서는 다른 환경에서 동일한 검사를 수행하는 방법과 결과를 해석하는 방법을 설명합니다.

비밀 정보를 저장해서는 안 되는 곳

셸 히스토리. export DEEPSEEK_API_KEY=sk-...은 ~/.bash_history에 평문으로 기록되며, 키를 교체한 후에도 오랫동안 남아 있습니다. HISTCONTROL=ignorespace이 설정된 경우 명령어 앞에 공백을 추가하거나, 셸을 거치지 말고 모드 600으로 설정된 파일에 값을 직접 작성하십시오.
커밋된 도트파일. 도트파일을 git으로 관리하는 경우 ~/.bashrc이나 ~/.zshrc에 포함된 키는 git add 한 번으로 공개 저장소에 노출될 수 있습니다. 푸시하기 전에 해당 저장소에서 git grep -I -n 'sk-'를 실행하십시오.
settings.yaml. 사용자 지정 공급자에는 apiKeyEnv을 사용하여 파일에 비밀 정보 대신 변수 이름이 담기도록 하십시오. 설정 파일은 이슈 리포트나 지원 채팅에 복사되어 붙여넣어지기 쉽지만, 자격 증명 파일은 그렇지 않습니다.
env의 출력 및 터미널 스크린샷. 전체 환경 변수를 출력하는 모든 작업은 키를 함께 노출합니다.
백업. ~/.dsh은 백업할 가치가 있지만, 그 안의 .credentials.yaml는 활성 상태의 비밀 정보입니다. 해당 파일을 제외하거나 아카이브를 암호화하십시오.

이 규칙들은 dsh에만 국한되지 않으며, Compose 환경 파일에서 비밀 정보 제외하기에서 동일 서버의 컨테이너 측면에서 발생하는 같은 문제를 다룹니다.

개발자 프리미엄 버전 사용하기

테스트를 마친 버전은 고정(pin)하십시오. 프리뷰 버전은 패치 릴리스에서 설정 키를 변경할 수 있으며, 이 경우 제공자가 설정을 불러오지 못할 수 있습니다. 고정한 설치본이 실행을 거부하거나 npx이 의도하지 않은 빌드를 계속 제공한다면, 프리뷰 버전에서 발생하는 설치 및 버전 오류 문서를 참조하여 npx 캐시와 Node에 포함된 npm 문제를 해결하십시오. settings.yaml과 cordis.patch.yml는 자격 증명 파일을 제외하고 버전 관리 시스템에 포함하여, 업그레이드 후 변경 사항을 추적할 수 있도록 하십시오.

프로필이 의도대로 동작하지 않을 때는 두 가지 플래그가 유용합니다. --dump-default-config은 부팅 없이 구성된 기본 설정을 출력하며, --dump-config는 동일한 방식으로 사용자의 프로필에 대해 구성된 설정을 출력합니다. 이 두 결과를 비교하면 패치 계층에서 실제로 무엇이 변경되었는지 확인할 수 있으며, 이는 계층을 수동으로 읽는 것보다 훨씬 빠릅니다.

dsh --profile web --dump-config

업그레이드 후 문제가 발생하면 가장 먼저 이 명령을 실행하십시오. 릴리스 간에 이동된 키는 덤프에서 누락된 분기로 나타나며, 이 경우 재설치 대신 한 줄의 편집만으로 문제를 해결할 수 있습니다.

FAQ

dsh는 DeepSeek API 키를 어디에 저장합니까?

$DSH_HOME/.credentials.yaml에 저장하며, DSH_HOME을 직접 설정하지 않았다면 기본 경로는 ~/.dsh/.credentials.yaml입니다. Models 페이지에서 키를 입력하면 해당 파일에 기록되고, 설정에는 참조값만 저장되므로 비밀 정보는 한 파일에만 존재합니다. stat -c '%a %n' ~/.dsh/.credentials.yaml 명령으로 파일 권한을 확인하고, 600보다 느슨하다면 600으로 변경하십시오. 사용자 지정 공급자를 사용하면 apiKeyEnv 환경 변수를 지정하여 파일 사용을 완전히 피할 수 있습니다.

dsh가 DeepSeek API 대신 로컬 모델을 사용하게 하려면 어떻게 합니까?

기본 URL이 로컬 OpenAI 호환 엔드포인트인 사용자 지정 공급자를 추가하십시오. Ollama의 경우 http://127.0.0.1:11434/v1을 사용하며, api: openai-completions과 ollama list에서 정확히 복사한 모델명 id를 입력하십시오. Ollama는 API 키 값을 요구하지만 실제로는 무시하므로 비어 있지 않은 문자열이면 무엇이든 가능합니다. dsh 설정을 편집하기 전에 curl -s http://127.0.0.1:11434/v1/models로 엔드포인트 응답을 확인하십시오. 엔드포인트가 죽어 있는 경우와 설정이 잘못된 경우 발생하는 오류가 비슷하기 때문입니다.

dsh는 기본적으로 내 코드를 외부로 전송합니까?

호스팅된 모델을 사용하면 전송됩니다. 프롬프트와 에이전트가 읽은 파일 내용은 해당 공급업체로 보내는 API 요청에 포함됩니다. 로컬 엔드포인트를 사용하면 해당 요청은 루프백으로 전달되어 기기 내부에 머뭅니다. 텔레메트리는 별도의 피드이며 기본적으로 꺼져 있습니다. DSH_TELEMETRY_MODE는 설정되지 않았을 때 DISABLED으로 해석되며, 이 상태에서는 어떠한 익스포터도 생성되지 않습니다. 실행 시작 전에 읽히는 옵트아웃 설정을 하려면 DSH_TELEMETRY_DISABLED=1을 설정하십시오.

변수를 설정했는데도 dsh가 MISSING_CREDENTIAL을 보고하는 이유는 무엇입니까?

dsh는 apiKeyEnv에 지정된 변수를 자신의 프로세스 환경에서 읽기 때문입니다. 셸에서 export한 변수는 systemd 서비스, 다른 사용자의 세션, 또는 변수를 export하기 전에 시작된 프로세스에는 전달되지 않습니다. 해당 값을 유닛용 EnvironmentFile 파일(권한 600)에 넣거나, dsh를 시작하는 동일한 셸에서 export하십시오. 실행 중인 프로세스가 실제로 어떤 값을 가지고 있는지 확인하려면 sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ을 사용하십시오.

dsh는 어떤 Node.js 버전이 필요합니까?

Node.js 22.19 이상(22 버전대) 또는 24 이상이 필요합니다. Node 23은 지원 범위에 포함되지 않습니다. 다른 작업을 수행하기 전에 node -v을 실행하십시오. 지원되지 않는 런타임으로 인한 시작 실패는 설치가 깨진 것처럼 보여 사용자가 런타임 대신 패키지를 재설치하게 만들기 때문입니다.

#deepseek#dsh#agent-harness #api-keys #ollama #configuration