DeepSeek Harness

1. 제품 소개

DeepSeek Harness(CLI 명령어 dsh)는 DeepSeek이 공식 오픈소스로 공개한 에이전트 실행 프레임워크로, 「Model + Harness = Agent」라는 공식을 표방합니다. 자체 모델을 제공하는 대신, 대규모 모델에 파일·터미널·웹·외부 서비스를 조작할 수 있는 「손과 발」을 달아 주어, 모델이 작업 공간에서 스스로 작업을 분해하고 파일을 읽고 코드를 수정하며 명령을 실행해 결과물을 전달하게 합니다. 「모든 것이 플러그인」 아키텍처를 채택하고 있어 모델도 교체 가능한 기능 중 하나일 뿐이며, 따라서 OpenAI 호환 또는 Anthropic 호환의 모든 모델 서비스를 연결할 수 있습니다. DeepSeek Harness는 Web UI(기본 http://127.0.0.1:3080), CLI, SDK 세 가지 사용 방식을 제공합니다. GravitexAI와 연동하면 다음과 같은 이점이 있습니다:

기능	설명
하나의 키로 전체 모델	각사 계정을 따로 가입할 필요 없이, 하나의 API 키로 GPT, Claude, Gemini, DeepSeek, Kimi, MiniMax 등 전체 모델을 호출
키 로컬 저장	API 키는 로컬 `$DSH_HOME/.credentials.yaml`(macOS/Linux 기본 `~/.dsh/`, Windows 기본 `%USERPROFILE%\.dsh\`)에만 저장되며, 설정 파일에는 자격 증명 참조만 남고 평문은 없음
GUI 원클릭 연동	설정 → 모델 → 사용자 지정 제공자 추가에서 주소, 프로토콜, 키, 모델만 입력하면 완료, 설정 파일을 직접 수정할 필요 없음
멀티 프로토콜 지원	OpenAI Completions, OpenAI Responses, Anthropic 네이티브 프로토콜을 모두 지원, 프로토콜별로 제공자를 나누어 생성 가능
종량제 자체 결제	사용자 지정 제공자 사용 요금은 GravitexAI에 직접 결제

2. 환경 요구 사항

Node.js 설치 필요(LTS 버전 권장)
macOS / Linux / Windows 지원, Web UI는 브라우저로 접속

DeepSeek Harness는 현재 개발자 프리뷰(Developer Preview) 단계로 빠르게 변경되고 있으며, 호환성이 깨지는 변경이 있을 수 있습니다. 업그레이드 전 공식 릴리스 노트를 확인하세요.

3. 사전 준비

로컬 머신에 Node.js가 설치되어 있어야 합니다
GravitexAI 콘솔에서 API 키(sk-xxxxxxxxxx 형식)를 생성해 두어야 합니다

4. 빠른 시작

1단계: DeepSeek Harness 설치 및 실행

전역 설치 없이 npx로 Web UI를 바로 실행할 수 있습니다:

npx @deepseek-ai/dsh web

이 명령은 기본적으로 http://127.0.0.1:3080에서 Web UI를 시작하고 브라우저를 자동으로 엽니다. --no-open 옵션을 주면 브라우저를 열지 않고 서버만 실행합니다. 설정과 데이터는 기본적으로 $DSH_HOME 디렉터리(macOS/Linux는 ~/.dsh/, Windows는 %USERPROFILE%\.dsh\)에 저장됩니다.

2단계: GravitexAI API 키 발급

GravitexAI 콘솔에 접속
「새 토큰」을 클릭하고 이름을 지정해 저장
sk-로 시작하는 키를 복사해 둡니다

3단계: 사용자 지정 제공자 추가

Web UI에서 설정 → 모델을 열고 「사용자 지정 제공자 추가」를 선택한 후 다음 표대로 입력합니다:

항목	입력 값	설명
Provider ID	`gravitex`	소문자만 가능, 생성 후 변경 불가(요청, 세션, 자격 증명 참조가 모두 이 ID를 사용). 변경하려면 새 제공자를 만들고 기존 것을 삭제해야 함
Display name	`GravitexAI`	표시 이름, 언제든 수정 가능
Base URL	`https://api.gravitex.ai/v1`	OpenAI 호환 프로토콜 주소, `/v1`을 반드시 포함
API 프로토콜	`openai-completions`	OpenAI 계열 모델(예: `gpt-5.5`)은 `openai-responses` 선택 필수, 나머지 모델은 `openai-completions` 선택
API Key	예: `sk-...`	2단계에서 발급받은 GravitexAI 토큰 붙여넣기
모델	모델 ID 하나 이상	다음 단계 참고

하나의 제공자는 하나의 프로토콜만 사용합니다. OpenAI 계열 모델(예: gpt-5.5)은 반드시 openai-responses 프로토콜을 사용해야 하며, DeepSeek, Gemini, Kimi 등의 모델은 openai-completions를 사용합니다. Claude 계열 모델은 Anthropic 네이티브 프로토콜(anthropic-messages) 연결을 권장하며, Base URL은 https://api.gravitex.ai(/v1 없이)입니다. 프로토콜이 다르면 제공자를 각각 만드세요(예: gravitex, gravitex-openai, gravitex-anthropic. 6절 「고급 설정」 참고).

입력을 완료한 폼은 다음과 같습니다:

4단계: 모델 추가

제공자 폼의 「모델 카탈로그」에서 사용 가능한 모델 가져오기를 클릭하면, DeepSeek Harness가 게이트웨이의 GET /models 인터페이스를 호출해 사용 가능한 모델을 나열합니다. 원하는 모델을 검색·선택한 후 「선택 항목 추가」를 클릭하면 됩니다:

탐지에 실패하거나 목록이 비어 있어도 모델 ID를 직접 입력하면 완전히 동일하게 동작합니다. 단, 모델이 속한 제공자의 프로토콜과 반드시 일치해야 합니다. 예시:

모델 ID	설명	프로토콜
`deepseek-v4-pro`	DeepSeek 플래그십 모델	`openai-completions`
`claude-sonnet-5`	Claude 계열	`anthropic-messages`(권장) / `openai-completions`
`gpt-5.5`	GPT 계열	`openai-responses`
`gemini-3.6-flash`	Gemini 계열	`openai-completions`
`kimi-k3`	Kimi 계열	`openai-completions`

전체 모델 ID는 GravitexAI 모델 광장에서 확인하세요.

5단계: 모델 선택 후 사용 시작

제공자를 저장하면 세션의 모델 선택기에서 GravitexAI의 모델을 확인할 수 있습니다. 모델을 선택하면 바로 작업을 시작할 수 있으며, 선택한 모델은 새 세션의 기본값으로도 저장됩니다. 모델 변경은 다음 요청부터 적용되며, 서비스를 재시작할 필요가 없습니다:

5. 주요 기능 요약

기능	설명
에이전트 작업 실행	모델이 작업 공간에서 파일을 읽고 쓰고 터미널 명령을 실행해 결과물 전달
모든 것이 플러그인	모델, 도구, 런타임 기능이 모두 플러그인이며 필요에 따라 확장·교체 가능
다양한 사용 형태	Web UI(`dsh web`), CLI, SDK 세 가지 방식
멀티 제공자 전환	모델 선택기에서 언제든 제공자/모델 전환, 다음 요청부터 적용
로컬 자격 증명 저장	키는 `$DSH_HOME/.credentials.yaml`에 저장, 설정에는 참조만 기록

6. 고급 설정(선택 사항)

Web UI에서 위 설정을 마쳤다면 일반적으로 이 절은 건너뛰어도 됩니다. 모델 페이지에는 기본 필드(키, 주소, 프로토콜, 모델 ID, 컨텍스트 창 등)만 노출되며, 추론 레벨, 이미지 입력, 요청 호환성 스위치 등 나머지 기능은 $DSH_HOME/settings.yaml(macOS/Linux 기본 ~/.dsh/settings.yaml, Windows 기본 %USERPROFILE%\.dsh\settings.yaml. 브라우저와 서버가 같은 머신이라면 설정 페이지 상단의 「설정 파일 열기」 버튼으로 바로 열 수 있음)을 직접 편집해야 합니다. 저장 후 다음 요청부터 바로 적용되며, 서비스를 재시작할 필요가 없습니다. API 키에 대하여: 아래 예시의 apiKeyEnv: GRAVITEX_API_KEY는 키를 환경 변수에서 읽어온다는 뜻입니다. 설정을 직접 작성하기 전에 터미널에서 먼저 설정하세요:

export GRAVITEX_API_KEY="sk-xxxxxxxxxx"

$env:GRAVITEX_API_KEY="sk-xxxxxxxxxx"

위 명령은 현재 터미널 세션에만 적용됩니다. Windows에서 영구 적용하려면 setx GRAVITEX_API_KEY "sk-xxxxxxxxxx"를 사용하세요(설정 후 터미널을 다시 열어야 함). macOS/Linux에서는 export 명령을 ~/.zshrc 또는 ~/.bashrc에 추가하면 됩니다.

이미 Web UI에서 제공자의 키를 저장했다면 settings.yaml에 자동 생성된 자격 증명 참조가 들어 있습니다. 이 위에 추가 설정을 할 때는 해당 참조를 그대로 두고 apiKeyEnv로 바꾸지 마세요. apiKeyEnv 방식은 키를 환경 변수로 제공하는 완전 수동 설정에 사용합니다.

전체 참조 설정

아래는 세 개의 제공자를 모두 포함한 완전한 settings.yaml 예시입니다. 필요에 따라 줄여서 사용하세요:

llm-pi-ai:
  providers:
    # 제공자 1: openai-completions 프로토콜 —— DeepSeek / Gemini / Kimi 등 모델
    gravitex:
      apiKeyEnv: GRAVITEX_API_KEY
      api: openai-completions
      baseURL: https://api.gravitex.ai/v1
      models:
        - id: deepseek-v4-pro
          compat:
            thinkingFormat: deepseek    # DeepSeek 모델에서 사고(thinking)를 올바르게 켜고 끄는 데 필수
          reasoningEfforts:             # 선언하면 모델 선택기에 추론 레벨 메뉴가 표시됨
            off:
            high: high
            max: max
        - id: gemini-3.6-flash
          input: [text, image]          # 비전 모델은 이미지 입력을 선언해야 함. 그렇지 않으면 첨부 이미지가 전송 전에 거부됨
        - id: kimi-k3

    # 제공자 2: openai-responses 프로토콜 —— GPT 계열 모델
    gravitex-openai:
      apiKeyEnv: GRAVITEX_API_KEY
      api: openai-responses
      baseURL: https://api.gravitex.ai/v1
      models:
        - id: gpt-5.5

    # 제공자 3: anthropic-messages 프로토콜 —— Claude 계열 모델(권장 방식)
    gravitex-anthropic:
      apiKeyEnv: GRAVITEX_API_KEY
      api: anthropic-messages
      baseURL: https://api.gravitex.ai  # 주의: Anthropic 프로토콜은 /v1 없이
      models:
        - id: claude-sonnet-5

필드 설명

필드	역할	필요한 경우
`apiKeyEnv`	지정한 환경 변수에서 키를 읽어옴	완전 수동 설정 시. Web UI에서 키를 저장했다면 자동 생성된 자격 증명 참조를 그대로 유지
`input`	모델이 지원하는 입력 모달리티(`text` / `image`) 선언	수동 등록한 비전 모델 —— 기본값은 텍스트 전용
`reasoningEfforts`	추론 레벨을 선언하면 모델 선택기에 레벨 메뉴가 표시됨	추론 강도를 수동으로 전환할 때. 비워 둔 `off`는 추론 파라미터를 보내지 않음
`compat.thinkingFormat: deepseek`	`off`가 사고를 완전히 끄고, 나머지 레벨은 명시적으로 켬	OpenAI 호환 게이트웨이 뒤의 DeepSeek 모델
`compat.supportsDeveloperRole: false`	시스템 프롬프트를 일반 역할(role)로 전송	키와 주소가 정확하지만 게이트웨이가 추론 모델 요청을 거부할 때
`compat.maxTokensField: max_tokens`	출력 상한을 `max_tokens` 필드로 전송	게이트웨이가 `max_completion_tokens` 필드를 인식하지 못할 때

뒤의 두 compat 필드는 제공자 레벨에 작성해 해당 제공자 아래 모든 모델에 일괄 적용할 수도 있습니다:

    gravitex:
      apiKeyEnv: GRAVITEX_API_KEY
      api: openai-completions
      baseURL: https://api.gravitex.ai/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: deepseek-v4-pro

7. 자주 묻는 질문

MISSING_CREDENTIAL 오류는 어떻게 해결하나요?

현재 제공자가 자격 증명을 찾지 못한 것입니다. 설정 방식에 따라 확인하세요: Web UI로 설정했다면 모델 페이지에서 API 키를 다시 저장하고, apiKeyEnv로 수동 설정했다면 해당 환경 변수가 설정되어 있는지(예: export GRAVITEX_API_KEY="sk-..."), 그리고 dsh를 실행하는 터미널에서 읽을 수 있는지 확인하세요. 채팅에 키를 붙여 넣어 우회하지 마세요.

UNKNOWN_MODEL 오류는 어떻게 해결하나요?

모델 ID가 현재 제공자에 인식되지 않는 것입니다. 해당 모델이 제공자의 모델 목록에 추가되어 있는지 확인하고, 모델 ID의 대소문자와 철자가 GravitexAI 모델 광장과 정확히 일치하는지 확인하세요.

GPT 계열 모델이 오류를 내거나 정상적으로 호출되지 않나요?

해당 모델이 속한 제공자의 프로토콜이 openai-responses인지 확인하세요. GPT 계열 모델은 openai-completions 프로토콜의 제공자 아래에 둘 수 없으며, openai-responses 프로토콜의 제공자(예: gravitex-openai)를 따로 만든 후 모델을 추가해야 합니다.

「사용 가능한 모델 가져오기」가 401을 반환하거나 목록이 비어 있나요?

401은 키 또는 주소가 일치하지 않는다는 뜻입니다. Base URL이 https://api.gravitex.ai/v1인지, 키가 sk-로 시작하고 불필요한 공백이 없는지 확인하세요. 목록이 비어 있거나 탐지에 실패하면 모델 ID를 직접 입력해도 완전히 동일하게 동작합니다.

키와 주소가 정확한데 모든 요청이 거부되나요?

게이트웨이와 OpenAI의 요청 형식이 다른 것입니다. settings.yaml의 제공자 레벨에 compat.supportsDeveloperRole: false와 compat.maxTokensField: max_tokens를 설정한 후(작성 방법은 6절 참고) 다시 시도하세요.

DeepSeek 모델에서 off를 선택해도 계속 사고(thinking)하나요?

비워 둔 off는 추론 필드를 전송하지 않으므로, 기본적으로 사고하는 모델은 계속 사고합니다. 해당 모델에 compat.thinkingFormat: deepseek를 설정하세요(6절 예시 참고).

이미지가 전송 전에 거부되나요?

수동 등록 모델은 기본적으로 텍스트 전용입니다. settings.yaml에서 해당 모델에 input: [text, image]를 추가하세요. 반대로 제공자가 이미지가 포함된 요청을 거부한다면 실제로 없는 이미지 능력을 선언한 것이므로, image를 제거하고 새 세션을 여세요.

Provider ID를 잘못 입력했는데 수정할 수 있나요?

불가능합니다. Provider ID는 영구적입니다(요청, 저장된 세션, 자격 증명 참조가 모두 이를 사용). 변경하려면 새 제공자를 추가하고 기존 제공자를 삭제하세요. 표시 이름, Base URL, 프로토콜, 자격 증명, 모델 목록은 언제든 편집할 수 있습니다.

8. 관련 리소스

DeepSeek Harness GitHub: deepseek-ai/deepseek-harness
공식 문서: deepseek-harness.github.io/deepseek-harness
공식 모델 설정 가이드: providers 설정
커뮤니티: GitHub Discussions / Discord
키 관리: https://maas.gravitex.ai/#/api-keys
모델 광장: https://maas.gravitex.ai/#/api-models

대화형 AI

프로그래밍 개발

AI 에이전트

기술 엔지니어링

번역

1. 제품 소개

2. 환경 요구 사항

3. 사전 준비

4. 빠른 시작

1단계: DeepSeek Harness 설치 및 실행

2단계: GravitexAI API 키 발급

3단계: 사용자 지정 제공자 추가

4단계: 모델 추가

5단계: 모델 선택 후 사용 시작

5. 주요 기능 요약

6. 고급 설정(선택 사항)

전체 참조 설정

필드 설명

7. 자주 묻는 질문

8. 관련 리소스

​1. 제품 소개

​2. 환경 요구 사항

​3. 사전 준비

​4. 빠른 시작

​1단계: DeepSeek Harness 설치 및 실행

​2단계: GravitexAI API 키 발급

​3단계: 사용자 지정 제공자 추가

​4단계: 모델 추가

​5단계: 모델 선택 후 사용 시작

​5. 주요 기능 요약

​6. 고급 설정(선택 사항)

​전체 참조 설정

​필드 설명

​7. 자주 묻는 질문

​8. 관련 리소스

1. 제품 소개

2. 환경 요구 사항

3. 사전 준비

4. 빠른 시작

1단계: DeepSeek Harness 설치 및 실행

2단계: GravitexAI API 키 발급

3단계: 사용자 지정 제공자 추가

4단계: 모델 추가

5단계: 모델 선택 후 사용 시작

5. 주요 기능 요약

6. 고급 설정(선택 사항)

전체 참조 설정

필드 설명

7. 자주 묻는 질문

8. 관련 리소스