메인 콘텐츠로 건너뛰기
DeepSeek Harness(명령어 dsh)는 DeepSeek의 오픈 소스 코딩 Agent Harness입니다. 워크스페이스, 터미널, 파일 편집, Skills, 계획, Web UI를 제공하며 OpenAI Chat Completions 호환 인터페이스로 AIHubMix에 연결할 수 있습니다.
이 문서는 DeepSeek Harness 0.2.0-rc.2 기준으로 작성되었으며, 이 버전은 2026년 10월 18일 기준 최신 버전입니다. 0.1.0-rc.6과 비교해 변경 폭이 크며, 설정 위치와 UI가 업데이트되었습니다. Harness는 개발자 프리뷰 단계이므로 이후 릴리스에서 필드나 UI가 변경될 수 있습니다.

​
요약

다음 네 가지 값을 설정합니다.
DeepSeek Harness Models 페이지에 설정된 AIHubMix

​
무엇이 필요한가요?

  • 유효한 AIHubMix API Key
  • Node.js 22(22.19.0 이상) 또는 Node.js 24 이상
  • npm Registry와 https://aihubmix.com에 접근 가능한 네트워크

​
DeepSeek Harness를 설치하는 방법

소스 저장소를 복제하지 않고 npm 릴리스를 설치합니다.
dsh: command not found가 표시되면 npm config get prefix를 실행하고 해당 디렉터리의 bin이 PATH에 포함되어 있는지 확인하세요.

​
Web UI를 시작하는 방법

워크스페이스로 사용할 프로젝트 디렉터리에서 실행합니다. 공식적으로 권장되는 방법은 npx를 사용하는 것입니다.
전역으로 설치한 경우에는 다음 명령도 사용할 수 있습니다.
http://127.0.0.1:3080을 열고 처음 사용할 때 워크스페이스를 선택하거나 추가합니다.

​
AIHubMix 프로바이더를 설정하는 방법

Settings → Models → Add model provider를 열고, 카드를 Custom model API로 전환한 뒤 다음 값을 입력합니다.
DeepSeek Harness 사용자 지정 프로바이더 설정 양식
최종 요청 엔드포인트는 https://aihubmix.com/v1/chat/completions입니다.
Base URL 필드에 전체 /chat/completions 경로를 입력하지 마세요.

​
auto 또는 다른 모델 추가

Base URL과 API Key를 입력한 후 Model catalog에서 Fetch available models를 선택합니다. Harness가 GET https://aihubmix.com/v1/models를 요청하고 현재 사용 가능한 모델 ID를 표시합니다.
DeepSeek Harness가 가져온 AIHubMix 모델 목록
첫 연결 테스트에서는 auto만 추가하고 표시 이름을 Auto로 설정할 수 있습니다. 특정 모델을 사용하려면 가져온 목록에서 해당 모델을 선택한 후 Add selected를 선택하세요. 그래픽 모델 선택기는 현재 Provider 카탈로그에 등록된 모델만 표시합니다.
AIHubMix auto 모델 수동 추가

​
auto와 지정 모델 비교

두 방식은 같은 Provider, Base URL, API Key를 사용합니다. 모델을 전환할 때 Provider를 다시 만들 필요가 없습니다.

​
환경 변수에 API Key 저장

개발 머신과 CI에서는 profile 파일을 통해 환경 변수에서 API Key를 읽도록 설정할 수 있습니다. Web UI는 web profile을, headless 테스트는 headless profile을 사용합니다. 파일 경로는 다음과 같습니다.
  • $DSH_HOME/profiles/web/cordis.patch.yml
  • $DSH_HOME/profiles/headless/cordis.patch.yml
두 파일에 다음 내용을 입력합니다.
두 항목은 모두 필요합니다. llm-pi-ai만 작성하고 agent-default-model을 작성하지 않으면 headless는 기본값인 deepseek-official을 계속 사용하며 MISSING_CREDENTIAL이 표시됩니다.
이전 버전은 $HOME/.dsh/settings.yaml에 설정을 저장했지만, 0.2.0부터는 이 파일을 사용하지 않습니다. DSH 0.2.0을 처음 시작하면 이 파일이 profile 설정으로 마이그레이션되고 원본 파일 이름은 settings.yaml.imported로 변경됩니다. 마이그레이션을 수행한 실행에서는 MISSING_CREDENTIAL이 표시될 수 있으며, 한 번 더 실행하면 됩니다.
키를 실행 환경에서 가져오면 설정 페이지에 읽기 전용 메시지가 표시되고 실제 값은 노출되지 않습니다.
DeepSeek Harness의 AIHubMix 프로바이더 상세 설정
환경 변수를 변경한 후 Harness를 다시 시작하세요.

​
모델 선택 및 대화 검증

Settings를 닫고 입력 상자 오른쪽 아래의 모델 선택기에서 Auto 또는 추가한 특정 모델을 선택합니다.
DeepSeek Harness 모델 선택기의 Auto
예상 응답을 받으면 Harness, OpenAI Chat Completions 호환 엔드포인트, AIHubMix 간 연결이 정상입니다.
DeepSeek Harness에서 성공한 AIHubMix 응답

​
headless 테스트 실행

Web UI 없이 테스트하려면 다음 명령을 실행합니다. 이 명령은 headless profile을 사용하므로 $DSH_HOME/profiles/headless/cordis.patch.yml에 위 두 항목이 작성되어 있어야 합니다.
성공하면 DSH_AIHUBMIX_OK가 출력됩니다.

​
자주 묻는 질문

​
MISSING_CREDENTIAL이 표시되는 이유는 무엇인가요?

Harness가 사용 가능한 설정을 읽지 못했습니다. profile에 두 항목이 모두 작성되어 있는지, 환경 변수 AIHUBMIX_API_KEY가 설정되어 있는지 확인한 뒤 같은 터미널에서 Harness를 시작하세요.

​
모델 검색에서 401이 반환되는 이유는 무엇인가요?

API Key가 유효하고 불필요한 공백이나 줄바꿈이 없는지 확인하세요. 모델 검색 요청은 Bearer 인증을 사용합니다.

​
모델 선택기에 Auto만 표시되는 이유는 무엇인가요?

선택기는 현재 Provider 카탈로그에 등록된 모델만 표시합니다. Settings → Models → AIHubMix → Edit를 열고, Model catalog에서 Fetch available models를 사용해 필요한 모델을 선택한 뒤 Add selected를 선택하세요.

​
UNKNOWN_MODEL이 표시되는 이유는 무엇인가요?

현재 Provider 카탈로그에 해당 모델 ID가 없습니다. 모델 ID는 대소문자를 구분하므로 모델 검색 결과의 정확한 값을 사용하세요.

​
연결 시간이 초과되는 이유는 무엇인가요?

DNS, 조직 네트워크, 로컬 프록시를 확인하세요. DSH는 HTTP_PROXY와 HTTPS_PROXY 환경 변수를 자동으로 읽습니다. 특정 주소를 프록시에서 제외하려면 NO_PROXY를 설정할 수 있습니다. 브라우저만 시스템 프록시를 사용하는 경우에는 dsh를 시작하는 터미널에서 HTTP_PROXY와 HTTPS_PROXY를 설정하세요.

​
보안 지침

  • API Key를 Git, 스크린샷, 공유 스크립트에 포함하지 마세요
  • Harness 자격 증명 저장소 또는 AIHUBMIX_API_KEY를 사용하세요
  • 문제 해결 중 전체 API Key를 출력하지 마세요
  • CI 플랫폼의 Secret 관리 기능으로 환경 변수를 주입하세요
마지막 업데이트: 2026-10-18