가이드

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

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: 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을 실행하십시오. 지원되지 않는 런타임으로 인한 시작 실패는 설치가 깨진 것처럼 보여, 사용자가 런타임 대신 패키지를 재설치하게 만드는 원인이 됩니다.

Linux 환경에서 dsh 설정 파일의 위치를 확인하고 DeepSeek API 키와 로컬 Ollama 엔드포인트를 구성하는 방법을 설명합니다. 데이터 전송 범위와 Node.js 버전 호환성 등 설정 시 주의사항을 상세히 다룹니다.

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 라인 기준) 또는 24 이상 버전이 필요합니다. Node 23은 해당 범위에 포함되지 않습니다. 버전 불일치가 발생하면 시작 단계에서 실패하며, 오류 메시지가 패키지 손상처럼 보일 수 있으므로 먼저 버전을 확인하십시오.

node -v
npx @deepseek-ai/dsh web

npx은 npm 레지스트리에서 패키지를 다운로드하고 http://127.0.0.1:3080에서 웹 UI를 시작합니다. 이 프로세스는 루프백 주소에 바인딩되므로, 방화벽에서 허용하더라도 다른 머신에서는 해당 포트에 접근할 수 없습니다. VPS를 사용하는 경우, 3080 포트를 인터넷에 개방하는 대신 SSH를 통해 포트 포워딩을 수행하십시오.

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과 통신하므로, 중간 단계 없이 두 서비스를 직접 연결할 수 있습니다. 먼저 모델 서버를 설정하십시오. VPS에서 Ollama로 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) 공급자, 프로세서 또는 내보내기 도구를 구성하지 않으므로, 새로운 프로필은 어떠한 텔레메트리 네트워크 요청도 생성하지 않습니다. FEEDBACK_ONLY은 피드백 기반 세션 로그 공유에 동의하는 설정입니다. FULL는 런처 보고를 허용합니다. 세션 피드는 세션 콘텐츠, 도구 데이터, 프롬프트 및 작업 공간 경로를 내보낼 수 있으므로, FULL를 활성화하는 것은 작업 내용을 DeepSeek으로 전송하는 것과 같다고 간주해야 합니다.

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

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

sudo ss -tnp | grep -i node

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

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

셸 히스토리. 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 환경 파일에서 비밀 정보 제외하기에서 동일 서버의 컨테이너 측면에서 발생하는 동일한 문제를 다룹니다.

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

테스트한 버전을 고정하십시오. 프리미엄 버전은 패치 릴리스에서 설정 키를 변경할 수 있으며, 이 경우 공급자가 설정을 불러오지 못할 수 있습니다. 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에 환경 변수 이름을 지정하여 파일 사용을 완전히 피할 수 있습니다.

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 요청에 포함됩니다. 로컬 엔드포인트를 사용하면 요청은 루프백으로 전달되어 머신 내부에 머무릅니다. 원격 측정(telemetry)은 별도의 피드이며 기본적으로 꺼져 있습니다. 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