DeepSeek Harness

Settings → Models → “Add model provider” → “Custom model API”에서 다섯 필드 — Provider ID, 표시 이름, 기본 URL, API 프로토콜, API 키 — 를 입력하면 Claude와 GPT가 내장 DeepSeek 카드와 같은 선택기에 표시됩니다

# Settings → Models → Add model provider → Custom model API
#
#   Provider ID     kunavo          (lowercase, and permanent)
#   display name    Kunavo
#   base URL        https://api.kunavo.com/v1
#   API protocol    OpenAI Chat Completions   (openai-completions)
#   API key         sk-kn-...
#
# Then Model catalog → Fetch available models → Add selected,
# or type the ids by hand. The page writes the active profile's
# $DSH_HOME/profiles/<profile>/cordis.patch.yml — profile "web" under
# `dsh web`. The same provider there, plus an optional second one
# that sends Claude ids over Anthropic Messages, whose base URL has
# NO /v1. This entry replaces the whole llm-pi-ai config: keep any
# provider already in it.

- id: llm-pi-ai
  config:
    providers:
      kunavo:
        apiKeyEnv: KUNAVO_API_KEY
        api: openai-completions
        baseURL: https://api.kunavo.com/v1   # → /v1/chat/completions
        models:
          - id: claude-sonnet-5
          - id: claude-opus-5
          - id: claude-haiku-4-5
          - id: gpt-5-6-sol
      kunavo-claude:
        apiKeyEnv: KUNAVO_API_KEY
        api: anthropic-messages
        baseURL: https://api.kunavo.com      # → /v1/messages
        models:
          - id: claude-sonnet-5
          - id: claude-haiku-4-5

단계별 안내

1. /app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
2. 웹 UI(dsh web)를 시작하고 Settings → Models로 이동합니다. Add model provider를 선택합니다. 처음에는 Third-party model provider 카드가 열리며, 여기에 dsh에서 제공하는 공급자만 표시됩니다. Custom model API로 전환하세요.
3. Provider ID(소문자로 입력하며 변경할 수 없음 — 문서에 따르면 요청, 저장된 세션, 모델 기본값, 자격 증명 참조가 모두 이 ID를 사용합니다. 이름을 바꾸려면 새 공급자를 추가하고 기존 공급자를 삭제해야 합니다), 표시 이름, 기본 URL https://api.kunavo.com/v1, API 프로토콜 OpenAI Chat Completions, API 키를 입력합니다. 키는 쓰기 전용입니다. dsh는 키를 $DSH_HOME/.credentials.yaml에 보관하고 프로필에는 키 참조만 저장합니다.
4. Model catalog에서 Fetch available models를 선택합니다. Kunavo가 GET /v1/models를 반환하므로 모델 선택기가 자동으로 채워집니다. 사용할 모델을 선택한 다음 Add selected를 선택합니다. ID를 직접 입력해도 되며, 검색 결과가 비어 있을 때는 직접 입력하도록 문서에서 안내합니다.
5. 선택 사항: Claude ID에 Anthropic 자체 프로토콜을 사용하려면 별도의 Provider ID와 기본 URL https://api.kunavo.com(/v1 제외), API 프로토콜 Anthropic Messages, 동일한 키를 사용하는 두 번째 사용자 지정 모델 API를 추가합니다. 여기서도 Fetch로 전체 카탈로그가 표시되므로 claude- ID만 추가하세요(그 이유).
6. 작성기에서 모델을 선택하고 인사말 대신 파일에 영향을 주는 요청을 보내세요. Harness는 대부분의 작업에서 도구 호출을 사용하므로, 첫 실행에서 파일을 읽고 수정해 보면 더 많은 것을 확인할 수 있습니다. 모델 변경은 다음 요청부터 적용되며, 문서에 따르면 재시작할 필요가 없습니다.

DeepSeek Harness의 “Configure models” 페이지(dsh-v0.2.0-rc.2 태그의 docs/user/guide/providers.md와 동일한 내용)에서 확인했습니다(2026년 10월 1일 기준). 서드파티 설정은 변경될 수 있으므로, 여기의 필드 이름이 실제 화면과 다르면 이 문서가 아니라 해당 페이지를 기준으로 삼으세요.

클라이언트를 디버깅하기 전에 확인할 사항

한 번의 요청으로 문제가 엔드포인트, 키 또는 구성 파일 중 어디에 있는지 판단할 수 있습니다. 이 요청에서 JSON이 반환되면 동일한 base URL과 키가 DeepSeek Harness에서 작동합니다.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

필드에 입력할 model id

모든 텍스트 모델은 model id로 접근할 수 있습니다. 현재 목록은 GET /v1/models이며, 가격이 포함된 카탈로그는 모델 페이지에서 확인할 수 있습니다. 요금은 토큰 100만 개당 USD 기준이며 입력 / 출력 순서입니다.

Anthropic Messages를 통한 Claude

Kunavo는 Anthropic Messages API에도 응답하며 anthropic-messages는 양식에서 제공하는 세 프로토콜 중 하나입니다. Harness 문서는 “공급자 하나는 프로토콜 하나를 사용하므로, 두 프로토콜을 제공하는 게이트웨이는 공급자 두 개가 필요합니다”라고 명시합니다. 따라서 이는 첫 번째 공급자의 설정이 아니라 그 옆에 추가하는 두 번째 공급자입니다.

• 기본 URL https://api.kunavo.com, 기본 경로를 사용합니다. 테스트 실행에서 이 기본 경로는 /v1/messages?beta=true로 요청을 보냈습니다. Claude Code가 사용하는 경로이며 Kunavo도 응답합니다. 끝에 /v1를 붙이면 /v1/v1/messages로 요청을 보냈습니다. DeepSeek Harness와 Claude Code 비교에서 두 클라이언트의 요청을 나란히 확인할 수 있습니다.
• Claude ID만 사용합니다. Kunavo의 /v1/messages는 claude- ID만 처리합니다. 다른 ID를 입력하면 gpt-가 /v1/chat/completions를 명시하는 404를 반환합니다. GPT에는 openai-completions 공급자를 사용하세요.
• Fetch에는 모든 모델이 표시되므로 Claude 모델만 추가하세요. dsh의 llm-pi-ai README에 따르면 이 프로토콜의 검색 요청은 Anthropic의 x-api-key 헤더와 함께 GET /v1/models로 전송됩니다. Kunavo의 모델 목록은 Authorization: Bearer에서와 마찬가지로 해당 헤더의 키를 사용합니다. 이는 dsh 소스 코드와 Kunavo 자체 테스트를 근거로 한 내용이며 이번 실행에서 확인한 것은 아닙니다. Fetch available models에는 GPT와 이미지 모델까지 전체 카탈로그가 표시되므로 claude- ID만 선택하세요. 직접 입력해도 동일하게 작동합니다. 전체 목록이 표시된다고 해서 확인할 수 있는 내용은 제한적입니다. 같은 README에 따르면 모델 목록 URL에는 끝에 /v1를 붙여도 되고 붙이지 않아도 되지만, 모델 요청에서는 기본 URL을 그대로 사용합니다. 따라서 Fetch는 https://api.kunavo.com/v1에서도 목록을 가져오며, 해당 기본 URL로 보내는 첫 턴은 /v1/v1/messages로 전송됩니다.
• 이 방식으로 얻는 이점. 요청은 Anthropic 형식으로 도착합니다. 테스트 실행에서는 시스템 프롬프트가 최상위 system 필드로 전달되어 developer 역할은 사용되지 않았습니다. Kunavo는 OpenAI 형식에서 변환하지 않고 요청을 그대로 전달합니다. openai-completions 공급자도 변환을 거쳐 같은 Claude ID에 연결되므로 사용 안내에서는 해당 공급자를 선택했습니다.

양식이 저장하는 파일

Models 페이지는 $DSH_HOME/profiles/<profile>/cordis.patch.yml를 작성합니다. dsh web로 시작하면 $DSH_HOME/profiles/web/cordis.patch.yml에 저장됩니다. 예전 dsh 문서는 $DSH_HOME/settings.yaml를 가리켰지만 0.2.0-rc.2 문서에는 그렇게 되어 있지 않습니다. 브라우저와 서버가 같은 컴퓨터에 있으면 Settings 헤더의 Open configuration file을 눌러 파일을 열 수 있으며, 어댑터는 다음 요청 시 이 파일을 다시 읽습니다. 이 엔드포인트에는 다음 다섯 가지 설정이 중요합니다.

1. 컨텍스트 창 및 최대 출력 토큰 — 양식에서 Customized settings → Model options에 있습니다. 직접 입력한 ID에는 두 값이 모두 없으므로 경로의 기본값이 적용됩니다. llm-pi-ai README에 따르면 컨텍스트는 262,144 토큰, 출력은 32,768 토큰이며 테스트 실행에서 두 사용자 지정 공급자 모두 정확히 max_tokens: 32768를 요청했습니다. 위 표의 모든 ID는 이보다 많은 값을 지원합니다. 어느 경우든 해당 행을 확인하고 더 큰 값을 원하면 모델의 카탈로그 항목에서 값을 높이세요. Kunavo는 한도가 아니라 모델이 생성한 토큰에 대해 요금을 청구합니다.
2. compat.supportsDeveloperRole — 필요하지 않습니다. Harness에서는 developer 역할을 거부하는 게이트웨이에 이 설정을 권장하지만, Kunavo는 Claude를 포함한 모든 모델 계열에서 해당 역할을 시스템 턴으로 처리합니다. (2026-09-30까지는 Claude 경로에서 이 역할을 누락해 이 항목에서 전환을 설정하도록 안내했습니다. 설정을 그대로 두어도 문제없습니다.)
3. compat.maxTokensField — 기본값 그대로 두세요. Harness에서는 보통 위 전환과 함께 첫 번째 해결 방법으로 사용하지만, Kunavo 자체 핸들러는 max_completion_tokens를 읽고 max_tokens를 대체값으로 사용하므로 기본값으로 이미 작동합니다.
4. reasoningEfforts — 양식에 입력란이 없습니다. 직접 입력한 모델에는 추론 수준이 선언되어 있지 않으므로 Effort 메뉴가 표시되지 않고, 모델의 추론 여부는 엔드포인트 자체의 기본 설정에 따라 결정됩니다. 메뉴를 사용하려면 수준을 직접 선언하세요. openai-completions에서는 각 키가 수준이고 각 값은 reasoning_effort로 전송되는 표기입니다. 이렇게 하면 gpt- ID에 적용됩니다. claude- ID에는 적용되지 않습니다. Kunavo의 채팅 인터페이스는 reasoning_effort를 Anthropic에 전달하지 않기 때문입니다(/docs/chat#reasoning).
5. 입력 유형(파일에서는 input: [text, image]) — 문서에 따르면 이는 “엔드포인트를 확인하는 것이 아니라 엔드포인트에 관한 주장을 지정하는 것”입니다. 이미지 입력을 지원하지 않는 ID에서 Image를 선택해도 Harness는 이를 감지하지 못하며, 이후 단계에서 요청이 거부됩니다. 체크하기 전에 /models에서 해당 ID를 확인하세요.

세션에서 전송하는 나머지 항목, 즉 턴마다 전송되는 도구 정의 24개, 새 세션마다 보내는 짧은 제목 요청, DeepSeek 자체 경로의 추가 필드에 대한 요금은 DeepSeek Harness 요금 안내에서 확인할 수 있습니다.