DeepSeek Harness 설정

DeepSeek Harness (명령어 이름 dsh)는 DeepSeek이 공식적으로 공개한 오픈소스 agent harness로, “모든 것이 플러그인”이라는 아키텍처를 채택하여 모델, 도구, 스킬, 세션, 샌드박스, UI가 모두 교체 가능한 플러그인입니다. 기본적으로는 DeepSeek 공식 API를 호출하지만, 모델 플러그인을 OfoxAI로 지정하면 동일한 harness에서 100개 이상의 모델을 사용할 수 있습니다.

설정 단계

1. dsh 설치

먼저 Node.js를 설치하세요. dsh는 npm에서 @deepseek-ai/dsh로 배포되며, 설치하면 dsh 명령을 사용할 수 있습니다.

npm install -g pnpm          # 이미 설치했다면 건너뛰기
pnpm add -g @deepseek-ai/dsh
dsh --version

npm install -g pnpm          # 이미 설치했다면 건너뛰기
pnpm add -g @deepseek-ai/dsh
dsh --version

npm install -g pnpm
pnpm add -g @deepseek-ai/dsh
dsh --version

설치 중 pnpm이 Ignored build scripts: node-pty, koffi … 경고를 표시할 수 있지만 무시해도 됩니다. 두 패키지 모두 모든 플랫폼용 사전 빌드된 바이너리를 제공하므로 로컬 컴파일이 필요하지 않습니다.

전역 설치 없이 바로 실행해 보려면:

npx @deepseek-ai/dsh web

2. OfoxAI 공급자 설정

dsh는 설정을 $DSH_HOME 아래에서 관리합니다. macOS와 Linux에서는 ~/.dsh, Windows에서는 %USERPROFILE%\.dsh입니다. 아래 두 가지 방법 중 하나를 선택하세요.

dsh web

llm-pi-ai:
  providers:
    ofox:
      apiKeyEnv: OFOX_API_KEY
      api: openai-completions
      baseURL: https://api.ofox.ai/v1
      models:
        - id: deepseek/deepseek-v4-pro-0813
          name: DeepSeek V4 Pro
        - id: google/gemini-2.5-flash
          name: Gemini 2.5 Flash
    ofox-anthropic:
      apiKeyEnv: OFOX_API_KEY
      api: anthropic-messages
      baseURL: https://api.ofox.ai/anthropic
      models:
        - id: anthropic/claude-sonnet-5
          name: Claude Sonnet 5
          contextWindow: 1000000
agent-default-model:
  provider: ofox
  model: deepseek/deepseek-v4-pro-0813

3. API Key 설정

apiKeyEnv에 지정하는 것은 Key 자체가 아니라 자격 증명의 이름입니다. dsh는 dsh를 실행한 환경의 환경 변수 → $DSH_HOME/.credentials.yaml → 프로젝트의 .env → 홈 디렉터리의 .env 순서로 해석합니다. 웹 UI로 설정했다면 Key가 이미 저장되어 있으므로 이 단계는 건너뛰어도 됩니다.

export OFOX_API_KEY=<당신의 OFOXAI_API_KEY>

export OFOX_API_KEY=<당신의 OFOXAI_API_KEY>

# 현재 세션에만 적용
$env:OFOX_API_KEY = "<당신의 OFOXAI_API_KEY>"
 
# 영구 적용 (새 터미널에서 사용 가능)
setx OFOX_API_KEY "<당신의 OFOXAI_API_KEY>"

4. 확인

dsh --profile headless "OK라고만 답하세요. 어떤 도구도 호출하지 마세요."

OK가 돌아오면 모델 계층이 OfoxAI에 연결된 것입니다. 일상적인 작업에서는 dsh web으로 웹 인터페이스를 실행하거나, dsh --profile headless "run the tests"처럼 단일 작업을 실행한 뒤 종료하세요.

플랫폼별 차이

설정 파일의 내용은 세 플랫폼에서 완전히 동일하며, 경로와 환경 변수 표기법만 다릅니다.

문제 해결

TIMEOUT: Request timed out. — dsh는 Node 애플리케이션이라 http_proxy / all_proxy를 읽지 않습니다. 따라서 시스템 프록시가 정상 동작하더라도 dsh가 연결된다는 보장은 없습니다. baseURL의 도메인에 현재 네트워크에서 접근할 수 없다면 중국 본토 사용자는 미러인 https://api.ofox.io/v1로 변경하세요.

MISSING_CREDENTIAL — apiKeyEnv에 지정한 자격 증명이 아무 값으로도 해석되지 않았습니다. dsh를 실행한 터미널에서 환경 변수가 적용되어 있는지, 또는 Key가 $DSH_HOME/.credentials.yaml에 저장되어 있는지 확인하세요. 다른 원인은 모델을 잘못 고른 경우입니다. 내장된 deepseek-official 라우트는 Key를 설정하지 않아도 모델 선택기에 자기 모델을 표시하며, 그 이름이 사용자 지정 라우트의 모델과 비슷하므로 잘못 선택하지 않도록 주의하세요.

응답이 비어 있는데 오류도 나지 않는 경우 — 가장 빠지기 쉬운 함정입니다. api: openai-responses에 Anthropic 계열 모델을 조합하면 요청은 정상적으로 끝나지만(finish reason: stop) 내용이 비어 있습니다. 해당 모델을 openai-completions 라우트로 옮기거나, https://api.ofox.ai/anthropic을 가리키는 anthropic-messages 라우트로 옮기세요.

INVALID_REQUEST / HTTP 400 endpoint_not_supported — 응답 본문에 Model '…' does not support the /v1/responses endpoint on this platform. Please use /v1/chat/completions instead.라고 적혀 있습니다. Google, Qwen 등의 모델을 openai-responses로 사용하면 이렇게 됩니다. 이 경우에도 api를 openai-completions로 변경하세요.

플러그인 로딩이 라우트 중복 오류로 실패하는 경우 — 동일한 라우트 이름이 두 번 등록된 것입니다. $DSH_HOME/cordis.patch.yml과 settings.yaml 양쪽에서 ofox를 정의하고 있지 않은지 확인하세요.

고급: patch 레이어를 통한 설정

settings.yaml은 런타임 사용자 설정을 담으며 다음 요청부터 적용됩니다. 플러그인 구성 자체를 변경하려면(플러그인 교체 또는 비활성화) $DSH_HOME/cordis.patch.yml의 patch 레이어를 사용하세요:

- id: llm-pi-ai
  config:
    providers:
      ofox:
        apiKeyEnv: OFOX_API_KEY
        api: openai-completions
        baseURL: https://api.ofox.ai/v1
- id: agent-default-model
  config:
    provider: ofox
    model: deepseek/deepseek-v4-pro-0813

dsh web --dump-config를 실행하면 합성된 플러그인 트리가 출력되어 설정이 적용되었는지 확인할 수 있습니다.

추천 모델

추천 모델은 모델 마켓플레이스 를 참조하세요.