DeepSeek Harness

DeepSeek Harness는 웹 버전의 사용자 지정 모델 API로 HiAPI에 연결할 수 있습니다. 아래 단계는 deepseek-v4.1-flash를 예로 사용하며, HiAPI는 OpenAI Chat Completions 프로토콜을 사용합니다. GPT가 필요하면 6단계를 참고하세요. 이 튜토리얼은 Mac에서 DeepSeek Harness 0.2.1-rc.2(웹 버전)로 설치, 설정 저장, 모델 선택까지 검증했으며, 일부 스크린샷은 Windows의 Edge 브라우저에서 찍었습니다. 공식 DeepSeek 계정 로그인 상자에 HiAPI API 키를 입력하지 마세요.

1. Node.js 설치

Node.js 설치에 설명된 대로 LTS 22.19 이상을 설치하고, 이미 있다면 건너뛰세요. 그런 다음 터미널에서 아래 두 명령을 실행하세요. 버전 번호가 보이면 충분합니다:

node --version
npm --version

2. Harness 설치 및 시작

1. Mac에서는 터미널을 열고 각 줄을 실행하세요:

npx --yes @deepseek-ai/dsh@0.2.1-rc.2 --version
npx --yes @deepseek-ai/dsh@0.2.1-rc.2 web

첫 번째 명령은 처음 실행할 때 공식 패키지를 내려받고 버전을 표시하며, 두 번째 명령은 웹 서비스를 시작합니다. Windows PowerShell에서는 두 명령의 npx를 npx.cmd로 바꾸세요.

2. dsh web:과 로컬 주소가 보이면 보통 브라우저가 저절로 열립니다. 열리지 않으면 터미널에 출력된 인증 파라미터가 포함된 전체 URL을 복사해 같은 컴퓨터의 브라우저 주소창에 붙여 넣으세요. 포트 주소만 입력하지 마세요.

① 0.2.1-rc.2가 표시되는지 확인합니다. ② 터미널에서 dsh web 뒤에 출력된 인증 파라미터가 포함된 전체 URL을 사용합니다. 스크린샷의 인증 토큰은 가려져 있습니다.

3. 서비스 터미널은 열어 두세요. 브라우저는 프런트엔드일 뿐이며 터미널을 닫으면 서비스가 중지됩니다. 나중에 다시 사용하려면 시작 명령을 다시 실행하고 새로 출력된 주소를 여세요. 작업을 마치면 이 터미널로 돌아와 Ctrl+C를 누르세요.

3. 메인 인터페이스와 모델 설정 열기

1. 처음 “미리보기 버전 안내”가 나타나면 페이지 안내대로 계속하세요. 먼저 “Get started” (开始使用) 아래의 공식 API 키 / 계정 항목을 닫고 메인 인터페이스로 들어갑니다.
2. 입력 상자 위의 Default workspace (默认工作区)와 표준 모드는 그대로 유지하세요.

① 기본 작업 공간을 유지합니다. ② 표준 모드를 유지합니다.

3. 왼쪽 아래의 More → Settings (更多 → 设置)를 클릭한 다음 왼쪽에서 Models (模型)를 클릭합니다.

① 왼쪽 아래에서 More를 클릭합니다. ② Settings를 클릭합니다. 2026-10-26, Windows Edge, Harness 0.2.1-rc.2.

4. 모델 설정 페이지에서 Add model provider (添加模型提供商)를 클릭한 뒤 Custom model API (自定义模型 API)로 전환합니다.

① 왼쪽에서 Models를 클릭합니다. ② Add model provider를 클릭합니다. 2026-10-26, Windows Edge, Harness 0.2.1-rc.2.

4. HiAPI API 키 받기

API 키 발급받기에 설명된 대로 키를 준비하고, 키 옆의 복사 아이콘을 클릭해 전체 HiAPI API 키를 복사하세요. 다음 단계의 API key (API 密钥) 항목에 붙여 넣습니다.

5. DeepSeek 입력 및 공급자 저장

1. Custom model API (自定义模型 API)에서 각 항목을 입력하세요:

2. Model catalog (模型目录) 아래에서 Add model (添加模型)을 클릭합니다. 새 행에 모델 ID로 deepseek-v4.1-flash, 표시 이름으로 DeepSeek V4.1 Flash를 입력하세요. 모델이 하나도 없는 공급자는 사용할 수 없습니다.

① Custom model API를 클릭합니다. ② Provider ID와 표시 이름을 입력합니다. ③ API 주소를 https://api.hiapi.ai/v1로 설정합니다. ④ 프로토콜로 OpenAI Chat Completions를 선택합니다. ⑤ 전체 HiAPI API 키를 붙여 넣습니다. ⑥ 먼저 Add model을 클릭한 뒤 DeepSeek 모델 ID와 표시 이름을 입력합니다. 생성 버튼은 아래쪽에 있으니 스크롤해서 저장하세요.

3. 양식 맨 아래로 스크롤해 Create provider (创建提供商)를 클릭합니다. 모델 목록으로 돌아오면 HiAPI · DeepSeek이 보여야 합니다. 같은 이름의 공급자가 이미 있으면 같은 ID로 새로 만들지 말고 그 항목을 편집해 저장하세요.
4. DeepSeek만 사용한다면 7단계로 바로 가서 모델을 선택하세요.

6. GPT가 필요할 때 Responses 구성 추가

1. gpt-6-astra가 필요하면 Add model provider → Custom model API (添加模型提供商 → 自定义模型 API)를 다시 클릭하고 아래 표를 입력하세요:

① Provider ID와 표시 이름을 입력합니다. ② API 주소를 https://api.hiapi.ai/v1로 설정합니다. ③ 프로토콜로 OpenAI Responses를 선택합니다. ④ 전체 HiAPI API 키를 붙여 넣습니다. ⑤ 먼저 Add model을 클릭한 뒤 gpt-6-astra와 표시 이름을 입력합니다. ⑥ Create provider를 클릭해 저장합니다.

2. 아래로 스크롤해 Create provider (创建提供商)를 클릭합니다. GPT에는 OpenAI Responses, DeepSeek에는 OpenAI Chat Completions를 프로토콜로 선택하고, API 주소는 /v1까지만 입력하며 /responses나 /chat/completions를 덧붙이지 마세요.

7. 모델 선택 후 시작

1. 설정 오른쪽 위의 **×**를 클릭해 채팅으로 돌아갑니다. 입력 상자 위의 Default workspace (默认工作区)는 그대로 두고, 에이전트 프리셋은 Standard mode (标准模式)를 사용하면 됩니다.
2. 입력 상자 오른쪽 아래의 Choose a model (请选择模型)을 클릭하고 HiAPI · DeepSeek 그룹 아래에서 DeepSeek V4.1 Flash를 클릭합니다. GPT를 구성했다면 HiAPI · GPT 그룹 아래에서 GPT-6 Astra도 선택할 수 있습니다.

① Choose a model을 클릭해 메뉴를 엽니다. ② DeepSeek V4.1 Flash를 선택합니다. ③ 또는 GPT-6 Astra를 선택합니다(둘 중 하나).

3. 입력 상자 옆의 모델 이름이 바뀌면 기본 권한을 유지한 채 “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하면 연결이 된 것입니다. 공급자와 모델은 이미 저장되었으므로 다음에는 시작한 뒤 모델 메뉴에서 고르기만 하면 됩니다.

문제 해결

여기에는 DeepSeek Harness에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.