DeepSeek Harness: JoinGonka Gateway를 통한 자체 프로바이더

하네스란 에이전트 작업에서 모델을 둘러싼 모든 것입니다: 「요청 → 도구 호출 → 결과 → 다음 단계」 사이클, 파일과 터미널용 도구, 권한과 확인, 세션 로그, 컨텍스트 압축. DeepSeek Harness는 이를 플러그인으로 조립합니다: 「everything is a plugin」 아키텍처는 프레임워크 Cordis 위에 구축되어 있으며, 도구부터 모델 어댑터까지 모든 노드를 코어 수정 없이 교체할 수 있습니다. 코드는 MIT 라이선스로 공개되어 있습니다.

설치가 필요 없습니다 — Node.js(22 계열은 22.19 이상, 또는 24 이상)만 있으면 충분합니다:

npx @deepseek-ai/dsh web

이 명령은 http://127.0.0.1:3080에서 Web UI를 띄우고 브라우저로 엽니다. SSH로 실행하면 주소는 터미널에 출력될 뿐입니다. --no-open 플래그는 브라우저 없이 서버를 실행하고, --port는 포트를 변경합니다. dsh를 실행한 디렉터리가 기본 작업 디렉터리가 되지만, 인터페이스는 workspace를 명시적으로 선택한 후에만 세션을 시작합니다.

모델 계층은 두 개의 어댑터로 구성됩니다. 직접 어댑터는 벤더의 공식 API로 연결됩니다. 멀티 프로바이더 어댑터 — dsh-llm-pi-ai — 는 터미널 에이전트 Pi의 기반과 동일한 라이브러리 pi-ai 위에 구축되어 있습니다. 이를 통해 카탈로그의 내장 프로바이더와 모든 자체 endpoint를 연결할 수 있습니다. 따라서 설정의 필드 이름 — api, contextWindow, maxTokens — 은 Pi에서 익숙한 것과 일치합니다.

성숙도에 관하여. 프로젝트 README는 경고로 시작합니다: developer preview, 빠른 이터레이션, 파괴적 변경. 별도 문서 SAFETY.md는 보안 감사가 수행되지 않았으며, 에이전트가 모델이 생성한 명령을 실행한다고 명시합니다. 실용적인 결론은 간단합니다: dsh를 컨테이너, 가상 머신 또는 별도 계정에서 실행하고, 접근 가능한 모든 것의 백업을 유지하세요.

1단계: 키. gate.joingonka.ai/register에서 가입하세요. 주소 확인이 끝나면 3M개의 무료 토큰이 계정에 들어옵니다. 대시보드에서 「API 키」 섹션을 열고 jg- 접두사가 붙은 키를 만드세요. 하네스 전용 키를 따로 만들어 두면 해당 트래픽이 통계에서 별도 행으로 표시되어 편리합니다.

2단계: 첫 화면. 테스트 상태 알림(Continue 버튼) 후 dsh가 공식 API 키 입력을 요청합니다(「Add an API key to get started」). 필수는 아니므로 Configure later를 누르세요.

3단계: 프로바이더. Settings → Models를 열고 Add a custom provider를 선택하세요. 폼 필드는 다음과 같습니다:

4단계: 모델. Models 블록에서 Fetch available models를 누르면 dsh가 게이트웨이에 목록을 요청하고 「Choose models to add」 창을 엽니다. 이번 실행에서는 네트워크의 세 모델—MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash—이 모두 나타났고, Add selected 후 하네스가 게이트웨이 데이터를 기준으로 각 모델에 컨텍스트 윈도우와 응답 상한을 자동 설정했습니다. 이제 Create provider만 누르면 됩니다.

5단계: 모델 선택. 설정을 닫고 Choose workspace를 눌러 프로젝트 디렉터리를 추가하세요. 새 프로바이더의 모델이 선택기에 나타나며, 선택한 모델이 새 세션의 기본 모델이 됩니다.

dsh는 키를 설정과 별도로 보관합니다: ~/.dsh/.credentials.yaml 파일에 소유자만 접근 가능한 권한으로 저장됩니다. settings.yaml에는 그 참조 이름(이번 실행에서는 프로바이더 ID에 따른 JOINGONKA_API_KEY)만 남습니다.

어떤 프로토콜을 선택할까. 게이트웨이는 세 가지를 모두 지원하며, 차이는 기본 주소와 부가 편의 기능입니다:

dsh에서 하나의 프로바이더는 하나의 프로토콜만 사용하므로, 두 번째 프로토콜을 쓰려면 다른 Provider ID를 가진 두 번째 프로바이더가 필요합니다. 일상적인 작업에는 첫 번째 옵션으로 충분합니다. 이번 실행에서는 도구 호출을 포함한 에이전트 루프가 세 가지 모두에서 정상 작동했습니다.

Models 폼은 일반 YAML 문서 — $DSH_HOME/settings.yaml, 기본값은 ~/.dsh/settings.yaml — 에 기록합니다. 직접 편집할 수 있습니다. 설정 헤더의 Open configuration file 버튼을 누르면 파일이 열리고, 어댑터는 다음 요청 시 파일을 다시 읽으므로 재시작이 필요 없습니다. Gonka 네트워크용 전체 버전은 다음과 같습니다:

# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    joingonka:
      displayName: JoinGonka Gateway
      apiKeyEnv: JOINGONKA_API_KEY
      api: openai-completions
      baseURL: https://gate.joingonka.ai/v1
      models:
        - id: deepseek-ai/DeepSeek-V4-Flash-0731
          name: DeepSeek V4 Flash
          contextWindow: 380000
          maxTokens: 32768
        - id: zai-org/GLM-5.3-Flash
          name: GLM-5.3 Flash
          contextWindow: 390000
          maxTokens: 8192
          reasoningEfforts:
            off: low
            high: high
        - id: MiniMaxAI/MiniMax-M2.7
          name: MiniMax M2.7
          contextWindow: 200000
          maxTokens: 8192
agent-default-model:
  provider: joingonka
  model: deepseek-ai/DeepSeek-V4-Flash-0731

여기서 중요한 점:

• apiKeyEnv는 키 자체가 아니라 키에 대한 참조 이름입니다. dsh는 값을 다음 순서로 찾습니다: 실행 시점의 환경 변수, 그다음 .credentials.yaml(폼이 여기에 기록합니다), 그다음 실행 디렉터리의 .env, 마지막으로 ~/.dsh/.env. 브라우저 없이 하네스를 설정한다면 ~/.dsh/.env에 권한 600으로 JOINGONKA_API_KEY=jg-your-key 한 줄이면 충분합니다. 시작 후에 export한 변수는 이미 실행 중인 프로세스에는 보이지 않습니다.
• contextWindow와 maxTokens는 명시적으로 지정하세요. dsh가 모르는 모델에는 262,144와 32,768 토큰이 할당되지만, 이는 실제 한도와 맞지 않습니다. 지정한 maxTokens는 각 요청의 기본 응답 한도도 됩니다.
• reasoningEfforts는 Effort 메뉴의 추론 수준입니다. 수동으로 등록한 모델에는 수준이 없고, 해당 모델용 메뉴가 나타나지 않습니다. GLM-5.3 Flash의 토글은 이진식입니다: low 값은 추론을 끄고, 다른 값은 추론을 완전하게 유지합니다. 그래서 off 수준에는 low가 매핑되고, high는 그대로 전달됩니다. 저희 실행에서 off일 때는 추론 블록이 전혀 없었고, high일 때는 다시 나타났습니다.
• agent-default-model은 headless 모드를 포함한 새 에이전트용 모델입니다. 인터페이스에서 모델을 선택하는 것도 같은 역할을 합니다. 여기에 reasoningEffort를 추가할 수도 있습니다.

dsh 문서가 엄격한 게이트웨이용으로 권장하는 compat 스위치(supportsDeveloperRole: false, maxTokensField: max_tokens)는 여기서 필요하지 않습니다: JoinGonka Gateway는 developer 역할과 max_completion_tokens 필드를 모두 받아들입니다.

설치 프로그램 npx @joingonka/setup은 이 하네스를 설정하지 않습니다: 연결은 전부 이전 섹션의 폼이나 위의 YAML 조각으로 끝납니다.

연동을 가장 빠르게 확인하는 방법은 코드가 있는 디렉터리에서 한 번만 실행해 보는 것입니다. 명백한 버그가 있는 작은 파일을 옆에 두고 찾아내게 해보세요:

cd /path/to/project
npx @deepseek-ai/dsh --profile headless "Read calc.py and tell me in one sentence whether it has a bug."

최종 답변은 stdout에 출력되고, 추론 과정은 dsh: reasoning: 표시와 함께 stderr에 출력됩니다. 에이전트는 스스로 파일 읽기 도구를 호출하고 본질적으로 답해야 합니다. 저희 실행에서는 네트워크의 세 모델 모두 오류가 있는 줄을 짚어냈습니다. 즉 '요청 → 도구 호출 → 결과 → 응답'의 전체 사이클이 게이트웨이를 통해 올바르게 구성된다는 뜻입니다.

검증의 나머지 절반은 게이트웨이 쪽입니다. 관리 화면에서 '사용량'을 열어보세요. 시간별·일별 요청, 모델별·키별 내역이 표시됩니다. 하네스 키가 있는 행과 최신 마지막 요청 시각이 나타났다면 트래픽이 실제로 게이트웨이를 통과하고 있다는 증거입니다.

문제가 생겼을 때는 보통 메시지에서 바로 진단이 읽힙니다:

네트워크 내 모든 모델의 가격은 동일하므로, 선택 기준은 예산이 아닌 동작 방식입니다. 아래는 제한 사항과 파일 내용을 읽어 오류를 찾는 동일한 태스크를 수행했을 때, 우리의 dsh 실행에서 각 모델이 어떻게 동작했는지 보여줍니다.

기본 권장 모델은 DeepSeek V4 Flash입니다. 에이전트 작업은 컨텍스트 용량과 수정 길이에 금방 제한이 걸리는데, 이 모델은 두 파라미터 모두 충분한 여유가 있습니다. 복잡한 로직을 생각해야 하는 태스크의 경우 GLM-5.3 Flash로 전환하고 추론 수준을 high로 설정하세요. 빠른 수정을 위해서는 동일한 공급자가 제공하는 off 수준의 모델을 사용하면 됩니다. MiniMax M2.7은 추론 과정이 화면에 표시되지 않아도 되는 짧은 태스크에 적합한 안정적인 옵션입니다. 모델은 인터페이스 선택기 또는 agent-default-model 블록 내 model 문자열을 통해 변경할 수 있습니다.

네트워크 구성은 참가자들의 투표에 의해 결정되며 시간이 지나면서 변경됩니다. 제한 사항을 포함한 최신 목록은 언제나 GET https://gate.joingonka.ai/v1/models를 통해 확인할 수 있습니다(Fetch available models 버튼도 이를 사용합니다).

에이전트 도구는 채팅과는 다르게 토큰을 소비합니다. 하네스(harness)는 사용자의 문구마다 시스템 프롬프트와 모든 도구의 설명을 추가하고 모델과 다중 턴 대화를 진행합니다. 저희 테스트 결과, 「파일을 읽고 오류를 찾는」 작업은 2~3턴에 14,000~22,000 토큰을 소모했습니다. 거의 대부분이 입력 토큰이며, 질문하기 전에도 턴마다 약 7,000 토큰이 나갑니다. 이는 자율성에 대한 정상적인 비용이며, 토큰 단가가 중요한 이유입니다.

JoinGonka Gateway를 통하면 토큰 비용은 입력 100만 토큰당 $0.0069, 출력 100만 토큰당 $0.021입니다. 이 가격은 네트워크 내 모든 모델에 동일하게 적용되며 페이지에서 실시간 소스로 업데이트됩니다. 2026년 9월 기준 가격 규모는 다음과 같습니다:

실제 사용량만큼만 결제하며, 구독이나 요청 횟수 제한은 없습니다. 잔액과 일일 소비량은 관리 페이지에서 확인할 수 있습니다.

버전. 프로젝트가 developer preview 상태인 동안에는 업데이트 시마다 제공자가 정상인지 확인하고, 재현성을 위해 버전을 다음과 같이 명시적으로 고정하십시오: npx @deepseek-ai/[email protected] web.

권한. 새 세션은 기본적으로 'Workspace Write' 모드로 작동하여 작업 디렉토리 내 쓰기가 가능합니다. 정책을 벗어나는 작업은 인터페이스에서 확인을 요청합니다. 모드는 Settings → General에서 변경 가능합니다.

재시도. 일시적인 네트워크 오류 발생 시 dsh는 문서에 따라 최대 5번까지 자동으로 재시도하므로, 짧은 네트워크 부하 급증은 보통 눈치채지 못하게 처리됩니다.

개인정보. 게이트웨이는 프롬프트나 답변 내용을 저장하지 않습니다. 통계에는 소비량 데이터만 남습니다. 프로젝트 파일은 에이전트가 로컬에서 직접 읽습니다.

이미지 작업이 필요한 경우(인터페이스 스크린샷, 사진 속 도표 등)는 비전 능력이 있는 모델을 가진 두 번째 제공자를 추가하세요. dsh는 여러 제공자를 동시에 유지할 수 있지만, Gonka 네트워크 모델은 텍스트 전용입니다.

DeepSeek Harness가 모델 개발사가 직접 출시하는 유일한 에이전트는 아닙니다. GLM 개발사인 Z.ai에는 ZCode 환경이 있고, MiniMax에는 터미널 기반의 MiniMax Code가 있습니다. 둘 다 동일한 키를 사용하여 같은 게이트웨이에 연결할 수 있습니다.