> ## Documentation Index > Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt > Use this file to discover all available pages before exploring further. # DeepSeek Harness > 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](https://nodejs.org/) 설치 필요(LTS 버전 권장) * macOS / Linux / Windows 지원, Web UI는 브라우저로 접속 DeepSeek Harness는 현재 개발자 프리뷰(Developer Preview) 단계로 빠르게 변경되고 있으며, 호환성이 깨지는 변경이 있을 수 있습니다. 업그레이드 전 공식 릴리스 노트를 확인하세요. ## 3. 사전 준비 * 로컬 머신에 Node.js가 설치되어 있어야 합니다 * [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 API 키(`sk-xxxxxxxxxx` 형식)를 생성해 두어야 합니다 ## 4. 빠른 시작 ### 1단계: DeepSeek Harness 설치 및 실행 전역 설치 없이 `npx`로 Web UI를 바로 실행할 수 있습니다: ```bash theme={null} 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 키 발급 1. [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에 접속 2. 「새 토큰」을 클릭하고 이름을 지정해 저장 3. `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절 「고급 설정」 참고). 입력을 완료한 폼은 다음과 같습니다: DeepSeek Harness 사용자 지정 제공자 추가 ### 4단계: 모델 추가 제공자 폼의 「모델 카탈로그」에서 **사용 가능한 모델 가져오기**를 클릭하면, DeepSeek Harness가 게이트웨이의 `GET /models` 인터페이스를 호출해 사용 가능한 모델을 나열합니다. 원하는 모델을 검색·선택한 후 「선택 항목 추가」를 클릭하면 됩니다: DeepSeek Harness 사용 가능한 모델 가져오기 탐지에 실패하거나 목록이 비어 있어도 모델 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 모델 광장](https://maas.gravitex.ai/#/api-models)에서 확인하세요. ### 5단계: 모델 선택 후 사용 시작 제공자를 저장하면 세션의 모델 선택기에서 GravitexAI의 모델을 확인할 수 있습니다. 모델을 선택하면 바로 작업을 시작할 수 있으며, 선택한 모델은 새 세션의 기본값으로도 저장됩니다. **모델 변경은 다음 요청부터 적용되며, 서비스를 재시작할 필요가 없습니다**: DeepSeek Harness 모델 선택 ## 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`는 키를 환경 변수에서 읽어온다는 뜻입니다. 설정을 직접 작성하기 전에 터미널에서 먼저 설정하세요: ```bash macOS / Linux theme={null} export GRAVITEX_API_KEY="sk-xxxxxxxxxx" ``` ```powershell Windows PowerShell theme={null} $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` 예시입니다. 필요에 따라 줄여서 사용하세요: ```yaml theme={null} 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` 필드는 **제공자 레벨**에 작성해 해당 제공자 아래 모든 모델에 일괄 적용할 수도 있습니다: ```yaml theme={null} 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. 자주 묻는 질문 현재 제공자가 자격 증명을 찾지 못한 것입니다. 설정 방식에 따라 확인하세요: Web UI로 설정했다면 모델 페이지에서 API 키를 다시 저장하고, `apiKeyEnv`로 수동 설정했다면 해당 환경 변수가 설정되어 있는지(예: `export GRAVITEX_API_KEY="sk-..."`), 그리고 `dsh`를 실행하는 터미널에서 읽을 수 있는지 확인하세요. 채팅에 키를 붙여 넣어 우회하지 마세요. 모델 ID가 현재 제공자에 인식되지 않는 것입니다. 해당 모델이 제공자의 모델 목록에 추가되어 있는지 확인하고, 모델 ID의 대소문자와 철자가 [GravitexAI 모델 광장](https://maas.gravitex.ai/#/api-models)과 정확히 일치하는지 확인하세요. 해당 모델이 속한 제공자의 프로토콜이 `openai-responses`인지 확인하세요. GPT 계열 모델은 `openai-completions` 프로토콜의 제공자 아래에 둘 수 없으며, `openai-responses` 프로토콜의 제공자(예: `gravitex-openai`)를 따로 만든 후 모델을 추가해야 합니다. 401은 키 또는 주소가 일치하지 않는다는 뜻입니다. Base URL이 `https://api.gravitex.ai/v1`인지, 키가 `sk-`로 시작하고 불필요한 공백이 없는지 확인하세요. 목록이 비어 있거나 탐지에 실패하면 모델 ID를 직접 입력해도 완전히 동일하게 동작합니다. 게이트웨이와 OpenAI의 요청 형식이 다른 것입니다. `settings.yaml`의 제공자 레벨에 `compat.supportsDeveloperRole: false`와 `compat.maxTokensField: max_tokens`를 설정한 후(작성 방법은 6절 참고) 다시 시도하세요. 비워 둔 `off`는 추론 필드를 전송하지 않으므로, 기본적으로 사고하는 모델은 계속 사고합니다. 해당 모델에 `compat.thinkingFormat: deepseek`를 설정하세요(6절 예시 참고). 수동 등록 모델은 기본적으로 텍스트 전용입니다. `settings.yaml`에서 해당 모델에 `input: [text, image]`를 추가하세요. 반대로 제공자가 이미지가 포함된 요청을 거부한다면 실제로 없는 이미지 능력을 선언한 것이므로, `image`를 제거하고 새 세션을 여세요. 불가능합니다. Provider ID는 영구적입니다(요청, 저장된 세션, 자격 증명 참조가 모두 이를 사용). 변경하려면 새 제공자를 추가하고 기존 제공자를 삭제하세요. 표시 이름, Base URL, 프로토콜, 자격 증명, 모델 목록은 언제든 편집할 수 있습니다. ## 8. 관련 리소스 * DeepSeek Harness GitHub: [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) * 공식 문서: [deepseek-harness.github.io/deepseek-harness](https://deepseek-harness.github.io/deepseek-harness/) * 공식 모델 설정 가이드: [providers 설정](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.zh.md) * 커뮤니티: [GitHub Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions) / [Discord](https://discord.gg/Ycq5dCaS4) * 키 관리: [https://maas.gravitex.ai/#/api-keys](https://maas.gravitex.ai/#/api-keys) * 모델 광장: [https://maas.gravitex.ai/#/api-models](https://maas.gravitex.ai/#/api-models)