DeepSeek Harness 설치와 API 연결 가이드

DeepSeek Harness는 DeepSeek AI가 공개한 오픈소스 코딩 에이전트이자 agent runtime입니다. 모델 주변에서 loop, tools, workspace access, sessions, permissions, interface를 제공하며 실제 지능은 API Provider의 모델이 담당합니다. 이 글은 DeepSeek code harness의 역할을 먼저 설명한 다음 공식 custom-provider 흐름으로 OmniaKey에 연결합니다.

DeepSeek Harness란?

DeepSeek Harness, 줄여서 dsh는 새 언어 모델이 아닙니다. 모델이 workspace를 이해하고, tool을 호출하고, 파일을 편집하고, command를 실행하고, session을 보존하고, 승인을 요청하게 만드는 소프트웨어 계층입니다.

일부 소개 글은 open-source AI agent framework라고 부르지만 공식 자료는 더 구체적으로 open-source agent harness, local-first 확장형 코딩 에이전트, agent 개발 및 runtime 환경이라고 설명합니다.

핵심 설계는 everything is a plugin입니다. Cordis plugin system을 기반으로 models, tools, skills, sessions, sandboxes, storage, loops, scheduling, UI까지 설정으로 교체하거나 재구성할 수 있습니다.

추적 가능한 event stream은 단순한 chat transcript가 아닙니다. 공식 문서는 resume, fork, search, replay를 같은 session log에 대한 작업으로 설명합니다. 답변 전에 여러 tool call을 수행한 agent를 디버깅할 때 유용합니다.

DeepSeek Harness가 아닌 것

• DeepSeek V4 Pro 같은 모델 자체가 아닙니다. Harness와 model은 별도 계층입니다.
• 안정된 production release가 아닙니다. 공식 자료는 developer preview라고 표시하며 호환성을 깨는 변경이 생긴다고 경고합니다.
• npm quick start로 실행할 때 hosted coding service가 아닙니다. Web UI는 기본적으로 local loopback에 bind합니다.
• Open source라고 model inference가 무료인 것은 아닙니다. Repository는 MIT license지만 API 사용료는 설정한 Provider에 따라 발생합니다.

DeepSeek Harness OmniaKey 설정값

세부 절차 전에 전체 값을 정리하면 다음과 같습니다.

Base URL에는 /v1이 포함되어야 합니다. bare origin만 넣거나 /v1/v1로 중복하거나 전체 /chat/completions request path를 붙이지 마세요. DeepSeek Harness가 operation path를 추가합니다.

1. DeepSeek Harness 설치와 실행

Node.js를 설치하고 agent가 볼 project directory에서 terminal을 연 뒤 공식 npm quick start를 실행합니다.

npx @deepseek-ai/dsh web

현재 명령은 Web UI를 다음 주소에서 시작합니다.

http://127.0.0.1:3080

3080이 사용 중이면 다른 port를 지정할 수 있습니다.

npx @deepseek-ai/dsh web --port 3081

dsh를 실행한 directory가 기본 filesystem location이 되지만 UI에서 workspace를 추가하고 선택하기 전에는 composer를 쓸 수 없습니다. 대상 repository를 명시적으로 선택하세요. 활성 permission policy가 허용하는 범위에서 agent가 file과 shell tools를 사용할 수 있습니다.

2. OmniaKey API key를 별도로 만들기

OmniaKey API Keys dashboard에서 DeepSeek Harness 전용 key를 만드세요. 여러 도구가 한 credential을 공유하는 것보다 quota 설정, rotation, revoke, audit가 쉽습니다.

평문 key를 repository, shell history, screenshot, issue, chat log에 남기지 마세요. Web UI에 저장된 key는 write-only입니다. DeepSeek 문서에 따르면 secret은 $DSH_HOME/.credentials.yaml에 저장되고 settings에는 credential reference만 남으며 페이지에는 redacted descriptor가 전달됩니다.

3. OmniaKey를 custom provider로 추가

새 설치에서는 Internal Testing Notice에서 Continue를 선택합니다. 다음 onboarding은 공식 DeepSeek API key를 요구하지만 OmniaKey는 built-in official route가 아니라 custom provider에 넣어야 하므로 Configure later를 선택합니다.

DeepSeek Harness에서 Settings → Models를 열고 Add a custom provider를 선택한 다음 입력합니다.

1. Provider ID는 omniakey. 소문자로 시작해야 합니다.
2. Display name은 OmniaKey.
3. Base URL은 https://api.omniakey.com/v1.
4. API protocol은 openai-completions.
5. API key에 방금 만든 OmniaKey key를 붙여 넣습니다.

Provider ID는 생성 후 이름을 바꿀 수 없습니다. 저장된 sessions, defaults, requests, credential references가 이 값을 사용하기 때문입니다. Display name, Base URL, protocol, credential, model list는 편집할 수 있습니다.

4. 모델 자동 조회와 선택

Model catalog 아래에서 Fetch available models를 선택합니다. Custom OpenAI-compatible Provider에서는 현재 Base URL에 Bearer authentication을 붙여 GET /models를 요청합니다. 위 설정이면 OmniaKey의 GET /v1/models가 됩니다.

실제로 사용할 model만 선택하세요. 다음 두 ID로 시작할 수 있습니다.

같은 Provider에서 OmniaKey가 현재 지원하는 Claude, GPT, Gemini, Grok, GLM도 사용할 수 있습니다. 정확한 ID는 live model catalog에서 복사하세요. Model name은 모호한 alias가 아니라 정확한 identifier입니다.

Discovery를 사용할 수 없으면 정확한 Model ID를 수동으로 추가해도 됩니다. Custom Provider를 만들려면 최소 한 개의 model이 필요합니다.

5. Workspace 선택과 안전한 검증

Provider를 저장하고 Choose workspace로 project를 선택한 뒤 새 session을 만드세요. Model picker에서 OmniaKey / deepseek-v4-pro 또는 OmniaKey / deepseek-v4-flash를 선택합니다.

처음에는 범위가 좁은 read-only task를 실행합니다.

package.json을 확인하고 사용 가능한 scripts를 요약하세요. 파일을 수정하거나 command를 실행하지 마세요.

이 테스트는 편집이나 shell command를 허용하기 전에 workspace, Provider, key, 정확한 model ID, 기본 response path를 확인합니다. Text response 성공이 모든 tool-call pattern의 성공을 뜻하지 않으므로 큰 refactor를 맡기기 전에 reversible tool task도 시험하세요.

Model settings는 server를 재시작하지 않아도 다음 request부터 적용됩니다. 다만 이미 첫 요청을 보낸 session은 log에 기록된 model을 유지합니다. Provider나 model을 바꾼 뒤에는 새 session으로 명확하게 테스트하세요.

선택 사항: settings.yaml로 OmniaKey 설정

첫 설정에는 Web UI가 더 이해하기 쉽습니다. 통제된 로컬 환경에서는 $DSH_HOME/settings.yaml에 Provider profile을 작성하고 key를 직접 넣는 대신 environment variable을 참조할 수 있습니다.

export OMNIAKEY_API_KEY="your-omniakey-api-key"

llm-pi-ai:
  providers:
    omniakey:
      displayName: OmniaKey
      apiKeyEnv: OMNIAKEY_API_KEY
      api: openai-completions
      baseURL: https://api.omniakey.com/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash

Key는 Harness process environment에 있어야 합니다. settings.yaml에 literal secret을 쓰지 말고 apiKeyEnv를 사용하세요. 공식 dsh-llm-pi-ai reference도 settings document에 secret을 넣지 않도록 credential reference를 권장합니다.

DeepSeek Harness에서 OmniaKey를 쓰는 이유

DeepSeek Harness는 custom gateway를 지원하며 OmniaKey는 이 extension point를 재사용 가능한 Provider 하나로 만듭니다.

• 여러 model family에 설정 하나. Vendor마다 gateway profile을 새로 만들지 않고 picker에서 정확한 model ID를 바꿉니다.
• Model discovery. ID를 외워 입력하는 대신 OmniaKey의 OpenAI-compatible model list를 읽을 수 있습니다.
• 분리된 운영 제어. Harness 전용 API key, quota, rotation lifecycle, usage trail을 설정합니다.
• 명확한 model identity. OmniaKey는 silent model substitution을 하지 않습니다. 요청한 Provider와 model이 실행되며 upstream이 없으면 visible failure를 반환합니다.
• 추가 agent subscription이 아닌 API usage 결제. OmniaKey는 prepaid per-token billing을 쓰며 현재 availability와 rate는 catalog에 유지됩니다.

OmniaKey가 direct DeepSeek key보다 항상 낫다는 뜻은 아닙니다. DeepSeek native account와 endpoint만 필요하면 direct provider가 합리적입니다. 같은 Harness에서 선택한 DeepSeek와 다른 model family를 한 key와 Base URL로 쓸 때 OmniaKey의 가치가 큽니다.

문제 해결

Fetch available models가 401을 반환

Key가 OmniaKey에서 발급되었고 공백이 없으며 활성 상태인지, 정확한 https://api.omniakey.com/v1과 함께 쓰는지 확인하세요. Model discovery는 Bearer authentication을 사용합니다.

Provider가 404를 반환

Model을 바꾸기 전에 Base URL을 확인하세요. 흔한 오류는 /v1 누락, /v1/v1 중복, https://api.omniakey.com/v1/chat/completions를 Base URL로 넣는 것입니다.

UNKNOWN_MODEL

선택한 model이 custom provider의 저장된 list에 없습니다. Models를 다시 조회하거나 OmniaKey catalog의 정확한 ID를 추가한 뒤 새 session에서 선택하세요.

MISSING_CREDENTIAL

Settings → Models에서 key를 저장하거나 DeepSeek Harness를 시작한 shell에 OMNIAKEY_API_KEY가 있는지 확인하세요. 다른 terminal에서 variable을 설정해도 이미 실행 중인 process는 바뀌지 않습니다.

바꾼 model이 적용되지 않는 것처럼 보임

새 session을 시작하세요. 기존 session은 첫 요청 이후 append-only log에 기록된 Provider와 model을 유지합니다.

텍스트는 되지만 agent tool이 실패

Basic text generation과 structured tool use는 서로 다른 검사입니다. Read-only tool task로 시작하고 Harness의 Trajectory view에서 정확한 failure를 확인한 뒤 limits나 permissions를 늘리세요. 잘못된 tool call은 유효한 API key를 rotate해도 해결되지 않습니다.

자주 묻는 질문

DeepSeek Harness는 무료인가요?

Source code는 MIT license입니다. Model inference는 별도이며 DeepSeek, OmniaKey 또는 다른 Provider를 사용하면 API 비용이 발생할 수 있습니다.

OmniaKey로 DeepSeek V4 Pro를 쓸 수 있나요?

네. OmniaKey를 openai-completions custom provider로 추가하고 정확한 ID deepseek-v4-pro를 선택하세요. 더 낮은 가격의 route로 deepseek-v4-flash도 제공됩니다.

0813 release, 공식 peak/off-peak rate, token cost 계산은 DeepSeek V4 Pro API 가격 가이드 (English)를 보세요. 더 새로운 Flash route, native vision, benchmark evidence, V4 Pro 현재 상태는 DeepSeek V4.1 Flash 리뷰에서 확인할 수 있습니다.

OmniaKey key를 built-in DeepSeek 카드에 넣어야 하나요?

대신 Add a custom provider를 사용하세요. Built-in card는 공식 DeepSeek route를 설정하며 custom-provider form은 gateway용 공식 경로로 Base URL, protocol, model list를 입력할 수 있습니다.

같은 Provider에서 Claude, GPT, Gemini도 쓸 수 있나요?

OmniaKey의 OpenAI-compatible surface가 현재 지원하면 가능합니다. Live list를 가져와 필요한 정확한 ID를 추가하세요. Protocol-specific behavior가 다를 수 있으므로 모든 model이 동일하다고 가정하지 말고 tool behavior를 확인하세요.

API key는 어디에 저장되나요?

Models page에서 저장한 key는 write-only이며 $DSH_HOME/.credentials.yaml에 저장됩니다. Settings에는 credential reference가 남습니다. YAML을 직접 설정할 때는 apiKeyEnv로 process environment에서 key를 제공하세요.

안정적인 production workflow에 쓸 수 있나요?

현재는 evaluation target으로 보세요. DeepSeek는 이 버전을 developer preview라고 명시하고 compatibility-breaking changes를 경고합니다. Version을 pin하고 secret 없는 설정을 backup하며 upgrade 후 공식 가이드를 다시 확인하세요.

확인한 출처

• DeepSeek Harness product page
• DeepSeek Harness GitHub README
• Official Web UI quick start
• Official model and custom-provider guide
• Official dsh-llm-pi-ai provider reference
• OmniaKey OpenAI-compatible API reference (English)
• OmniaKey live model catalog