> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepSeek Harness

> DeepSeek Harness를 AIHubMix에 연결하는 방법: npm 릴리스 설치, OpenAI 호환 프로바이더 설정, auto 또는 지정 모델 추가, Agent 요청 검증.

DeepSeek Harness(명령어 `dsh`)는 DeepSeek의 오픈 소스 코딩 Agent Harness입니다. 워크스페이스, 터미널, 파일 편집, Skills, 계획, Web UI를 제공하며 OpenAI Chat Completions 호환 인터페이스로 AIHubMix에 연결할 수 있습니다.

<Info>
  이 문서는 2026년 8월 14일 DeepSeek Harness `0.1.0-rc.6`에서 검증했습니다. Harness는 개발자 프리뷰 단계이므로 이후 릴리스에서 필드나 UI가 변경될 수 있습니다.
</Info>

<h2 id="summary">
  요약
</h2>

다음 네 가지 값을 설정합니다.

| 설정                           | 값                         |
| ---------------------------- | ------------------------- |
| Provider ID                  | `aihubmix`                |
| Base URL                     | `https://aihubmix.com/v1` |
| API protocol                 | `openai-completions`      |
| API key environment variable | `AIHUBMIX_API_KEY`        |

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/01-models-aihubmix-configured.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=9a11531222d056d05d6ee6030eddb595" alt="DeepSeek Harness Models 페이지에 설정된 AIHubMix" width="1280" height="720" data-path="public/en/deepseek-harness/01-models-aihubmix-configured.png" />
</Frame>

<h2 id="requirements">
  무엇이 필요한가요?
</h2>

* 유효한 [AIHubMix API Key](https://console.aihubmix.com/token)
* Node.js `22.19.0` 이상, Node.js 24+도 지원
* npm Registry와 `https://aihubmix.com`에 접근 가능한 네트워크

```bash theme={null}
node --version
npm --version
```

<h2 id="install">
  DeepSeek Harness를 설치하는 방법
</h2>

소스 저장소를 복제하지 않고 npm 릴리스를 설치합니다.

```bash theme={null}
npm install -g @deepseek-ai/dsh
dsh --version
```

`dsh: command not found`가 표시되면 `npm config get prefix`를 실행하고 해당 디렉터리의 `bin`이 `PATH`에 포함되어 있는지 확인하세요.

<h2 id="start-web-ui">
  Web UI를 시작하는 방법
</h2>

워크스페이스로 사용할 프로젝트 디렉터리에서 실행합니다.

```bash theme={null}
dsh web --port 3080
```

`http://127.0.0.1:3080`을 열고 처음 사용할 때 워크스페이스를 선택하거나 추가합니다.

<h2 id="configure-provider">
  AIHubMix 프로바이더를 설정하는 방법
</h2>

**Settings > Models > Add a custom provider**를 엽니다.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/03-add-custom-provider.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=e5f609447d3c979a65235ecc1b0382d0" alt="DeepSeek Harness 사용자 지정 프로바이더 설정 양식" width="1280" height="720" data-path="public/en/deepseek-harness/03-add-custom-provider.png" />
</Frame>

| 필드           | 권장 값                      | 설명                                       |
| ------------ | ------------------------- | ---------------------------------------- |
| Provider ID  | `aihubmix`                | 소문자 식별자. 이미 사용 중이면 `aihubmix-gateway` 사용 |
| Display name | `AIHubMix`                | 모델 선택기에 표시할 이름                           |
| Base URL     | `https://aihubmix.com/v1` | `/v1` 포함 필수                              |
| API protocol | `openai-completions`      | OpenAI Chat Completions 호환 프로토콜          |
| API key      | AIHubMix API Key          | Harness가 자격 증명으로 저장하며 평문 값을 다시 표시하지 않음   |

최종 요청 엔드포인트는 `https://aihubmix.com/v1/chat/completions`입니다.

<Warning>
  Base URL 필드에 전체 `/chat/completions` 경로를 입력하지 마세요.
</Warning>

<h2 id="add-models">
  auto 또는 다른 모델 추가
</h2>

Base URL과 API Key를 입력한 후 **Fetch available models**를 선택합니다. Harness가 `GET https://aihubmix.com/v1/models`를 요청하고 현재 사용 가능한 모델 ID를 표시합니다.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/07-discover-models.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=7fdeeb8c4ba8400910bcabe1e7b50a78" alt="DeepSeek Harness가 가져온 AIHubMix 모델 목록" width="1280" height="720" data-path="public/en/deepseek-harness/07-discover-models.png" />
</Frame>

첫 연결 테스트에서는 `auto`만 추가하고 표시 이름을 `Auto`로 설정할 수 있습니다. 특정 모델을 사용하려면 가져온 목록에서 선택하거나 **Add model**에서 정확한 모델 ID를 입력하세요. 그래픽 모델 선택기는 현재 Provider 카탈로그에 등록된 모델만 표시합니다.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/04-add-auto-model.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=0c1e93d53cf9840d5c5885dc192b0d80" alt="AIHubMix auto 모델 수동 추가" width="1280" height="720" data-path="public/en/deepseek-harness/04-add-auto-model.png" />
</Frame>

**Create provider**를 선택해 저장합니다.

<h2 id="auto-vs-specific-models">
  auto와 지정 모델 비교
</h2>

| 선택       | 사용 시점                              |
| -------- | ---------------------------------- |
| `auto`   | 첫 연결 테스트 또는 AIHubMix의 자동 모델 선택     |
| 지정 모델 ID | 고정된 모델 기능, 버전 또는 재현 가능한 결과가 필요한 경우 |

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

<h2 id="environment-variables">
  환경 변수에 API Key 저장
</h2>

`$HOME/.dsh/settings.yaml`을 편집합니다.

```yaml theme={null}
llm-pi-ai:
  providers:
    aihubmix:
      displayName: AIHubMix
      apiKeyEnv: AIHUBMIX_API_KEY
      api: openai-completions
      baseURL: https://aihubmix.com/v1
      models:
        - id: auto
          name: Auto
          contextWindow: 1000000
          maxTokens: 32768

agent-default-model:
  provider: aihubmix
  model: auto
```

```bash theme={null}
export AIHUBMIX_API_KEY='sk-***'
dsh web --port 3080
```

키를 실행 환경에서 가져오면 설정 페이지에 읽기 전용 메시지가 표시되고 실제 값은 노출되지 않습니다.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/02-aihubmix-provider-details.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=a18af7f6409268331dcb4ddfa7d78568" alt="DeepSeek Harness의 AIHubMix 프로바이더 상세 설정" width="1280" height="720" data-path="public/en/deepseek-harness/02-aihubmix-provider-details.png" />
</Frame>

환경 변수를 변경한 후 Harness를 다시 시작하세요.

<h2 id="verify-chat">
  모델 선택 및 대화 검증
</h2>

Settings를 닫고 입력 상자 오른쪽 아래의 모델 선택기에서 **Auto** 또는 추가한 특정 모델을 선택합니다.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/05-select-auto-model.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=82577ac5295eebc0ef6e4945f75f5ffe" alt="DeepSeek Harness 모델 선택기의 Auto" width="1280" height="720" data-path="public/en/deepseek-harness/05-select-auto-model.png" />
</Frame>

```text theme={null}
Reply with exactly: AIHubMix connection successful
```

예상 응답을 받으면 Harness, OpenAI Chat Completions 호환 엔드포인트, AIHubMix 간 연결이 정상입니다.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/06-live-chat-success.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=f5fe3902c1c2f57b84b34b739b258394" alt="DeepSeek Harness에서 성공한 AIHubMix 응답" width="1280" height="720" data-path="public/en/deepseek-harness/06-live-chat-success.png" />
</Frame>

<h2 id="headless-test">
  headless 테스트 실행
</h2>

```bash theme={null}
export AIHUBMIX_API_KEY='sk-***'
dsh --profile headless \
  'Reply with exactly DSH_AIHUBMIX_OK and do not use tools.'
```

성공하면 `DSH_AIHUBMIX_OK`가 출력됩니다.

<h2 id="troubleshooting">
  자주 묻는 질문
</h2>

<h3 id="missing-credential">
  MISSING\_CREDENTIAL이 표시되는 이유는 무엇인가요?
</h3>

Harness가 실행 환경에서 `AIHUBMIX_API_KEY`를 받지 못했습니다. 변수를 설정한 뒤 같은 터미널에서 Harness를 시작하세요.

<h3 id="models-401">
  모델 검색에서 401이 반환되는 이유는 무엇인가요?
</h3>

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

<h3 id="only-auto">
  모델 선택기에 Auto만 표시되는 이유는 무엇인가요?
</h3>

선택기는 현재 Provider 카탈로그에 등록된 모델만 표시합니다. **Settings > Models > AIHubMix > Edit**에서 **Fetch available models**를 사용하거나 정확한 모델 ID를 직접 추가하세요.

<h3 id="unknown-model">
  UNKNOWN\_MODEL이 표시되는 이유는 무엇인가요?
</h3>

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

<h3 id="connection-timeout">
  연결 시간이 초과되는 이유는 무엇인가요?
</h3>

DNS, 조직 네트워크, 로컬 프록시를 확인하세요. 브라우저만 시스템 프록시를 사용한다면 `dsh`를 시작하는 터미널에서 `HTTP_PROXY`, `HTTPS_PROXY`, `NODE_USE_ENV_PROXY=1`을 설정합니다.

<h2 id="security">
  보안 지침
</h2>

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

***

마지막 업데이트: 2026-08-14