DeepSeek Harness 설정

이 가이드는 DeepSeek Harness (dsh)를 Aiberm를 사용자 지정 OpenAI 호환 공급자로 사용해 실행하는 방법을 보여 줍니다. 설정이 끝나면 하나의 Aiberm API 키로 Claude, GPT, Gemini, DeepSeek, Kimi, MiniMax, GLM, Grok 및 Aiberm의 나머지 모델에 접근할 수 있습니다.

Info

DeepSeek Harness는 개발자 프리뷰이며 빠르게 바뀝니다. 이 페이지는 공식 README와 Configure models 가이드를 따른 뒤, 그 단계를 Aiberm에 맞춰 설명합니다.

DeepSeek Harness란 무엇인가요?

DeepSeek Harness는 DeepSeek AI의 오픈소스 에이전트 하네스입니다. 모든 것이 플러그인이며 Cordis로 조합됩니다. 일반적인 진입점은 브라우저 UI(dsh web)이며, 동일한 홈 디렉터리가 일회성 헤드리스 작업에도 사용됩니다.

공식 프로젝트:

홈페이지: deepseek.com/harness
소스: github.com/deepseek-ai/deepseek-harness
토론: GitHub Discussions

사전 준비

Aiberm 계정 (가입하기)
Aiberm API 키 (키 발급하기)
Node.js 설치 (npx에 필요)
macOS, Linux 또는 Windows의 터미널

설치 및 시작

공식 설치 경로는 일회성 npx 실행입니다. 에이전트가 작업할 프로젝트 디렉터리에서 다음을 실행하세요.

npx @deepseek-ai/dsh web

Web UI는 기본적으로 http://127.0.0.1:3080에서 수신합니다. 현재 작업 디렉터리가 워크스페이스 루트가 됩니다.

유용한 변형:

# Another port
npx @deepseek-ai/dsh web --port 8080

# One-shot headless job (same models and credentials as the Web UI)
npx @deepseek-ai/dsh --profile headless "summarize the README"

이미 CLI를 설치했다면:

dsh web
dsh --help
dsh web --help

Tip

web과 headless 프로필은 처음 사용할 때 $DSH_HOME(기본값 ~/.dsh) 아래에 만들어집니다. Aiberm를 사용하기 위해 저장소를 클론할 필요는 없습니다.

Aiberm 구성하기 (Web UI, 권장)

Aiberm는 내장 DeepSeek 카드가 아니며, 카탈로그의 OpenAI / Anthropic 공급자도 아닙니다. 해당 항목은 공식 엔드포인트를 유지합니다. Aiberm는 OpenAI 호환 게이트웨이이므로 사용자 지정 공급자로 추가합니다.

공식 참고: Configure models.

1단계: Settings → Models 열기

Web UI에서 Settings → Models를 엽니다.

2단계: 사용자 지정 공급자 추가

Add a custom provider를 선택하고 다음을 입력합니다.

필드	값
Provider ID	`aiberm` (소문자, 영구 — 세션, 기본값, 자격 증명 이름에 사용됨)
Display name	`Aiberm`
Base URL	`https://aiberm.com/v1`
API protocol	`openai-completions`
API key	콘솔 → API Tokens의 Aiberm 키

Add a custom provider form

Warning

Provider ID는 나중에 이름을 바꿀 수 없습니다. 요청, 저장된 세션, 기본 모델, 저장된 자격 증명이 모두 이 ID를 사용합니다. 바꾸려면 새 공급자를 추가하고 이전 공급자를 삭제하세요.

3단계: 모델 불러오기 또는 입력

Model catalog에서 Fetch available models를 선택합니다. Harness는 방금 입력한 키로 Aiberm의 OpenAI 호환 GET /v1/models를 호출합니다. 원하는 모델을 선택한 뒤 저장하세요.

Fetch available models from Aiberm

검색에 실패하면 모델 ID를 직접 입력하세요. ID는 모델 목록 또는 Aiberm Pricing에서 확인하세요. 예시:

claude-sonnet-4-6
claude-opus-4-6
gpt-5.4
google/gemini-3-flash
deepseek/deepseek-v4-pro
grok-4.6

Info

이 페이지는 API 키를 settings.yaml에 쓰지 않습니다. 키는 $DSH_HOME/.credentials.yaml에 쓰기 전용으로 저장됩니다. 설정에는 AIBERM_API_KEY 같은 참조만 유지됩니다.

4단계: 모델 선택

저장하면 작성기 하단의 모델 선택기에 Aiberm가 나타납니다. 모델을 선택하면 그 선택이 새 세션의 기본값도 됩니다. 이미 요청을 보낸 세션은 자체 로그에 기록된 모델을 유지합니다.

선택기는 내장 DeepSeek 모델과 Aiberm 사용자 지정 공급자를 따로 묶습니다. Claude, GPT, Gemini 및 나머지 카탈로그에는 Aiberm 그룹을 사용하세요.

Aiberm 구성하기 (settings.yaml)

$DSH_HOME/settings.yaml(보통 ~/.dsh/settings.yaml)을 편집해 동일한 공급자를 선언할 수 있습니다. 이 파일에 API 키를 넣지 마세요.

llm-pi-ai:
  providers:
    aiberm:
      displayName: Aiberm
      apiKeyEnv: AIBERM_API_KEY
      api: openai-completions
      baseURL: https://aiberm.com/v1
      models:
        - id: claude-sonnet-4-6
        - id: claude-opus-4-6
        - id: claude-opus-4-6-thinking
        - id: gpt-5.4
        - id: google/gemini-3-flash
        - id: deepseek/deepseek-v4-pro
        - id: grok-4.6
        - id: kimi-k2.6
        - id: minimax-m2.7

agent-default-model:
  provider: aiberm
  model: claude-sonnet-4-6

그런 다음 키를 다음 위치 중 하나에 저장하세요(요청 시 첫 번째 일치가 사용됩니다).

실행 환경: AIBERM_API_KEY=sk-... npx @deepseek-ai/dsh web
$DSH_HOME/.credentials.yaml (Models 페이지가 쓰는 위치):

AIBERM_API_KEY: sk-your-aiberm-api-key

실행 디렉터리의 프로젝트 .env, 또는 $DSH_HOME/.env

공식 자격 증명 순서: 프로세스 환경 → $DSH_HOME/.credentials.yaml → 프로젝트 .env → $DSH_HOME/.env. Models 페이지에 쓴 값은 이전 .env 키보다 우선합니다.

POSIX에서는 .credentials.yaml을 모드 600으로 유지하세요.

Harness 제공 카탈로그에 없는 사용자 지정 경로는 api, baseURL, 비어 있지 않은 models 목록을 반드시 설정해야 합니다. models는 해당 경로의 카탈로그를 대체합니다. 선택기에 넣고 싶은 모든 모델이 여기에 있어야 합니다. id만 있는 항목으로도 충분합니다.

비전 모델

직접 입력한 모델은 따로 지정하기 전까지 텍스트 전용으로 취급됩니다. 그런 모델에 이미지를 첨부하면 Harness는 요청을 보내기 전에 거부합니다.

Aiberm 비전 모델에는 settings.yaml에 input을 추가하세요.

llm-pi-ai:
  providers:
    aiberm:
      apiKeyEnv: AIBERM_API_KEY
      api: openai-completions
      baseURL: https://aiberm.com/v1
      models:
        - id: claude-sonnet-4-6
        - id: gemini-3-pro-image-preview
          input: [text, image]
        - id: gpt-image-2
          input: [text, image]

나열된 모든 모델이 이미지를 받는다면 경로 폴백을 한 번만 설정하세요.

defaultInput: [text, image]

defaultInput은 재정의가 아니라 폴백입니다. 기본값은 [text]입니다.

설정 확인

http://127.0.0.1:3080을 엽니다.
모델 선택기에 Aiberm와 모델이 표시되는지 확인합니다.

Model picker showing the Aiberm group

Hi와 같은 짧은 프롬프트를 보냅니다.
선택 사항: Aiberm를 통해 모델을 직접 나열합니다.

curl -H "Authorization: Bearer sk-your-aiberm-api-key" \
     https://aiberm.com/v1/models

선택기에 없는 추가 ID는 공급자의 models 목록에 추가하거나 Fetch available models를 다시 실행하세요.

헤드리스 및 CLI 참고

Web UI와 dsh --profile headless는 $DSH_HOME을 공유합니다. Aiberm를 한 번 구성한 뒤 다음을 실행하세요.

npx @deepseek-ai/dsh --profile headless "list the files in this directory"

런처 플래그가 먼저 오고, 그 이후는 프로필에 속합니다.

dsh --profile web --port 8080
dsh --profile web --help
dsh --help

문제 해결

`MISSING_CREDENTIAL`

경로가 AIBERM_API_KEY(또는 다른 apiKeyEnv)를 지정했지만 값이 저장되어 있지 않습니다. Settings → Models에서 키를 저장하거나, dsh를 시작하는 셸에서 같은 변수를 보내세요.

`UNKNOWN_MODEL`

선택한 모델이 이 공급자의 models 목록에 없습니다. 모델을 다시 가져오거나 ID를 직접 추가하세요. Aiberm ID는 시간이 지나며 바뀝니다. 모델 목록에서 확인하세요.

모델 가져오기 또는 채팅 시 401

Aiberm Console에서 키를 확인하세요.
Base URL은 https://aiberm.com/v1이어야 합니다 (/v1 포함).
키를 settings.yaml에 붙여 넣지 마세요. 자격 증명 또는 환경에 넣으세요.

요청이 여전히 DeepSeek 또는 OpenAI로 감

내장 DeepSeek 카드나 카탈로그의 openai / anthropic 공급자를 구성한 것입니다. 해당 항목은 공식 엔드포인트를 유지합니다. 잘못 구성된 행을 삭제하고 ID aiberm와 base URL https://aiberm.com/v1로 사용자 지정 공급자를 추가하세요.

보내기 전에 이미지가 거부됨

모델에 이미지 모달리티가 없습니다. 해당 모델에 input: [text, image]를 추가한 뒤(비전 모델 참고) 새 세션을 시작하세요. 첨부된 이미지는 이전 세션 로그에 남습니다.

구성 편집이 적용되지 않음

공급자와 키 변경은 다음 요청에 적용되며 서버를 다시 시작할 필요는 없습니다. 기존 세션은 이미 로그에 기록된 모델을 유지합니다. 기본값을 바꾼 뒤에는 새 채팅을 시작하세요.

파일 위치

경로	용도
`$DSH_HOME/settings.yaml`	공급자, 모델 목록, 기본 모델 (`~/.dsh/settings.yaml`)
`$DSH_HOME/.credentials.yaml`	API 키만
`$DSH_HOME/profiles/web/`	자동 생성된 웹 프로필

참고 사항

키는 Models 페이지를 사용하는 것이 좋습니다. settings.yaml에는 apiKeyEnv 참조만 두세요.
에이전트가 읽지 않기를 원하는 비밀이 이미 있는 디렉터리에서는 에이전트를 실행하지 마세요.
이 가이드 밖의 필드(타임아웃, 재시도, reasoning 호환)는 공식 dsh-llm-pi-ai README를 참고하세요.