DeepSeek Harness (dsh)는 DeepSeek 자체 모델을 내장하고 있지만, 이 모델에만 국한되지 않습니다. 하네스는 모델 제공자를 구성으로 처리합니다. 제공자 블록을 OpenAI 호환 엔드포인트에 연결하고, 자격 증명 참조를 제공하면 에이전트 세션은 해당 URL 뒤에 있는 모든 모델에서 실행됩니다. 로컬 Ollama 인스턴스, 회사 게이트웨이, DashScope 호환 모드를 통한 Qwen, 또는 Anthropic 및 OpenAI와 같은 대규모 카탈로그 제공자 모두 동일한 블록에 연결할 수 있습니다.
이 가이드에서는 해당 블록을 키별로 자세히 설명한 다음, 세 가지 작동 레시피를 제시합니다: 로컬 모델, 호스팅된 OpenAI 호환 엔드포인트, 그리고 내장 카탈로그 제공자입니다. 여기에 인용된 모든 내용은 2026년 8월 20일에 가져온 마스터 브랜치에 있는 공식 제공자 가이드에서 발췌했습니다. 한 가지 미리 경고할 점은: dsh는 개발자 프리뷰이며, README에는 호환성을 깨뜨릴 수 있는 변경 사항이 있을 것이라고 대문자로 경고하고 있습니다. 프로덕션에 복사하기 전에 설치된 버전에 대해 문서를 확인하십시오.
하네스 자체가 처음이라면, 먼저 DeepSeek Harness가 무엇이며 어떻게 작동하는지를 알아본 다음, 제공자 구성에 대해 여기로 돌아오십시오.
에이전트 하네스에서 모델을 교체하는 이유
에이전트 하네스는 루프입니다: 모델이 계획하고, 도구를 호출하고, 결과를 읽고, 반복합니다. 하네스가 루프를 소유하고 모델은 재료입니다. 재료를 변경하는 세 가지 이유는 다음과 같습니다:
비용. 에이전트 세션은 모든 도구 결과가 다시 컨텍스트로 피드백되기 때문에 토큰을 빠르게 소모합니다. 일상적인 세션을 더 저렴한 모델로 라우팅하거나, V4-Pro 대신 DeepSeek V4-Flash로 라우팅하면 워크플로우를 변경하지 않고도 요금이 달라집니다. 필요한 세션을 위해 비싼 최신 모델을 계속 구성해둘 수 있습니다.
데이터 지역성. 일부 코드베이스는 건물을 떠날 수 없습니다. 자체 하드웨어에서 실행되는 모델을 가리키는 제공자 블록은 프롬프트, 파일 내용 및 도구 출력이 네트워크를 넘지 않는다는 것을 의미합니다. 동일한 하네스, 동일한 UI, egress(외부 전송) 비용 없음.
로컬 개발. 플러그인을 구축하거나 에이전트 동작을 테스트할 때, 매 반복마다 API 크레딧이 소모되거나 네트워크에 의존하고 싶지 않을 것입니다. 작은 로컬 모델은 루프를 테스트하기에 충분히 빠르게 응답하며, 동작이 중요할 때 실제 모델로 다시 교체할 수 있습니다.
이 디자인은 dsh의 아키텍처에서 비롯됩니다: 하네스의 모든 것은 플러그인이며, 모델 어댑터는 교체 가능한 부분 중 하나입니다. 제공자 경로는 dsh-llm-pi-ai 플러그인이 소유하며, 이 플러그인은 리포지토리의 플러그인 구성 카탈로그에 "이 인스턴스가 소유하는 제공자 경로"를 포함하는 것으로 문서화되어 있습니다. 이것이 메커니즘입니다. 사용자에게 보이는 인터페이스는 하나의 YAML 블록입니다.
제공자 블록, 키별 설명
사용자 지정 제공자는 $DSH_HOME/settings.yaml에 있으며, 설정(Settings) → 모델(Models) 메뉴 아래 웹 UI에서도 생성할 수 있습니다. 다음은 공식 문서에서 가져온 예시입니다:
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]
각 키의 기능:
my-gateway는 제공자 ID입니다. 영구적인 식별자이므로 사용할 이름을 신중하게 선택하십시오. UI에 표시되는 표시 이름은 별도로 설정됩니다.apiKeyEnv는 API 키를 담는 환경 변수의 이름을 지정합니다. 설정 파일에는 실제 비밀 자체가 포함되지 않고, 이 참조만 포함됩니다. 실제 키가 어디에 저장되는지에 대한 자세한 내용은 아래를 참조하십시오.api는 와이어 프로토콜을 선언합니다.openai-completions는 OpenAI 호환 엔드포인트에 대한 문서화된 값이며, 이는 "모든 모델" 약속이 작동하도록 만듭니다. 대부분의 게이트웨이, 로컬 런타임 및 호스팅된 제공자는 이 프로토콜을 사용합니다.baseURL은 하네스가 요청을 보내는 엔드포인트 루트입니다.models는 이 제공자를 통해 사용할 수 있는 모델 ID를 나열합니다. 각 항목에는 최소한id가 필요하며, 이는 엔드포인트가 요청 본문에서 예상하는 것과 일치해야 합니다.input은 모델별 모달리티를 선언합니다. 사용자 지정 모델은 기본적으로 텍스트 전용이므로, 비전 모델은input: [text, image]를 명시적으로 선언해야 이미지 첨부 파일이 도달할 수 있습니다. 또한 제공자의 모든 모델에 대한 대체 값을 설정하는 경로 수준defaultInput이 있으며, 모델 수준input이 이를 재정의합니다.compat은 기본 OpenAI 동작에서 벗어나는 엔드포인트에 대한 호환성 스위치를 포함합니다. 문서에는 두 가지가 언급되어 있습니다:developer역할을 거부하는 백엔드의 경우supportsDeveloperRole: false, 그리고 이전 출력 제한 필드 이름을 원하는 백엔드의 경우maxTokensField: max_tokens입니다. Compat은 경로 수준 또는 모델별로 설정할 수 있습니다.
알아둘 만한 한 가지 편리한 기능: 웹 UI를 통해 사용자 지정 제공자를 추가할 때, "사용 가능한 모델 가져오기(Fetch available models)" 옵션은 엔드포인트의 OpenAI 호환 GET /models 경로를 쿼리하여 모델 목록을 자동으로 채워줍니다. 엔드포인트가 해당 경로를 구현하는 경우, 수동으로 입력할 필요가 없습니다.
실제 API 키가 저장되는 곳
비밀은 $DSH_HOME/.credentials.yaml에 쓰기 전용으로 저장됩니다. UI를 통해 키를 저장하면 dsh는 수정된 설명자만 반환하며, 실제 값은 다시 표시되지 않습니다. settings.yaml은 참조(apiKeyEnv 이름, 자격 증명 설명자)만 포함하며, 키 자체는 포함하지 않습니다. 이러한 분리는 아무것도 유출하지 않고 설정 파일을 커밋하거나 공유할 수 있으며, 제공자 구성을 건드리지 않고 키를 교체할 수 있음을 의미합니다.
레시피 1: Ollama를 통해 로컬 모델 실행
Ollama는 http://localhost:11434/v1에서 OpenAI 호환 API를 노출하며, 이는 Ollama 자체 OpenAI 호환성 가이드에 문서화되어 있습니다. dsh는 모든 기본 URL에 openai-completions를 사용하므로, 이 연결은 간단합니다.
[확인: dsh 문서에는 Ollama 특정 예제가 없습니다. 이 레시피는 문서화된 사용자 지정 제공자 스키마를 Ollama의 문서화된 OpenAI 호환 엔드포인트에 적용합니다. 내부 게시 전에 설치 환경에서 테스트하십시오.]
llm-pi-ai:
providers:
ollama-local:
apiKeyEnv: OLLAMA_API_KEY
api: openai-completions
baseURL: http://localhost:11434/v1
models:
- id: gpt-oss:20b
- id: qwen3
이에 대한 참고 사항:
- Ollama는 로컬에서 API 키를 요구하지 않지만, 스키마는 자격 증명 참조를 예상하므로 더미 값을 설정하십시오:
export OLLAMA_API_KEY=ollama. Ollama는 보내는 모든 것을 무시합니다. - 모델
id는 Ollama가 제공하는 태그와 일치해야 합니다.ollama list를 실행하고 태그를 포함하여 이름을 정확히 복사하십시오. - 먼저 모델을 풀(
ollama pull gpt-oss:20b)한 다음, 서버가 응답하는지 확인한 후에 dsh에 연결하십시오. 전체 로컬 설정은 Ollama를 사용하여 GPT-OSS를 실행하는 방법에서 다루었으며, 하드웨어가 지원된다면 Kimi K3와 같은 다른 오픈 웨이트 모델에도 동일한 패턴이 적용됩니다.
간단한 건전성 검사는 혼란스러운 에이전트 세션을 피하는 데 도움이 됩니다: dsh 구성을 건드리기 전에 Apidog에서 http://localhost:11434/v1/models를 호출하십시오. 해당 요청이 모델 목록을 반환하면, 기본 URL이 정확하고 서버가 작동 중이며, dsh UI의 "사용 가능한 모델 가져오기"도 작동할 것입니다. 그렇지 않으면 어떤 하네스 구성도 문제를 해결할 수 없습니다.
기대치 관리: 에이전트 하네스는 도구 호출과 긴 컨텍스트에 크게 의존합니다. 작은 로컬 모델은 테스트를 위한 루프를 처리하지만, 하네스가 구축된 최신 모델보다 계획 능력이 떨어지고 도구 호출을 더 자주 놓칠 것입니다. 이는 플러그인 개발에는 괜찮지만, 실제 작업에서는 답답할 수 있습니다.
레시피 2: 호스팅된 OpenAI 호환 엔드포인트 (DashScope를 통한 Qwen)
호스팅된 예시를 위해, OpenAI 호환성을 가정하는 공급업체보다는 이를 문서화하는 공급업체를 선택하십시오. Alibaba Cloud Model Studio (DashScope)는 그렇게 합니다: OpenAI 호환성 페이지는 Qwen 모델을 위한 /compatible-mode/v1 엔드포인트를 문서화하며, 지역별, 워크스페이스별 도메인(싱가포르의 경우: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1)과 DASHSCOPE_API_KEY 환경 변수를 통한 인증을 제공합니다.
dsh 스키마에 매핑:
llm-pi-ai:
providers:
qwen-dashscope:
apiKeyEnv: DASHSCOPE_API_KEY
api: openai-completions
baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
models:
- id: qwen3-max
{WorkspaceId}를 Model Studio 콘솔의 실제 워크스페이스 도메인으로 바꾸고, 공급업체의 모델 목록에서 현재 ID를 확인하십시오. 우리는 Qwen 3.8 API 가이드에서 주력 모델 계층에 대한 요약을 제공합니다. 동일한 패턴은 문서화된 OpenAI 호환성을 가진 모든 공급업체에 적용됩니다: Moonshot의 Kimi API, OpenRouter, vLLM 배포, 또는 회사 내부 게이트웨이 등입니다. 변경되는 부분은 baseURL, 환경 변수 이름, 그리고 모델 ID뿐입니다. Codex에서 오픈 소스 모델을 구성했다면, 이것은 익숙하게 느껴질 것입니다. dsh의 YAML 블록은 Codex의 model_providers 구성과 동일한 역할을 합니다.
호스팅된 엔드포인트 특정 사항 두 가지:
- 공급업체의 엔드포인트가 역할이나 토큰 필드에 대한 이상한 오류로 요청을 거부하는 경우,
compat스위치가 바로 이를 위해 존재합니다. 먼저supportsDeveloperRole: false를 시도해보십시오. 이전 OpenAI 호환 구현은developer역할 이전에 존재했습니다. - 비전 모델은 호스팅된 모델이 이미지를 지원하더라도
input: [text, image]를 명시적으로 선언해야 합니다. dsh는 달리 지정하지 않는 한 사용자 지정 모델에 대해 텍스트 전용으로 가정합니다.
레시피 3: 내장 카탈로그 제공자
주류 클라우드의 경우 사용자 지정 블록이 필요하지 않습니다. dsh는 DeepSeek, Anthropic, OpenAI를 위한 카탈로그 제공자를 제공하며, 설정은 대부분 "API 키 붙여넣기"입니다. 특수 카탈로그 항목은 자체 네이티브 인증 흐름을 가집니다: Bedrock은 AWS 자격 증명을 사용하고, Vertex는 ADC 프로젝트를 원하며, Azure는 api-버전이 필요하고, Codex는 OAuth를 통해 인증합니다.
카탈로그 제공자는 하네스 뒤에서 Claude 또는 GPT를 사용하고자 할 때 마찰이 적은 경로이며, 대부분의 사람들이 DeepSeek V4-Pro를 실행하는 방법이 될 것입니다. DeepSeek V4-Pro의 API는 하네스 자체와 함께 2026년 8월에 출시되었습니다(api-docs.deepseek.com에서 자세한 정보 확인). 사용자 지정 제공자는 카탈로그가 다루지 않는 모든 것(로컬 런타임, 게이트웨이, 지역 공급업체, OpenAI 호환 애그리게이터)을 위한 것입니다.
모델 선택 및 세션이 기억하는 것
제공자를 추가하면 해당 모델을 사용할 수 있게 됩니다. 설정(Settings) → 모델(Models)에서 모델을 선택하면 새 세션의 기본값이 됩니다. 문서에서 기억할 만한 두 가지 동작:
- 기존 세션은 시작 시 사용한 모델을 유지합니다. 세션은 원래 모델을 기록하므로, 프로젝트 중간에 기본값을 변경해도 기록이 조용히 다시 작성되거나 현재 실행 중인 세션이 사용하는 모델이 변경되지 않습니다.
- 현재 기본값을 소유하는 제공자를 삭제하면, 새 모델을 선택할 때까지 컴포저가 입력을 차단합니다. 하네스는 추측하는 대신 명확하게 오류를 발생시킵니다.
이러한 세션 고정은 재현성에 중요합니다. dsh를 다른 하네스와 비교할 때(저희는 DeepSeek Harness 대 Claude Code에서 정확히 그렇게 했습니다), 세션의 스크립트가 실행 중 중간에 모델이 변경된 것이 아니라 하나의 모델을 반영한다는 것을 신뢰할 수 있습니다.
일반적인 실패 문제 해결
잘못되었거나 도달할 수 없는 baseURL. 가장 흔한 실패는 가장 평범한 것입니다. URL이 프로토콜이 예상하는 지점에서 끝나는지(일반적으로 OpenAI 호환 엔드포인트의 경우 /v1, DashScope의 경우 /compatible-mode/v1) 확인하고, 하네스 외부에서 일반 GET {baseURL}/models 요청이 성공하는지 확인하십시오. 이곳은 Apidog 다운로드가 5분 만에 본전을 뽑는 지점입니다. 하네스가 보낼 것과 동일한 헤더(Authorization: Bearer $KEY)로 요청을 보내고, 래핑된 하네스 오류 대신 실제 상태 코드와 본문을 읽으십시오. 오프라인으로 개발 중이거나 공급업체가 불안정한 경우, Apidog에서 제공자의 /models 및 /chat/completions 응답을 모의(mock)하고, 개발하는 동안 baseURL을 해당 모의로 지정하십시오.
누락되거나 비어 있는 환경 변수. apiKeyEnv는 변수 이름을 지정하는 것이지, 변수를 생성하는 것이 아닙니다. dsh가 실제로 실행되는 환경에 변수가 설정되어 있지 않으면, 요청은 인증 없이 전송되어 401 오류로 돌아옵니다. GUI 또는 서비스 관리자에서 시작된 프로세스가 셸 프로필을 상속하지 않을 수 있음을 기억하십시오. 임의의 터미널에서만 확인하지 말고, dsh web을 시작하는 동일한 컨텍스트에서 echo $GATEWAY_API_KEY를 실행하십시오.
입력 모달리티 불일치. 이미지를 첨부했는데 모델이 이를 전혀 인식하지 못하거나 요청 오류가 발생합니다. 사용자 지정 모델은 기본적으로 텍스트 전용입니다. 모델 항목에 input: [text, image]를 추가하거나, 제공자의 모든 모델이 이미지를 처리하는 경우 경로 수준에서 defaultInput을 설정하십시오.
프로토콜 특이 사항. 지원되지 않는 역할 또는 거부된 토큰 매개변수를 언급하는 오류는 호환성 스위치를 가리킵니다: supportsDeveloperRole: false 및 maxTokensField: max_tokens가 문서화된 두 가지입니다.
어제는 모든 것이 작동했는데. 개발자 프리뷰입니다. 배포하는 버전을 고정하고, 업그레이드 전에 릴리스 노트를 읽고, 설정 스키마가 변경될 수 있음을 예상하십시오. deepseek-harness 리포지토리가 진실의 원천이며, 이 블로그 게시물을 포함한 어떤 블로그 게시물도 아닙니다.
한 가지 더 통합 참고 사항: 모델 제공자는 사용자 정의 이야기의 절반에 불과합니다. 나머지 절반은 에이전트가 호출할 수 있는 도구이며, API 워크플로우를 직접 연결할 수 있습니다. 이에 대해서는 DeepSeek Harness 내에서 Apidog CLI 사용하기에서 다룹니다.
FAQ
DeepSeek Harness가 Ollama를 공식적으로 지원하나요?
공식 제공자 문서에는 Ollama가 명시적으로 언급되어 있지 않습니다. 이 문서는 openai-completions 프로토콜을 사용하는 모든 엔드포인트를 지원하며, Ollama는 http://localhost:11434/v1에 OpenAI 호환 API를 문서화합니다. 위의 레시피는 문서화된 두 부분을 결합한 것입니다. dsh는 개발자 프리뷰이며 릴리스 사이에 스키마가 변경될 수 있으므로 설치 환경에서 테스트해 보십시오.
dsh는 API 키를 어디에 저장하나요?
$DSH_HOME/.credentials.yaml에 쓰기 전용으로 저장됩니다. UI는 저장 후 수정된 설명자를 보여주며, settings.yaml은 apiKeyEnv 이름과 같은 참조만 포함합니다. 제공자 구성 내에 일반 텍스트 키가 남는 일은 없습니다.
다른 세션에 대해 다른 모델을 실행할 수 있나요?
네, 그렇습니다. 모델을 선택하면 새 세션에 대해서만 기본값이 설정됩니다. 기존의 모든 세션은 시작 시 사용한 모델을 유지합니다. 따라서 일상적인 세션에는 DeepSeek V4-Flash와 같은 저렴한 모델을 실행하고, 어려운 문제에 대해서는 기본값을 더 강력한 모델로 전환하더라도 이전 세션은 영향을 받지 않습니다.
내 사용자 지정 엔드포인트가 curl에서는 발생하지 않는 오류를 반환합니다. 어떻게 해야 하나요?
정확한 페이로드를 비교하십시오. 하네스가 백엔드에서 허용하지 않는 developer 역할 또는 최신 토큰 제한 필드를 보낼 수 있습니다. 문서화된 수정 사항은 compat 아래의 supportsDeveloperRole: false 및 maxTokensField: max_tokens입니다. API 클라이언트에서 하네스 형태의 요청을 재현하면 백엔드가 어떤 필드에서 문제를 일으키는지 알 수 있습니다.